orangeofcarl0-sys/dsh-computer-use

dsh-computer-use

我的 DeepSeek Harness 桌面操作插件：观察 → 编号定位 → 自动升级投递 → 验证，全程零审批、零打断。

[Version]()
[dsh]()
License: MIT
Node.js
Platforms

verified desktop demo

源自 988hj7tczd-oss/dsh-computer-use（MIT）@07477f4，现为独立维护的个人项目，安全姿态与投递管线均按自有路线演进。出处与借鉴见文末「出处与致谢」。

这是什么

给 DeepSeek Harness 加一套可观察、可验证的桌面操作层：折叠态 2 个 / 展开态 21 个模型友好工具（动态工具面：默认只暴露 computer_do 与 screen_observe，进入后展开全部），底层通过 cua-driver 驱动本地桌面（独立虚拟光标，不抢真实鼠标）。Windows 深度实测——前台锁、XAML/WinUI 输入、观测几何这些硬墙都在本机踩过并解决。

三个核心机制：

1. 先观察，再操作：动作必须基于新鲜观察快照（element 编号或窗口本地截图像素坐标），过期即拒绝；
2. 所见即所点：观察输出与动作坐标共用同一"窗口本地截图像素"空间，零换算；
3. 自动升级投递：后台优先，后台不可用自动升级前台、绕前台锁，完成后恢复用户原焦点。

设计立场：无感自治

不追求极致安全，方向相反。在"后台优先 + 升级链 + 恢复原前台 + 审计注记"底座上执行四原则：

| 原则 | 行为 |
|---|---|
| 易用无感 | 动作零审批、零打断；归因靠全量投递注记 + harness 会话日志 |
| 自动提权 | 投递链自动升级（恢复原前台）；观测失败自动降级桌面级采集；观测/投递能力默认全开，无模式开关 |
| 极危敏感警告 | extremePatterns 命中元素标签 → 结果附警告注记，不阻断；默认空 = 零差异 |
| 仅作基本兜底 | 凭据硬保护（密码框拒绝自动输入，唯一硬拒绝）、快照 TTL、无快照拒绝、allowedApps 白名单（默认关） |

能力一览

| 能力 | 说明 |
|---|---|
| 屏幕观察 | 目标窗口 AX/UIA 编号树 + 坐标；native 主模型直读截图；vision 观察者描述 |
| 区域放大 | screen_zoom 裁剪窗口局部为 ≤500px JPEG 直读 |
| 独立虚拟光标 | 点击/拖拽展示操作过程，不抢用户真实鼠标 |
| 文本与快捷键 | computer_type 走 UIA ValuePattern 后台写入（XAML/WinUI 必需）；组合键走 hotkey 通道（UIA AcceleratorKey 匹配） |
| 三级投递链 | background → foreground → bring_to_front 绕锁，完成后恢复原前台 |
| 观测几何根治 | 1:1 窗口截图（max_image_dimension 配置化），点击零标定命中 |
| 应用管理 | 列出运行中应用、后台启动、按需前置 |
| 确定性验证 | computer_verify / computer_wait_for：UIA 谓词断言与轮询（unknown 永不视为成功） |
| 剪贴板与菜单 | 剪贴板读写（粘贴流）；菜单路径直调（fail-closed） |
| 强杀开关 | computer_stop 锁存全部桌面操作，computer_resume 唯一解锁 |
| 子 agent 委派 | computer_task：多步/噪声大的操作交给一次性子 agent，必须以 {ok,summary,evidence} 收尾，主上下文只吃一条 ≤400 字符回执。工具范围能否限制取决于宿主能力：能限制时只给桌面工具；宿主拒绝该约束时插件照常委派并在回执里如实写明（含拒绝原因）——见〈委派的能力边界〉 |
| 上下文成本控制 | 重复观察降噪（未变窗口回极简回执，实测大树 1586→250 字符）、成本阶梯写入工具描述（ax 300px，且为先验驱动的布局重建而非像素测量），像素路径一律走定位环：

screen_observe（AX 树失败/树空）
→ screen_zoom(x1,y1,x2,y2)  # 取目标主导的小裁剪
→ 本图内语义确认目标 + 读出图内坐标
→ 图内坐标 × crop.scale + crop.x/y = 整窗截图像素
→ computer_click(x=,y=)（必要时 AX/视觉复核命中）

screen_zoom 结果附 crop 元数据（原点/尺寸/换算比例）并给出换算公式。裁剪务必让目标占画面主导——实测目标主导小裁剪误差 13-80px。

委派的能力边界（诚实说明）

computer_task 想给子 agent 施加三条约束：限定工具范围（只用桌面工具）、要求结构化输出、禁止再派生。它们是独立的宿主能力，能否生效取决于宿主提供方：

- 三者都支持 → 子 agent 只拿到桌面工具，结构化结果经宿主校验；
- 宿主拒绝工具范围约束时（实测形态：tools.restrict() names unknown global tools——动态工具面把工具注册在会话作用域后，宿主对 toolFilter 的名字校验只认全局层）→ 插件丢掉这一条、保住结构化输出，并在回执里写明“子 agent 拥有与父会话同级的能力”及拒绝原因；
- 宿主连结构化也不支持 → 再降一级，回执标注“结果未结构化”。

也就是说：在宿主不支持工具范围约束的部署上，子 agent 与父会话能力同级（可能具备 shell/文件工具）。插件不会把这条约束当作已生效来上报；需要严格限制时，请用宿主自己的子 agent 机制并在其配置里限定工具。

前后台投递

两条通道：后台（UIA Invoke / PostMessage，不抢焦点，后台/最小化窗口可操作）与前台（短暂焦点交换 + SendInput，完成后恢复原前台）。会静默丢弃后台事件的目标（Chromium/Electron 内容、GTK、VCL 等），驱动返回结构化 background_unavailable 而非假装成功。

| deliveryMode | 行为 |
|---|---|
| auto（默认） | 后台优先；background_unavailable → 自动前台重试；前台锁拦截 → bring_to_front（AttachThreadInput）绕锁重试，完成后恢复原前台窗口；全过程注记进结果 |
| background | 全程后台；不可用时返回结构化错误 + foreground=true 升级指引 |
| foreground | 始终前台 |

单次动作可用 foreground: true 覆盖。Windows 前台锁（ForegroundLockTimeout）、UIPI、XAML CoreInput 不吃 PostMessage 这些坑均已实测绕过——详见提交历史与 WINDOWS_TEST.md。

配置

- id: dsh-computer-use
config:
ttlMs: 60000
maxElements: 120
observeDedup: summary
verboseReceipts: false
taskTimeoutMin: 5
maxTaskCalls: 3
supersession: note
allowedApps: []
cursorTheme: com.dsh.computeruse.rainbow
nativeImage: auto
visionProvider: deepseek-official
visionModel: deepseek-v4-flash-vision-exp
passwordScan: auto
extremePatterns: []
deliveryMode: auto

| 配置项 | 默认 | 说明 |
|---|---:|---|
| ttlMs | 60000 | 观察快照有效期（毫秒） |
| maxElements | 120 | 单次观察最多返回的编号元素数（实测常见任务 30-70 个） |
| observeDedup | summary | 重复观察降噪：同一未变窗口回极简回执——summary（含编号摘要）/ brief（单行）/ off（每次全量）；需要完整清单时传 force=true |
| verboseReceipts | false | 动作回执详略：false = 只回一行要点；true = 附原始 JSON 明细（排障用） |
| taskTimeoutMin | 5 | computer_task 默认超时分钟数（可用 timeout_min 覆盖，1-60）。实测设太长会在子 agent 无法收敛时纯浪费 |
| maxTaskCalls | 3 | 每会话允许的 computer_task 次数上限（防委托风暴与反复超时重复劳动） |
| supersession | note | 同快照连击语义：note 附一致性注记 / enforce 第二次动作直接拒绝（每动作一观察）/ off 全关 |
| passwordScan | auto | Windows 结构性密码扫描（UIA sidecar 读 IsPassword ∨ ES_PASSWORD 结构位）；off = 零 spawn，凭据保护退回启发式。macOS/Linux 不适用 |
| allowedApps | [] | 作用域白名单；空 = 不限制 |
| cursorTheme | com.dsh.computeruse.rainbow | 虚拟光标主题；空 = 引擎默认 |
| nativeImage | auto | auto 超限额自动降级 / full 原图 / compact 始终小图 |
| visionProvider / visionModel | deepseek-official / deepseek-v4-flash-vision-exp | vision 观察者路由 |
| extremePatterns | [] | 极危清单（正则源数组）：命中元素标签 → 警告注记，不阻断 |
| deliveryMode | auto | 投递策略，见上节 |

平台支持

| 平台 | 状态 | 说明 |
|---|---|---|
| Windows | ✅ 深度实测 | 三级链 / XAML hotkey / 1:1 观测均在本机闭环；管理员窗口属系统边界（UIPI） |
| macOS | ✅ 已测试 | 需 Accessibility / Screen Recording 授权 |
| Linux | ✅ 已测试 | 桌面环境与 accessibility 栈影响元素识别 |

故障排查

| 现象 | 常见原因 | 处理 |
|---|---|---|
| cua-driver not found | 驱动不在 PATH | 安装驱动或设 CUA_DRIVER_BIN |
| 没有可见窗口 | 图形会话/窗口权限 | 确认目标在运行并重观察 |
| 快照已过期 | 超过 ttlMs | 重新 screen_observe |
| 元素编号点击失败 | 界面已变化 | 重观察取新编号 |
| AX/UIA 树为空 | Canvas/游戏/Electron | 用 native / vision |
| native 被拒 | 主模型无 image 能力 | 换视觉模型或用 vision |
| 动作被守卫拒绝 | 无快照/过期/白名单/凭据保护 | 按拒绝原因处理，守卫拒绝均有明确原因文本 |
| Windows 管理员窗口不可操作 | UIPI 完整性级别更高 | 使用普通用户窗口 |

开发与验证

npm install
npm run check                      # 语法 + 安装脚本检查
npm test                           # 七套离线测试共 148 断言：
posture 34（无感自治姿态/凭据硬保护/快照新鲜度）
tools 15 · delivery-chain 3
schema.conformance 20 工具 × 42 场景（按声明 schema 严格校验每种返回形态，
含结构化拒绝/驱动错误/观测降级——dsh 严格输出校验类 bug 的守门测试）
observe.dedup 13 · task.tool 16 · config.plumbing 25
node verify-runtime.mjs            # 运行时验证（需真实 harness + cua-driver）
node tests/live-action.e2e.mjs 3   # 真桌面动作闭环 + 稳定性循环（真记事本 3 轮）
node evals/verify-oracles.mjs      # S4 评测 oracle 双向验证（setup 必 ok → 空跑必失败 → simulate 必过）

License

MIT。个人项目，与 DeepSeek 无关。

English (brief)

Personal Computer Use plugin for the DeepSeek Harness: 2 tools by default (dynamic tool surface — computer_do + observe), 21 when expanded driving local desktops through cua-driver with an isolated virtual cursor. Windows-deep-tested.

Stance — zero-friction autonomy: no approval prompts, no interruptions; capabilities always on (auto desktop-level observation fallback, three-tier delivery escalation that restores the previous foreground). The only hard refusal is automated typing into password fields. extremePatterns adds non-blocking warning notes.

Loop: screen_observe (AX/UIA index tree, native screenshot read, or vision observer) → act via element index or window-local screenshot pixels → auto-escalated delivery → observe again to verify.

Install: install cua-driver, then git clone https://github.com/orangeofcarl0-sys/dsh-computer-use.git && ./install.sh (set DSH_HOME on Windows/Linux). Config defaults: ttlMs: 60000, deliveryMode: auto, extremePatterns: [] — see the Chinese section above for the full table.

Derived from 988hj7tczd-oss/dsh-computer-use (MIT); see Acknowledgements.

出处与致谢

原仓库（代码基座）

- 988hj7tczd-oss/dsh-computer-use @ 07477f4（MIT）——本项目的直接前身。按 MIT 派生后独立演进：安全姿态、投递管线、观测几何均与本仓库自有路线重写，与上游互不合并；原始问题反馈（#7 resolveBin、#8 hotkey 通道）已提回上游跟踪。

运行时底座
- trycua/cua（MIT）——cua-driver 是本插件消费的跨平台驱动。“后台优先、升级梯子、foreground 是对观测失败的响应”的投递哲学与之同源；Windows 侧的三级链、bring_to_front 恢复语义、XAML hotkey 通道为本仓库在本机实测的自有实现。

设计思想借鉴（方法与验收，不含代码）

- Microsoft UFO² —— UIA∪视觉混合控制检测、GUI-API 混合执行的路线图输入；
- Agent-S（Simular，ICLR 2025）—— ACI（辅助功能树 + set-of-marks）的 grounding 兜底思路，列入后续 roadmap；
- OSWorld / Windows Agent Arena —— 执行式 oracle 回归验证方法论；
- Anthropic / OpenAI CUA / Gemini computer use —— 截图循环与原子动作空间的参照系；
- ZCode 官方 computer-use 插件 —— action receipt / 观察版本化契约的重放安全设计参照。

除原仓库派生部分外，本项目不含上述项目的代码；借鉴限于思想与验收方法层面。