dsh-project-mcp-manager 0.1.0 → 0.3.1

package/README.md

@@ -1,34 +1,74 @@
 # dsh-project-mcp-manager
 
-独立项目级 MCP 自动加载插件：在项目根 `<projectRoot>/.dsh/mcp.yml` 写入 MCP
-服务器配置，在该项目开启 dsh 会话时自动装载（经官方
-`@deepseek-ai/dsh-mcp-client`），文件改动热重载到运行中的 dsh 进程，并按
-会话 cwd 控制工具可见性。无 UI，核心功能精简型插件。
-
-## 工作原理
-
-- **项目发现**：在线 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 所在项目。会话
-  销毁时释放。
-
-## 配置格式
-
-`<projectRoot>/.dsh/mcp.yml`，格式与 profile `cordis.patch.yml` 的受管块
-一致（begin/end 标记之间的 YAML insert 列表），每行一个 MCP 服务器：
+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.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
+```
+
+**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
+npm install
+npm run build     # tsc → lib/
+npm test          # node test/test-model.mjs / test-mcp-file / test-cc-file / test-registry / test-cli
+```
+
+## 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
@@ -40,7 +80,7 @@
         transport: stdio
         command: npx
         args: ['-y', '@modelcontextprotocol/server-gitlab']
-        cwd: .            # 相对项目根解析
+        cwd: .            # resolved relative to the project root
         toolCallTimeoutMs: 60000
         failOnStartupError: false
         reconnect:
@@ -51,51 +91,206 @@
 # <<< dsh-project-mcp-manager:mcp:end
 ```
 
-`transport` 支持 `stdio`（command/args/env/cwd）与 `streamable-http`
-（url/headers）。行加 `disabled: true` 即停用。标记之外的内容逐字节保留。
+`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.
 
-## 安装（挂载到 profile）
+**Divergences from the native cordis dialect**: the `!!js` tag (a js-yaml
+expression evaluated by the profile loader, e.g. the official README's
+`env: { TOKEN: !!js process.env.GITHUB_TOKEN }`) is **not supported** in
+project files — an unresolved tag inside the managed block makes the whole
+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 below);
+`disabled` must be `true`/`false`. 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`.
 
-插件通过 **bundle patch** 挂载：把包加入 `dsh.profile.bundles` 后，dsh 启动时
-按顺序合成每个 bundle 的 patch（`dsh.bundle.patch` 指向的 `cordis.patch.yml`）
-作为插件行。**不要再往 profile 的 `cordis.patch.yml` 手动插入同名行**——两层
-同时存在会启动失败：`duplicate loader entry id: mcp-project`（EntryGroup
-拒绝重复 id）。二选一：留在 bundles，或移出 bundles 改手动插行，不能同时。
+## Claude Code compatibility (read-only)
 
-**本地开发安装**（未发布 npm 前的推荐方式，junction 实时同步源码）：
+To fit the habits of Claude Code users, two CC locations are **loaded** but
+never written by this plugin — with different defaults, because they are
+different risk classes:
 
-```powershell
-cd C:\Users\haima\.dsh\profiles\web
-pnpm add link:D:\path\to\dsh-mcp-project   # 源码包目录
-```
+- `<projectRoot>/.mcp.json` — the CC project file (`{ "mcpServers": { … } }`).
+  An in-repo, version-controlled project declaration: **on by default**,
+  read-only. Turn the whole layer off with `DSH_MCP_IGNORE_MCP_JSON=1`.
+- `~/.claude.json` — only the **top-level `mcpServers`** subtree is read, and
+  only **on explicit request**: set `DSH_MCP_READ_CLAUDE_USER=1`. This is CC's
+  machine-wide user state, not something any one project asked for: mounting
+  it unconditionally fans every such server into *every* known dsh project as
+  its own process — the exact incident that made it opt-in. Nothing else in
+  the file is ever touched, logged or displayed (strict allowlist: oauth
+  credentials, per-project history and UI state stay invisible to this
+  plugin).
+
+Notes and limits:
+
+- **No `local` scope.** CC's `claude mcp add` defaults to a per-project
+  section inside `~/.claude.json` (`projects.<cwd>.mcpServers`); this plugin
+  does not read it. Use `dsh-mcp add --scope user` or the project files.
+- `type: "sse"` entries are rejected with a per-entry diagnostic — the mount
+  backend (`dsh-mcp-client`) only speaks `stdio` and `streamable-http`.
+  CC's `type: "http"` and an explicit `type: "streamable-http"` both map to
+  `streamable-http`; with `type` omitted, an entry that has only `url` (no
+  `command`) is treated as http, everything else as stdio.
+- stdio `cwd`: for project-layer rows an empty `cwd` resolves to the project
+  root; for user-layer rows (both `~/.dsh/mcp.yml` and `~/.claude.json`) it
+  resolves to the dsh host's working directory. Note what "user layer" does
+  *not* mean: user rows still mount **one process per known project** (a
+  session in two projects gets two fibers, renamed `p<hash>_…` per the
+  effective-name rules) — only their `cwd` is shared, not the connection.
+- Unknown CC keys are ignored per entry. `enabled: false` — and, as an alias,
+  `disabled: true` — skips the row silently (no diagnostic, and no name
+  occupancy — see below).
+- A `disabled: true` row in a **native yml** still holds its shadow keys in
+  the shadow chain (see dedup below): same-name rows in lower layers are
+  shadowed too and stay unmounted — disabled means "this name must not run",
+  not "let the CC copy through". CC-side `enabled: false` has no placeholder
+  effect. Consequence: switching off a `.mcp.json` entry without deleting it
+  lets a **same-named user-layer row surface** in that project; to suppress a
+  server across all layers, keep a `disabled: true` placeholder row (matching
+  name or normalized name) in `.dsh/mcp.yml`.
+- Broken files/entries never take down the valid ones; each source fails
+  independently, so an unreadable `.mcp.json` cannot unmount the project's
+  yml rows (and vice versa). Entry errors land in `.dsh/.mcp-diag.json` and
+  the host log (file content is never echoed). A project whose only MCP
+  config is `.mcp.json` still gets a `.dsh/` directory as soon as there is
+  anything worth reporting there.
+- `~/.claude.json` is rewritten by CC on every session; the watcher re-reads
+  it but only triggers reconciliation when the `mcpServers` subtree actually
+  changed (canonical-JSON hash gate).
+- Boundary switches (dsh host environment): `DSH_MCP_READ_CLAUDE_USER=1`
+  opts the `~/.claude.json` user layer in; `DSH_MCP_IGNORE_MCP_JSON=1` turns
+  the project `.mcp.json` layer off; the legacy `DSH_MCP_IGNORE_CLAUDE_JSON=1`
+  force-disables the user layer and **wins over the opt-in** (a one-shot
+  warning names the winner; the legacy switch will be removed in a later
+  release). While the user layer is on, the host logs its fan-out size once
+  ("N servers will join M known projects") so extra spawns are explainable.
+
+**Shadow priority** — layers merge first-come-first-served (1 → 4 below), and
+a row is shadowed when it collides with an earlier row on **any** of three
+keys: the exact `serverName`; the *normalized name* (lowercased with
+non-alphanumerics stripped — `unityMCP` and `unity-mcp` are one service
+written two ways); or the *service identity* (`stdio`: command + args,
+path-case-insensitive on Windows; `streamable-http`: the url). Rows without a
+command/url register no identity key — `node a.js` and `node b.js` stay
+different services — while `disabled` placeholder rows hold all three keys
+without mounting anything. Identity is compared on the **raw strings as
+written in the file, before `${VAR}` expansion**, and `env`, `headers`, `cwd`
+are *not* part of the key: two genuinely different servers sharing one command
+line (but e.g. different env) still collapse to the winner, while the same
+server written once with a `${VAR}` and once as a literal does not match. If a
+drop was unintended, rename the loser (past normalization) or adjust its
+command line. Losers are reported in `.dsh/.mcp-diag.json`
+(`shadowedByYml` / `shadowedByProject` / `shadowedIdentity`) and every
+identity/normalized-name drop warns in the host log:
+
+1. `<projectRoot>/.dsh/mcp.yml` (native, panel/CLI-managed)
+2. `<projectRoot>/.mcp.json` (CC project)
+3. `~/.dsh/mcp.yml` (native user layer — see CLI)
+4. `~/.claude.json` top-level `mcpServers` (CC user, opt-in)
 
-然后在 `package.json` 的 `dsh.profile.bundles` 数组末尾追加
-`"dsh-project-mcp-manager"`，重启 dsh 生效（HMR 只热装首次 insert 的行，
-换实现需重启宿主进程）。
+User-layer rows apply to every known project, so a name defined both in one
+project and in a user layer (or in two projects) participates in the regular
+effective-name conflict renaming (see How it works).
 
-**发布后安装**：`pnpm add dsh-project-mcp-manager`（或 dsh 的插件子命令，
-`dsh plugin --profile web ...`），同样确认包已加入 `dsh.profile.bundles`。
+## `${VAR}` expansion
 
-## 与 dsh-skill-mcp-panel 的关系
+`${VAR}` references (matching `\$\{[A-Za-z_][A-Za-z0-9_]*\}` anywhere in the
+string) in `command`, `args[*]`, `env[*]`, `cwd`, `url` and `headers[*]` — from
+**any** of the four sources above — are **interpolated** from the dsh host
+process environment at mount time (same semantics as Claude Code, so
+`"Authorization": "Bearer ${TOKEN}"` works). An unset or empty variable makes
+the row skip with an `env-missing` diagnostic naming the variable (never its
+value); a literal `${NAME}` that must survive unexpanded is not expressible.
+A `url` containing a reference is accepted by the pre-mount schema in any
+position — including the host part, e.g. `https://${HOST}/mcp` — because
+validity is judged only after expansion: expanded inputs are re-validated
+against the mount schema before spawn, and a malformed result (e.g. a non-URL
+`${GATEWAY}/mcp`) skips the row with an `env-invalid` diagnostic instead of
+reaching the mount backend. In the snapshot/row views, `fiberPhase` stays on
+the mount-lifecycle vocabulary (`pending` for a row that never mounted) and
+the reason rides on a separate `skipReason` field (`env-missing` /
+`env-invalid` / `config-invalid` / `plugin-throw`). 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.
 
-- 已装的 v2.0.1 面板：无项目级装载能力，与本插件不冲突；其全局受管块行
-  会被本插件读取（loader entries），项目同名行自动改名避开。
-- v2.1 面板源码（含 ProjectMcpRegistry）：与本插件功能重复，**同一进程内
-  两者只能启用一个**（双装载同一 serverName 会触发 mcp-client 的进程根
-  预留冲突）。v2.1 写出的项目文件行（`panel-mcp-` 前缀 id）本插件可直接
-  读取，过渡平滑。
+## CLI: `dsh-mcp`
 
-## 构建与测试
+CC-style command-line management for the **native** files (writes only
+`.dsh/mcp.yml` — never `.mcp.json` / `~/.claude.json`; running hosts
+converge via the file watchers, no dsh connection needed):
 
 ```powershell
-npm install
-npm run build     # tsc → lib/
-node test/test-model.mjs
-node test/test-registry.mjs
+dsh-mcp add gitlab npx -y @modelcontextprotocol/server-gitlab -e GITLAB_TOKEN=${GITLAB_TOKEN}
+dsh-mcp add --transport http sentry https://mcp.sentry.dev/mcp -H "Authorization: Bearer ${SENTRY_TOKEN}"
+dsh-mcp add --scope user shared node ./tools/shared.js   # writes ~/.dsh/mcp.yml
+dsh-mcp list          # all four layers, with shadow annotations
+dsh-mcp get gitlab    # winning entry, secret values shown as key names only
+dsh-mcp remove gitlab # native yml only; read-only layers get guidance
 ```
 
-## 安全边界
+Scopes: `--scope project` (default; writes `<projectRoot>/.dsh/mcp.yml` under
+the nearest `.git` ancestor) and `--scope user` (writes `~/.dsh/mcp.yml`,
+mounted into every project). `add` defaults `cwd` to `"."` (project root) for
+project scope and `""` (host directory) for user scope; `-c` overrides.
+There is no `local` scope — `--scope local`
+fails with an explanation. `--transport` accepts `stdio` (default) and `http`;
+`sse` is refused (unsupported by the backend).
+
+## 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), but only edits to the **exact** config files of
+  known project roots — `<projectRoot>/.dsh/mcp.yml` and
+  `<projectRoot>/.mcp.json` — trigger a full reconciliation after a 150 ms
+  debounce: added lines are mounted, removed lines are unmounted, and config
+  changes are remounted. A second watcher covers the user layer as two
+  **exact file paths** — `~/.dsh/mcp.yml` and `~/.claude.json` (chokidar v5
+  notices a watched file being created as long as its parent directory
+  exists) — never the home directory at large. `~/.claude.json` events are
+  arbitrated by the canonical-JSON content hash alone (no size/mtime fast
+  path: same-instant, same-length rewrites with different content must not be
+  swallowed).
+- **Effective names**: when the original `serverName` is unique across the
+  whole catalog (global lines + all project lines, where each project's
+  merged rows include the user-layer rows that survived shadowing) 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. 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; 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
 
-`.dsh/mcp.yml` 中的 `stdio` 行会在 dsh 宿主进程内 spawn 其 `command`——
-项目文件是**可执行代码载体**，只应在可信项目中添加。装载失败/配置无效行
-仅告警跳过，不影响其他服务器。
+`stdio` lines in `.dsh/mcp.yml` (and `.mcp.json` rows mounted from it) 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. CC's machine-wide `~/.claude.json` user layer is therefore **off by
+default**: reading it opts foreign, environment-level servers into every
+project's spawn set, which must be a deliberate `DSH_MCP_READ_CLAUDE_USER=1`.
+The read-only allowlist exists precisely because that file also holds
+credentials: nothing from it is ever written out, echoed into diagnostics, or
+printed by the CLI.

package/docs/README.zh.md

@@ -0,0 +1,244 @@
+# 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.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
+```
+
+**升级/锁定版本**：重跑方式一的 `add` 命令并带上目标版本后缀——`@latest`
+升级到最新，`@0.2.0` 锁定到指定版本。
+
+## 构建与测试
+
+```powershell
+npm install
+npm run build     # tsc → lib/
+npm test          # node 直跑 test/ 下五个 .mjs（model / mcp-file / cc-file / registry / cli）
+```
+
+## 配置格式
+
+`<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` 即停用。标记之外的内容逐字节保留。
+
+**与原生 cordis 方言的差异**：`!!js` 标签（profile 的 `cordis.patch.yml` 由
+Loader 求值的 js-yaml 表达式，如官方 README 示例 `env: { TOKEN: !!js
+process.env.GITHUB_TOKEN }`）在项目文件里**不支持**——受管块内出现未解析
+标签会使该文件整体报错跳过（写入 `.dsh/.mcp-diag.json` 并打日志），不会把
+表达式当字面量字符串静默装载。`env`/`headers` 的值 otherwise 是字面量，仅
+`${VAR}` 引用会在装载时做串内插值（见下文「${VAR} 展开」）；`disabled` 只能是
+`true`/`false`。反之项目文件是超集语法：`env`/`headers` 允许 `KEY: null`
+表示删除该键（装载时被剔除），这在官方 mcp-client 校验里会被拒绝——把这类
+行原样挪回 `cordis.patch.yml` 会装载失败。
+
+## Claude Code 兼容层（只读）
+
+为顺应 CC 用户习惯，插件会**装载**以下两个 CC 配置位置，但从不写入它们。
+两者的默认姿态不同，因为风险等级不同：
+
+- `<projectRoot>/.mcp.json` —— CC 的 project 层文件（`{ "mcpServers": { … } }`）。
+  它是随仓库版本管理的项目自身声明：**默认开启**、只读。设
+  `DSH_MCP_IGNORE_MCP_JSON=1` 可整层停用。
+- `~/.claude.json` —— 只读取**顶层 `mcpServers`** 子树，且**只在显式请求时**：
+  设 `DSH_MCP_READ_CLAUDE_USER=1` 才读。这是 CC 的机器级用户状态，不属于任何
+  项目：无条件读取会把每台这样的服务器扇出到**每个已知 dsh 项目**各起一个
+  进程——这正是把它改为 opt-in 的事故根因。该文件其余内容一律不读入配置、
+  不写、不打日志、不在任何输出里回显（严格 allowlist：oauth 凭据、项目历史、
+  UI 状态对本插件不可见）。
+
+边界与限制：
+
+- **没有 local 作用域**。CC 的 `claude mcp add` 默认写进 `~/.claude.json` 的
+  `projects.<cwd>.mcpServers`（local 层），本插件不读取该层；请用
+  `dsh-mcp add --scope user` 或项目文件。
+- `type: "sse"` 条目按条目报错跳过——装载后端（`dsh-mcp-client`）只支持
+  `stdio` 与 `streamable-http`。CC 的 `type: "http"` 与显式
+  `type: "streamable-http"` 都映射为 `streamable-http`；缺省 `type` 时，
+  只带 `url` 不带 `command` 的条目按 http 处理，其余视为 stdio。
+- stdio 的 `cwd`：项目层行的空 `cwd` 解析为项目根；用户层行
+  （`~/.dsh/mcp.yml` 与 `~/.claude.json`）解析为 dsh 宿主的工作目录。
+  注意"用户层"不等于共享进程：用户层行仍**按每个已知项目各装一个进程**
+  （两个项目各开会话就是两个 fiber，按生效名规则改名为 `p<hash>_…`）——
+  共享的只是 `cwd`，不是连接。
+- 未知 CC 键容忍忽略；`enabled: false`（以及作为别名的 `disabled: true`）
+  静默跳过该条目（不记诊断，也不占名）。
+- 原生 yml 里 `disabled: true` 的行仍**占住影子键**（见下方去重规则）：下层
+  同名行一并被遮蔽不装载——禁用意味着"这个名字不许跑"，而不是"让位给 CC
+  副本"。CC 侧的 `enabled: false` 没有占位效果。推论：不删除、只在
+  `.mcp.json` 里关掉一条，同名的**用户层行会在该项目浮上来**装载；要把某台
+  服务器在所有层压住，请在 `.dsh/mcp.yml` 留一条 `disabled: true` 占位行
+  （名字或归一化名字对上即可）。
+- 坏文件/坏条目不影响其他服务器，且**按源隔离**：`.mcp.json` 坏了不会卸掉
+  同项目的 yml 行（反之亦然）；条目错误写入 `.dsh/.mcp-diag.json` 与宿主
+  日志（诊断从不带文件内容）。只有 `.mcp.json`、没用过原生 yml 的项目，
+  一旦有可报内容也会创建 `.dsh/` 目录。
+- CC 每次会话都会重写 `~/.claude.json`；watcher 会对该文件做
+  `mcpServers` 子树的规范化哈希门控——子树没变就不触发对账。
+- 共存边界开关（dsh 宿主环境变量）：`DSH_MCP_READ_CLAUDE_USER=1` 显式启用
+  `~/.claude.json` 用户层；`DSH_MCP_IGNORE_MCP_JSON=1` 停用项目 `.mcp.json`
+  层；旧开关 `DSH_MCP_IGNORE_CLAUDE_JSON=1` 为强制关闭用户层，**优先级高于
+  opt-in**（冲突时打一次「胜出」告警；旧开关将在后续版本移除）。用户层开启
+  时，宿主一次性日志提示扇出规模（「N 条服务器将并入 M 个已知项目」），
+  让多出来的 spawn 可解释、可回退。
+
+**影子优先序**——按 1→4 先到先得合并，后到行与已收录行命中**三把键中的任何
+一把**即被遮蔽：精确 `serverName`；*归一化名称*（转小写去掉非字母数字后相同
+——`unityMCP` 与 `unity-mcp` 就是一台服务器的两种写法）；*服务身份*
+（`stdio` 取 command + args，Windows 下路径大小写不敏感；`streamable-http`
+取 url）。command/url 为空的行不注册身份键——`node a.js` 与 `node b.js` 是
+不同服务、绝不互杀——而 `disabled` 占位行三键全占、自身不装载。身份比对用的
+是**文件里的原始字符串，发生在 `${VAR}` 展开之前**，且 `env`、`headers`、
+`cwd` **不参与**身份键：同一命令行、仅 env 不同的两台真不同服务器仍会被去重
+（只留高优先级一条），同一台服务器一条写 `${VAR}`、一条写字面量则**不**互认。
+误剔时的处置：给被剔行改名（归一化后不同）或调整命令与参数。被遮蔽方写入
+`.dsh/.mcp-diag.json`（`shadowedByYml` / `shadowedByProject` /
+`shadowedIdentity`），身份/归一名去重剔除的每行还会在宿主日志告警「跳过重复
+服务定义」：
+
+1. `<projectRoot>/.dsh/mcp.yml`（原生格式，面板/CLI 管理）
+2. `<projectRoot>/.mcp.json`（CC project 层）
+3. `~/.dsh/mcp.yml`（原生用户层，见 CLI）
+4. `~/.claude.json` 顶层 `mcpServers`（CC user 层，opt-in）
+
+用户层行适用于所有已知项目，因此「某项目与用户层同名」（或两个项目同名）
+会走常规的生效名冲突改名规则（见工作原理）。
+
+## `${VAR}` 展开
+
+以上任一来源中，`command`、`args[*]`、`env[*]`、`cwd`、`url`、`headers[*]` 里的
+`${VAR}` 引用（正则 `\$\{[A-Za-z_][A-Za-z0-9_]*\}`，允许出现在字符串任意
+位置）在装载时刻从 dsh 宿主进程环境做**串内插值**——与 Claude Code 同语义，
+`"Authorization": "Bearer ${TOKEN}"` 这类写法可用。变量未设置**或为空串**时
+该行跳过装载，诊断记 `env-missing` 并只带变量名（绝不带值）；需要保留字面
+`${NAME}` 的写法目前不可表达。含引用的 `url` 在装载前的 schema 校验里任意
+位置都放行（包括 host 段，如 `https://${HOST}/mcp`）——合法性只在展开后判定：
+展开结果会再过一遍装载 schema 复验，产出非法配置（如 `${GATEWAY}/mcp` 拼出
+非 URL）时以 `env-invalid` 跳过，不把坏值递给装载后端。快照/行视图里
+`fiberPhase` 保持装载生命周期枚举（未挂上的行是 `pending`），跳过原因走独立
+的 `skipReason` 字段（`env-missing` / `env-invalid` / `config-invalid` /
+`plugin-throw`）。插件任何写路径都不落盘展开后的值；
+CLI 写入时 `${VAR}` 原样保留——配置可以进 git，凭据留在环境里。
+
+## CLI：`dsh-mcp`
+
+CC 风格的原生文件命令行管理（**只写** `.dsh/mcp.yml`——从不写
+`.mcp.json` / `~/.claude.json`；不连接运行中的 dsh 宿主，宿主经文件监听自动
+收敛）：
+
+```powershell
+dsh-mcp add gitlab npx -y @modelcontextprotocol/server-gitlab -e GITLAB_TOKEN=${GITLAB_TOKEN}
+dsh-mcp add --transport http sentry https://mcp.sentry.dev/mcp -H "Authorization: Bearer ${SENTRY_TOKEN}"
+dsh-mcp add --scope user shared node ./tools/shared.js   # 写 ~/.dsh/mcp.yml
+dsh-mcp list          # 四个来源全展示，带遮蔽标注
+dsh-mcp get gitlab    # 优先层条目；密钥值只显示键名
+dsh-mcp remove gitlab # 只动原生 yml；命中只读层时给出编辑指引
+```
+
+作用域：`--scope project`（缺省，写最近 `.git` 祖先下的
+`.dsh/mcp.yml`）与 `--scope user`（写 `~/.dsh/mcp.yml`，装载进每个项目）。
+`add` 的 `cwd` 缺省随作用域而变：project 为 `"."`（项目根），user 为 `""`
+（宿主目录）；`-c` 显式覆盖。
+没有 `local` 作用域——`--scope local` 会报错并解释。`--transport` 接受
+`stdio`（缺省）与 `http`；`sse` 拒绝（后端不支持）。
+
+## 工作原理
+
+- **项目发现**：在线 agent 会话的 `session.header.cwd` + dsh 进程启动目录 →
+  向上找最近的含 `.git` 的祖先目录作为项目根（无 `.git` 时退回目录本身）。
+- **装载**：每个 `(项目, serverName)` 在宿主 ctx 上装载一个
+  `@deepseek-ai/dsh-mcp-client` 实例（`ctx.plugin`），注册进全局工具层。
+  同一项目内多会话共享同一连接。
+- **热重载**：chokidar 监听各项目根（depth 2，忽略 node_modules/.git/.hg/
+  .svn），但只有**已知项目根的精确配置文件**（`<projectRoot>/.dsh/mcp.yml`
+  与 `<projectRoot>/.mcp.json`）的改动经 150ms 防抖触发全量对账：新增行
+  装载、删除行卸载、配置变化重装。另有独立 watcher 以**两个精确文件路径**
+  监听用户层：`~/.dsh/mcp.yml` 与 `~/.claude.json`（chokidar v5 对被监听的
+  缺失文件能在其创建时补发事件，前提是父目录已存在）——不监听家目录整体。
+  `~/.claude.json` 事件只由规范化内容哈希门裁决（没有 size/mtime 快路径：
+  同刻、同体积而内容不同的重写不能被吞掉）。
+- **生效名**：原始 `serverName` 在整个目录（全局行 + 全部项目行；每个项目的
+  行集合含遮蔽后幸存的用户层行）中唯一时
+  保持原名；冲突时双方都改为 `p<sha256(项目根)前6位>_<原名>`（截断 32 字符，
+  确定性、与装载顺序无关），避免 `dsh-mcp-client` 按进程根的 serverName
+  预留冲突。全局行（profile `cordis.patch.yml` / bundle 层已装载的
+  mcp-client 行）参与占用判定但不改名。模型可见的工具名由生效服务器名与
+     MCP 工具自身的名字拼成 `mcp__<生效名>__<工具名>`，与文件里写的 `serverName` 可能不同。
+- **会话可见性**：agent 创建时按其会话 cwd 解析项目，对该 agent 应用
+  `tools.restrict({ deny })`，deny 掉除本会话项目外的全部项目服务器；会话
+  无 cwd 时回退 owner 项目（子代理），再回退 dsh 进程 cwd 所在项目。会话
+  销毁时释放。
+
+## 安全边界
+
+`.dsh/mcp.yml` 中的 `stdio` 行（以及经兼容层装载的 `.mcp.json` 行）会在 dsh
+宿主进程内 spawn 其 `command`——项目文件是**可执行代码载体**，只应在可信项目
+中添加。装载失败/配置无效行仅告警跳过，不影响其他服务器。CC 的机器级
+`~/.claude.json` 用户层因此**默认关闭**：读取它等于把外来的环境级服务器塞进
+每个项目的 spawn 集合，必须是显式决定（`DSH_MCP_READ_CLAUDE_USER=1`）。
+`~/.claude.json` 之所以同时按严格 allowlist 只读，正是因为该文件还存放凭据：
+其中未使用的部分不会被读出、写入任何文件，也不会在 CLI 或诊断输出里出现。