@luchenglong/cli-bridge 0.2.13 → 0.2.14

package/CHANGELOG.md

@@ -9,6 +9,46 @@ GitHub Release（`scripts/verify.mjs` 在 CI 与 prepack 双重锁一致）。
 > - CodeBuddy 线：[docs/history/codebuddy/CHANGELOG.md](docs/history/codebuddy/CHANGELOG.md)（终版 1.6.2）
 > - MiMo 线：[docs/history/mimo/CHANGELOG.md](docs/history/mimo/CHANGELOG.md)（终版 1.2.9）
 
+## [0.2.14] - 2026-10-23
+
+> 用户反馈：「agent 委派任务时 agy/opencode/claude/codex 部分 CLI 报错：无权编辑工作区外的内容」。
+> 根因不是 CLI 的沙箱太严，而是**工作区边界一开始就定错了**。
+
+### Fixed
+- **MCP 形态下所有 provider 的工作目录都可能是错的**（这是本次报错的根因）。
+  链路：`@deepseek-ai/dsh-mcp-client` 启动 stdio server 时 `config.cwd` 默认是**空字符串**
+  （源码里 `cwd: z.string().default("")`），于是 MCP 进程的 `process.cwd()` 是 **DSH 主进程
+  的目录**（dsh-home / 安装目录），而不是用户的会话目录。而各 provider 的 cwd 兜底恰好是
+  `process.env.<ID>_MCP_CWD || process.cwd()` —— 于是 CLI 认为"工作区"是那个无关目录，
+  用户项目里的一切都成了"工作区外"：
+  - **codex**：`-s workspace-write` 直接拒绝写入
+  - **claude / opencode / agy**：按各自的 project 边界拒绝
+  实测复现（同一组任务，cwd 正确前的表现）：agy 能写区外、codex/claude/opencode 失败。
+
+  修复：新增 `mcp/session-cwd.mjs`，用 DSH 提供给子进程的 `DSH_SESSION_ID` 从 projcache 的
+  `record.identity.cwd` 读出**会话真实目录**，把兜底链补成：
+  `args.cwd`（调用方显式传）→ `<ID>_MCP_CWD`（用户 env）→ **会话真实目录** → `process.cwd()`。
+  六家全部接入（agy / codebuddy / mimo / opencode / claude / codex）。
+  读取全程容错：任何失败都返回空串继续往下兜底，绝不打断工具调用；结果按会话 id 缓存 60s。
+
+  验证（`tests/e2e/session-cwd-fix.mjs`）：故意把 MCP 进程 cwd 设成一个无关目录、会话目录
+  设为 `my-project`，调用时不传 cwd —— 状态文件记录的 cwd 是 `my-project`，即用的是会话目录
+  而非进程目录。
+
+### 说明（不是缺陷，但会继续表现为「无权编辑」）
+- **codex 的 `-s workspace-write` 只能写 cwd 之内**，这是它自身的安全设计。cwd 修好后，
+  常规"在项目内改文件"已经正常；要**跨项目/写工作区外**仍会被拒，需要显式放宽：
+  - 传 `sandboxMode: 'danger-full-access'`（或在设置面板改「沙箱模式」）
+  - 或传 `addDirs: [...]` 追加可写目录（claude/agy 走 `--add-dir`；codex exec 亦支持）
+- claude / agy 用 `--dangerously-skip-permissions`，opencode 用 `--auto`，本就没有沙箱限制；
+  它们此前的失败来自 cwd 错位（本次修复），以及排查过程中观察到的**免费额度限流**
+  （`429 free-models-per-day-high-balance`）与 cc-switch 代理未启动（见下）。
+
+### 排查环境记录（避免误判为插件缺陷）
+- 复现过程中 codex / opencode 返回 `429 Rate limit exceeded: free-models-per-day-high-balance`，
+  claude 返回 `API Error: Connection error` —— 后者根因是 **cc-switch 本地代理 15721 未运行**
+  （`ECONNREFUSED`），并非插件问题。claude 依赖该代理补 session 头（见 0.2.11）。
+
 ## [0.2.13] - 2026-10-20
 
 > 用户反馈「通道可能通了，但是我没有看到状态灯」。查证后：**灯没坏，是显示条件没被满足**

package/PROVIDER-CONTRACT.md

@@ -212,6 +212,37 @@ export function check(env) → true | throw                             // --che
 `{homeDir}/cli-bridge-mcp-<id>.json`**（用 bridge-kit 的 buildMcpBridgePayload + 原子写
 `tmp→rename`）。允许 `import node:*`（MCP 是真 Node 进程）。
 
+### 4.1 cwd 解析（**必读**，0.2.14 事故）
+
+MCP 形态**没有** `getCwdFallback`（那是 preset/dynamic 才有的 hostOpts）。cwd 兜底链必须走
+`mcp/session-cwd.mjs`：
+
+```
+args.cwd（调用方显式传，最可靠）
+  → env <ID>_MCP_CWD（用户覆盖）
+  → resolveSessionCwd(env)      ← 会话真实目录，经 DSH_SESSION_ID 从 projcache 读
+  → process.cwd()               ← 最后兜底
+```
+
+**为什么不能用 `|| process.cwd()` 直接兜底**（这正是 0.2.14 修的 bug）：
+`@deepseek-ai/dsh-mcp-client` 启动 stdio server 时 `config.cwd` 默认是**空字符串**
+（源码 `cwd: z.string().default("")`），所以 MCP 进程的 `process.cwd()` 是 **DSH 主进程的
+目录**（dsh-home / 安装目录），不是用户会话目录。CLI 据此把整个用户项目判成"工作区外"：
+
+- codex `-s workspace-write` → 直接拒绝写入
+- claude / opencode / agy → 按各自 project 边界拒绝
+
+DSH 会给子进程 `DSH_SESSION_ID`（实测存在），但**不给**会话目录的环境变量 —— 所以必须自己
+从 `{DSH_HOME}/storages/session_projcache/sessions/<sessionId>.json` 的
+`record.identity.cwd` 读。读取全程容错（失败返回空串继续兜底），结果按会话 id 缓存 60s。
+
+回归防线：`tests/keystone/session-cwd.test.mjs` 会检查每个 provider 都 import 了
+`session-cwd.mjs`，且**不再出现裸 `|| process.cwd()` 兜底**；
+`tests/e2e/session-cwd-fix.mjs` 在"MCP 进程 cwd 故意设错"的条件下验证实际用的是会话目录。
+
+注意：cwd 修好只代表"工作区对了"。codex 的 `workspace-write` 仍不允许写 cwd 之外 ——
+那是它的安全设计，跨项目任务需显式传 `sandboxMode: 'danger-full-access'` 或 `addDirs`。
+
 ## 5. 交付文件清单（每个 provider 完全一致，路径冻结）
 
 | 文件 | 形态 | 说明 |

package/mcp/cli-bridge-mcp.mjs

@@ -33,7 +33,7 @@ import * as claudeMcp from './providers/claude.mjs'
 import * as codexMcp from './providers/codex.mjs'
 
 const SERVER_NAME = 'cli-bridge-mcp'
-const SERVER_VERSION = '0.2.13'
+const SERVER_VERSION = '0.2.14'
 const PROTOCOL = '2024-11-05'
 
 const PROVIDERS = [agyMcp, codebuddyMcp, mimoMcp, opencodeMcp, claudeMcp, codexMcp]

package/mcp/providers/agy.mjs

@@ -12,6 +12,7 @@
 //  - 无 ctx.emit：状态走快照文件 {homeDir}/cli-bridge-mcp-agy.json
 //    （bridge-kit buildMcpBridgePayload + 原子写 tmp→rename；写失败静默）。
 import { spawn as nodeSpawn } from 'node:child_process'
+import { resolveCwdWithSession } from '../session-cwd.mjs'
 import { existsSync } from 'node:fs'
 import { resolve as resolvePath } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -57,10 +58,15 @@ function exePrefix() {
   }
   return [process.platform === 'win32' ? 'agy.exe' : 'agy']
 }
-function resolveCwd(a) {
-  if (a && a.cwd) return resolvePath(String(a.cwd))
-  return process.env.AGY_MCP_CWD || process.cwd()
-}
+    function resolveCwd(a) {
+      if (a && a.cwd) return resolvePath(String(a.cwd))
+      // 兜底链：用户 env 覆盖 → **会话真实目录** → process.cwd()。末两级很关键：
+      // MCP server 由 DSH 以空 cwd 启动，process.cwd() 是 DSH 主进程目录而非用户项目，
+      // 直接用会让 CLI 把整个项目判成「工作区外」（agy/claude/opencode/codex 都踩过）。
+      const envCwd = process.env.AGY_MCP_CWD
+      if (envCwd) return resolvePath(String(envCwd))
+      return resolveCwdWithSession(null, '', resolvePath)
+    }
 
 // ── spawn（旧 runAgy verbatim 语义；实时折叠走 bridge-kit 行流）────────────────
 function runAgy(args) {

package/mcp/providers/claude.mjs

@@ -9,6 +9,7 @@
 // 工具名/schema 从描述符取（单一来源，防两处漂移），描述与 background 语义按 MCP 面重写：
 // MCP 没有 DSH jobs，background 参数在该形态无意义，故 schema 里裁掉。
 import { spawn as nodeSpawn } from 'node:child_process'
+import { resolveCwdWithSession } from '../session-cwd.mjs'
 import { readFileSync } from 'node:fs'
 import { resolve as resolvePath, dirname } from 'node:path'
 
@@ -67,10 +68,15 @@ const engine = createStatusEngine({ provider, publish: publishSnapshot })
 provider.engine = engine
 
 function exePrefix() { return resolveExePrefix(process.env, '') }
-function resolveCwd(a) {
-  if (a && a.cwd) return resolvePath(String(a.cwd))
-  return process.env.CLAUDE_MCP_CWD || process.cwd()
-}
+    function resolveCwd(a) {
+      if (a && a.cwd) return resolvePath(String(a.cwd))
+      // 兜底链：用户 env 覆盖 → **会话真实目录** → process.cwd()。末两级很关键：
+      // MCP server 由 DSH 以空 cwd 启动，process.cwd() 是 DSH 主进程目录而非用户项目，
+      // 直接用会让 CLI 把整个项目判成「工作区外」（agy/claude/opencode/codex 都踩过）。
+      const envCwd = process.env.CLAUDE_MCP_CWD
+      if (envCwd) return resolvePath(String(envCwd))
+      return resolveCwdWithSession(null, '', resolvePath)
+    }
 
 // ── spawn（实时折叠走 bridge-kit 行流；.cmd 走 shell）─────────────────────────
 function runClaude(args) {

package/mcp/providers/codebuddy.mjs

@@ -19,6 +19,7 @@
 //  - 设置：统一文件 cli-bridge-settings.json 的 codebuddy 分区（5s 缓存），旧扁平
 //    文件的字段级迁移在 DSH 面板侧由 keystone 完成；这里读不到即用默认值。
 import { spawn as nodeSpawn } from 'node:child_process'
+import { resolveSessionCwd } from '../session-cwd.mjs'
 import { existsSync, readFileSync } from 'node:fs'
 import { resolve as resolvePath, join as nodePathJoin } from 'node:path'
 
@@ -127,7 +128,12 @@ function cwdBlockedReason(cwd, io) {
 function runCodebuddy(args, io) {
   return new Promise((resolve) => {
     const settings = readSettings(io)
-    const cwdFallback = (io.env || {}).CODEBUDDY_MCP_CWD || process.cwd()
+    // cwd 兜底链：用户 env 覆盖 → **会话真实目录** → process.cwd()。
+    // 末两级很关键：MCP server 由 DSH 以空 cwd 启动，process.cwd() 是 DSH 主进程目录，
+    // 而非用户项目；直接用会让 CLI 把整个项目判成「工作区外」（或撞 cwd 白名单）。
+    const cwdFallback = (io.env || {}).CODEBUDDY_MCP_CWD
+      || resolveSessionCwd(io.env)
+      || process.cwd()
     const target = engine.resolveTarget(args, cwdFallback)
     const backend = provider.resolveBackend(args, target, settings.preferredBackend)
     // 端点/凭据：端点按登录域自动对齐（修 npm 面 401）；凭据仅 codebuddy-en 需要

package/mcp/providers/codex.mjs

@@ -11,6 +11,7 @@
 //   • 模型清单没有 CLI 子命令，只能走 HTTP /models（descriptor 的 codex_models 负责），
 //     这里只做工具面转接，不复制解析逻辑。
 import { spawn as nodeSpawn } from 'node:child_process'
+import { resolveCwdWithSession } from '../session-cwd.mjs'
 import { resolve as resolvePath } from 'node:path'
 import { readFileSync } from 'node:fs'
 import { dirname } from 'node:path'
@@ -78,10 +79,15 @@ function exePrefix() {
   return codexResolveExePrefix(process.env, '')
 }
 
-function resolveCwd(a) {
-  if (a && a.cwd) return resolvePath(String(a.cwd))
-  return process.env.CODEX_BRIDGE_CWD || process.cwd()
-}
+    function resolveCwd(a) {
+      if (a && a.cwd) return resolvePath(String(a.cwd))
+      // 兜底链：用户 env 覆盖 → **会话真实目录** → process.cwd()。末两级很关键：
+      // MCP server 由 DSH 以空 cwd 启动，process.cwd() 是 DSH 主进程目录而非用户项目，
+      // 直接用会让 CLI 把整个项目判成「工作区外」（agy/claude/opencode/codex 都踩过）。
+      const envCwd = process.env.CODEX_BRIDGE_CWD
+      if (envCwd) return resolvePath(String(envCwd))
+      return resolveCwdWithSession(null, '', resolvePath)
+    }
 
 function baseResult(over) {
   return Object.assign({

package/mcp/providers/mimo.mjs

@@ -21,6 +21,7 @@
 // 登录由用户在 CLI 侧 `mimo auth login` 自理。
 
 import { spawn as nodeSpawn } from 'node:child_process'
+import { resolveCwdWithSession } from '../session-cwd.mjs'
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs'
 import { dirname, join as joinPath, resolve as resolvePath } from 'node:path'
 
@@ -90,10 +91,15 @@ provider.engine = engine
 function exePrefix() {
   return resolveMimoExePrefix(process.env)
 }
-function resolveCwd(a) {
-  if (a && a.cwd) return resolvePath(String(a.cwd))
-  return process.env.MIMO_MCP_CWD || process.env.MIMO_BRIDGE_CWD || process.cwd()
-}
+    function resolveCwd(a) {
+      if (a && a.cwd) return resolvePath(String(a.cwd))
+      // 兜底链：用户 env 覆盖 → **会话真实目录** → process.cwd()。末两级很关键：
+      // MCP server 由 DSH 以空 cwd 启动，process.cwd() 是 DSH 主进程目录而非用户项目，
+      // 直接用会让 CLI 把整个项目判成「工作区外」（agy/claude/opencode/codex 都踩过）。
+      const envCwd = process.env.MIMO_MCP_CWD || process.env.MIMO_BRIDGE_CWD
+      if (envCwd) return resolvePath(String(envCwd))
+      return resolveCwdWithSession(null, '', resolvePath)
+    }
 
 // ── spawn（旧 runMimo verbatim 语义；实时折叠走 bridge-kit 行流）────────────────
 function runMimo(args) {

package/mcp/providers/opencode.mjs

@@ -9,6 +9,7 @@
 // opencode 无 quota/额度门禁（凭据与额度由 opencode 自身与 provider 决定），
 // 因此本面只有三件套。
 import { spawn as nodeSpawn } from 'node:child_process'
+import { resolveCwdWithSession } from '../session-cwd.mjs'
 import { resolve as resolvePath } from 'node:path'
 
 import defineProvider, { resolveExePrefix } from '../../providers/opencode.mjs'
@@ -73,10 +74,15 @@ provider.engine = engine
 function exePrefix() {
   return resolveExePrefix(process.env, '')
 }
-function resolveCwd(a) {
-  if (a && a.cwd) return resolvePath(String(a.cwd))
-  return process.env.OPENCODE_MCP_CWD || process.cwd()
-}
+    function resolveCwd(a) {
+      if (a && a.cwd) return resolvePath(String(a.cwd))
+      // 兜底链：用户 env 覆盖 → **会话真实目录** → process.cwd()。末两级很关键：
+      // MCP server 由 DSH 以空 cwd 启动，process.cwd() 是 DSH 主进程目录而非用户项目，
+      // 直接用会让 CLI 把整个项目判成「工作区外」（agy/claude/opencode/codex 都踩过）。
+      const envCwd = process.env.OPENCODE_MCP_CWD
+      if (envCwd) return resolvePath(String(envCwd))
+      return resolveCwdWithSession(null, '', resolvePath)
+    }
 
 // ── spawn（实时折叠走 bridge-kit 行流）────────────────────────────────────────
 function runOpencode(args) {

package/mcp/session-cwd.mjs

@@ -0,0 +1,123 @@
+// mcp/session-cwd.mjs — MCP 形态下解析「会话工作区」。
+//
+// 为什么需要（真实事故，2026-10-23）：
+// 用户反馈「agent 委派任务时 agy/opencode/claude/codex 报错：无权编辑工作区外的内容」。
+// 根因不在 CLI 沙箱本身，而在**工作区边界被定错了**：
+//   MCP 各 provider 的 cwd 兜底是 `process.env.<ID>_MCP_CWD || process.cwd()`，
+//   而 DSH 的 mcp-client 启动 stdio server 时 `config.cwd` 默认是空字符串
+//   （@deepseek-ai/dsh-mcp-client 里 `cwd: z.string().default("")`），
+//   于是 MCP 进程的 cwd = **DSH 主进程的目录**（dsh-home / 安装目录），而不是用户的会话目录。
+//   结果：CLI 认为"工作区"是那个目录，用户项目里的一切都在"工作区外"——
+//   codex 的 `-s workspace-write` 直接拒绝写入，其余各家也按各自的 project 边界拒绝。
+//
+// 修法：DSH 给子进程提供了 `DSH_SESSION_ID`（实测存在），会话的 cwd 存在
+// projcache 的 `record.identity.cwd` 里。据此把兜底链补成：
+//   args.cwd（调用方显式传，最可靠）→ <ID>_MCP_CWD（用户配置）
+//   → 本模块（会话真实目录）→ process.cwd()（最后兜底）
+//
+// 约束：本模块零依赖（只用 node:fs / node:path），且必须容错——任何读取失败都返回 ''，
+// 由调用方继续往下兜底，绝不抛异常打断工具调用。
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+const CACHE_TTL_MS = 60 * 1000
+let cache = { at: 0, sid: '', cwd: '' }
+
+/** 从 projcache 里按会话 id 取 cwd。读不到返回 ''。 */
+function cwdFromProjcache(dshHome, sessionId) {
+  if (!dshHome || !sessionId) return ''
+  const base = join(dshHome, 'storages', 'session_projcache', 'sessions')
+  // 会话 id 在磁盘上可能是 `<id>.json` 或 `session-<uuid>.json` 两种形态
+  const plain = sessionId.replace(/^session-/, '')
+  const cands = [
+    join(base, sessionId + '.json'),
+    join(base, 'session-' + plain + '.json'),
+    join(base, plain + '.json')
+  ]
+  for (const f of cands) {
+    try {
+      if (!existsSync(f)) continue
+      const j = JSON.parse(readFileSync(f, 'utf8'))
+      const c = j && j.record && j.record.identity && j.record.identity.cwd
+      if (typeof c === 'string' && c) return c
+    } catch (e) { /* 单文件失败继续试下一个 */ }
+  }
+  return ''
+}
+
+/**
+ * 解析当前 DSH 会话的工作目录。
+ * @param {object} [env] 默认 process.env（便于测试注入）
+ * @param {number} [nowMs] 便于测试注入时间
+ * @returns {string} 会话 cwd；无法确定时返回 ''
+ */
+export function resolveSessionCwd(env, nowMs) {
+  const e = env || (typeof process !== 'undefined' ? process.env : {}) || {}
+  const sid = String(e.DSH_SESSION_ID || '')
+  if (!sid) return ''
+  const at = Number(nowMs) || Date.now()
+  if (cache.sid === sid && at - cache.at < CACHE_TTL_MS) return cache.cwd
+
+  const home = String(e.DSH_HOME || '')
+  let cwd = cwdFromProjcache(home, sid)
+  // projcache 没命中时退一步：会话存储目录名里编码了 cwd（--C-Users-...--），
+  // 但它只覆盖有事件落盘的会话，且解码易错 —— 仅在 projcache 缺失时尝试。
+  if (!cwd && home) cwd = cwdFromSessionDirs(home, sid)
+
+  cache = { at, sid, cwd }
+  return cwd
+}
+
+/** 会话事件目录名把 cwd 编码成 `--C-Users-lcl-Desktop-Foo--`。仅在 projcache 缺失时用。 */
+function cwdFromSessionDirs(dshHome, sessionId) {
+  const base = join(dshHome, 'sessions')
+  try {
+    if (!existsSync(base)) return ''
+    for (const dirName of readdirSync(base)) {
+      if (!dirName.startsWith('--') || !dirName.endsWith('--')) continue
+      const inner = join(base, dirName)
+      let entries = []
+      try { entries = readdirSync(inner) } catch (e) { continue }
+      if (!entries.includes(sessionId)) continue
+      // `--C-Users-lcl-Desktop-Foo-Bar--` → C:\Users\lcl\Desktop\Foo\Bar
+      // 编码规则：盘符与反斜杠被替换成 '-', 空格等特殊字符被编码成 ~XXXX~（此处不做还原）
+      const raw = dirName.slice(2, -2)
+      const decoded = decodeSessionDirName(raw)
+      if (decoded) return decoded
+    }
+  } catch (e) { }
+  return ''
+}
+
+/**
+ * 解码 DSH 会话目录名。已知编码：`C:` → `C`，`\` 与 `/` → `-`，特殊字符 → `~HEX~`。
+ * 反解有歧义（`-` 既是分隔符也可能属于目录名），故只在能明确判定盘符时返回，否则放弃。
+ */
+function decodeSessionDirName(raw) {
+  const m = /^([A-Za-z])-(.+)$/.exec(raw)
+  if (!m) return ''
+  const drive = m[1].toUpperCase() + ':\\'
+  const rest = m[2].replace(/~([0-9A-Fa-f]{4})~/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+  // 剩余的 '-' 视作路径分隔符（与 DSH 编码一致）
+  return drive + rest.split('-').join('\\')
+}
+
+/** 供测试重置缓存。 */
+export function resetSessionCwdCache() { cache = { at: 0, sid: '', cwd: '' } }
+
+/**
+ * 各 MCP provider 共用的 cwd 兜底链。
+ * 顺序：调用方显式 args.cwd → 用户 env 覆盖 → 会话真实目录 → process.cwd()。
+ * @param {object} a 工具入参
+ * @param {string} envKey 该 provider 的 cwd 覆盖环境变量名（如 CLAUDE_MCP_CWD）
+ * @param {(p: string) => string} [resolvePathFn] 路径规范化（各 provider 自带）
+ */
+export function resolveCwdWithSession(a, envKey, resolvePathFn) {
+  const rp = typeof resolvePathFn === 'function' ? resolvePathFn : (x) => x
+  if (a && a.cwd) return rp(String(a.cwd))
+  const env = (typeof process !== 'undefined' && process.env) || {}
+  if (envKey && env[envKey]) return rp(String(env[envKey]))
+  const sessionCwd = resolveSessionCwd(env)
+  if (sessionCwd) return rp(sessionCwd)
+  return (typeof process !== 'undefined' && process.cwd) ? process.cwd() : ''
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luchenglong/cli-bridge",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "description": "CLI Bridge for DeepSeek Harness (DSH): one package bridging six local coding-CLI agents — agy (Google Antigravity CLI), Tencent CodeBuddy Code, Xiaomi MiMo (MiMoCode), OpenCode, Claude Code, and OpenAI Codex CLI. Each provider keeps its own agent preset (cordis-agy / codebuddy-first / cordis-mimo / opencode-first / claude-first / codex-first), tools (<id>_run / <id>_continue / <id>_status, plus per-provider model listing), rate-limit/network fallback dialog, and zero-dependency MCP server, unified under a single home-level status light, one settings file, and one bundle patch. Merges agy-first-bridge, codebuddy-first-bridge and mimo-first-bridge.",
   "license": "MIT",
   "publishConfig": {

package/scripts/register-global-mcp.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// scripts/register-global-mcp.mjs — 把 CLI Bridge 的聚合 MCP 注册为 DSH **家级**（所有会话可见）。
+//
+// 为什么需要这一步：本包的 provider 工具只在两种情况下存在 ——
+//   ① 用了本包的 agent preset（claude-first 等）；② 注册了 MCP。
+// 普通会话（standard preset）两者都没有，于是「装了插件却看不到任何工具」，状态灯也永远不亮。
+// 这就是本脚本存在的理由。
+//
+// 设计取舍：
+//   • 直接指向 npm 已安装包内的 mcp/cli-bridge-mcp.mjs，**不复制副本** —— 升级包后重启即生效，
+//     不会出现「bin 里是旧副本、包是新版」的版本漂移。
+//   • command 用 DSH 自带 node.exe 的绝对路径，不依赖 PATH。
+//   • 写入前备份、写入后立即用 yaml 解析校验，校验失败自动回滚（家级补丁写错会让所有会话起不来）。
+//   • 幂等：已存在同 id 条目则跳过。
+//
+// 用法：
+//   node scripts/register-global-mcp.mjs            # 注册（或报告已注册）
+//   node scripts/register-global-mcp.mjs --dry-run  # 只报告将要做什么
+//   node scripts/register-global-mcp.mjs --remove   # 撤销注册
+//
+// 之后必须重启 DSH（host 组合变更热加载不可靠）。
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const ENTRY_ID = 'mcp-cli-bridge-global'
+const SERVER_NAME = 'cli'
+const TOOL_TIMEOUT_MS = 900000
+
+const args = new Set(process.argv.slice(2))
+const DRY = args.has('--dry-run')
+const REMOVE = args.has('--remove')
+
+function fail(msg) { console.error('✗ ' + msg); process.exit(1) }
+function info(msg) { console.log('  ' + msg) }
+
+/** 定位 dsh-home：优先 DSH_HOME，其次 Windows 默认位置。 */
+export function detectDshHome(env = process.env) {
+  const cands = []
+  if (env.DSH_HOME) cands.push(env.DSH_HOME)
+  if (env.APPDATA) cands.push(path.join(env.APPDATA, 'DSH Desktop', 'dsh-home'))
+  if (env.HOME) cands.push(path.join(env.HOME, '.dsh'))
+  for (const c of cands) { try { if (fs.existsSync(c)) return c } catch (e) { } }
+  return ''
+}
+
+const dshHome = detectDshHome()
+if (!dshHome) fail('找不到 dsh-home（试过 DSH_HOME / %APPDATA%\\DSH Desktop\\dsh-home / ~/.dsh）')
+info('dsh-home: ' + dshHome)
+
+const patchFile = path.join(dshHome, 'cordis.patch.yml')
+if (!fs.existsSync(patchFile)) fail('找不到家级补丁: ' + patchFile)
+
+// 已安装包内的 MCP 入口。**优先用 DSH 里已安装的那份**（稳定路径，随 npm 升级生效）；
+// 只有找不到安装包时才回落到本脚本所在仓库（开发态）。若直接写仓库路径，一旦仓库被移动
+// 或换台机器就会失效 —— 家级配置必须指向稳定位置。
+function findInstalledEntry() {
+  const profilesDir = path.join(dshHome, 'profiles')
+  const cands = []
+  try {
+    for (const p of fs.readdirSync(profilesDir)) {
+      cands.push(path.join(profilesDir, p, 'node_modules', '@luchenglong', 'cli-bridge', 'mcp', 'cli-bridge-mcp.mjs'))
+    }
+  } catch (e) { }
+  for (const c of cands) { try { if (fs.existsSync(c)) return c } catch (e) { } }
+  return ''
+}
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const repoEntry = path.join(pkgRoot, 'mcp', 'cli-bridge-mcp.mjs')
+const mcpEntry = findInstalledEntry() || repoEntry
+if (!fs.existsSync(mcpEntry)) fail('找不到 MCP 入口（安装包与本仓库都没有）: ' + mcpEntry)
+info('MCP 入口: ' + mcpEntry + (mcpEntry === repoEntry ? '  ⚠ 取的是仓库路径（未在 dsh-home 里找到已安装包）' : '  (已安装包)'))
+
+// DSH 自带 node（避免 PATH 依赖）；找不到就回落到 process.execPath
+const dshNode = path.join(path.dirname(dshHome), 'backend', 'node.exe')
+const nodeExe = fs.existsSync(dshNode) ? dshNode : process.execPath
+info('node: ' + nodeExe)
+
+// yaml 解析器：优先用 DSH 自带依赖，其次包内 peer
+async function loadYaml() {
+  const cands = [
+    path.join(path.dirname(dshHome), 'backend', 'dsh', 'node_modules', 'yaml', 'index.js'),
+    'yaml'
+  ]
+  for (const c of cands) {
+    try { const m = await import(c.startsWith('/') || /^[A-Za-z]:/.test(c) ? 'file:///' + c.replace(/\\/g, '/') : c); return m.default || m } catch (e) { }
+  }
+  try { return await import('yaml') } catch (e) { }
+  return null
+}
+const YAML = await loadYaml()
+
+const original = fs.readFileSync(patchFile, 'utf8')
+const already = original.includes(ENTRY_ID)
+
+if (REMOVE) {
+  if (!already) { info('未注册，无需撤销'); process.exit(0) }
+  // 删除从注释块起到条目结束（以 "- id: <ENTRY_ID>" 所在 insert 块为单位）
+  const lines = original.split('\n')
+  const out = []
+  let skipping = false
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i]
+    if (!skipping && ln.includes('- id: ' + ENTRY_ID)) {
+      // 往回删掉本块已有的 "- insert:" 行
+      while (out.length && /^\s*-\s*insert:\s*$/.test(out[out.length - 1])) out.pop()
+      skipping = true
+      continue
+    }
+    if (skipping) {
+      if (/^\s{0,6}\S/.test(ln) && !/^\s*$/.test(ln) && !/^\s+(config|failOnStartupError|name|args|command|serverName|transport|toolCallTimeoutMs)/.test(ln) && !/^\s{8,}/.test(ln) && !/^\s*#/.test(ln)) skipping = false
+      else { continue }
+    }
+    out.push(ln)
+  }
+  const nextText = out.join('\n').replace(/\n{3,}/g, '\n\n')
+  if (DRY) { info('[dry-run] 将删除条目 ' + ENTRY_ID); process.exit(0) }
+  fs.writeFileSync(patchFile + '.bak-remove-' + Date.now(), original, 'utf8')
+  fs.writeFileSync(patchFile, nextText, 'utf8')
+  info('✓ 已撤销注册（已备份）')
+  info('  ⚠ 需重启 DSH 生效')
+  process.exit(0)
+}
+
+if (already) {
+  info('✓ 已注册 ' + ENTRY_ID + '（幂等，未重复写入）')
+  info('  ⚠ 若刚改过包版本，重启 DSH 即可加载新版')
+  process.exit(0)
+}
+
+const block = [
+  '',
+  '# ══════════════════════════════════════════════════════════════════════════',
+  '# CLI Bridge 全局 MCP（家级/host 层）—— 由 scripts/register-global-mcp.mjs 写入',
+  '# 把六家 CLI 以【一个聚合 MCP】接进所有会话：',
+  '#   mcp__' + SERVER_NAME + '__{agy,codebuddy,mimo,opencode,claude,codex}_{run,continue,status}',
+  '# 直接指向安装包内的入口，不复制副本 —— 升级包后重启 DSH 即生效，无版本漂移。',
+  '# ⚠ DSH 自带的 subagent_claude_code / subagent_codex 不走本 MCP，',
+  '#   它们的调用不会点亮 CLI Bridge 的状态灯（两套实现彼此独立）。',
+  '# ⚠ 改此条目后必须重启 DSH（host 组合变更热加载不可靠）。',
+  '# ══════════════════════════════════════════════════════════════════════════',
+  '- insert:',
+  '    - id: ' + ENTRY_ID,
+  "      name: '@deepseek-ai/dsh-mcp-client'",
+  '      config:',
+  '        serverName: ' + SERVER_NAME,
+  '        transport: stdio',
+  "        command: '" + nodeExe + "'",
+  "        args: ['" + mcpEntry + "']",
+  '        toolCallTimeoutMs: ' + TOOL_TIMEOUT_MS,
+  '      failOnStartupError: false',
+  ''
+].join('\n')
+
+if (DRY) { info('[dry-run] 将追加注册块到 ' + patchFile); process.exit(0) }
+
+const bak = patchFile + '.bak-before-cli-bridge-mcp-' + new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)
+fs.writeFileSync(bak, original, 'utf8')
+info('已备份: ' + path.basename(bak))
+
+const nextText = original.replace(/\s*$/, '\n') + block
+fs.writeFileSync(patchFile, nextText, 'utf8')
+
+// 校验：解析失败或找不到条目 → 回滚（家级补丁坏了会导致所有会话启动失败）
+if (YAML) {
+  try {
+    const doc = YAML.parse(fs.readFileSync(patchFile, 'utf8'))
+    let found = null
+    const walk = (o) => {
+      if (!o || found) return
+      if (Array.isArray(o)) return o.forEach(walk)
+      if (typeof o === 'object') { if (o.id === ENTRY_ID) { found = o; return } Object.values(o).forEach(walk) }
+    }
+    walk(doc)
+    if (!found) throw new Error('解析后找不到 ' + ENTRY_ID)
+    info('✓ YAML 校验通过，条目已就位（serverName=' + found.config.serverName + '）')
+  } catch (e) {
+    fs.writeFileSync(patchFile, original, 'utf8')
+    fail('YAML 校验失败，已回滚: ' + e.message)
+  }
+} else {
+  info('⚠ 未找到 yaml 解析器，跳过结构校验（已保留备份）')
+}
+
+info('')
+info('✓ 注册完成。现在重启 DSH 使家级组合生效。')
+info('  重启后任意会话应能看到 20+ 个 mcp__' + SERVER_NAME + '__* 工具')
+info('  （被调度禁用的 provider 不会出现 —— 见设置面板「CLI 调度」）')