dsh-project-mcp-manager 0.4.2 → 0.4.3

package/docs/design/adaptation-dsh-0.1.2-rc1.md

@@ -1,6 +1,6 @@
 # 适配记录：dsh v0.1.2-rc.1
 
-[← 返回 README](../README.zh.md) ｜ 相关：[JSON 配置层设计提案](proposal-json-mcp-config.md)
+[← 返回 README](../README.zh.md) ｜ 相关：[dsh v0.1.5-rc.1 适配记录](adaptation-dsh-0.1.5-rc1.md) · [JSON 配置层设计提案](proposal-json-mcp-config.md)
 
 **记录日期**：2026-09-09 ｜ **被测插件**：`dsh-project-mcp-manager` v0.3.1
 **宿主**：`@deepseek-ai/dsh@0.1.2-rc.1`（自带 `dsh-mcp-client@0.1.2-rc.1`、cordis 4.0.2、

package/docs/design/adaptation-dsh-0.1.5-rc1.md

@@ -0,0 +1,121 @@
+# 适配记录：dsh v0.1.5-rc.1
+
+[← 返回 README](../README.zh.md) ｜ 相关：[dsh v0.1.2-rc.1 适配记录](adaptation-dsh-0.1.2-rc1.md)
+
+**记录日期**：2026-09-10 ｜ **被测插件**：`dsh-project-mcp-manager` v0.4.2
+**宿主**：`@deepseek-ai/dsh@0.1.5-rc.1`（自带 `dsh-mcp-client@0.1.5-rc.1`、cordis 4.0.2、
+cordis-plugin-loader 1.0.3、cordis-plugin-include 1.0.7）
+
+**结论**：功能可用，无 API 断裂。装载、生效名、工具注册与调用、`tools.restrict`
+在 0.1.5-rc.1 上全部实测通过。**1.1 的依赖漂移已解决**（`@deepseek-ai/dsh-mcp-client`
+升到 `^0.1.5-rc.1`，peer 全部解析到 0.1.5-rc.1，与宿主同版）。headless 端到端
+LLM 任务被本机 `~/.dsh/settings.yaml` 的 `reasoningEffort: high` 挡住
+（qwen3.8-flash 不支持），与插件无关。
+
+---
+
+## 1. 待处理事项
+
+### 1.1 依赖版本漂移：插件仍在跑 mcp-client 0.1.2-rc.1 —— 已解决
+
+**现象**：`package.json` 声明 `@deepseek-ai/dsh-mcp-client@^0.1.2-rc.1`，仓库
+`node_modules` 实际解析到 **0.1.2-rc.1**（连带 peer `dsh-tools` / `dsh-scope` /
+`dsh-timeout` 同为 0.1.2-rc.1），而宿主是 0.1.5-rc.1 → 同一进程内存在两份
+dsh-mcp-client 代码。
+
+**关键更正**：`^0.1.2-rc.1` **不会**升级到 `0.1.5-rc.1`——npm semver 要求带
+prerelease 的候选版本与比较符的 major.minor.patch 元组相同，实测
+`npm view "@deepseek-ai/dsh-mcp-client@^0.1.2-rc.1" version` 只解析出
+`0.1.2-rc.1`。所以必须显式改范围。
+
+**升前实测**：插件自带的 0.1.2-rc.1 客户端对 0.1.5 形态的 `tools.register` /
+`restrict` 仍能装载并调用；宿主自带的 0.1.5-rc.1 客户端对同一探针同样成功。
+功能上可共存，但进程内双副本与 peer 漂移仍是风险。
+
+**处置（已完成）**：升到 `^0.1.5-rc.1` 后重装，插件侧 `dsh-mcp-client` 与其
+全部 peer（`dsh-attachment` / `dsh-llm` / `dsh-scope` / `dsh-subprocess` /
+`dsh-timeout` / `dsh-tools`）解析到 **0.1.5-rc.1**，与宿主同版。pnpm 12 为这
+批 prerelease 写入 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`（否则
+供应链门禁会挡住刚发布的 rc）。升后 `pnpm test` 六套全绿，隔离实机复验
+`mcp__compat-probe__probe` → `pong:compat-015`，插件与宿主解析版本对齐。
+
+### 1.2 本机 headless LLM 任务被默认模型设置挡住（非插件）
+
+**现象**：`dsh --profile headless "<任务>"` 立即退出：
+
+```
+dsh: UNSUPPORTED_REASONING_EFFORT: provider "qwen-token-plan-cn" model "qwen3.8-flash" does not support reasoning effort "high"
+```
+
+来源是 `~/.dsh/settings.yaml` 的 `agent-default-model.reasoningEffort: high`。
+dump-config 里合成默认仍是 `deepseek-official` / `deepseek-flash`，被 settings
+层覆盖。未改用户设置；改用隔离脚本完成装载/调用验证（见 §3）。
+
+---
+
+## 2. 兼容性核对结果（静态）
+
+| 插件依赖点 | 0.1.5-rc.1 现状 |
+|---|---|
+| `tools.restrict({ deny })`、`ToolRestriction{allow,deny}`、`tools.schemas(scope?)` | 签名未变；unknown names / 空过滤仍失败 |
+| `agents` 服务名、`list()`、`isOwnedBy(id, owner)` | 均未变；`inject = ["tools","agents"]` 仍可满足 |
+| `agent/created`、`agent/disposed`、`agent/session-start` | 事件名与 payload `{ agent }` 仍在 |
+| cordis 4.0.2 | 与 0.1.2 线相同，无升级 |
+| mcp-client `Config` | 字段无增删（`serverName`/`transport`/`command`/`args`/`env`/`cwd`/`url`/`headers`/`toolCallTimeoutMs`/`failOnStartupError`/`reconnect`） |
+| `serverName` 约束 `[A-Za-z0-9_-]{1,32}` | 未变 → `effectiveServerNames()` 截 32 仍安全 |
+| 工具命名 `mcp__<serverName>__<rawName>` | 未变 |
+| `MAX_TIMER_DELAY_MS` | 宿主 `dsh-timeout` 仍是 `2147483647` |
+| `globalNames()` 读 `entry.config.patches` | include 1.0.7 仍有 `patches`；`dump-config` 出现 `# == dsh-project-mcp-manager` / `- id: mcp-project` |
+| mcp-client `inject` | 仍是 `["tools"]` |
+| mcp-client 0.1.2 → 0.1.5 实现 diff | `lib/index.js` 仅 +7/−2：`tools/list` 增加重复 continuation cursor 校验，不影响本插件发出的配置 |
+
+`pnpm test` 全绿（model 27 / mcp-file 7 / json-file 9 / json-write 6 / registry 34 / cli 18）。
+
+---
+
+## 3. 实测方法与结果
+
+### 3.1 安装/激活（headless profile）
+
+`~/.dsh/profiles/headless/package.json` 已是：
+
+```json
+"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless", "dsh-project-mcp-manager"]
+"dependencies": { "dsh-project-mcp-manager": "link:D:/Projects/Agent/dsh-mcp-project" }
+```
+
+`dsh --profile headless --dump-config` 合成树含 `# == dsh-project-mcp-manager` /
+`- id: mcp-project`。0.1.2 记录的「必须进 bundles」规则在 0.1.5 上仍然成立。
+
+### 3.2 隔离实机：装载 + 调用（不经 LLM）
+
+在本仓库 `.dsh/`（gitignore）写入最小 stdio 探针 `compat-probe`（`probe` →
+`pong:compat-015`），用隔离脚本走插件真实的 `ctx.plugin(mcp-client)` 路径：
+
+升前插件解析 0.1.2-rc.1、升后与宿主对齐 0.1.5-rc.1。升后复验：
+
+| 检查 | 结果 |
+|---|---|
+| 插件解析到的 mcp-client | 0.1.5-rc.1（与宿主对齐） |
+| 宿主自带 mcp-client | 0.1.5-rc.1 |
+| 插件客户端 mount + call | `mcp__compat-probe__probe` → `pong:compat-015` |
+| 宿主客户端 mount + call | 同上 |
+| `restrict({ deny: [精确名] })` / 拒绝 unknown | 通过 |
+| `ProjectMcpRegistry` 读项目 `.dsh/mcp.yml` 再 mount/call | `scan` → `attempt` → `active`，调用返回 `pong:compat-015` |
+
+诊断（第二次成功跑）：`scan ok:true rows:[compat-probe]` → `attempt` →
+`active`（`effectiveName: compat-probe`，目录内唯一故未改名）。
+
+### 3.3 未覆盖
+
+- headless 经模型的两步任务（本机 settings 的 `reasoningEffort: high` 使进程
+  在创建 Agent 前退出；未改用户设置）。
+- 热重载 watcher 与跨项目 deny 隔离未在 0.1.5 宿主进程里常驻复跑（单测仍覆盖）。
+
+---
+
+## 4. 建议
+
+1. **升依赖已完成**，无需再改范围。
+2. 若要补 headless LLM 路径：先把本机 `agent-default-model.reasoningEffort`
+   改成当前模型支持的值（或去掉），再跑两步任务。这是宿主设置问题，不是插件缺陷。

package/docs/releases/v0.4.1.md

@@ -1,117 +1,117 @@
-# 发布说明 v0.4.1（代码审查收口）
-
-[← 返回 README](../README.zh.md) ｜ 相关：[v0.4.0 发布说明](v0.4.0.md)
-
-**发布日期**：2026-09-16 ｜ **区间**：`v0.4.0 → v0.4.1`
-**规模**：6 commits + 收尾文档；源码 8 文件 +570 / −213（含全量测试与文档 20 文件 +1134 / −237）；
-新增源码模块 1 个（`src/dsh-paths.ts`）；测试套件仍为 6 套，新增 13 个场景
-
-v0.4.1 是一次**纯修复与可见性**版本：把 v0.3.1 以来全部 TypeScript 变更的代码审查
-（`docs/code-review/ts-review-since-v0.3.1.zh.md`）逐条落地。**配置文件格式没有任何变化**，
-唯一可见的输出变化是 CLI 写出的 JSON 条目现在带显式 `type`。
-
----
-
-## 亮点速览
-
-| 主题 | 一句话 |
-|---|---|
-| ⚠️ 项目侧压制不再自伤 | 只 deny「本轮真会全局装载」的名字，不再误伤项目自己的工具或宿主 patch |
-| `$DSH_HOME` 全链路生效 | 用户层三文件、全局诊断、CLI 读写路径统一走 `src/dsh-paths.ts` |
-| 坏条目不再被顺手删掉 | `mcpServers` 里的非对象条目跨读-改-写原样保留，可被指名删除 |
-| yml 写入并发安全 | 新增 `updateManagedRows`：读-改-写全在锁内，`EACCES` 不再被吞成「文件缺失」 |
-| 遮蔽诊断按层归因 | 纯用户层冲突只写全局诊断，零配置项目不再被动创建 `.mcp-diag.json` |
-| 告警按变化门控 | 文件错误、坏条目、`name-taken` 只在集合变化时告警一次 |
-| CLI 提示双真相 | `add` 提示新行会不会被遮蔽，`remove` 说明同名定义接管 |
-| `DSH_MCP_PROFILE` 校验 | `../../somewhere` 不再被拼进 profiles 目录 |
-
----
-
-## 修复
-
-### 项目侧压制只 deny 真会全局装载的名字（`src/registry.ts`）
-
-两个静默自伤场景：用户层 `~/.dsh/mcp.yml` 里的 `disabled: true` 占名行，以及被宿主全局
-patch 行顶掉（`name-taken`）的用户层行——两者都**不产生全局实例**，却照旧进了该项目的
-压制集合。压制按 `mcp__<原名>__` 前缀展开，于是 deny 打到了项目自己的服务器（它的生效名
-从未改名）或宿主 patch 实例上，而快照仍报 `fiberPhase: "active"`、没有 `skipReason`。
-
-修复：把用户层合并结果与「宿主已占名」集合前移到项目循环之前，`suppressedGlobals`
-只收真正会全局装载的名字；`sweepRestrictions` 再加一道「该名字当前确有全局实例」的守卫。
-
-### `$DSH_HOME` 重定位不再让用户层整体消失（`src/dsh-paths.ts`）
-
-此前用户层路径、全局诊断与 CLI 各处都硬编码 `homedir()/.dsh`，与 README 承诺的
-「dshHome 默认 `%USERPROFILE%\.dsh`，设置了 `DSH_HOME` 则用其值」相矛盾。重定位后
-用户层三文件全部指向不存在的路径，而「文件缺失」是合法的零配置状态，所以**没有任何告警**。
-
-新模块 `src/dsh-paths.ts` 成为唯一解析口径：`dshHomeDir(home, env)` / `dshHomeFor()` /
-`userLayerPathsIn()` / `profileMcpJsonFile()`。注入的路径（registry 的 `userLayerPaths`、
-CLI 的 `deps.home`）仍然优先于环境变量，测试才能与本机真实配置隔离。
-
-### 其余修复
-
-- **`remove` 说明同名接管**：yml 与 json 同时有同名行时，仍只删首个命中，但会打印
-  接下来由哪个文件的定义接管生效；再执行一次才真正清空。
-- **坏条目跨写入保留**：`readJsonServers`/`updateJsonServers` 不再过滤非对象条目，
-  手写的 `"legacy": "node x.js"` 不会被无关的 `add`/`remove` 永久删除，判重能看到它占的名，
-  `dsh-mcp remove legacy` 可以清掉它。
-- **yml 写路径锁内读-改-写**：`updateManagedRows(path, mutate, options)` 取代「锁外预读 +
-  锁内整体替换」，并发两个 `add` 不再互相丢行；`createIfMissing` 收紧为只接受 `ENOENT`，
-  `EACCES` 与损坏的受管块不再被当成「文件缺失」而被覆盖。
-- **`DSH_MCP_PROFILE` 先校验再拼路径**：不匹配 `^[A-Za-z0-9][A-Za-z0-9._-]*$`（含显式的
-  `.` / `..`）时按「解析不出 profile」降级并告警一次，不再读到 profiles 目录之外。
-- **`serverView` 的用户层作用域**：报 `global` + 层文件路径，与快照分区口径一致
-  （原先固定报 `workspace` + 项目根）。
-
----
-
-## 变更
-
-- **遮蔽诊断按层归因**：`IdentityShadow` 带上失败方与胜出方的来源，新增 `shadowedGlobal`
-  桶记录用户层之间的精确同名遮蔽（此前零可见性）。只涉及用户层的冲突在
-  `<dshHome>/.mcp-diag.json` 全局报一次；项目侧只保留至少一方是项目层行的条目，
-  零配置项目不再因为两个用户层文件互相冲突而被创建 `.dsh/.mcp-diag.json`。
-- **告警按变化门控**：文件级错误、坏条目、`name-taken` 集合只在集合本身变化时告警，
-  不再每轮对账每项目重刷；`skipReason` 照旧每轮写入，快照仍能查到原因。
-- **`name-taken` 文案**改为「宿主全局 patch 行（bundle 层或 profile patch 层）」，
-  与 `globalNames()` 实际收集的范围一致。
-- **CLI 写出的 JSON 条目带显式 `type`**（`stdio` / `http`），便于要求该键的生态工具消费；
-  本插件自己的读取器仍然可以推断。
-- **`add` 写入后复核**：新行被更高优先层按名字或按同服务遮蔽时提示「不会装载」，
-  同作用域另一方言文件也有定义时提示条目数。
-- **JSON 读取失败带 errno**（`读取失败（EACCES）`），错误串不含文件内容。
-- **`rowNameOf` 移入 `src/model.ts`** 由装载器与 CLI 共用：受管行 id 优先于
-  `config.serverName`。CLI 此前口径相反，id 与 `config.serverName` 不一致的行
-  没法用装载器实际使用的名字删除。
-- **内部清理**：`reconcileAll` 的项目循环体抽成 `scanProject`；逐项目 Map 按本轮 known keys
-  剪枝；`planProjectChanges` 的 O(n²) 查找改 Map；`activeProfile()` 经 `Promise.resolve`
-  兜住同步抛错；CLI 消除 `.dsh` / `mcp.yml` 字面量重复，`getMissMessage` 改用实际查过的层。
-
----
-
-## 文档
-
-- `docs/guide/layers.md` / `.zh.md`：补记 v0.4.0 起遗留 `.mcp.json` 层的三处行为变化——
-  条目级显式 `cwd` 现在生效、DSH 透传键（`toolCallTimeoutMs`/`failOnStartupError`/`reconnect`）
-  现在生效、`disabled: true` 从「静默跳过不占名」改为「占名不装载」。
-- `docs/guide/cli.md` / `.zh.md`：`-f`（`--format`）与 `-p`（`--profile`）自 v0.4.0 起是本 CLI
-  的保留短名，会吞掉下一个词元；要传给被 spawn 命令的同名参数写在 `--` 之后。
-- `CHANGELOG.md`：补记快照消费方须知——全局层分区的 `project` 字段自 v0.4.0 起是**层文件
-  自身所在目录**（`mcp.yml`/`mcp.json` 为 dshHome，profile 文件为 `profiles/<name>`），
-  v0.3.1 报的是 `.dsh` 的父目录（家目录）。`dsh-skill-mcp-panel` 等消费方按「层自己的目录」读。
-
----
-
-## 升级
-
-无需改动任何配置文件，无破坏性变更：
-
-- 设置了 `DSH_HOME` 的机器，用户层会从**它下面**读取（这是 README 一直承诺的行为，
-  此前的静默失效是缺陷）。若之前依赖「无论 `DSH_HOME` 如何都读 `%USERPROFILE%\.dsh`」，
-  把文件移到 `$DSH_HOME` 下即可。
-- CLI 新写出的 JSON 条目多一个 `type` 键；既有文件不会被改写。
-- 快照 / 诊断的字段只有新增（`shadowedGlobal`、`IdentityShadow.source` 与 `winnerSource`）。
-
-安全边界不变：`stdio` 行仍在 dsh 宿主进程里 spawn `command`，项目与用户层配置文件都是
-可执行代码载体，只在可信项目里启用。
+# 发布说明 v0.4.1（代码审查收口）
+
+[← 返回 README](../README.zh.md) ｜ 相关：[v0.4.0 发布说明](v0.4.0.md)
+
+**发布日期**：2026-09-16 ｜ **区间**：`v0.4.0 → v0.4.1`
+**规模**：6 commits + 收尾文档；源码 8 文件 +570 / −213（含全量测试与文档 20 文件 +1134 / −237）；
+新增源码模块 1 个（`src/dsh-paths.ts`）；测试套件仍为 6 套，新增 13 个场景
+
+v0.4.1 是一次**纯修复与可见性**版本：把 v0.3.1 以来全部 TypeScript 变更的代码审查
+（`docs/code-review/ts-review-since-v0.3.1.zh.md`）逐条落地。**配置文件格式没有任何变化**，
+唯一可见的输出变化是 CLI 写出的 JSON 条目现在带显式 `type`。
+
+---
+
+## 亮点速览
+
+| 主题 | 一句话 |
+|---|---|
+| ⚠️ 项目侧压制不再自伤 | 只 deny「本轮真会全局装载」的名字，不再误伤项目自己的工具或宿主 patch |
+| `$DSH_HOME` 全链路生效 | 用户层三文件、全局诊断、CLI 读写路径统一走 `src/dsh-paths.ts` |
+| 坏条目不再被顺手删掉 | `mcpServers` 里的非对象条目跨读-改-写原样保留，可被指名删除 |
+| yml 写入并发安全 | 新增 `updateManagedRows`：读-改-写全在锁内，`EACCES` 不再被吞成「文件缺失」 |
+| 遮蔽诊断按层归因 | 纯用户层冲突只写全局诊断，零配置项目不再被动创建 `.mcp-diag.json` |
+| 告警按变化门控 | 文件错误、坏条目、`name-taken` 只在集合变化时告警一次 |
+| CLI 提示双真相 | `add` 提示新行会不会被遮蔽，`remove` 说明同名定义接管 |
+| `DSH_MCP_PROFILE` 校验 | `../../somewhere` 不再被拼进 profiles 目录 |
+
+---
+
+## 修复
+
+### 项目侧压制只 deny 真会全局装载的名字（`src/registry.ts`）
+
+两个静默自伤场景：用户层 `~/.dsh/mcp.yml` 里的 `disabled: true` 占名行，以及被宿主全局
+patch 行顶掉（`name-taken`）的用户层行——两者都**不产生全局实例**，却照旧进了该项目的
+压制集合。压制按 `mcp__<原名>__` 前缀展开，于是 deny 打到了项目自己的服务器（它的生效名
+从未改名）或宿主 patch 实例上，而快照仍报 `fiberPhase: "active"`、没有 `skipReason`。
+
+修复：把用户层合并结果与「宿主已占名」集合前移到项目循环之前，`suppressedGlobals`
+只收真正会全局装载的名字；`sweepRestrictions` 再加一道「该名字当前确有全局实例」的守卫。
+
+### `$DSH_HOME` 重定位不再让用户层整体消失（`src/dsh-paths.ts`）
+
+此前用户层路径、全局诊断与 CLI 各处都硬编码 `homedir()/.dsh`，与 README 承诺的
+「dshHome 默认 `%USERPROFILE%\.dsh`，设置了 `DSH_HOME` 则用其值」相矛盾。重定位后
+用户层三文件全部指向不存在的路径，而「文件缺失」是合法的零配置状态，所以**没有任何告警**。
+
+新模块 `src/dsh-paths.ts` 成为唯一解析口径：`dshHomeDir(home, env)` / `dshHomeFor()` /
+`userLayerPathsIn()` / `profileMcpJsonFile()`。注入的路径（registry 的 `userLayerPaths`、
+CLI 的 `deps.home`）仍然优先于环境变量，测试才能与本机真实配置隔离。
+
+### 其余修复
+
+- **`remove` 说明同名接管**：yml 与 json 同时有同名行时，仍只删首个命中，但会打印
+  接下来由哪个文件的定义接管生效；再执行一次才真正清空。
+- **坏条目跨写入保留**：`readJsonServers`/`updateJsonServers` 不再过滤非对象条目，
+  手写的 `"legacy": "node x.js"` 不会被无关的 `add`/`remove` 永久删除，判重能看到它占的名，
+  `dsh-mcp remove legacy` 可以清掉它。
+- **yml 写路径锁内读-改-写**：`updateManagedRows(path, mutate, options)` 取代「锁外预读 +
+  锁内整体替换」，并发两个 `add` 不再互相丢行；`createIfMissing` 收紧为只接受 `ENOENT`，
+  `EACCES` 与损坏的受管块不再被当成「文件缺失」而被覆盖。
+- **`DSH_MCP_PROFILE` 先校验再拼路径**：不匹配 `^[A-Za-z0-9][A-Za-z0-9._-]*$`（含显式的
+  `.` / `..`）时按「解析不出 profile」降级并告警一次，不再读到 profiles 目录之外。
+- **`serverView` 的用户层作用域**：报 `global` + 层文件路径，与快照分区口径一致
+  （原先固定报 `workspace` + 项目根）。
+
+---
+
+## 变更
+
+- **遮蔽诊断按层归因**：`IdentityShadow` 带上失败方与胜出方的来源，新增 `shadowedGlobal`
+  桶记录用户层之间的精确同名遮蔽（此前零可见性）。只涉及用户层的冲突在
+  `<dshHome>/.mcp-diag.json` 全局报一次；项目侧只保留至少一方是项目层行的条目，
+  零配置项目不再因为两个用户层文件互相冲突而被创建 `.dsh/.mcp-diag.json`。
+- **告警按变化门控**：文件级错误、坏条目、`name-taken` 集合只在集合本身变化时告警，
+  不再每轮对账每项目重刷；`skipReason` 照旧每轮写入，快照仍能查到原因。
+- **`name-taken` 文案**改为「宿主全局 patch 行（bundle 层或 profile patch 层）」，
+  与 `globalNames()` 实际收集的范围一致。
+- **CLI 写出的 JSON 条目带显式 `type`**（`stdio` / `http`），便于要求该键的生态工具消费；
+  本插件自己的读取器仍然可以推断。
+- **`add` 写入后复核**：新行被更高优先层按名字或按同服务遮蔽时提示「不会装载」，
+  同作用域另一方言文件也有定义时提示条目数。
+- **JSON 读取失败带 errno**（`读取失败（EACCES）`），错误串不含文件内容。
+- **`rowNameOf` 移入 `src/model.ts`** 由装载器与 CLI 共用：受管行 id 优先于
+  `config.serverName`。CLI 此前口径相反，id 与 `config.serverName` 不一致的行
+  没法用装载器实际使用的名字删除。
+- **内部清理**：`reconcileAll` 的项目循环体抽成 `scanProject`；逐项目 Map 按本轮 known keys
+  剪枝；`planProjectChanges` 的 O(n²) 查找改 Map；`activeProfile()` 经 `Promise.resolve`
+  兜住同步抛错；CLI 消除 `.dsh` / `mcp.yml` 字面量重复，`getMissMessage` 改用实际查过的层。
+
+---
+
+## 文档
+
+- `docs/guide/layers.md` / `.zh.md`：补记 v0.4.0 起遗留 `.mcp.json` 层的三处行为变化——
+  条目级显式 `cwd` 现在生效、DSH 透传键（`toolCallTimeoutMs`/`failOnStartupError`/`reconnect`）
+  现在生效、`disabled: true` 从「静默跳过不占名」改为「占名不装载」。
+- `docs/guide/cli.md` / `.zh.md`：`-f`（`--format`）与 `-p`（`--profile`）自 v0.4.0 起是本 CLI
+  的保留短名，会吞掉下一个词元；要传给被 spawn 命令的同名参数写在 `--` 之后。
+- `CHANGELOG.md`：补记快照消费方须知——全局层分区的 `project` 字段自 v0.4.0 起是**层文件
+  自身所在目录**（`mcp.yml`/`mcp.json` 为 dshHome，profile 文件为 `profiles/<name>`），
+  v0.3.1 报的是 `.dsh` 的父目录（家目录）。`dsh-skill-mcp-panel` 等消费方按「层自己的目录」读。
+
+---
+
+## 升级
+
+无需改动任何配置文件，无破坏性变更：
+
+- 设置了 `DSH_HOME` 的机器，用户层会从**它下面**读取（这是 README 一直承诺的行为，
+  此前的静默失效是缺陷）。若之前依赖「无论 `DSH_HOME` 如何都读 `%USERPROFILE%\.dsh`」，
+  把文件移到 `$DSH_HOME` 下即可。
+- CLI 新写出的 JSON 条目多一个 `type` 键；既有文件不会被改写。
+- 快照 / 诊断的字段只有新增（`shadowedGlobal`、`IdentityShadow.source` 与 `winnerSource`）。
+
+安全边界不变：`stdio` 行仍在 dsh 宿主进程里 spawn `command`，项目与用户层配置文件都是
+可执行代码载体，只在可信项目里启用。

package/docs/releases/v0.4.2.md

@@ -1,65 +1,65 @@
-# 发布说明 v0.4.2（质量门禁收口）
-
-[← 返回 README](../README.zh.md) ｜ 相关：[v0.4.1 发布说明](v0.4.1.md)
-
-**发布日期**：2026-09-16 ｜ **区间**：`v0.4.1 → v0.4.2`
-**规模**：代码修复 1 commit + 锁文件元数据 1 commit + 发布 1 commit；
-源码与测试 8 文件 +106 / −54，无新增模块，测试套件与用例数不变（6 套 101 例全绿）
-
-v0.4.2 是一次**纯代码质量**版本：清零 PR #7 上 Sonar「New Code 可靠性评级 = D」
-门禁的全部 15 项告警（12×S2871、1×S3776、1×S7778、1×S1199）。
-**没有任何用户可见的行为变化**——每一处修改要么是把代码原本就在做的语义显式写出来，
-要么是内部拆分。
-
----
-
-## 修复
-
-### 字符串排序全部改用显式比较器（12 项 CRITICAL，S2871）
-
-`Array.prototype.sort()` 不带比较器的写法被静态分析判为可靠性缺陷（默认序随元素
-`toString` 漂移）。新增 `src/model.ts` 导出的具名比较器：
-
-```ts
-export function byCodeUnit(a: string, b: string): number {
-  if (a < b) return -1;
-  if (a > b) return 1;
-  return 0;
-}
-```
-
-它就是 UTF-16 码元序——与 `sort()` 默认行为**逐字节等价**，所以全部排序结果的既有
-顺序不变、测试零改动。刻意不用 `localeCompare`：诊断/快照的键集顺序、告警门控签名、
-`list` 输出序都是 wire 可见的，不能交给宿主机的 locale 决定。落点：
-`src/registry.ts` 6 处（canonicalConfig、两个签名函数、两路 watcher 键、blocked 集）、
-`src/cli.ts` 1 处（profile 枚举）、五个测试文件 8 处（含未被标记的同类，一并对齐）。
-
-### `scanProject` 认知复杂度 24 → 约 6（S3776）
-
-两处无损拆分（`src/registry.ts`）：
-
-- 同服务剔除告警 + 变更门控（签名比对、告警循环）抽为方法
-  `warnIdentityShadows(key, projectRoot, identityShadows): boolean`，返回
-  `shadowChanged` 供诊断条件使用；
-- scan 诊断的「值不值得写」大 || 条件与载荷字段抽为纯函数
-  `buildScanDiag(input): Record<string, unknown> | null`，返回 `null` 即
-  「干净且无配置」——**零配置项目不留痕**的约定原样保持，写入的载荷逐字段等价。
-
-### 其余两项 MINOR（S7778 / S1199）
-
-- `src/cli.ts` `collectLayers` 末尾两次 `layers.push` 合并为单次调用（实参自左向右
-  求值，六层影子优先序不变）。
-- `test/test-model.mjs` 第 17 用例去掉冗余裸块。
-
----
-
-## 依赖元数据
-
-`pnpm-lock.yaml` 的 `@deepseek-ai/cordis` importer specifier 由 `^4.0.1` 同步为
-`^4.0.2`——`package.json` 自 v0.4.1 起声明的就是 `^4.0.2`（解析版本一直是 `4.0.2`），
-此前锁文件差一行元数据导致 pnpm 每次运行都要求重锁。不改依赖解析结果。
-
-## 升级
-
-无破坏性变更，无需任何操作：不写不改任何配置文件，装载、deny、诊断、CLI 输出与
-v0.4.1 完全一致。
+# 发布说明 v0.4.2（质量门禁收口）
+
+[← 返回 README](../README.zh.md) ｜ 相关：[v0.4.1 发布说明](v0.4.1.md)
+
+**发布日期**：2026-09-16 ｜ **区间**：`v0.4.1 → v0.4.2`
+**规模**：代码修复 1 commit + 锁文件元数据 1 commit + 发布 1 commit；
+源码与测试 8 文件 +106 / −54，无新增模块，测试套件与用例数不变（6 套 101 例全绿）
+
+v0.4.2 是一次**纯代码质量**版本：清零 PR #7 上 Sonar「New Code 可靠性评级 = D」
+门禁的全部 15 项告警（12×S2871、1×S3776、1×S7778、1×S1199）。
+**没有任何用户可见的行为变化**——每一处修改要么是把代码原本就在做的语义显式写出来，
+要么是内部拆分。
+
+---
+
+## 修复
+
+### 字符串排序全部改用显式比较器（12 项 CRITICAL，S2871）
+
+`Array.prototype.sort()` 不带比较器的写法被静态分析判为可靠性缺陷（默认序随元素
+`toString` 漂移）。新增 `src/model.ts` 导出的具名比较器：
+
+```ts
+export function byCodeUnit(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+```
+
+它就是 UTF-16 码元序——与 `sort()` 默认行为**逐字节等价**，所以全部排序结果的既有
+顺序不变、测试零改动。刻意不用 `localeCompare`：诊断/快照的键集顺序、告警门控签名、
+`list` 输出序都是 wire 可见的，不能交给宿主机的 locale 决定。落点：
+`src/registry.ts` 6 处（canonicalConfig、两个签名函数、两路 watcher 键、blocked 集）、
+`src/cli.ts` 1 处（profile 枚举）、五个测试文件 8 处（含未被标记的同类，一并对齐）。
+
+### `scanProject` 认知复杂度 24 → 约 6（S3776）
+
+两处无损拆分（`src/registry.ts`）：
+
+- 同服务剔除告警 + 变更门控（签名比对、告警循环）抽为方法
+  `warnIdentityShadows(key, projectRoot, identityShadows): boolean`，返回
+  `shadowChanged` 供诊断条件使用；
+- scan 诊断的「值不值得写」大 || 条件与载荷字段抽为纯函数
+  `buildScanDiag(input): Record<string, unknown> | null`，返回 `null` 即
+  「干净且无配置」——**零配置项目不留痕**的约定原样保持，写入的载荷逐字段等价。
+
+### 其余两项 MINOR（S7778 / S1199）
+
+- `src/cli.ts` `collectLayers` 末尾两次 `layers.push` 合并为单次调用（实参自左向右
+  求值，六层影子优先序不变）。
+- `test/test-model.mjs` 第 17 用例去掉冗余裸块。
+
+---
+
+## 依赖元数据
+
+`pnpm-lock.yaml` 的 `@deepseek-ai/cordis` importer specifier 由 `^4.0.1` 同步为
+`^4.0.2`——`package.json` 自 v0.4.1 起声明的就是 `^4.0.2`（解析版本一直是 `4.0.2`），
+此前锁文件差一行元数据导致 pnpm 每次运行都要求重锁。不改依赖解析结果。
+
+## 升级
+
+无破坏性变更，无需任何操作：不写不改任何配置文件，装载、deny、诊断、CLI 输出与
+v0.4.1 完全一致。

package/docs/releases/v0.4.3.md

@@ -0,0 +1,54 @@
+# 发布说明 v0.4.3（对齐 dsh 0.1.5-rc.1）
+
+[← 返回 README](../README.zh.md) ｜ 相关：[v0.4.2 发布说明](v0.4.2.md) ·
+[dsh 0.1.5-rc.1 适配记录](../design/adaptation-dsh-0.1.5-rc1.md)
+
+**发布日期**：2026-09-10 ｜ **区间**：`v0.4.2 → v0.4.3`
+**规模**：依赖对齐 1 commit + 适配记录 1 commit + 发布 1 commit；
+无源码与测试改动，测试套件与用例数不变（6 套 101 例全绿）
+
+v0.4.3 是一次**宿主对齐**版本：把运行时依赖从 dsh 0.1.2-rc.1 线升到
+0.1.5-rc.1，避免已发布的 v0.4.2 在新宿主里继续装入自带的旧 mcp-client
+副本。**没有任何用户可见的行为变化**——配置格式、装载语义、deny 隔离与
+CLI 输出与 v0.4.2 完全一致。
+
+---
+
+## 变更
+
+### `@deepseek-ai/dsh-mcp-client` `^0.1.2-rc.1` → `^0.1.5-rc.1`
+
+`^0.1.2-rc.1` **不会**解析到 `0.1.5-rc.1`：npm semver 要求带 prerelease 的
+候选版本与比较符的 major.minor.patch 元组相同。v0.4.2 因此在 dsh 0.1.5-rc.1
+宿主进程里加载插件自带的 0.1.2-rc.1 客户端及其 0.1.2-rc.1 peer
+（`dsh-tools` / `dsh-scope` / `dsh-timeout` 等）。
+
+升到 `^0.1.5-rc.1` 后，mcp-client 与全部 peer 解析到 **0.1.5-rc.1**，与宿主
+同版。pnpm 12 为这批刚发布的 rc 写入 `pnpm-workspace.yaml` 的
+`minimumReleaseAgeExclude`，否则供应链门禁会挡住安装。
+
+静态核对：`tools.restrict`、`agents.list` / `isOwnedBy`、会话事件名、
+mcp-client `Config`、`serverName` 约束、`mcp__<name>__<tool>` 命名与
+`MAX_TIMER_DELAY_MS` 均无断裂。实现 diff 仅 `tools/list` 增加重复
+continuation cursor 校验。
+
+隔离实机：`ProjectMcpRegistry` 读项目 `.dsh/mcp.yml` 后
+`scan` → `attempt` → `active`，`mcp__compat-probe__probe` →
+`pong:compat-015`。完整记录见
+[适配记录](../design/adaptation-dsh-0.1.5-rc1.md)。
+
+---
+
+## 升级
+
+无破坏性变更，无需改任何配置文件。
+
+已装 v0.4.2 且宿主已升到 dsh 0.1.5-rc.1 的 profile，把插件升到 v0.4.3
+即可去掉进程内双副本：
+
+```powershell
+dsh plugin --profile <p> add dsh-project-mcp-manager@0.4.3
+```
+
+本地 link 开发：`pnpm install` 后确认
+`@deepseek-ai/dsh-mcp-client` 解析为 `0.1.5-rc.1`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-project-mcp-manager",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "packageManager": "pnpm@12.3.4",
   "description": "dsh-project-mcp-manager: per-project and global MCP server loading for DSH. Reads <projectRoot>/.dsh/mcp.yml or .dsh/mcp.json (plus the read-only Claude Code project file .mcp.json), mounts project rows per project and user-layer rows (~/.dsh/mcp.yml, ~/.dsh/mcp.json, ~/.dsh/profiles/<name>/mcp.json) globally as @deepseek-ai/dsh-mcp-client instances with ${VAR} env expansion at mount time, hot-reloads on file change, scopes tool visibility per session, and ships a dsh-mcp CLI that writes either native yml or DSH JSON.",
   "type": "module",
@@ -28,7 +28,7 @@
     "cordis"
   ],
   "dependencies": {
-    "@deepseek-ai/dsh-mcp-client": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-mcp-client": "^0.1.5-rc.1",
     "chokidar": "^5.0.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"