dsh-project-mcp-manager 0.6.0 → 0.7.2

package/docs/design/adaptation-dsh-0.2.0-rc.2.md

@@ -0,0 +1,89 @@
+# 适配记录：dsh v0.2.0-rc.2
+
+[← 返回 README](../README.zh.md) ｜ 相关：[dsh 0.1.6-alpha.2 适配方案](adaptation-dsh-0.1.6-alpha.2.md) ·
+[dsh 0.1.5-rc.2 适配记录](adaptation-dsh-0.1.5-rc2.md) ·
+[v0.7.0 发布说明](../releases/v0.7.0.md)
+
+**记录日期**：2026-09-30 ｜ **插件**：`dsh-project-mcp-manager` v0.7.0
+**宿主**：本机 `dsh` 0.2.0-rc.2（`dsh --version`）。对照源码
+`D:\Projects\Agent\deepseek-harness`，标签 `dsh-v0.1.5-rc.2` → `dsh-v0.2.0-rc.2`
+（发布包 `@deepseek-ai/dsh-mcp-client@0.2.0-rc.2`、cordis 4.0.4、
+cordis-plugin-include 1.0.9、cordis-plugin-loader 1.0.5）。
+实机只用 **headless** profile（`~/.dsh/profiles/headless` 以 junction 链到本仓库）。
+
+**结论**：官方没有接过本插件的项目级发现、按会话 cwd 隔离和 `dsh-mcp` CLI。
+v0.6.0 的依赖范围解析不到 0.2.0 的 client，且 `agent/session-start` 已删除、
+`maxInstructionBytes` 会被静默丢掉。v0.7.0 按这三处对齐后，headless 实机可以
+装载探针并调用 `mcp__compatprobe__probe`。
+
+---
+
+## 1. 官方已经覆盖、本插件不再独占的能力
+
+对照 `packages/mcp` 与 profile 装配（0.1.5-rc.2 之后、0.2.0-rc.2 之前落地，
+0.2.0-rc.2 相对 0.1.6-alpha.2 的 client 源码几乎只剩类型收紧）：
+
+| 能力 | 官方现状 | 本插件 |
+|---|---|---|
+| 全局 / 每 profile 声明 MCP | `$DSH_HOME` 与 profile 的 Cordis patch，一行一个 `dsh-mcp-client` | 用户层 yml/json 仍是更短的写法，挂载后仍是官方 client |
+| profile 配置热重载 | 官方 HMR，作用在 profile 配置层 | 不替代。项目文件仍由本插件 chokidar 监听 |
+| 运行时加服务器 | `plugin_manager` 与 configuration-only bundle | 不替代 |
+| 协议、分页、重连、instructions | client 内建；SDK `@modelcontextprotocol/client@2.0.0` | 不碰协议 |
+| MCP resources 与服务器提示节 | `mcp-resources` 进 base bundle；client 经 `registerServerContext` 登记 | 升级到同一份 client 后，本插件挂上的服务器自动出现在资源工具里 |
+| 工具名 | 干净时仍是 `mcp__<serverName>__<rawName>`；不合函数名契约时追加 12 hex | deny 展开仍用已注册的精确名 |
+
+源码与文档里没有 `<projectRoot>/.dsh/mcp.yml`、`.dsh/mcp.json` 或项目级
+`.mcp.json` 的装载器。`docs/user/guide/mcp-memory.md` 仍是 profile overlay。
+会话 cwd 只用于文件工具和工作区指令，没有「cwd → 该项目 MCP 工具可见性」的映射。
+
+本插件继续留下的三件事：
+
+1. 项目级配置发现（含只读遗留 `.mcp.json`）与六层影子合并。
+2. 按会话 cwd 的 `tools.restrict({ deny })`。
+3. MCP 专用格式与 `dsh-mcp` CLI。
+
+---
+
+## 2. 对插件有影响的破坏性变更
+
+| 点 | 0.1.5-rc.2 → 0.2.0-rc.2 | 处置 |
+|---|---|---|
+| 依赖范围 | `^0.1.5-rc.1` 解析不到 `0.2.0-rc.2`（预发布必须同一 major.minor.patch 元组） | 下限改为 `^0.2.0-rc.2`。0.1.5 用户留在 v0.6.0 |
+| `agent/session-start` | 事件删除。`agent/created` 变为 `{ agent, source: 'startup'\|'resume'\|'clear'\|'compact', signal? }`，`ctx.serial` 派发 | 删除该监听。现有 `agent/created` 只解构 `agent`，仍然成立。构造时 `liveAgents()` 补扫保留 |
+| Config | 两个传输各增加可选 `maxInstructionBytes`（int ≥ 1，默认 32768）。超限拒绝这一次连接 | schema / `toOfficialConfig` / JSON 透传。缺省不写键。CLI 不加参数 |
+| cordis | 4.0.2 → 4.0.4。include 1.0.7 → 1.0.9，loader 1.0.3 → 1.0.5 | 开发依赖 `^4.0.4`。`ctx.plugin` / `ctx.on` / `ctx.provide` / `config.patches` 仍在 |
+| client peer | 发布包 peer 钉死 `0.2.0-rc.2`（tools、scope、timeout、attachment、llm、subprocess；resources 与 system-prompt 可选）。直接依赖换成 schemastery、`dsh-util-values`、MCP client SDK 2.0.0 | 锁文件跟着解析。pnpm 12 把这批 rc 写入 `minimumReleaseAgeExclude` |
+| stdio 环境 | 子进程环境 = 清洗后的父环境 + 配置 `env`。名字匹配凭据或 `DSH_*` 的环境变量不继承 | 文档说明。本插件展开进 `env` 的值仍是显式配置 |
+| 结果形状 | 不再接受 legacy `toolResult`；无 tools capability 的服务器保持连接、工具集为空 | 不改装载逻辑。调用期错误仍不经过本插件 |
+| `apply` | 等待初次连接。`failOnStartupError: false` 时失败只打日志并进入官方重连，fiber 仍 resolve | 与现有 `trackMount` 一致：fiber resolve 即 `active`，0 工具的首连交给官方重连 |
+| `tools.restrict` / `schemas()` | 仍要求 agent 作用域上的精确工具名；`schemas()` 多了可选 `deferLoading` | 本插件本来就走 `agent.ctx.tools.restrict` 并按 `name` 读 schema |
+| `session.header.cwd` | 仍在 | 项目发现路径不变 |
+| 传输集合 / serverName / `MAX_TIMER_DELAY_MS` | 仍是 `stdio` \| `streamable-http`，`[A-Za-z0-9_-]{1,32}`，`2147483647` | 常量注释改为 0.2.0-rc.2，值未改 |
+
+0.2.0-rc.1 → 0.2.0-rc.2 的 client 源码差异是一处类型断言，没有新的配置字段。
+
+---
+
+## 3. 实机（headless profile）
+
+`dsh --profile headless --dump-config` 合成树含 `# == dsh-project-mcp-manager` /
+`- id: mcp-project`。插件包是 junction：`link:D:/Projects/Agent/dsh-mcp-project`。
+
+临时 git 仓库 `compatprobe`（stdio 探针，`initialize` 带回 `instructions: "hello from probe"`，工具 `probe` → `pong:compat-020`）：
+
+| 检查 | 结果 |
+|---|---|
+| `maxInstructionBytes: 16` | 子进程收到 `initialize` 与 `notifications/initialized`，**没有** `tools/list`（超限发生在同步工具之前）。`failOnStartupError` 默认 false，诊断仍记 `active` |
+| `maxInstructionBytes: 65536` | 收到 `tools/list`。模型调用 `mcp__compatprobe__probe` → `pong:compat-020` |
+| mcp-resources 协同 | 同一轮里 `list_mcp_resources` 的 `server` 参数接受 `compatprobe`（共享资源工具能看见本插件挂上的服务器） |
+| 单测 | `pnpm test` 六套全绿 |
+
+未改本机 `~/.dsh` 的模型设置。headless 使用当前默认模型完成了上述调用。
+
+---
+
+## 4. 代码改动
+
+- `package.json`：`dsh-mcp-client` `^0.2.0-rc.2`，`cordis` `^4.0.4`，版本 0.7.0。
+- `src/registry.ts`：去掉 `agent/session-start`。
+- `src/model.ts`、`src/json-file.ts`、`src/json-write.ts`：透传 `maxInstructionBytes`。

package/docs/design/proposal-runtime-robustness-and-json-interop.md

@@ -238,6 +238,8 @@
 **提案**：以官方 storageDomain/service 模式 `ctx.provide("projectMcp", { snapshot, serverView, globalState, reload })`，并补类型声明合并。插件现有导出面（`inject = ["tools","agents"]`、`globalNames()`、`activeProfile()`）保持不变。
 
 > **落地口径（v0.6.0）**：`snapshot` / `serverView` / `globalState` 进 enqueue 与对账互斥，按上一轮 `lastScanFiles` / `userLayer` 内存拼装，不读盘、不跑 `reconcileAll`；`reload` 才对账一次。
+>
+> **后续口径**：配套 UI 独立成包后即为稳定消费方。方法、`projectMcp/updated`（对账成功结束、无载荷）与包入口导出的视图类型按语义化版本承诺；UI 包以精确版本 peer-depend 本包。浏览器 SSE 仍由 UI 自建。见 [查询面](../guide/service.zh.md)。上面「不承诺稳定 API」只保留为 v0.6.0 当时的裁决。
 
 **风险**：服务名与稳定性承诺需评审；`reload` 的语义限定为"触发一次 reconcileAll"。
 
@@ -375,6 +377,6 @@ C3 本轮跳过。
 2. **A4 键名与语法**：`tools.allow`/`tools.deny`，同时读取 `includeTools`/`excludeTools`；**完整 glob**（`*`、`**`、`?`、`[…]`）。
 3. **A5 作用域**：允许 `--scope project|user|profile`；缺省 **project**（与 `add` 一致）。
 4. **B1 卸载策略**：无会话且非进程 cwd 后 **5 分钟宽限**再卸载。
-5. **B3 服务名与稳定性**：服务名 `projectMcp`；**不承诺稳定 API**。
+5. **B3 服务名与稳定性**：服务名 `projectMcp`。v0.6.0 落地时不承诺稳定 API；配套 UI 独立成包后改为对它按语义化版本承诺，见 [查询面](../guide/service.zh.md)。
 6. **C1 opt-in**：**只报错**，无 `sseAsStreamableHttp`，无环境开关。
 7. **C3 默认值与层序**：**本轮不做**（不读 `.vscode/mcp.json`）。

package/docs/guide/env-expansion.md

@@ -24,3 +24,10 @@ the reason rides on a separate `skipReason` field (`env-missing` /
 [configuration sources and layers](layers.md)). Values are never
 persisted anywhere by the plugin; the CLI writes `${VAR}` through literally,
 so secrets can live in the environment while configs live in git.
+
+From dsh 0.2, the official stdio transport builds the child environment from a
+scrubbed parent (ambient names matching `/KEY|PASSWORD|SECRET|TOKEN/i` and
+ambient `DSH_*` are dropped) and then overlays the configured `env`. A secret
+this plugin interpolates into `env` or `headers` is explicit config and is
+kept. A secret that exists only as an ambient variable, and is not written
+into `env`, is no longer inherited by the child.

package/docs/guide/env-expansion.zh.md

@@ -18,3 +18,8 @@
 `plugin-throw`；其它如 `name-taken` / `idle` / `give-up` 见
 [配置来源与分层](layers.zh.md)）。插件任何写路径都不落盘展开后的值；
 CLI 写入时 `${VAR}` 原样保留——配置可以进 git，凭据留在环境里。
+
+dsh 0.2 起，官方 stdio 传输的子进程环境是「清洗后的父进程环境 + 配置里的
+`env`」。父进程里名字匹配 `/KEY|PASSWORD|SECRET|TOKEN/i` 的变量，以及环境中的
+`DSH_*`，不会继承给子进程。本插件把 `${VAR}` 展开进 `env` / `headers` 的值属于
+显式配置，会保留。只存在于环境、没有写进 `env` 的凭据，子进程再也拿不到。

package/docs/guide/format.md

@@ -67,7 +67,12 @@ file fail with an explicit error (logged and written to `.dsh/.mcp-diag.json`)
 instead of silently mounting the expression text as a literal string. Values
 in `env`/`headers` are otherwise literal, except for `${VAR}` references
 which are interpolated at mount time (see [`${VAR}` expansion](env-expansion.md));
-`disabled` must be `true`/`false`. The project file is otherwise a superset
+`disabled` must be `true`/`false`. Optional `maxInstructionBytes` (integer ≥ 1)
+is the official cap on attributed server instructions, default 32768 when the
+key is omitted. An oversized instruction rejects that connection inside
+`dsh-mcp-client` (the row still activates when `failOnStartupError` is false,
+then follows the official reconnect loop). `dsh-mcp` has no flag for this
+field; write it in the file. The project file is otherwise a superset
 grammar: `env`/`headers` accept `KEY: null` to delete a key (stripped at
 mount), which the official mcp-client schema rejects — such lines would fail
 if moved back to `cordis.patch.yml`.
@@ -97,7 +102,7 @@ Follows the ecosystem (Cursor / Claude Code's `mcpServers` shape):
   already speaks Streamable HTTP, change `type` to `"http"`; or drop `type`
   and keep `url` (this plugin infers streamable-http). There is no implicit
   fallback. The DSH passthrough keys
-  `toolCallTimeoutMs`/`failOnStartupError`/`reconnect`, `enabled: false`
+  `toolCallTimeoutMs`/`failOnStartupError`/`maxInstructionBytes`/`reconnect`, `enabled: false`
   (silently skipped, claims no name) and `disabled: true` (claims its name but
   is not mounted).
 - Unknown keys are tolerated and ignored; names must match

package/docs/guide/format.zh.md

@@ -62,7 +62,11 @@ process.env.GITHUB_TOKEN }`）在项目文件里**不支持**——受管块内
 标签会使该文件整体报错跳过（写入 `.dsh/.mcp-diag.json` 并打日志），不会把
 表达式当字面量字符串静默装载。`env`/`headers` 的值其余情况下是字面量，仅
 `${VAR}` 引用会在装载时做串内插值（见 [`${VAR}` 展开](env-expansion.zh.md)）；
-`disabled` 只能是 `true`/`false`。反之项目文件是超集语法：`env`/`headers`
+`disabled` 只能是 `true`/`false`。可选 `maxInstructionBytes`（整数 ≥ 1）是官方对
+「带归属头的服务器 instructions」的字节上限；省略该键时用官方默认 32768。
+超限由 `dsh-mcp-client` 拒绝这一次连接（`failOnStartupError` 为 false 时本插件
+仍把 fiber 标成 active，随后走官方重连）。`dsh-mcp` 没有对应参数，直接写进文件。
+反之项目文件是超集语法：`env`/`headers`
 允许 `KEY: null` 表示删除该键（装载时被剔除），这在官方 mcp-client 校验里会被
 拒绝——把这类行原样挪回 `cordis.patch.yml` 会装载失败。
 
@@ -89,7 +93,7 @@ process.env.GITHUB_TOKEN }`）在项目文件里**不支持**——受管块内
   （`dsh-mcp-client`）只支持 `stdio` 与 streamable-http——服务端已支持
   Streamable HTTP 时把 `type` 改为 `"http"`；或删除 `type` 只留 `url`
   （本插件按 streamable-http 推断）。没有隐式回退。DSH 透传键
-  `toolCallTimeoutMs`/`failOnStartupError`/`reconnect`、`enabled: false`
+  `toolCallTimeoutMs`/`failOnStartupError`/`maxInstructionBytes`/`reconnect`、`enabled: false`
   （静默跳过、不占名）与 `disabled: true`（占名但不装载）。
 - 未知键容忍忽略；名字须匹配 `[A-Za-z0-9_-]{1,32}`；坏条目逐条报错、不影响其余。
 - **JSON 文件由 `dsh-mcp` CLI 独占**：写入保留其他顶层键与键序，但 JSON 没有注释，

package/docs/guide/service.md

@@ -0,0 +1,95 @@
+# Query surface (`projectMcp`)
+
+English | [中文](service.zh.md)
+
+[← README](../../README.md) ｜ Related: [configuration sources and layers](layers.md) · [CLI `dsh-mcp`](cli.md)
+
+Other plugins and the companion UI read mount state through the cordis service
+`ctx.projectMcp`. This package stays in-process: it emits one event when a
+reconcile finishes. The browser still uses the SSE channel the companion UI
+builds itself.
+
+## Methods
+
+| Method | Behavior |
+|---|---|
+| `snapshot()` | In-memory partitions from the previous reconcile (project files and the user layer). Joins the reconcile queue, does not read disk, and does not start a reconcile. |
+| `serverView(projectRoot, rawName)` | One row's in-memory view. Same queue rules as `snapshot()`. |
+| `globalState(rawName)` | Live global-layer state for that raw name, or `undefined` for a project row. |
+| `reload()` | One full reconcile (`reconcileNow`). |
+
+`snapshot()` / `serverView()` / `globalState()` do not emit.
+
+## Event
+
+After every **successful** `reconcileAll` — including a fingerprint hit that
+still runs the health check, session deny sweep, tool budget, and summary —
+the registry emits:
+
+```ts
+ctx.on("projectMcp/updated", async () => {
+  const snapshot = await ctx.projectMcp.snapshot();
+});
+```
+
+The event name is `PROJECT_MCP_UPDATED_EVENT` (`"projectMcp/updated"`). There
+is no payload and no diff. Dispatch is synchronous and does not await a
+listener's promise. The listener reads `snapshot()` or `serverView()` and
+compares with what it last pushed. An early return (`disposed`) or a throw
+inside reconcile does not emit. A listener that throws is logged
+(`项目 MCP 变更事件投递失败：…`) and does not fail the reconcile.
+
+## Types
+
+Named view types are exported from the package entry. The `exports` map does
+not allow a deep import of `lib/registry.js`.
+
+```ts
+import {
+  PROJECT_MCP_SERVICE,
+  PROJECT_MCP_UPDATED_EVENT,
+  type FiberPhaseView,
+  type McpRowSource,
+  type McpScopeInfo,
+  type McpServerRuntimeView,
+  type McpServerView,
+  type McpTransport,
+  type PatchRow,
+  type ProjectFileState,
+  type ProjectMcpService,
+  type ProjectServerPhase,
+  type ProjectServerState,
+  type ReconnectConfig,
+  type ToolFilter,
+} from "dsh-project-mcp-manager";
+```
+
+`ProjectFileState` is what `snapshot()` returns. Each row is an
+`McpServerRuntimeView` (`McpServerView` plus `source`, `fiberPhase`,
+`skipReason`, and `toolCount`). `globalState()` returns `ProjectServerState`.
+
+## Semver for the companion UI
+
+`projectMcp`'s methods, the `projectMcp/updated` event, and the view types
+exported above follow semantic versioning **for the companion UI**:
+
+| Bump | What it means for this surface |
+|---|---|
+| patch | Fixes that keep the methods, the event, and the view shape. |
+| minor | Additive fields, methods, or events. |
+| major | Removals, renames, or a change in meaning. |
+
+The companion UI lists this package as a peer dependency pinned to the **same
+exact version** (no `^` or `~`). When the surface and the UI move, they move
+together:
+
+```json
+{
+  "peerDependencies": {
+    "dsh-project-mcp-manager": "<exact version of this package>"
+  }
+}
+```
+
+Replace the placeholder with the version in this package's `package.json` at
+the release the UI is built against.

package/docs/guide/service.zh.md

@@ -0,0 +1,88 @@
+# 查询面（`projectMcp`）
+
+[English](service.md) | 中文
+
+[← 返回 README](../README.zh.md) ｜ 相关：[配置来源与分层](layers.zh.md) · [CLI `dsh-mcp`](cli.zh.md)
+
+其它插件和配套 UI 经 cordis 服务 `ctx.projectMcp` 读装载状态。本包只在进程内
+发事件：对账成功结束时通知一次。浏览器仍走配套 UI 自己建的 SSE，本包不打开那条通道。
+
+## 方法
+
+| 方法 | 行为 |
+|---|---|
+| `snapshot()` | 上一轮对账的内存分区（项目文件与用户层）。进对账队列，不读盘，不发起对账。 |
+| `serverView(projectRoot, rawName)` | 一行的内存 view。排队规则与 `snapshot()` 相同。 |
+| `globalState(rawName)` | 该原名的全局层运行态；项目行返回 `undefined`。 |
+| `reload()` | 一次全量对账（`reconcileNow`）。 |
+
+`snapshot()` / `serverView()` / `globalState()` 不发事件。
+
+## 事件
+
+每次 **成功** 的 `reconcileAll` 结束都会 emit——指纹未变、因而跳过重读、但仍跑完
+健康巡检、会话 deny、工具预算和摘要的那一轮也算。注册表调用：
+
+```ts
+ctx.on("projectMcp/updated", async () => {
+  const snapshot = await ctx.projectMcp.snapshot();
+});
+```
+
+事件名是 `PROJECT_MCP_UPDATED_EVENT`（`"projectMcp/updated"`）。无载荷，也不带
+diff。派发是同步的，不会等待监听方返回的 Promise。监听方读 `snapshot()` 或
+`serverView()`，和自己上次推出去的结果比较。对账中途因 `disposed` 返回，或对账
+内部抛错，都不发。监听方抛错会记一条 `项目 MCP 变更事件投递失败：…`，对账本身
+仍算成功。
+
+## 类型
+
+具名视图类型从包入口导出。`exports` 不开放 `lib/registry.js` 深导入。
+
+```ts
+import {
+  PROJECT_MCP_SERVICE,
+  PROJECT_MCP_UPDATED_EVENT,
+  type FiberPhaseView,
+  type McpRowSource,
+  type McpScopeInfo,
+  type McpServerRuntimeView,
+  type McpServerView,
+  type McpTransport,
+  type PatchRow,
+  type ProjectFileState,
+  type ProjectMcpService,
+  type ProjectServerPhase,
+  type ProjectServerState,
+  type ReconnectConfig,
+  type ToolFilter,
+} from "dsh-project-mcp-manager";
+```
+
+`snapshot()` 的元素类型是 `ProjectFileState`。每一行是 `McpServerRuntimeView`
+（`McpServerView` 再加 `source`、`fiberPhase`、`skipReason`、`toolCount`）。
+`globalState()` 返回 `ProjectServerState`。
+
+## 对配套 UI 的语义化版本
+
+`projectMcp` 的方法、`projectMcp/updated`，以及上面导出的视图类型，**对配套 UI**
+按语义化版本承诺：
+
+| 版本位 | 对这个面意味着 |
+|---|---|
+| patch | 修复，方法、事件和视图形状不变。 |
+| minor | 只增加字段、方法或事件。 |
+| major | 删除、改名，或改变含义。 |
+
+配套 UI 把本包写成 peer dependency，并锁定到**同一精确版本**（不要写 `^` 或 `~`）。
+查询面和 UI 一起动时，两边版本一起动：
+
+```json
+{
+  "peerDependencies": {
+    "dsh-project-mcp-manager": "<本包的精确版本>"
+  }
+}
+```
+
+把占位符换成 UI 所配套的那一版里、本包 `package.json` 的 `version`。

package/docs/releases/v0.7.0.md

@@ -0,0 +1,41 @@
+# 发布说明 v0.7.0（适配 dsh 0.2.0-rc.2）
+
+[← 返回 README](../README.zh.md) ｜ 相关：[适配记录](../design/adaptation-dsh-0.2.0-rc.2.md) ·
+[v0.6.0 发布说明](v0.6.0.md) ·
+[0.1.6-alpha.2 适配方案](../design/adaptation-dsh-0.1.6-alpha.2.md)
+
+**发布日期**：2026-09-30 ｜ **区间**：`v0.6.0 → v0.7.0`
+**宿主**：dsh `0.2.0` 线，从 `0.2.0-rc.2` 起。dsh 0.1.5 继续使用插件 v0.6.0。
+
+官方 dsh 仍不发现项目级 MCP 文件、不按会话 cwd 隔离工具、也没有 MCP 专用 CLI。
+v0.7.0 把装载后端对齐到宿主自带的 `@deepseek-ai/dsh-mcp-client@0.2.0-rc.2`，
+并补上这一版新增的配置字段。
+
+---
+
+## 亮点速览
+
+| 主题 | 一句话 |
+|---|---|
+| 依赖下限 | `@deepseek-ai/dsh-mcp-client` 抬到 `^0.2.0-rc.2`；cordis 开发依赖 `^4.0.4` |
+| 会话事件 | 删除已不存在的 `agent/session-start`；补扫由 `agent/created`（含 `source`）承担 |
+| instructions 上限 | 可选透传 `maxInstructionBytes`；缺省不写键，官方默认 32768 |
+| 定位 | 承认官方 profile patch / HMR / resources；本插件留下项目发现、会话隔离、CLI |
+
+---
+
+## 用户可见变化
+
+- 支持矩阵改为 **dsh ≥ 0.2.0-rc.2**（`0.2.0` 元组）。`^0.1.5-rc.1` 解析不到
+  `0.2.0-rc.*`，不改范围就会在新宿主里嵌一套旧 client。
+- `.dsh/mcp.yml` 与 JSON 方言可以写 `maxInstructionBytes`（整数 ≥ 1）。省略时
+  不把 32768 抄进配置。超限由官方 client 拒绝该次连接。`dsh-mcp` 不增加对应参数。
+- 官方 stdio 会丢掉父进程里名字像凭据的环境变量和 `DSH_*`。写进 `env` 并经
+  `${VAR}` 展开的值仍然传给子进程。
+
+---
+
+## 验证
+
+`pnpm test` 六套全绿（model 33 / mcp-file 7 / json-file 13 / json-write 6 /
+registry 46 / cli 21）。headless profile 实机见适配记录。

package/docs/releases/v0.7.1.md

@@ -0,0 +1,49 @@
+# 发布说明 v0.7.1（代码审查整改）
+
+[← 返回 README](../README.zh.md) ｜ 相关：[审查记录](../code-review/review-feat-adapt-dsh-0.2.0-rc.2.zh.md) ·
+[v0.7.0 发布说明](v0.7.0.md) ·
+[dsh 0.2.0-rc.2 适配记录](../design/adaptation-dsh-0.2.0-rc.2.md)
+
+**发布日期**：2026-09-30 ｜ **区间**：`v0.7.0 → v0.7.1`
+**宿主**：dsh `0.2.0` 线（从 `0.2.0-rc.2` 起），与 v0.7.0 相同；纯补丁版，配置口径与装载语义不变。
+
+v0.7.1 只落地 [feat/adapt-dsh-0.2.0-rc.2 代码审查](../code-review/review-feat-adapt-dsh-0.2.0-rc.2.zh.md)
+的意见：一处可靠性修复、一处死代码清理、两条回归测试，以及不改变语义的小重构。
+
+---
+
+## 亮点速览
+
+| 主题 | 一句话 |
+|---|---|
+| 后台任务失败可见 | 所有不 await 的入队统一走 `schedule()`，失败记一条 warn（原先完全静默） |
+| 死导出 | 删除无人引用的 `DEFAULT_MAX_INSTRUCTION_BYTES`，避免与上游默认漂移 |
+| 回归测试 | 覆盖 `agent/created`（`source: "resume"`）事件路径与「连接字段变更必拆连接」的装载计划 |
+| 小重构 | 抽 `enqueueDiag()`、放宽 `enqueue()` 签名；配置指纹的 `stat` 并发发起 |
+
+---
+
+## 变更明细
+
+- **后台入队（审查 S1 / Sonar S9383）**：构造函数的 `agent/created`、`agent/disposed`
+  与插件热更补扫三处，加上文件事件 `kick`、宽限卸载 timer、`kickSweep`，全部改走新的
+  `schedule()`——`enqueue()` 的返回值不再被丢弃，失败会记一条
+  `项目 MCP 后台任务失败：<原因>`。此前这类失败被链路完全吞掉：对账没跑成，日志里
+  什么也看不到。诊断落盘（fiber settle 后的 `active` / `failed`）仍走独立的
+  `enqueueDiag()`：同样排回对账链，但按最佳努力静默失败。
+- **死代码（审查 B1）**：删掉 `DEFAULT_MAX_INSTRUCTION_BYTES`。「缺省不写键、让官方
+  默认值生效」的口径由字段注释与四处输出（官方配置 / 受管行 / view / JSON 条目）的
+  测试固定，不需要再在本地留一份 32768。
+- **回归测试（审查 B2、B3）**：新增两条用例——
+  `agent/created` 带 `source: "resume"` 时补扫并挂载会话项目，且对被自己项目行遮蔽的
+  全局实例应用 deny（项目侧压制展开成精确工具名）；`planProjectChanges` 在
+  `maxInstructionBytes` 这类连接字段变化时产出 unmount → mount，而 `tools` 变化不拆连接。
+- **小重构（审查 S7503、S9381、S9382）**：`enqueue()` 签名放宽为 `() => T | Promise<T>`，
+  `serverView()` / `snapshot()` 去掉只为满足签名的 `async`；`trackMount` 的 fiber settle
+  回调改调 `enqueueDiag()`，消掉嵌套 Promise；配置指纹的逐文件 `stat` 改 `Promise.all`
+  并发发起（签名仍按排序后的路径逐条拼接，结果与串行一致）。
+
+## 验证
+
+`tsc --noEmit` 通过；六套测试全绿（model 33 / mcp-file 7 / json-file 13 /
+json-write 6 / registry 48 / cli 21，registry 比 v0.7.0 多两条新用例）。

package/docs/releases/v0.7.2.md

@@ -0,0 +1,37 @@
+# 发布说明 v0.7.2（查询面推送）
+
+[← 返回 README](../README.zh.md) ｜ 相关：[查询面](../guide/service.zh.md) ·
+[v0.7.1 发布说明](v0.7.1.md)
+
+**发布日期**：2026-10-02 ｜ **区间**：`v0.7.1 → v0.7.2`
+**宿主**：dsh `0.2.0` 线（从 `0.2.0-rc.2` 起），与 v0.7.1 相同。装载语义不变。
+
+v0.7.2 让配套 UI 不用再定时轮询 `snapshot()`。对账成功结束时发一条进程内事件，
+视图类型从包入口具名导出。浏览器 SSE 仍由 UI 包自建。
+
+---
+
+## 亮点速览
+
+| 主题 | 一句话 |
+|---|---|
+| 变更事件 | 对账成功结束 `ctx.emit("projectMcp/updated")`，无载荷；监听方再读 `snapshot()` |
+| 具名类型 | 包入口导出 `ProjectFileState`、`McpServerRuntimeView`、`McpServerView`、`McpRowSource` 等，并开始生成 `.d.ts` |
+| 稳定性 | 方法、事件与这些视图类型对配套 UI 按语义化版本承诺；UI 包以同一精确版本 peer-depend |
+
+---
+
+## 变更明细
+
+- **变更事件**：每次成功的 `reconcileAll` 结束（含指纹未变、跳过重读但仍跑完巡检的那一轮）
+  emit `projectMcp/updated`。查询方法本身不发。监听方抛错记一条
+  `项目 MCP 变更事件投递失败：…`，对账仍算成功。
+- **类型出口**：`declaration` 打开后 `lib/index.d.ts` 才存在；`package.json` 的 `types`
+  指向它。`exports` 仍不开放 `lib/` 深导入。
+- **配套 UI**：查询面从「不承诺稳定」改为对该消费方按语义化版本演进。patch 保持形状，
+  minor 只增加，major 才删除或改名。peer 写成精确版本，不要 `^` / `~`。
+
+## 验证
+
+`pnpm test` 六套全绿（model 33 / mcp-file 7 / json-file 13 / json-write 6 /
+registry 48 / cli 21）。

package/lib/cli.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+export interface CliIo {
+    out(line: string): void;
+    err(line: string): void;
+}
+export interface CliDeps {
+    /** 用户主目录（测试注入）：给出时用户层固定为 `<home>/.dsh`，忽略 `$DSH_HOME`。 */
+    home?: string;
+    /** 项目根解析（默认向上找 .git，测试注入）。 */
+    resolveProjectRoot?: (cwd: string) => Promise<string>;
+    /** `import --from -` 的 stdin（测试注入；缺省读 `process.stdin`）。 */
+    readStdin?: () => Promise<string>;
+}
+interface ParsedArgs {
+    positional: string[];
+    /** 未显式给出时为 undefined：list 展示全部层；add/remove/get 缺省按 project。 */
+    scope?: "project" | "user" | "profile";
+    /** 写入格式：缺省时取 DSH_MCP_CLI_FORMAT，再缺省 yml。 */
+    format?: "yml" | "json";
+    /** --scope profile 的目标 profile 名。 */
+    profile?: string;
+    transport: "stdio" | "http";
+    env: Record<string, string>;
+    headers: Record<string, string>;
+    cwd?: string;
+    help: boolean;
+    /** import 输入：文件路径或 `-`（stdin）。 */
+    from?: string;
+    dryRun: boolean;
+    overwrite: boolean;
+}
+/** CLI 写入格式的默认值开关：`yml`（默认）或 `json`；`--format` 优先。 */
+export declare const CLI_FORMAT_ENV = "DSH_MCP_CLI_FORMAT";
+/**
+ * 手搓 argv 解析（零依赖）：`--` 之后全按位置参数；未知「选项」视为服务器命令行
+ * token 透传（刻意策略：宁可透传也不误伤 spawn 参数）。
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs | {
+    error: string;
+};
+export declare function runCli(argv: string[], io: CliIo, deps?: CliDeps): Promise<number>;
+export {};

package/lib/dsh-paths.d.ts

@@ -0,0 +1,42 @@
+/** dsh 家目录重定位环境变量。 */
+export declare const DSH_HOME_ENV = "DSH_HOME";
+/** 显式指定 profile 名的环境变量（覆盖自动解析；CLI/无 profile 启动场景用）。 */
+export declare const PROFILE_ENV = "DSH_MCP_PROFILE";
+/** 原生受管块文件名（项目层 `<root>/.dsh/mcp.yml` 与用户层 `<dshHome>/mcp.yml` 同名）。 */
+export declare const MCP_YML_FILE = "mcp.yml";
+/** 项目/用户层配置目录名（项目层为 `<root>/.dsh`）。 */
+export declare const DSH_DIR = ".dsh";
+/** 诊断文件名（项目层写 `<root>/.dsh/`，全局层写 `<dshHome>/`）。 */
+export declare const DIAG_FILE = ".mcp-diag.json";
+/**
+ * dsh 家目录：`DSH_HOME` 非空则取其绝对化值，否则 `<home>/.dsh`。
+ * 显式传入的 home 只影响缺省分支——注入方（测试/CLI `--home`）想完全接管路径时
+ * 应直接给 dshHome。
+ */
+export declare function dshHomeDir(home?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * 注入优先的 dsh 家目录：显式给出的 home（CLI `deps.home`、测试注入）视为完整接管，
+ * 直接取 `<home>/.dsh`；未给出时才解析 `DSH_HOME`。注入点若被 env 反超，注入就失去
+ * 隔离意义（测试会读到真实用户配置）。
+ */
+export declare function dshHomeFor(home: string | undefined, env?: NodeJS.ProcessEnv): string;
+/** 用户层（全局装载）三个来源文件的路径。 */
+export interface UserLayerPaths {
+    mcpYml: string;
+    mcpJson: string;
+    profilesDir: string;
+}
+/** dsh 家目录 → 用户层三个来源路径。 */
+export declare function userLayerPathsIn(dshHome: string): UserLayerPaths;
+/** profile 层配置文件路径（`<dshHome>/profiles/<name>/mcp.json`）。 */
+export declare function profileMcpJsonFile(profilesDir: string, profile: string): string;
+/** 对方插件全局存储路径（`$DSH_HOME/dsh-mcp.json`）；本插件不读取内容，只在存在时诊断。 */
+export declare function foreignUserMcpJsonFile(dshHome: string): string;
+/**
+ * 合法 profile 名：字母数字开头，其后允许字母数字、`.`、`_`、`-`。
+ * 用于把外部输入（`DSH_MCP_PROFILE`）挡在 profiles 目录内——`..`、
+ * `../../somewhere`、绝对路径都会被拒。
+ */
+export declare const PROFILE_NAME_RE: RegExp;
+/** profile 名是否可安全拼进 profiles 目录（显式拒绝 `.` 与 `..`）。 */
+export declare function isValidProfileName(name: string): boolean;

package/lib/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * dsh-project-mcp-manager —— 独立项目级 MCP 自动加载插件（宿主半区，无 UI）。
+ *
+ * 用法：在项目根创建 <projectRoot>/.dsh/mcp.yml（原生受管块，格式与
+ * profile cordis.patch.yml 一致）或 .dsh/mcp.json（JSON 方言），在该项目
+ * 开启 dsh 会话时自动装载其中的 MCP 服务器（经 @deepseek-ai/dsh-mcp-client），
+ * 文件改动经 watch 热重载。
+ *
+ * 装载模型见 README 与 docs/guide/layers.md；查询面见 docs/guide/service.md；
+ * 运行时行为见 registry.ts 的类注释。
+ */
+import { Context } from "@deepseek-ai/cordis";
+export { bindProjectMcpService, PROJECT_MCP_SERVICE, PROJECT_MCP_UPDATED_EVENT, type ProjectMcpService } from "./service.js";
+export type { FiberPhaseView, McpServerRuntimeView, ProjectFileState, ProjectServerPhase, ProjectServerState } from "./registry.js";
+export type { McpScopeInfo, McpServerView, McpTransport, ReconnectConfig, ToolFilter } from "./model.js";
+export type { PatchRow } from "./mcp-file.js";
+export type { McpRowSource } from "./json-file.js";
+export declare const name = "dsh-project-mcp-manager";
+/** agents 为硬依赖：宿主启动早期插件行先于 agents 服务装载时，等待其就绪后再 apply，
+ *  保证构造时的 liveAgents 补扫能看到已恢复/已存在的会话。 */
+export declare const inject: string[];
+/** 显式指定 profile 名的环境变量（实现在 dsh-paths.ts，registry 的校验共用）。 */
+export { PROFILE_ENV } from "./dsh-paths.js";
+export declare function apply(ctx: Context): void;

package/lib/index.js

@@ -2,7 +2,7 @@ import { MCP_PLUGIN_NAME } from "./mcp-file.js";
 import { PROFILE_ENV } from "./dsh-paths.js";
 import { ProjectMcpRegistry, profileNameFromConfigPath } from "./registry.js";
 import { bindProjectMcpService, PROJECT_MCP_SERVICE } from "./service.js";
-export { bindProjectMcpService, PROJECT_MCP_SERVICE } from "./service.js";
+export { bindProjectMcpService, PROJECT_MCP_SERVICE, PROJECT_MCP_UPDATED_EVENT } from "./service.js";
 export const name = "dsh-project-mcp-manager";
 /** agents 为硬依赖：宿主启动早期插件行先于 agents 服务装载时，等待其就绪后再 apply，
  *  保证构造时的 liveAgents 补扫能看到已恢复/已存在的会话。 */