虚拟光标桌面操作 AndroidSix/dsh-computer-use-ng

dsh-computer-use-ng

让 DeepSeek Harness 像人一样操作桌面。 观察屏幕、定位界面元素、移动独立虚拟光标、点击、输入、滚动和拖拽。

给 DeepSeek Harness 一层安全、可观察的 Computer Use 能力。 观察桌面应用、定位界面元素，再通过独立虚拟光标执行操作。

dsh-computer-use-ng verified desktop demo

真实演示： 本地一个不含敏感信息的页面，通过 Computer Use 动作循环完成了观察、填写、点击和验证。

社区维护分支。 本项目基于 Wei Jerry 的 dsh-computer-use（MIT）独立维护，自 0.4.0 起重点跟进 DSH 0.2+。与原作者无隶属关系；原作者与贡献者的署名保留在 NOTICE 中。

中文文档 · English documentation

- 中文文档
- English Documentation

生态入口

| 入口 | 作用 | Link |
| harness-desktop | 开箱即用的 DeepSeek Harness 桌面客户端 | 下载 |
| AI House | 发现 AI 工具、模型和 Agent | 工具中心 |
| npm | 安装和查看包信息 | dsh-computer-use-ng |
| awesome-dsh-plugin | 发现更多 DeepSeek Harness 插件 | Plugin list |
| 上游项目 | 原始项目与历史版本 | dsh-computer-use |

维护说明

- 本仓库是独立维护分支，版本线从 0.4.0 开始；首个版本重点修复 DSH 0.2.1-rc.2 兼容性。
- 工具名（screen_observe、computer_click 等）保持不变，已有提示词和工作流无需改写。
- 本仓库从新的 Git 历史开始，不包含上游的提交历史或内部项目文档；MIT 署名见 NOTICE。
- 问题反馈、功能请求和 PR 请提到本仓库，而不是上游仓库。
- npm 包名 dsh-computer-use-ng，发布账号 androidsup；也可以用固定版本 dsh-computer-use-ng@0.4.0。

中文文档

这是什么？

dsh-computer-use-ng 是 DeepSeek Harness 的跨平台 Computer Use 插件，为 AI 智能体增加一套可观察、可约束、可验证的桌面操作能力。

它不是传统的鼠标宏：智能体必须先观察目标窗口，再基于新鲜快照执行动作。点击、双击和右键操作通过 cua-driver 的独立虚拟光标完成，用户可以看到操作过程，而不是让程序悄悄发送一串不可见事件。

适合用于：
- 让 DeepSeek Harness 操作原生 macOS、Windows 和 Linux 桌面应用；
- 操作 Electron、Canvas 或游戏等 Accessibility/AX 信息不完整的界面；
- 构建「打开应用 → 观察 → 点击 → 输入 → 再观察验证」的智能体闭环；
- 为桌面自动化、内部工具和个人工作流增加可审计的 Computer Use 执行层；
- 研究 Computer Use、视觉定位和安全护栏。

本项目是开源社区插件，不是 DeepSeek 官方产品，也不代表 DeepSeek 的官方立场。

为什么需要它？

普通文本智能体能生成答案，但很多桌面任务它没法直接完成。dsh-computer-use-ng 把桌面交互拆成三个阶段：

观察 Observation → 决策 Decision → 受约束执行 Guarded Action

flowchart LR
A[DeepSeek Harness Agent] --> B[dsh-computer-use-ng]
B --> C[安全护栏 Guard]
C --> D[AX / UIA 界面树]
C --> E[虚拟光标与键盘]
D --> F[cua-driver]
E --> F
F --> G[桌面应用 Desktop Apps]

核心原则：

1. 先观察，再操作：没有新鲜观察快照时，动作会被拒绝；
2. 模型所见即所点：元素编号和坐标来自同一窗口截图空间；
3. 语义优先：优先使用 element 编号，坐标模式保留视觉操作自由度；
4. 失败关闭：目标不明确、快照过期、应用不在白名单时不继续执行。

能力一览

| 能力 | 说明 |
| 屏幕观察 | 读取目标窗口元数据、Accessibility/AX/UIA 元素和坐标 |
| 三种观察模式 | ax 零视觉 token、native 主模型直读图片、vision 视觉观察者 |
| 独立虚拟光标 | 点击、双击、右键会显示虚拟光标移动和操作过程，不抢用户真实鼠标 |
| 文本与快捷键 | 输入文本、发送 return、cmd+c、ctrl+shift+p 等按键 |
| 滚动与拖拽 | 支持上下左右滚动和窗口本地截图坐标拖拽 |
| 应用管理 | 列出运行中的应用，后台启动应用，按需前置窗口 |
| 安全护栏 | 快照 TTL、应用白名单、危险操作审批、密码框保护 |
| 跨平台 | macOS 已验证；Windows/Linux 需按真实环境完成平台验收 |

12 个模型工具

| 工具 | 作用 | 主要参数 |
| screen_observe | 获取窗口、AX/UIA 元素、坐标或截图 | window, mode, query, maxElements |
| screen_zoom | 截取并放大窗口局部区域 | window_id, pid, x1, y1, x2, y2 |
| computer_click | 点击元素或截图坐标 | element 或 x,y，可选 count |
| computer_double_click | 双击元素或坐标 | element 或 x,y |
| computer_right_click | 右键点击元素或坐标 | element 或 x,y |
| computer_type | 向焦点或指定元素输入文本 | text, 可选 element |
| computer_key | 发送按键或快捷键 | key，例如 return、cmd+c |
| computer_scroll | 在目标窗口滚动 | direction, amount, 可选 element |
| computer_drag | 拖拽窗口中的区域 | from_x, from_y, to_x, to_y |
| computer_wait | 等待界面加载或动画完成 | ms，最大 60000 |
| app_list | 列出正在运行的应用 | 无 |
| app_launch | 启动应用 | name 或 bundle_id，可选 bring_to_front |

版本兼容

- 当前插件版本：0.4.0
- DSH 运行时：>=0.1.2-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0（已在 0.2.1-rc.2 实测通过）
- Node.js：>=22.18.0
- @deepseek-ai/dsh-tools / @deepseek-ai/schemastery 只声明为宿主 peerDependencies，不随插件打包，避免同进程出现第二份 DSH 模块

0.2 的 DSH 版本号是预发布版本（例如 0.2.1-rc.2）。普通范围 <0.2.0 在 node-semver 下不包含它，因此这里使用显式的 0.2 预发布区间；旧版 0.1.x 运行时仍受支持。

快速开始

方式一：DSH 插件管理器（推荐）

如果装过旧版 dsh-computer-use，先卸载，避免同名工具重复注册
dsh plugin --profile desktop remove dsh-computer-use

从 npm 安装（推荐，desktop profile）
dsh plugin --profile desktop add dsh-computer-use-ng

Web profile 同样一条命令
dsh plugin --profile web add dsh-computer-use-ng

或固定版本
dsh plugin --profile desktop add dsh-computer-use-ng@0.4.0

或直接从 GitHub 固定 tag 安装
dsh plugin --profile desktop add github:AndroidSix/dsh-computer-use-ng#v0.4.0

也可以直接在 DSH 的 插件页 → 添加插件 里输入包名 dsh-computer-use-ng。

安装完成后重启 DSH，或在插件页确认 dsh-computer-use-ng 已启用。

方式二：使用 harness-desktop

普通桌面用户建议先下载 harness-desktop。它是开箱即用的 DeepSeek Harness 桌面客户端，支持 macOS、Windows 和 Linux。

1. 下载并启动 harness-desktop
2. 完成首启配置
3. 安装本插件
4. 重启 harness-desktop
5. 在对话中让 Agent 操作桌面

方式三：从 GitHub 源码安装

git clone https://github.com/AndroidSix/dsh-computer-use-ng.git
cd dsh-computer-use-ng

先预演，不写入配置 ./install.sh --dry-run

安装到用户级 patch 层 ./install.sh

安装后重启 harness-desktop

安装脚本只做两件事：

1. 把插件链接到 $DSH_HOME/profiles/desktop/node_modules/dsh-computer-use-ng（找不到 desktop 时回退到 web）；
2. 在 $DSH_HOME/cordis.patch.yml 注册插件。

脚本使用用户级 patch 层，不改项目代码，也不改其他 profile 的配置。

Windows / Linux

install.sh 默认使用 $HOME/.dsh。Windows 或 Linux 用户请先指定自己的 DSH home：

export DSH_HOME="/path/to/your/dsh-home"
./install.sh --dry-run
./install.sh

如果系统不支持符号链接，请改用宿主 DSH 的插件管理方式，或按 docs/store-evidence.md 中的手动安装说明操作。

方式四：npm 包

npm install -g dsh-computer-use-ng

安装后仍需让 DSH profile 加载该 bundle，并确认 cua-driver 已安装且在 PATH 中，或设置：

export CUA_DRIVER_BIN=/path/to/cua-driver

在 Windows 官方安装器布局中，插件还会自动探测 %USERPROFILE%\\.cua-driver\\packages\\current\\cua-driver.exe；GUI 宿主的 PATH 不完整时，无需手工把目录加入 PATH。

安装完成后重启宿主，再通过 app_list 或 screen_observe 验证工具是否出现。

第一个完整任务

安装并授权后，可以让 Agent 执行下面的任务：

请完成以下桌面任务：

1. 使用 app_list 列出正在运行的应用；
2. 使用 app_launch 打开一个普通桌面应用；
3. 使用 screen_observe 观察目标窗口；
4. 找到目标按钮，优先使用 element 编号点击；
5. 使用 computer_type 输入一段非敏感测试文本；
6. 再次使用 screen_observe 验证文本已经出现；
7. 如果界面发生变化，请重新观察，不要使用旧元素编号继续操作；
8. 如果动作被安全护栏拒绝，请报告拒绝原因，不要绕过护栏。

推荐的操作循环

app_list / app_launch
↓
screen_observe
↓
computer_click / computer_type / computer_key
↓
computer_wait（如需等待） ↓ screen_observe 验证结果

每次界面明显变化后，都应重新调用 screen_observe。元素编号只属于某一次观察快照，不要跨页面、弹窗或长时间等待复用。

观察模式

screen_observe 的 mode 有三种选择：

| 模式 | 原理 | 成本 | 适用场景 |
| ax（默认） | 读取 AX/UIA 界面树并返回编号和坐标 | 不消耗视觉 Token | 原生应用、元素树完整的界面 |
| native | 将截图作为图片块交给当前对话模型 | 图片 Token；不额外调用视觉观察者 | Canvas、游戏、Electron 或 AX 树为空的界面 |
| vision | 通过 Harness 的 ctx.llm 调用视觉模型，返回结构化元素列表 | 额外一次视觉模型调用 | 当前主模型不支持图片输入时 |

native 模式

当前对话模型必须声明支持 image 输入，例如视觉模型。插件通过 Harness attachments 传递图片，不额外发起独立视觉 API 请求。

screen_observe(mode="native")

vision 模式

默认观察模型为：

provider: deepseek-official
model: deepseek-v4-flash-vision-exp

老版本 Harness 需要在模型配置中声明：

models:
- id: deepseek-v4-flash-vision-exp
input: [text, image]

当 DeepSeek 视觉观察者不可用时，插件可以尝试 GLM 视觉兜底。GLM 兜底需要 ZHIPU_API_KEY，并可能受到免费模型访问量限制。

自动降级

当 AX/UIA 树为空时，插件会尝试：

native（当前路由支持图片时） → vision（宿主存在可用视觉模型时） → ax（返回可用的界面树信息或明确错误）

坐标语义

从 v0.2.0 起，所有坐标均为：

窗口本地截图像素（window-local screenshot pixels）

这意味着：

- 坐标原点在目标窗口左上角；
- screen_observe 输出的 @(x,y) 与 computer_click(x=,y=) 使用同一坐标系；
- 不需要乘以 2；
- 不需要加屏幕坐标或窗口偏移；
- 使用 screen_zoom 时，返回图片是局部区域，但点击仍应使用整窗截图坐标。

优先使用：

computer_click(element=5)
只有在元素无法通过 AX/UIA 识别，或视觉模式给出坐标时，才使用：

computer_click(x=640, y=420)

安全模型

已内置的安全机制

1. 无快照拒绝：没有先调用 screen_observe，动作不会执行；
2. 观察快照 TTL：快照过期后动作被拒绝，必须重新观察；
3. 应用白名单：配置 allowedApps 后，只允许指定应用接受操作；
4. 危险操作审批：元素标签命中删除、支付、购买、转账、退出登录等词时请求用户确认；
5. 密码框保护：检测到 AXSecureTextField / AXPasswordField 时拒绝自动输入；
6. 键盘前台重试审批：键盘/文本优先后台投递；只有驱动明确拒绝后台投递并建议前台模式、且当前工具/平台支持时，才请求用户对本次前台重试授权；未获 allowed-once 不切换焦点、不重试；
7. 固定 argv 调用：通过宿主以非 shell 方式启动 cua-driver；
8. 权限边界声明：核心桌面路径不读取业务文件或额外凭据；仅当用户配置视觉 GLM fallback 时，才读取指定 key 来源并向 GLM API 发起请求；没有 npm lifecycle 安装脚本。

重要限制

语义安全检测依赖观察到的元素标签，主要对 element 编号模式有效：

- x/y 坐标模式无法提前知道目标语义，主要依赖快照 TTL 和可见操作；
- computer_type 和 computer_key 作用于当前焦点时，无法预判最终目标内容；
- 驱动拒绝后台键盘/文本投递时，前台重试会先请求本次用户批准；授权后可能切换目标窗口焦点；
- computer_key 不会阻止 cmd+q、ctrl+alt+delete 等系统快捷键；
- 不要把本插件的操作权限授予不可信 Agent；
- 密码、API Key 和其他敏感信息必须由用户本人输入。

配置

插件配置位于 DSH 的用户级 patch 层：

- id: dsh-computer-use-ng
config:
ttlMs: 30000
maxElements: 500
allowedApps: []
cursorTheme: com.dsh.computeruse.rainbow
nativeImage: auto
visionProvider: deepseek-official
visionModel: deepseek-v4-flash-vision-exp

| 配置项 | 默认值 | 说明 |
| ttlMs | 30000 | 观察快照有效期，单位毫秒；多步任务建议显式设置 30000-60000 |
| maxElements | 500 | 单次观察最多返回的编号元素数量 |
| allowedApps | [] | 空数组表示不限制；非空时只允许列表中的应用 |
| cursorTheme | com.dsh.computeruse.rainbow | 虚拟光标主题；空字符串使用引擎默认主题 |
| nativeImage | auto | auto 自动降级；full 原图；compact 始终使用小图 |
| visionProvider | deepseek-official | vision 模式使用的 provider |
| visionModel | deepseek-v4-flash-vision-exp | vision 模式使用的视觉模型 |

安装脚本或 bundle patch 可能覆盖代码层默认值。请以实际生成的 $DSH_HOME/cordis.patch.yml 为准；多步任务建议显式写入 ttlMs，不要依赖隐式默认值。

平台支持 · Platform Support

| 平台 | 状态 | 说明 |
| macOS | ✅ 已验证 | 可能需要 Accessibility 和 Screen Recording 权限 |
| Windows | ⛔ BLOCKED | 当前无 Windows 10/11 真机；路径和按键逻辑已测试，真实 GUI 未验收 |
| Linux | ⛔ 未验证 | 桌面环境、Accessibility 栈和窗口管理器可能影响元素识别 |

测试通过不代表所有应用的界面树都完全一致。AX/UIA 不完整时，请使用 native 或 vision 模式，并在提交问题时附上操作系统、目标应用和 screen_observe 输出。

故障排查

| 现象 | 常见原因 | 处理方式 |
| cua-driver not found | 引擎不在 PATH 或官方安装器路径不可用 | 安装 cua-driver，确认 ~/.cua-driver/packages/current/cua-driver.exe 存在，或设置 CUA_DRIVER_BIN |
| 没有可见窗口 | 图形会话或窗口权限不可用 | 确认目标应用正在运行并重新观察 |
| 快照已过期 | 超过 ttlMs | 重新调用 screen_observe |
| 元素编号点击失败 | 界面已经变化 | 重新观察后再使用新编号 |
| AX/UIA 树为空 | Canvas、游戏、Electron 或特殊窗口 | 使用 native 或 vision |
| native 被拒绝 | 当前主模型没有 image 输入能力 | 切换视觉模型或使用 vision |
| vision 模型不可用 | provider/model 未注册 image 输入 | 配置 visionProvider / visionModel |
| GLM fallback 不可用 | 没有 ZHIPU_API_KEY 或遇到限流 | 配置 Key，或使用 Harness 视觉模型 |
| 危险操作被拒绝 | 需要用户审批 | 检查审批提示，不要绕过安全护栏 |
| Windows 管理员窗口无法操作 | 目标窗口权限级别更高 | 使用普通用户窗口 |

开发与验证

项目使用隔离 profile 开发，避免污染真实 GUI 配置：

npm install
npm run check

运行时验证需要已安装 harness-desktop 和 cua-driver
node verify-runtime.mjs

macOS headless 验证示例：

DSH_HOME=$PWD/.dsh-p0 ELECTRON_RUN_AS_NODE=1 \
/Applications/harness-desktop.app/Contents/MacOS/harness-desktop --expose-internals \
/Applications/harness-desktop.app/Contents/Resources/app/node_modules/@deepseek-ai/dsh/lib/bin.js \
--profile test "请调用 screen_observe 观察当前窗口并报告"

更多证据：

- 权限声明
- 验证报告
- Windows 测试指南
- Store 安装证据
- 运行时验证脚本

自动发版到 npm

仓库的 .github/workflows/publish.yml 在 GitHub Release 发布时运行：

1. 校验 v版本号 与 package.json、package-lock.json 两处版本一致（scripts/check-release-version.mjs）；
2. npm ci 安装依赖，运行 npm test 与 npm run check，并做主题生成器冒烟检查；
3. npm pack 只打包 files 白名单内的文件，并把产物附加到 GitHub Release；
4. 通过 npm Trusted Publishing 发布（自动生成 provenance 签名，仓库中不需要 NPM_TOKEN）。

普通提交不会触发发布，草稿状态的 Release 也不会发布。稳定版本发布到 npm latest，预发布版本（如 0.5.0-rc.1）发布到 next。

日常更新流程：

1. 修改 package.json 的 version，并同步 package-lock.json
npm install --package-lock-only

2. 本地校验版本一致性（可选带 tag 参数）
npm run check:release -- v0.4.1

3. 提交并推送 main，然后基于该提交创建 v0.4.1 的 GitHub Release

也可以手动在 Actions 中触发 Publish to npm，输入已存在的 tag 重试。已经成功发布的 npm 版本不能重复发布，失败后请先修复原因再重试。

不想走 GitHub Release 时，可用本地脚本发布（需已 npm login）：

npm run publish:npm:dry # 只打印将执行的步骤，不打包、不上传
npm run publish:npm # 校验 → 测试 → 打包 → 发布

本地发布同样会生成 provenance，但签名者会是你的本机环境；推荐优先使用 GitHub Release 通道。

首次配置：在 npm 上打开包的 Settings → Trusted Publisher，选择 GitHub Actions，填写所有者为 AndroidSix、仓库 dsh-computer-use-ng、工作流文件名 publish.yml，环境名称留空，权限允许 npm publish。

相关项目

- harness-desktop：开箱即用的 DeepSeek Harness 桌面客户端；
- awesome-dsh-plugin：DeepSeek Harness 插件精选列表；
- AI House 工具中心：发现更多 AI 工具、模型和 Agent；
- cua-driver：底层跨平台桌面驱动；
- npm package：安装包和版本信息；
- GitHub 仓库：本维护分支的源码与 issue；
- 上游项目：原始项目与历史版本。

License

MIT License

English Documentation

dsh-computer-use-ng 是什么？

dsh-computer-use-ng 是 DeepSeek Harness 的跨平台 Computer Use 插件。它给智能体提供一层桌面操作能力：可观察、有护栏、可验证。

插件围绕一条明确的循环设计：

Observe → Decide → Execute with Guardrails → Observe and Verify

它能检查桌面窗口，暴露可操作的 AX/UIA 元素，用基于截图的视觉兜底，并通过隔离的虚拟光标操作。适合桌面自动化、Computer Use 研究、内部工作流，以及需要受限桌面操作的智能体应用。

这是社区插件，不是 DeepSeek 官方产品，与 DeepSeek 没有隶属关系。
维护说明： 本仓库是 dsh-computer-use（MIT）的独立维护延续版。版本号从 0.4.0 起算；issue 和 PR 都归本仓库处理。原作者信息记录在 NOTICE。

亮点

- 观察原生桌面窗口和无障碍树；
- 支持 ax、native、vision 三种观察模式；
- 点击、双击、右键、输入、按键、滚动、拖拽；
- 启动应用，列出正在运行的应用；
- 把动作绑定到最新的观察快照；
- 用应用允许列表限制动作范围；
- 遇到有风险的语义目标时请求批准；
- 拒绝向密码字段自动输入；
- AX/UIA 数据不完整时回退到截图；
- macOS 已验证；Windows 有逻辑和路径覆盖，但真实 GUI 验证受阻；Linux 尚未验证。

兼容性

- 插件版本：0.4.0
- DSH 运行时：>=0.1.2-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0（已在 0.2.1-rc.2 上验证）
- Node.js：>=22.18.0
- @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery 只是宿主的 peerDependencies，所以配置档不会在宿主进程里再生成一份 DSH 模块副本

DSH 0.2 版本是预发布版（例如 0.2.1-rc.2）。按 node-semver 的规则，单纯的 <0.2.0 范围会把它们排除在外，所以清单里显式写了 0.2 预发布分支。0.1.x 系列仍然支持。

快速开始

用 DSH 插件管理器安装（推荐）

Remove the original plugin first if it is installed, to avoid duplicate tool names.
dsh plugin --profile desktop remove dsh-computer-use

Install from npm
dsh plugin --profile desktop add dsh-computer-use-ng

The same command works for the web profile
dsh plugin --profile web add dsh-computer-use-ng

Or pin a version
dsh plugin --profile desktop add dsh-computer-use-ng@0.4.0

Or install from the GitHub tag
dsh plugin --profile desktop add github:AndroidSix/dsh-computer-use-ng#v0.4.0

重启 DSH，或者在插件页面确认 dsh-computer-use-ng 已启用。

推荐的桌面体验

下载 harness-desktop，这是开箱即用的 DeepSeek Harness 桌面客户端。装好宿主后，安装本插件并重启宿主。

从源码安装

git clone https://github.com/AndroidSix/dsh-computer-use-ng.git
cd dsh-computer-use-ng

./install.sh --dry-run
./install.sh

安装脚本会创建用户级插件链接，并把 bundle 注册到 DSH home 补丁层。它不会改动项目源文件，也不会改动其他配置档。

在 Windows 或 Linux 上，运行脚本前先把 DSH_HOME 设为实际的 DSH home 目录：

export DSH_HOME="/path/to/your/dsh-home"
./install.sh

安装 npm 包

npm install -g dsh-computer-use-ng
确认宿主已加载 bundle，且 cua-driver 在 PATH 中可用，或者把 CUA_DRIVER_BIN 设为它的绝对路径。

在 Windows 上，官方安装器的目录布局也会被自动识别，路径是 %USERPROFILE%\.cua-driver\packages\current\cua-driver.exe，这样即使 GUI 宿主的 PATH 里没有该驱动，也能正常使用。

工具

| 工具 | 用途 | 主要参数 |
| screen_observe | 观察窗口、AX/UIA 元素、坐标或截图 | window、mode、query、maxElements |
| screen_zoom | 截取更小的区域做视觉检查 | window_id、pid、x1、y1、x2、y2 |
| computer_click | 点击元素或截图坐标 | element 或 x,y；可选 count |
| computer_double_click | 双击元素或坐标 | element 或 x,y |
| computer_right_click | 右键点击元素或坐标 | element 或 x,y |
| computer_type | 向当前聚焦或选中的输入框输入文本 | text，可选 element |
| computer_key | 发送按键或快捷键 | key，例如 return、cmd+c |
| computer_scroll | 滚动目标窗口 | direction、amount，可选 element |
| computer_drag | 在截图坐标之间拖拽 | from_x、from_y、to_x、to_y |
| computer_wait | 等待页面加载或动画结束 | ms，最大 60000 |
| app_list | 列出正在运行的应用 | 无 |
| app_launch | 启动应用 | name 或 bundle_id；可选 bring_to_front |

标准操作循环

app_list / app_launch
↓
screen_observe
↓
computer_click / computer_type / computer_key
↓
computer_wait
↓
screen_observe to verify the result

快照只在本次观察内有效。UI 一旦变化，就要重新观察，然后再使用上一状态里的元素索引或坐标。

观察模式

| 模式 | 工作方式 | 适用场景 |
| ax | 返回紧凑的 AX/UIA 树，带元素索引和坐标 | 无障碍数据可用的原生应用 |
| native | 把截图作为图片块返回给当前多模态模型 | Canvas、游戏、Electron，或 AX/UIA 数据不完整的窗口 |
| vision | 调用 Harness 的 ctx.llm 视觉模型描述截图 | 纯文本主模型，需要单独的观察器 |

native 要求当前路由声明支持图片输入。vision 使用配置好的 visionProvider 和 visionModel；默认模型是 deepseek-v4-flash-vision-exp。可选的 GLM 兜底需要 ZHIPU_API_KEY，并且可能被限流。

无障碍树为空时，回退顺序是：

native → vision → ax

插件会挑一条可用的路径；如果没有任何视觉路径可用，就返回明确的错误。

坐标语义

从 v0.2.0 起，所有坐标都是窗口内的截图像素：

- 原点位于目标窗口的左上角；
- screen_observe 返回的坐标与 computer_click 接受的坐标处于同一坐标系；
- 不要乘以 2；
- 不要加屏幕或窗口偏移；
- screen_zoom 返回裁剪后的图像，但点击坐标仍是全窗口截图坐标系中的坐标。

优先使用语义化元素操作：

computer_click(element=5)

当目标未通过 AX/UIA 暴露，或视觉观察器提供了坐标时，使用 x,y。

安全模型

插件包含：

1. 先观察后操作：没有最新观察结果的操作会被拒绝；
2. 快照 TTL：快照过期后需要重新观察；
3. 应用白名单：allowedApps 可限制操作范围；
4. 风险操作审批：删除、支付、购买、转账、退出登录等标签可要求用户审批；
5. 密码字段保护：拒绝向密码字段自动输入；
6. 键盘前台重试审批：键盘/文本操作优先走后台投递；驱动明确拒绝后，且仅在驱动支持该模式时，前台重试需要一次性用户审批。未获审批则不改变焦点，也不重试；
7. 固定非 shell 驱动调用：宿主以固定 argv 启动 cua-driver；
8. 明确权限边界：核心桌面路径不读取业务文件或额外凭据。可选的 GLM 回退只读取其配置的密钥来源，并向 GLM 视觉 API 发送 HTTPS 请求；没有 npm 生命周期脚本。

语义检查对基于 element 的操作最有效。坐标操作和未聚焦的 computer_type/computer_key 调用无法预测最终语义目标。computer_key 不校验系统快捷键。不要把这能力交给不可信的智能体，密码和密钥请始终自己输入。

如果驱动报告 background_unavailable，在当前工具/平台支持的情况下，插件会请求一次性审批，然后以前台模式重试；该重试可能把目标窗口带到前台。拒绝或未获审批则操作保持被拒。

配置

- id: dsh-computer-use-ng
config:
ttlMs: 30000
maxElements: 500
allowedApps: []
cursorTheme: com.dsh.computeruse.rainbow
nativeImage: auto
visionProvider: deepseek-official
visionModel: deepseek-v4-flash-vision-exp

| 选项 | 默认值 | 说明 |
| ttlMs | 30000 | 观察结果有效期，单位毫秒 |
| maxElements | 500 | 观察返回的索引元素上限 |
| allowedApps | [] | 空表示不限制；否则只允许列出的应用 |
| cursorTheme | com.dsh.computeruse.rainbow | 虚拟光标主题；空则使用引擎默认值 |
| nativeImage | auto | 截图策略：auto、full 或 compact |
| visionProvider | deepseek-official | vision 模式使用的服务商 |
| visionModel | deepseek-v4-flash-vision-exp | 支持图像输入的观察模型 |

如果安装器或 bundle 补丁覆盖了代码级默认值，以生成的 $DSH_HOME/cordis.patch.yml 为准。多步任务请显式设置 ttlMs，不要依赖隐式默认值。

平台支持

| 平台 | 状态 | 说明 |
| macOS | ✅ 已验证 | 可能需要辅助功能和屏幕录制权限 |
| Windows | ⛔ 受阻 | 逻辑与路径覆盖已具备；真实 GUI 验证需要 Windows 10/11 普通用户桌面会话 |
| Linux | ⛔ 未验证 | 桌面环境、辅助功能栈和窗口管理器都会影响元素发现 |

macOS 路径已在项目证据中验证。Windows 和 Linux 仍需在真实平台上跑一遍，才能宣称已完整测试。这不代表每个应用暴露的辅助功能树都相同。AX/UIA 数据不完整时，改用 native 或 vision，并在 bug 报告里附上操作系统、目标应用和观察输出。

故障排查

| 现象 | 可能原因 | 处理方式 |
| cua-driver not found | 驱动不在 PATH 中，或官方安装器路径不可用 | 安装驱动，确认 ~/.cua-driver/packages/current/cua-driver.exe 存在，或设置 CUA_DRIVER_BIN |
| 看不到窗口 | 缺少图形会话或权限 | 确认目标应用可见，再观察一次 |
| 快照过期 | ttlMs 已超时 | 再次调用 screen_observe |
| 元素点击失败 | UI 已变化 | 重新观察，使用新的索引 |
| AX/UIA 树为空 | Canvas、游戏、Electron 或特殊窗口 | 改用 native 或 vision |
| native 被拒绝 | 主路由不支持图像输入 | 换成支持图像输入的模型，或改用 vision |
| 视觉模型不可用 | 服务商/模型未声明图像输入能力 | 配置 visionProvider / visionModel |
| GLM 兜底不可用 | 缺少 ZHIPU_API_KEY 或触发限流 | 配置密钥，或改用 Harness 视觉模型 |
| background_unavailable | 驱动无法在后台发送键盘/文本输入 | 如果可以接受切换窗口焦点，批准一次性前台重试 |
| 风险操作被拒绝 | 未获得用户批准 | 遵循批准结果，不要绕过防护 |
| Windows 提权窗口被拒绝 | 目标权限级别更高 | 改用普通用户窗口 |

开发与验证

npm install
npm run check
node verify-runtime.mjs

运行时验证需要可用的 harness-desktop 安装和 cua-driver。更多证据见：

- PERMISSIONS.md
- VERIFICATION.md
- WINDOWS_TEST.md
- docs/store-evidence.md
- verify-runtime.mjs

生态

- harness-desktop —— 开箱即用的 DeepSeek Harness 桌面客户端；
- awesome-dsh-plugin — DeepSeek Harness 插件精选列表；
- AI House Tools — 发现 AI 工具、模型和智能体；
- cua-driver — 底层的跨平台桌面驱动；
- npm package — 包版本与下载量；
- GitHub repository — 本维护分支的源码与 issue 跟踪；
- Upstream project — 原项目与历史版本。

License

MIT License

与 DeepSeek 无隶属关系。DeepSeek Harness 是 DeepSeek AI 的开源项目。