@luchenglong/cli-bridge 0.0.0-stage → 0.2.2

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/INSTALL.md

@@ -0,0 +1,118 @@
+# 安装指南（CLI Bridge）
+
+一个包四种形态，可组合使用：
+
+1. **持久 Agent Preset**（推荐主形态）—— 三家工具 + 优先策略 + 回退弹窗 + `<id>_status`：
+   `cordis-agy` / `codebuddy-first` / `cordis-mimo`（preset id 与旧包一致，旧会话直接续用）；
+2. **家级指示灯插件** —— 状态灯、统一设置面板、preset 声明注册，随 DSH 启动自动加载、
+   所有会话显示、无需审批（`home-plugin/cli-bridge-indicator`，经包内 `dsh.bundle.patch` 挂载）；
+3. **动态 Cordis 插件** —— 沙箱内临时形态（`dynamic/<id>.host.js`），给不方便装 preset 的
+   组合用；
+4. **MCP stdio server** —— 给 DSH 之外的任何 MCP 客户端（Claude Code / Cursor / …）：
+   `node mcp/cli-bridge-mcp.mjs`（或单家入口 `mcp/<id>-mcp-server.mjs`）。
+
+**推荐组合：方式 A + 方式 B** —— 一次接线，三家工具与常驻状态灯齐备。
+
+---
+
+## 前提
+
+- 一套可运行的 **DeepSeek Harness (DSH)**（`>=0.1.1-rc.2 <0.3.0-0`，本机 0.2.1-alpha.1 验证）。
+- 至少装好一家你要用的本机 CLI（工具会在缺失时亮灰灯并给出安装指引，不会崩）：
+  - `agy`（Google Antigravity CLI）—— 需已登录（`agy login`）；
+  - `codebuddy`（`npm i -g @tencent-ai/codebuddy-code`）；workbuddy/codebuddy-en 走桌面捆绑路径；
+  - `mimo`（MiMoCode CLI）或运行中的 Xiaomi MiMo Desktop（mimo-desktop 后端）。
+- 会话组合挂载这些 Host 服务（`standard` 系 preset 默认都有）：`tools`、`subprocess`、
+  `systemPrompt`、`timer`；可选增强：`jobs`（后台任务）、`planMode`（plan 自动判定）、
+  `sandboxPolicy`（默认 cwd）、`userQuestions`（回退弹窗）。
+
+---
+
+## 方式 A + B：bundle 接线（一次装齐，推荐）
+
+本包是「双面 bundle」：`dsh.bundle.patch` 只带一行 indicator（家级灯 + 设置 + 路由），
+三家 preset 由 indicator 内 **声明制自注册**（Form-A，`agentPresets.register`），
+任何受支持 DSH 版本一步到位。
+
+1. 安装依赖到 profile（停 DSH 后端后操作；运行中改 bundles 有损坏风险，红线）：
+
+   ```powershell
+   npm run deploy:local        # 暂存到 {DSH_HOME}/staging/cli-bridge（只拷贝，不改 profile）
+   ```
+
+   或全局安装后直接引用 npm 包：`npm i -g @luchenglong/cli-bridge`。
+
+2. 在 profile 的 `package.json` 加依赖（file: 或版本号），并把包名加入 bundles 列表：
+
+   ```jsonc
+   {
+     "dependencies": { "@luchenglong/cli-bridge": "file:C:/Users/<you>/AppData/Roaming/DSH Desktop/dsh-home/staging/cli-bridge" },
+     "bundles": ["@luchenglong/cli-bridge"]
+   }
+   ```
+
+3. 若之前挂着三个旧桥接包：删除它们的依赖与 bundle 条目（迁移见 [docs/MIGRATION.md](docs/MIGRATION.md)）。
+
+4. 重启 DSH，验证：
+   - 模式菜单出现 **AGY 执行代理 / CodeBuddy 执行代理 / MiMo 执行代理** 三个 preset；
+   - 标题栏出现一盏聚合 pill（AGY · CB · MIMO 分区）；
+   - `GET http://127.0.0.1:<port>/cli-bridge/status` 返回三桶 JSON；
+   - 设置页出现「CLI Bridge」段（三家卡片 + 诊断）。
+
+## 方式 C：动态宿主（无 preset 的组合）
+
+把 `dynamic/<id>.host.js`（仓库已带生成物；改模板后 `node scripts/build.mjs` 重新生成）
+粘贴进 Cordis 组合的 `code.host`。沙箱内零 import，宿主能力走 `harness.*`；状态经
+`cliBridgeCollector`（旧 `agyCollector/codebuddyCollector/mimoCollector` 别名兼容）汇入灯。
+
+## 方式 D：MCP server（DSH 之外）
+
+```json
+{
+  "mcpServers": {
+    "cli-bridge": {
+      "command": "node",
+      "args": ["<安装路径>/@luchenglong/cli-bridge/mcp/cli-bridge-mcp.mjs"]
+    }
+  }
+}
+```
+
+只要一家：`args` 换成 `mcp/agy-mcp-server.mjs`（等价 `--provider=agy`），其余配置与旧包一致。
+自检：`node mcp/cli-bridge-mcp.mjs --check`。
+
+**MCP 形态的状态灯**：MCP 进程把状态原子写到 `{DSH_HOME}/cli-bridge-mcp-<id>.json`
+（90s 内有效），DSH 里常驻的家级灯自动合并显示；家级插件不在线时，灯自然熄灭（快照过期），
+不会误报「运行中」。旧包快照文件（`codebuddy-indicator-mcp.json`、
+`plugins/mimo-indicator/mcp-live.json`）仍被兼容读取。
+
+---
+
+## 设置
+
+DSH 设置页 →「CLI Bridge」：每家一张卡片（字段由 provider 声明），token 类字段只显掩码
+（保存留空 = 保持现值，勾选清除 = 显式删除）。落盘 `{DSH_HOME}/cli-bridge-settings.json`
+（按 provider 分区；env `CLI_BRIDGE_SETTINGS_FILE` 可覆盖）。
+旧包设置文件（`codebuddy-bridge-settings.json`、`{APPDATA}/mimo-first-bridge/settings.json`）
+会被**一次性字段级迁移**：新文件没写过该字段则自动回退旧值，写过即以新值为准；永不写旧文件。
+
+## 环境变量总表（与旧包逐字一致，另加统一项）
+
+| 变量 | 作用 |
+| --- | --- |
+| `AGY_BIN` / `AGY_CLI` | agy 可执行覆盖 |
+| `AGY_MCP_CWD` | agy 默认工作目录 |
+| `CLI_BRIDGE_AGY_QUOTA`（兼容旧 `AGY_QUOTA_SCRIPT`） | 额度脚本路径覆盖（默认包内 bin） |
+| `CODEBUDDY_BIN` / `CODEBUDDY_EN_BIN` / `WORKBUDDY_BIN` | codebuddy 各家可执行覆盖 |
+| `CODEBUDDY_AUTH_TOKEN` / `CODEBUDDY_BASE_URL` / `CODEBUDDY_INTERNET_ENVIRONMENT` | codebuddy 端点与凭据注入 |
+| `CODEBUDDY_AUTH_DIR` / `CODEBUDDY_CREDENTIALS_DIR` / `CODEBUDDY_MODELS_FILE` | 登录域文件目录 / DSH 凭据库目录（内放 `WORKBUDDY_TOKEN:` 等）/ 模型目录注入（旧包即有，多为测试与诊断覆盖；`WORKBUDDY_TOKEN` 本身不是环境变量，是凭据文件里的键） |
+| `CODEBUDDY_MCP_CWD` | codebuddy MCP 默认工作目录（仅 MCP 面；preset/dynamic 不读） |
+| `CODEBUDDY_AUTH_TOKEN` / `CODEBUDDY_BASE_URL` / `CODEBUDDY_INTERNET_ENVIRONMENT` | codebuddy 端点与凭据注入 |
+| `CODEBUDDY_SETTINGS_FILE` | 旧 codebuddy 设置文件覆盖（迁移读） |
+| `CODEBUDDY_MCP_ALLOWED_ROOTS` | codebuddy MCP 的 cwd 白名单 |
+| `MIMO_BIN` / `MIMO_CLI` | mimo CLI 覆盖 |
+| `MIMO_BRIDGE_BACKEND` / `MIMO_BACKEND` / `MIMO_DESKTOP_MODEL` | mimo 后端/桌面模型 env |
+| `MIMO_BRIDGE_SETTINGS` | 旧 mimo 设置文件覆盖（迁移读） |
+| `MIMO_MCP_CWD` | mimo 默认工作目录 |
+| `DSH_HOME` | dsh-home 定位（设置/MCP 快照文件根） |
+| `CLI_BRIDGE_SETTINGS_FILE` | 统一设置文件整体覆盖 |

package/docs/MCP-POLICY.zh.md

@@ -0,0 +1,49 @@
+# CLI Bridge 优先策略（cli-bridge MCP）· 中文版
+
+[English](../MCP-POLICY.md) | 中文 —— 权威文本；开发机上同步安装到
+`~/.claude/CLAUDE.md` 与 `~/.codex/AGENTS.md`。
+
+本机三个编码 CLI agent —— **`agy`**（Google Antigravity）、**`codebuddy`**（腾讯
+CodeBuddy Code，四种产品形态）与 **`mimo`**（小米 MiMoCode CLI / MiMo Desktop）——
+经 MCP server **`cli-bridge`** 暴露为工具：`agy_run / agy_continue / agy_status /
+agy_quota`、`codebuddy_run / codebuddy_continue / codebuddy_status`、
+`mimo_run / mimo_continue / mimo_status / mimo_settings`（宿主侧带服务前缀，如
+`mcp__cli-bridge__agy_run`）。所有 CLI **全程受宿主掌控、完全非交互**：权限自动批准、
+绝不弹提示，可以直接改文件、跑构建、做跨文件排查。
+
+一个 server 同时暴露三家；用 `--provider=agy`（或单家入口 `mcp/<id>-mcp-server.mjs`）
+可只开一家，工具面与旧包配置逐字兼容。
+
+## 优先规则 —— 决策表与上下文协议
+
+### 工具选择（三家同构）
+- **单条 read/glob/grep 或 <30 秒短命令** → 用宿主原生工具。
+- **实现、编辑、重构、调试、构建、跨文件排查** → 优先 `<id>_run`（按账号/额度选家族）。
+- **同主题后续** → `<id>_continue` 带 `sessionId`/`conversationId` 或 `latest: true`
+  （会话上下文由服务端保留）。
+- **对 CLI 产出做最终构建/测试验证** → 用宿主原生工具。
+- **图像/视频生成** → 派给 `agy_run`，不指定模型。
+
+### 上下文协议（一个主题 = 一个会话）
+- **主题首次派发**：带一段紧凑 CONTEXT 前言（指向路径，不要粘贴文件内容；CLI 自己读仓库）：
+  ```
+  CONTEXT: 2-6 行 —— 目标；仓库根；关键路径；决定/约束；当前状态。
+  TASK: 完整指令。
+  ```
+- **后续**：调用 `<id>_continue`，只说新增部分。
+- 任务暂时不许写文件时，`<id>_run` 用 `mode: "plan"`。
+- 委派子代理时，要求其同样遵守本 CLI 优先策略。
+- `<id>_run`/`<id>_continue` 运行期间可随时 `<id>_status` 看各项目此刻步骤与最近轨迹，
+  无需等待完成。
+
+## 额度感知（agy）
+
+`agy_quota` 返回 Google AI 套餐各池余量。**Gemini 5 小时窗口是唯一的任务级门禁**
+（余量低于约 10% 时桥接会直接拦截派发）；周池耗尽不会中止工作 —— 只代表本周剩余时间
+agy 不是好选择。codebuddy 无额度 API：用 `codebuddy_status` 观察各项目
+`runs`/`totalTokens`。`mimo_settings` 查看生效后端（CLI vs Desktop）。
+
+## 回退 —— 绝不循环
+
+CLI **被限流或网络不通**时，工具结果文本会明确说明。**不要循环重试。** 用自己的工具
+完成任务，或询问用户是否回退到本地模型/API 配置。绝不让被派发的 CLI 回调宿主。

package/docs/MIGRATION.md

@@ -0,0 +1,43 @@
+# 从三个旧包迁移到 @luchenglong/cli-bridge
+
+三个旧包（`agy-first-bridge` ≤1.7.1、`codebuddy-first-bridge` ≤1.6.2、
+`mimo-first-bridge` ≤1.2.9）已全部并入本包并 deprecated。**行为与接口的兼容性是逐字级
+的**，迁移只是「换包名 + 换路径」：
+
+## 不变的东西（刻意设计）
+
+| 项 | 旧 | 新 | 变化 |
+| --- | --- | --- | --- |
+| 工具名 | `agy_run` / `codebuddy_run` / `mimo_run` …（含 continue/status/quota/settings） | 同左 | **无** |
+| 工具入参/返回语义 | 旧包定义 | verbatim 移植 | **无** |
+| preset id | `cordis-agy` / `codebuddy-first` / `cordis-mimo` | 同左 | **无**（旧会话头直接续用） |
+| 优先策略/POLICY 文本 | 各旧包 | verbatim | **无** |
+| 回退弹窗三选一 | 各旧包 | 统一内核实现，标签/语义一致 | 无 |
+| env 变量 | 各旧包（见 INSTALL 总表） | 全部保留 | 无 |
+| 家级路由 | `/{agy,codebuddy,mimo}-indicator/status` 等 | 保留为兼容别名，新增 `/cli-bridge/status` 聚合 | 兼容 |
+| 设置语义（token 掩码/空=保持/Clear=清除） | codebuddy v1.3+ | 统一面板逐字段保留 | 兼容 |
+| 旧设置文件 | `codebuddy-bridge-settings.json`、`{APPDATA}/mimo-first-bridge/settings.json` | 自动一次性迁移（新分区没写过该字段才回退旧值；写新不写旧） | 无损 |
+| MCP 快照文件 | `{DSH_HOME}/plugins/agy-indicator/mcp-live.json`、`{DSH_HOME}/codebuddy-indicator-mcp.json`、`{DSH_HOME}/plugins/mimo-indicator/mcp-live.json` | 新名 `cli-bridge-mcp-<id>.json`；三个旧名仍被家级灯兼容读取 | 无损 |
+
+## 需要动手的三处
+
+1. **DSH profile / bundles**：删除三个旧包条目，加入 `@luchenglong/cli-bridge`
+   （操作前必须停止 DSH 后端——运行时改接线有损坏风险）。
+2. **外部 MCP 配置**（Claude Code / Cursor 等）：`args` 路径从
+   `<旧包>/mcp/<id>-mcp-server.mjs` 换成 `<新包>/mcp/<id>-mcp-server.mjs`（同名兼容入口，
+   也可换 `mcp/cli-bridge-mcp.mjs` 一次拿全部三家）。
+3. **直接引用过旧包内部路径的脚本**（如有）：旧 `core/*` → 新
+   `providers/<id>.mjs` + `core/bridge-kit.mjs`；旧 preset 模块路径 → 新
+   `@luchenglong/cli-bridge/preset-<id>`（exports 子路径）。
+
+## 版本对应
+
+`0.1.0` 的功能基线 = agy 1.7.1 + codebuddy 1.6.2 + mimo 1.2.9 之和。
+三家完整历史在 [docs/history/](history/)（verbatim）；统一包自己的演进在
+[CHANGELOG.md](../CHANGELOG.md)。
+
+## 旧包仓库
+
+三个旧仓库将只读归档（README 顶部挂迁移横幅）。npm 上已执行
+`npm deprecate <旧包>@"*" "replaced by @luchenglong/cli-bridge"`。
+不要再向旧包提 issue/PR —— 一律发到新仓库。

package/docs/RELEASE-SOP.md

@@ -0,0 +1,77 @@
+# 发布与维护 SOP（npm + GitHub）
+
+> 本包发布与日常维护的操作手册。每一步的「为什么」都指向旧包 lineage 里的历史事故
+> （agy v1.6.1、codebuddy v1.1.8/v1.7.1、mimo v1.2.9），不要跳步。
+
+## 0. 铁律（违反任何一条都不要发布）
+
+1. **npm publish 必须带 `--access public`**：包是 `@luchenglong` scope，scoped 包默认
+   restricted，漏了直接 402/私有可见性事故。
+2. **client 注册 id === 包名**（`@luchenglong/cli-bridge`，红线 4）。`scripts/verify.mjs`
+   与 `tests/keystone/client-id.test.mjs` 双重机器闸门。改包名必须同改 client.js 的
+   `__ModuleLoader__.load({ id })`，否则 client combo 加载失败 → DSH 启动致命屏（agy
+   v1.6.1 / codebuddy v1.1.8 事故原样）。
+3. **先 git 后 npm**：commit → tag → push → GitHub Release → `npm publish` 顺序不可倒置。
+   发布前 `npm run check` 全绿（build --check 防生成物漂移 + verify 红线 + node --test +
+   mcp --check）。
+4. **生成物入库**：`dynamic/*.host.js`、`preset/*/agent.cordis.yml`、`preset.yml` 提交；
+   `scripts/build.mjs --check` 漂移即红。改了 plugin-list/模板/kit/providers 必须重跑
+   `node scripts/build.mjs` 并把生成物放进同一个 commit。
+5. **provider 语义 verbatim**：工具名、入参 schema、preset id、POLICY 文案是对外的兼容
+   承诺（旧会话头/提示词在用）。要改 = 大版本 + MIGRATION.md 补条目。
+6. **禁止新增运行时依赖与 `@deepseek-ai/dsh*` peer 依赖**（verify/测试双锁；加 dsh peer
+   会武装 0.2.x 兼容闸门，历史论证）。
+
+## 1. 标准发布流程
+
+```powershell
+# ① 全量校验
+npm run check
+
+# ② 版本同步三处：package.json / CHANGELOG.md 顶部 / mcp/cli-bridge-mcp.mjs 的
+#    SERVER_VERSION（verify.mjs 机器比对，漏改即红）
+
+# ③ 提交 + tag + 推送
+git add <相关文件>; git commit -m "chore(release): v0.1.1"
+git tag -a v0.1.1 -m "v0.1.1"
+git push origin main; git push origin v0.1.1
+
+# ④ 发布（prepack 自动再跑 verify + build --check）
+npm publish --access public
+
+# ⑤ 发布后审计
+npm view @luchenglong/cli-bridge version dist.tarball
+# GitHub 建 Release 挂 CHANGELOG 条目
+```
+
+## 2. 首次建仓（当前凭据失效，恢复后照此执行）
+
+```powershell
+gh auth login                      # 或 gh auth refresh -s repo,workflow
+gh repo create new-256/cli-bridge --public --source . --push --description "Unified CLI bridge for DSH: agy + CodeBuddy + MiMo in one plugin"
+npm login
+npm publish --access public
+# 旧包下线（deprecate 不删除，旧安装仍可用但提示迁移）
+npm deprecate agy-first-bridge@"*" "replaced by @luchenglong/cli-bridge"
+npm deprecate codebuddy-first-bridge@"*" "replaced by @luchenglong/cli-bridge"
+npm deprecate mimo-first-bridge@"*" "replaced by @luchenglong/cli-bridge"
+```
+
+> 360 安全软件曾静默删除带 GitHub remote 丢失的目录——**每个仓库必须有 remote**。
+> 三个旧仓库在 README 挂迁移横幅后于 GitHub 归档（Archive）。
+
+## 3. 日常维护闸门
+
+- 任意代码改动：`npm run check`（等价 CI）。
+- 只改一家：`node scripts/build.mjs --only=<id>` + `node --test tests/<id>`。
+- 指示灯/设置层改动：`node --test tests/keystone`。
+- 排查线上「灯不对」：先看 `GET /cli-bridge/status` 三桶 JSON，再看
+  `{DSH_HOME}/cli-bridge-mcp-<id>.json` 的 updatedAt（>90s = MCP 侧停更），
+  再看设置卡诊断行。
+- 运行时接线永远「先停 DSH 后端」再改 profile（红线 2）。
+
+## 4. 回滚
+
+npm 侧：`npm deprecate @luchenglong/cli-bridge@<坏版本> "..."` + 发补丁版（npm 不删
+已发布内容）。git 侧：revert 提交重发。DSH 侧最坏情况（client id 写错上线）：profile
+里摘掉该 bundle 重启即可恢复，与旧包时代一致。