@ohos-cpf/3rdloop 0.0.8 → 0.0.10

package/README.md

@@ -165,6 +165,49 @@ npm i -g @ohos-cpf/3rdloop
 3rdloop serve remove-ext <扩展名>      # 移除已安装扩展
 ```
 
+### 场景六：MCP Gateway 装配（kb 检索 / 覆盖率脚本等 AI 工具）
+
+npm 包内置 MCP Gateway（`vendor/MCP`）、知识库检索引擎（`vendor/Archive`）与已知问题知识库种子（`vendor/BadCase`）。opencode / deveco-code serve 需要在**全局配置**注册 Gateway 才会在启动时自动 spawn：
+
+```bash
+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 提示一行（不修改任何文件）。
+
+### 场景七：知识回收（把沉淀的知识打包发给维护者）
+
+任务执行会在本机沉淀知识（kb 文档、BadCase 规则、经验索引）。这些知识默认只在你机器上；想贡献给社区/团队，打包发给维护者即可：
+
+```bash
+# 用户侧：打包（纯本地操作，不上传任何数据）
+3rdloop knowledge export                    # → ./3rdloop-knowledge-<日期>-<主机名>.zip
+3rdloop knowledge export --since 2026-09-01 # 只打包该日期后新增的
+3rdloop knowledge export --note "mp3agic 批次"  # 附备注
+
+# 维护者侧：收到 zip 后合入（先预演再落位）
+3rdloop knowledge import <zip> --dry-run    # 预览将新增/冲突的文件
+3rdloop knowledge import <zip>              # 落位到本地 kb-data 与 BadCase
+3rdloop knowledge import <zip> --allow-overwrite  # 覆盖同名文件
+```
+
+包内容：kb 结构化知识文档 + BadCase 规则/案例 + 经验索引清单（仅人工评估参考）。zip 为标准格式（可用系统 unzip 自查内容）；不含检索索引（导入后自动重建）。维护者审核后可把精选内容合入仓库 `Archive/data` 与 `BadCase/`，随 npm 版本分发给所有用户。
+
 更多进阶用法（任务管理、`step` 单步执行、`orch` 自定义编排、工作流注册等），见仓库 `cli/README_DEVELOP.md` 或 `3rdloop <子命令> --help`。
 
 

package/lib/cli.js

@@ -108,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 });
@@ -143,8 +143,14 @@ export async function runCli(argv) {
         case 'config':
             return cmdConfig({ flags, rest, projectRoot, user3libHome, jsonMode, out });
 
+        case 'mcp':
+            return cmdMcpImpl({ rest, user3libHome, jsonMode });
+
+        case 'knowledge':
+            return cmdKnowledgeImpl({ rest, user3libHome, dataDir, jsonMode });
+
         case 'serve':
-            return cmdServe({ flags, rest, jsonMode, dataDir, user3libHome });
+            return cmdServe({ rest, jsonMode, dataDir, user3libHome });
 
         case 'update':
             return cmdUpdate({ flags, rest, jsonMode, out });
@@ -173,9 +179,10 @@ 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;
 }
 
@@ -224,6 +231,26 @@ 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 });
+}
+
+// ─── knowledge（知识打包回收）──────────────────────────────────────
+
+/**
+ * 3rdloop knowledge 命令二段分发（转发到 lib/knowledge.js）。
+ */
+async function cmdKnowledgeImpl({ rest, user3libHome, dataDir, jsonMode }) {
+    const { cmdKnowledge } = await import('./knowledge.js');
+    return cmdKnowledge({ rest, user3libHome, dataDir, jsonMode });
+}
+
 // ─── update（自更新）─────────────────────────────────────────────
 
 async function cmdUpdate({ flags, rest, jsonMode, out }) {
@@ -667,12 +694,18 @@ function printHelp() {
   3rdloop workflows                     列出已注册的固定编排工作流
   3rdloop run <工作流名> [--flag <值> ...]     以固定编排执行工作流（阻塞到终态）
   3rdloop config list|get|set|unset ...  配置 .env 配置项（默认读写 ~/.3lib/.env）
+  3rdloop mcp install [--cli opencode|deveco|all]  装配 MCP Gateway（注册到 AI CLI +
+          种子复制知识库数据/BadCase 到 ~/.3lib/3rdloop/，npm 安装态必需）
+  3rdloop mcp uninstall|status            移除注册 / 查看装配状态
+  3rdloop knowledge export [--since <date>] [--note <text>]
+          打包本地知识（kb 文档 + BadCase）为 zip 发给维护者回收
+  3rdloop knowledge import <zip> [--dry-run]  维护者合入收到的知识包
   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 doctor                        环境自检
+  3rdloop doctor [--no-fix]             环境自检（默认自动装配 MCP Gateway；--no-fix 仅诊断）
   3rdloop version                       版本信息
 
 工作流机制:

package/lib/doctor.js

@@ -63,14 +63,16 @@ async function probeServe(baseUrl) {
 
 /**
  * 收集全部检查项（doctor 与 precheckEnv 共用）。
- * 每项：{ name, passed, detail, fix }——fix 为不通过时的修复提示。
+ * 每项：{ name, passed, detail, fix, warning? }——fix 为不通过时的修复提示；
+ * warning: true 的项仅 doctor 展示提示，不参与 precheckEnv 阻断（MCP 等增强能力缺失不阻断核心引擎）。
  * @param {object} opts
  * @param {string} opts.projectRoot
  * @param {string} opts.skillDir
  * @param {string} opts.dataDir
- * @returns {Promise<Array<{name: string, passed: boolean, detail?: string, fix?: string}>>}
+ * @param {string} [opts.user3libHome] - ~/.3lib（MCP 装配检查用；缺省按 ~ 推导）
+ * @returns {Promise<Array<{name: string, passed: boolean, detail?: string, fix?: string, warning?: boolean}>>}
  */
-async function collectChecks({ projectRoot, skillDir, dataDir }) {
+async function collectChecks({ projectRoot, skillDir, dataDir, user3libHome = '' }) {
     const checks = [];
 
     // 1. Node.js 版本
@@ -161,30 +163,120 @@ async function collectChecks({ projectRoot, skillDir, dataDir }) {
         fix: `端口 ${cliCfg.port} 被异常进程占用，请清理后重试（lsof -i :${cliCfg.port} 定位 / 任务管理器结束进程）`,
     });
 
+    // 8. MCP Gateway 装配（警告级：不阻断核心引擎，仅影响 kb 工具/脚本工具/知识库检索）
+    //    AI CLI 全局配置中 mcp-gateway 已注册且指向存在的入口脚本 → 通过
+    const mcpCheck = await checkMcpRegistration(cliType);
+    checks.push({ warning: true, ...mcpCheck });
+
     return checks;
 }
 
+/**
+ * 检查 MCP Gateway 是否已装配（AI CLI 全局配置注册 + 入口脚本存在）。
+ * 宽容实现：不 import lib/mcp.js 的完整装配（避免 doctor 依赖装配状态本身），
+ * 仅读配置文件判断。
+ */
+async function checkMcpRegistration(cliType) {
+    const home = process.env['HOME'] || process.env['USERPROFILE'] || '';
+    const configRoot = process.env['XDG_CONFIG_HOME'] || path.join(home, '.config');
+    const files = [
+        path.join(configRoot, 'opencode', 'opencode.json'),
+        path.join(configRoot, 'deveco', 'deveco.jsonc'),
+    ];
+    const details = [];
+    let anyRegistered = false;
+    for (const file of files) {
+        const label = path.basename(path.dirname(file));
+        if (!fs.existsSync(file)) {
+            details.push(`${label}: 未注册`);
+            continue;
+        }
+        try {
+            const raw = fs.readFileSync(file, 'utf8');
+            const json = JSON.parse(_stripJsoncComments(raw));
+            const entry = json?.mcp?.['mcp-gateway'];
+            if (!entry) {
+                details.push(`${label}: 未注册`);
+                continue;
+            }
+            // 入口脚本存在性（command 数组第 2 个元素）
+            const entryPath = Array.isArray(entry.command) ? entry.command[1] : null;
+            if (entryPath && fs.existsSync(entryPath)) {
+                details.push(`${label}: 已注册`);
+                anyRegistered = true;
+            } else {
+                details.push(`${label}: 已注册但入口脚本不存在（${entryPath || '未配置'}）`);
+            }
+        } catch {
+            details.push(`${label}: 配置解析失败`);
+        }
+    }
+    return {
+        name: 'MCP Gateway 装配',
+        passed: anyRegistered,
+        detail: details.join('；'),
+        fix: '3rdloop doctor（自动装配）或 3rdloop mcp install（kb 检索/脚本工具/知识库检索需要）',
+    };
+}
+
+/** 剥离 JSONC 注释（// 行注释与 /* 块注释）。 */
+function _stripJsoncComments(raw) {
+    return raw
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/(^|[^:"'\\])\/\/.*$/gm, '$1');
+}
+
 /**
  * 执行环境自检（3rdloop doctor 命令实现）。
  *
+ * 默认自动修复（fix=true）：MCP Gateway 未装配时自动执行装配（等价 3rdloop mcp install，
+ * 幂等可重跑）；--no-fix 仅诊断不修改任何文件。
+ *
  * @param {object} opts
  * @param {string} opts.projectRoot
  * @param {string} opts.skillDir
  * @param {string} opts.dataDir
+ * @param {string} [opts.user3libHome] - ~/.3lib（自动装配目标）
  * @param {boolean} [opts.quiet] - 静默模式（不打印表格，仅返回结果）
+ * @param {boolean} [opts.fix] - 自动修复开关（默认 true）
  * @returns {Promise<{ ok: boolean, checks: Array<{name: string, passed: boolean, detail?: string, fix?: string}> }>}
  */
 export async function runDoctor(opts = {}) {
-    const checks = await collectChecks(opts);
+    const { fix = true } = opts;
+    let checks = await collectChecks(opts);
 
-    // 汇总
-    const ok = checks.every(c => c.passed);
+    // ── 自动修复：MCP Gateway 未装配 → 自动执行装配并复查 ──
+    if (fix) {
+        const mcpIdx = checks.findIndex(c => c.name === 'MCP Gateway 装配' && !c.passed);
+        if (mcpIdx !== -1) {
+            if (!opts.quiet) {
+                process.stderr.write(`\n${C.yellow}检测到 MCP Gateway 未装配，正在自动装配（3rdloop mcp install）...${C.reset}\n`);
+            }
+            try {
+                const { mcpInstall } = await import('./mcp.js');
+                const code = await mcpInstall({ user3libHome: opts.user3libHome || '', rest: [], jsonMode: false });
+                if (code === 0) {
+                    const recheck = await checkMcpRegistration();
+                    checks[mcpIdx] = { warning: true, ...recheck };
+                } else {
+                    checks[mcpIdx].detail += '；自动装配失败，请手动执行 3rdloop mcp install 查看报错';
+                }
+            } catch (err) {
+                checks[mcpIdx].detail += `；自动装配异常: ${err.message}`;
+            }
+        }
+    }
+
+    // 汇总：warning 项不参与通过判定（提示性）
+    const ok = checks.every(c => c.passed || c.warning);
 
-    // 打印（失败项附加修复提示）
+    // 打印（失败项附加修复提示；警告项用 ⚠ 标记）
     if (!opts.quiet) {
         process.stderr.write(`\n${C.bold}3rdloop doctor 环境自检${C.reset}${C.gray}（AI CLI: ${resolveCliType()}）${C.reset}\n`);
         for (const c of checks) {
-            const icon = c.passed ? `${C.green}✓${C.reset}` : `${C.red}✗${C.reset}`;
+            const icon = c.passed
+                ? `${C.green}✓${C.reset}`
+                : (c.warning ? `${C.yellow}⚠${C.reset}` : `${C.red}✗${C.reset}`);
             process.stderr.write(`  ${icon} ${c.name}`);
             if (c.detail) process.stderr.write(`  ${C.gray}${c.detail}${C.reset}`);
             process.stderr.write('\n');
@@ -202,7 +294,9 @@ export async function runDoctor(opts = {}) {
  *
  * 与 doctor 同一检查集，语义差异：
  *   - serve 未运行不算失败（执行命令时会自动拉起；端口异常仍算失败）
- *   - 轻量：仅文件/PATH/端口探测，不拉起任何进程、不触引擎
+ *   - 轻量：仅文件/PATH/端口探测，不拉起任何进程、不触引擎、**不改任何文件**
+ *     （MCP 装配等修复动作只在 3rdloop doctor 中执行，任务命令保持无副作用）
+ *   - MCP 未装配为警告级：不阻断，仅 stderr 提示一行
  *
  * @param {object} opts - { projectRoot, skillDir, dataDir }（与 runDoctor 相同）
  * @returns {Promise<{ ok: boolean, failures: Array<{name: string, detail?: string, fix?: string}> }>}
@@ -210,8 +304,15 @@ export async function runDoctor(opts = {}) {
 export async function precheckEnv(opts = {}) {
     const checks = await collectChecks(opts);
     const failures = checks
-        .filter(c => !c.passed)
+        .filter(c => !c.passed && !c.warning)
         .map(({ name, detail, fix }) => ({ name, detail, fix }));
+
+    // 警告级提示（不阻断）：MCP 未装配时提醒一次
+    const mcpWarn = checks.find(c => c.name === 'MCP Gateway 装配' && !c.passed);
+    if (mcpWarn) {
+        process.stderr.write(`提示: MCP Gateway 未装配（kb 检索/脚本工具不可用），运行 ${C.cyan}3rdloop doctor${C.reset} 可自动装配\n`);
+    }
+
     return { ok: failures.length === 0, failures };
 }