dsh-as-mcp 0.52.83 → 0.52.84

package/CHANGELOG.md

@@ -6,6 +6,29 @@ plugin is pre-1.0, so a minor bump is a feature and a patch is a fix or docs.
 A Chinese summary of every release lives in [CHANGELOG.zh.md](./CHANGELOG.zh.md);
 this file stays the authoritative record.
 
+## 0.52.84
+
+- The GitHub-install instructions now lead with the approval that keeps working. pnpm matches a
+  git dependency's build by `<name>@<git url>` with no `#<ref>`, so one `allowBuilds` entry covers
+  every later commit; the previous text led with the commit-pinned key pnpm prints
+  (`…/tar.gz/<sha>: true`), which stops matching on the next push and forced a fresh manual
+  approval on every update. The section also states the correct floor for the two commands it
+  documents — `github:…` and a release `.tgz` are both fetched as tarballs, so the repository form
+  needs pnpm ≥11.19.0 (11.11.0 only covers cloned git dependencies), and pnpm 10 names the same
+  decision `onlyBuiltDependencies` — and points at the channels that need no build approval: `npm`
+  and the prebuilt Release asset, neither of which runs `prepare`.
+- `tools/check-docs.mjs` now fails when either README's git-install guidance drifts from the
+  package's own identity. While `package.json` keeps a `prepare` script and `lib/` stays
+  gitignored, both languages must carry the manifest-derived key
+  (`dsh-as-mcp@git+https://github.com/xiseliuli/dsh-as-mcp.git`) and name
+  `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`. A package or repository rename, or making the build
+  unnecessary, therefore breaks the release check instead of silently leaving readers a key that
+  matches nothing. Issue #1 is why this exists: a Plugin Hub 1.6.5 install fell back to the git
+  channel after its own npm lookup missed this package, pnpm's build gate refused the `prepare`
+  run, and DSH's generic hint left the reporter to copy a key by hand.
+- Install guidance is the only change: the built `lib/` and every tool behave as in 0.52.83, apart
+  from the version the MCP `initialize` result advertises.
+
 ## 0.52.83
 
 - A first-time MCP client now learns the reporting contract where it actually looks. The `initialize`

package/CHANGELOG.zh.md

@@ -6,6 +6,12 @@
 - 两份文件的**版本标题必须完全一致**（集合与顺序），由 `tools/check-docs.mjs` 强制检查——发布时漏写中文条目会让检查失败，中文读者不会悄悄落后一个版本。
 - 版本号遵循 SemVer；项目仍是 pre-1.0，所以 minor 是功能，patch 是修复或文档。
 
+## 0.52.84
+
+- GitHub 安装指引改为先给「能长期有效的放行方式」：pnpm 按 `<name>@<git url>`（不带 `#<ref>`）匹配 git 依赖的构建，一条 `allowBuilds` 条目就能覆盖之后的所有 commit；原文先让读者抄 pnpm 打印的、钉在 commit 上的 key（`…/tar.gz/<sha>: true`），上游一 push 就失效，每更新一次都得重新手动放行。同时纠正本页两条命令的实际门槛：`github:…` 与 release `.tgz` 都按 tarball 拉取，所以按仓库 URL 放行需要 pnpm ≥11.19.0（11.11.0 只覆盖克隆形式的 git 依赖）；pnpm 10 上该开关叫 `onlyBuiltDependencies`。并新增「不放行构建」的通道：npm 与预构建的 Release 资产，两者都不执行 `prepare`。
+- `tools/check-docs.mjs` 新增漂移检查：只要 `package.json` 还带 `prepare` 且 `lib/` 仍在 `.gitignore` 里，中英两份 README 就必须带上由 manifest 推导出的 key（`dsh-as-mcp@git+https://github.com/xiseliuli/dsh-as-mcp.git`）并点名 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`；改包名或仓库名、或提交 `lib/` 删掉 `prepare`，检查会失败或自动不再要求这段——不会再把一个匹配不上任何东西的 key 留在文档里。这条来自 issue #1：Plugin Hub 1.6.5 自己的 npm 反查没命中本包、回退到 git 通道，pnpm 的构建门禁拦下 `prepare`，而 DSH 只打印通用提示，读者只能自己抄 key。
+- 除上述安装说明外无行为变化：构建产物与各工具与 0.52.83 相同，差别只有 MCP `initialize` 宣告的版本号。
+
 ## 0.52.83
 
 - 首次接入的 MCP 客户端现在能在它真正会读的地方看到上报契约：`initialize` 指令、`session_prompt` 的描述与 `wait` 选项都写明"`wait: false` 启动 → 用 `session_status` 跟进（`waitMs` 让变化即刻返回）"，以及失败通道（`turn.failure` = `{kind, message}`；正常完成不带 failure 块）。`session_prompt` 首次提供 output schema（含 `turn.failure`）；`session_status` 的 output schema 从只有 `sessionId`/`running` 扩展为完整报告（`idleMs`、`stalled`、`failure`、`lastTurn`、`changed`、`waitedMs` 等），schema 感知的客户端不必猜。很多 MCP 宿主不会把 `initialize.instructions` 传给模型，所以工具描述才是唯一可靠的首屏说明——这些措辞现在由测试固定，而不是靠习惯维护。

package/README.md

@@ -76,33 +76,52 @@ dsh plugin --profile <name> add github:xiseliuli/dsh-as-mcp
 ```
 
 A git install fetches source, not the built `lib/`, so pnpm must run this package's `prepare`
-script (`tsdown && node scripts/build-client.mjs`) to produce it. pnpm ≥10 refuses to run that
-script — and the `esbuild` postinstall the build depends on — until the profile allows them, so
-the first `add` fails with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`.
-
-A bare package name in `allowBuilds` works for `esbuild` (a registry dependency) but never for
-`dsh-as-mcp` here: pnpm only approves a git-hosted build by its exact resolved key, never by
-name alone ([pnpm docs](https://pnpm.io/settings/build#allowbuilds)). The failed `add` prints
-that exact key in its error; copy it verbatim into the profile's `pnpm-workspace.yaml`
-(`~/.dsh/profiles/<name>/pnpm-workspace.yaml`) and re-run the `add`. Don't rely on pnpm having
-written a placeholder entry for you — on this failure path it does not. The result looks like:
+script (`tsdown && node scripts/build-client.mjs`) to produce it. pnpm's supply-chain gate blocks
+dependency build scripts by default — the `esbuild` postinstall the build needs included — until
+the profile allows them, so the first `add` fails with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`.
+That refusal is pnpm's policy, not a packaging defect: a git dependency can execute arbitrary
+code at install time, so pnpm requires an exact, explicit approval.
+
+**Approve the build once, by repository URL.** pnpm matches a git dependency's build by
+`<name>@<git url>` with no `#<ref>`, so a single entry keeps the build working across commits and
+releases. On a profile whose pnpm is ≥11.19.0 — DSH 0.2.1-rc.5 bundles 11.28.5, and a successful
+`add` names the version it used on its last line (`… using pnpm v…`) — add this to the profile's
+`pnpm-workspace.yaml` (`~/.dsh/profiles/<name>/pnpm-workspace.yaml`) and re-run the `add`:
 
 ```yaml
 allowBuilds:
-  '<the exact git spec pnpm wrote, including its commit hash>': true
+  'dsh-as-mcp@git+https://github.com/xiseliuli/dsh-as-mcp.git': true
   esbuild: true
 ```
 
-Treat that allowance as permission to run this package's code on your machine at install time;
-pin a commit (`github:xiseliuli/dsh-as-mcp#<sha>`) so a later push cannot silently change what runs.
-`dsh plugin add` runs the pnpm version DSH pins (v11.28.5 in DSH 0.2.1-rc.5 — its output ends with
-`using pnpm v…`), so the following applies only once DSH ships a newer pnpm. If the
-profile's pnpm is ≥11.19.0 (≥11.11.0 for a cloned, non-`github:` git dependency), you can instead
-approve the repository itself — `'dsh-as-mcp@git+https://github.com/xiseliuli/dsh-as-mcp.git': true`, with
-no `#<sha>` — so a later commit on the same repo keeps building without re-approval; on an older
-pnpm the exact-commit key is your only option and needs re-approving after every update
-([pnpm 11.11 release notes](https://pnpm.io/blog/releases/11.11-11.14),
-[pnpm/pnpm#12367](https://github.com/pnpm/pnpm/issues/12367)).
+A bare name (`dsh-as-mcp: true`) never approves a git-hosted artifact; pnpm matches on the
+identity, not the package name ([pnpm docs](https://pnpm.io/settings/build#allowbuilds)).
+
+On an older pnpm (11.0–11.18) only the exact key works, because approving a tarball-fetched
+`github:` dependency by repository URL landed in
+[pnpm 11.19.0](https://github.com/pnpm/pnpm/releases/tag/v11.19.0) — both commands on this page
+are fetched as tarballs (`github:…`, and a release `.tgz`). The failed `add` prints that exact key
+pinned to the resolved commit; copy it verbatim, keeping it on one line if the terminal wrapped
+it, and expect to re-approve after any update
+([pnpm/pnpm#12367](https://github.com/pnpm/pnpm/issues/12367)). Don't wait for pnpm to write the
+entry for you: on this failure path it writes nothing. On pnpm 10 the same decision is
+`onlyBuiltDependencies`, not `allowBuilds`; trust the key pnpm prints.
+
+The approval is permission to run this package's build code on your machine at install time. If
+you pin a commit (`github:xiseliuli/dsh-as-mcp#<sha>`), the key must carry that commit; the
+repository-URL key above approves any commit from this repository.
+
+**Without approving a build**, install a published artifact instead — both ship the built `lib/`
+and never run `prepare`:
+
+```bash
+dsh plugin --profile <name> add dsh-as-mcp
+dsh plugin --profile <name> add \
+  https://github.com/xiseliuli/dsh-as-mcp/releases/download/v<version>/dsh-as-mcp-<version>.tgz
+```
+
+Git installs also need DSH ≥ `0.1.5-rc.1` ([Compatibility](#compatibility)); an older runtime
+refuses the plugin unless an exact-version exemption is granted with `dsh plugin allow-version`.
 
 **From a tarball:**
 

package/README.zh.md

@@ -73,31 +73,47 @@ dsh plugin --profile <名称> add github:xiseliuli/dsh-as-mcp
 ```
 
 git 安装拉下来的是源码，不是构建产物 `lib/`，所以 pnpm 得跑本包的 `prepare` 脚本
-（`tsdown && node scripts/build-client.mjs`）才能把它建出来。pnpm ≥10 默认拒绝执行这个脚本——
-连带它依赖的 `esbuild` 的 postinstall 也一并拦下——直到 profile 显式放行，所以第一次 `add` 会以
-`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` 失败。
+（`tsdown && node scripts/build-client.mjs`）才能把它建出来。pnpm 的供应链门禁默认拒绝执行
+依赖的构建脚本——连带它依赖的 `esbuild` 的 postinstall 也一并拦下——直到 profile 显式放行，
+所以第一次 `add` 会以 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` 失败。这是 pnpm 的策略，不是打包
+缺陷：git 依赖在安装期可以执行任意代码，所以 pnpm 要求一次精确、明确的放行。
 
-`allowBuilds` 里写裸包名，对 `esbuild`（来自 registry）有效，但对这里的 `dsh-as-mcp` 永远无效：
-pnpm 只认 git 依赖精确解析出来的那个 key，不认包名
-（[pnpm 文档](https://pnpm.io/settings/build#allowbuilds)）。失败的那次 `add` 会在报错里打印这个
-精确 key；把它原样抄进 profile 的 `pnpm-workspace.yaml`（`~/.dsh/profiles/<名称>/pnpm-workspace.yaml`），
-再重新跑一次 `add`。不要指望 pnpm 已经替你写好占位项——这条失败路径下它不会写。结果长这样：
+**一次放行、按仓库 URL 生效（推荐）。** pnpm 按 `<name>@<git url>`（不带 `#<ref>`）匹配 git 依赖的
+构建，因此一条条目就能跨 commit、跨版本一直有效。profile 的 pnpm ≥11.19.0 时——DSH 0.2.1-rc.5
+自带 11.28.5，成功的那次 `add` 最后一行会写明用的版本（`… using pnpm v…`）——把下面这段写进
+profile 的 `pnpm-workspace.yaml`（`~/.dsh/profiles/<名称>/pnpm-workspace.yaml`），再重跑 `add`：
 
 ```yaml
 allowBuilds:
-  '<pnpm 写出来的那个精确 git spec，含 commit hash>': true
+  'dsh-as-mcp@git+https://github.com/xiseliuli/dsh-as-mcp.git': true
   esbuild: true
 ```
 
-这个放行等于允许在你机器上、在安装阶段执行这个包的代码——建议钉死到某个 commit
-（`github:xiseliuli/dsh-as-mcp#<sha>`），免得后续的 push 悄悄改掉实际跑的代码。`dsh plugin add` 使用的是
-DSH 锁定的 pnpm 版本（DSH 0.2.1-rc.5 为 v11.28.5，输出末尾会打印 `using pnpm v…`），所以下面这条要等
-DSH 自带更新的 pnpm 后才适用。如果 profile 用的 pnpm
-≥11.19.0（若是克隆而非 `github:` 这种 tarball 形式的 git 依赖，则 ≥11.11.0 即可），可以改为放行整个
-仓库——`'dsh-as-mcp@git+https://github.com/xiseliuli/dsh-as-mcp.git': true`，不带 `#<sha>`——这样同一个仓库
-之后再提交新 commit 也不用重新放行；更早的 pnpm 版本只能用精确 commit 的 key，每次更新都要重新放行一次
-（[pnpm 11.11 release notes](https://pnpm.io/blog/releases/11.11-11.14)，
-[pnpm/pnpm#12367](https://github.com/pnpm/pnpm/issues/12367)）。
+裸包名（`dsh-as-mcp: true`）永远不会放行 git 托管产物：pnpm 认的是带来源的身份，不是包名
+（[pnpm 文档](https://pnpm.io/settings/build#allowbuilds)）。
+
+更早的 pnpm（11.0–11.18）只认精确 key，因为「按仓库 URL 放行 tarball 形式的 `github:` 依赖」是
+[pnpm 11.19.0](https://github.com/pnpm/pnpm/releases/tag/v11.19.0) 才有的——本页两条命令
+（`github:…` 和 release `.tgz`）都是按 tarball 拉取的。失败的那次 `add` 会打印这个精确 key
+（钉在解析出的 commit 上）；原样抄过去，如果终端把 URL 折行了就拼回一行；并且此后**每次更新都要
+重新放行**（[pnpm/pnpm#12367](https://github.com/pnpm/pnpm/issues/12367)）。不要指望 pnpm 已经替你
+写好占位项：这条失败路径下它不会写。pnpm 10 上这个开关叫 `onlyBuiltDependencies` 而不是
+`allowBuilds`，以报错里给出的 key 为准。
+
+这个放行等于允许在你机器上、在安装阶段执行这个包的构建代码。如果你把依赖钉死到某个 commit
+（`github:xiseliuli/dsh-as-mcp#<sha>`），key 就必须带那个 commit；上面那条仓库 URL 形式放行的是
+本仓库的任意 commit。
+
+**不想放行构建**，就装已经构建好的发布物——两者都带现成的 `lib/`，都不执行 `prepare`：
+
+```bash
+dsh plugin --profile <名称> add dsh-as-mcp
+dsh plugin --profile <名称> add \
+  https://github.com/xiseliuli/dsh-as-mcp/releases/download/v<版本>/dsh-as-mcp-<版本>.tgz
+```
+
+git 安装还要求 DSH ≥ `0.1.5-rc.1`（见[兼容性](#兼容性)）；更老的运行时会拒绝加载，除非用
+`dsh plugin allow-version` 授予精确版本豁免。
 
 **从 tarball：**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-as-mcp",
-  "version": "0.52.83",
+  "version": "0.52.84",
   "description": "Expose this DeepSeek Harness as an MCP server: create workspaces and sessions, drive DSH agents, edit files, run commands (foreground and background), fork/rename/rename-model sessions, and read exact token usage and cost receipts for every call.",
   "type": "module",
   "license": "MIT",