前言¶
DeepSeek Harness（DSH）里的智能体若要操作本机 GUI，常见做法是装上游的 agent skill，让模型按文档里的 snapshot → act → verify 循环走。Vercel Labs 的 agent-desktop CLI 通过系统无障碍树读写界面：每次返回带稳定 @ref 的 JSON 快照，智能体对 ref 执行动作后再快照校验，不依赖像素匹配和坐标。DSH 可以直接扫描 skill 目录加载 SKILL.md，但在 macOS 上 Harness 的 Bash 工具处于文件沙箱，无法执行 /bin/ps；而 agent-desktop 的 list-apps、带 --app 的过滤、launch、close-app 等都会用 ps 建应用清单，在 Bash 里会报 ps: Operation not permitted。下面介绍社区插件 dsh-agent-desktop（维护者 dogxxgod，分类为模型推理 / computer-use），它从 Host 进程调用 CLI（不受 Bash 沙箱限制），并把 skill 里的操作规则注入系统提示，与单独安装 skill 可以并存。
这是什么¶
dsh-agent-desktop 是 DSH 的 Host 插件 bundle：把本机已安装的 agent-desktop CLI 封装成一组原生 desktop_* 工具，供 Harness 智能体调用。插件版本 1.0.0，要求 DSH >= 0.2.1-rc.5（README 写明在 macOS 26.7.1 arm64 上与 0.2.1-rc.5 联调），CLI 兼容 agent-desktop 1.1.0（JSON envelope version: 2.6）。Node 引擎为 ^22.19.0 || >=24.0.0（Harness 自带运行时，无需另装 Node）。许可证 MIT，源码与说明见 GitHub，社区目录页：skillhub.cn/plugins/dogxxgod/dsh-agent-desktop（独立社区站点，与 DeepSeek / 幻方无官方从属关系）。
核心功能¶
插件不改变 agent-desktop 的语义，只是把 CLI 子命令映射为工具，统一返回 CLI 的 JSON envelope（ok 加 data 或 error）；命令失败不会转成工具异常，由模型按返回内容处理。
| 工具 | 对应 CLI | 用途 |
|---|---|---|
desktop_status |
status |
平台、权限、CLI 版本、状态目录、支持能力；应最先调用 |
desktop_list_windows |
list-windows |
可见窗口及 w-… id |
desktop_list_apps |
list-apps |
运行中的 GUI 应用 |
desktop_snapshot |
snapshot |
无障碍树与 @ref |
desktop_find |
find |
按 role/name/text 等匹配元素 |
desktop_get |
get |
读取 ref 属性 |
desktop_click |
click 等 |
点击 ref |
desktop_type |
type |
向 ref 输入文本 |
desktop_press |
press |
按键组合 |
desktop_scroll |
scroll |
滚动 |
desktop_screenshot |
screenshot |
窗口/显示器 PNG |
desktop_run |
任意命令 | launch、剪贴板、wait、session、batch 等剩余能力 |
可选配置通过 profile 的 cordis.patch.yml 覆盖插件行（后层替换整个 config）：
| 字段 | 默认 | 含义 |
|---|---|---|
binaryPath |
agent-desktop |
PATH 上的命令名或绝对路径 |
stateHome |
""（CLI 默认 ~/.agent-desktop） |
设置 AGENT_DESKTOP_HOME |
timeoutMs |
60000 |
单次 CLI 默认超时；工具可传 timeout_ms |
promptSection |
true |
是否注入桌面控制规则到系统提示 |
安装与启用¶
安装前需满足：DSH 版本、agent-desktop CLI、以及 macOS 上的无障碍（及可选录屏）授权。插件本身是本地 bundle，无构建步骤、无 install 脚本、无额外 npm 依赖。
1. 安装 agent-desktop CLI¶
npm install -g agent-desktop
agent-desktop version # {"version":"2.6","ok":true,...}
若二进制不在 PATH，在配置里设置 binaryPath。macOS 权限可执行：
agent-desktop permissions --guide
向启动 Harness 的应用（如 DeepSeek Harness.app）授予辅助功能；需要截图时再授予屏幕录制。desktop_status 会报告这两项状态。
2. 下载并注册 bundle¶
官方支持路径是 Harness 插件管理器，将 release 解压目录链入当前 profile。以 v1.0.0 为例（macOS）：
curl -L -o dsh-agent-desktop-1.0.0.zip \
https://codeload.github.com/dogxxgod/dsh-agent-desktop/zip/refs/tags/v1.0.0
unzip -q dsh-agent-desktop-1.0.0.zip -d ~/work
解压后应得到含 package.json 的目录（例如 ~/work/dsh-agent-desktop-1.0.0）。在 Harness Plugins 页使用 Install bundle / Install from folder（文案随版本略有不同），选中该文件夹；或让智能体调用同等 Host 能力，例如：
用 plugin_manager 把
/absolute/path/to/dsh-agent-desktop-1.0.0安装为 bundle
管理器会把 dsh-agent-desktop 写入 profile 的 dsh.profile.bundles 并激活 agent-desktop host 行。
3. 重启并验证¶
若提示 restart-required，重启 Harness 后执行 desktop_status，工具列表中应出现 desktop_*。
可选覆盖配置示例：
- id: agent-desktop
config:
binaryPath: /Users/you/.local/bin/agent-desktop
stateHome: /Users/you/.agent-desktop
timeoutMs: 90000
promptSection: true
升级时下载新 tag 的 ZIP（URL 中把 v1.0.0 换成新版本），解压覆盖原目录或注册新目录；bundle 为链接安装，重启 Harness 即可生效，无需重复注册。卸载在 Plugins 页或 plugin_manager remove_bundle 后重启；CLI 与状态目录可按 README 自行删除。
典型用法¶
工作流与上游 agent-desktop 一致，由模型在工具层完成循环：
- 调用
desktop_status确认 CLI、权限与状态目录。 - 用
desktop_list_apps/desktop_list_windows或desktop_run的launch定位目标应用。 desktop_snapshot获取带@ref的树；需要时用desktop_find缩小范围。desktop_click、desktop_type、desktop_press、desktop_scroll等对 ref 操作。- 再次
desktop_snapshot或desktop_get校验结果；截图用desktop_screenshot。
插件在 promptSection: true 时会注入 snapshot → act → verify、ref 生命周期、重试策略等规则，即使未单独安装 filesystem skill 也能按同一套约定操作。
适用场景与注意¶
适合已在 DSH >= 0.2.1-rc.5 上开发 computer-use / 桌面自动化 智能体、并愿意在本机安装 agent-desktop 的开发者。README 在 macOS 上给出了权限与联调环境；Windows / Linux 权限模型见上游文档。
安全与权限：CLI 由 Host 进程启动，权限等同于运行 Harness 的用户与启动 Harness 的应用；安装前应阅读仓库源码与 MIT 许可证，确认符合你的部署策略。Bash 工具仍保持沙箱，仅 desktop 相关能力走 Host。
社区目录当前星标为 0，不代表功能完整性；以 README 与 release 1.0.0 为准。
结尾¶
dsh-agent-desktop 补上 DSH Bash 沙箱与 agent-desktop 对 ps 依赖之间的缺口，把 Vercel Labs 的无障碍树桌面控制 loop 变成 Harness 一等公民工具。需要详情与更新时查阅 GitHub 仓库 与 SkillHub 目录页。
