前言¶
在 DeepSeek Harness（DSH）里做「电脑使用」类智能体时，常见做法是拼若干零散脚本：读屏幕、点控件、等窗口、截个图。每换一台机器或一种界面技术，就要再对接一层。@wobuxcm/dsh-win-tools 把 Windows 侧能力收进一个自带运行时的宿主插件：无障碍树引用、SendInput 坐标操作、GDI 截图、浏览器 DOM、剪贴板、进程内等待和操作员急停，都通过统一的 pc_* 工具暴露给 DSH。下面按「是什么 → 能做什么 → 怎么装 → 怎么用 → 注意点」介绍。
这是什么¶
- 名称：
@wobuxcm/dsh-win-tools（npm 包名，GitHub：wobuxcm/dsh-win-tools） - 维护：仓库由 wobuxcm 发布；
package.json中 author 为 cjl15 - 分类：客户端（SkillHub 目录归类）
- 定位：面向 DSH 的 Windows 桌面控制插件，自包含，README 写明无其它插件依赖；当前版本 0.2.3，要求 Node.js ≥ 20
- 平台：仅 Windows x64（SendInput、GDI、随包二进制均为 Windows 实现）
插件在 DSH profile 里作为 bundle 加载后，智能体可通过 Cordis 调用的 15 个 pc_* 工具操作本机，无需再单独部署无障碍代理栈（随包含 agent-desktop-win32-x64.exe 等）。
核心功能¶
十五个 pc_* 工具¶
| 工具 | 作用 |
|---|---|
pc_status |
无障碍桥接健康、平台、权限、CLI 版本 |
pc_snapshot |
读无障碍树，返回 @ref；支持 surface / waitFor / root / includeBounds |
pc_find |
按 role/name/value/text 搜索元素（比全量快照轻） |
pc_read |
按 @ref 读单个属性或状态（text/value/bounds/visible 等） |
pc_act |
按 ref 执行无障碍动作，或按坐标注入鼠标/键盘（自绘界面） |
pc_key |
按键组合（SendInput，Unicode 安全） |
pc_screen |
GDI 截图，返回 PNG 路径并作为图片附件；annotate: true 可叠无障碍框与编号 |
pc_display |
显示器布局（物理像素）与 DPI |
pc_window |
列举/聚焦窗口 |
pc_browser |
浏览器 DOM：title/text/table/links/click/type/shot |
pc_wait |
进程内轮询：窗口标题 / 像素 / 区域比例 / 画面变化，可附带动作 |
pc_app |
应用列举/启动/关闭/缩放/最小化/最大化/还原 |
pc_clipboard |
读写文本剪贴板 |
pc_notify |
托盘气泡通知 |
pc_pause |
操作员急停开关（pause/resume/status） |
典型工作流可以是：先 pc_status 确认桥接正常，用 pc_snapshot 或 pc_find 拿 @ref，pc_read 核对状态，再用 pc_act / pc_key 操作；需要视觉确认时配合 pc_screen；跨应用等待用 pc_wait；浏览器内任务走 pc_browser（需额外安装 playwright-core 与本机 Edge/Chrome）。
安全与可观测¶
README 把安全写得很具体，适合在生产机器上评估：
- 急停（唯一开关）：全局热键
Ctrl+Alt+Shift+F12切换%DSH_HOME%/cua.stop；文件存在时，所有写操作（pc_act、pc_key、pc_windowfocus、pc_app、pc_wait）返回PAUSED_BY_USER。 - 黑名单：点击/按键前检查目标点与前台窗口标题，命中「支付/充值/购买/授权/扫码/付款/收银/转账/下单/结算/微信支付/支付宝」等关键词时返回
BLOCKED_KEYWORD。 - 屏幕活动指示：常驻置顶小条，AI 动键盘鼠标时显示「AI is operating this PC」，暂停时变灰；点击穿透、不抢焦点，5 秒无动作自动隐藏。设
PC_INDICATOR=0可关闭。 - 日志：
%DSH_HOME%/win-tools.log（JSONL），每次调用一条，排查问题先看这里。
环境变量可覆盖部分路径：PC_AGENT_BIN、PC_CUA_DIR、PC_BROWSER_JS、PC_NODE_BIN。
安装与启用¶
官方方式是把插件装进 DSH 使用的 profile，并在 package.json 里声明 bundle（不要用凭名称拼装的 dsh plugin add github:... 代替下列步骤）。
- 在 profile 目录安装 npm 包：
npm i @wobuxcm/dsh-win-tools
- 在同一 profile 的
package.json中加入 bundles：
"dsh": { "profile": { "bundles": ["@wobuxcm/dsh-win-tools"] } }
源码开发时可在 package.json 里写 link:<插件源码目录>，或用 junction 指到本地目录：
New-Item -ItemType Junction -Path "<profile>\node_modules\@wobuxcm\dsh-win-tools" -Target "<插件源码目录>"
启用后，DSH 会按 bundle 配置加载插件；插件以当前 dsh 进程的权限运行，安装前建议阅读仓库源码、LICENSE 与 THIRD-PARTY-NOTICES.md（随包含 MIT 自研代码与 Apache-2.0 的 agent-desktop 二进制等声明）。
若要用 pc_browser，还需在 profile 中安装可选依赖：
npm i playwright-core
典型用法与踩坑¶
以下用法逻辑来自 README「使用备注」，可直接指导智能体编排。
无障碍 ref 与窗口 ID¶
@ref会过期：界面变化后旧 ref 返回STALE_REF，应重新pc_snapshot，不要对同一 ref 盲目重试。pc_window的 id：HWND（如1575036）与cliId（w-1575036）均可传给pc_snapshot/pc_find。- 移动光标的动作：
hover/focus默认可能被 headless 策略拒绝（POLICY_DENIED），需加headed: true；坐标点击走 SendInput，不受此限。 - 坐标是物理像素：先
pc_display看dpi；例如 200% 缩放（dpi 192）时，逻辑坐标需按 DPI 换算。
等待、浏览器与通知¶
pc_wait：一次只等一个条件；image_changed必须给rect，整屏轮询开销大；急停会打断正在等待的调用。pc_browser：依赖playwright-core与本机浏览器；登录态可用--profile，复用已开浏览器可用--cdp。pc_notify：气泡展示约阻塞 4 秒，不宜在循环里 await。
急停与指示灯¶
- 急停即
%DSH_HOME%/cua.stop文件是否存在；热键只是切换该文件。 - 指示灯由独立 PowerShell（
bin/indicator.ps1）根据%DSH_HOME%/cua.active的 mtime 亮灭，写操作只 touch 文件，无 IPC。
适用场景与限制¶
适合：在 Windows 工作站上跑 DSH，需要智能体稳定操作原生 UI、截图、窗口与应用、轻度浏览器自动化，且希望自带运行时、少拼依赖的开发者。
不适合或需额外条件：
- 非 Windows 或 32 位环境。
- 重度浏览器自动化未装
playwright-core/ 无 Edge/Chrome 时，pc_browser不可用。 pc_wait的image_changed未指定rect时不应整屏滥用。
DSH 生态强调「一切皆插件」；SkillHub 目录是社区站点，与 DeepSeek / 幻方无官方从属关系。选用本插件时，除功能外应一并评估黑名单、急停与日志是否符合你的合规与运维习惯。
结尾¶
@wobuxcm/dsh-win-tools 把 Windows 桌面控制的常见能力收成 15 个 pc_* 工具，并自带无障碍桥接与安全开关，适合作为 DSH 在 Windows 上的客户端自动化底座。更多细节与 CHANGELOG 见仓库 README。
- 目录页：https://www.skillhub.cn/plugins/wobuxcm/dsh-win-tools
- GitHub：https://github.com/wobuxcm/dsh-win-tools
