dsh-cua：DeepSeek Harness 的计算机控制插件

2026-10-04

前言¶

DeepSeek Harness（DSH）采用插件化架构。让智能体操作电脑是一个常见需求。dsh-cua 提供了这一能力。

是什么¶

这是一个计算机控制插件，由 cua-driver daemon（trycua）提供支持。它封装了 14 个模型工具，走 DSH 原生注册、审批面板和图片附件体系，不依赖 MCP。

工作方式¶

一次工具调用 = spawn 一次驱动 CLI（stdin 送 JSON、stdout 收 JSON），实际状态常驻本地 daemon 里。寻址优先级：1. 优先 element_token。像素坐标用于 canvas/视频等非 UIA 区域。非法参数组合在插件层直接拒绝，不会发出任何输入。

功能¶

• cua_status：驱动 daemon 是否在线；离线附启动指引
• cua_list_windows / cua_list_apps：顶层窗口清单（pid / window_id / 标题 / 边界）；运行中与已安装应用清单
• cua_window_state：指定窗口的无障碍元素树快照：结构化 elements（element_token/role/label/frame）+ Markdown 树 + 窗口截图
• cua_desktop_screenshot：主屏全屏截图（真实物理像素）
• cua_zoom：放大窗口截图的局部区域（小字号 / 密集控件）
• cua_verify_state：操作后断言验证：元素存在/启用/选中/值相等、窗口边界（容差 px）；结果三态 satisfied / unsatisfied / unknown，unknown 永不当作成功
• cua_click / cua_type_text / cua_press_key / cua_hotkey / cua_scroll：点击（左/右/中、双击三击）、输入文本、按键、组合键、滚动——目标可以是元素 token、窗口像素或桌面坐标
• cua_set_value：经无障碍 SetValue 直接给控件赋值（比逐字键入可靠，写入后回读校验）
• cua_bring_to_front：把窗口带到前台（后台投递路径通常用不到）

安装与启用¶

前置条件：一个带 profile 的 DSH 部署；驱动 daemon 在线。

dsh plugin --profile web add github:hfloveyy/dsh-cua

重启 dsh web 后验证：

dsh --profile web --dump-config

在对话里让 agent「列出当前所有窗口，截个图看看桌面上有什么」即为通。

配置¶

在 profile 的 cordis.patch.yml 按 id 覆盖：

- id: cua
  config:
    requireApproval: true   # 每个动作前弹审批面板（false 可关闭插件层审批）
    disabled: false         # true = 不注册任何工具
    timeoutMs: 15000        # 工具协作式超时（2000–120000）
    maxElements: 200        # 单次快照转发的元素上限（20–5000）
    maxRows: 120            # list_windows/list_apps 单次转发行数上限（10–1000）
    binDir: ""              # 自定义驱动二进制目录；留空按优先级解析

安全与限制¶

安全采用双层闸门。插件层：七个动作类工具经 tools/pre-execute 返回 ask 决策。驱动层：daemon 维护 permission mode（standard / bounded / unrestricted）、session 授权租约、capability manifest 与 revoke 命令。

已知限制：
- 插件自带二进制的平台：Windows x64；macOS 与 Linux 走全局驱动（上游 install.sh）。
- 多显示器暂只覆盖主屏（跟随上游当前版本行为）。
- 驱动的浏览器 CDP 工具组（browser_navigate / browser_click 等）与应用生命周期组（launch_app / invoke_menu）尚未注册。

结尾¶

dsh-cua 为 DSH 提供了元素级的计算机控制能力。适合需要智能体操作桌面应用的开发者。安装前请检查源码与许可证。