@ohos-cpf/3rdloop 0.0.8 → 0.0.10

package/lib/mcp.js

@@ -0,0 +1,498 @@
+/**
+ * mcp.js —— 3rdloop mcp：MCP Gateway 一键装配（install / uninstall / status）
+ *
+ * 背景：npm 包内 vendor/ 携带 MCP Gateway（vendor/MCP）、知识库检索引擎
+ * （vendor/Archive）、已知问题知识库种子（vendor/BadCase），但 AI CLI
+ * （opencode / deveco-code）需要在其**全局配置**里注册 mcp-gateway 才会在
+ * serve 启动时 spawn Gateway。本命令完成装配：
+ *
+ *   3rdloop mcp install [--cli opencode|deveco|all] [--force]
+ *     ① 生成用户级 Gateway 配置 ~/.3lib/3rdloop/mcp/config.json
+ *        - scriptsDir / enginePath → 包内（vendor，随包更新获得新脚本/引擎）
+ *        - knowledgeBase.dataDir → ~/.3lib/3rdloop/kb-data（用户数据，跨版本不丢）
+ *     ② 种子复制：kb-data（← vendor/Archive/data）、BadCase 副本
+ *        （← vendor/BadCase，泛化 SKILL 的可写知识库）
+ *     ③ 注册 mcp-gateway 到 ~/.config/opencode/opencode.json 与
+ *        ~/.config/deveco/deveco.jsonc（保留其他字段，幂等可重跑）
+ *
+ *   3rdloop mcp uninstall [--cli ...]   仅移除注册条目（用户数据保留）
+ *   3rdloop mcp status                  查看注册状态与路径
+ *
+ * 设计约束：
+ *   - 仓库开发态（npm link，无 vendor/）自动回退仓库 MCP/、Archive/、BadCase/
+ *   - 用户已有 ~/.3lib/3rdloop/mcp/config.json 时仅刷新路径字段，
+ *     保留 downstreamServers 等用户改动（--force 重置为包内默认）
+ *   - deveco.jsonc 为 JSONC：容错解析（去注释重试），解析失败提示手动配置
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { resolveCliType } from './config.js';
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+export const CLI_ROOT = path.resolve(moduleDir, '..');
+
+/** 注册到 AI CLI 全局配置的条目名（与既有生态约定一致） */
+export const MCP_ENTRY_NAME = 'mcp-gateway';
+
+/** AI CLI 全局配置文件位置（按平台） */
+function aiCliConfigPaths() {
+    const home = process.env['HOME'] || process.env['USERPROFILE'] || '';
+    const configRoot = process.env['XDG_CONFIG_HOME'] || path.join(home, '.config');
+    return {
+        opencode: path.join(configRoot, 'opencode', 'opencode.json'),
+        'deveco-code': path.join(configRoot, 'deveco', 'deveco.jsonc'),
+    };
+}
+
+// ─── 包内资产定位（vendor 优先，仓库开发态回退）────────────────────────
+
+let _assetsCache = null;
+
+/**
+ * 定位 MCP / Archive / BadCase 资产目录。
+ * @returns {{ mcpDir: string, archiveDir: string, badcaseDir: string, mode: 'vendor'|'repo' }}
+ * @throws {Error} vendor 与仓库路径均不存在
+ */
+export function resolveAssets() {
+    if (_assetsCache) return _assetsCache;
+
+    const vendorDir = path.join(CLI_ROOT, 'vendor');
+    const repoRoot = path.resolve(CLI_ROOT, '..');
+
+    const tryDirs = [
+        { root: vendorDir, mode: 'vendor' },
+        { root: repoRoot, mode: 'repo' },
+    ];
+    for (const { root, mode } of tryDirs) {
+        const mcpDir = path.join(root, 'MCP');
+        if (fs.existsSync(path.join(mcpDir, 'src', 'index.js'))) {
+            _assetsCache = {
+                mcpDir,
+                archiveDir: path.join(root, 'Archive'),
+                badcaseDir: path.join(root, 'BadCase'),
+                mode,
+            };
+            return _assetsCache;
+        }
+    }
+    throw new Error(
+        `无法定位 MCP Gateway：期望 cli/vendor/MCP 或仓库 MCP/。` +
+        `npm 安装态请重装包（npm i -g @ohos-cpf/3rdloop），仓库态请在 cli/ 上一级执行`
+    );
+}
+
+// ─── 用户级路径 ────────────────────────────────────────────────────────
+
+/**
+ * 用户级路径集合（kb 数据 / BadCase 副本 / Gateway 配置）。
+ * @param {string} user3libHome - ~/.3lib
+ */
+export function userPaths(user3libHome) {
+    const loopHome = path.join(user3libHome, '3rdloop');
+    return {
+        loopHome,
+        mcpConfigDir: path.join(loopHome, 'mcp'),
+        mcpConfig: path.join(loopHome, 'mcp', 'config.json'),
+        kbDataDir: path.join(loopHome, 'kb-data'),
+        badcaseDir: path.join(loopHome, 'BadCase'),
+    };
+}
+
+// ─── 工具函数 ─────────────────────────────────────────────────────────
+
+/** 递归复制目录（跳过 node_modules）。 */
+function copyDir(src, dst) {
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        const s = path.join(src, entry.name);
+        const d = path.join(dst, entry.name);
+        if (entry.isDirectory()) copyDir(s, d);
+        else fs.copyFileSync(s, d);
+    }
+}
+
+/**
+ * 容错读取 JSON / JSONC 配置（带 // 与 /* 注释剥离重试）。
+ * @returns {{ ok: boolean, data: object|null, raw: string, error?: string }}
+ */
+function readJsonc(file) {
+    let raw = '';
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+        return { ok: false, data: null, raw: '', error: err.message };
+    }
+    try {
+        return { ok: true, data: JSON.parse(raw), raw };
+    } catch { /* 尝试剥注释 */ }
+    const stripped = raw
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/(^|[^:"'\\])\/\/.*$/gm, '$1');
+    try {
+        return { ok: true, data: JSON.parse(stripped), raw };
+    } catch (err) {
+        return { ok: false, data: null, raw, error: `JSONC 解析失败: ${err.message}` };
+    }
+}
+
+/** 合并写入 AI CLI 全局配置的 mcp.mcp-gateway 条目（保留其他字段）。 */
+function upsertMcpEntry(file, entry, { createIfMissing = true } = {}) {
+    const existed = fs.existsSync(file);
+    if (!existed && !createIfMissing) return { ok: true, skipped: true };
+
+    const parsed = existed ? readJsonc(file) : { ok: true, data: {} };
+    if (!parsed.ok) {
+        return { ok: false, error: `${file} ${parsed.error}（可手动编辑，或删除该文件后重跑 3rdloop mcp install）` };
+    }
+    const data = parsed.data || {};
+    if (!data.mcp || typeof data.mcp !== 'object') data.mcp = {};
+    data.mcp[MCP_ENTRY_NAME] = entry;
+
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+    return { ok: true, skipped: false, existed };
+}
+
+/** 从 AI CLI 全局配置移除 mcp.mcp-gateway 条目（文件不存在视为成功）。 */
+function removeMcpEntry(file) {
+    if (!fs.existsSync(file)) return { ok: true, removed: false };
+    const parsed = readJsonc(file);
+    if (!parsed.ok) {
+        return { ok: false, error: `${file} ${parsed.error}（请手动删除其中的 "${MCP_ENTRY_NAME}" 条目）` };
+    }
+    const data = parsed.data || {};
+    let removed = false;
+    if (data.mcp && typeof data.mcp === 'object' && MCP_ENTRY_NAME in data.mcp) {
+        delete data.mcp[MCP_ENTRY_NAME];
+        removed = true;
+        fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+    }
+    return { ok: true, removed };
+}
+
+/** 读取某 AI CLI 配置中 mcp-gateway 的注册状态。 */
+function readMcpEntry(file) {
+    if (!fs.existsSync(file)) return { state: 'missing-file' };
+    const parsed = readJsonc(file);
+    if (!parsed.ok) return { state: 'parse-error', error: parsed.error };
+    const entry = parsed.data?.mcp?.[MCP_ENTRY_NAME];
+    if (!entry) return { state: 'missing-entry' };
+    return { state: 'registered', entry };
+}
+
+// ─── install ──────────────────────────────────────────────────────────
+
+/**
+ * 生成/刷新用户级 Gateway 配置。
+ * 已存在时仅刷新 scriptsDir/enginePath/gateway/scripts 策略（保留 downstreamServers
+ * 与用户自定义 dataDir），force 时以包内 config 为模板重置。
+ */
+function writeUserMcpConfig({ userMcpConfig, templateConfig, assets, kbDataDir, force }) {
+    const existed = fs.existsSync(userMcpConfig);
+    const current = existed ? readJsonc(userMcpConfig) : null;
+    if (existed && !current.ok) {
+        return { ok: false, error: `${userMcpConfig} ${current.error}（可 --force 覆盖或手动修复）` };
+    }
+
+    const tmplKb = templateConfig.knowledgeBase || {};
+    const curKb = (!force && existed && current.data?.knowledgeBase) || null;
+
+    let cfg;
+    if (curKb) {
+        // 刷新模式：以现有用户配置为基底
+        cfg = current.data;
+        cfg.scripts = { ...(templateConfig.scripts || {}), ...(cfg.scripts || {}) };
+        cfg.gateway = cfg.gateway || templateConfig.gateway;
+    } else {
+        // 首次 / --force：以包内模板为基底（深拷贝，含 scripts 策略/downstreamServers）
+        cfg = JSON.parse(JSON.stringify(templateConfig));
+    }
+    if (force) {
+        cfg.downstreamServers = templateConfig.downstreamServers || {};
+        cfg.gateway = templateConfig.gateway || cfg.gateway;
+        cfg.scripts = { ...(templateConfig.scripts || {}) };
+    }
+
+    // dataDir：仅当用户改过（≠ 模板默认相对值）才保留，否则统一指向用户 kb-data
+    const userSetDataDir = curKb && curKb.dataDir && curKb.dataDir !== tmplKb.dataDir
+        ? curKb.dataDir : null;
+    const finalDataDir = userSetDataDir || kbDataDir;
+
+    // 路径字段始终刷新为当前安装位置（包更新后路径不变，幂等无害）
+    cfg.scriptsDir = path.join(assets.mcpDir, 'scripts');
+    cfg.knowledgeBase = {
+        ...tmplKb,
+        ...(curKb || {}),
+        enabled: (curKb?.enabled) ?? tmplKb.enabled ?? true,
+        enginePath: path.join(assets.archiveDir, 'src', 'index.js'),
+        dataDir: finalDataDir,
+    };
+
+    fs.mkdirSync(path.dirname(userMcpConfig), { recursive: true });
+    fs.writeFileSync(userMcpConfig, JSON.stringify(cfg, null, 2) + '\n');
+    return { ok: true, existed, config: cfg };
+}
+
+/**
+ * 3rdloop mcp install 实现。
+ * @param {object} opts
+ * @param {string} opts.user3libHome - ~/.3lib
+ * @param {string[]} opts.rest - 命令参数（--cli / --force）
+ * @param {boolean} opts.jsonMode
+ * @returns {Promise<number>} 退出码
+ */
+export async function mcpInstall({ user3libHome, rest = [], jsonMode = false }) {
+    const cliFilter = _parseCliFilter(rest); // 'all' | 'opencode' | 'deveco-code'
+    const force = rest.includes('--force');
+    const out = (data) => { if (jsonMode) process.stdout.write(JSON.stringify(data, null, 2) + '\n'); };
+    const log = (msg) => process.stderr.write(`${msg}\n`);
+
+    const assets = resolveAssets();
+    const up = userPaths(user3libHome);
+
+    // ① 包内模板 config（downstreamServers / gateway / 脚本策略）
+    const templateFile = path.join(assets.mcpDir, 'config.json');
+    if (!fs.existsSync(templateFile)) {
+        log(`错误: 未找到 Gateway 配置模板: ${templateFile}`);
+        return 1;
+    }
+    const templateConfig = JSON.parse(fs.readFileSync(templateFile, 'utf8'));
+
+    // ② 用户级 Gateway 配置
+    const writeResult = writeUserMcpConfig({
+        userMcpConfig: up.mcpConfig,
+        templateConfig,
+        assets,
+        kbDataDir: up.kbDataDir,
+        force,
+    });
+    if (!writeResult.ok) {
+        log(`错误: ${writeResult.error}`);
+        return 1;
+    }
+
+    // ③ 种子数据（目录已存在则跳过，保用户数据）
+    const seeds = [
+        { src: path.join(assets.archiveDir, 'data'), dst: up.kbDataDir, label: '知识库数据' },
+        { src: assets.badcaseDir, dst: up.badcaseDir, label: 'BadCase 已知问题知识库' },
+    ];
+    const seeded = [];
+    for (const { src, dst, label } of seeds) {
+        if (fs.existsSync(dst)) continue;
+        if (!fs.existsSync(src)) continue; // 仓库缺该资产时跳过（prepack 有警告）
+        copyDir(src, dst);
+        seeded.push({ label, dst });
+    }
+
+    // ④ 注册到 AI CLI 全局配置
+    const entry = {
+        command: ['node', path.join(assets.mcpDir, 'src', 'index.js'), '--config', up.mcpConfig],
+        enabled: true,
+        type: 'local',
+    };
+    const targets = cliFilter === 'all'
+        ? Object.keys(aiCliConfigPaths())
+        : [cliFilter];
+    const registered = [];
+    const failures = [];
+    for (const cliType of targets) {
+        const file = aiCliConfigPaths()[cliType];
+        const res = upsertMcpEntry(file, entry);
+        if (!res.ok) failures.push(res.error);
+        else registered.push({ cliType, file, existed: !!res.existed });
+    }
+    if (failures.length > 0) {
+        for (const f of failures) log(`错误: ${f}`);
+        return 1;
+    }
+
+    if (jsonMode) {
+        out({
+            ok: true,
+            mode: assets.mode,
+            userConfig: up.mcpConfig,
+            kbDataDir: up.kbDataDir,
+            badcaseDir: up.badcaseDir,
+            seeded,
+            registered,
+        });
+    } else {
+        log(`[3rdloop mcp] Gateway 来源: ${assets.mode === 'vendor' ? '包内 vendor/MCP' : '仓库 MCP/'}`);
+        log(`[3rdloop mcp] 用户配置: ${up.mcpConfig}${writeResult.existed && !force ? '（已存在，仅刷新路径）' : ''}`);
+        log(`[3rdloop mcp] 知识库数据目录: ${up.kbDataDir}`);
+        log(`[3rdloop mcp] BadCase 副本: ${up.badcaseDir}`);
+        for (const s of seeded) log(`[3rdloop mcp] 已种子复制 ${s.label} → ${s.dst}`);
+        for (const r of registered) {
+            log(`[3rdloop mcp] 已注册 ${MCP_ENTRY_NAME} → ${r.file}${r.existed ? '（覆盖旧条目）' : ''}`);
+        }
+        log(`[3rdloop mcp] 完成。重启 ${targets.join(' / ')} serve 后 AI 会话即可使用 MCP 工具`);
+    }
+    return 0;
+}
+
+// ─── uninstall / status ───────────────────────────────────────────────
+
+export async function mcpUninstall({ rest = [], jsonMode = false }) {
+    const cliFilter = _parseCliFilter(rest);
+    const out = (data) => { if (jsonMode) process.stdout.write(JSON.stringify(data, null, 2) + '\n'); };
+    const log = (msg) => process.stderr.write(`${msg}\n`);
+
+    const targets = cliFilter === 'all' ? Object.keys(aiCliConfigPaths()) : [cliFilter];
+    const removed = [];
+    const failures = [];
+    for (const cliType of targets) {
+        const file = aiCliConfigPaths()[cliType];
+        const res = removeMcpEntry(file);
+        if (!res.ok) failures.push(res.error);
+        else if (res.removed) removed.push({ cliType, file });
+    }
+    if (failures.length > 0) {
+        for (const f of failures) log(`错误: ${f}`);
+        return 1;
+    }
+    if (jsonMode) out({ ok: true, removed });
+    else if (removed.length === 0) log('[3rdloop mcp] 未发现已注册的条目，无需卸载');
+    else for (const r of removed) log(`[3rdloop mcp] 已移除 ${MCP_ENTRY_NAME} → ${r.file}`);
+    log('[3rdloop mcp] 用户数据（kb-data / BadCase / config）已保留，可随时重新 install');
+    return 0;
+}
+
+export async function mcpStatus({ user3libHome, jsonMode = false }) {
+    const out = (data) => { if (jsonMode) process.stdout.write(JSON.stringify(data, null, 2) + '\n'); };
+    const log = (msg) => process.stderr.write(`${msg}\n`);
+
+    let assets;
+    try {
+        assets = resolveAssets();
+    } catch (err) {
+        if (jsonMode) out({ ok: false, error: err.message });
+        else log(`错误: ${err.message}`);
+        return 1;
+    }
+    const up = userPaths(user3libHome);
+
+    const registrations = {};
+    for (const [cliType, file] of Object.entries(aiCliConfigPaths())) {
+        const st = readMcpEntry(file);
+        registrations[cliType] = { file, state: st.state, entry: st.entry || null };
+    }
+
+    const result = {
+        ok: true,
+        mode: assets.mode,
+        gateway: path.join(assets.mcpDir, 'src', 'index.js'),
+        userConfig: up.mcpConfig,
+        userConfigExists: fs.existsSync(up.mcpConfig),
+        kbDataDir: up.kbDataDir,
+        kbDataSeeded: fs.existsSync(up.kbDataDir),
+        badcaseDir: up.badcaseDir,
+        badcaseSeeded: fs.existsSync(up.badcaseDir),
+        registrations,
+    };
+
+    if (jsonMode) {
+        out(result);
+    } else {
+        log(`Gateway 来源: ${assets.mode === 'vendor' ? '包内 vendor/MCP' : '仓库 MCP/'}（${result.gateway}）`);
+        log(`用户配置: ${up.mcpConfig}${result.userConfigExists ? '' : '（未生成，先 3rdloop mcp install）'}`);
+        log(`知识库数据: ${up.kbDataDir}${result.kbDataSeeded ? '' : '（未初始化）'}`);
+        log(`BadCase 副本: ${up.badcaseDir}${result.badcaseSeeded ? '' : '（未初始化）'}`);
+        for (const [cliType, r] of Object.entries(registrations)) {
+            const icon = r.state === 'registered' ? '✓' : '✗';
+            const detail = r.state === 'registered'
+                ? `已注册 (${r.file})`
+                : r.state === 'missing-file' ? `未注册（配置文件不存在: ${r.file}）`
+                : r.state === 'missing-entry' ? `未注册（${r.file} 无 ${MCP_ENTRY_NAME} 条目）`
+                : `解析失败: ${r.file}`;
+            log(`${icon} ${cliType}: ${detail}`);
+        }
+        const anyRegistered = Object.values(registrations).some(r => r.state === 'registered');
+        if (!anyRegistered) log('提示: 执行 3rdloop mcp install 完成装配');
+    }
+    return 0;
+}
+
+// ─── 命令入口 ─────────────────────────────────────────────────────────
+
+/**
+ * 3rdloop mcp 命令入口（子命令分发）。
+ * @param {object} opts
+ * @param {string[]} opts.rest - flags.rest（含子命令与参数）
+ * @param {string} opts.user3libHome - ~/.3lib
+ * @param {boolean} opts.jsonMode
+ * @returns {Promise<number>} 退出码
+ */
+export async function cmdMcp({ rest = [], user3libHome = '', jsonMode = false }) {
+    if (rest.includes('--help') || rest.includes('-h')) {
+        printMcpHelp();
+        return 0;
+    }
+
+    // 位置子命令 = 第一个非 flag 参数（--cli 的值跳过）
+    let subcommand = null;
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--cli') { i++; continue; }
+        if (rest[i].startsWith('--')) continue;
+        subcommand = rest[i];
+        break;
+    }
+
+    try {
+        if (subcommand === 'install') return await mcpInstall({ user3libHome, rest, jsonMode });
+        if (subcommand === 'uninstall') return await mcpUninstall({ rest, jsonMode });
+        if (subcommand === 'status') return await mcpStatus({ user3libHome, jsonMode });
+        if (subcommand === null && rest.length === 0) {
+            printMcpHelp();
+            return 0;
+        }
+        if (subcommand !== null) {
+            process.stderr.write(`未知子命令: ${subcommand}\n`);
+        } else {
+            process.stderr.write(`未知参数: ${rest.join(' ')}\n`);
+        }
+        printMcpHelp();
+        return 1;
+    } catch (err) {
+        process.stderr.write(`错误: ${err.message}\n`);
+        return 1;
+    }
+}
+
+// ─── 帮助 / 参数 ──────────────────────────────────────────────────────
+
+function _parseCliFilter(rest) {
+    const idx = rest.indexOf('--cli');
+    const raw = idx !== -1 ? rest[idx + 1] : undefined;
+    if (!raw || raw === 'all') return 'all';
+    if (raw === 'opencode') return 'opencode';
+    if (raw === 'deveco' || raw === 'deveco-code') return 'deveco-code';
+    throw new Error(`非法 --cli 值: "${raw}"（可选: opencode | deveco | all）`);
+}
+
+export function printMcpHelp() {
+    process.stdout.write(`3rdloop mcp —— MCP Gateway 装配（npm 安装态必需，仓库开发态可选）
+
+用法:
+  3rdloop mcp install [--cli opencode|deveco|all] [--force]
+      ① 生成用户级 Gateway 配置 ~/.3lib/3rdloop/mcp/config.json
+         （scriptsDir/enginePath 指向包内 vendor，kb 数据落在 ~/.3lib/3rdloop/kb-data）
+      ② 种子复制知识库数据（kb-data）与 BadCase 已知问题知识库到用户目录
+      ③ 注册 mcp-gateway 到 opencode / deveco 全局配置（幂等，可重跑）
+      --force 重置用户级配置为包内默认（downstreamServers 等）
+  3rdloop mcp uninstall [--cli opencode|deveco|all]
+      仅移除注册条目；用户数据（kb-data / BadCase / config）保留
+  3rdloop mcp status
+      查看注册状态、用户配置与数据目录
+
+说明:
+  - opencode/deveco serve 启动时会按全局配置自动 spawn MCP Gateway，
+    AI 会话即可调用 kb 搜索、覆盖率分析脚本等工具
+  - 安装/更新 npm 包后路径不变，注册条目持续有效；包更新后新脚本
+    自动可用（scriptsDir 随包）
+  - 默认注册到 opencode 与 deveco 两处（--cli 可限定）
+`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ohos-cpf/3rdloop",
-    "version": "0.0.8",
+    "version": "0.0.10",
     "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 → 查入口大小写"。

package/vendor/Archive/data/docs/experiences/arkts-demo-coverage-import-trailing-slash.md

@@ -0,0 +1,20 @@
+## ArkTS Demo 覆盖率分析：import 路径尾斜杠导致 0% 误报
+
+### 问题现象
+
+运行 `analyze-demo-coverage.cjs`（AST 模式）分析 mp3agic 库 Demo 覆盖率，首轮输出 `Demo 匹配完成: 0/271 (0.00%)`，但 grep 确认 Demo 明确 import 了库的 18 个类。若不人工核验直接采信首轮结果，会得出"Demo 完全未覆盖库接口"的严重错误结论。任何 Demo 源码使用 `from '@ohos/xxx/'`（尾部带 `/`）写法的鸿蒙库都会触发此类 0% 误报。
+
+### 解决方案
+
+**根因**：脚本 import 匹配判断 `fromLib === libName || fromLib.endsWith('/' + libName.split('/').pop())` 中，`'@ohos/mp3agic/'` 既不等于 `'@ohos/mp3agic'` 也不以 `'/mp3agic'` 结尾（结尾多了 `/`），所有 import 被静默跳过。正则模式 `extractImportsRegex` 与 AST 模式 `extractImportedSymbolsAST` 存在完全相同的判断缺陷；AST 模式 `resolveModuleNames` 中 `moduleName === libName` 同样失配，导致模块解析失败、库类型坍缩为 `any`。
+
+**修复方案**（2026-08-27 已落入 `MCP/scripts/analyze-demo-coverage.cjs` 与 `analyze-xts-coverage.cjs`）：
+1. 对模块说明符先做 `fromLib.replace(/\/+$/, '')` 归一化再比较（正则提取、AST 提取、resolveModuleNames 三处均需修改）
+2. 同时兼容子路径 import：`fromNorm.startsWith(libName + '/')`（如 `@ohos/xxx/src/...`）
+3. 默认导入检测正则追加 `(?:/[^'"]*)?` 容错尾斜杠/子路径
+
+**旧版本脚本应急 workaround**：将 `entry/src/main/ets` 复制到临时目录，sed 去除 import 尾斜杠（mp3agic 案例 59 处），通过脚本已有的 `--src` 参数指向副本。
+
+### 结果
+
+修复后直接分析原始仓库即得真实覆盖率 69.37%（188/271），与人工核验值完全一致，无需任何副本 workaround。核心经验：覆盖率报告出现 0%/异常低值时，先 grep 确认 Demo 是否 import 了库——快速诊断口诀："import 有、覆盖无 → 查尾斜杠"。

package/vendor/Archive/data/docs/experiences/arkts-library-source-files-may-be-ts.md

@@ -0,0 +1,18 @@
+## ArkTS 三方库源码文件可能是 .ts 扩展名——工程结构验证不要以 .ets 数量为唯一判据
+
+### 问题现象
+
+克隆 ArkTS 三方库 mp3agic（gitcode.com/CPF-ApplicationTPC/mp3agic）后，统计 `library/` 目录下 `.ets` 文件数仅得 1 个，一度怀疑源码缺失。且该库入口文件为小写 `index.ets`，与常见的大写 `Index.ets` 约定不一致。
+
+### 解决方案
+
+深入查看后确认：ArkTS 三方库的实现源码不一定是 `.ets` 文件。mp3agic 的 `library/src/main/ets/components/mp3agic/` 下全部 48 个源文件均为 `.ts` 扩展名（如 `Mp3File.ts`、`ID3v2.ts`），`library/` 下仅入口文件 `index.ets` 一个 `.ets` 文件。验证 ArkTS 库工程结构时应确认以下要素（而非统计 `.ets` 文件数）：
+
+- 入口文件（`index.ets` / `Index.ets`，匹配需大小写不敏感）
+- `oh-package.json5`
+- `src/main/module.json5`
+- 源码目录存在（不限扩展名，`.ets` 与 `.ts` 均算）
+
+### 结果
+
+以 `oh-package.json5` / `module.json5` / 入口文件的存在作为工程结构有效性判据是可靠的，源码并未缺失。扫描 ArkTS 库源码时应同时包含 `*.ets` 与 `*.ts`（路径限定在 `src/main/ets/` 下），否则会完全遗漏 `.ts` 实现文件；入口统一从 `index.ets` 解析导出。另注意：macOS 文件系统大小写不敏感，`Index.ets` 字面匹配可偶然命中 `index.ets`，但在 Linux（大小写敏感文件系统）上按字面匹配会漏判，入口文件匹配必须显式做大小写不敏感处理。