@luchenglong/cli-bridge 0.0.0-stage → 0.2.3

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,80 @@
+# 发布与维护 SOP（npm + GitHub）
+
+> 本包发布与日常维护的操作手册。每一步的「为什么」都指向旧包 lineage 里的历史事故
+> （agy v1.6.1、codebuddy v1.1.8/v1.7.1、mimo v1.2.9），不要跳步。
+
+## 0. 铁律（违反任何一条都不要发布）
+
+1. **scoped 包可见性 = `package.json` 的 `publishConfig.access = "public"`**：包是
+   `@luchenglong` scope，scoped 包默认 restricted。**权威开关必须写在 package.json 里**
+   （0.2.2 首发踩坑：SOP 只要求命令行 `--access public`，但走 GUI/插件通道发布时不带该
+   参数 → npm 按私有包处理 → `E402 Payment Required`）。命令行仍建议显式带
+   `--access public` 双保险，漏了也不会再翻车。
+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 重启即可恢复，与旧包时代一致。