@ohos-cpf/3rdloop 0.0.7 → 0.0.9

package/README.md

@@ -44,10 +44,10 @@ npm i -g @ohos-cpf/3rdloop
 3rdloop doctor
 ```
 
-`doctor` 会逐项检查 Node / opencode / `.env` 凭据 / SKILL 目录 / 数据目录，缺什么会明确提示。除此之外还需要了解：
+`doctor` 会逐项检查 Node / CLI_TYPE 配置 / AI CLI（按 `CLI_TYPE` 检测 opencode 或 deveco）/ `.env` 凭据 / SKILL 目录 / 数据目录 / serve 服务连通性，缺什么会明确提示。除此之外还需要了解：
 
 - **Node.js** >= 22
-- **opencode CLI**：`3rdloop` 会自动拉起 `opencode serve`（在项目上一级目录运行），退出时清理进程树；已存在则复用，一般无需手动管理
+- **AI CLI**（默认 `deveco`，`CLI_TYPE` 可切 `opencode`）：`3rdloop` 会自动拉起对应的 `serve` 服务（在项目上一级目录运行），退出时清理进程树；已存在则复用，一般无需手动管理
 - **LLM 凭据**：`doctor` 提示凭据缺失时，见下面"配置"一节
 
 ### 场景二：配置 —— 需要注意哪些配置项
@@ -78,8 +78,9 @@ npm i -g @ohos-cpf/3rdloop
 # LLM 模型 id
 3rdloop config set LLM_MODEL glm-5.2
 
-# 默认 CLI 类型（opencode | deveco-code，HarmonyOS 场景切 deveco-code）
-3rdloop config set CLI_TYPE deveco-code
+# 默认 CLI 类型（默认 deveco-code；如需切回 opencode）
+# 切换后 doctor 按新类型检测，run/step/orch/workflow 拉起对应 serve 并连接
+3rdloop config set CLI_TYPE opencode
 
 # 数据存储目录（默认 ~/.3lib/3rdloop/db，如团队共享目录）
 3rdloop config set 3LIB_DATA_DIR "D:\code\team\shared-db"
@@ -106,6 +107,8 @@ npm i -g @ohos-cpf/3rdloop
 
 `run` 会自动完成"任务拆解 → 编排执行 → 准出审核"的完整大循环，多轮次自动重规划直到通过；退出码 `0` 即通过。
 
+> **环境预检**：`run`/`submit`/`step run`/`orch run|start` 及工作流在正式执行前会自动做环境预检（Node 版本 / CLI_TYPE / AI CLI / LLM 凭据 / SKILL 目录 / 数据目录）。任一项不通过直接退出码 `1`，并打印对应修复命令（如 `3rdloop config set DASHSCOPE_API_KEY <sk-xxx>`）；完整自检用 `3rdloop doctor`。`--print-taskdef` 等 dry-run 不预检。
+
 任务比较耗时、不想干等？提交后立即返回 taskId（进程内继续跑，需保持进程存活），之后可用 `3rdloop progress/wait/result <taskId>` 跟进：
 
 ```bash
@@ -134,43 +137,59 @@ npm i -g @ohos-cpf/3rdloop
 
 > 提 PR 是非幂等发布操作，失败不会自动重试；执行成功后报告 `ohos-lib-pr-push-report.md` 会自动复制到执行目录。先用 `--print-taskdef` dry-run 可以核对将执行的编排定义。
 
-### 场景五：用 Web 界面操作（serve / web）
-
-除了命令行，也可以在浏览器里使用 Web 工作台（提交任务 / 查看循环进度 / PR 检视等），由两个命令提供支撑：
+### 场景五：用 Web 界面操作（serve）
 
-**`3rdloop serve` —— 启动 Server HTTP 后端**（供前端 / 脚本反向代理调用）：
+除了命令行，也可以在浏览器里使用 Web 工作台（提交任务 / 查看循环进度 / PR 检视等）。`3rdloop serve` 一条命令**同时启动** Server HTTP 后端（默认 3000）与 Web 前端（默认 8080，静态托管 + `/api/*` 反代到后端 + 扩展挂载）：
 
 ```bash
-# 只启动后端（默认 http://127.0.0.1:3000，可用 --port / 3LIB_SERVER_PORT 覆盖）
+# 后端（默认 http://127.0.0.1:3000）+ Web 前端（默认 http://localhost:8080）同时启动
 3rdloop serve
 
-# 后端 + Web 前端一起拉起（前端默认 8080，可用 --web-port / 3LIB_WEB_PORT 覆盖）
-3rdloop serve --web
-```
+# 启动后自动打开浏览器
+3rdloop serve --open
 
-> CLI 的 `run`/`submit`/`wait` 等命令保持嵌入式模式，不经此后端；两者可独立使用。
+# 自定义端口（--port 后端 / --web-port 前端，也可用 3LIB_SERVER_PORT / 3LIB_WEB_PORT 覆盖）
+3rdloop serve --port 3001 --web-port 8081
 
-**`3rdloop web` —— 启动 Web 前端服务**（静态托管 + `/api/*` 反代到后端 + 扩展挂载，默认端口 8080）：
+# 禁用全部扩展（纯核心工作台模式）
+3rdloop serve --no-ext
+```
 
-```bash
-# 启动并自动打开浏览器（--backend 默认指向 http://127.0.0.1:3000，配合 serve 使用）
-3rdloop web --open
+> CLI 的 `run`/`submit`/`wait` 等命令保持嵌入式模式，不经此后端。
 
-# 自定义端口 / 后端地址
-3rdloop web --port 8081 --backend http://127.0.0.1:3000
+扩展机制（tag / issue / prcheck 等二级目录功能以扩展形式按需安装，不随 npm 包分发）：
 
-# 禁用全部扩展（纯核心工作台模式）
-3rdloop web --no-ext
+```bash
+3rdloop serve install-ext <扩展目录>   # 安装扩展到 ~/.3lib/3rdloop/web-ext/
+3rdloop serve list-ext                 # 列出可用扩展（含来源与挂载点）
+3rdloop serve remove-ext <扩展名>      # 移除已安装扩展
 ```
 
-扩展机制（tag / issue / prcheck 等二级目录功能以扩展形式按需安装，不随 npm 包分发）：
+### 场景六：MCP Gateway 装配（kb 检索 / 覆盖率脚本等 AI 工具）
+
+npm 包内置 MCP Gateway（`vendor/MCP`）、知识库检索引擎（`vendor/Archive`）与已知问题知识库种子（`vendor/BadCase`）。opencode / deveco-code serve 需要在**全局配置**注册 Gateway 才会在启动时自动 spawn：
 
 ```bash
-3rdloop web install-ext <扩展目录>   # 安装扩展到 ~/.3lib/3rdloop/web-ext/
-3rdloop web list-ext                 # 列出可用扩展（含来源与挂载点）
-3rdloop web remove-ext <扩展名>      # 移除已安装扩展
+3rdloop doctor              # 推荐：环境自检，检测到未装配时自动完成装配（幂等）
+3rdloop mcp status          # 查看注册状态与数据目录
+3rdloop mcp install         # 显式装配/重装（doctor 自动装配的底层命令，可单独使用）
+3rdloop mcp uninstall       # 仅移除注册（用户数据保留）
+
+# 可选参数
+3rdloop doctor --no-fix               # 仅诊断，不做任何修改
+3rdloop mcp install --cli opencode    # 只注册到 opencode（--cli deveco | opencode | all）
+3rdloop mcp install --force           # 重置用户级配置为包内默认
 ```
 
+装配效果：
+
+- `~/.3lib/3rdloop/mcp/config.json` — 用户级 Gateway 配置（脚本/引擎指向包内，随包更新获得新版本）
+- `~/.3lib/3rdloop/kb-data/` — 本地知识库数据（`kb_add_document` / `kb_search` 工具，跨版本更新不丢失）
+- `~/.3lib/3rdloop/BadCase/` — 已知问题知识库副本（RN 检视 SKILL 消费；泛化 SKILL 的写入落在此处，不污染包目录）
+- 装配后**重启 serve**，AI 会话即可调用全部 MCP 工具（kb 检索、覆盖率分析脚本、下游知识库等）
+
+> SKILL 中的分析脚本（如 `analyze-xts-coverage.cjs`）通过 `{{skillDir}}/../../../MCP/scripts/` 相对路径调用，npm 安装态与仓库开发态一致，无需额外配置。装配通常无需手动执行——`3rdloop doctor`（README 快速上手第一步）会自动完成；`run/submit` 等任务命令的预检若发现未装配，仅在 stderr 提示一行（不修改任何文件）。
+
 更多进阶用法（任务管理、`step` 单步执行、`orch` 自定义编排、工作流注册等），见仓库 `cli/README_DEVELOP.md` 或 `3rdloop <子命令> --help`。
 
 

package/lib/cli.js

@@ -34,7 +34,6 @@ import {
     resolveSkillDir,
     generateTaskId,
     getCliVersion,
-    checkNodeVersion,
 } from './config.js';
 import { EXIT, TERMINAL_LOOP_STATES } from './exit-codes.js';
 
@@ -109,7 +108,7 @@ export async function runCli(argv) {
             return cmdVersion(jsonMode);
 
         case 'doctor':
-            return cmdDoctor({ projectRoot, skillDir, dataDir, quiet });
+            return cmdDoctor({ projectRoot, skillDir, dataDir, user3libHome, quiet, rest });
 
         case 'run':
             return cmdRun({ flags, rest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u });
@@ -144,17 +143,20 @@ export async function runCli(argv) {
         case 'config':
             return cmdConfig({ flags, rest, projectRoot, user3libHome, jsonMode, out });
 
+        case 'mcp':
+            return cmdMcpImpl({ rest, user3libHome, jsonMode });
+
         case 'serve':
-            return cmdServe({ flags, rest, jsonMode, dataDir });
+            return cmdServe({ rest, jsonMode, dataDir, user3libHome });
 
         case 'update':
             return cmdUpdate({ flags, rest, jsonMode, out });
 
-        case 'web':
-            return cmdWeb({ flags, rest, user3libHome, dataDir, jsonMode, out });
-
         default:
             process.stderr.write(`未知命令: ${cmd}\n`);
+            if (cmd === 'web') {
+                process.stderr.write('提示: "3rdloop web" 已合并到 "3rdloop serve"（Web 前端随 serve 默认启动，扩展管理用 3rdloop serve install-ext/list-ext/remove-ext）\n');
+            }
             printHelp();
             return EXIT.ERROR;
     }
@@ -174,12 +176,26 @@ function cmdVersion(jsonMode) {
 
 // ─── doctor ───────────────────────────────────────────────────────
 
-async function cmdDoctor({ projectRoot, skillDir, dataDir, quiet }) {
+async function cmdDoctor({ projectRoot, skillDir, dataDir, user3libHome, quiet, rest = [] }) {
     const { runDoctor } = await import('./doctor.js');
-    const { ok } = await runDoctor({ projectRoot, skillDir, dataDir, quiet });
+    const fix = !rest.includes('--no-fix');
+    const { ok } = await runDoctor({ projectRoot, skillDir, dataDir, user3libHome, quiet, fix });
     return ok ? EXIT.OK : EXIT.ERROR;
 }
 
+/**
+ * 环境预检 + 失败报告（run/submit 等引擎命令共用）。
+ * 通过返回 true；失败打印各项修复提示（--json 时输出结构化结果）并返回 false。
+ */
+async function _precheckOrReport({ projectRoot, dataDir, skillDir, jsonMode, out }) {
+    const { precheckEnv, reportPrecheckFailures } = await import('./doctor.js');
+    const pre = await precheckEnv({ projectRoot, dataDir, skillDir });
+    if (pre.ok) return true;
+    if (jsonMode) out({ ok: false, error: '环境预检未通过', failures: pre.failures });
+    else reportPrecheckFailures(pre.failures);
+    return false;
+}
+
 // ─── workflows（列出已注册工作流） ────────────────────────────────
 
 async function cmdWorkflows({ jsonMode, out }) {
@@ -212,6 +228,16 @@ async function cmdConfig({ flags, rest, projectRoot, user3libHome, jsonMode, out
     return cmdConfigImpl({ projectRoot, user3libHome, jsonMode, out, rest });
 }
 
+// ─── mcp（MCP Gateway 装配）────────────────────────────────────────
+
+/**
+ * 3rdloop mcp 命令二段分发（转发到 lib/mcp.js）。
+ */
+async function cmdMcpImpl({ rest, user3libHome, jsonMode }) {
+    const { cmdMcp } = await import('./mcp.js');
+    return cmdMcp({ rest, user3libHome, jsonMode });
+}
+
 // ─── update（自更新）─────────────────────────────────────────────
 
 async function cmdUpdate({ flags, rest, jsonMode, out }) {
@@ -224,11 +250,11 @@ async function cmdUpdate({ flags, rest, jsonMode, out }) {
     return result.ok ? EXIT.OK : EXIT.ERROR;
 }
 
-// ─── serve（启动 Server HTTP 后端，供前端展示）─────────────────────────
+// ─── serve（同时启动 Server HTTP 后端 + Web 前端）─────────────────
 
-async function cmdServe({ flags, rest, jsonMode, dataDir }) {
+async function cmdServe({ flags, rest, jsonMode, dataDir, user3libHome }) {
     const { cmdServe: impl } = await import('./serve.js');
-    return impl({ rest: flags.rest, jsonMode, dataDir });
+    return impl({ rest: flags.rest, jsonMode, dataDir, user3libHome });
 }
 
 // ─── run / submit ──────────────────────────────────────────────────
@@ -267,6 +293,11 @@ async function submitAndRunImpl({ flags, rest, projectRoot, dataDir, skillDir, j
         return EXIT.ERROR;
     }
 
+    // ── 环境预检（引擎执行前快速失败：凭据/目录类问题直接退出码 1，
+    //    避免跑到一半才失败、被误报为任务失败退出码 2）──────────────────
+    const preOk = await _precheckOrReport({ projectRoot, dataDir, skillDir, jsonMode, out });
+    if (!preOk) return EXIT.ERROR;
+
     // skill-dir 可能来自全局 flags 已在外部解析
     const r = await runner();
     const taskId = generateTaskId();
@@ -274,20 +305,19 @@ async function submitAndRunImpl({ flags, rest, projectRoot, dataDir, skillDir, j
         projectRoot,
         dataDir,
         skillDir,
-        cliType: 'opencode',
         verbose,
     });
 
-    // 挂载 opencode 生命周期
-    const { OpencodeManager } = await import('./opencode.js');
-    const oc = new OpencodeManager({ projectRoot });
+    // 挂载 AI CLI serve 生命周期（类型由 CLI_TYPE 决定：opencode | deveco-code）
+    const { CliServeManager } = await import('./opencode.js');
+    const oc = new CliServeManager({ projectRoot, cliType: ctx.cliType });
     const ocHealth = await oc.ensureRunning();
     if (!ocHealth.ok) {
         if (jsonMode) {
             process.stdout.write(JSON.stringify({ ok: false, error: ocHealth.message, taskId }, null, 2) + '\n');
         }
         process.stderr.write(`\n错误: ${ocHealth.message}\n`);
-        process.stderr.write('请先启动 opencode serve（项目上一级目录: opencode serve）后重试。\n');
+        process.stderr.write(`请先启动 ${oc.cliType} serve（项目上一级目录: ${oc.bin} serve）后重试。\n`);
         await oc.stop();
         return EXIT.ERROR;
     }
@@ -623,14 +653,6 @@ async function cmdOrch({ flags, rest, projectRoot, dataDir, skillDir, jsonMode,
     return impl({ flags, rest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u });
 }
 
-/**
- * 3rdloop web 命令二段分发（转发到 lib/web.js：前端服务 + 扩展挂载）。
- */
-async function cmdWeb({ flags, rest, user3libHome, dataDir, jsonMode, out }) {
-    const { cmdWeb: impl } = await import('./web.js');
-    return impl({ flags, rest, user3libHome, dataDir, jsonMode, out });
-}
-
 // ─── 帮助 ─────────────────────────────────────────────────────────
 
 function printHelp() {
@@ -659,12 +681,15 @@ function printHelp() {
   3rdloop workflows                     列出已注册的固定编排工作流
   3rdloop run <工作流名> [--flag <值> ...]     以固定编排执行工作流（阻塞到终态）
   3rdloop config list|get|set|unset ...  配置 .env 配置项（默认读写 ~/.3lib/.env）
-  3rdloop serve [--port N] [-w|--web] [--web-port N]  启动 Server HTTP 后端（供前端展示）
+  3rdloop mcp install [--cli opencode|deveco|all]  装配 MCP Gateway（注册到 AI CLI +
+          种子复制知识库数据/BadCase 到 ~/.3lib/3rdloop/，npm 安装态必需）
+  3rdloop mcp uninstall|status            移除注册 / 查看装配状态
+  3rdloop serve [--port N] [--web-port N]  启动 Server 后端 + Web 前端（同时启动）
+         [--web-root <dir>] [--ext-root <dir>] [--ext <name,...>] [--no-ext] [--open]
+  3rdloop serve install-ext <dir>                安装扩展（tag/issue/prcheck 等二级功能）
+  3rdloop serve list-ext | remove-ext <name>     扩展管理
   3rdloop update [--check] [--yes] [--registry <url>]  自更新到 npm 最新版
-  3rdloop web [--port N] [--backend <url>]       启动 Web 前端服务
-  3rdloop web install-ext <dir>                  安装扩展（tag/issue/prcheck 等二级功能）
-  3rdloop web list-ext | remove-ext <name>       扩展管理
-  3rdloop doctor                        环境自检
+  3rdloop doctor [--no-fix]             环境自检（默认自动装配 MCP Gateway；--no-fix 仅诊断）
   3rdloop version                       版本信息
 
 工作流机制:

package/lib/config-cmd.js

@@ -90,7 +90,7 @@ export const ENV_KEYS = [
     { key: 'MAX_CONCURRENT_SESSIONS', label: 'AI Session 并发上限', description: '跨所有编排任务共享的全局并发信号量上限', default: '50', validate: validators.intPositive },
 
     // ── CLI / AI 助手后端 ────────────────────────────────────────────
-    { key: 'CLI_TYPE', label: '默认 CLI 类型', description: 'opencode | deveco-code', default: 'opencode', validate: validators.cliType },
+    { key: 'CLI_TYPE', label: '默认 CLI 类型', description: 'opencode | deveco-code', default: 'deveco-code', validate: validators.cliType },
     { key: 'OPENCODE_HOST', label: 'opencode 主机', description: '连接配置（可选）', default: 'localhost', validate: validators.nonEmpty },
     { key: 'OPENCODE_PORT', label: 'opencode 端口', description: '连接配置（可选，默认 4096）', default: '4096', validate: validators.portOrEmpty },
     { key: 'DEVECO_HOST', label: 'deveco 主机', description: '连接配置（可选）', default: 'localhost', validate: validators.nonEmpty },

package/lib/config.js

@@ -7,6 +7,7 @@
  *   - 定位数据目录（--data-dir > 3LIB_DATA_DIR > ~/.3lib/3rdloop/db）
  *   - 生成 clinic 安全唯一 taskId（随机位 8）
  *   - SKILL 目录优先级链（--skill-dir > 3LIB_SKILL_DIR > vendor/Skills）
+ *   - 解析 AI CLI 类型（CLI_TYPE：opencode | deveco-code，默认 deveco-code）
  *
  * 数据目录策略：
  *   用户级统一 ~/.3lib/3rdloop/db（跨平台，由 getUser3libHome 解析），
@@ -204,6 +205,37 @@ export function getUser3libHome() {
     return path.join(home, '.3lib');
 }
 
+/** 支持的 AI CLI 类型 */
+const CLI_TYPES = ['opencode', 'deveco-code'];
+/** 默认 CLI 类型（本项目面向 HarmonyOS 三方库场景，默认 DevEco Code） */
+const DEFAULT_CLI_TYPE = 'deveco-code';
+let _warnedInvalidCliType = false;
+
+/**
+ * 解析当前生效的 AI CLI 类型（opencode | deveco-code）。
+ *
+ * 优先级：显式参数 > 环境变量 CLI_TYPE（含 loadEnvChain 注入的
+ * 系统环境变量 > ~/.3lib/.env > 项目 Server/.env 链）> 'deveco-code'（默认）。
+ * 与 Server/CLI/cli.js、check-env.mjs 的 resolveCliType 语义保持一致。
+ *
+ * CLI_TYPE 配了无效值时不崩溃：回退默认值并在 stderr 告警一次
+ * （doctor 会将其作为失败项显式报告）。
+ *
+ * @param {string} [override] - 显式类型（优先级最高）
+ * @returns {'opencode'|'deveco-code'}
+ */
+export function resolveCliType(override) {
+    const raw = String(override ?? process.env.CLI_TYPE ?? '').trim();
+    if (CLI_TYPES.includes(raw)) return raw;
+    if (raw && !_warnedInvalidCliType) {
+        _warnedInvalidCliType = true;
+        process.stderr.write(
+            `[3rdloop] 警告: CLI_TYPE="${raw}" 无效（可选值: ${CLI_TYPES.join(' | ')}），已回退 ${DEFAULT_CLI_TYPE}\n`
+        );
+    }
+    return DEFAULT_CLI_TYPE;
+}
+
 /**
  * 确定数据目录。
  *