dsh-project-mcp-manager 0.1.1 → 0.4.2

package/README.md

@@ -1,134 +1,151 @@
-# dsh-project-mcp-manager
-
-English | [中文](docs/README.zh.md)
-
-A project-level MCP auto-loading plugin for DSH: write MCP server configs in
-`<projectRoot>/.dsh/mcp.yml` and they are mounted automatically (via the
-official `@deepseek-ai/dsh-mcp-client`) whenever a dsh session opens in that
-project. Changes to the file hot-reload into the running dsh process, and tool
-visibility is scoped per session cwd. No UI — core functionality only.
-
-## Installation (mount into a profile)
-
-The plugin is mounted through a **bundle patch**: once the package is added to
-`dsh.profile.bundles`, dsh synthesizes each bundle's patch (the
-`cordis.patch.yml` pointed to by `dsh.bundle.patch`) into plugin lines at
-startup, in order.
-
-**Prerequisite: install dsh itself** (for users who don't have dsh yet):
-
-```powershell
-npm install -g @deepseek-ai/dsh        # official npm package
-npm install -g deepseek-ai/dsh         # or install from the GitHub source
-```
-
-**Option 1: the dsh plugin command (recommended)** — `dsh plugin` forwards
-pnpm inside the profile directory and handles installing/upgrading
-dependencies:
-
-```powershell
-# Install the latest version (web profile shown as an example;
-# substitute the name of any other profile, e.g. headless)
-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.1.0
-```
-
-**Option 2: install directly with pnpm** (equivalent to option 1):
-
-```powershell
-# dshHome defaults to %USERPROFILE%\.dsh (uses $DSH_HOME if set)
-cd $env:USERPROFILE\.dsh\profiles\web
-pnpm add dsh-project-mcp-manager@latest
-```
-
-**Option 3: local development install** (a junction that live-syncs your
-source, so code changes take effect immediately):
-
-```powershell
-cd $env:USERPROFILE\.dsh\profiles\web
-pnpm add link:<path-to-your-dsh-mcp-project-source>   # e.g. D:\dev\dsh-mcp-project
-```
-
-**Upgrading / pinning versions**: re-run the `add` command from option 1 with
-the desired version suffix — `@latest` upgrades to the newest release, `@0.1.0`
-pins to a specific version.
-
-## Build & test
-
-```powershell
-npm install
-npm run build     # tsc → lib/
-node test/test-model.mjs
-node test/test-registry.mjs
-```
-
-## Configuration format
-
-`<projectRoot>/.dsh/mcp.yml` uses the same managed-block format as the profile
-`cordis.patch.yml` (a YAML `insert` list between begin/end markers), with one
-MCP server per line:
-
-```yaml
-# >>> dsh-project-mcp-manager:mcp:begin
-- insert:
-    - id: panel-mcp-gitlab
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: gitlab
-        transport: stdio
-        command: npx
-        args: ['-y', '@modelcontextprotocol/server-gitlab']
-        cwd: .            # resolved relative to the project root
-        toolCallTimeoutMs: 60000
-        failOnStartupError: false
-        reconnect:
-          enabled: true
-          initialDelayMs: 500
-          maxDelayMs: 30000
-          maxAttempts: 10
-# <<< dsh-project-mcp-manager:mcp:end
-```
-
-`transport` supports `stdio` (command/args/env/cwd) and `streamable-http`
-(url/headers). Add `disabled: true` to a line to deactivate it. Content outside
-the markers is preserved byte-for-byte.
-
-## How it works
-
-- **Project discovery**: the `session.header.cwd` of an active agent session,
-  plus the dsh process start directory → walk up to the nearest ancestor
-  containing `.git` as the project root (falls back to the directory itself
-  when there is no `.git`).
-- **Mounting**: each `(project, serverName)` pair mounts one
-  `@deepseek-ai/dsh-mcp-client` instance (`ctx.plugin`) on the host ctx and
-  registers it into the global tool layer. Multiple sessions inside the same
-  project share a single connection.
-- **Hot reload**: chokidar watches each project root (depth 2, ignoring
-  node_modules/.git/.hg/.svn); changes to `.dsh/mcp.yml` trigger a full
-  reconciliation after a 150 ms debounce: added lines are mounted, removed
-  lines are unmounted, and config changes are remounted.
-- **Effective names**: when the original `serverName` is unique across the
-  whole catalog (global lines + all project lines) it keeps its name; on a
-  conflict both sides are renamed to
-  `p<first 6 chars of sha256(projectRoot)>_<original name>` (truncated to 32
-  characters, deterministic and independent of mount order) to avoid the
-  serverName reservation conflicts that `dsh-mcp-client` makes per process
-  root. Global lines (profile `cordis.patch.yml` / mcp-client lines already
-  mounted at the bundle level) participate in occupancy determination but are
-  never renamed.
-- **Session visibility**: when an agent is created, its session cwd resolves
-  to a project, and `tools.restrict({ deny })` is applied to that agent to deny
-  every project server except those of the session's own project; a session
-  without a cwd falls back to the owner project (subagents), then to the
-  project containing the dsh process cwd. Released when the session is
-  destroyed.
-
-## Security boundary
-
-`stdio` lines in `.dsh/mcp.yml` spawn their `command` inside the dsh host
-process — project files are **executable code carriers**, so only add them in
-projects you trust. Lines that fail to mount or are invalid are skipped with a
-warning and do not affect other servers.
+# dsh-project-mcp-manager
+
+English | [中文](docs/README.zh.md)
+
+A project-level MCP auto-loading plugin for DSH: write MCP server configs in
+`<projectRoot>/.dsh/mcp.yml` and they are mounted automatically (via the
+official `@deepseek-ai/dsh-mcp-client`) whenever a dsh session opens in that
+project. Changes to the file hot-reload into the running dsh process, and tool
+visibility is scoped per session cwd. No UI — core functionality only.
+
+## Documentation
+
+Feature documentation lives in `docs/`, English and Chinese side by side:
+
+- [Configuration format](docs/guide/format.md) — native YAML managed
+  block, JSON dialect, divergences from the cordis dialect.
+- [Configuration sources and layers](docs/guide/layers.md) — the
+  six-layer source model, shadow priority, global vs project mounting, and the
+  read-only legacy Claude Code layer.
+- [`${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.
+
+Design and release records (Chinese): [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) ·
+[v0.4.2 release notes](docs/releases/v0.4.2.md) ·
+[v0.4.1 release notes](docs/releases/v0.4.1.md) ·
+[v0.4.0 release notes](docs/releases/v0.4.0.md) ·
+[v0.3.1 release notes](docs/releases/v0.3.1.md).
+
+Code review records (Chinese): [TypeScript changes since v0.3.1](docs/code-review/ts-review-since-v0.3.1.zh.md).
+
+## Installation (mount into a profile)
+
+The plugin is mounted through a **bundle patch**: once the package is added to
+`dsh.profile.bundles`, dsh synthesizes each bundle's patch (the
+`cordis.patch.yml` pointed to by `dsh.bundle.patch`) into plugin lines at
+startup, in order.
+
+**Prerequisite: install dsh itself** (for users who don't have dsh yet):
+
+```powershell
+npm install -g @deepseek-ai/dsh        # official npm package
+npm install -g deepseek-ai/dsh         # or install from the GitHub source
+```
+
+**Option 1: the dsh plugin command (recommended)** — `dsh plugin` forwards
+pnpm inside the profile directory and handles installing/upgrading
+dependencies:
+
+```powershell
+# Install the latest version (web profile shown as an example;
+# substitute the name of any other profile, e.g. headless)
+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.2.0
+```
+
+**Option 2: install directly with pnpm** (equivalent to option 1):
+
+```powershell
+# dshHome defaults to %USERPROFILE%\.dsh (uses $DSH_HOME if set)
+cd $env:USERPROFILE\.dsh\profiles\web
+pnpm add dsh-project-mcp-manager@latest
+```
+
+**Option 3: local development install** (a junction that live-syncs your
+source, so code changes take effect immediately):
+
+```powershell
+cd $env:USERPROFILE\.dsh\profiles\web
+pnpm add link:<path-to-your-dsh-mcp-project-source>   # e.g. D:\dev\dsh-mcp-project
+```
+
+> **dsh ≥ 0.1.2 note**: whether the plugin loads depends on the profile's
+> `dsh.profile.bundles` list, and a plain `pnpm add link:` does **not** add the
+> package to it. Options 1 and 2 reconcile it automatically; if you ran pnpm by
+> hand, run any `dsh plugin --profile web list` once (or check
+> `dsh --profile web --dump-config` for a `dsh-project-mcp-manager` row) to
+> 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.2.0`
+pins to a specific version.
+
+## Build & test
+
+```powershell
+pnpm install
+pnpm run build     # tsc → lib/
+pnpm test          # node test/test-model.mjs / test-mcp-file / test-json-file / test-json-write / test-registry / test-cli
+```
+
+## How it works
+
+- **Project discovery**: the `session.header.cwd` of an active agent session,
+  plus the dsh process start directory → walk up to the nearest ancestor
+  containing `.git` as the project root (falls back to the directory itself
+  when there is no `.git`).
+- **Mounting**: each `(project, serverName)` pair in the project layers mounts
+  one `@deepseek-ai/dsh-mcp-client` instance (`ctx.plugin`) on the host ctx and
+  registers it into the global tool layer; multiple sessions inside the same
+  project share a single connection. **Every user-layer row mounts exactly one
+  instance** (global, independent of the number of projects) — see
+  [configuration sources and layers](docs/guide/layers.md).
+- **Hot reload**: chokidar watches each project root (depth 2, ignoring
+  node_modules/.git/.hg/.svn), but only edits to the **exact** config files of
+  known project roots — `<projectRoot>/.dsh/mcp.yml`,
+  `<projectRoot>/.dsh/mcp.json` and `<projectRoot>/.mcp.json` — trigger a full
+  reconciliation after a 150 ms debounce: added rows are mounted, removed rows
+  are unmounted, and config changes are remounted. A second watcher covers the
+  user layer as three **exact file paths** — `~/.dsh/mcp.yml`,
+  `~/.dsh/mcp.json` and `~/.dsh/profiles/<active profile>/mcp.json` (chokidar
+  v5 can deliver an event for a watched missing file when it is created, as
+  long as its parent directory exists) — never the home directory at large.
+- **Profile name resolution**: derived from the loader root include's
+  `config.path` (`~/.dsh/profiles/<name>/cordis.yml`) or `ctx.baseUrl`, and
+  overridable with `DSH_MCP_PROFILE=<name>`; when it cannot be resolved the
+  profile layer is not read (the other layers still are).
+- **Effective names**: when the original `serverName` is unique across the
+  whole catalog (host global rows + all project rows) it keeps its name; on a
+  conflict **project rows** are renamed to `p<first 6 hex chars of
+  sha256(project root)>_<original name>` (truncated to 32 characters,
+  deterministic and independent of mount order) to avoid the serverName
+  reservation conflicts that `dsh-mcp-client` makes per process root. Global
+  rows (profile patch lines and user-layer rows) participate in occupancy
+  determination but are never renamed. Model-visible tool names are built from
+  the **effective** server name and the MCP tool's own name
+  (`mcp__<effectiveServerName>__<toolName>`), which may differ from the
+  `serverName` written in the file.
+- **Session visibility**: when an agent is created, its session cwd resolves to
+  a project, and `tools.restrict({ deny })` is applied to that agent to deny
+  every project server except those of the session's own project, plus the
+  global servers suppressed by the project's own rows; a session without a cwd
+  falls back to the owner project (subagents), then to the project containing
+  the dsh process cwd. Released when the session is destroyed.
+
+## Security boundary
+
+`stdio` lines in `.dsh/mcp.yml`, `.dsh/mcp.json` and `.mcp.json` spawn their
+`command` inside the dsh host process — config files are **executable code
+carriers**, so only add them in projects you trust. The user layers
+(`~/.dsh/mcp.yml`, `~/.dsh/mcp.json`, the profile json) are executable code
+carriers too, they just belong to your own machine: user-layer rows mount
+**globally** (one host-level connection, visible to every project) and are no
+longer fanned out per project. Lines that fail to mount or are invalid are
+skipped with a warning and do not affect other servers. Claude user-state
+monoliths such as `~/.claude.json` (mixing credentials with project history)
+are **no longer read at all** as of v0.4.0.

package/docs/README.zh.md

@@ -1,114 +1,123 @@
-# dsh-project-mcp-manager
-
-[English](../README.md) | 中文
-
-项目级 MCP 自动加载插件：在项目根 `<projectRoot>/.dsh/mcp.yml` 写入 MCP
-服务器配置，在该项目开启 dsh 会话时自动装载（经官方
-`@deepseek-ai/dsh-mcp-client`），文件改动热重载到运行中的 dsh 进程，并按
-会话 cwd 控制工具可见性。无 UI，仅具备核心功能。
-
-## 安装（挂载到 profile）
-
-插件通过 **bundle patch** 挂载：把包加入 `dsh.profile.bundles` 后，dsh 启动时
-按顺序合成每个 bundle 的 patch（`dsh.bundle.patch` 指向的 `cordis.patch.yml`）
-作为插件行。
-
-**前置：安装 dsh 本体**（尚未安装 dsh 的用户）：
-
-```powershell
-npm install -g @deepseek-ai/dsh        # npm 官方包
-npm install -g deepseek-ai/dsh         # 或从 GitHub 源码安装
-```
-
-**方式一：dsh 插件命令（推荐）**——`dsh plugin` 在 profile 目录内转发 pnpm，
-负责安装/升级依赖：
-
-```powershell
-# 安装最新版（web profile 示例；headless 等其他 profile 替换名字即可）
-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.1.0
-```
-
-**方式二：直接 pnpm 安装**（与方式一等价）：
-
-```powershell
-# dshHome 默认为 %USERPROFILE%\.dsh（设置了 DSH_HOME 则用其值）
-cd $env:USERPROFILE\.dsh\profiles\web
-pnpm add dsh-project-mcp-manager@latest
-```
-
-**方式三：本地开发安装**（junction 实时同步源码，改代码即生效）：
-
-```powershell
-cd $env:USERPROFILE\.dsh\profiles\web
-pnpm add link:<你的 dsh-mcp-project 源码目录>   # 例如 D:\dev\dsh-mcp-project
-```
-
-**升级/锁定版本**：重跑方式一的 `add` 命令并带上目标版本后缀——`@latest`
-升级到最新，`@0.1.0` 锁定到指定版本。
-
-## 构建与测试
-
-```powershell
-npm install
-npm run build     # tsc → lib/
-node test/test-model.mjs
-node test/test-registry.mjs
-```
-
-## 配置格式
-
-`<projectRoot>/.dsh/mcp.yml`，格式与 profile `cordis.patch.yml` 的受管块
-一致（begin/end 标记之间的 YAML insert 列表），每行一个 MCP 服务器：
-
-```yaml
-# >>> dsh-project-mcp-manager:mcp:begin
-- insert:
-    - id: panel-mcp-gitlab
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: gitlab
-        transport: stdio
-        command: npx
-        args: ['-y', '@modelcontextprotocol/server-gitlab']
-        cwd: .            # 相对项目根解析
-        toolCallTimeoutMs: 60000
-        failOnStartupError: false
-        reconnect:
-          enabled: true
-          initialDelayMs: 500
-          maxDelayMs: 30000
-          maxAttempts: 10
-# <<< dsh-project-mcp-manager:mcp:end
-```
-
-`transport` 支持 `stdio`（command/args/env/cwd）与 `streamable-http`
-（url/headers）。行加 `disabled: true` 即停用。标记之外的内容逐字节保留。
-
-## 工作原理
-
-- **项目发现**：在线 agent 会话的 `session.header.cwd` + dsh 进程启动目录 →
-  向上找最近的含 `.git` 的祖先目录作为项目根（无 `.git` 时退回目录本身）。
-- **装载**：每个 `(项目, serverName)` 在宿主 ctx 上装载一个
-  `@deepseek-ai/dsh-mcp-client` 实例（`ctx.plugin`），注册进全局工具层。
-  同一项目内多会话共享同一连接。
-- **热重载**：chokidar 监听各项目根（depth 2，忽略 node_modules/.git/.hg/
-  .svn），`.dsh/mcp.yml` 的增删改经 150ms 防抖触发全量对账：新增行装载、
-  删除行卸载、配置变化重装。
-- **生效名**：原始 `serverName` 在整个目录（全局行 + 全部项目行）中唯一时
-  保持原名；冲突时双方都改为 `p<sha256(项目根)前6位>_<原名>`（截断 32 字符，
-  确定性、与装载顺序无关），避免 `dsh-mcp-client` 按进程根的 serverName
-  预留冲突。全局行（profile `cordis.patch.yml` / bundle 层已装载的
-  mcp-client 行）参与占用判定但不改名。
-- **会话可见性**：agent 创建时按其会话 cwd 解析项目，对该 agent 应用
-  `tools.restrict({ deny })`，deny 掉除本会话项目外的全部项目服务器；会话
-  无 cwd 时回退 owner 项目（子代理），再回退 dsh 进程 cwd 所在项目。会话
-  销毁时释放。
-
-## 安全边界
-
-`.dsh/mcp.yml` 中的 `stdio` 行会在 dsh 宿主进程内 spawn 其 `command`——
-项目文件是**可执行代码载体**，只应在可信项目中添加。装载失败/配置无效行
-仅告警跳过，不影响其他服务器。
+# dsh-project-mcp-manager
+
+[English](../README.md) | 中文
+
+项目级 MCP 自动加载插件：在项目根 `<projectRoot>/.dsh/mcp.yml` 写入 MCP
+服务器配置，在该项目开启 dsh 会话时自动装载（经官方
+`@deepseek-ai/dsh-mcp-client`），文件改动热重载到运行中的 dsh 进程，并按
+会话 cwd 控制工具可见性。无 UI，仅具备核心功能。
+
+## 文档
+
+功能说明已拆分到 `docs/`，中英双版并存：
+
+- [配置格式](guide/format.zh.md)——原生 YAML 受管块、JSON 方言、与
+  cordis 方言的差异。
+- [配置来源与分层](guide/layers.zh.md)——六层来源模型、影子优先序、
+  全局装载 vs 项目装载，以及只读的遗留 Claude Code 层。
+- [`${VAR}` 展开](guide/env-expansion.zh.md)——装载时插值与对应诊断。
+- [CLI `dsh-mcp`](guide/cli.zh.md)——作用域、写入格式与独占契约。
+
+设计与发布记录（中文）：[dsh 0.1.2-rc.1 适配记录](design/adaptation-dsh-0.1.2-rc1.md) ·
+[JSON 配置层设计提案](design/proposal-json-mcp-config.md) ·
+[v0.4.2 发布说明](releases/v0.4.2.md) ·
+[v0.4.1 发布说明](releases/v0.4.1.md) ·
+[v0.4.0 发布说明](releases/v0.4.0.md) ·
+[v0.3.1 发布说明](releases/v0.3.1.md)。
+
+代码审查记录（中文）：[v0.3.1 以来 TypeScript 变更审查](code-review/ts-review-since-v0.3.1.zh.md)。
+
+## 安装（挂载到 profile）
+
+插件通过 **bundle patch** 挂载：把包加入 `dsh.profile.bundles` 后，dsh 启动时
+按顺序合成每个 bundle 的 patch（`dsh.bundle.patch` 指向的 `cordis.patch.yml`）
+作为插件行。
+
+**前置：安装 dsh 本体**（尚未安装 dsh 的用户）：
+
+```powershell
+npm install -g @deepseek-ai/dsh        # npm 官方包
+npm install -g deepseek-ai/dsh         # 或从 GitHub 源码安装
+```
+
+**方式一：dsh 插件命令（推荐）**——`dsh plugin` 在 profile 目录内转发 pnpm，
+负责安装/升级依赖：
+
+```powershell
+# 安装最新版（web profile 示例；headless 等其他 profile 替换名字即可）
+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.2.0
+```
+
+**方式二：直接 pnpm 安装**（与方式一等价）：
+
+```powershell
+# dshHome 默认为 %USERPROFILE%\.dsh（设置了 DSH_HOME 则用其值）
+cd $env:USERPROFILE\.dsh\profiles\web
+pnpm add dsh-project-mcp-manager@latest
+```
+
+**方式三：本地开发安装**（junction 实时同步源码，改代码即生效）：
+
+```powershell
+cd $env:USERPROFILE\.dsh\profiles\web
+pnpm add link:<你的 dsh-mcp-project 源码目录>   # 例如 D:\dev\dsh-mcp-project
+```
+
+> **dsh ≥ 0.1.2 注意**：插件是否生效取决于 profile 的 `dsh.profile.bundles`，
+> 而单纯 `pnpm add link:` **不会**把包写进 bundles。方式一/方式二会自动补齐；
+> 若你手写了 pnpm 命令，请再跑一次任意 `dsh plugin --profile web list`（或
+> `--dump-config` 检查合成结果里有没有 `dsh-project-mcp-manager` 行）触发
+> bundle reconcile。
+
+**升级/锁定版本**：重跑方式一的 `add` 命令并带上目标版本后缀——`@latest`
+升级到最新，`@0.2.0` 锁定到指定版本。
+
+## 构建与测试
+
+```powershell
+pnpm install
+pnpm run build     # tsc → lib/
+pnpm test          # node 直跑 test/ 下六个 .mjs（model / mcp-file / json-file / json-write / registry / cli）
+```
+
+## 工作原理
+
+- **项目发现**：在线 agent 会话的 `session.header.cwd` + dsh 进程启动目录 →
+  向上找最近的含 `.git` 的祖先目录作为项目根（无 `.git` 时退回目录本身）。
+- **装载**：项目层每个 `(项目, serverName)` 在宿主 ctx 上装载一个
+  `@deepseek-ai/dsh-mcp-client` 实例（`ctx.plugin`），注册进全局工具层，同一
+  项目内多会话共享同一连接；**用户层每行只装载一个实例**（全局，与项目数无关）
+  ——详见[配置来源与分层](guide/layers.zh.md)。
+- **热重载**：chokidar 监听各项目根（depth 2，忽略 node_modules/.git/.hg/
+  .svn），但只有**已知项目根的精确配置文件**（`<projectRoot>/.dsh/mcp.yml`、
+  `<projectRoot>/.dsh/mcp.json` 与 `<projectRoot>/.mcp.json`）的改动经 150ms
+  防抖触发全量对账：新增行装载、删除行卸载、配置变化重装。另有独立 watcher 以
+  **精确文件路径**监听用户层：`~/.dsh/mcp.yml`、`~/.dsh/mcp.json` 与
+  `~/.dsh/profiles/<当前 profile>/mcp.json`（chokidar v5 对被监听的缺失文件能在
+  其创建时补发事件，前提是父目录已存在）——不监听家目录整体。
+- **profile 名解析**：从 loader 根 include 的 `config.path`
+  （`~/.dsh/profiles/<name>/cordis.yml`）或 `ctx.baseUrl` 推导，可用
+  `DSH_MCP_PROFILE=<name>` 覆盖；解析不出时不读 profile 层（其余层照常）。
+- **生效名**：原始 `serverName` 在整个目录（宿主全局行 + 全部项目行）中唯一时
+  保持原名；冲突时**项目行**改为 `p<sha256(项目根)前6位>_<原名>`（截断 32 字符，
+  确定性、与装载顺序无关），避免 `dsh-mcp-client` 按进程根的 serverName
+  预留冲突。全局行（profile patch 行与用户层行）参与占用判定但不改名。模型可见
+  的工具名由生效服务器名与 MCP 工具自身的名字拼成 `mcp__<生效名>__<工具名>`，
+  与文件里写的 `serverName` 可能不同。
+- **会话可见性**：agent 创建时按其会话 cwd 解析项目，对该 agent 应用
+  `tools.restrict({ deny })`，deny 掉除本会话项目外的全部项目服务器，以及本项目
+  自身行压制过的全局服务器；会话无 cwd 时回退 owner 项目（子代理），再回退 dsh
+  进程 cwd 所在项目。会话销毁时释放。
+
+## 安全边界
+
+`.dsh/mcp.yml`、`.dsh/mcp.json` 与 `.mcp.json` 中的 `stdio` 行会在 dsh
+宿主进程内 spawn 其 `command`——配置文件是**可执行代码载体**，只应在可信项目
+中添加。用户层（`~/.dsh/mcp.yml`、`~/.dsh/mcp.json`、profile json）同样是可执行
+代码载体，只是它们属于你自己的机器：用户层行会以**全局**方式装载（宿主级一条
+连接，所有项目可见），不再按项目 fan-out。装载失败/配置无效行仅告警跳过，不影响
+其他服务器。`~/.claude.json` 这类 Claude 用户态单体文件（混存凭据与项目历史）
+自 v0.4.0 起**完全不再读取**。