Windows 桌面控制桥 sheilacraig/dsh-windows-mcp-lite

dsh-windows-mcp-lite

从 DeepSeek Harness 到 CursorTouch/Windows-MCP 的纯配置型桥。

它挂载 DSH 本体自带的 MCP 客户端桥，用 stdio 指向上游 Windows-MCP 服务器。整个集成就只有 cordis.patch.yml 一个文件——约 25 行，没有 JavaScript，装之前你能整屏读完。

DSH agent
└─ mcp__windows__Snapshot / Click / Type / ...
└─ @deepseek-ai/dsh-mcp-client （DSH 自带） └─ uvx windows-mcp@0.8.8 serve （stdio 子进程） └─ 你的桌面：UIA 树 / Win32 输入 / 屏幕采集

它刻意不做的事

这是设计取舍，不是"功能缺失清单"：

- 没有宿主插件。 没有 index.js，我们没有任何代码跑在你的 harness 进程里。
- 没有 web 路由。 不新增任何 HTTP 端点，因此不新增未鉴权的攻击面，也不会给你多一个"必须绑回环"的理由。
- 没有状态文件。 不写 ~/.dsh/...state.json，不占浏览器存储。
- 没有会改你 profile 的安装器。 npm run prewarm 在你自己的终端里装好并验证上游服务器，绝不替你改 profile patch。
- 没有运行时依赖、没有构建步骤。 dependencies 为空，不需要编译，也不需要你授予 allowBuilds。
- 不含针对某台机器的绝对路径。 桥从 PATH 调 uvx；仓库里的测试会在任何机器相关路径漏进发布文件时让构建失败。
- 没有 peerDependencies。 那一行只是点名 @deepseek-ai/dsh-mcp-client，从不 import 它，而 DSH 会从自己的安装里解析随附包。这与 DSH 官方的 templates/mcp 组合包形态一致——它同样不声明任何 peer。声明 peer 会变成一道硬性激活门禁，而其 SemVer 预发布规则会静默拒掉合法宿主；宿主范围改由 engines.dsh 声明，供市场卡片展示。
- 没有 screenshots.json。 没有界面可拍。给一个配置文件配上"截屏"是装饰，不是证据；市场会回退到它能抽到的内容。

如果你要的是应用内依赖安装器、默认关闭的 Computer Use 开关、或 doctor 诊断工具，这个生态里别的插件提供了。这个插件用它们换的是"小到一屏能审完"——对一个要把键盘、鼠标和屏幕交出去的插件来说，这一点比平时更值钱。

前置条件

- Windows 10 / 11。 上游服务器只支持 Windows。
- 带内置 MCP 客户端桥的 DeepSeek Harness。 声明范围 >=0.2.0-rc.1 <0.3.0-0；作者在 0.2.0-rc.2（桌面版）上实测通过。声明的是范围，实测的是那一个版本，两者别混。
- 运行 DSH 的那个进程的 PATH 上要有 uv。 uvx 负责拉起上游服务器并为它建隔离环境。用官方安装脚本装过 uv 的话，这一条已经满足。
- 可选：支持图片输入的模型，这样 Screenshot 才会以真正的图片进入对话。不支持时桥会把它退化成文本诊断；Snapshot 返回纯文本，完全不依赖视觉。

安装

应用内：设置 → 插件 → 添加插件，填其中一种：

dsh-windows-mcp-lite # npm 包名 github:sheilacraig/dsh-windows-mcp-lite # GitHub 仓库 C:\path\to\a\local\checkout # 本地绝对路径

CLI 持有的 profile：

dsh plugin --profile <profile> add dsh-windows-mcp-lite

Electron 桌面版的 desktop profile 属于应用本身，请走应用的插件面板。

装完重启 DSH，让新的补丁层在启动时合成。

第一次启动最慢

uvx 第一次会为上游服务器建隔离环境，需要下载几十 MB 的 Python 依赖。慢网下这是好几分钟，而桥等初始连接的时间远不到那么久；依赖缓存好之后就很快了。

所以放到 harness 外面做，那里没有超时：

npm run prewarm

脚本会跑 uvx windows-mcp@0.8.8 serve --exclude-tools ...——与桥完全相同的 argv——对它说 initialize + tools/list，打印服务器身份、耗时和完整工具清单，然后退出。它拉起的正是桥将要拉起的同一个进程，所以这一步成功就说明 harness 那侧再没有要下载或要发现的东西。环境预热后，作者本机实测 initialize 在 2.1 秒内返回。

模型能拿到什么

16 个工具，名字形如 mcp__windows__<工具>。上游 0.8.8 公布 21 个；本插件默认排除 5 个（见「默认最小权限」）。

| 工具 | 作用 |
| Screenshot | 截屏，附光标位置与窗口列表 |
| Snapshot | 完整桌面状态：无障碍树、可交互元素、可滚动区域 |
| DisplayInventory | 显示器布局、工作区、DPI |
| Click、Move、Scroll | 鼠标输入，含显式拖拽 |
| Type、Shortcut | 键盘输入 |
| Wait、WaitFor | 固定等待，或轮询直到界面条件成立 |
| MultiSelect、MultiEdit | 批量选中 / 批量输入 |
| Clipboard | 读写剪贴板 |
| Notification | Windows 通知 |
| App | 启动应用、调整或聚焦窗口 |
| ControlStatus | 当前谁在控制桌面——上游不提供排除它的方式 |

验证

1. 先跑一次 npm run prewarm（见上），它同时验证服务器与钉住的版本。
2. 在 DSH 里让 agent 调 mcp__windows__DisplayInventory。它只读显示几何，不点不敲。
3. 再调 mcp__windows__Snapshot 拿无障碍树文本。

默认最小权限

--exclude-tools PowerShell,Registry,FileSystem,Process,Scrape —— 上游这 5 个工具默认关闭，因为 DeepSeek Harness 已经有一套受自身审批策略与沙箱约束的 shell、文件、注册表、进程能力。再开一份上游的等价物，等于给同样的能力多开一条完全没有这些控制的路径。

要改这套集合，就在你自己的 profile patch 里覆盖那一行（见下）。去掉 --exclude-tools 即恢复全部 21 个工具。

配置

所有默认值都在 cordis.patch.yml。要改，请在你自己的 profile里覆盖那一行——不要改装好的那份：

$DSH_HOME/profiles/<profile>/cordis.patch.yml
- id: windows-mcp-lite
config:
serverName: windows
transport: stdio
command: uvx
args: [windows-mcp@0.8.8, serve, --exclude-tools, "PowerShell,Registry,FileSystem,Process,Scrape,App"]
toolCallTimeoutMs: 120000
failOnStartupError: false
env:
ANONYMIZED_TELEMETRY: "false"
WINDOWS_MCP_DISABLE_FLASH: "1"

关于这个覆盖，有两点最容易让人踩坑：

- 补丁是整块替换 config，不是深合并。 你漏写的每个键都等于删掉它。serverName、transport 必填，stdio 形态下 command 必填，streamable-http 形态下 url 必填。
- serverName 决定所有工具名（mcp__<serverName>__<工具>）。改了它等于改掉整套工具名，并且会让 prompt 缓存前缀失效。

一个 profile 只能有一份 Windows-MCP 桥。 两行用同一个 serverName 会冲突，后加载的那行在加载时失败。启用本插件前，请先停用同一 profile 里其它的 Windows-MCP 插件。

想用预装好的解释器而不是 uvx？先 uv tool install windows-mcp，然后把 command 设为 windows-mcp、args 设为 [serve, --exclude-tools, ...]。想用常驻 HTTP 服务？把 transport 换成 streamable-http 并给 url——注意 HTTP 形态没有 env，遥测与闪框的设置就归启动那个服务的方式管了。

安全

装上它，等于把你的鼠标、键盘、剪贴板和屏幕交给一个以你自己权限运行的进程里的 agent。请按"交出这个桌面会话"来评估。

- stdio，不是监听端口。 桥启动的是管道连接的子进程，不绑任何端口。
- 默认最小权限，见上。
- 上游遥测默认关闭（上游默认向 PostHog 匿名上报）；同时关掉了那圈橙色截屏边框。
- Harness 的文件沙箱管不到它。 MCP 工具调用是普通工具调用，审批策略能拦；沙箱实现在 harness 自己的文件与 shell 工具里，不约束这个子进程。
- 控制权交还是尽力而为，不是边界。 上游允许真人通过明显移动物理鼠标或按 Ctrl+Alt+Shift+Backspace 夺回桌面；它已经启动的外部命令在夺权后仍会继续跑。
- 钉住上游版本。 windows-mcp@0.8.8 是固定版本，上游发版不会悄悄改变这座桥的行为。要升级就显式改这一行并重跑 npm run prewarm。
- 装之前请读 cordis.patch.yml。 那个文件就是插件本体，其余都是元数据、文档和测试。

排障

| 现象 | 原因与处理 |
| 工具调用返回 USER_CONTROL，或 ControlStatus 报 state: "user" | 上游把桌面优先给人，只有约 10 秒没有物理输入后才交给 agent。此刻控制权在你手里，wait_seconds 是它还在等的空闲时长。明显移动鼠标或按 Ctrl+Alt+Shift+Backspace 可以主动夺回控制权。ControlStatus 在其它调用全被拦下时仍然可用——工具被拒时先调它。 |
| 完全没有 mcp__windows__* 工具 | 桥没能拉起服务器。在终端里跑 npm run prewarm，它会以同样的原因失败并给出提示。最常见的原因是运行 DSH 的那个进程的 PATH 上没有 uvx：桌面快捷方式或编辑器带的 PATH 可能和你装 uv 的那个终端不一样。harness 日志里有 mcp-client(windows) 那一行。 |
| 升级后工具全变名字了 | 工具名是 mcp__<serverName>__<工具>。改 serverName，或者把钉住的上游版本换成一个工具名不同的版本，都会重命名整套工具。 |
| Screenshot 返回的是文本 | 当前模型不接受图片输入。改用 Snapshot：它抽的是无障碍树，不是像素。 |
| 所有桌面工具一起被拒 | 同一 profile 里有第二行 Windows-MCP 用了相同的 serverName，只有先加载的那行生效。停用另一个插件。 |

开发

npm install # 唯一的 devDependency：js-yaml，只给测试用
npm test # node --test，校验桥的各项不变量
npm run prewarm # 安装并验证上游服务器

npm test 会强制检查：有且只有一行 insert 指向 @deepseek-ai/dsh-mcp-client；serverName 符合工具名命名规则；args 里是钉住的 windows-mcp@x.y.z；排除清单与文档一致；工具数量与文档一致；以及任何发布文件里都不允许出现绝对路径或盘符。

卸载

在设置 → 插件里移除这个 bundle，或删掉 profile patch 里的那一行。停用 bundle 会连同整行配置一起撤掉。不会留残留：本插件不写任何文件。

许可与致谢

MIT —— 见 LICENSE。

- 真正干活的桌面自动化全部来自 CursorTouch/Windows-MCP（MIT），本仓库只负责接线。
- MCP 客户端桥属于 DeepSeek Harness，本仓库不分发它。
- 与 DeepSeek 官方及 Windows-MCP 作者均无隶属关系。