dsh-project-mcp-manager 0.1.0 → 0.1.1

package/README.md

@@ -1,91 +1,62 @@
 # 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)
 
-```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
-```
+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.
 
-`transport` 支持 `stdio`（command/args/env/cwd）与 `streamable-http`
-（url/headers）。行加 `disabled: true` 即停用。标记之外的内容逐字节保留。
+## Installation (mount into a profile)
 
-## 安装（挂载到 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.
 
-插件通过 **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 改手动插行，不能同时。
+**Prerequisite: install dsh itself** (for users who don't have dsh yet):
 
-**本地开发安装**（未发布 npm 前的推荐方式，junction 实时同步源码）：
+```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
-cd C:\Users\haima\.dsh\profiles\web
-pnpm add link:D:\path\to\dsh-mcp-project   # 源码包目录
+# 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
 ```
 
-然后在 `package.json` 的 `dsh.profile.bundles` 数组末尾追加
-`"dsh-project-mcp-manager"`，重启 dsh 生效（HMR 只热装首次 insert 的行，
-换实现需重启宿主进程）。
+**Option 2: install directly with pnpm** (equivalent to option 1):
 
-**发布后安装**：`pnpm add dsh-project-mcp-manager`（或 dsh 的插件子命令，
-`dsh plugin --profile web ...`），同样确认包已加入 `dsh.profile.bundles`。
+```powershell
+# dshHome defaults to %USERPROFILE%\.dsh (uses $DSH_HOME if set)
+cd $env:USERPROFILE\.dsh\profiles\web
+pnpm add dsh-project-mcp-manager@latest
+```
 
-## 与 dsh-skill-mcp-panel 的关系
+**Option 3: local development install** (a junction that live-syncs your
+source, so code changes take effect immediately):
 
-- 已装的 v2.0.1 面板：无项目级装载能力，与本插件不冲突；其全局受管块行
-  会被本插件读取（loader entries），项目同名行自动改名避开。
-- v2.1 面板源码（含 ProjectMcpRegistry）：与本插件功能重复，**同一进程内
-  两者只能启用一个**（双装载同一 serverName 会触发 mcp-client 的进程根
-  预留冲突）。v2.1 写出的项目文件行（`panel-mcp-` 前缀 id）本插件可直接
-  读取，过渡平滑。
+```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
@@ -94,8 +65,70 @@ 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
+```
 
-`.dsh/mcp.yml` 中的 `stdio` 行会在 dsh 宿主进程内 spawn 其 `command`——
-项目文件是**可执行代码载体**，只应在可信项目中添加。装载失败/配置无效行
-仅告警跳过，不影响其他服务器。
+`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.

package/docs/README.zh.md

@@ -0,0 +1,114 @@
+# 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`——
+项目文件是**可执行代码载体**，只应在可信项目中添加。装载失败/配置无效行
+仅告警跳过，不影响其他服务器。

package/lib/registry.js

@@ -21,8 +21,8 @@
  * 会话”场景）。
  */
 import chokidar from "chokidar";
-import { join, resolve } from "node:path";
-import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import * as mcpClient from "@deepseek-ai/dsh-mcp-client";
 import { extractManagedRows, readPatchFile } from "./mcp-file.js";
 import { findProjectRoot } from "./project-root.js";
@@ -296,14 +296,23 @@ export class ProjectMcpRegistry {
                 }
             }
             catch (catchError) {
-                if (this.projects.has(key) || !String(catchError).includes("ENOENT")) {
+                const message = catchError instanceof Error ? catchError.message : String(catchError);
+                // 「配置文件不存在」(ENOENT) 只有在该项目确实有活着的装载时才算异常——
+                // 意味着文件在装载之后被删/移走。零配置项目缺文件是常态：不能用
+                // projects.has(key) 当判据，空项目条目也会让它恒真（误报根因）。
+                const liveServers = this.projects.get(key)?.servers.size ?? 0;
+                if (liveServers > 0 || !message.includes("ENOENT")) {
                     ok = false;
-                    error = catchError instanceof Error ? catchError.message : String(catchError);
+                    error = message;
                 }
                 rows = [];
             }
             desiredByProject.set(key, { projectRoot, rows, ok, error });
-            await this.writeDiag(projectRoot, { kind: "scan", ok, error, rows: rows.map((row) => row.rawName) });
+            // 诊断只记有信息量的扫描：异常，或确实解析出了配置行。干净且无配置的
+            // 项目不写任何记录——否则每个被访问过的目录都会凭空多出 .dsh/.mcp-diag.json。
+            if (!ok || rows.length > 0) {
+                await this.writeDiag(projectRoot, { kind: "scan", ok, error, rows: rows.map((row) => row.rawName) });
+            }
         }
         const catalogProjects = [...desiredByProject.values()]
             .filter((entry) => entry.ok)
@@ -318,6 +327,11 @@ export class ProjectMcpRegistry {
     async reconcileProject(key, entry) {
         let project = this.projects.get(key);
         if (project === undefined) {
+            // 只为「确实有行要装载」的项目建条目：否则会话/进程访问过的每个目录都会
+            // 永久留在 projects 里（knownProjects 会一直把它带上），零配置项目也就
+            // 不该算作已知项目。已有条目保留，用于卸载后仍能在快照里看到该文件。
+            if (entry.rows.length === 0)
+                return;
             project = { projectRoot: entry.projectRoot, servers: new Map() };
             this.projects.set(key, project);
         }
@@ -330,6 +344,7 @@ export class ProjectMcpRegistry {
             await this.mountServer(project, item);
     }
     // ── 装载诊断（写 <projectRoot>/.dsh/.mcp-diag.json，宿主日志不可见时定位失败）──
+    // 调用方只在有异常或有配置行时写入：无配置的干净项目不创建该文件。
     async writeDiag(projectRoot, event) {
         try {
             const path = join(projectRoot, ".dsh", ".mcp-diag.json");
@@ -345,6 +360,8 @@ export class ProjectMcpRegistry {
             lines.push({ ts: new Date().toISOString(), ...event });
             if (lines.length > 30)
                 lines = lines.slice(-30);
+            // .dsh 可能已被用户删掉（而项目仍有活装载）：补建目录，避免诊断静默丢失。
+            await mkdir(dirname(path), { recursive: true });
             await writeFile(path, JSON.stringify(lines, null, 2), "utf8");
         }
         catch {

package/package.json

@@ -1,48 +1,49 @@
-{
-  "name": "dsh-project-mcp-manager",
-  "version": "0.1.0",
-  "description": "dsh-project-mcp-manager: per-project MCP server loading for DSH. Reads <projectRoot>/.dsh/mcp.yml, mounts each server as an @deepseek-ai/dsh-mcp-client instance, hot-reloads on file change, and scopes tool visibility per session.",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./package.json": "./package.json"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "license": "MIT",
-  "author": "wldxiaobai <944418001@qq.com>",
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "mcp",
-    "project",
-    "plugin",
-    "cordis"
-  ],
-  "dependencies": {
-    "@deepseek-ai/dsh-mcp-client": "^0.1.1-rc.2",
-    "chokidar": "^5.0.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build",
-    "test": "node test/test-model.mjs && node test/test-registry.mjs"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md",
-    "LICENSE"
-  ],
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@types/node": "^26.2.0",
-    "typescript": "^7.0.2"
-  }
-}
+{
+  "name": "dsh-project-mcp-manager",
+  "version": "0.1.1",
+  "description": "dsh-project-mcp-manager: per-project MCP server loading for DSH. Reads <projectRoot>/.dsh/mcp.yml, mounts each server as an @deepseek-ai/dsh-mcp-client instance, hot-reloads on file change, and scopes tool visibility per session.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "author": "wldxiaobai <944418001@qq.com>",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "mcp",
+    "project",
+    "plugin",
+    "cordis"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-mcp-client": "^0.1.1-rc.2",
+    "chokidar": "^5.0.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "node test/test-model.mjs && node test/test-registry.mjs"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "docs",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  }
+}