电脑操控 lavg43-oss/dsh-tool-computer

dsh-tool-computer

为 DeepSeek Harness（DSH）提供计算机操作能力，分两条路线：

- browser —— 通过 DevTools Protocol 驱动 Chrome 或 Edge。零依赖。 网页里发生的一切，走这条又快又确定的路径。
- computer —— 驱动 Windows 桌面：截图能真正送到模型手里，还有鼠标、键盘、滚动和窗口控制。浏览器之外的一切都归它。

它只解决一个具体问题：让智能体既能看又能动手，图像真正到达模型，而且不必为每次点击都付一次视觉推理的代价。

状态：可用，已在真实 Chrome 和真实桌面上测试过。仅支持 Windows。
安装前先看 SECURITY.md —— 这等于把机器的控制权交给智能体。

为什么要分两条路

经典的像素到动作循环很贵：截全屏、把图发给模型、让它猜坐标、移动鼠标、等待、重复。每一步都要好几秒，而且每次点击都是近似值。

任务落在浏览器里时，你根本不用猜：页面自己就说了它有哪些元素、叫什么、在哪儿。在真实机器上实测，同一个浏览器：

| 操作 | browser（CDP） | 像素循环 |
| 读取整个页面 | 28 ms | 0.5–1 s + 视觉推理 |
| 点击元素 | 139 ms | 2–6 s（猜坐标） |
| 读取精确值 | 9 ms | 视觉推理 |
| 向输入框输入 | 152 ms | 2–6 s |
| 截取标签页 | 165 ms | 0.5–1 s |
| 导航 | 2.9–3.3 s | 2.9–3.3 s（这是网络耗时） |

不只是快：按引用点击不可能偏一个像素，不会因为屏幕分辨率不同而失效，也不会点中中途冒出来的 cookie 横幅。

安装

要求：Windows、Node 22+（为了内置的 WebSocket），以及带配置档的 DeepSeek Harness。

1. 把 computer/ 文件夹复制进你的 DSH 配置档：

cp -r computer "$DSH_HOME/profiles/<profile>/plugins/computer"

2. 在配置档补丁里加上插件条目（$DSH_HOME/profiles/<profile>/cordis.patch.yml）：

- insert:
- id: tool-computer
name: ./plugins/computer/index.js
config:
maxWidth: 1600
maxHeight: 1000

name 相对于配置档文件夹，因为加载器的 baseUrl 指向那里。如果从别处的 --patch 层引入，改用 file:///... URL。

3. 重启 DSH：插件树在启动时组装。

没有东西需要安装：DSH 配置档的 node_modules 是空的，所以插件不从 @deepseek-ai/ 导入任何东西。它手写实现了 Cordis 消费的 Config['~standard'].validate，并用普通对象注册自己的工具。

出问题时，不用智能体也能修

这一节的存在，是因为一次真实故障，也因为一个让人不舒服的这类工具有一个共同特点：插件一旦弄坏会话，智能体自己修不了。 工具 schema 随每次请求一起发送，所以只要有一个不合法，每一轮都会失败——包括本该执行修复的那一轮。智能体不是恢复路径，你才是。

所以插件自带一项检查，它不依赖插件本身能否工作；还有一套恢复流程，短到用文本编辑器就能完成。

随时手动检查

node "$DSH_HOME/profiles/<profile>/plugins/computer/lib/health-check.js"

插件可以安全加载时，它退出码为 0，并打印 health check passed。不能加载时，它退出码为 1，逐条列出问题所在，并告诉你如何禁用它。它会构建工具 schema，再按严格服务商校验器的方式检查：每个数组都要有带类型的对象 items，required 必须是名称数组，不能有联合类型，每个对象都要有 additionalProperties。它不需要网络，不写任何东西，也不启动任何东西。

禁用它，这招永远管用

在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 里找到 tool-computer 那一行，把 disabled 设为 true：

- insert:
- id: tool-computer
name: ./plugins/computer/index.js
disabled: true # <- this line
config:
maxWidth: 1600

然后重启 DSH。

有两点要注意，都是踩过坑才明白的：

- 缩进很关键。 name、disabled 和 config 必须缩进在 - id: 之下，并且互相对齐。否则补丁格式不合法，插件会继续加载——手改「没生效」通常就是这个原因。
- 本地插件没有版本可以回滚。 它就是一个文件：每次重启加载的都是磁盘上当前的内容。没有之前能用的构建可以退回，所以恢复手段是 disabled: true，而不是降级。

为什么 schema 是最脆弱的部分

服务商在运行任何东西之前会校验整个工具列表，所以一个坏节点就会让全部被拒。而 DSH 校验的是工具返回*的值是否匹配 output.schema——从不校验它声明的参数——所以参数 schema 格式错误在本地根本不会报错。它表现为 Invalid schema for function 'x': ...，每一轮都出现。

正因如此才有两个脚本，任何对工具的改动在发布前都该跑一遍：

node scripts/schema-guard.mjs # asserts the published schema shape
node scripts/inspect-wire-schema.mjs # prints exactly what goes on the wire

配置

每个选项都是可选的。

config:
maxWidth: 1600 # screenshot width cap (px)
maxHeight: 1000 # screenshot height cap (px)
timeoutMs: 30000 # per-call budget
captureAfterActions: false # attach a fresh screenshot after click/type/key
persistentShell: true # keep one warm PowerShell per session (see below)
requireApprovalFor: [] # actions that must ask the user first
browserMode: null # 固定浏览器模式，或留 null 表示每个任务都询问 browserProfileDir: null # 「真实配置档」模式使用的 Chrome 用户数据目录

工具 browser — 9 个操作

| 操作 | 作用 |
| snapshot | 读取页面：交互元素带索引（e1、e2……），附标签、状态和焦点，外加可见文本 |
| click | 按快照里的 ref 点击元素，或用 CSS 选择器 |
| type | 在字段里输入，可先清空再按 Enter |
| press | 按键，可带修饰键 |
| navigate | 打开 URL 并返回快照 |
| evaluate | 运行 JavaScript 并返回结果：用于获取精确数据 |
| screenshot | 把标签页截成图片，视觉信息重要时用 |
| wait | 等待文本或选择器出现 |
| tabs | 列出打开的标签页 |

流程是：snapshot -> 读取引用 -> 用该 ref 执行 click/type -> 新的 snapshot。模型绝不会自己编造选择器或坐标。

三种浏览器模式，按任务选择

浏览器不会只用一种方式连接，因为隔离范围随你正在做的事而变。智能体不会猜该用哪种模式：调用时不声明模式就会失败，并让模型来问你。

| 模式 | 作用 | 何时用 |
| perfil-propio | Chrome 使用全新、隔离的配置档；不碰你的任何标签页或会话 | 日常工作。登录网站一次即可 |
| perfil-real | 你日常用的 Chrome，会话已经打开 | 当你已经登录时。需要先关闭 Chrome |
| sin-navegador | 完全不碰浏览器 | 网银、个人文书，任何你不想暴露的事 |

模式选择不会在任务之间继承：每次调用都带自己的 mode，模式变化时插件会关闭上一个连接，所以它无法复用用不同配置档打开的浏览器。想不再被询问，就固定一个：

config:
browserMode: perfil-propio

如果真实配置档正在使用，插件会立刻说明（以及该怎么做），靠即时检查锁文件，而不是等 45 秒去连一个永远不会响应的端口。

工具 computer — 16 个操作

| 操作 | 作用 |
| screenshot | 截取屏幕，并把图片返回给模型 |
| click、double_click、right_click | 在 x,y 处点击 |
| move、drag | 移动光标、拖拽 |
| scroll | 鼠标滚轮 |
| type | 在获得焦点的窗口里输入 |
| key、keys | 单个按键，或组合键（["ctrl","shift","s"]） |
| cursor | 光标在哪，什么获得了焦点 |
| windows | 列出窗口：标题、进程、PID、矩形区域、焦点 |
| focus_window、close_window | 置前、请求关闭 |
| start_app | 从封闭列表里打开应用 |
| wait | 等待 UI 稳定 |

坐标可以是绝对屏幕像素（space: "screen"），也可以是在截取模型刚刚看过的画面（space: "image"，默认值）：插件保存图像到屏幕的映射并翻译。

图像如何到达模型

这部分最容易出错。DSH 工具注册表会用 output.schema 校验 execute 返回的值，而且它是认真的：当 additionalProperties: false 时，把内容放进值里会让整个结果失效（INVALID_TOOL_OUTPUT），模型什么都收不到——既没有文本也没有图像。

正确的路径是 finalizeContent：值保持干净（{ action, result }），通过校验，内容——文本块和图像块——随后再附加：

const pendingContent = new WeakMap()

// in execute(): publish the capture and record its blocks
const reference = await ctx.attachments.saveImage({ data, mediaType: 'image/png', name })
pendingContent.set(exec, [
{ type: 'text', text: 'screenshot frame 7: 1600x664 px ...' },
{ type: 'image', attachment: reference },
])
return { action, result }

// in the tool definition
finalizeContent(exec) {
const content = pendingContent.get(exec)
pendingContent.delete(exec)
return content
}

运行时会在同一轮把图像附加到模型的上下文，所以模型下一步就能看到它。已端到端验证：屏幕上输入的唯一 token 仅凭截图就被读回——见 docs/vision-proof.png。

桌面性能

每个 computer 动作的开销等于启动 PowerShell 的开销……除非你不再每个动作都启动一个。用两台显示器在 5206x2160 下实测：

| | 每个动作 |
| 每个动作新开进程 | 8.6 – 10.4 s |
| 常驻服务器（默认） | 预热后 12 ms |

运行器有两种模式，共用同一条代码路径（Invoke-Request）：

- 服务器（-Server）：每个会话一个常驻 PowerShell，每行一个 JSON 请求，每行一个 JSON 响应。
- 单进程：回退模式，也是手动测试时方便的模式。

插件在挂载时于后台启动服务器，空闲 10 分钟后关闭，随 DSH 进程一起关闭，并且在服务器失败、死亡或停止响应时回退到单进程模式，而不是让动作失败。

要求与限制

- Windows。 用 GDI 截屏，用 SendInput/SetCursorPos 输入。
- Node 22 或更新版本，因为浏览器工具通过内置 WebSocket 讲 CDP。全程不安装任何包。
- 承载插件的进程必须能操作桌面。 在 DSH 中，shell 调用被低完整性受限 token 限制，而该 token 无法移动光标或注入输入（已验证：沙箱内 SetCursorPos 返回 False）。插件从宿主进程运行其运行器，而不是通过受限 shell。这是有意为之，详见 SECURITY.md。
- 当前模型必须接受图像，否则 screenshot 会被拒绝，并给出明确的
- 多显示器：screenshot 会截取整个虚拟桌面。截图会归一化到像素预算，坐标映射也会随之调整。
- 截屏会把屏幕上的一切都截进去。 如果你想监管的内容只在一个窗口里，就截那个窗口，别截整个桌面。

参与贡献

欢迎提交 bug 报告和改进，尤其是来自其他环境的反馈——这套东西对接的是 GDI、SendInput、Chrome 的 DevTools Protocol 和一个 DSH 配置档，出问题往往只出在其中某一处。

- 先读 CONTRIBUTING.md：里面列了提 pull request 前要跑的两项检查、代码风格，以及动手设计之前值得知道的两条约束。
- 开一个 issue——有 bug 表单和想法表单，bug 表单会问那些真正重要的环境细节。
- 如果你要改行为，请在 scripts/ 里加一项检查或调整一项检查。这个仓库的习惯是：关于清理或正确性的说法，要用脚本断言，而不是写在注释里。

开发

node scripts/audit-repo.mjs . # no machine paths, no secrets, no non-Node imports
node scripts/browser-integration.mjs # real Chrome, 9 browser actions, cleans up after itself

audit-repo.mjs 是让这个仓库可以安全发布的检查：只要混进作者机器上的路径、凭据，或者 Node 之外的 import，它就会失败。browser-integration.mjs 会启动一个用完即弃的浏览器，并断言它零残留进程——这个 bug 项目曾经发布过一次，后来用进程树 kill 修掉了。

致谢与先例

如果你刚接触 computer use，先读 Anthropic 的 computer use tool：它是行为参考，它的动作分发设计（action 加参数）也是这个项目沿用的。这里没有他们的代码——他们不公开实现——也没有复制他们的任何文档；见 NOTICE.md。

CDP 这条路子的思路，和浏览器自动化项目（比如无障碍树读取器）一致：读结构，不读像素。

许可证

MIT。见 LICENSE。