后台操作预览窗 ZhaoGC4/dsh-cua-preview

dsh-cua-preview

Codex 风格的 DeepSeek Harness 后台电脑操作小窗预览（macOS） A Codex-like floating glass preview window for DeepSeek Harness background computer-use.

当 DeepSeek Harness 的智能体在后台操作某个 macOS 窗口时，屏幕角落会出现一个 Codex 风格的毛玻璃小窗，只显示被操作的那个窗口的实时缩略画面与当前动作。它不抢前台、不移动鼠标、不显示整个桌面，也不会把其他 app 的画面带进预览。

目录

- 它解决什么问题
- 特性
- 效果
- 工作原理
- 环境要求
- 安装
- 使用
- 配置
- 隐私与安全
- 已知限制
- 卸载
- 故障排查
- 开发
- English summary
- 许可证与致谢

它解决什么问题

智能体使用后台 Computer Use 操作软件时，你通常只能看到前台应用，不知道智能体此刻在操作哪个窗口、点了哪里。Codex 的 Computer Use 会显示一个小预览窗；本项目把同样的体验带进 DeepSeek Harness：

- 只显示被操作的窗口，而不是整个屏幕；
- 小窗永远不会抢走前台窗口和键盘焦点；
- 你可以用鼠标拖动，或用 macOS 三指拖移把小窗放到任何位置，位置会被记住；
- 智能体空闲后自动隐藏，下次操作自动出现。

本项目只做「预览/观察」，不发送任何鼠标或键盘事件——真正的输入仍由 Computer Use 服务商（Anionex 的 @anionex/dsh-computer-use）以不抢焦点的方式完成。

特性

- 🖼 窗口级绑定：预览的唯一数据来源是 screencapture -l<windowId>，窗口 id 来自 Computer Use 的 observation JSON；没有有效窗口就不显示，绝不退化成全屏预览。
- 🪟 Codex 式玻璃拟态：macOS 原生 vibrancy: 'hud' 材质 + 58% 深色 tint、圆角、细高光描边和柔和投影。
- ⚡ 尽量流畅：覆盖层以约 140ms 间隔自采集目标窗口（通常 3–7 fps），双缓冲交叉淡入消除闪烁。
- 🖱 可拖动 + 位置记忆：整张卡片是拖动区，支持鼠标拖动与 macOS「三指拖移」；位置保存在 ~/.dsh/cua-preview/window-state.json。
- 👻 不抢焦点：focusable: false + showInactive() + type: panel；不接收键盘输入。
- 🔒 本地且最小权限：抓屏在 DSH Host 派生的进程链内执行，复用 Host 已有的「屏幕录制」授权，不新增 TCC 授权；帧只在 /tmp 短暂落盘后立即删除；循环回环 socket 带随机 token；不访问网络、无遥测。
- ⏱ 自动出现/隐藏：智能体有 Computer Use 活动时显示，闲置 activeMs（默认 12s）后自动隐藏。

效果

图中预览只包含 TextEdit 的目标窗口（桌面上还有其它应用的窗口，但不会出现在小窗里）。

工作原理

DeepSeek Harness Host（已有 Screen Recording 权限） └─ dsh-cua-preview 插件（plugin/index.js） ├─ 监听 session/event 里的 computer_* tool/call 与 tool/result ├─ 从 tool result 的 observation JSON 取出精确的 app + window.id ├─ 启动一个独立 Electron 覆盖层（app/），通过 127.0.0.1 + 随机 token 通信 └─ 发送 target { windowId, app, title, status } / activity / hide │ ▼ Electron 覆盖层（app/main.js，非激活置顶面板） ├─ 只对 target.windowId 执行 screencapture -x -t jpg -l<windowId> ├─ 3–7 fps 抓帧，双缓冲交叉淡入显示 ├─ 标题「正在操作你的电脑」+ 应用名 + 瞬时动作 caption └─ 12s 无活动自动隐藏；用户可拖动，位置持久化

设计取舍与协议细节见 docs/ARCHITECTURE.md。

环境要求

| 项 | 要求 |
| 操作系统 | macOS 14 或更新（开发/实测：macOS 27） |
| DeepSeek Harness | Desktop 版 0.2.1-rc.2（dsh.compatibility.dsh = >=0.2.1-rc.2 <0.3.0-0） |
| Computer Use 提供器 | 已安装并启用 @anionex/dsh-computer-use v0.3.x；本项目只预览它的 computer_ 工具 |
| Electron | 任意官方 Electron 二进制。推荐直接复用 dsh-orb 已缓存的 ~/.dsh/dsh-orb/electron-runtime/Electron.app，或把 electronPath 指向 /Applications/Electron.app |
| 屏幕录制权限 | DSH 已获得（Computer Use 本身就需要）；本项目不额外申请 |
| Node.js | 不需要单独安装：安装脚本使用 DSH 自带的 pnpm 与 Electron 的 Node 模式 |

安装

⚠️ DSH 桌面版的 desktop 配置档由 Electron 应用独占管理，官方 dsh plugin --profile desktop 会拒绝操作。下面的脚本按与 Plugins 页相同的两步执行（pnpm add file: + 写入 cordis.patch.yml），并在改动前自动备份。

方式 A：一键脚本（推荐）

git clone https://github.com/ZhaoGC4/dsh-cua-preview.git
cd dsh-cua-preview
bash scripts/install.sh

脚本会：

1. 备份 ~/.dsh/profiles/desktop/{package.json,cordis.patch.yml,pnpm-lock.yaml} 到 ~/.dsh/cua-preview/install-backup-<时间戳>/；
2. 用 DSH 自带运行时 pnpm 把本仓库以 file: 依赖安装进 desktop 配置档；
3. 在 cordis.patch.yml 追加带标记的插件行（含 electronPath）。

然后重启 DeepSeek Harness（保存好正在进行的工作；插件重载/宿主重启会中断当前会话）。

如果装过 dsh-orb，脚本会自动复用它的 Electron 缓存；否则请先安装 Electron 或设置 DSH_CUA_PREVIEW_ELECTRON=/path/to/Electron。

方式 B：手动安装

1) 记下仓库绝对路径
REPO="$(pwd)"
DSH_APP="/Applications/DeepSeek Harness.app"
RT="$DSH_APP/Contents/Resources/runtime"

2) 在 desktop profile 安装依赖
cd ~/.dsh/profiles/desktop
ELECTRON_RUN_AS_NODE=1 \
DSH_DESKTOP_NODE_EXECUTABLE="$DSH_APP/Contents/MacOS/DeepSeek Harness" \
PATH="$RT/bin:$PATH" \
"$DSH_APP/Contents/MacOS/DeepSeek Harness" --expose-internals \
"$RT/primary-runtime/dependencies/pnpm/bin/pnpm.mjs" add "file:$REPO"

3) 在 ~/.dsh/profiles/desktop/cordis.patch.yml 末尾追加：（electronPath 按实际路径填写，或删除该行让插件自动探测）
cat >> ~/.dsh/profiles/desktop/cordis.patch.yml <<EOF

- insert:
- id: cua-preview
name: 'dsh-cua-preview'
config:
electronPath: '$HOME/.dsh/dsh-orb/electron-runtime/Electron.app/Contents/MacOS/Electron'
captureGapMs: 140
activeMs: 12000
EOF

验证安装

重启后，让智能体使用后台 Computer Use 观察任意应用（例如让它先加载 /dsh-computer-use 技能，再观察 TextEdit）。应当看到小窗出现。也可以检查：

cat ~/.dsh/cua-preview/plugin.log # 插件日志：server / overlay spawned / connected
cat ~/.dsh/cua-preview/app.log # 覆盖层日志：target / fps

使用

| 操作 | 说明 |
| 显示 | 智能体发出 computer_ 工具调用并返回窗口 observation 后自动出现 |
| 隐藏 | 最后一次活动 12 秒后自动隐藏；也可在配置里调小 activeMs |
| 拖动 | 鼠标按住小窗任意位置拖动；macOS「三指拖移」（系统设置 › 辅助功能 › 指针控制 › 触控板选项）同样有效 |
| 位置记忆 | 拖动结束后写入 ~/.dsh/cua-preview/window-state.json，下次出现回到原位（拖出屏幕会自动夹回可见区） |
| 只显示目标窗口 | 小窗只显示 observation 指向的窗口，不会显示桌面或其他应用 |

无需手动开关；它跟随 Computer Use 活动自动出现/隐藏。

配置

在 ~/.dsh/profiles/desktop/cordis.patch.yml 的 cua-preview 行里配置：

| 字段 | 默认值 | 说明 |
| electronPath | 自动探测 | 官方 Electron 二进制绝对路径；留空则依次尝试 ~/.dsh/dsh-orb/electron-runtime/... 与 /Applications/Electron.app/... |
| appDir | 包内 app/ | 覆盖层目录；从 git 仓库 file: 安装时无需修改 |
| captureGapMs | 140 | 两次抓帧的间隔，越大越省 CPU、越小越流畅（建议 80–250） |
| activeMs | 12000 | 最后一次 Computer Use 活动后保持可见的时间 |
| hideDelayMs | 250 | 收到 hide 后的淡出余量 |

覆盖层还支持以下环境变量（插件会自动注入；仅调试时需要手动设置）：DSH_PREVIEW_PORT、DSH_PREVIEW_TOKEN、DSH_PREVIEW_PARENT、DSH_PREVIEW_CAPTURE_GAP_MS、DSH_PREVIEW_ACTIVE_MS。

运行期文件：

| 路径 | 用途 |
| ~/.dsh/cua-preview/plugin.log | 插件日志（自动轮转至 256KB） |
| ~/.dsh/cua-preview/app.log | 覆盖层日志（含实测 fps/target） |
| ~/.dsh/cua-preview/window-state.json | 小窗位置 |
| /tmp/dsh-preview-frames/ | 抓帧临时目录（每帧读取后立即删除） |

更多见 docs/CONFIGURATION.md。

隐私与安全

- 只截目标窗口：使用 screencapture -l<windowId>，不是全屏截图；窗口 id 来自当前 Computer Use observation。
- 不发送输入：本插件只显示画面，不注入任何鼠标/键盘事件。
- 帧即用即删：JPEG 写入 /tmp 后立即读入内存并删除；不会长期保存。
- 本机回环：插件与覆盖层通过 127.0.0.1 随机端口通信，带 32 字节随机 token 握手；不联网、无遥测。
- 权限复用：抓屏发生在 DSH Host 派生的进程链中，复用 DSH 已有的「屏幕录制」授权，不新增 TCC 权限。
- 注意：预览显示的是应用真实内容；在屏幕共享/录屏/演示时请留意目标窗口是否含敏感信息。

已知限制

- 仅支持 macOS + DSH 桌面版 + Anionex 的 computer_ 工具；旧的 dsh-orb 前台 click/open_app/... 工具不会触发预览（它们使用全局屏幕，正是本项目要避免的“全局预览”）。
- 若某次工具结果里没有 window.id（例如只有 app 列表），小窗不会显示。
- 帧率约 3–7 fps（每次 screencapture 是一个子进程，约 100–150ms 开销），不是视频级流畅度。
- 没有 “Esc 取消”：DSH 没有给外部进程的会话中断接口，本项目不做假取消；小窗只负责显示并自动隐藏。
- 需要 DSH Host 重启/重载后插件才会出现；升级 DSH 后如失效，重新执行安装脚本。
- 同时有多个会话操作不同 app 时，以最近一次 observation 的窗口为准（v2 协议由插件按会话事件转发）。

卸载

bash scripts/uninstall.sh # 保留日志与备份 bash scripts/uninstall.sh --purge # 同时删除 ~/.dsh/cua-preview

然后重启 DeepSeek Harness。脚本会移除 cordis.patch.yml 中带标记的插件块和 profile 依赖；安装时的备份仍在 ~/.dsh/cua-preview/install-backup-。

故障排查

| 症状 | 处理 |
| 小窗完全不出现 | 看 ~/.dsh/cua-preview/plugin.log：若出现 no Electron binary found，在 patch 里配置 electronPath 或安装 Electron；若只有 server listening 没有 overlay connected，检查 Electron 是否能启动 |
| 有日志但没有画面 | 看 app.log：出现 capture miss 通常表示目标窗口已关闭/最小化；出现 target 但没有 fps 表示 screencapture 被系统拒绝（确认 DSH 有屏幕录制权限） |
| 显示的不是我要操作的 app | 预览严格跟随 Computer Use 的 observation；确认 Agent 当前观察的确实是你要求的应用（可读取会话日志里的 computer_observe 结果） |
| 覆盖层重复出现/旧窗口残留 | 重启 DSH，或手动结束残留的 Electron --no-sandbox .../dsh-cua-preview/app 进程；插件卸载时会自动结束子进程 |
| 拖动位置不对 | 删除 ~/.dsh/cua-preview/window-state.json 后重启覆盖层 |
| macOS 提示「『Electron』正在后台运行」 | 这是系统对 accessory 后台进程的提示（不是本项目窗口），可在 系统设置 → 通知 中关闭 |
| 安装后 DSH 提示任务中止 | 插件/依赖变更可能触发 Host 重启；会话日志会自动恢复，重新继续即可 |

更多见 docs/TROUBLESHOOTING.md。

开发

仓库结构：

dsh-cua-preview/
├── plugin/index.js # DSH Host 插件：观察 session 事件并转发 target ├── app/ # Electron 覆盖层：玻璃窗口 + 窗口级截图 + 拖动/记忆 │ ├── main.js # 窗口、抓帧循环、socket 协议 │ ├── preload.cjs # 受控 IPC 桥 │ ├── index.html # 极简玻璃 UI │ └── renderer.js # 双缓冲交叉淡入 ├── scripts/ │ ├── install.sh / uninstall.sh │ └── profile-patch.mjs # 带标记的 cordis.patch.yml 编辑器 ├── docs/ARCHITECTURE.md ├── docs/CONFIGURATION.md └── docs/TROUBLESHOOTING.md

本地检查：

npm run check # node --check 插件与覆盖层

调试覆盖层时可以手动启动（需要一个向它发送 target 消息的 socket 服务端，或安装后直接观察日志）。协议说明见 docs/ARCHITECTURE.md。

English summary

dsh-cua-preview 为 macOS 上 DeepSeek Harness 的后台 computer-use 加上类似 Codex 的悬浮玻璃预览。Host 插件监听 computer_* 工具的结果，取出准确的 window.id，再转发给一个小巧、不抢焦点的 Electron 覆盖层。覆盖层只捕获那个窗口（绝不截整屏），以 3–7 fps 交叉淡入淡出帧，始终置顶且不抢焦点，可以拖动（鼠标或 macOS 三指拖移），会记住位置，并在智能体空闲后自动隐藏。不需要额外的 TCC 权限，不联网，不上报遥测，不注入输入。

要求：macOS 14+、DeepSeek Harness Desktop 0.2.1-rc.2、Anionex Computer Use 服务商，以及一个 Electron 二进制（会自动复用 dsh-orb 已缓存的运行时）。用 bash scripts/install.sh 安装，重启 DSH，后台 Computer Use 期间预览就会自动出现。

许可证与致谢

- 本项目以 MIT 许可证发布，见 LICENSE。
- 感谢 Anionex/dsh-computer-use 提供不抢焦点的后台 Computer Use 能力（本项目的 observation 数据来源）。
- 感谢 dsh-orb 生态提供的悬浮球/Electron 运行时思路（本项目复用其已缓存的官方 Electron 运行时，但不依赖它运行）。
- DeepSeek Harness 是 DeepSeek AI 的项目，本项目与官方无隶属关系。