@ohos-cpf/3rdloop 0.0.7 → 0.0.9

package/lib/web.js

@@ -1,5 +1,5 @@
 /**
- * web.js —— 3rdloop web 命令：启动 Web 前端服务
+ * web.js —— Web 前端服务库（由 3rdloop serve 内嵌启动）
  *
  * 架构（方案 A + D 组合）：
  *   - 核心前端资产：仓库 Web/public（开发态）/ cli/web（发布态，prepack 复制）
@@ -15,12 +15,11 @@
  *   3. /api/* 与 /stream*               反向代理到后端 Server（SSE 透传）
  *   4. 其余                             核心前端静态文件
  *
- * 用法：
- *   3rdloop web [--port 8080] [--backend http://127.0.0.1:3000]
- *               [--web-root <dir>] [--ext-root <dir>]... [--open]
- *   3rdloop web install-ext <dir>    安装扩展到 ~/.3lib/3rdloop/web-ext/
- *   3rdloop web list-ext             列出可用扩展（含来源与挂载点）
- *   3rdloop web remove-ext <name>    移除已安装扩展
+ * 本模块不再提供独立 CLI 命令（原 `3rdloop web` 已合并到 `3rdloop serve`，
+ * Web 前端随 serve 默认启动）。对外导出供 serve.js 组合使用：
+ *   startWebServer()                           一站式：解析资产/加载扩展/监听端口
+ *   resolveUserExtRoot()                       用户扩展根目录解析
+ *   webExtInstall / webExtList / webExtRemove  扩展管理子命令
  */
 
 import http from 'node:http';
@@ -39,8 +38,6 @@ import {
 import { EXIT } from './exit-codes.js';
 
 const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const DEFAULT_PORT = 8080;
-const DEFAULT_BACKEND = 'http://127.0.0.1:3000';
 
 // ─── MIME ─────────────────────────────────────────────────────────
 const MIME = {
@@ -68,160 +65,24 @@ const MIME = {
 };
 
 // ═══════════════════════════════════════════════════════════════════
-// 命令入口（由 cli.js 分发）
+// 目录解析
 // ═══════════════════════════════════════════════════════════════════
 
 /**
- * @param {object} opts
- * @param {object} opts.flags - parseGlobalFlags 结果
- * @param {string[]} opts.rest - 剩余参数（含子命令位置参数与 web 专属 flags）
- * @param {string} opts.user3libHome - 用户 3lib 主目录（~/.3lib）
- * @param {string} opts.dataDir - CLI 数据目录
- * @param {boolean} opts.jsonMode
- * @param {Function} opts.out - --json 输出函数
- * @returns {Promise<number>} 退出码
+ * 用户扩展根目录（3LIB_WEB_EXT_ROOT > ~/.3lib/3rdloop/web-ext）。
+ * @param {string} user3libHome - 用户 3lib 主目录（~/.3lib）
  */
-export async function cmdWeb({ flags, user3libHome, dataDir, jsonMode, out }) {
-    // 注意：使用 flags.rest（全局 flags 如 --json/--data-dir 已被 parseGlobalFlags 消费）
-    let argv;
-    try {
-        argv = _parseWebArgs(flags.rest);
-    } catch (err) {
-        process.stderr.write(`${err.message}\n`);
-        _printWebHelp();
-        return EXIT.ERROR;
-    }
-    const userExtRoot = process.env['3LIB_WEB_EXT_ROOT']
+export function resolveUserExtRoot(user3libHome) {
+    return process.env['3LIB_WEB_EXT_ROOT']
         ? path.resolve(process.env['3LIB_WEB_EXT_ROOT'])
         : path.join(user3libHome, '3rdloop', 'web-ext');
-
-    if (argv.help) {
-        _printWebHelp();
-        return EXIT.OK;
-    }
-
-    const positional = argv.positionals;
-
-    // ── 子命令分发 ──
-    if (positional[0] === 'install-ext') {
-        return _cmdInstallExt(positional[1], { userExtRoot, jsonMode, out });
-    }
-    if (positional[0] === 'list-ext') {
-        return _cmdListExt({ userExtRoot, jsonMode, out });
-    }
-    if (positional[0] === 'remove-ext') {
-        return _cmdRemoveExt(positional[1], { userExtRoot, jsonMode, out });
-    }
-    if (positional[0] !== undefined) {
-        process.stderr.write(`未知子命令: ${positional[0]}\n`);
-        _printWebHelp();
-        return EXIT.ERROR;
-    }
-
-    // ── 启动 Web 服务 ──
-    return _startServer({ argv, userExtRoot, dataDir });
-}
-
-// ═══════════════════════════════════════════════════════════════════
-// 参数解析
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * 解析 web 命令专属参数。
- * parseGlobalFlags 已消费全局 flags（--json/--data-dir 等），这里处理剩余部分。
- * 非法参数直接 throw，由 cmdWeb 统一捕获打印帮助。
- */
-function _parseWebArgs(rest) {
-    const opts = {
-        port: DEFAULT_PORT,
-        backend: DEFAULT_BACKEND,
-        webRoot: '',
-        extRoots: [],
-        extNames: [],
-        noExt: false,
-        open: false,
-        help: false,
-        positionals: [],
-    };
-
-    for (let i = 0; i < rest.length; i++) {
-        const arg = rest[i];
-
-        if (arg === '--port') {
-            const raw = rest[++i];
-            const n = parseInt(raw, 10);
-            if (!Number.isFinite(n) || n <= 0 || n > 65535) {
-                throw new Error(`非法端口: "${raw}"`);
-            }
-            opts.port = n;
-        } else if (arg === '--backend') {
-            const raw = rest[++i];
-            if (!raw || !/^https?:\/\//.test(raw)) {
-                throw new Error(`非法后端地址: "${raw}"（须为 http(s):// 开头）`);
-            }
-            opts.backend = raw.replace(/\/+$/, '');
-        } else if (arg === '--web-root') {
-            opts.webRoot = rest[++i] || '';
-        } else if (arg === '--ext-root') {
-            const raw = rest[++i];
-            if (raw) opts.extRoots.push(raw);
-        } else if (arg === '--no-ext') {
-            opts.noExt = true;
-        } else if (arg === '--ext') {
-            // 白名单：逗号分隔 + 可重复指定（--ext tag --ext issue 等效 --ext tag,issue）
-            const raw = rest[++i];
-            if (raw) {
-                for (const n of raw.split(',')) {
-                    const t = n.trim();
-                    if (t) opts.extNames.push(t);
-                }
-            }
-        } else if (arg === '--open') {
-            opts.open = true;
-        } else if (arg === '--help' || arg === '-h') {
-            opts.help = true;
-        } else if (arg.startsWith('--')) {
-            throw new Error(`未知选项: ${arg}（查看帮助: 3rdloop web --help）`);
-        } else {
-            opts.positionals.push(arg);
-        }
-    }
-    return opts;
-}
-
-/**
- * 应用扩展开关过滤：
- *   --no-ext   → 全部禁用（纯后端操作模式：仅核心工作台 + loop + knowledge）
- *   --ext 名称集 → 白名单，仅挂载指定扩展（未发现的名字打 warning）
- * --no-ext 优先于 --ext（同时给出时白名单被忽略）。
- *
- * @param {Array<object>} extensions - loadExtensions 发现的全部扩展
- * @param {object} argv - _parseWebArgs 结果
- * @param {(msg: string) => void} warn
- * @returns {Array<object>} 过滤后的扩展列表
- */
-function _applyExtFilter(extensions, argv, warn) {
-    if (argv.noExt) return [];
-    if (argv.extNames.length === 0) return extensions;
-
-    const known = extensions.map((e) => e.name);
-    for (const name of argv.extNames) {
-        if (!known.includes(name)) {
-            warn(`[web-ext] --ext 指定的扩展 "${name}" 未发现（可用: ${known.join(', ') || '无'}）`);
-        }
-    }
-    return extensions.filter((e) => argv.extNames.includes(e.name));
 }
 
-// ═══════════════════════════════════════════════════════════════════
-// 目录解析
-// ═══════════════════════════════════════════════════════════════════
-
 /**
  * 核心前端资产目录。
  * 优先级：--web-root > 3LIB_WEB_ROOT > 仓库 Web/public（开发态）> cli/web（发布态内置）
  */
-function _resolveWebRoot(flagValue) {
+export function resolveWebRoot(flagValue) {
     if (flagValue) {
         const dir = path.resolve(flagValue);
         if (!fs.existsSync(dir)) throw new Error(`--web-root 目录不存在: ${dir}`);
@@ -249,7 +110,7 @@ function _resolveWebRoot(flagValue) {
  * 扩展根目录列表（优先级从高到低，同名扩展先注册者生效）。
  * 顺序：--ext-root（可多个）> 3LIB_WEB_EXT_ROOT > 仓库 Web/ext（开发态）> 用户扩展目录。
  */
-function _resolveExtRoots(extRootFlags, userExtRoot) {
+export function resolveExtRoots(extRootFlags, userExtRoot) {
     const roots = [];
     const push = (p) => {
         const r = path.resolve(p);
@@ -267,33 +128,80 @@ function _resolveExtRoots(extRootFlags, userExtRoot) {
 }
 
 // ═══════════════════════════════════════════════════════════════════
-// 服务启动
+// 服务启动（由 3rdloop serve 调用）
 // ═══════════════════════════════════════════════════════════════════
 
-async function _startServer({ argv, userExtRoot, dataDir }) {
-    const warn = (msg) => process.stderr.write(`${msg}\n`);
+/**
+ * 应用扩展开关过滤：
+ *   --no-ext   → 全部禁用（纯后端操作模式：仅核心工作台 + loop + knowledge）
+ *   --ext 名称集 → 白名单，仅挂载指定扩展（未发现的名字打 warning）
+ * --no-ext 优先于 --ext（同时给出时白名单被忽略）。
+ *
+ * @param {Array<object>} extensions - loadExtensions 发现的全部扩展
+ * @param {object} opts - { noExt, extNames }
+ * @param {(msg: string) => void} warn
+ * @returns {Array<object>} 过滤后的扩展列表
+ */
+export function applyExtFilter(extensions, { noExt, extNames }, warn) {
+    if (noExt) return [];
+    if (!extNames || extNames.length === 0) return extensions;
 
-    let webRoot;
-    try {
-        webRoot = _resolveWebRoot(argv.webRoot);
-    } catch (err) {
-        process.stderr.write(`[3rdloop web] ${err.message}\n`);
-        return EXIT.ERROR;
+    const known = extensions.map((e) => e.name);
+    for (const name of extNames) {
+        if (!known.includes(name)) {
+            warn(`[web-ext] --ext 指定的扩展 "${name}" 未发现（可用: ${known.join(', ') || '无'}）`);
+        }
     }
+    return extensions.filter((e) => extNames.includes(e.name));
+}
+
+/**
+ * 一站式启动 Web 前端服务：解析前端资产 → 加载扩展 → 创建服务 → 监听端口。
+ * 由 3rdloop serve 内嵌调用（后端反代地址指向同进程的 Server 后端）。
+ *
+ * @param {object} opts
+ * @param {number} opts.port - 监听端口（必填）
+ * @param {string} opts.backend - 后端 Server 地址（必填，如 http://127.0.0.1:3000）
+ * @param {string} [opts.webRootFlag] - --web-root 覆盖
+ * @param {string[]} [opts.extRootFlags] - --ext-root 追加扩展根目录
+ * @param {string} [opts.userExtRoot] - 用户扩展根目录（resolveUserExtRoot 结果）
+ * @param {boolean} [opts.noExt] - 禁用全部扩展
+ * @param {string[]} [opts.extNames] - 白名单扩展名
+ * @param {string} [opts.dataDir] - CLI 数据目录（扩展数据落 <dataDir>/web-ext/<name>）
+ * @param {boolean} [opts.open] - 启动后自动打开浏览器
+ * @param {(msg: string) => void} [opts.log] - 日志函数（默认 stderr；--json 模式传 no-op）
+ * @param {string} [opts.tag] - 日志前缀标签
+ * @returns {Promise<import('node:http').Server>} 已监听的 http.Server（不注册信号处理，生命周期由调用方管理）
+ * @throws 前端资产缺失 / 端口被占用（EADDRINUSE）等启动错误
+ */
+export async function startWebServer({
+    port,
+    backend,
+    webRootFlag = '',
+    extRootFlags = [],
+    userExtRoot = '',
+    noExt = false,
+    extNames = [],
+    dataDir = '',
+    open = false,
+    log = (msg) => process.stderr.write(`${msg}\n`),
+    tag = '3rdloop serve',
+}) {
+    const webRoot = resolveWebRoot(webRootFlag);
 
     // 加载扩展 → 应用 --no-ext / --ext 开关 → 初始化路由
-    const extRoots = _resolveExtRoots(argv.extRoots, userExtRoot);
-    const discovered = loadExtensions(extRoots, warn).extensions;
-    const extensions = _applyExtFilter(discovered, argv, warn);
+    const extRoots = resolveExtRoots(extRootFlags, userExtRoot);
+    const discovered = loadExtensions(extRoots, log).extensions;
+    const extensions = applyExtFilter(discovered, { noExt, extNames }, log);
     for (const ext of extensions) {
-        ext.router = initExtRouter(ext, { cliRoot: CLI_ROOT, dataDir, logger: warn });
+        ext.router = initExtRouter(ext, { cliRoot: CLI_ROOT, dataDir, logger: log });
     }
     const mounted = extensions.filter((e) => e.page || e.router);
 
     const server = http.createServer((req, res) => {
-        _handleRequest(req, res, { webRoot, extensions, backend: argv.backend })
+        _handleRequest(req, res, { webRoot, extensions, backend })
             .catch((err) => {
-                process.stderr.write(`[3rdloop web] 请求处理异常: ${err.message}\n`);
+                log(`[${tag}] 请求处理异常: ${err.message}`);
                 if (!res.headersSent) {
                     res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 }
@@ -303,52 +211,32 @@ async function _startServer({ argv, userExtRoot, dataDir }) {
             });
     });
 
-    return await new Promise((resolve) => {
-        server.on('error', (err) => {
-            if (err.code === 'EADDRINUSE') {
-                process.stderr.write(`[3rdloop web] 端口 ${argv.port} 已被占用（可用 --port 指定其他端口）\n`);
-            } else {
-                process.stderr.write(`[3rdloop web] 服务启动失败: ${err.message}\n`);
-            }
-            resolve(EXIT.ERROR);
-        });
-
-        server.listen(argv.port, () => {
-            process.stderr.write(`[3rdloop web] 前端服务已启动: http://localhost:${argv.port}\n`);
-            process.stderr.write(`[3rdloop web] 前端资产: ${webRoot}\n`);
-            process.stderr.write(`[3rdloop web] 后端代理: ${argv.backend}（/api/*、/stream*）\n`);
-            if (argv.noExt) {
-                process.stderr.write('[3rdloop web] 扩展挂载已禁用（--no-ext）：仅核心工作台 + loop + knowledge\n');
-            } else if (argv.extNames.length > 0) {
-                if (mounted.length > 0) {
-                    const desc = mounted.map((e) => `${e.mount}（${e.title}）`).join('、');
-                    process.stderr.write(`[3rdloop web] 白名单挂载扩展 ${mounted.length}/${discovered.length} 个: ${desc}\n`);
-                } else {
-                    process.stderr.write(`[3rdloop web] 白名单未匹配到任何扩展（发现 ${discovered.length} 个，--ext: ${argv.extNames.join(', ')}）\n`);
-                }
-            } else if (mounted.length > 0) {
-                const desc = mounted.map((e) => `${e.mount}（${e.title}）`).join('、');
-                process.stderr.write(`[3rdloop web] 已挂载扩展 ${mounted.length} 个: ${desc}\n`);
-            } else {
-                process.stderr.write(
-                    '[3rdloop web] 未挂载扩展（tag/issue/prcheck 等二级功能可用 "3rdloop web install-ext <dir>" 启用）\n'
-                );
-            }
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, () => resolve());
+    });
 
-            if (argv.open) _openBrowser(`http://localhost:${argv.port}`);
-        });
+    log(`[${tag}] Web 前端已启动: http://localhost:${port}`);
+    log(`[${tag}] 前端资产: ${webRoot}`);
+    log(`[${tag}] 后端代理: ${backend}（/api/*、/stream*）`);
+    if (noExt) {
+        log(`[${tag}] 扩展挂载已禁用（--no-ext）：仅核心工作台 + loop + knowledge`);
+    } else if (extNames.length > 0) {
+        if (mounted.length > 0) {
+            const desc = mounted.map((e) => `${e.mount}（${e.title}）`).join('、');
+            log(`[${tag}] 白名单挂载扩展 ${mounted.length}/${discovered.length} 个: ${desc}`);
+        } else {
+            log(`[${tag}] 白名单未匹配到任何扩展（发现 ${discovered.length} 个，--ext: ${extNames.join(', ')}）`);
+        }
+    } else if (mounted.length > 0) {
+        const desc = mounted.map((e) => `${e.mount}（${e.title}）`).join('、');
+        log(`[${tag}] 已挂载扩展 ${mounted.length} 个: ${desc}`);
+    } else {
+        log(`[${tag}] 未挂载扩展（tag/issue/prcheck 等二级功能可用 "3rdloop serve install-ext <dir>" 启用）`);
+    }
 
-        // 退出码与 CLI 约定对齐：130 SIGINT / 143 SIGTERM
-        const shutdown = (code) => {
-            process.stderr.write('\n[3rdloop web] 正在关闭…\n');
-            server.close(() => process.exit(code));
-            // 兜底：close 回调被长连接阻塞时强制退出
-            setTimeout(() => process.exit(code), 1500).unref();
-        };
-        process.on('SIGINT', () => shutdown(130));
-        process.on('SIGTERM', () => shutdown(143));
-        // cmdWeb 的 Promise 不 resolve：服务常驻，退出走信号处理
-    });
+    if (open) _openBrowser(`http://localhost:${port}`);
+    return server;
 }
 
 // ═══════════════════════════════════════════════════════════════════
@@ -541,12 +429,12 @@ function _openBrowser(url) {
 }
 
 // ═══════════════════════════════════════════════════════════════════
-// 子命令：install-ext / list-ext / remove-ext
+// 扩展管理子命令（由 3rdloop serve install-ext/list-ext/remove-ext 分发）
 // ═══════════════════════════════════════════════════════════════════
 
-function _cmdInstallExt(srcDir, { userExtRoot, jsonMode, out }) {
+export function webExtInstall(srcDir, { userExtRoot, jsonMode, out }) {
     if (!srcDir) {
-        process.stderr.write('用法: 3rdloop web install-ext <扩展目录>\n');
+        process.stderr.write('用法: 3rdloop serve install-ext <扩展目录>\n');
         return EXIT.ERROR;
     }
     try {
@@ -563,9 +451,9 @@ function _cmdInstallExt(srcDir, { userExtRoot, jsonMode, out }) {
     }
 }
 
-function _cmdListExt({ userExtRoot, jsonMode, out }) {
+export function webExtList({ userExtRoot, jsonMode, out }) {
     const warn = (msg) => process.stderr.write(`${msg}\n`);
-    const extRoots = _resolveExtRoots([], userExtRoot);
+    const extRoots = resolveExtRoots([], userExtRoot);
     const { extensions } = loadExtensions(extRoots, warn);
 
     const items = extensions.map((e) => ({
@@ -586,7 +474,7 @@ function _cmdListExt({ userExtRoot, jsonMode, out }) {
     if (items.length === 0) {
         process.stdout.write('暂无可用扩展。\n');
         process.stdout.write(`扩展目录（可手动放置或用 install-ext 安装）: ${userExtRoot}\n`);
-        process.stdout.write('仓库内置扩展源: <仓库>/Web/ext/，如 3rdloop web install-ext Web/ext/tag\n');
+        process.stdout.write('仓库内置扩展源: <仓库>/Web/ext/，如 3rdloop serve install-ext Web/ext/tag\n');
         return EXIT.OK;
     }
 
@@ -598,9 +486,9 @@ function _cmdListExt({ userExtRoot, jsonMode, out }) {
     return EXIT.OK;
 }
 
-function _cmdRemoveExt(name, { userExtRoot, jsonMode, out }) {
+export function webExtRemove(name, { userExtRoot, jsonMode, out }) {
     if (!name) {
-        process.stderr.write('用法: 3rdloop web remove-ext <扩展名>\n');
+        process.stderr.write('用法: 3rdloop serve remove-ext <扩展名>\n');
         return EXIT.ERROR;
     }
     try {
@@ -616,49 +504,3 @@ function _cmdRemoveExt(name, { userExtRoot, jsonMode, out }) {
         return EXIT.ERROR;
     }
 }
-
-// ═══════════════════════════════════════════════════════════════════
-// 帮助
-// ═══════════════════════════════════════════════════════════════════
-
-function _printWebHelp() {
-    process.stdout.write(`
-3rdloop web —— 启动 Web 前端服务（静态托管 + /api 反代 + 扩展挂载）
-
-用法:
-  3rdloop web [选项]                     启动前端服务
-  3rdloop web install-ext <dir>          安装扩展到 ~/.3lib/3rdloop/web-ext/
-  3rdloop web list-ext                   列出可用扩展（含来源与挂载点）
-  3rdloop web remove-ext <name>          移除已安装扩展
-
-选项:
-  --port <N>          监听端口（默认 8080）
-  --backend <url>     后端 Server 地址（默认 http://127.0.0.1:3000，/api/* 与 /stream* 反代）
-  --web-root <dir>    核心前端资产目录覆盖（默认: 仓库 Web/public，发布包为内置 cli/web）
-  --ext-root <dir>    追加扩展根目录（可多次指定；目录下每个子目录是一个扩展）
-  --ext <name,...>    白名单：仅挂载指定扩展（逗号分隔，可重复指定；未发现的名字打警告）
-  --no-ext            禁用全部扩展（纯后端操作模式；优先于 --ext）
-  --open              启动后自动打开浏览器
-  -h, --help          本帮助
-
-两种典型模式:
-  本地全功能（仓库开发态）:
-      node cli/bin/3rdloop.mjs web
-      = 核心前端（Web/public：PR/仓库检视 + loop + knowledge）+ 全部扩展（Web/ext：tag/issue/prcheck）
-  纯后端操作（经 3rdloop，不受已安装扩展影响）:
-      3rdloop web --no-ext
-      = 仅核心工作台，导航栏不出现 tag/issue/prcheck 等二级功能入口
-
-扩展机制:
-  - 扩展 = 自包含目录（manifest.json + router.cjs + public/），提供 /tag、
-    /issue、/prcheck 等二级目录功能，不随 npm 包分发
-  - 加载来源优先级: --ext-root > 3LIB_WEB_EXT_ROOT > 仓库 Web/ext（开发态）> ~/.3lib/3rdloop/web-ext
-  - 扩展数据目录: <数据目录>/web-ext/<name>（跟随 --data-dir）
-  - 启用示例: 3rdloop web install-ext Web/ext/tag && 3rdloop web
-  - 前端导航栏通过 /api/ext-registry 自动渲染已挂载扩展入口
-
-环境变量:
-  3LIB_WEB_ROOT         核心前端资产目录（等效 --web-root）
-  3LIB_WEB_EXT_ROOT     用户扩展根目录（默认 ~/.3lib/3rdloop/web-ext）
-`);
-}

package/lib/workflow.js

@@ -134,6 +134,17 @@ export async function cmdWorkflow({ wf, wfWords, flags, env }) {
         return EXIT.OK;
     }
 
+    // ── 环境预检（正式执行前快速失败；dry-run 已在上方返回，不预检） ──
+    {
+        const { precheckEnv, reportPrecheckFailures } = await import('./doctor.js');
+        const pre = await precheckEnv({ projectRoot: env.projectRoot, dataDir, skillDir: env.skillDir });
+        if (!pre.ok) {
+            if (jsonMode) out({ ok: false, error: '环境预检未通过', failures: pre.failures });
+            else reportPrecheckFailures(pre.failures);
+            return EXIT.ERROR;
+        }
+    }
+
     // ── 正式执行：复用 orch 链路 ────────────────────────────────────
     // taskId 缺省由 runner 生成（generateTaskId），workflow 可覆盖
     const r = await _runner();
@@ -141,12 +152,11 @@ export async function cmdWorkflow({ wf, wfWords, flags, env }) {
         projectRoot: env.projectRoot,
         dataDir,
         skillDir: env.skillDir,
-        cliType: 'opencode',
         verbose,
     });
 
-    // 挂载 opencode 生命周期
-    const oc = await _ensureOpcodene(ctx, jsonMode, out);
+    // 挂载 AI CLI serve 生命周期（类型由 CLI_TYPE 决定）
+    const oc = await _ensureCliServe(ctx, jsonMode, out);
     if (!oc) return EXIT.ERROR;
 
     // 信号处理：优雅中止（orchControl abort → kill 子进程）
@@ -292,15 +302,15 @@ function _queries() {
     return import('./queries.js');
 }
 
-/** 确保 opencode serve 运行（正式执行需要；dry-run 不需要）。 */
-async function _ensureOpcodene(ctx, jsonMode, out) {
-    const { OpencodeManager } = await import('./opencode.js');
-    const oc = new OpencodeManager({ projectRoot: ctx.projectRoot });
+/** 确保 AI CLI serve 运行（正式执行需要；dry-run 不需要）。 */
+async function _ensureCliServe(ctx, jsonMode, out) {
+    const { CliServeManager } = await import('./opencode.js');
+    const oc = new CliServeManager({ projectRoot: ctx.projectRoot, cliType: ctx.cliType });
     const ocHealth = await oc.ensureRunning();
     if (!ocHealth.ok) {
         if (jsonMode) out({ ok: false, error: ocHealth.message });
         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 null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ohos-cpf/3rdloop",
-    "version": "0.0.7",
+    "version": "0.0.9",
     "description": "3rdLibraryLoop 三方库自动化检视 CLI：嵌入式复用核心引擎，任务生命周期管理（submit/run/wait/progress/abort/list/result/doctor）",
     "type": "module",
     "license": "MIT",
@@ -43,9 +43,13 @@
         "test": "node --test test/*.mjs"
     },
     "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.0",
         "@opencode-ai/sdk": "^1.18.6",
         "better-sqlite3": "^13.0.1",
+        "chokidar": "^4.0.0",
         "dotenv": "^17.0.0",
-        "openai": "^4.0.0"
+        "jieba-wasm": "^2.4.0",
+        "openai": "^4.0.0",
+        "typescript": "^5.5.4"
     }
 }

package/vendor/Archive/data/.index/meta.json

@@ -0,0 +1,7 @@
+{
+  "indexVersion": "1.0.0",
+  "termsHash": "244653ada2b478d99365a03c7b7a50f73bf086d4966ce050d0db91494b883367",
+  "synonymsHash": "692fd79264100cf346359dcf57101ff7699d1e88c460a4ee7cc4c0d7b4e9936a",
+  "segmentCount": 44,
+  "builtAt": 1788338587090
+}

package/vendor/Archive/data/docs/experiences/arkts-check-tool-pitfalls-baseline-comparison.md

@@ -0,0 +1,13 @@
+## arkts_check 独立工具使用坑：相对路径假阴性与环境误报甄别
+
+### 问题现象
+对 PR 新增的 `.ets` 文件以**相对路径**（如 `entry/src/ohosTest/...`）调用独立 arkts_check 工具时返回 "No errors found"，看似零问题；改用**绝对路径**复查同一文件却立即报出多处错误（含真实 `arkts-no-any-unknown` 违规）。另有两类干扰：所有 `@ohos/*` import 均报 "Cannot find module"；批量检查输出中混入大量非目标文件（master 既有文件）的历史存量错误，干扰统计。
+
+### 解决方案
+1. arkts_check 必须使用**绝对路径**调用；必要时用一个"已知有问题的文件"做**阳性对照**，验证工具确实在检查。
+2. `Cannot find module '@ohos/*'` 类错误是独立 linter 无法解析 ohpm 本地依赖（`@ohos/xxx` → `file:../library`）产生的**环境误报**，不计入问题统计。
+3. **基线对照法**：对 master 既有文件跑同样的检查作为基线——既有文件的违规属于历史存量，与本 PR 无关；将 PR 新增文件的报错与基线对比，即可区分"PR 引入"与"历史存量"。
+4. 批量调用 arkts_check 可能实际检查目录内全部文件，需对工具保存的完整输出**按目标文件名 grep 过滤**后再统计；单文件逐个检查更可控。
+
+### 结果
+在 mp3agic PR #53 检视中，通过绝对路径 + 基线对照确认：master 既有测试文件基线为 125+ 错误（大量历史存量 arkts-no-any-unknown），而 PR 新增代码仅 1 处真实违规，显著优于仓库基线。避免了"相对路径假阴性导致漏检"和"环境误报/历史存量导致误判"两类错误结论。

package/vendor/Archive/data/docs/experiences/arkts-deep-path-import-recognition.md

@@ -0,0 +1,31 @@
+# ArkTS 测试代码的深层路径 import 风格与识别方法
+
+### 问题现象
+
+分析 ArkTS（鸿蒙）三方库的测试代码（XTS/Demo）时，测试文件的 import 存在两种风格：
+
+```ts
+// 风格 A：包名导入
+import { EncodedText, ID3v22Tag } from '@ohos/mp3agic'
+// 风格 B：深层路径导入（直接指向库内源文件）
+import { BufferTools } from '@ohos/mp3agic/src/main/ets/components/mp3agic/BufferTools'
+import { MutableInteger } from '@ohos/mp3agic/src/main/ets/components/mp3agic/MutableInteger'
+```
+
+基于 import 匹配的静态分析工具若只匹配包名（`fromLib === libName || fromLib.endsWith('/' + libName.split('/').pop())`），风格 B 不满足任何条件，导致 `importedSymbols` 为空、整个测试文件被静默跳过。mp3agic 案例中一个 803 行、覆盖 28 个静态方法的测试文件被整体漏掉，且无任何告警。
+
+### 解决方案
+
+在包名匹配条件基础上增加深层路径前缀识别：
+
+```js
+// AST 与正则引擎均需同步修改
+if (fromLib !== libName && !fromLib.endsWith('/' + libName.split('/').pop())
+    && !fromLib.startsWith(libName + '/')) continue;
+```
+
+AST 模式下还需在 `resolveModuleNames` 中将深层路径模块说明符映射到库目录下的真实源文件：`'@ohos/pkg/src/main/ets/...'` → `library/src/main/ets/...`（同时做小写键二次查找以兼容大小写差异）。
+
+### 结果
+
+mp3agic 库 XTS 覆盖率分析结果从 8/271（2.95%）修正为 100/271（36.90%），与人工 grep 全量调用盘点逐类一致。结论：任何扫描 ArkTS 测试/示例代码做调用分析的工具，都必须同时兼容包名导入与深层路径导入两种风格，并在 import 均未被识别时输出告警。该修复已合入 `analyze-xts-coverage.cjs`（arkts-library-xts-coverage SKILL v1.1.0）。

package/vendor/Archive/data/docs/experiences/arkts-demo-coverage-entry-file-case-mismatch.md

@@ -0,0 +1,25 @@
+## ArkTS 库入口文件大小写不一致导致覆盖率分析静默低估
+
+### 问题现象
+
+修复 import 尾斜杠问题后，mp3agic Demo 覆盖率仍仅 58.67%（159/271），抽查发现 `Mp3File.getId3v1Tag`（6 处调用）、`Mp3v2CommentFrameData.setLanguage` 等明显漏判。用最小化调试脚本重现 AST Program 后发现 `let mp3file = new Mp3File(...)` 的推断类型是 `any`，且存在 `Cannot find module '@ohos/mp3agic'` 诊断。此缺陷只造成部分漏判而非全 0（共 29 个接口漏判），脚本对"有库 import 但匹配数为 0 的文件"不产生任何警告、退出码仍为 0，极难在常规测试中暴露。
+
+### 解决方案
+
+**根因链**：`extract-interfaces.cjs` 的 `locateEntryFile` 候选路径硬编码 `library/Index.ets`（大写 I）；mp3agic 仓库实际文件是 `library/index.ets`（小写 i）；macOS 文件系统大小写不敏感，`fs.existsSync('Index.ets')` 通过，脚本拿到"看似有效"的错误大小写路径；`matchCoverageAST` 用该路径构造虚拟路径 key（`Index.ts`），而 `fileContents` Map 的 key 来自 `readdirSync` 的真实大小写（`index.ts`），精确匹配失败 → `resolveModuleNames` 解析不到模块 → 库类型全部坍缩为 `any` → 基于类型的调用匹配失效。
+
+**修复方案**（2026-08-27 已落入脚本）：
+1. `locateEntryFile` 返回前用 `fs.readdirSync(path.dirname(entryFile))` 核对文件名真实大小写并回写（toRealCase 辅助函数）
+2. `resolveModuleNames` 解析入口虚拟路径失败时对 `fileContents` keys 做大小写不敏感回退查找
+3. 新增静默失败告警防线：编译诊断出现 `Cannot find module '<库名>'`（TS 错误码 2307）时放弃 AST 结果、降级正则模式；文件有库 import 但匹配数为 0 时输出 ⚠️ 提示；覆盖率 0%/异常低（<10%）时在控制台与报告中输出「分析可信度警告」章节
+
+**可复用诊断方法**：
+- 用调试脚本打印 `checker.typeToString(getTypeAtLocation(varDecl))`，实例变量为 `any` 即模块解析失败
+- 打印 `program.getSemanticDiagnostics()` 检查是否存在 `Cannot find module '<库名>'`
+- 对报告"未覆盖"接口抽样 grep 真实调用数与报告交叉验证
+
+**旧版本脚本应急 workaround**：复制 libroot 到临时目录（排除 .git），把 `library/index.ets` 重命名为 `Index.ets`，用 `--libroot` 指向副本。
+
+### 结果
+
+修复后在 macOS 上直接分析原始仓库（小写入口 + 尾斜杠 import）得到真实覆盖率 69.37%，与"临时副本改名"workaround 结果完全一致。平台差异提醒：入口大小写坑在 macOS（大小写不敏感文件系统）上表现为静默低估，在 Linux（大小写敏感）上表现为 `existsSync` 直接失败走降级逻辑，两者症状不同但同源。快速诊断口诀："部分漏、变量 any → 查入口大小写"。