dsh-windows-mcp-lite

dsh plugin --profile web add dsh-windows-mcp-lite

dsh-windows-mcp-lite

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

[English](README.md) | 中文

它挂载 DSH 本体自带的 MCP 客户端桥，用 stdio 指向上游 Windows-MCP 服务器。整个集成就只有 [cordis.patch.yml](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](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](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 指向 `@deepse

…(truncated)