dsh-project-mcp-manager 0.7.1 → 0.7.2

package/README.md

@@ -43,6 +43,9 @@ Feature documentation lives in `docs/`, English and Chinese side by side:
 - [`${VAR}` expansion](docs/guide/env-expansion.md) — mount-time interpolation and
   its diagnostics.
 - [CLI `dsh-mcp`](docs/guide/cli.md) — scopes, write formats, ownership contract.
+- [Query surface](docs/guide/service.md) — `ctx.projectMcp`, the
+  `projectMcp/updated` event, exported view types, and the semver contract for
+  the companion UI.
 
 Design and release records (Chinese): [dsh 0.2.0-rc.2 adaptation](docs/design/adaptation-dsh-0.2.0-rc.2.md) ·
 [dsh 0.1.6-alpha.2 adaptation plan](docs/design/adaptation-dsh-0.1.6-alpha.2.md) ·
@@ -51,6 +54,7 @@ Design and release records (Chinese): [dsh 0.2.0-rc.2 adaptation](docs/design/ad
 [dsh 0.1.2-rc.1 adaptation](docs/design/adaptation-dsh-0.1.2-rc1.md) ·
 [JSON config layer proposal](docs/design/proposal-json-mcp-config.md) ·
 [Runtime robustness & JSON interop proposal](docs/design/proposal-runtime-robustness-and-json-interop.md) ·
+[v0.7.2 release notes](docs/releases/v0.7.2.md) ·
 [v0.7.1 release notes](docs/releases/v0.7.1.md) ·
 [v0.7.0 release notes](docs/releases/v0.7.0.md) ·
 [v0.6.0 release notes](docs/releases/v0.6.0.md) ·
@@ -90,7 +94,7 @@ dsh plugin --profile web add dsh-project-mcp-manager@latest
 
 # Install a specific version (check available versions with
 # npm view dsh-project-mcp-manager versions)
-dsh plugin --profile web add dsh-project-mcp-manager@0.7.1
+dsh plugin --profile web add dsh-project-mcp-manager@0.7.2
 ```
 
 **Option 2: install directly with pnpm** (equivalent to option 1):
@@ -117,7 +121,7 @@ pnpm add link:<path-to-your-dsh-mcp-project-source>   # e.g. D:\dev\dsh-mcp-proj
 > trigger the bundle reconcile.
 
 **Upgrading / pinning versions**: re-run the `add` command from option 1 with
-the desired version suffix — `@latest` upgrades to the newest release, `@0.7.1`
+the desired version suffix — `@latest` upgrades to the newest release, `@0.7.2`
 pins to a specific version. v0.7.x needs dsh 0.2.0-rc.2 (the `0.2.0` line).
 dsh 0.1.5 keeps working with plugin `@0.6.0`.
 
@@ -179,6 +183,21 @@ pnpm test          # node test/test-model.mjs / test-mcp-file / test-json-file /
   falls back to the owner project (subagents), then to the project containing
   the dsh process cwd. Released when the session is destroyed.
 
+## Query surface
+
+Other plugins and the companion UI read mount state from `ctx.projectMcp`
+(`snapshot`, `serverView`, `globalState`, `reload`). Queries are the previous
+reconcile's memory; they do not read disk. A successful reconcile emits
+`projectMcp/updated` with no payload. The listener calls `snapshot()` and
+diffs. This package does not open a browser SSE channel.
+
+That surface — the methods, the event, and the view types re-exported from the
+package entry (`ProjectFileState`, `McpServerRuntimeView`, `McpServerView`,
+`McpRowSource`, and the types those views name) — follows semantic versioning
+for the companion UI. The UI package peer-depends on
+`dsh-project-mcp-manager` at the **same exact version** (no `^` or `~`).
+Details: [query surface](docs/guide/service.md).
+
 ## Security boundary
 
 `stdio` lines in `.dsh/mcp.yml`, `.dsh/mcp.json` and `.mcp.json` spawn their

package/docs/README.zh.md

@@ -36,6 +36,8 @@ client 决定。** v0.7.x 面向 dsh `0.2.0` 线（从 0.2.0-rc.2 起）。仍
   全局装载 vs 项目装载，以及只读的遗留 Claude Code 层。
 - [`${VAR}` 展开](guide/env-expansion.zh.md)——装载时插值与对应诊断。
 - [CLI `dsh-mcp`](guide/cli.zh.md)——作用域、写入格式与独占契约。
+- [查询面](guide/service.zh.md)——`ctx.projectMcp`、`projectMcp/updated` 事件、
+  包入口导出的视图类型，以及对配套 UI 的语义化版本承诺。
 
 设计与发布记录（中文）：[dsh 0.2.0-rc.2 适配记录](design/adaptation-dsh-0.2.0-rc.2.md) ·
 [dsh 0.1.6-alpha.2 适配方案](design/adaptation-dsh-0.1.6-alpha.2.md) ·
@@ -44,6 +46,7 @@ client 决定。** v0.7.x 面向 dsh `0.2.0` 线（从 0.2.0-rc.2 起）。仍
 [dsh 0.1.2-rc.1 适配记录](design/adaptation-dsh-0.1.2-rc1.md) ·
 [JSON 配置层设计提案](design/proposal-json-mcp-config.md) ·
 [运行时稳健性与 JSON 互通提案](design/proposal-runtime-robustness-and-json-interop.md) ·
+[v0.7.2 发布说明](releases/v0.7.2.md) ·
 [v0.7.1 发布说明](releases/v0.7.1.md) ·
 [v0.7.0 发布说明](releases/v0.7.0.md) ·
 [v0.6.0 发布说明](releases/v0.6.0.md) ·
@@ -79,7 +82,7 @@ npm install -g deepseek-ai/dsh         # 或从 GitHub 源码安装
 dsh plugin --profile web add dsh-project-mcp-manager@latest
 
 # 安装指定版本（版本号可先 npm view dsh-project-mcp-manager versions 查看）
-dsh plugin --profile web add dsh-project-mcp-manager@0.7.1
+dsh plugin --profile web add dsh-project-mcp-manager@0.7.2
 ```
 
 **方式二：直接 pnpm 安装**（与方式一等价）：
@@ -104,7 +107,7 @@ pnpm add link:<你的 dsh-mcp-project 源码目录>   # 例如 D:\dev\dsh-mcp-pr
 > `dsh-project-mcp-manager` 行）触发 bundle reconcile。
 
 **升级/锁定版本**：重跑方式一的 `add` 命令并带上目标版本后缀——`@latest`
-升级到最新，`@0.7.1` 锁定到指定版本。v0.7.x 需要 dsh 0.2.0-rc.2（`0.2.0` 线）。
+升级到最新，`@0.7.2` 锁定到指定版本。v0.7.x 需要 dsh 0.2.0-rc.2（`0.2.0` 线）。
 dsh 0.1.5 继续用插件 `@0.6.0`。
 
 ## 构建与测试
@@ -148,6 +151,19 @@ pnpm test          # node 直跑 test/ 下六个 .mjs（model / mcp-file / json-
   自身行压制过的全局服务器；会话无 cwd 时回退 owner 项目（子代理），再回退 dsh
   进程 cwd 所在项目。会话销毁时释放。
 
+## 查询面
+
+其它插件和配套 UI 从 `ctx.projectMcp`（`snapshot`、`serverView`、`globalState`、
+`reload`）读装载状态。查询看到的是上一轮对账的内存，不读盘。对账成功结束时 emit
+`projectMcp/updated`，无载荷。监听方再调 `snapshot()` 自己 diff。本包不打开浏览器
+SSE。
+
+这个面——方法、事件，以及从包入口再导出的视图类型（`ProjectFileState`、
+`McpServerRuntimeView`、`McpServerView`、`McpRowSource`，以及这些视图点名的类型）
+——对配套 UI 按语义化版本承诺。UI 包把 `dsh-project-mcp-manager` 写成
+peer dependency，并锁定到**同一精确版本**（不要写 `^` 或 `~`）。详见
+[查询面](guide/service.zh.md)。
+
 ## 安全边界
 
 `.dsh/mcp.yml`、`.dsh/mcp.json` 与 `.mcp.json` 中的 `stdio` 行会在 dsh

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/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.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 补扫能看到已恢复/已存在的会话。 */

package/lib/json-file.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { type PatchRow } from "./mcp-file.js";
+import { type McpServerInput } from "./model.js";
+/** DSH 自有 JSON 配置文件名（位于 `<root>/.dsh/`、`$DSH_HOME/`、`$DSH_HOME/profiles/<name>/`）。 */
+export declare const JSON_MCP_FILE = "mcp.json";
+/** 对方插件（`@wingsky-1/dsh-mcp-manager`）的全局存储文件名（位于 `$DSH_HOME/`）。 */
+export declare const FOREIGN_MCP_JSON_FILE = "dsh-mcp.json";
+/** 对方 `{version, servers}` 存储格式的可执行诊断（本插件不读取该方言）。 */
+export declare const FOREIGN_MCP_FORMAT_HINT = "\u8BE5\u6587\u4EF6\u7591\u4F3C @wingsky-1/dsh-mcp-manager \u7684\u5B58\u50A8\u683C\u5F0F\uFF08{version, servers}\uFF09\uFF0C\u672C\u63D2\u4EF6\u4E0D\u8BFB\u53D6\u3002\u5EFA\u8BAE\u6539\u7528 mcpServers \u65B9\u8A00\uFF0C\u6216\u6539\u7528 .dsh/mcp.yml";
+/** 对方文件名里误写了本插件 `mcpServers`：不装载，提示改用 mcp.json。 */
+export declare const FOREIGN_MCP_WRONG_FILE_HINT = "\u8BE5\u6587\u4EF6\u540D\u4E3A dsh-mcp.json\uFF08@wingsky-1/dsh-mcp-manager \u7684\u5168\u5C40\u5B58\u50A8\uFF09\uFF0C\u672C\u63D2\u4EF6\u4E0D\u4ECE\u6B64\u8DEF\u5F84\u88C5\u8F7D\u3002\u8BF7\u628A mcpServers \u5199\u5230 mcp.json";
+/**
+ * 检测对方插件的存储格式。本插件方言文件（mcp.json / .mcp.json）里一旦有
+ * `mcpServers`（即便同时有 `servers`）就不告警。对方文件名 `dsh-mcp.json`
+ * 即使写了 `mcpServers` 也不装载，并提示改用 mcp.json。缺 `mcpServers` 且顶层
+ * 是 `servers` 数组，或同时有 `version` 与 `servers`，认定为对方格式。
+ */
+export declare function detectForeignMcpFormat(value: Record<string, unknown>, fileName?: string): string | undefined;
+/** 遗留 Claude Code project 层文件名（位于项目根，与 `.dsh/` 并列，只读）。 */
+export declare const CC_PROJECT_FILE = ".mcp.json";
+/** 置为 "1" 时跳过遗留 `<projectRoot>/.mcp.json` 的读取与监听；DSH 自有 JSON 层不受影响。 */
+export declare const IGNORE_MCP_JSON_ENV = "DSH_MCP_IGNORE_MCP_JSON";
+/** 遗留 CC 项目层是否启用：默认开，`DSH_MCP_IGNORE_MCP_JSON=1` 关。 */
+export declare function mcpJsonLayerEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 配置行来源。数组顺序即影子优先序（先到先得）：
+ * `dsh-project` > `dsh-project-json` > `cc-project` > `dsh-profile-user` > `dsh-user-yml` > `dsh-user`。
+ * 前三者是项目层（按项目装载、按会话隔离），后三者是用户层（宿主级全局装载）。
+ */
+export type McpRowSource = "dsh-project" | "dsh-project-json" | "cc-project" | "dsh-profile-user" | "dsh-user-yml" | "dsh-user";
+/** 带来源标记的配置行：主管线合并与快照展示用。disabled=true 的行参与占名
+ *  （遮蔽下层同名）但不进入装载集合。 */
+export interface SourcedRow {
+    rawName: string;
+    row: PatchRow;
+    source: McpRowSource;
+    disabled?: boolean;
+}
+export interface JsonReadResult {
+    rows: SourcedRow[];
+    /** 单条坏条目（sse/缺字段/坏名字）的报错，逐条收集，不影响其余条目。 */
+    entryErrors: string[];
+    /** 整文件级错误（不存在=正常空结果；解析失败等）。消息不含文件内容。 */
+    fileError?: string;
+    /**
+     * 文件存在、缺 `mcpServers`、且顶层像 `{version, servers}`（对方插件存储格式）时的
+     * 诊断。缺 `mcpServers` 仍是合法空层；此字段只为「配了但不生效」提供可执行说明。
+     */
+    formatHint?: string;
+}
+/** stdio 空 cwd 的解析策略：项目层=项目根；用户层=继承宿主工作目录。 */
+export type JsonCwdPolicy = "project" | "host";
+export interface JsonReadOptions {
+    source: McpRowSource;
+    cwdPolicy: JsonCwdPolicy;
+    /** 项目根（cwdPolicy="project" 时空 cwd 的落点；用户层传空串）。 */
+    projectRoot: string;
+    /** true：缺 `mcpServers` 报文件级错误（遗留 CC 文件语义）；false：视为空层。 */
+    requireMcpServers?: boolean;
+}
+/**
+ * 单条目宽松 schema：未知字段（timeout/scope 等生态附加键）容忍并忽略。
+ * `type` 缺省视为 stdio（有 url/httpUrl 无 command 时按 http 推断）。
+ * `transport` 与 `httpUrl` 为原生/Gemini 方言别名，由 jsonEntryToInput 归一。
+ */
+export declare const jsonServerEntrySchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    transport: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    httpUrl: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    toolCallTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    failOnStartupError: z.ZodOptional<z.ZodBoolean>;
+    maxInstructionBytes: z.ZodOptional<z.ZodNumber>;
+    reconnect: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        initialDelayMs: z.ZodOptional<z.ZodNumber>;
+        maxDelayMs: z.ZodOptional<z.ZodNumber>;
+        maxAttempts: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    tools: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    includeTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type JsonServerEntry = z.infer<typeof jsonServerEntrySchema>;
+/** 单条 JSON 条目 → 官方输入。坏条目返回 `{ error }` 由调用方逐条收集。 */
+export declare function jsonEntryToInput(name: string, entry: JsonServerEntry, options: JsonReadOptions): {
+    input: McpServerInput;
+} | {
+    error: string;
+};
+/** `mcpServers` 值 → SourcedRow 列表；坏条目逐条报错跳过。 */
+export declare function parseJsonServersValue(mcpServers: unknown, options: JsonReadOptions): {
+    rows: SourcedRow[];
+    entryErrors: string[];
+};
+/** 通用 JSON 方言读取：文件缺失 → 空结果；坏条目逐条报错。 */
+export declare function readJsonRows(path: string, options: JsonReadOptions): Promise<JsonReadResult>;
+/** 读 DSH 自有 JSON 层（缺 `mcpServers` 视为空层）。 */
+export declare function readDshJsonFile(path: string, options: JsonReadOptions): Promise<JsonReadResult>;
+/** 读遗留 `<projectRoot>/.mcp.json`（CC project scope；缺 `mcpServers` 报文件级错误）。 */
+export declare function readMcpJsonFile(path: string, projectRoot: string): Promise<JsonReadResult>;

package/lib/json-write.d.ts

@@ -0,0 +1,32 @@
+import { type McpServerInput } from "./model.js";
+/**
+ * `mcpServers` 映射。值类型是 unknown 而非对象：文件里可能存在非对象条目
+ * （`"legacy": "node x.js"` 这类手写错误），读-改-写必须原样带过，不能顺手删。
+ * 写入方（CLI）只新增/删除自己指名的键。
+ */
+export type JsonServers = Record<string, unknown>;
+/**
+ * 读 JSON 文档：缺失/空文件 → `{}`；解析失败或顶层非对象 → 抛错（消息不含文件内容）。
+ * 调用方据此拒绝写入，避免把无法解析的文件覆盖掉。
+ */
+export declare function readJsonDocument(path: string): Promise<Record<string, unknown>>;
+/**
+ * 读现有 `mcpServers` 映射（缺失/null → 空映射；顶层非对象 → 抛错）。
+ * 条目一律保留（含非对象的坏条目）：CLI 的判重要能看见坏条目占用的名字，
+ * `remove <坏条目名>` 也才能把它清掉。装载侧的坏条目过滤在 json-file.ts。
+ */
+export declare function readJsonServers(path: string): Promise<JsonServers>;
+/**
+ * 锁内读-改-写 `mcpServers`：mutate 收到锁内的最新映射，返回值（或原地修改）即写回值。
+ * 加锁 + 原子写；写前自校验（序列化结果必须可解析回来）。返回写回后的映射。
+ */
+export declare function updateJsonServers(path: string, mutate: (servers: JsonServers) => JsonServers | void): Promise<JsonServers>;
+/** 整体替换 `mcpServers`（保留其余顶层键与键序）。 */
+export declare function writeJsonServers(path: string, servers: JsonServers): Promise<JsonServers>;
+/**
+ * 官方输入 → JSON 条目（Cursor/CC 方言 + DSH 透传键）。
+ * 缺省值不落盘（`args: []`、空 `env`/`headers`、空或 "." 的 `cwd`、默认
+ * `toolCallTimeoutMs`/`failOnStartupError`/`maxInstructionBytes`/`reconnect`），保持文件简洁可读。
+ * `${VAR}` 原样保留，装载时才展开——凭据不落盘。
+ */
+export declare function toJsonEntry(input: McpServerInput): Record<string, unknown>;