xiaoheizi1212/dsh-computer-use

dsh-computer-use

面向 DeepSeek Harness 的模型无关 Computer Use 能力：一个隔离的浏览器、一个 Windows 原生辅助程序、提供商中立的观察、一个用于导入已登录会话的 Chrome Cookie Bridge，以及一个文本规划器（DeepSeek）加一个用于感知的第三方视觉模型。

平台与许可证

- 许可证：MIT — 开源，可自由使用、修改和再分发。
- 平台：windows 提供商的原生辅助程序仅支持 Windows；playwright 浏览器提供商及其他所有内容均跨平台。
- macOS：目前尚未开发 — 作者没有 macOS 环境。欢迎开发者贡献 macOS 版本。

致谢

第 1 版 — 使用 DeepSeek-V4-Pro-0813 与 DeepSeek Harness 创建。

Token 用量：223,443,625 tokens · 99% 缓存命中率。

它提供什么

- 一个能力接缝 ctx.computerUse（start / listTargets / observe / act / stop）。
- 六个面向模型的工具：computer_observe、computer_act、computer_stop、computer_take_over、computer_resume、computer_perceive。
- 同一接缝背后的三个提供商：fake（确定性测试）、playwright（隔离的 Chromium）、windows（原生辅助程序）。
- 一个感知层：accessibility 模式（无图像）和 analyze 模式（截图 → 第三方视觉模型 → 结构化结果）。
- 风险分级、故障关闭式审批 + 域名允许列表 + 完整的 computer/ 可重放会话日志。

必需插件（harness 依赖）

| 包 | 原因 |
| --- | --- |
| @deepseek-ai/dsh-llm-pi-ai | 承载第三方视觉路由（声明 input:['text','image']） |
| @deepseek-ai/dsh-llm | image 内容块和 createUserMessage |
| @deepseek-ai/dsh-attachment（+ -local） | 将截图持久化为内容寻址引用 |
| @deepseek-ai/dsh-credentials（+ -local） | 按请求解析视觉 API 密钥 |
| @deepseek-ai/dsh-user-approval | 一次性故障关闭式操作审批 |
| @deepseek-ai/dsh-tools / -session / -system-prompt | 工具注册表、会话日志、指导 |

@deepseek-ai/dsh-llm-deepseek 仅支持文本，不能作为视觉模型 — 它是规划器。

配置

所有选项都位于 dsh-computer-use/plugin 行（config:）上，例如在你的 profile 的 cordis.patch.yml 中：

- id: computer-use
name: dsh-computer-use/plugin
config:
provider: playwright
visionProvider: xiaomi
visionModel: mimo-v2.5

你也可以直接从 DeepSeek Harness GUI 实时开启/关闭整个能力 — 该插件注册了一个 computer-use 设置区（Settings → computer-use），因此 enabled、provider 以及上面的浏览器/导入选项无需编辑 YAML 即可编辑。

核心

| 选项 | 默认值 | 含义 |
| --- | --- | --- |
| enabled | true | 主开关 — false 会关闭整个能力 |
| provider | fake | 后端：fake（测试）\| playwright（浏览器）\| windows（桌面） |
| tools | true | 注册面向模型的工具 |
| confirmActions | true | 在风险性 computer_act 调用前进行一次性确认 |
| visionProvider / visionModel | — | computer_perceive analyze 使用的 llm-pi-ai 路由 + 模型 |
| visionMaxTokens | 2000 | 视觉输出 token 上限 |
| allowedDomains | [] | 浏览器可在其中操作的主机名（空 = 无限制） |
| windowsHelperCommand | '' | 原生辅助可执行文件（默认为捆绑的 lib/native/win32-x64/dsh-computer-use-helper.exe） |

浏览器（Playwright）会话

| 选项 | 默认值 | 含义 |
| --- | --- | --- |
| browserHeadless | true | 无头模式（默认）或可见窗口。false = 正常模式（弹窗） |
| browserWindowState | normal | 可见窗口状态：normal \| maximized \| minimized（先 launch、后应用状态） |
| reuseBrowserProfile | false | 使用持久化（专用）浏览器配置文件，而非隔离上下文 |
| browserUserDataDir | — | 持久化配置文件的 "User Data" 根目录（非默认；例如 ~/.dsh/browser-profiles/main） |
| browserProfileName | Default | browserUserDataDir 内的配置文件目录名 |
| importCookies | false | 导入 cookies，使隔离浏览器共享用户的登录状态 |
| importPasswords | false | 导入已保存的密码以用于自动填充 |
| importHistory | false | 导入浏览历史作为注入上下文 |
| cookiesFile | — | 当 importCookies 时加载的 Playwright 存储状态 JSON（{ "cookies": [...] }） |
| passwordManagerCsv | — | 当 importPasswords 时的密码管理器 CSV 导出（name,url,username,password） |

Windows（桌面）提供程序

| 选项 | 默认值 | 含义 |
| --- | --- | --- |
| windowsWindowState | normal | 目标窗口状态：normal \| maximized \| minimized（minimized = 先激活后最小化） |

脚本化：导入 cookies / 密码 / 历史记录

浏览器默认以隔离方式启动（无 cookies、无配置文件）。要赋予其你的登录状态：

A. Cookie Bridge（推荐 — 适用于 Chrome 127+ App-Bound Encryption）

Chrome 127+ 使用 App-Bound Encryption 加密 cookies，因此独立进程无法读取你现有配置文件的 cookies。Cookie Bridge 通过在 Chrome 内部运行来绕过此限制：一个小型扩展通过 chrome.cookies 读取 cookies（明文 — Chrome 自行解密）并将其 POST 到本地接收器。

1. 一次性安装配套扩展（见 github.com/xiaoheizi1212/dsh-cookie-bridge）：
chrome://extensions → 开发者模式 → "加载已解压的扩展程序" → 扩展文件夹。
2. 启动接收器：
pnpm exec tsx scripts/import-cookies-server.ts
3. 要么点击扩展图标并选择一个域名，要么从 agent 驱动它：
pnpm exec tsx scripts/request-cookies.ts all x.com,xiaohongshu.com

然后将插件指向保存的 cookies.json：

- id: computer-use
config:
provider: playwright
importCookies: true
cookiesFile: "C:/path/to/dsh-computer-use/cookies.json"

Cookie 值只会从 Chrome 传输到 127.0.0.1（绝不会传输到远程主机），并且只会导出你所选域的 cookie。多次导出会合并（按 domain|path|name 去重）。

B. 专用浏览器配置文件（手动登录一次）

使用插件自有的、非默认配置文件。Chrome 拒绝在其真正的 User Data 目录上启用远程调试，而复制配置文件不会携带 App-Bound cookie，因此受支持的路径是创建一个全新的专用配置文件，在其中登录一次：

- id: computer-use
config:
provider: playwright
reuseBrowserProfile: true
browserUserDataDir: "C:/Users/you/.dsh/browser-profiles/main"
browserProfileName: "Default"
browserHeadless: false   # visible window so you can log in

⚠️ 不支持复用你现有的* Chrome 配置文件：Chrome 127+ 的 App-Bound Encryption 以及“默认数据目录上不允许远程调试”的限制就是为了阻止这种做法而设计的。

密码 / 历史记录（预留）

- 密码 — importPasswords: true 需要一个 passwordManagerCsv 导出文件（name,url,username,password）；预留开关，请先接入你自己的自动填充桥接。
- 历史记录 — importHistory: true 是一个预留开关；在你自己的适配器中，将访问量最高的来源作为模型上下文注入。

每次导入都会削弱隔离性。只导入任务所需的内容，并且在 allowedDomains 列表为空时绝不要启用导入。

视觉模型

推荐默认值：qwen2.5-vl-72b-instruct，通过 OpenAI 兼容网关（自托管 vLLM、DashScope、OpenRouter）使用。备选：gpt-4o-mini、glm-4v-flash、llava-v1.6-34b、internvl2-76b、mimo-v2.5。

在你的配置文件的 settings.yaml（或基础 llm-pi-ai 部分）中配置视觉路由：

llm-pi-ai:
providers:
vision:
apiKeyEnv: VISION_API_KEY
api: openai-completions
baseURL: https://your-vision-endpoint/v1
defaultInput: [text, image]
models:
- id: qwen2.5-vl-72b-instruct
contextWindow: 131072
input: [text, image]

pi-ai 不会验证模态声明：一个声明支持图像但实际并不支持的模型，会在消息持久化后于回合中途失败。在确定选用某个模型之前，请验证它确实能接受图像。

安装与加载

dsh plugin --profile web add dsh-computer-use
npx playwright install chromium   # once, for the playwright provider

该 bundle 的 cordis.patch.yml 会挂载 ctx.computerUse（包根目录）以及工具/提供方插件（dsh-computer-use/plugin，提供方为 fake）。在你的配置文件补丁中覆盖 provider，以选择 playwright 或 windows。

提供方

- fake — 用于契约测试和无密钥演示的确定性内存提供方。
- playwright — 隔离的 Chromium：观察（截图 → ctx.attachments + 带短生命周期元素 id 的无障碍树）与操作（click-element / click-coordinate / type-text / press-key / scroll / drag / set-value / activate-target）。默认无头模式；通过 browserHeadless / browserWindowState 启用有头模式 + 窗口状态。
- windows — 原生辅助协议（src/native/）之上的轻量适配器；自包含的辅助程序（dsh-computer-use-helper.exe，UI Automation + Windows.Graphics.Capture + SendInput）由 pnpm build 构建。通过 windowsWindowState 设置目标窗口状态。

策略

- 操作按类型进行确定性的风险分类，绝不依据页面内容：scroll / activate-target → read（无需确认）；type-text / set-value / drag → local；click- / press-key → external（一次性确认）。destructive / financial / auth 属于域/策略层面的判定，交由 Harness 权限扩展处理。
- allowedDomains 将 Playwright 提供程序限制为仅在列出的主机名内操作；超出允许列表的目标会以 TARGET_NOT_ALLOWED 失败。
- 提示注入边界：分类器和允许列表从不读取页面文本、无障碍名称或截图内容，因此不受信任的页面内容无法授予权限。

开发

pnpm install
pnpm build      # tsdown 将 src 打包进 lib/ + dotnet 将原生辅助程序发布到 lib/native/win32-x64
pnpm test       # 无密钥契约测试（fake/framing/transport/windows/perception）+ Playwright（需要 Chromium）
pnpm typecheck

源码使用显式的 .ts 导入说明符（harness 约定）；tsdown 会将其重写为 .js。

文档

- 协议 — 带版本的原生辅助线协议（分帧、握手、方法、截图通道）。
- 安全 — 威胁模型与安全不变量。
- 提供程序编写 — 如何向 ctx.computerUse 接缝添加提供程序。

许可证

MIT