@luchenglong/cli-bridge 0.0.0-stage → 0.2.3

package/core/scheduling.mjs

@@ -0,0 +1,149 @@
+// core/scheduling.mjs — CLI 调度（启用集合 + 调用优先级）单源纯逻辑。
+//
+// 语义（用户可见的两件事）：
+//   • enabled  = 勾选启用哪些 CLI（数量随之而定）；未启用的一面不注册工具、不进提示词。
+//   • priority = 智能体调用 CLI 的建议顺序，数组顺序即优先级（首位最高）。
+//
+// 落盘位置：统一设置文件 {DSH_HOME}/cli-bridge-settings.json 的顶层 `_scheduling` 区。
+// 下划线前缀 = 非 provider 分区（registry 的 PROVIDER_IDS 永远不含它，逐分区语义不受影响），
+// 因此新代码写出的文件被旧包读取时整区被忽略 = 纯增量，向后兼容。
+//
+// 缺省语义（文件缺失/无该区）：全部 provider 启用、按注册表顺序 —— 与调度特性上线前
+// 的行为逐字一致（读不到配置永远不等于关掉所有桥）。
+//
+// 沙箱纪律：与 bridge-kit 同源约束 —— 不得 import；Node 内建一律经
+// globalThis.process.getBuiltinModule + typeof 守卫（动态宿主沙箱可能没有 fs，
+// 那种环境读不到文件 → 走缺省全开，绝不炸 apply）。
+
+/** 设置文件里调度区的键名（下划线前缀避开 provider id 命名空间）。 */
+export const SCHEDULING_SECTION = '_scheduling'
+
+/** 人类可读的默认注册顺序（调用建议顺序）；enabled 缺省 = 全部启用。 */
+export function defaultPriority(ids) {
+  return (Array.isArray(ids) ? ids : []).slice()
+}
+
+/**
+ * 清洗任意来源的调度对象。
+ * @param {unknown} raw  文件/POST 里的原始值（可能是任何东西，全部容错）
+ * @param {string[]} ids 全量 provider id（顺序 = 缺省优先级）
+ * @param {(id: string) => string} [labelOf] 展示名（仅用于诊断文本，不参与判定）
+ */
+export function normalizeScheduling(raw, ids, labelOf) {
+  const all = Array.isArray(ids) ? ids.slice() : []
+  const label = typeof labelOf === 'function' ? labelOf : ((id) => String(id))
+  const enabled = all.slice()
+  let priority = all.slice()
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    if (Array.isArray(raw.enabled)) {
+      const seen = Object.create(null)
+      const picked = []
+      for (const x of raw.enabled) {
+        const id = String(x == null ? '' : x)
+        if (!id || all.indexOf(id) < 0 || seen[id]) continue
+        seen[id] = true; picked.push(id)
+      }
+      // 空数组 = 用户真的想把全部关掉（而不是「没配」），保留该语义；
+      // 非空但过滤后为空 = 写的全是未知 id（坏值）→ 回落全开（fail-open，
+      // 绝不让一次手滑/陈旧配置把所有桥关掉）。
+      if (raw.enabled.length === 0 || picked.length > 0) {
+        enabled.length = 0
+        Array.prototype.push.apply(enabled, picked)
+      }
+    }
+    if (Array.isArray(raw.priority)) {
+      const seen2 = Object.create(null)
+      const ordered = []
+      for (const x of raw.priority) {
+        const id = String(x == null ? '' : x)
+        if (!id || all.indexOf(id) < 0 || seen2[id]) continue
+        seen2[id] = true; ordered.push(id)
+      }
+      for (const id of all) if (!seen2[id]) ordered.push(id) // 漏写的排在末尾
+      if (ordered.length) priority = ordered
+    }
+  }
+  const order = priority.filter((id) => enabled.indexOf(id) >= 0)
+  for (const id of enabled) if (order.indexOf(id) < 0) order.push(id)
+  return { enabled, priority, order }
+}
+
+/** 展示文本：「CB → MIMO」或「全部启用 · CB → AGY → MIMO」。 */
+export function describeScheduling(s, labelOf) {
+  const st = s || {}
+  const label = typeof labelOf === 'function' ? labelOf : ((id) => String(id))
+  const order = Array.isArray(st.order) ? st.order : []
+  const names = order.map(label).join(' → ')
+  return names ? names : '（全部禁用）'
+}
+
+// ── 读盘（四形态共用；无 fs 时安全返回 null）────────────────────────────────────
+// 名字带 sched 前缀：本文件会与 bridge-kit / provider 描述符【文本内联进同一个动态
+// 沙箱脚本作用域】（providers/codebuddy.mjs 已有 builtinModule），撞名即隐患。
+function schedBuiltinModule(name) {
+  try {
+    const proc = globalThis.process
+    return (proc && typeof proc.getBuiltinModule === 'function') ? proc.getBuiltinModule(name) : null
+  } catch (e) { return null }
+}
+
+export function schedulingSettingsPath(env) {
+  const e = env || (globalThis.process && globalThis.process.env) || {}
+  try {
+    if (e.CLI_BRIDGE_SETTINGS_FILE) return String(e.CLI_BRIDGE_SETTINGS_FILE)
+    const nodePath = schedBuiltinModule('node:path')
+    if (nodePath && e.DSH_HOME) return nodePath.join(String(e.DSH_HOME), 'cli-bridge-settings.json')
+  } catch (e2) { }
+  return null
+}
+
+/**
+ * 生效调度：文件 _scheduling > 缺省全开。
+ * env/argv CLI_BRIDGE_PROVIDER（单面钉住，旧薄封装兼容语义）存在时视为最高优先 ——
+ * 它代表「这个 MCP 进程只为这一家而启动」（部署者的显式意志，比面板勾选更具体、
+ * 更靠近进程生命周期），调度不再削减它。
+ * 宿主形态（preset / dynamic 桥接插件）应传 ignorePin：钉住只是 MCP 进程的启动参数，
+ * 不该让全局 env 反过来把用户会话里的其他桥关掉。
+ * @param {string[]} ids 全量 provider id
+ * @param {{ env?: Record<string,string>, readFileSync?: Function, path?: string|null, ignorePin?: boolean }} [io]
+ */
+export function resolveScheduling(ids, io) {
+  const o = io || {}
+  const env = o.env || (globalThis.process && globalThis.process.env) || {}
+  let raw = null
+  try {
+    const p = ('path' in o) ? o.path : schedulingSettingsPath(env)
+    const nodeFs = o.readFileSync ? { readFileSync: o.readFileSync } : schedBuiltinModule('node:fs')
+    if (p && nodeFs && typeof nodeFs.readFileSync === 'function') {
+      raw = JSON.parse(nodeFs.readFileSync(p, 'utf8'))
+    }
+  } catch (e) { raw = null }
+  const file = normalizeScheduling(raw && typeof raw === 'object' ? raw[SCHEDULING_SECTION] : null, ids)
+  const pinned = o.ignorePin ? '' : String(env.CLI_BRIDGE_PROVIDER || '').trim()
+  if (pinned && ids.indexOf(pinned) >= 0) {
+    return Object.assign(file, {
+      enabled: [pinned],
+      order: [pinned],
+      pinned: pinned,
+      source: raw ? 'env:CLI_BRIDGE_PROVIDER+file' : 'env:CLI_BRIDGE_PROVIDER'
+    })
+  }
+  return Object.assign(file, { pinned: '', source: raw ? 'file' : 'default' })
+}
+
+/**
+ * 桥接面门禁（preset / dynamic 的 apply() 首行用）：本 provider 是否被调度启用。
+ * fail-open —— 任何异常（无 fs、文件损坏、沙箱限制）都返回 true：读不到配置永远
+ * 不等于关掉桥（否则一次文件损坏就把三条 CLI 全灭了）。ignorePin 固定 true：
+ * 钉住语义属于 MCP 独立进程，宿主形态的全局 env 不该反向影响用户会话。
+ */
+export function isBridgeEnabled(selfId, ids, io) {
+  try {
+    const list = Array.isArray(ids) ? ids : []
+    // 全量清单本身不可得（空/不含自己）= 无门禁语义，fail-open。
+    if (!list.length || list.indexOf(String(selfId)) < 0) return true
+    const o = Object.assign({ ignorePin: true }, io || {})
+    return resolveScheduling(list, o).enabled.indexOf(String(selfId)) >= 0
+  } catch (e) { return true }
+}
+

package/docs/ARCHITECTURE.md

@@ -0,0 +1,117 @@
+# 架构（CLI Bridge）
+
+三个旧桥接包（agy / codebuddy / mimo）深度重构为一个包。目标不是「拼盘」，而是把三处
+几乎相同的骨架收敛成一份参数化实现，每家只提供一个描述符（descriptor）。
+
+## 1. 三形态共享一个内核
+
+同一个 provider 描述符驱动三种运行形态：
+
+| 形态 | 运行环境 | 宿主能力 | 状态出口 |
+| --- | --- | --- | --- |
+| preset（`preset/<dir>/cli-bridge.mjs`） | 宿主进程内真 ESM | 真 `process`/node:*/ctx.* | `ctx.emit('<id>/status'\|'<id>/mode')` |
+| dynamic（`dynamic/<id>.host.js`） | Cordis 沙箱 `new Function` | 只有注入的 `harness.*`/ctx，**禁止 import/process 裸用** | `cliBridgeCollector.mergeSnapshot(id, snap)` |
+| MCP（`mcp/cli-bridge-mcp.mjs`） | 独立 stdio 进程 | node:* 全量 | 原子快照文件 `{DSH_HOME}/cli-bridge-mcp-<id>.json` |
+
+约束的根因：沙箱形态（dynamic）里，`providers/<id>.mjs` 与 `core/bridge-kit.mjs` 被
+`scripts/build.mjs` **文本内联**（`stripModuleSyntax`）。因此这两个文件：零 import、
+零 `import.meta` 字面量、`process/fs` 一律 deps 注入或 typeof 守卫。
+preset/MCP 形态是真实模块，可以用 node:* 与相对 import（禁止 `@deepseek-ai/*`，
+历史论证见本地 preset 解析根问题）。
+
+## 2. `core/bridge-kit.mjs` —— 通用骨架（与 provider 无关）
+
+- **createStatusEngine({provider, publish})**：按项目（cwd）分桶的活动模型 ——
+  `begin/foldEvent/end`，每项目 `current`（此刻步骤）+ `trail`（轨迹环，MAX_TRAIL=12）+
+  累计 `runs/totalTokens`；会话表（MAX_SESSIONS=256）记录 `sessionId → {cwd, backend}`
+  供续接路由（`resolveTarget`：显式 cwd > 会话归属 > 回退 cwd）。全局状态派生：
+  running>0 → running；否则 fallback（回退激活）/ lastStatus 成功失败 / idle。
+- **createRunner(o) → coreExecute(args, exec)**：完整编排管线——
+  `preflight`（可 abort）→ `resolveExe`（抛错→unavailableStatus）→ `buildArgv` →
+  `delegates(backend)` 判定是否交给 provider.execute（非 spawn 路径，如 mimo 桌面）→
+  `jobs.start`（background）或前台循环：`HUNG_TIMEOUT` 守卫（timeout+60s 强杀）、
+  `isTransientCliError` 静默重试一次、`isLimited`（provider 可覆盖）触发 `askFallback`
+  三选一（回退/重试/取消），一切状态变化实时 publish。
+- **纯函数**：`projectName/clampInt/shortLabel/summarizeArgs/endpointHost/LIMIT_RE`、
+  NDJSON 半行安全 `createLineStream`、展示层 `renderResult/renderStatus`、
+  MCP 载荷 `buildMcpBridgePayload/normalizeMcpBridge`（stale=90s）。
+
+provider 侧全部差异 = 一个 descriptor（见 `PROVIDER-CONTRACT.md` §1）。
+
+## 3. 家级指示灯（`home-plugin/cli-bridge-indicator/`）
+
+随 DSH 启动的 bundle 插件（`dsh.bundle.patch` 一行插入；`dsh.client.platform:"web"`）。
+内部分层，全部可单测（`createIndicatorState` 是纯状态机，注入 `listPresetSessions/
+readMcpFile/isSuccessStatus/now` 即可离线测）：
+
+- **index.mjs**：每 provider 一个桶 `{projects, sessionLeases, presetActiveUntil,
+  lastModeAt}`。事件源三路合并：① preset 桥接 `ctx.emit('<id>/status')`（同进程）；
+  ② dynamic 宿主 `cliBridgeCollector.mergeSnapshot`（家级收集器，旧包单家收集器名
+  `agyCollector/…` 保留别名）；③ MCP 快照文件（每次读取实时合并，过期只清零 running，
+  绝不清掉活动细节）。合并规则：state 是派生字段——外部快照的 state 只在 running 时被
+  信任，其余本地重算（`isSuccessStatus` 来自 descriptor，mimo 的 ACCEPTED 等语义各家自定）。
+- **租约（lease）**：preset 桥接每 30s 心跳 `ctx.emit('<id>/mode',{active,sessionId})`，
+  TTL 75s（两跳 + 5s 宽限）。`sessionId` 有值 → 会话级租约；缺省 → 全局租约（client
+  无法判定时的保守亮）。关会话/停桥接后租约过期，灯自动灭（旧 mimo 1.2.9「灯常亮」
+  事故类的对偶防线：宁可用租约到期灭，不可无来源亮）。
+- **preset 双通道判定**：宿主侧 `agents.list() × agentPresets.composedPreset()` 枚举
+  「哪些 DSH 会话正跑在桥接预设下」是权威；client 侧 `useSessions` 投影只是兜底。
+- **路由**：`GET /cli-bridge/status`（聚合三桶）、`GET/POST /cli-bridge/settings`、
+  `GET /agy-indicator/quota`（5 分钟缓存）。旧包路径 `/agy-indicator/status` 等全部
+  保留为单桶别名（旧前端/脚本兼容）。
+- **preset-declarations.mjs（Form-A 自注册）**：indicator `ctx.inject(['agentPresets'])`
+  → 对三家各 `agentPresets.register(definition)`。定义体直接 import 各
+  `preset/<dir>/plugin-list.mjs`（与 legacy YAML 生成同一事实来源）。`{__jsExpr}`
+  字面量**原样透传**给注册器（loader 原生识别；任何 JSON 序列化往返会丢函数——绝不
+  编译成函数，这是旧 gen-preset-decl 时代踩过的位置）。旧 DSH 上对不存在的服务
+  `inject` 只会 pending，无害；因此该形态跨版本一步到位。
+- **client.js（红线 4）**：`window.__ModuleLoader__.load({ id: "@luchenglong/cli-bridge" })`
+  —— id 必须逐字等于包名，不一致 = 整个 client combo 抛错 = 白屏进安全模式（历史两次
+  事故）。`scripts/verify.mjs` + `tests/keystone/client-id.test.mjs` 双闸门。UI：标题栏
+  一盏聚合 pill + 悬停/点击分区面板 + 设置页 meta 驱动卡片（provider 声明 fields，
+  前端不认识任何具体字段名）。
+
+## 4. 统一设置（`lib/settings.mjs`）
+
+单一文件 `{DSH_HOME}/cli-bridge-settings.json`，按 provider 分区。provider 只声明纯逻辑
+（keys/secretKeys/defaults/normalize/meta/diagnose，§3），落盘/掩码/清洗全在 keystone：
+GET 永不回传明文 secret（掩码 `••••尾4`）；POST 空=保持、`<key>Clear:true`=清除；
+写用 tmp→rename 原子替换。**旧包设置文件一次性字段级迁移**（codebuddy 扁平文件 /
+mimo `{APPDATA}/mimo-first-bridge/settings.json` 的 backend→preferredBackend 映射）：
+新分区从未写过该键才回退旧值，写过即新值说了算；永不写旧文件。
+
+## 5. MCP 面（`mcp/cli-bridge-mcp.mjs` + `mcp/providers/<id>.mjs`）
+
+一个 stdio JSON-RPC server（LSP 式换行分帧），initialize/tools/call 由 keystone 框架
+实现；每家一个纯面模块（`tools(env)/call(name,args,io)/check(env)`，§4），`io` 注入
+fs/path/homeDir/env/log，面模块不猜路径。`--provider=<id>` 过滤单家；
+`mcp/<id>-mcp-server.mjs` 是薄封装（旧配置只换路径）。MCP 进程没有 ctx.emit，publish
+改写快照文件；家级灯实时合并（见 §3-③）。
+
+## 6. 构建与闸门
+
+```
+plugin-list.mjs（每家的唯一插件清单源）
+  ├─ scripts/build.mjs → preset/<dir>/agent.cordis.yml + preset.yml（legacy 目录形态）
+  └─ preset-declarations.mjs 直接 import（新声明制形态，同一份源）
+dynamic/<id>.host.template.mjs + core/bridge-kit.mjs + providers/<id>.mjs
+  └─ scripts/build.mjs（stripModuleSyntax + 双占位文本内联）→ dynamic/<id>.host.js
+```
+
+生成物提交入库（fresh clone 可用），`--check` 模式比对漂移 → CI/prepack 红。
+三道闸门：`build --check`（漂移）、`verify.mjs`（红线/版本锁/描述符完整度）、
+`node --test` + `mcp --check`（行为）。CI 矩阵 node 18/20/22。
+
+## 7. 为什么这些选择（旧事故对照）
+
+- **裸 specifier 桥接行**（`@luchenglong/cli-bridge/preset-<id>`）：preset mount 的
+  baseUrl 不指向可预期的包内目录，`./preset/...` 相对行 import 永久挂起 → auditRows
+  never started（agy 1.7.1 主根因之一）。exports 子路径 + Node 解析 = 机器无关。
+- **声明制自注册**：0.1.6+ 起 `$DSH_HOME/.agent-presets/` 目录无人再读（官方 skill 明言），
+  preset 必须以 `agentPresets.register` / bundle 声明行注册 —— Form-A 自注册跨版本可用，
+  legacy 目录形态仅作旧版兜底。
+- **无 dsh peer 依赖**：兼容闸门只校验 `@deepseek-ai/dsh*` peers，桥接包不声明 =
+  天然通过；声明了反而武装闸门（版本漂移即 500）。
+- **workflow 行单源**：上游把 dsh-workflow-worker-thread 改名 dsh-workflow-ptc 曾让
+  「任一 enabled 行 import 失败 → 整个 preset 拒挂」（agy 1.7.1）。现在清单由
+  plugin-list.mjs 一份源生成，行名跟 standard-base 常量走，漂移只会出现在一处修一处。

package/docs/FALLBACK-AND-INDICATOR.md

@@ -0,0 +1,93 @@
+# 回退机制与状态灯（CLI Bridge）
+
+三家桥接共用的两项能力在 `core/bridge-kit.mjs` 里收敛成了**一份参数化实现**：
+限流/网络失败时的回退弹窗，与实时聚合状态灯。provider 只提供差异化判据
+（`isLimited` / `failureHint` / `isSuccessStatus`），骨架不再各抄一份。
+
+---
+
+## 一、回退机制（弹窗确认）
+
+### 触发条件
+
+`<id>_run` / `<id>_continue` 前台执行后，若结果 `ok === false` 且被判定为「疑似流量
+受限 / 网络不通」，触发回退弹窗。判定优先用 provider 的 `isLimited(res)` 覆盖
+（例如 mimo 需要认「free API service has ended / 登录 / 第三方」这类旧文案），
+否则用 kit 的通用 `LIMIT_RE`（stderr + response + status 拼接命中任一）：
+
+```
+rate limit / ratelimit / 429 / too many / quota / exceed /
+network / offline / ENETUNREACH / ECONNREFUSED / ECONNRESET /
+ETIMEDOUT / EAI_AGAIN / ENOTFOUND / timeout / timed out /
+unavailable / 503 / 502 / 500 / connection / proxy / socket /
+tls / ssl / dns / 网络 / 超时 / 限流 / 流量 / 受限 / 配额 / 连接 / 断开
+```
+
+注意 kit 的两处刻意豁免：`AUTH_REQUIRED` 不弹（登录问题不是限流，弹窗只会误导）；
+endpoint-mismatch 类 401 不弹（配置错误，重试无意义）。瞬时错误
+（`isTransientCliError`）先静默自动重试一次，仍失败才走弹窗。
+
+### 弹窗内容
+
+经 DSH `userQuestions.ask()` 单选（文案 provider.label 化，三家同构）：
+
+> **AGY 受限** —— agy 调用失败（疑似流量受限/网络不通，状态=`<status>`）。
+> 是否改用 DSH 本地 API 配置继续？
+
+| 选项 | 行为 |
+| --- | --- |
+| **使用 DSH 本地 API 配置（回退）** | 返回 `{ ok:false, fallback:true, status:'FALLBACK_TO_DSH', reason:<原status> }`；模型据此改用原生工具/本地模型完成任务，不再调用该 CLI。 |
+| **重试 <id> 一次** | 立即再执行一次（累计最多 2 次）。 |
+| **不回退（返回错误）** | 原样返回错误结果，由模型决定后续。 |
+
+### 防阻塞 / 防循环
+
+- **无真人应答者不弹窗**：`ask()` 抛 `CALLER_NOT_LIVE` / `DELEGATED_CALLER` 时按
+  `'error'` 处理（子代理永不被弹窗卡死）；缺 `userQuestions` 服务同理。
+- **最多 2 次尝试**：`attempt >= 2` 即停。
+- **后台任务不弹窗**：`background:true` 完成时真人上下文未必还在，后台失败只在结果里
+  提示「前台重跑才会被询问」。
+- **HUNG_TIMEOUT 守卫**：`timeoutSec + 60s` 后强杀并按受限类处理（长构建要调大
+  `timeoutSec`）。
+- **不让 CLI 回调宿主**：policy 段明文禁止，杜绝环路。
+
+## 二、聚合状态灯（一盏 pill，三家分区）
+
+`home-plugin/cli-bridge-indicator` 随 DSH 启动（bundle patch 一行），每 provider
+一个桶，合并三路数据源：
+
+1. **preset 桥接事件** —— `ctx.emit('<id>/status', { snapshot })`（同进程）+
+   `<id>/mode` 心跳租约；
+2. **dynamic 沙箱** —— `cliBridgeCollector.mergeSnapshot(id, snap)`（旧单家收集器
+   服务名保留别名）；
+3. **MCP 子进程** —— `{DSH_HOME}/cli-bridge-mcp-<id>.json` 原子快照，读取时实时合并，
+   超过 90s 视为停更（只清零 running，不清活动细节）。旧包快照文件
+   （`codebuddy-indicator-mcp.json`、`plugins/mimo-indicator/mcp-live.json`）兼容读取。
+
+### 租约（preset 优先态）
+
+桥接 preset 被某会话使用时发 `<id>/mode` 心跳（30s 一跳，TTL 75s = 两跳+宽限）：
+
+- payload 带 `sessionId` → **会话级租约**：只有该会话显示「优先」高亮；
+- 缺省 → 全局租约（client 侧无法判定时的保守亮）；
+- 会话关闭/桥接停用 → 租约自然过期，高亮自动灭。宿主侧 `listPresetSessions`
+  （agents × composedPreset）是权威枚举，client `useSessions` 投影只是兜底 ——
+  「宁可用租约到期灭，不可无来源亮」（mimo 1.2.9 灯常亮事故的对偶防线）。
+
+### 状态语义
+
+| 色 | state | 含义 |
+| --- | --- | --- |
+| 绿 | ok / idle-ready | 就绪 / 上次成功 |
+| 蓝 | running | 正在派发（悬停看当前步骤） |
+| 红 | failed | 上次失败（灰非红：CLI 不可用→灰） |
+| 灰 | unavailable | CLI 未安装 / 找不到 exe |
+| 橙 | fallback | 用户已选择回退 DSH 本地 |
+
+`state` 是派生字段：外部快照的 state 只在 running 时被信任，其余按 provider 的
+`isSuccessStatus` 本地重算（引擎 globalStatus 只认 'SUCCESS'，mimo 的 ACCEPTED 等
+变体在描述符层归一 —— indicator 测试锁定此行为）。
+
+点击 pill 展开按 provider、按项目的面板：当前步骤 + trail（12 条环）、
+累计 runs / totalTokens、最近完成结果；`GET /cli-bridge/status` 返回同数据的 JSON
+（旧单家路由 `/agy-indicator/status` 等保留为别名）。

package/docs/HANDOVER.md

@@ -0,0 +1,226 @@
+# HANDOVER — @luchenglong/cli-bridge 交接文档
+
+> 面向接手这个仓库/这台机器的下一个人（或下一个 Agent）。
+> 目标：**不读完所有历史也能安全改动、发布、排障**。历史事故与红线集中在 §5 与 §10。
+> 最近一次更新：2026-10-15（0.2.2 首发 npm + 旧包 deprecated + 旧仓归档之后）。
+
+---
+
+## 1. 这是什么
+
+`@luchenglong/cli-bridge` 把**本机三个编码 CLI**（agy / CodeBuddy / MiMo）以同一套 provider
+描述符接入 DSH，并有四种落地形态（preset / 动态宿主 / 家级宿主插件+指示灯 / MCP stdio server）。
+它由三个旧包（`agy-first-bridge` / `codebuddy-first-bridge` / `mimo-first-bridge`）合并而来，
+旧包的工具名、预设 id、策略文案**逐字保留**（兼容承诺，见 §5）。
+
+## 2. 当前状态快照
+
+| 项 | 值 |
+| --- | --- |
+| 版本 | **0.2.2**（三处版本锁：`package.json` / `mcp/cli-bridge-mcp.mjs` 的 `SERVER_VERSION` / `CHANGELOG.md` 顶部；`verify.mjs` 机器比对） |
+| npm | `@luchenglong/cli-bridge@0.2.2`（`latest`；2026-10-14 首次发布，shasum `362d506e0b85dd7014bb8b3fc1100bf3a6d0d1d5`，58 files / 320.1 kB） |
+| GitHub | `new-256/cli-bridge`，`main` @ `520194c`；tag `v0.1.0` / `v0.2.1` / `v0.2.2` |
+| 旧包 | 三个都已在 npm 标 **deprecated**（提示迁移到统一包）：`agy-first-bridge@1.7.1`、`codebuddy-first-bridge@1.6.2`、`mimo-first-bridge@1.2.9` |
+| 旧仓 | `new-256/agy-first-bridge`、`new-256/mimo-first-bridge`：README 顶部已加迁移横幅且 **archived（只读）**；`codebuddy-first-bridge` 在 GitHub 上不存在 |
+| 测试 | **271 pass / 0 fail**（28 个 `*.test.mjs`），四闸门 `npm run check` 全绿 |
+| 本机运行时 | DSH Desktop，宿主 **2026-10-14 22:35 重启后加载 0.2.2**；`dsh-home/profiles/web` 以 `file:` 依赖 + pnpm 快照部署 |
+
+**交接时点唯一未完成项**：家级补丁里四条 MCP 行刚被恢复，**需重启 DSH 才生效**（§7.3、§11）。
+
+## 3. 五分钟上手
+
+```powershell
+cd "C:\Users\lcl\Desktop\DSH插件开发\CLI Bridge"
+
+npm run check                             # 四闸门：build --check / verify / node --test / mcp --check
+node mcp/cli-bridge-mcp.mjs --check       # MCP 自检（含 scheduling 快照）
+node scripts/build.mjs                    # 改了模板/providers 后必须重跑，生成物要进同一个 commit
+
+# 活体探针（DSH 运行中；$env:DSH_WEB_URL 是当前 GUI 地址，端口每次启动可能变）
+Invoke-WebRequest "$env:DSH_WEB_URL/cli-bridge/status"   -UseBasicParsing | Select-Object -Expand Content
+Invoke-WebRequest "$env:DSH_WEB_URL/cli-bridge/settings" -UseBasicParsing | Select-Object -Expand Content
+```
+
+设置面板：DSH「设置 → CLI Bridge 桥接」→ 横向标签 `总设置 | AGY | CB | MIMO`。
+「总设置」= 调度（勾选启用 + `↑↓` 优先级），其余 = 各 CLI 偏好与诊断。
+
+## 4. 代码地图（改哪里）
+
+| 路径 | 职责 | 谁维护 |
+| --- | --- | --- |
+| `providers/registry.mjs` | **唯一 id 轴** `PROVIDER_IDS`；新 provider 第一站 | keystone（Lead 单作者） |
+| `providers/<id>.mjs` | 描述符：工具/policy/settings meta/mcp/diagnose/回退 | 每 provider 作者 |
+| `core/bridge-kit.mjs` | 共享内核：状态引擎、runner、限流、回退弹窗、MCP payload（**零 import**） | keystone |
+| `core/scheduling.mjs` | 调度单源（无 import → 可整段内联进沙箱） | keystone |
+| `home-plugin/cli-bridge-indicator/lib/index.mjs` | 宿主半：状态机 + HTTP 路由 + 收集器 + 门禁 | keystone |
+| `…/lib/settings.mjs` | 设置读写/掩码/旧文件迁移/`_scheduling` 区 | keystone |
+| `…/lib/preset-declarations.mjs` | 声明制注册三个 preset（恒注册，顺序按优先级） | keystone |
+| `…/lib/client.js` | 浏览器半：pill / 弹窗 / 设置标签页（**红线：load id ≡ 包名**） | keystone |
+| `preset/<dir>/` | preset 形态（`plugin-list.mjs` 是唯一权威源 + 生成物 `*.yml`） | 生成物入库 |
+| `dynamic/<id>.host.{js,template.mjs}` | 动态沙箱宿主（模板 → 生成物） | 生成物入库 |
+| `mcp/cli-bridge-mcp.mjs` + `mcp/providers/<id>.mjs` | 统一 MCP server（一个 server 暴露三家） | keystone |
+| `mcp/{agy,codebuddy,mimo}-mcp-server.mjs` | 旧包兼容入口（等价 `--provider=<id>`） | keystone |
+| `scripts/build.mjs` / `verify.mjs` / `deploy.mjs` | 生成 / 发布红线 / 本地暂存部署 | keystone |
+| `deploy/legacy-mcp/` | **家级 `bin\` 服务器材料的权威副本**（`bin\` 不入 git） | keystone |
+| `tests/keystone/` | 红线行为测试（client 面、状态机、路由、门禁、legacy MCP） | keystone |
+| `tests/{agy,codebuddy,mimo}/`、`tests/core/` | 各 provider 与内核回归 | provider 作者 |
+
+## 5. 不可动的契约（红线）
+
+1. **client 注册 id ≡ 包名**：`lib/client.js` 的 `window.__ModuleLoader__.load({ id: "@luchenglong/cli-bridge" })`
+   逐字不变。不等 → client combo 加载失败 → **整屏插件页崩溃**（agy v1.6.1 / codebuddy v1.1.8 事故）。
+   `verify.mjs` + `tests/keystone/client-id.test.mjs` + `client-ui-surface.test.mjs` 三重机器锁。
+2. **对外语义 verbatim**：工具名 `<id>_run/_continue/_status`、入参 schema、preset id
+   （`cordis-agy` / `codebuddy-first` / `cordis-mimo`）、POLICY 文案（如 codebuddy `POLICY_TEXT` 6970B）。
+   要改 = 大版本 + `docs/MIGRATION.md` 补条目。
+3. **模板占位符各恰一次**：`/*__KIT__*/`、`/*__PROVIDER__*/`、`/*__SCHED__*/`；生成物
+   （`dynamic/*.host.js`、`preset/*/agent.cordis.yml`、`preset.yml`）**必须入库**，`build --check` 漂移即红。
+4. **单一 id 轴**：任何地方需要 id 列表都从 `providers/registry.mjs` 派生（`build.mjs`、
+   `preset-declarations`、client 的 `providerMetas()` 都已改为派生）。禁止第二处硬编码三家 id。
+5. **零运行时依赖**，且**禁止新增 `@deepseek-ai/dsh*` peer 依赖**（`verify.mjs` + 测试双锁）。
+6. **家级 `bin\` 三个服务器与 `deploy/legacy-mcp/` 副本逐字节一致**（`tests/keystone/legacy-mcp-gate.test.mjs`）。
+7. **失败要响亮（开发期）**：不写静默降级/兜底；门禁只做「注册/不注册」，不改工具语义。
+
+## 6. 调度（0.2.0+）实现要点
+
+用户目标：**选择启用哪些 CLI（数量）+ 排定调用优先级**，且加第 N 家 CLI 时零改动。
+
+- **落盘**：`{DSH_HOME}/cli-bridge-settings.json` 顶层 `_scheduling = { enabled, priority }`
+  （下划线前缀 = 非 provider 分区，旧代码整区忽略 → 纯增量兼容）。
+- **语义**：`enabled` 是集合（数组顺序无意义）；`priority` 的**数组顺序即优先级**；
+  派生 `order = priority ∩ enabled`。
+- **fail-open**：文件缺失/坏值/无 fs → 全部启用（读不到 ≠ 全关）；只有**显式** `enabled: []` 是全关。
+- **钉住优先**：env `CLI_BRIDGE_PROVIDER` / `--provider=<id>`（MCP 薄封装）优先级最高；
+  宿主形态传 `ignorePin`，避免被全局 env 反噬。
+- **四个生效面**：
+  1. `preset/<id>/cli-bridge.mjs` 与 `dynamic/*.host.js` 的 `apply()` 首行门禁（禁用面零注册）；
+     `preset-declarations` 的注册顺序 = 优先级顺序；
+  2. 统一 MCP `selectedProviders()` 按 `enabled` 过滤、按 `order` 排序（**启动读一次**）；
+  3. 家级 `bin\*-mcp-server.mjs` 经 `bin\cli-bridge-scheduling.mjs` 的 `filterTools()` **每请求现读**
+     （面板改完立即生效，无需重启子进程）；mimo 的 dispatch 层单独加了拒调文本；
+  4. `GET /cli-bridge/status` 与 `/cli-bridge/settings` 每次轮询现读并附 `scheduling` 快照。
+- **客户端**：`providerMetas()` 以视图 `scheduling.all ∪ providers 键` 为权威 id 轴（本地 `PROVIDERS`
+  降级为 fallback，仅补 presetId/展示 label）；标签页一排点击切换；`stale` 项目（>10 分钟无活动）
+  不再渲染常亮 pill（弹窗里仍保留历史）。
+
+## 7. 本机运行环境接线现状（机器特定）
+
+### 7.1 安装形态
+
+- `dsh-home/profiles/web/package.json`：`"@luchenglong/cli-bridge": "file:C:/Users/lcl/Desktop/DSH插件开发/CLI Bridge"`，
+  并在 `dsh.profile.bundles` 登记 → 包内 `cordis.patch.yml` 作为 bundle 层自动挂载（宿主半 + 浏览器半 + 三 preset）。
+- **改完必须刷新快照**（pnpm 对 `file:` 依赖按**版本**键控缓存）：
+  ```powershell
+  $installed = "$env:APPDATA\DSH Desktop\dsh-home\profiles\web\node_modules\@luchenglong\cli-bridge"
+  Remove-Item $installed -Recurse -Force
+  Push-Location "$env:APPDATA\DSH Desktop\dsh-home\profiles\web"; pnpm install --prefer-offline; Pop-Location
+  # 校验：Get-FileHash 对比仓库与快照同名文件
+  ```
+
+### 7.2 生效时机（**最容易踩**）
+
+| 改动 | 生效方式 |
+| --- | --- |
+| `lib/client.js`（浏览器半） | **刷新页面（F5）** 即生效，不用重启 |
+| `lib/index.mjs`、`lib/settings.mjs`、`preset-declarations.mjs` | **必须重启 DSH**（宿主启动时加载） |
+| `dsh-home/cordis.patch.yml`（家级补丁/插件行） | **必须重启 DSH** |
+| 家级 `bin\*-mcp-server.mjs` | 子进程重启；但调度门禁是**每请求**读盘，改设置不用重启 |
+| 统一 `mcp/cli-bridge-mcp.mjs` | 子进程重启后读新配置 |
+
+### 7.3 家级补丁（`dsh-home\cordis.patch.yml`）
+
+活跃 8 条：`session-cleaner`、`local-llm-bridge`、`bot-gateway`、`mobile-companion`，
+以及 **四条 MCP 行**：`mcp-agy-global` / `mcp-codebuddy-global` / `mcp-playwright-global` / `mcp-mimo-global`
+（2026-10-14 从注释状态恢复；备份 `cordis.patch.yml.bak-before-mcp-restore-20261014-234959`）。
+
+⚠️ 该文件里 agy/codebuddy/playwright **各另有一份注释留档副本**（历史）。启用时**只能启用一份**，
+否则同 id 重复 → loader 致命错误。改完必须用规范 YAML 解析器验证：
+
+```powershell
+node -e "const y=require('$env:APPDATA/DSH Desktop/backend/dsh/node_modules/yaml');const d=y.parse(require('fs').readFileSync('$env:APPDATA/DSH Desktop/dsh-home/cordis.patch.yml','utf8'));const ids=[];for(const e of d)for(const k of Object.keys(e))for(const i of e[k])ids.push(i.id);console.log(d.length, ids.join(','), 'dup:', ids.filter((x,n)=>ids.indexOf(x)!==n))"
+```
+
+### 7.4 家级 MCP 材料
+
+`dsh-home\bin\agy-mcp-server.mjs`、`bin\codebuddy-mcp-server.mjs`、`bin\cli-bridge-scheduling.mjs`（门禁 helper）、
+`bin\mimo-mcp\{mcp\mimo-mcp-server.mjs,core\*}`、`plugins\playwright-mcp\`（含浏览器内核 `browsers\`）。
+这些是**稳定副本**（仓库/包体变动不影响），但其权威源在仓库 `deploy/legacy-mcp/` + `mcp/`。
+
+### 7.5 状态与设置
+
+- 设置文件：`dsh-home\cli-bridge-settings.json`（交接时：`enabled=[codebuddy,agy]`、
+  `priority=[agy,codebuddy,mimo]` → `order=[agy,codebuddy]`，即 **mimo 停用、agy 优先级最高**）。
+- 状态路由：`GET /cli-bridge/status`（含 `scheduling`）；旧路由 `/<id>-indicator/status` 仍返回裸桶。
+- GUI 需要登录态；**用 HTTP 探针即可**（不要把无凭据浏览器指向 GUI，会 401）。
+
+## 8. 发布流程
+
+见 `docs/RELEASE-SOP.md`（铁律 + 逐步命令）。要点：
+
+1. `npm run check` 全绿 → 版本三锁同步（含 `CHANGELOG.md` 顶部）→ `node scripts/build.mjs` → commit → tag → push；
+2. **scoped 包可见性权威开关是 `package.json` 的 `publishConfig.access="public"`**
+   （0.2.2 首发踩坑：只靠命令行 `--access public` 时，走 GUI/插件通道发布不带该参数 → `E402 Payment Required`）；
+3. 发布后可 `npm deprecate <old>@* "<msg>"` 迁移旧包；**先发布后弃用，顺序不可倒置**；
+4. npm 首次创建 scoped 包返回 `PUT 202 Accepted`（"may take a few minutes"）**属正常，勿重复发布**。
+
+本机发布通道：DSH 工具 `repo_push_access`（GUI 插件 “repo-push-access”，凭据存 DSH 凭据库）。
+
+## 9. 凭据与安全
+
+- 凭据库：`dsh-home\.credentials.yaml`。**键必须形如 `<scope>/<id>`**
+  （如 `repo-push-access/github-com`、`repo-push-access/registry-npmjs-org`）——
+  曾因键写成 `repo-push-access:github.com` 导致凭据文档整体不可读 → DSH 启动致命错 + profile 被隔离为
+  `profiles.broken-*`。
+- 命令行侧**没有** npm/GitHub 登录态；需要 CLI 操作时从凭据库取用，**不要把 token 打进日志/翻译稿**。
+- 仓库内不得出现任何 token；`.credentials.yaml` 及其备份不入库。
+
+## 10. 排障手册（症状 → 原因 → 处置）
+
+| 症状 | 原因 | 处置 |
+| --- | --- | --- |
+| 设置面板白屏 / 整个插件页崩 | client.js 引用了未声明标识符，或 load id ≠ 包名 | 跑 `tests/keystone/client-ui-surface.test.mjs`（含标识符扫描）与 `client-id.test.mjs` |
+| 面板没有横向标签 / 没有调度卡 | 浏览器仍在用旧 client.js | F5 刷新；核对 `GET /cli-bridge/settings` 是否含 `scheduling`（不含=宿主也是旧代码 → 重启） |
+| 面板改了启用/优先级但没生效 | ①POST 未成功 ②宿主形态需重启会话 ③统一 MCP 子进程需重启 | 看 `cli-bridge-settings.json` 是否写入 `_scheduling`；家级 `bin\` 服务器无需重启（每请求读盘） |
+| 指示灯长期亮着 | 陈旧项目（>10 分钟无活动）驱动了顶层聚合 | 0.2.1 已修（客户端过滤 + 服务端聚合只看新鲜项目）；复发查 `projects[].stale` 与 `PROJECT_TTL_MS` |
+| `pnpm install` 后还是旧代码 | `file:` 依赖按版本键控缓存 | 先 `Remove-Item` 快照目录再 `pnpm install --prefer-offline`，然后哈希比对 |
+| npm 发布 `E402 Payment Required` | scoped 包按私有发布 | `package.json` 加 `publishConfig.access="public"` |
+| npm 发布后 `npm view` 404 | 首次创建 scoped 包在 processing / CDN 负缓存 | 看 npm 日志 `…\.npm-cache\_logs\*` 的 `PUT 202`；等几分钟，别重复发 |
+| 家级补丁报 `Sequence item without - indicator` | 解除注释时把**段落注释**也剥了（前导 `#` 被误删） | 从 `*.bak-*` 还原，按**条目行区间**精确剥离；用 §7.3 的 YAML 校验命令 |
+| 会话里没有 `mcp__*` 工具 | 家级补丁四条 MCP 行被注释 / 未重启 / 子进程未起 | 检查补丁活跃 id、重启 DSH、`Get-CimInstance Win32_Process` 找 node 子进程 |
+| 出现 `profiles.broken-*` | 启动期插件激活失败被桌面壳隔离 | 看 `dsh-home\logs\startup-*.log` 定位首个 error；历史根因是凭据键格式 |
+
+## 11. 待办与已知遗留
+
+1. **重启 DSH** —— 恢复的四条 MCP 行需要重启才注册（交接时点刚改完配置，尚未重启）。
+   重启后：新会话出现 `mcp__agy__*`（4 个，含 quota）、`mcp__codebuddy__*`（3）、`mcp__playwright__*`；
+   `mcp__mimo__*` 因调度停用而**工具面为空**（这是设计行为，不是故障）。
+2. 可选：`repo-push-access` 插件写临时 npmrc 时带的 `always-auth=true` 触发 npm 11 弃用警告
+   （源码在 `C:\Users\lcl\Desktop\DSH插件开发\git推送管理\repo-push-access`）；删掉该行即可静音。
+3. 可选：npm 上的 0.2.2 比仓库少 2 个**纯文档** commit（发布后的 release notes/SOP 补充）；
+   如需 npm 侧完全一致，可发 0.2.3（无功能改动）。
+4. `dsh-home\profiles.broken-*` 是历史隔离物（用户数据，未清理）。
+
+## 12. 事故史速查（后来者避坑）
+
+- **client 注册 id 必须等于包名**：旧包曾因 id 不匹配导致整屏崩溃 → 现在三重机器锁。
+- **一次 edit 失败没复查**：渲染引用了未定义的 handler → 白屏，`node --check` 查不出 →
+  新增「渲染引用标识符必须已声明」静态测试。
+- **React hook 顺序**：tab 的 `useState` 曾放在 `if (!view) return` 之后 → view 加载瞬间 hook 数量变化 → 崩面板；
+  现在有「hook 必须在早期 return 之前」的静态锁。
+- **profile 隔离会吞掉用户层补丁**：`profiles/web/cordis.patch.yml` 曾随隔离重建丢失 →
+  机器级配置一律写 `dsh-home\cordis.patch.yml`（家级，不受隔离影响）。
+- **双源挂载**：家级 `file://` 行与 bundle 层同时声明同一 id → `multiple active Loader sources` 致命错误；
+  统一包只走 bundle 层，家级只保留注释留档。
+- **MCP 反复丢失**：家级三条 MCP 行曾在隔离重建中消失且被当基线固化；恢复时误留成注释 →
+  本次已恢复为活跃行（§7.3）。
+
+---
+
+### 交接最小检查单
+
+- [ ] `npm run check` 全绿（271 测试）
+- [ ] `node mcp/cli-bridge-mcp.mjs --check` 显示 `scheduling.source`
+- [ ] `GET $env:DSH_WEB_URL/cli-bridge/status` 返回三家 + `scheduling`
+- [ ] 重启 DSH 后确认四条 MCP 工具面（含 mimo 为空）
+- [ ] 设置面板能勾选/排序/保存，且 `cli-bridge-settings.json` 落盘
+- [ ] 知道红线在 §5、生效时机在 §7.2、排障在 §10