前言¶

在 DSH 或 MCP 客户端里做 Windows 桌面自动化，常见路线只有两类：纯视觉（截图 + 坐标点击，慢且脆弱），或前台接管（动真光标、抢焦点，人必须停下手头工作）。对需要边写代码边让智能体操作本机应用的场景，后者几乎不可用。

下面介绍社区插件 tandem-agent-mouse（维护者 JiamingShi-JsPhys，分类：工作流）。它以 MCP 服务形式在 Windows 10/11 上提供桌面自动化：识别层以 UIA 为主而非像素猜测；默认 A 模式在后台读窗口、截图、批量操作，结构性禁止动用户光标与焦点；可选 B 模式在隐藏第二桌面上跑智能体应用，通过角落投影窗口观看，输入仅靠窗口消息注入。当前版本为 1.0.0b1（beta），README 标明 API 仍可能变动，升级前应固定版本并阅读 CHANGELOG。

这是什么¶

tandem-agent-mouse 是一个面向 Windows 的 MCP Server，让 Claude 或其他 MCP 客户端能列举窗口、读取 UIA 无障碍树、后台截图，并执行点击与输入类操作。与「全盘 SendInput」类方案不同，项目在 guard.py 中对违禁 Win32 API 做_FETCH 级拦截（缺失函数指针即 ForegroundViolation），红线由代码执行而非提示词承诺。

• 维护者：JiamingShi-JsPhys
• 平台：Windows 10/11（README 字段测试环境含 Windows 11 26200）
• 协议：stdio JSON-RPC MCP，python -m tandem_agent_mouse serve 启动
• DSH：package.json 中通过 dsh.bundle.patch 挂载 cordis.patch.yml，可作为 DSH 生态中的工作流类插件使用；社区目录页见文末链接。

核心功能¶

A 模式（默认）：用户桌面上的后台自动化¶

A 模式不切换输入桌面、不调用 SetForegroundWindow / SetCursorPos / SendInput 等。智能体在用户当前桌面上：

1. 用 UIA CacheRequest 做全树扫描，元素以统一 JSON 格式返回（类型、名称、矩形、可执行 actions 等）。
2. 截图链路为：UIA →（失败时）唤醒探测与重试 → PrintWindow(PW_RENDERFULLCONTENT) →（仍空白时）Windows Graphics Capture（需可选依赖 winsdk）→ 明确报错。
3. 通过 background_act 等工具批量 invoke / toggle / set_value，仅返回 diff。

若某操作在后台无法完成（例如部分 Chromium 控件拒绝消息点击），服务返回 needs_foreground，由用户决定是否切换到 B 模式；服务不会自行前台化。

B 模式（可选）：隐藏桌面 + 角落投影¶

B 模式在隐藏桌面上创建沙箱进程树（CREATE_SUSPENDED + KILL_ON_JOB_CLOSE Job Object），保证关闭投影窗、set_mode A、优雅退出或强杀服务时整棵进程树被内核清理，无孤儿进程。

• 用户通过置顶角落投影窗（约 0.5s/帧）观看沙箱内应用。
• 输入仅为 PostMessage 注入，沙箱内绘制虚拟光标；README 实测表明 SendInput 会进 INPUT 桌面，从沙箱线程会 ACCESS_DENIED，故不用真光标。
• 用户点击投影区域可映射回沙箱坐标；关闭投影即终止沙箱。

MCP 工具面¶

README 将工具分为两组，无需记忆 A/B 字母：

（完整工具表以仓库 README 为准，资料片段在 background_act 处截断。）

安装与启用¶

以下命令摘自 GitHub README，安装前请在本机检查源码与许可证，并确认 MCP 服务将以当前 DSH / Python 进程权限运行。

在项目目录中安装可编辑包与可选捕获依赖：

cd "Tandem Agent Mouse"
uv pip install --system -e .
# 基础能力含 PrintWindow；Electron 空白帧回退需 WGC 时：
uv pip install --system winsdk

运行测试（README 标明 32 项测试）：

python -m pytest tests/ -q

启动 stdio MCP 服务：

python -m tandem_agent_mouse serve

在 Claude Code、Claude Desktop 或其他 MCP 客户端中注册（配置项与 README 一致）：

{
  "mcpServers": {
    "tandem-agent-mouse": {
      "command": "python",
      "args": ["-m", "tandem_agent_mouse", "serve"]
    }
  }
}

DSH 用户安装插件 bundle 时，以 SkillHub 目录页与仓库内 .dsh-plugin/、cordis.patch.yml 说明为准；勿凭仓库名自行拼接未在文档出现的 dsh plugin add 命令。

典型用法¶

先用自然语言驱动客户端，由 MCP 调用对应工具。README 中的可复现流程如下。

A 模式（后台、不打断用户）：

"Write something in Notepad"  -> observe 找到编辑区 -> act set_value
"Show me this window"         -> screenshot 返回图像 + 网格 + click_at 用法说明

B 模式（沙箱 + 投影）：

sandbox_mode "sandbox" -> 出现 "Tandem Agent Mouse Sandbox" 角落窗口
sandbox_launch Edge    -> Edge 在隐藏桌面打开，投影中可见
sandbox_click/type     -> 消息注入完成搜索、导航等
sandbox_human          -> 按节奏类人输入；虚拟光标仅在投影窗内绘制
关闭投影窗口           -> 沙箱拆除，无残留进程

README 记载的一次现场验证路径：沙箱内 Edge → bilibili → 搜索并打开播放页，全程用户光标未移动、未抢焦点。

适用场景与注意¶

适合谁

• 在 Windows 上让 MCP 智能体读写 Office、记事本、浏览器等窗口，且要求工作时不被抢鼠标。
• 需要 UIA 结构化元素而非纯坐标点选的前台自动化。
• 必须在隔离桌面跑高风险或全屏交互时，用 B 模式观看并手动把关。

务必注意

1. Beta 软件：1.0.0b1，生产环境请锁定版本。
2. 仅 Windows：依赖 Win32、UIA、桌面与 Job Object 等 API。
3. 权限：MCP 服务权限即运行它的用户权限；安装与启用前审查源码与许可证。
4. 失败语义：后台做不了就报 needs_foreground，不要期待静默降级到前台劫持。
5. 社区目录：SkillHub 为独立插件站点，与 DeepSeek / 幻方无官方从属关系，非「官方应用商店」。

结尾¶

tandem-agent-mouse 把 Windows 桌面自动化收成第三条路：UIA 识别 + 后台批处理 + 可选沙箱投影，并在 guard.py 里用硬约束保证「默认不碰用户桌面状态」。若你的工作流落在 DSH「一切皆插件」体系里，可从目录页查看条目说明，再按 README 安装 MCP 服务并接入客户端。

• 目录页：https://www.skillhub.cn/plugins/JiamingShi-JsPhys/tandem-agent-mouse
• 源码与文档：https://github.com/JiamingShi-JsPhys/tandem-agent-mouse