# 发布说明 v0.6.0（运行时稳健性与 JSON 互通）

[← 返回 README](../README.zh.md) ｜ 相关：[v0.4.3 发布说明](v0.4.3.md) ·
[设计提案](../design/proposal-runtime-robustness-and-json-interop.md) ·
[本区间 TypeScript 审查](../code-review/ts-review-v0.4.3-to-v0.6.0.zh.md) ·
[审查落地复查（7e0088d…804662f）](../code-review/ts-review-7e0088d-to-804662f.zh.md)

**发布日期**：2026-09-13 ｜ **区间**：`v0.4.3 → v0.6.0`
**规模**：PR #9（提案 A/B/C 组，C3 除外）+ 审查落地与 Sonar 拆分；
`pnpm test` 六套全绿

v0.6.0 落地
[运行时稳健性与 JSON 互通提案](../design/proposal-runtime-robustness-and-json-interop.md)。
一次跳过中间的 0.4.4 / 0.5.0 切分，是因为 **B1 按需挂载改变了装载语义**
（无会话项目不再常驻 stdio 子进程）。VS Code `.vscode/mcp.json` 只读层（C3）
本轮明确不做。

---

## 亮点速览

| 主题 | 一句话 |
|---|---|
| ⚠️ 按需挂载 | 项目层只给有会话 ∪ 进程 cwd 的项目装载；无会话宽限 5 分钟后卸载，记 `idle` |
| 连接自愈 | 当前 fiber 世代曾有工具、持续 0 工具才重挂；恢复清零；连续 3 次失败才 `give-up` |
| 诊断摘要 + `status` | `{ summary?, events }`；CLI 不连宿主即可看层行数、idle / 不健康 / 预算 |
| `dsh-mcp import` | 批量导入 `mcpServers`；同名锁内 skip；`--dry-run` 预演影子冲突 |
| 工具过滤 / 预算 | 条目 `tools.allow`/`deny`；超阈值只告警不裁剪 |
| JSON 互通 | 传输值域镜像官方 client；SSE 可执行报错；Gemini `httpUrl`；对方格式诊断 |
| `projectMcp` 查询面 | 不稳定 API：内存快照进 enqueue，不读盘、不驱动对账 |

---

## 用户可见变化

### 装载与运行时

- **按需挂载**：扫描与生效名仍按全量已知项目计算；项目层只给「有活跃会话 ∪
  进程 cwd」的项目发起装载。最后一次会话离开且该项目不是 cwd 后，宽限 5 分钟
  再卸载服务器，保留条目与文件监听，行记 `skipReason: "idle"` 并进入
  `summary.idle`（不算不健康；已有 `env-missing` 等更具体原因不覆盖）。
  用户层仍宿主级常驻。
- **连接自愈**：曾经在**当前 fiber 世代**暴露过工具、后来 `mcpToolCount === 0`
  且持续超过退避窗口时 unmount 再 mount。单次 0 工具边沿（`list_changed`
  闪空）不拆连接；新一代首连窗口交给官方 client 内部重连。`tools > 0` 清
  `remountCount` / `givenUp`（连续失败，不是寿命配额；连续 3 次无恢复才
  `give-up`）。`disabled: true` / `enabled: false` 不复活。
- **配置指纹**：`mtimeMs+size` 加上当前 profile 名与排序后的宿主全局名未变则
  跳过文件重读，仍跑巡检 / deny / 预算 / 摘要。运行中改 `DSH_MCP_PROFILE`
  或宿主 patch 名集会失配并重读。
- **工具预算**：超过 `DSH_MCP_TOOL_BUDGET_WARN`（缺省 200 工具 / 256KiB）每次
  越过阈值告警一次并写入诊断摘要，回落到阈值下会清门控。**永不裁剪**。
  deny 展开与预算共用 `schemaToolId`（`name` 优先于 `id`）。
- **工具过滤**：条目 `tools.allow` / `tools.deny`（完整 glob；deny 优先）。
  JSON 亦映射 `includeTools` / `excludeTools`。只改过滤不拆连接。完整
  `mcp__…` 模式按**生效名**匹配（项目行改名后写死原名不会命中）。非法 glob
  （例如 `[z-a]`）按条目告警一次。

### JSON / CLI

- 传输值域镜像官方 client（`stdio` | `streamable-http`）。
- MCP SSE 端点传输给出可执行报错，不静默回退。
- 接受 Gemini `httpUrl` 与原生 `transport`；裸 `url` 在本插件仍是 Streamable
  HTTP（与 Gemini 相反，已文档化）。无 `type`/`transport` 时同时有 `command`
  与 `url`/`httpUrl` 的条目报错，不当 stdio 静默装载。
- 对方 `{version, servers}` 存储格式写诊断并声明共存。用户层 watcher 监听
  `$DSH_HOME/dsh-mcp.json`，创建即可诊断；该文件若已是本插件 `mcpServers`
  方言，提示搬到 `mcp.json`，仍不从此路径装载。
- 诊断文件 `{ summary?, events }`；`rows` 按配置目录计。`dsh-mcp status`
  打印层行数与摘要。`--scope project|user|profile` 只打印对应层与诊断文件
  （`profile` 只列 profile 层，可再配 `--profile`）。idle 打成「未装载（无会话）」。
- `dsh-mcp import --from <file|->` 批量导入 `mcpServers`（缺省 project，
  `--dry-run` / `--overwrite`；同名 skip/overwrite 在锁内判定）。
- `dsh-mcp add` 没有 `--allow` / `--deny`；过滤请写文件或用 `import`。
  `list` / `get` 会展示已有过滤（只显示模式文本）。

### 插件查询面

其它插件可经不稳定服务 `ctx.projectMcp`（`snapshot` / `serverView` /
`globalState` / `reload`）读装载状态。查询进 enqueue、只读上一轮对账内存，
不读盘、不驱动对账。**不承诺 API 稳定**。

---

## 审查收口

两轮 TypeScript 审查的高/中优先级项均已落地后再切 tag：

- [v0.4.3 至 v0.6.0](../code-review/ts-review-v0.4.3-to-v0.6.0.zh.md)
  （H1–H2 / M1–M8）
- [7e0088d 至 804662f 复查](../code-review/ts-review-7e0088d-to-804662f.zh.md)
  余项（健康配额恢复清零、查询面内存快照、同世代 0 工具去抖、idle 不算不健康、
  `status --scope profile` 等）在 `dcdcdab` 及后续 commit 关闭。

PR #9 后续的 Sonar 认知复杂度拆分不改变行为。

---

## 升级

- **行为变化**：长期开着许多项目、但只有一两个有会话时，未活跃项目的 MCP
  子进程会在 5 分钟宽限后退出。需要某个无会话项目始终在线时，把 dsh 进程 cwd
  放在该项目，或保持至少一条会话。
- 配置文件格式向后兼容；`type: "sse"` 仍会跳过，只是报错更可执行。
- 不读 `.vscode/mcp.json`（与 v0.4.3 相同）。
- 宿主对齐：与 dsh **0.1.5-rc.1 / rc.2** 同线（`@deepseek-ai/dsh-mcp-client
  ^0.1.5-rc.1`）。rc.2 相对 rc.1 仅为 UI 变更，运行时无差别。

```powershell
dsh plugin --profile <p> add dsh-project-mcp-manager@0.6.0
```

## 组件版本

- `dsh-project-mcp-manager` v0.6.0 ｜ 依赖 `@deepseek-ai/dsh-mcp-client ^0.1.5-rc.1`、
  `chokidar ^5`、`yaml ^2`、`zod ^4`（开发：`@deepseek-ai/cordis ^4.0.2`、`typescript ^7`）
- 实测宿主：`@deepseek-ai/dsh@0.1.5-rc.2`（见
  [适配记录](../design/adaptation-dsh-0.1.5-rc2.md)）

**Full Changelog**：https://github.com/wldxiaobai/dsh-project-mcp-manager/compare/v0.4.3...v0.6.0