dsh-windows-mcp 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -4,7 +4,73 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2026-10-10
+## [0.2.1] - 2026-10-29
+
+### Added
+
+- **Settings page** (`lib/settings.js`, the `settings.section` slot): a new
+  **Settings → Desktop** entry whose page groups the knobs into
+  **Bridge** (`toolCallTimeoutMs`, screenshot scale/backend, flash overlay,
+  the excludable tools), **Updates** (check on boot, preferred mirror) and
+  **About** (version, repository, a **Star** button). Values are validated and
+  clamped, stored atomically in `$DSH_HOME/dsh-windows-mcp.settings.json`, and
+  bridge changes are written into the profile's bridge row with a backup; the
+  page reports when a restart is needed.
+- `preferredMirror`: the update check can pin a mirror while `auto` keeps the
+  measured ranking.
+- The settings entry now wears a monitor-and-cursor glyph instead of the
+  shell's gear: the `settings.section` slot has no icon field, so the icon is
+  painted as a `currentColor` mask on the settings nav row, matched by the
+  entry's own localized label.
+
+### Fixed
+
+- Reading the bridge row now treats a missing `WINDOWS_MCP_DISABLE_FLASH`
+  inside the machine-written block as "flash enabled", not as unknown.
+- `mirrorOrder` had a stray spacing glitch on its declaration line.
+## [0.2.0] - 2026-10-24
+
+### Added
+
+- **Windows-MCP version management** (`lib/updater.js`, `lib/installs.js`): the
+  plugin checks the mirrors for the newest stable `windows-mcp`, installs a
+  version **side by side** under `$DSH_HOME/dsh-windows-mcp/toolchain/<version>`
+  (each version its own `UV_TOOL_DIR`, so nothing is overwritten), rewrites the
+  bridge row to the freshly installed executable, and keeps the replaced version
+  so **Roll back** switches back to it without downloading anything. The check
+  result, active/previous version and the install history are persisted in
+  `$DSH_HOME/dsh-windows-mcp.versions.json`. Checks run on boot and are cached
+  for six hours.
+- **Fast-mirror selection for the Python dependency** (`lib/mirrors.js`,
+  `lib/pypi.js`): PyPI plus the USTC, Aliyun, Tencent Cloud, Huawei Cloud,
+  Nanjing University and TUNA mirrors are probed with a 96 KiB ranged read and
+  ranked by measured throughput; the install uses the fastest working mirror and
+  falls back to the next candidate on failure.
+- On the plugin page: running version, newest version, kept versions, the
+  measured mirror speed, and **Check for updates** / **Update to vX** / **Roll
+  back to vPrev** actions, with the streamed `uv` log.
+- `tools/update-e2e.mjs`, a maintainer harness that runs the real check, install,
+  activation and rollback against this machine's profile (never published).
+
+### Changed
+
+- `createPrepare` / the prepare route now install into the managed tool root
+  through `UV_TOOL_DIR`, support a chosen `--default-index` mirror, and resolve
+  the executable from the version that was installed.
+- `uv` installs set `UV_CONCURRENT_DOWNLOADS=4`, `UV_HTTP_RETRIES=3` and
+  `UV_HTTP_TIMEOUT=600`: at uv's default of eight parallel downloads the mirrors
+  answer HTTP 429 and the install fails.
+- The bridge-row writer, the doctor report and the `/state` payload all report
+  which side is live (`managed` vs the global `uv-tool` install).
+
+### Fixed
+
+- The PyPI index parser dropped files whose link carried a `#sha256=…` fragment
+  (every wheel on a real mirror), so the newest version looked missing.
+- The version pin regex stopped at YAML punctuation but not at the backtick used
+  in the written block's prose comment.
+
+## [0.1.0] - 2026-10-11
 
 ### Added
 

package/LICENSE

@@ -19,9 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-This plugin does not bundle Windows-MCP: at runtime it launches the upstream
-package `windows-mcp` (CursorTouch/Windows-MCP, MIT) and mounts the MCP client
-bridge that ships with DeepSeek Harness. Both remain under their own licenses.

package/README.md

@@ -1,5 +1,10 @@
 # dsh-windows-mcp
 
+**English** · [中文](https://github.com/helloHub1212/dsh-windows-mcp/blob/main/README.zh.md)
+
+[![npm version](https://img.shields.io/npm/v/dsh-windows-mcp.svg)](https://www.npmjs.com/package/dsh-windows-mcp)
+[![CI](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml)
+
 **Windows desktop automation for [DeepSeek Harness](https://github.com/sandbaseai/deepseek-harness-handbook)** — lets the DSH agent see your screen and drive your PC.
 
 This plugin connects [CursorTouch/Windows-MCP](https://github.com/CursorTouch/Windows-MCP) to DSH by mounting one loader row against the **MCP client bridge that already ships inside DeepSeek Harness**. There is no reimplemented protocol client and no second copy of the MCP SDK: the plugin is a *carrier bundle*, and everything you can do comes from the official bridge.
@@ -98,6 +103,30 @@ The block it writes is exactly the row documented under [Pin a local interpreter
 
 The page also shows the **Patch target**: the `cordis.patch.yml` a manual write would touch, which is the profile this host booted — including a `dsh --profile web` host. If this package sits in more than one profile and the host does not report which one it started, the plugin writes nothing and says so instead of guessing: set `DSH_WINDOWS_MCP_PROFILE=<profile name>` (or an absolute profile directory) for the process that runs DSH and retry.
 
+### Update Windows-MCP, and roll back
+
+The same page manages the upstream version, so an upgrade never means reinstalling the dependency by hand:
+
+- **It checks by itself.** On boot, and whenever the page asks, the plugin probes the PyPI mirrors, takes the fastest one that answers and reads its `windows-mcp` index. The result is cached for six hours in `$DSH_HOME/dsh-windows-mcp.versions.json`, so restarts do not hammer the network.
+- **Versions live side by side.** Every version is installed into its own tool root, `$DSH_HOME/dsh-windows-mcp/toolchain/<version>/windows-mcp`, through `UV_TOOL_DIR`. Activating a version only rewrites the bridge row (backed up, as above): no reinstall, and the previous version stays on disk.
+- **Update in one click.** **Update to vX** downloads that version from the fastest mirror that works, verifies the executable and its `dist-info`, then activates it — the panel names the running version and the mirror it came from.
+- **Roll back the same way.** **Roll back to vPrev** points the bridge back at the version the active one replaced; nothing is downloaded.
+
+Only the managed installs are touched: until you install one, the bridge keeps using the global `uv tool` installation, and the panel says which side is live (`uv-tool` vs `managed`).
+
+### Fast mirrors for the Python dependency
+
+The check measures all seven candidates — PyPI plus the USTC, Aliyun, Tencent Cloud, Huawei Cloud, Nanjing University and TUNA mirrors — with a 96 KiB ranged read, and ranks them by throughput. An install uses the fastest mirror that works and falls back to the next one when a mirror fails, with `UV_CONCURRENT_DOWNLOADS=4`, `UV_HTTP_RETRIES=3` and `UV_HTTP_TIMEOUT=600`, because mirrors rate-limit uv's default of eight parallel downloads (HTTP 429). A mirror that has blocked this network is ranked out instead of failing the install; the measured speed is shown per mirror in the panel.
+
+### Settings page and the star button
+
+Everything above, plus a few knobs that do not belong on a plugin card, lives in **Settings → Desktop** — a new entry in the settings sidebar, next to the other plugins' pages:
+
+- **Bridge** — `toolCallTimeoutMs`, the screenshot scale, the capture backend, upstream's flash overlay, and the three tools the bridge may exclude (`App`, `PowerShell`, `FileSystem`). These are written into the bridge row of your profile's `cordis.patch.yml` (timestamped backup first), so **they apply after DSH restarts**; the page states which row is in effect.
+- **Updates** — whether the plugin checks for a newer Windows-MCP on boot, and the mirror policy: `auto` keeps the measured ranking, an explicit mirror pins it, and the official index always stays as the last resort.
+- **About** — the plugin version, the repository link, and a **Star** button that opens the project on GitHub in a new tab.
+
+Saving is atomic (`$DSH_HOME/dsh-windows-mcp.settings.json`). A value out of range is clamped to its default and reported instead of being written silently, and a change that leaves the bridge row untouched does not rewrite the patch layer at all. **Revert** restores the defaults in the form.
 ## Verify
 
 ```text
@@ -293,12 +322,30 @@ Layout:
 
 ```text
 cordis.patch.yml      the integration: two insert rows
-lib/index.js          host half: windows_mcp_doctor + startup audit (no dependencies)
-test/plugin.test.mjs  patch composition + hostile-context tests
+lib/index.js          host half: routes + windows_mcp_doctor + startup audit (no dependencies)
+lib/dependency.js     dependency state, uv invocation, profile bridge-row writer
+lib/pypi.js           PyPI index parsing and version maths (pure functions)
+lib/mirrors.js        mirror candidates, ranged speed probe, ranking
+lib/installs.js       per-version tool roots and the versions state file
+lib/updater.js        version manager: check / install / activate / roll back
+lib/settings.js       user settings: validation, storage, bridge round-trip
+lib/client.js         web half: composer switch, plugin panel, settings page
+test/plugin.test.mjs  patch composition + hostile-context + panel tests
+test/update.test.mjs  version maths, mirror ranking, isolation and rollback state machine
+test/settings.test.mjs  settings validation, bridge round-trip, settings route
 scripts/dump-config.mjs  dev helper for composing against a scratch profile
 tools/                zero-dependency debug probes (not published to npm)
 ```
 
+To exercise the update path for real — real mirrors, real `uv`, real profile
+write — use the e2e harness:
+
+```powershell
+node tools/update-e2e.mjs --check          # probe the mirrors, read the newest stable version
+node tools/update-e2e.mjs --install 0.8.8  # download, activate, rewrite the bridge row
+node tools/update-e2e.mjs --rollback
+```
+
 Contributions are welcome; keep `lib/index.js` free of runtime dependencies and
 keep `apply()` throw-proof.
 

package/README.zh.md

@@ -1,5 +1,10 @@
 # dsh-windows-mcp
 
+[English](https://github.com/helloHub1212/dsh-windows-mcp/blob/main/README.md) · **中文**
+
+[![npm version](https://img.shields.io/npm/v/dsh-windows-mcp.svg)](https://www.npmjs.com/package/dsh-windows-mcp)
+[![CI](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml)
+
 **给 [DeepSeek Harness](https://github.com/sandbaseai/deepseek-harness-handbook) 接上 Windows 桌面自动化** —— 让 DSH 的 agent 能"看见"你的屏幕并操作你的电脑。
 
 本插件把 [CursorTouch/Windows-MCP](https://github.com/CursorTouch/Windows-MCP) 接到 DSH 上，做法是**挂载 DSH 本体自带的那座 MCP 客户端桥**：不重新实现协议客户端，也不重复打包 MCP SDK。插件本身是一个 *carrier bundle*（只有补丁、没有自己的服务），agent 能用的一切能力都来自官方那座桥。
@@ -94,6 +99,30 @@ Windows-MCP 本身是个 Python 程序，所以 **设置 → 插件 → dsh-wind
 
 面板上还会显示 **写入目标**：手动写入会落到哪个 `cordis.patch.yml`，也就是这个宿主启动的那个 profile（`dsh --profile web` 启动的 web 宿主同样适用）。如果本插件装在多个 profile 里、而宿主没有报告自己启动的是哪一个，插件**不会猜**：它什么都不写并直接说明——给运行 DSH 的进程设 `DSH_WINDOWS_MCP_PROFILE=<profile 名>`（或 profile 的绝对路径）再重试。
 
+### 更新 Windows-MCP，以及回退
+
+同一个面板也管上游版本，所以升级不用再手动重装依赖：
+
+- **自己检查。** 宿主启动时（以及页面要求时）插件会探测各 PyPI 镜像，取响应最快的那个读它的 `windows-mcp` 索引；结果在 `$DSH_HOME/dsh-windows-mcp.versions.json` 里缓存 6 小时，重启不会反复打网络。
+- **版本各装各的。** 每个版本通过 `UV_TOOL_DIR` 装进自己的目录：`$DSH_HOME/dsh-windows-mcp/toolchain/<版本>/windows-mcp`。激活一个版本只是重写桥那一行（同样先备份），**不需要重装**，上一版原样留在磁盘上。
+- **一键更新。** **更新到 vX** 会从能用的最快镜像下载该版本（失败自动换下一个镜像），校验可执行文件和 `dist-info` 之后再激活；面板会显示当前运行版本和它来自哪个镜像。
+- **回退同样一键。** **回退到 vPrev** 把桥指回“当前版本替换掉的那个版本”，不下载任何东西。
+
+只动插件自己管理的安装：在你安装第一个托管版本之前，桥仍然用全局 `uv tool` 装的那份；面板会标明当前生效的是 `uv-tool` 还是 `managed`。
+
+### Python 依赖的镜像加速
+
+检查阶段会用 96 KiB 的 range 读取量一遍七个候选——PyPI 官方，加上中科大、阿里云、腾讯云、华为云、南京大学、清华 TUNA——按实测吞吐量排序。安装时用最快且能用的镜像，失败就回退到下一个；同时固定 `UV_CONCURRENT_DOWNLOADS=4`、`UV_HTTP_RETRIES=3`、`UV_HTTP_TIMEOUT=600`，因为镜像会限流 uv 默认的 8 并发（HTTP 429）。对当前网络直接封锁的镜像（本机 TUNA 现在返回 403）会被排到后面而不是让安装失败；每个镜像的实测速度都显示在面板上。
+
+### 设置页与 Star 按钮
+
+除了插件卡片上的这些，还有几个不属于卡片的小开关，集中在 **设置 → 桌面控制** —— 设置界面左边栏里新增的一页，和别的插件页并列：
+
+- **桥接** —— `toolCallTimeoutMs`、截图缩放、截图后端、上游的闪光提示层，以及桥允许排除的三个工具（`App`、`PowerShell`、`FileSystem`）。这些会写进你 profile 的 `cordis.patch.yml` 桥行（先做时间戳备份），所以 **重启 DSH 后才生效**；页面上会写明当前生效的是哪一行。
+- **更新** —— 是否在启动时自动检查新版 Windows-MCP，以及镜像策略：`auto` 用实测排序，指定镜像则固定用它（官方源始终留作最后的兜底）。
+- **关于** —— 插件版本、仓库链接，以及一个「点个 Star」按钮，点开在新标签页打开 GitHub 仓库。
+
+保存是原子的（`$DSH_HOME/dsh-windows-mcp.settings.json`）。越界的值会被夹到默认值并告知，而不是悄悄写坏；只改插件参数、不涉及桥行时不会重写补丁层。**还原** 把表单恢复成默认值。
 ## 验证
 
 ```text
@@ -243,12 +272,29 @@ npm run dump
 
 ```text
 cordis.patch.yml      集成本体：两行 insert
-lib/index.js          宿主半边：windows_mcp_doctor + 启动审计（零依赖）
-test/plugin.test.mjs  补丁合成测试 + 恶意 ctx 测试
+lib/index.js          宿主半边：路由 + windows_mcp_doctor + 启动审计（零依赖）
+lib/dependency.js     依赖状态、uv 调用封装、profile 桥行写入
+lib/pypi.js           PyPI 索引解析与版本比较（纯函数）
+lib/mirrors.js        镜像候选、限速探测与排序
+lib/installs.js       按版本隔离的工具目录 + 版本状态文件
+lib/updater.js        版本管理：检查 / 安装 / 激活 / 回退
+lib/settings.js       用户设置：校验、落盘、桥行往返
+lib/client.js         网页半边：输入框开关 + 插件面板 + 设置页
+test/plugin.test.mjs  补丁合成测试 + 恶意 ctx 测试 + 面板测试
+test/update.test.mjs  版本解析、镜像排序、版本隔离与回退状态机测试
+test/settings.test.mjs 设置校验、桥行往返、设置路由测试
 scripts/dump-config.mjs  面向影子 profile 的合成调试脚本
 tools/                零依赖调试探针（不发布到 npm）
 ```
 
+要对着真实网络和本机 profile 验证升级链路，用 `tools/update-e2e.mjs`：
+
+```powershell
+node tools/update-e2e.mjs --check          # 探测镜像并读出最新稳定版
+node tools/update-e2e.mjs --install 0.8.8  # 真下载、真激活、真改桥行
+node tools/update-e2e.mjs --rollback
+```
+
 欢迎贡献；请保持 `lib/index.js` 无运行时依赖，并保持 `apply()` 永不抛错。
 
 ## 致谢与许可