dsh-plugin-rea 2.0.5 → 2.0.7

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 本插件遵循语义化版本。版本号变化说明「配置组合」这层的变化，与 REA 自身的版本无关。
 
+## 2.0.7 — 2026-10-18
+
+**机器上已有可用的 REA 时，2.x 直接按 1.x 的方式跑它（环境检测 + 委派），不再供给；同时把 2.0.6 的宿主声明收紧到真的能证明的范围。**
+
+### 新增：环境检测 → 跑 1.x 的那条路
+
+- **启动时判断该跑谁**：`rea` 在 PATH 上且能应答 `--version`，就用它（`rea mcp`，用户自己的 Node 与 PATH）；否则走供给的
+  bundle。这正是 1.x 的契约，现在从 2.x 的行里也能到。
+- **版本优先级**：系统 REA 比供给的旧就不抢（6.4.0 是 170 个工具、6.5.0 是 207 个，静默回退工具数是真回归）。相等或更新
+  才切；预发布/无法比较时保守留 bundle。
+- **覆盖**：`REA_BUNDLE_LAUNCH=auto|system|bundle`（默认 auto）、`REA_BUNDLE_SYSTEM_REA=<path>` 点名不在 PATH 上的二进制。
+  `system` 在找不到时**报错退出**，而不是替用户去下 800 MB。
+- **`--shim-status` 报告决定**：`launch.{preference,mode,reason,unusable,systemRea,rejected}`；`--shim-print-env` 在 system
+  模式下打印 `{launch,rea,version}`。
+- **防自委派**：被委派的子进程带 `REA_BUNDLE_DELEGATED=1`，一个调用本 shim 的 wrapper 不会让委派无限递归。
+
+### 修复（两轮独立复核，逐条可复现）
+
+- **委派参数被加引号**：`cmd /c` 下 `.cmd` 的 `%*` 收到的是 `"mcp"` 而不是 `mcp` —— 探针能过、委派是坏的。现在只给路径加
+  引号，参数原样传（行固定传 `mcp`；需要 shell 引号的参数本就不在这条路上）。
+- **探测预算 3s 与真机同量级**：实测经 `.cmd` 的 `rea --version` 为 2.4s（并发 2.8–3.0s），3s 预算等于掷硬币。改为 8s；超时
+  用 `taskkill /T /F` 杀进程树，不再只杀 cmd.exe 而留下一个占着管道的 REA。
+- **Windows 信号转发是错的**：`child.kill("SIGINT")` 只 TerminateProcess(cmd.exe)，里面的 REA 继续跑；现在 Windows 走
+  `taskkill /T`，POSIX 不重复转发（stdio inherit 已由进程组投递）。
+- **`--shim-status` 退出码**：`system` 被点名但不可用时曾返回 0（bundle 恰好已供给），实际启动却 78；现在按「这一行能不能
+  起来」返回，并新增 `launch.unusable` 字段。
+- **候选判定**：`existsSync` 换成 `statSync().isFile()`（名为 `rea.cmd` 的目录曾被当成坏安装）；PATH 项去引号、跳过相对项；
+  显式路径被拒时理由如实报告。
+- **`fail()` 的补救命令补上 `--root`**：shim 用 `REA_BUNDLE_ROOT` 解析出的根与 setup 的默认根可以不同，照着旧提示执行会供给
+  到另一个根。
+- **`engine.dsh` 上限收紧**：`<0.3.0` 在 includePrerelease 语义下会放行 `0.3.0-alpha.1`/`0.3.0-rc.1`；改为 `<0.3.0-0`，并用
+  市场自己的 `satisfiesRange` 逐版本核对。
+- **`host-compat.mjs` 的测试加固**：发布清单逐项钉住；新增「低地板必须被判为泄漏」的反向对照（原实现把 `leaked` 改成 `[]`
+  仍然全绿）；`+build` 元数据按 semver 接受、`v` 前缀与零填充预发布按 semver 拒绝。
+- **环境独立性**：`setup.mjs` 自检的 shim 步骤钉 `bundle` 模式（否则机器上更新的 REA 会冒充本次供给的产物）；CI 两个 job
+  各加 job 级 `REA_BUNDLE_LAUNCH=bundle`；测试里的每个 shim 调用点都钉住模式，测试不再随机器变。
+- **`rea-bundle-bootstrap.ps1` 认 `REA_BUNDLE_ROOT`**：四份代码里只有它忽略这个覆盖，导致 bootstrap 把 800 MB 装到
+  `<DSH_HOME>/plugins/rea-bundle`，而 shim/setup/check-updates 去 `REA_BUNDLE_ROOT` 找，看到空 bundle 再起一次。
+- 中文 README 的「更新到 2.0.4」措辞改正为「更新到 2.0.5」。
+
+### 验证
+
+- 单测 **60 条**（新增 12 条：6 条启动模式 + 1 条清单钉住 + 1 条泄漏反向对照 + 1 条 semver 容差 + 3 条 PATH/空格路径/委派退出码），
+  Windows 57 过 + 3 平台跳过。
+- `verify-branch.ps1` 全绿；`audit-manifest.mjs` clean；`host-compat.mjs` 10 covered / 5 correctly outside。
+- 真机：全局 `rea` 6.4.0 与供给的 6.5.0 并存时 `auto` 留 bundle（不降工具数），`REA_BUNDLE_LAUNCH=system` 才切过去。
+
+
+## 2.0.6 — 2026-10-18
+
+**声明宿主版本：`engines.dsh` 覆盖 `0.1.7-rc.2` … `0.2.1-rc.2` 全部发布版本，市场卡片因此显示「兼容」而不是「未声明」。**
+
+### 兼容声明
+
+- **`engines.dsh: ">=0.1.7-rc.2 <0.3.0"`**：市场侧的 `deriveHostCompatibility` 只认两类声明 —— `engines.dsh`
+  与指向 `@deepseek-ai/dsh*` 的 `peerDependencies`；两者都没有就是 `unknown`（卡片「兼容性未知」）。
+  这里只声明前者，刻意不声明 peer：`@deepseek-ai/dsh-mcp-client` 在 npm 上只有 `0.0.1-rc.1`，
+  而宿主随包内置的是 0.2.x，声明 peer 会让 pnpm 解析出一个与宿主不一致的版本，反而制造假冲突。
+- **范围来自核对，不是估计**：`scripts/host-compat.mjs` 内置 dsh 发布列表（0.1.7-rc.2 至 0.2.1-rc.2 共 10 个），
+  逐个验证是否被声明覆盖，并反向确认 `0.3.0` 与 `0.1.7-rc.1`、`0.1.7-alpha.2` 落在范围之外。
+- **跨版本比对过的东西**：`packages/mcp/mcp-client` 在 `dsh-v0.1.7-rc.2` 与 `dsh-v0.2.1-rc.2` 两个 tag 上，
+  配置面与发布的行一致（`serverName`/`transport`/`command`/`args`/`env`/`failOnStartupError` 均存在且同名），
+  且两个 tag 都有 `dsh.bundle.patch`。范围声明的是「核对过的宿主」，不是「应该能用」。
+
+### 上游（只更新仓库，暂不带入）
+
+- 上游已发布 **rea-agents 6.6.0**（GitHub release `rea-agents-6.6.0`，2026-10-18）；npm `latest` 仍是 **6.5.0**，
+  所以本包的钉（`manifest/bundle.manifest.json` 的 `pins.reaAgents` 与 `components.reaAgents.sources.npm.version`）
+  **保持 6.5.0 不动**。已核 6.6.0 的 `engines.node`（`^22.19.0 || ^24.11.0 || >=26.0.0`）与 `bin`
+  （`scripts/rea.mjs`）均未变化，`optionalDependencies.frida` 为 17.23.2。
+- 计划：**2026-10-19** 随下一版把钉升到 6.6.0 并复跑真机；届时工具数、探针正则与文档一并更新。
+
+### 修复 / 工程
+
+- 新增 `scripts/host-compat.mjs`（纯函数 + CLI）：semver 预发布排序、`>=floor <ceiling` 判定、发布列表覆盖检查。
+- `bundle:host-compat` npm script；`verify-branch.ps1` 新增 `engines.dsh` 存在性与覆盖率两项；
+  `validate.yml` 新增「Declared DSH range covers every released host」步骤，清单检查也要求 `engines.dsh`。
+
+### 验证
+
+- 单测 **46 条**（新增 4 条：声明可解析、10 个发布版本全覆盖且 3 个未核对版本被排除、反向对照能抓出
+  `>=0.2.0` 这种看似合理却漏掉整个 0.2.0-rc 线的写法、预发布排序符合 semver 而非字符串序）：Windows 43 过 + 3 平台跳过。
+- `node scripts/host-compat.mjs`：10 个发布版本 covered、3 个 correctly outside。
+- `verify-branch.ps1` 全绿；`audit-manifest.mjs` clean（两份 README 结构仍平行）。
+
 ## 2.0.5 — 2026-10-18
 
 **市场更新失败已定位并修复：清单里没有 `main`，市场因此在每次更新时判「新构建没有可加载入口」并回滚。**

package/README.md

@@ -125,6 +125,43 @@ provisioning (the harness itself is unaffected: `failOnStartupError: false` is d
 `node scripts/setup.mjs` once; from then on the shim is in place, and every later missing state is picked up
 by the shim itself, which provisions in the background.
 
+### Which DSH versions
+
+`package.json` declares `engines.dsh: ">=0.1.7-rc.2 <0.3.0"`, and that declaration is the answer the plugin market
+reads: with it the card says **compatible**; without it the market can only say *unknown*. The range is not a guess —
+it is the dsh release list this plugin is checked against, and `node scripts/host-compat.mjs` fails the build when the
+two disagree:
+
+| Host | Covered |
+|---|---|
+| `0.1.7-rc.2` … `0.2.1-rc.2` — every release in between, alpha and rc | yes |
+| `0.3.0` and later | no — a new minor line is a host nobody updated this row for yet |
+
+What was actually compared across that range is the row provider: `packages/mcp/mcp-client` at `dsh-v0.1.7-rc.2` and at
+`dsh-v0.2.1-rc.2` exposes the same config surface the shipped row uses (`serverName`, `transport`, `command`, `args`,
+`env`, `failOnStartupError`), and `dsh.bundle.patch` exists at both tags. A host outside the range can still work; it is
+simply not claimed.
+
+### A REA you already have is used as-is
+
+2.x exists to supply what a machine is missing. If REA is already installed — `rea` on PATH, the 1.x setup — the row
+runs **that**, exactly as the 1.x line did, and nothing is provisioned:
+
+| What the machine has | What the row runs |
+|---|---|
+| `rea` on PATH, at least as new as the provisioned build | your REA (`rea mcp`), with your Node and your PATH |
+| `rea` on PATH but older than the provisioned build | the provisioned bundle — a stale global CLI would take the tool count backwards (6.4.0 ships 170 tools, 6.5.0 ships 207) |
+| no `rea` on PATH | the provisioned bundle, provisioning itself on first use |
+
+- `REA_BUNDLE_LAUNCH=auto|system|bundle` overrides the decision (`auto` is the default); `REA_BUNDLE_SYSTEM_REA=<path>`
+  names a binary that is not on PATH.
+- The probe is the CLI's own `--version`, bounded at 8 s: a `.cmd` shim on Windows takes ~2.4 s to answer, so the check
+  runs once per start and only when a `rea` actually exists.
+- `--shim-status` prints the decision — `launch.mode`, `launch.reason`, `launch.systemRea` — and its `launch.rejected`
+  list says why a candidate was skipped (`"exit 7"`, `"inside the bundle"`, `"timeout"`).
+- A delegated child carries `REA_BUNDLE_DELEGATED=1`, so a wrapper that calls this shim cannot make it delegate to
+  itself forever.
+
 ## Configure — nothing
 
 The shipped row carries **no machine path**:

package/README.zh-CN.md

@@ -116,6 +116,40 @@ node scripts/setup.mjs --reuse      # 或先 --dry-run 看计划
 任何东西能去启动后台供给（harness 本身不受影响：`failOnStartupError: false` 是刻意的）。先手动跑一次
 `node scripts/setup.mjs`；此后 shim 就位，之后每一次「状态缺失」都由它自己发现并在后台补供给。
 
+### 支持哪些 DSH 版本
+
+`package.json` 里声明了 `engines.dsh: ">=0.1.7-rc.2 <0.3.0"`，这就是插件市场读的那句话：有它，卡片显示
+**兼容**；没有它，市场只能说*未声明*。这个范围不是猜的——它对应本插件实际核对过的 dsh 发布列表，
+`node scripts/host-compat.mjs` 会在两者不一致时让构建失败：
+
+| 宿主版本 | 是否覆盖 |
+|---|---|
+| `0.1.7-rc.2` … `0.2.1-rc.2`（中间的 alpha 与 rc 全部在内） | 是 |
+| `0.3.0` 及以后 | 否 —— 新的小版本线是还没为它核对过这一行的宿主 |
+
+真正被比对过的是「行提供方」：`packages/mcp/mcp-client` 在 `dsh-v0.1.7-rc.2` 与 `dsh-v0.2.1-rc.2` 两个 tag 上，
+暴露的配置面与发布的行完全一致（`serverName`、`transport`、`command`、`args`、`env`、`failOnStartupError`），
+并且两个 tag 都有 `dsh.bundle.patch`。范围之外的宿主可能照样能用，只是没有替它声明。
+
+### 机器上已有 REA 就直接用它
+
+2.x 存在的意义是补上机器缺的东西。如果 REA 已经装好——`rea` 在 PATH 上，也就是 1.x 的形态——这一行就**直接跑它**，
+和 1.x 一模一样，不再做任何供给：
+
+| 机器上的情况 | 这一行跑什么 |
+|---|---|
+| `rea` 在 PATH 上，且不比供给的版本旧 | 你自己那份（`rea mcp`），用你的 Node 和你的 PATH |
+| `rea` 在 PATH 上，但比供给的版本旧 | 供给出来的 bundle —— 旧的全局 CLI 会把工具数往回退（6.4.0 是 170 个，6.5.0 是 207 个） |
+| PATH 上没有 `rea` | 供给出来的 bundle，首次使用时自行供给 |
+
+- `REA_BUNDLE_LAUNCH=auto|system|bundle` 覆盖这个判断（默认 `auto`）；`REA_BUNDLE_SYSTEM_REA=<path>` 用来点名一个
+  不在 PATH 上的可执行文件。
+- 探测用的是 CLI 自己的 `--version`，上限 8 秒：Windows 上的 `.cmd` 垫片要 ~2.4 秒才答得出来，所以这个检查每次启动
+  只做一次，而且只在真的存在 `rea` 时才做。
+- `--shim-status` 会把判断结果打出来 —— `launch.mode`、`launch.reason`、`launch.systemRea`，`launch.rejected` 里
+  写的是每个候选被跳过的原因（`"exit 7"`、`"inside the bundle"`、`"timeout"`）。
+- 被委派的子进程带着 `REA_BUNDLE_DELEGATED=1`，所以一个调用本 shim 的 wrapper 不会让它无限委派给自己。
+
 ## 配置 —— 不需要
 
 发布的那一行**不含任何机器路径**：
@@ -249,7 +283,7 @@ shim** 的 MCP `initialize` 握手返回 `serverInfo {name: rea, version: 6.5.0}
 ### 在市场里更新
 
 在哪儿装的就在哪儿更新。更新到 **2.0.5 及以上**是常规操作；而把已装的 2.0.1–2.0.4 通过应用内市场**更新到
-2.0.4**，在健康的 profile 上连续失败了三次：
+2.0.5**，在健康的 profile 上连续失败了三次：
 
 > dsh-plugin-rea 更新后缺少入口文件（package.json 的 main/exports 指向的文件不存在），且未能验证恢复原版本文件