English

dsh-computer-use-win

给 DeepSeek Harness 装上 Windows 电脑操控能力——MCP stdio 服务器 + PowerShell/UIA 桌面引擎，22 个工具让 agent 能看（UIA 无障碍树、窗口裁剪截图、OCR 词框）也能做（鼠标、键盘、UIA 语义动作、窗口管理）真实的 Windows 桌面应用。

通过 DSH 内置的 @deepseek-ai/dsh-mcp-client 桥接，不改 DSH 本体，零运行时依赖。

① 文件资源管理器：find 定位 + 语义 invoke 选中文件（状态栏"选中 1 个项目"）	② type_text 写入真实文档（剪贴板路径，verifyValue 回读）	③ UWP 计算器：find 定位按钮 + 语义 Invoke 点击（25×4=100）

特性

• 文本优先的观察——UIA 无障碍树三视图（control/content/raw）；按 name/automationId/类名/值找控件，不靠猜像素。元素 id 用 UIA RuntimeId（UI 刷新后仍稳定，过期报 stale 而非点错地方）。
• 三级截图链——PrintWindow（非前台窗口也能抓）→ WGC（Windows.Graphics.Capture，DirectComposition/被遮挡窗口）→ 屏幕区域兜底（带 occludedPossible 标记）。窗口裁剪 + 降采样 + imageScale/origin 坐标映射，PNG 30 分钟自动清理。
• 三条输入路径，诚实上报——语义（UIA pattern，不碰鼠标）/ 前台（SetCursorPos + SendInput + 剪贴板 / KEYEVENTF_UNICODE）/ 后台（PostMessage 直进窗口消息队列，不抢前台；投递未验证，如实 verified:false——Chromium/Electron/WinUI 会静默丢合成消息，工具会明说）。
• UIA 盲区 OCR 回退——Windows.Media.Ocr（csc 编译的 C# WinRT 助手）；返回文字 + 逐词屏幕坐标词框，query 命中后自动回查匹配词下的控件（ControlFromPoint）。
• 内置安全机制
  • 坐标 homing——观察后窗口被移动，点击自动补偿并回报 homed:{dx,dy}
  • 急停 failsafe——物理鼠标停屏幕角落 500ms，所有输入被拒（EMERGENCY STOP），只有人把鼠标移开才恢复
  • identity guard——按 windowTitle 操作时窗口 HWND/PID 变了就拒绝（identity_changed）
  • 前台校验——输入 fail-closed：目标窗口不是真前台就直接报错，绝不打进别的窗口
  • Win 键黑名单——Win+R/X/L/S 类组合按设计拦截
• 持久化后端——一个常驻 PowerShell 进程 + JSON 行协议，热态延迟 6–100ms（首次 ~500ms 冷启动）；C# P/Invoke 助手按 hash 编译成缓存 DLL，重启免重编。

安装

# 从 npm（推荐）
dsh plugin --profile web add dsh-computer-use-win

# 从 GitHub（--profile 指定装进哪个 profile）
dsh plugin --profile web add github:Yu-tao-Li/dsh-computer-use-win
# 或在 DSH 设置的插件市场（dshmarket）搜索 dsh-computer-use-win

重启 dsh web，工具以 mcp__wincu__windows_computer_use_* 出现。

bundle 在启动时通过所在 profile 的 package.json 解析已安装包中的 server.mjs，因此适用于任意 profile / $DSH_HOME，也兼容 pnpm 布局，无硬编码路径。同一 profile 只保留一个 serverName: wincu 行。

DSH Desktop 的 process.execPath 指向 Electron 可执行程序。自 0.2.4 起，bundle 为 MCP 子进程显式设置 ELECTRON_RUN_AS_NODE=1，让服务以 Node 模式运行；普通 Node 启动同样适用。自定义 Electron 构建需启用 runAsNode fuse。此前为 #13 添加过完整用户配置覆盖的用户，升级后应移除该专用覆盖，再检查 health，使新版默认配置生效。

工具清单（22 个，前缀 mcp__wincu__）

所有工具都支持可选窗口定位（windowTitle 子串 / processId / nativeWindowHandle）+ activate: true；不指定 = 当前前台窗口。activate 在影响结果的路径上都会生效（输入类、坐标点击/滚动、ocr 截屏、move_window 等）；close_window 忽略它（WM_CLOSE 后台即可），activate_window 恒定激活。各工具的确切语义见 docs/wiki/mcp-tools.md。

架构

DSH agent
   │  模型看到 mcp__wincu__windows_computer_use_* 工具
   ▼
@deepseek-ai/dsh-mcp-client   ← DSH 内置桥接（官方 MCP SDK StdioClientTransport）
   │  JSON-RPC 2.0 over stdio（按行分帧）
   ▼
mcp/server.mjs                ← 本仓库：MCP 服务器（Node ≥22，零依赖）
   │  保活一个持久化后端；JSON 行协议
   ▼
scripts/windows-uia.ps1       ← 本仓库：桌面引擎（PowerShell 5.1 兼容）
   ├─ UI Automation 程序集        → 无障碍树
   ├─ user32 P/Invoke（C# 缓存 DLL）→ 鼠标/键盘/窗口操作
   ├─ Windows.Media.Ocr（C# WinRT）→ OCR
   └─ Windows.Graphics.Capture   → WGC 窗口捕获

安全与限制

• 动作是真实的——敏感操作前让 agent 先 snapshot；重要窗口用 windowTitle 明确限定。
• WinUI / Chromium / Electron 会丢弃 PostMessage 合成输入（verified:false 是诚实上报，不是成功）。这类目标走前台/剪贴板路径。
• 提权窗口（UAC/管理员程序）UIA 与合成输入都被 Windows 拦截，读不到也点不了。
• 坐标以物理像素为准（显式 Per-Monitor V2 DPI）。
• OCR 对 CJK 按字符给词框（引擎特性），点选足够用。
• 仅支持 Windows。

开发

mcp/server.mjs          MCP stdio 服务器 + 持久化后端管理
scripts/windows-uia.ps1 桌面引擎（one-shot 与 -Persistent 双模式）
test/                   self-test / MCP 协议 / Notepad E2E / 功能综合 / 延迟基准
docs/wiki/              上游架构文档（见 THIRD_PARTY.md）
docs/dev-notes.md       设计原理、踩坑记录、性能数据、测试记录

npm ci                             # 安装仅用于测试的 Electron / MCP SDK / YAML 依赖
node mcp/server.mjs --self-test     # 全栈自检（仅 Windows）
node test/mcp-test.mjs              # initialize → tools/list → tools/call
node test/profile-resolution.mjs    # DSH profile node_modules 路径回归测试
node test/bundle-startup.mjs        # 实际 bundle 的 Node / Electron 启动回归
node test/notepad-e2e.mjs           # 真实输入端到端（会开记事本）

npm test 运行自检、MCP 协议、profile 路径、Node/Electron bundle 启动、worker 生命周期、激活取消、窗口枚举/坐标缓存/参数校验及输入错误回归测试。每项测试使用独立进程和临时目录，日志与自检截图留在输出所示目录；不发送物理输入，也不修改已安装的 DSH profile。bundle 启动回归使用确定性的 PowerShell 协议 fixture；输入和窗口移动场景使用模拟接口。自检和只读窗口测试验证真实桌面后端。

默认使用 Windows PowerShell 5.1；可设置 $env:WINDOWS_CU_POWERSHELL = (Get-Command pwsh).Source 后运行 npm test 验证 PowerShell 7。CI（.github/workflows/ci.yml）在每次 push/PR 时分别测试这两种运行时。

许可

MIT，见 LICENSE。本项目是 cgissing/windows-computer-use（MIT）的衍生作品，上游版权声明保留于 THIRD_PARTY.md。