@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Agent/SkillSelector/scanner/skillScanner.js

@@ -0,0 +1,382 @@
+/**
+ * skillScanner.js — SKILL 目录扫描器
+ *
+ * 职责：
+ *   扫描给定 SKILL 筛选目录，解析每个子目录下的 SKILL.md frontmatter，
+ *   产出结构化的 SkillMeta[]，供模糊匹配与排序使用。
+ *
+ * 设计原则：
+ *   - 高内聚：所有"目录 → SkillMeta[]"的逻辑集中于此
+ *   - 低耦合：只依赖 node:fs/path，不依赖 LLM、不依赖 Agent
+ *   - 容错：单个 SKILL.md 解析失败不影响其余 SKILL，仅记录并跳过
+ *
+ * SKILL 目录格式（参考 D:\\code\\AIWeb\\Server\\Skills）：
+ *   <skillDirectory>/
+ *     ├── SomeSkill/
+ *     │   ├── SKILL.md          # 必须存在，含 YAML frontmatter
+ *     │   ├── references/        # 可选
+ *     │   └── scripts/          # 可选
+ *     └── AnotherSkill/
+ *         └── SKILL.md
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * 解析 SKILL.md 的 YAML frontmatter（轻量级实现，不引入 yaml 依赖）
+ *
+ * frontmatter 形如：
+ *   ---
+ *   name: cpp-porting-analysis
+ *   description: 对 C++ 开源库进行鸿蒙化可行性分析...
+ *   license: MIT
+ *   metadata:
+ *     author: lalhan
+ *     version: "2.2.0"
+ *     category: harmonyos-porting
+ *     language: C/C++
+ *   compatibility: 适用于任意托管在 Git 仓库的 C/C++ 开源库...
+ *   ---
+ *
+ * @param {string} md - SKILL.md 全文
+ * @returns {object} 解析出的元数据对象
+ */
+export function parseFrontmatter(md) {
+  const result = {};
+  if (!md) return result;
+
+  // 切出首尾 --- 之间的内容（容错：允许 frontmatter 前有 BOM/空白）
+  const fmMatch = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return result;
+
+  const lines = fmMatch[1].split(/\r?\n/);
+  let currentKey = null; // 当前所属的顶层 key（用于二级缩进归入 metadata 等嵌套对象）
+  let block = null; // 块标量收集状态：{ key, indicator, lines, indent }
+
+  for (const line of lines) {
+    // 块标量收集模式：累积缩进比指示符更深的行（含空行），遇到非块内容行则先落地块
+    if (block) {
+      if (_isBlockContentLine(line, block.indent)) {
+        block.lines.push(line);
+        continue;
+      }
+      result[block.key] = parseBlockScalar(block.indicator, block.lines);
+      block = null;
+      currentKey = null;
+    }
+
+    if (!line.trim()) continue;
+
+    // 二级缩进行：归属到上一个顶层 key 的子字段（仅处理 metadata 这类对象）
+    if (/^\s+/.test(line) && currentKey) {
+      const sub = line.trim();
+      const colonIdx = sub.indexOf(':');
+      if (colonIdx > 0) {
+        const k = sub.slice(0, colonIdx).trim();
+        const v = _stripQuotes(sub.slice(colonIdx + 1).trim());
+        if (!result[currentKey] || typeof result[currentKey] !== 'object') {
+          result[currentKey] = {};
+        }
+        result[currentKey][k] = v;
+      }
+      continue;
+    }
+
+    // 顶层 key: value
+    const colonIdx = line.indexOf(':');
+    if (colonIdx <= 0) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const rest = line.slice(colonIdx + 1).trim();
+
+    if (rest === '') {
+      // 形如 "metadata:"，后续缩进行归入此 key
+      currentKey = key;
+      result[currentKey] = {};
+    } else if (/^[|>](?:[-+])?$/.test(rest)) {
+      // 块标量指示符（| / |- / |+ 字面块，> / >- / >+ 折叠块）：
+      // 记录 currentKey 与指示符，后续更深的缩进行累积为该 key 的值
+      currentKey = key;
+      result[key] = '';
+      block = { key, indicator: rest, lines: [], indent: _lineIndent(line) };
+    } else {
+      currentKey = key;
+      result[key] = _stripQuotes(rest);
+    }
+  }
+
+  // 到文件结尾仍未闭合的块标量
+  if (block) {
+    result[block.key] = parseBlockScalar(block.indicator, block.lines);
+  }
+
+  return result;
+}
+
+/**
+ * 解析 YAML 块标量内容（纯函数，便于单测）
+ *
+ * @param {string} indicator - 块标量指示符，如 '|'、'|-'、'|+'、'>'、'>-'、'>+'
+ * @param {string[]} lines - 块内容行（含块内空行，不含指示符行本身）
+ * @returns {string}
+ */
+export function parseBlockScalar(indicator, lines) {
+  const literal = indicator[0] === '|'; // '|' 字面块：保留换行；'>' 折叠块：行间折叠为空
+  // 块为空（无任何内容行）时按 YAML 语义返回空字符串
+  if (!lines.length) return '';
+  // 判断块内是否存在至少一行非空内容；全是空行也按空字符串处理
+  const hasContent = lines.some((l) => l.trim() !== '');
+
+  let out;
+  if (literal) {
+    // 字面块：剔除公共缩进后按行保留 \n（首尾空行剔除）
+    const trimmed = _trimEmptyEdgeLines(lines);
+    const minIndent = _minContentIndent(trimmed);
+    const dedented = trimmed.map((l) => (l.trim() ? l.slice(minIndent) : ''));
+    out = dedented.join('\n');
+  } else {
+    // 折叠块：段内行折叠为空格连接，空行作为段落分隔保留为单个 \n
+    out = '';
+    for (const line of lines) {
+      const text = line.trim();
+      if (!text) {
+        if (out && !out.endsWith('\n')) out += '\n';
+        continue;
+      }
+      if (out && !out.endsWith('\n')) out += ' ';
+      out += text;
+    }
+  }
+
+  if (!hasContent && !out.trim()) return '';
+
+  // chomping：'-' 去除全部尾换行，'+' 保留尾换行，默认 clip 保留单个尾换行
+  const chomping = indicator.slice(1);
+  if (chomping === '-') {
+    out = out.replace(/\n+$/, '');
+  } else if (out && !out.endsWith('\n')) {
+    out += '\n';
+  }
+  return out;
+}
+
+/**
+ * 判断该行是否属于当前块标量的内容行：空行永远属于块；否则缩进必须深于指示符行
+ * @param {string} line
+ * @param {number} blockIndent - 块标量指示符行自身的缩进
+ * @returns {boolean}
+ */
+function _isBlockContentLine(line, blockIndent) {
+  if (!line.trim()) return true; // 空行：段落分隔或尾部空行，均属于块
+  return _lineIndent(line) > blockIndent;
+}
+
+/**
+ * 计算行首空格缩进数（非空格开头视为 0）
+ * @param {string} line
+ * @returns {number}
+ */
+function _lineIndent(line) {
+  const m = line.match(/^ +/);
+  return m ? m[0].length : 0;
+}
+
+/**
+ * 剔除字面块内容的首尾空行（保留中间空行）
+ * @param {string[]} lines
+ * @returns {string[]}
+ */
+function _trimEmptyEdgeLines(lines) {
+  let start = 0;
+  let end = lines.length - 1;
+  while (start <= end && !lines[start].trim()) start++;
+  while (end >= start && !lines[end].trim()) end--;
+  return lines.slice(start, end + 1);
+}
+
+/**
+ * 计算非空内容行的最小缩进（作为字面块的公共缩进基准）
+ * @param {string[]} lines
+ * @returns {number}
+ */
+function _minContentIndent(lines) {
+  let min = Infinity;
+  for (const line of lines) {
+    if (line.trim()) min = Math.min(min, _lineIndent(line));
+  }
+  return min === Infinity ? 0 : min;
+}
+
+/**
+ * 去除值两端的引号（单/双引号）
+ * @param {string} v
+ * @returns {string}
+ */
+function _stripQuotes(v) {
+  if (!v) return v;
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+/**
+ * 判断目录是否为合法 SKILL 目录（含 SKILL.md）
+ * @param {string} dirPath
+ * @returns {Promise<boolean>}
+ */
+async function _isSkillDir(dirPath) {
+  try {
+    const stat = await fs.stat(path.join(dirPath, 'SKILL.md'));
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 扫描 skillDirectory，产出 SkillMeta[]
+ *
+ * @param {string} skillDirectory - SKILL 筛选目录绝对路径
+ * @returns {Promise<import('./types.js').SkillMeta[]>}
+ */
+export async function scanSkills(skillDirectory) {
+  if (!skillDirectory) {
+    throw new Error('skillScanner: skillDirectory 不能为空');
+  }
+
+  // 确保目录存在
+  let entries;
+  try {
+    entries = await fs.readdir(skillDirectory, { withFileTypes: true });
+  } catch (err) {
+    throw new Error(`skillScanner: 无法读取 SKILL 目录 ${skillDirectory}：${err.message}`);
+  }
+
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    // 跳过隐藏目录（如 .git）
+    if (entry.name.startsWith('.')) continue;
+
+    const dirPath = path.join(skillDirectory, entry.name);
+    if (!(await _isSkillDir(dirPath))) continue;
+
+    const skillMdPath = path.join(dirPath, 'SKILL.md');
+    let md;
+    try {
+      md = await fs.readFile(skillMdPath, 'utf-8');
+    } catch (err) {
+      // 读取失败则跳过，不中断整体扫描
+      console.warn(`[skillScanner] 读取 SKILL.md 失败，跳过：${skillMdPath}（${err.message}）`);
+      continue;
+    }
+
+    const fm = parseFrontmatter(md);
+    const meta = _buildSkillMeta(entry.name, dirPath, skillMdPath, fm, md);
+    skills.push(meta);
+  }
+
+  return skills;
+}
+
+/**
+ * 根据 frontmatter + 文件信息构建 SkillMeta
+ * @private
+ */
+function _buildSkillMeta(dirName, dirPath, skillMdPath, fm, md) {
+  const metadata = (fm.metadata && typeof fm.metadata === 'object') ? fm.metadata : {};
+  // 提取 frontmatter 之后的正文，截取前 2500 字符参与模糊匹配
+  const bodyText = md.replace(/^---[\s\S]*?---/, '').trim().slice(0, 2500);
+  // 计算正文长度（frontmatter 之后的内容），用于评估 SKILL 复杂度
+  const bodyLength = md.replace(/^---[\s\S]*?---/, '').length;
+
+  // 触发场景声明：优先取 frontmatter 的 metadata.useWhen，否则从 description 的 "use when/当...时" 段解析
+  const useWhen = metadata.useWhen || _extractUseWhen(fm.description || '');
+
+  return {
+    dirName,
+    skillPath: dirPath,
+    skillMdPath,
+    name: fm.name || dirName,
+    description: fm.description || '',
+    license: fm.license || '',
+    compatibility: fm.compatibility || '',
+    version: metadata.version || '',
+    author: metadata.author || '',
+    category: metadata.category || '',
+    // 兼容两种字段命名：language 或 language-support
+    language: metadata.language || metadata['language-support'] || '',
+    useWhen,
+    // 可搜索文本：metadata×3 权重放大 + 正文前 2500 字符 + useWhen 触发场景
+    searchableText: _buildSearchableText(fm.name, fm.description, metadata, bodyText, useWhen),
+    bodyText,
+    bodyLength,
+    hasReferences: false, // 在 scanSkills 后置检测，见下
+    hasScripts: false,
+  };
+}
+
+/**
+ * 从 description 中解析 "use when..." 触发场景段
+ *
+ * 规范格式（见 skill-generator）：description = {做什么}. Use when {什么时候用}. {关键词}.
+ * 兼容多种写法：
+ *   - "Use when 需要评估...覆盖率。"          → "需要评估...覆盖率"
+ *   - "use when auditing README/API docs..." → "auditing README/API docs"
+ *   - "USE FOR: 鸿蒙三方库接口提取..."         → "鸿蒙三方库接口提取..."
+ * 解析失败（无 use when 段）返回空字符串，不阻塞。
+ *
+ * @param {string} description
+ * @returns {string}
+ * @private
+ */
+function _extractUseWhen(description) {
+  if (!description) return '';
+  // 优先匹配 "use when" / "use for" 之后的内容，取到句子结束（句号/分号/换行）
+  const m = description.match(/(?:use\s+when|use\s+for)\s*[：:，,]?\s*(.+?)(?:[。；;]|$)/i);
+  if (m && m[1]) {
+    return m[1].trim();
+  }
+  // 兼容中文散文式："当...时调用" / "当...时使用"
+  const cn = description.match(/当(.+?)(?:时调用|时使用)/);
+  if (cn && cn[1]) {
+    return cn[1].trim();
+  }
+  return '';
+}
+
+/**
+ * 构建用于模糊匹配的可搜索文本（小写）
+ *
+ * 策略（参考 BearCode 的 BM25 lite）：
+ *   - metadata 字段（name+description+category+language+harmonyos-support+compatibility）
+ *     权重放大 3 倍，确保 frontmatter 匹配占主导
+ *   - 正文前 2500 字符参与索引，覆盖 description 未提及的语义
+ *   - useWhen 触发场景参与索引，让"什么场景下调用"这一语义信号进入召回
+ *
+ * @param {string} name
+ * @param {string} description
+ * @param {object} metadata
+ * @param {string} [bodyText=''] - SKILL.md 正文前 2500 字符
+ * @param {string} [useWhen=''] - 从 frontmatter/description 解析的触发场景
+ * @returns {string} 小写拼接文本
+ * @private
+ */
+function _buildSearchableText(name, description, metadata, bodyText = '', useWhen = '') {
+  const metaParts = [
+    name,
+    description,
+    metadata.category,
+    metadata.language || metadata['language-support'],
+    metadata['harmonyos-support'],
+    metadata.compatibility || '',
+    useWhen,
+  ].filter(Boolean).join(' ');
+
+  // metadata 权重放大 3 倍，正文权重 1 倍
+  const metaWeighted = [metaParts, metaParts, metaParts].join(' ');
+  return (metaWeighted + ' ' + bodyText).toLowerCase();
+}
+
+export default { scanSkills, parseFrontmatter };

package/vendor/Server/Agent/SkillSelector/types.js

@@ -0,0 +1,63 @@
+/**
+ * types.js — SkillSelector 模块的类型契约（JSDoc 参考，不参与运行时）
+ *
+ * 本文件仅用于集中声明数据结构，便于 IDE 提示与维护者阅读。
+ * JS 中没有运行时类型，这里用 JSDoc @typedef 描述。
+ */
+
+/**
+ * @typedef {Object} SkillMeta
+ * @property {string} dirName        - SKILL 目录名（唯一标识，如 'CPPAnalysisSkill'）
+ * @property {string} skillPath      - 该 SKILL 目录绝对路径
+ * @property {string} skillMdPath    - SKILL.md 绝对路径
+ * @property {string} name           - frontmatter.name
+ * @property {string} description    - frontmatter.description（匹配核心字段）
+ * @property {string} license         - frontmatter.license
+ * @property {string} compatibility  - frontmatter.compatibility
+ * @property {string} version         - metadata.version
+ * @property {string} author          - metadata.author
+ * @property {string} category        - metadata.category
+ * @property {string} language        - metadata.language 或 metadata['language-support']
+ * @property {string} searchableText  - name+description+category+language 拼成的小写串
+ * @property {number} bodyLength       - SKILL.md 正文长度（frontmatter 之后）
+ * @property {boolean} hasReferences  - 是否有 references/ 子目录
+ * @property {boolean} hasScripts      - 是否有 scripts/ 子目录
+ */
+
+/**
+ * @typedef {Object} TaskAnalysis
+ * @property {string} intent        - 任务意图一句话
+ * @property {string[]} keywords    - 匹配关键词
+ * @property {string[]} constraints - 任务约束
+ * @property {string[]} techStack   - 技术栈/语言
+ */
+
+/**
+ * @typedef {Object} SkillDimensions
+ * @property {number} intent     - 意图契合度分（满分 40）
+ * @property {number} techStack  - 技术栈匹配分（满分 30）
+ * @property {number} constraint - 约束满足度分（满分 20）
+ * @property {number} keyword    - 关键词命中分（满分 10）
+ */
+
+/**
+ * @typedef {Object} RankedSkill
+ * @property {string} id         - SKILL 的 dirName
+ * @property {number} score      - 0-100 总分（= dimensions 各项之和）
+ * @property {SkillDimensions} dimensions - 分维度分数（容错：缺失时为空对象）
+ * @property {string} reason     - 一句话理由
+ */
+
+/**
+ * @typedef {Object} SkillSelection
+ * @property {SkillMeta|null} best          - 最佳 SKILL（未命中阈值/分差过小时为 null）
+ * @property {string|null} skillPath        - best 的绝对目录路径（未命中为 null）
+ * @property {boolean} hit                   - 检索是否命中（top1>=阈值 且 top1-top2 分差>=10）
+ * @property {number} topScore               - top1 分数（未召回为 0）
+ * @property {number} scoreGap               - top1-top2 分差（<10 时判定不确定，hit=false）
+ * @property {Array<{skill: SkillMeta, score: number, dimensions: SkillDimensions, reason: string}>} ranked - 排序结果
+ * @property {TaskAnalysis} analysis        - 任务拆解
+ * @property {Array<object>} trace          - ReAct 每步留痕
+ */
+
+export {};

package/vendor/Server/Agent/SkillSelector/utils/actionWords.js

@@ -0,0 +1,60 @@
+/**
+ * actionWords.js — 动作类型词与领域/产出物词分离管理
+ *
+ * 设计原则：
+ *   - ACTION_WORDS 只保留真正的"动作/意图"词（动词类），决定匹配哪个动作型 SKILL
+ *     （如"准出审核/验收测试"→ acceptance-check SKILL）。
+ *   - DOMAIN_WORDS 是"领域/产出物特征词"（语义上不是动作，如"接口规格/覆盖率/XTS"），
+ *     由领域通道用于召回时匹配 SKILL 的 useWhen / searchableText，不参与动作加权。
+ *   - 历史教训：曾把"接口规格/接口签名/方法签名/方法级接口/导出链"等语义非动作词
+ *     混入 ACTION_WORDS，靠 BM25 加权拉分，属于"该场景未命中后逐条打补丁"的治标方式，
+ *     反而稀释了真正的动作信号。现改为动作/领域双通道各自独立承载。
+ *
+ * 该词表与 llm/prompts.js 的 TASK_ANALYSIS_PROMPT 保持一致，
+ * 确保 LLM 产出的关键词能被 isActionWord / isDomainWord 识别。
+ */
+export const ACTION_WORDS = [
+  '准出审核', '验收测试', '验收检查', '验收', '审核',
+  '可行性分析', '可行性', '分析',
+  '代码生成', '生成',
+  '文档生成', '编写',
+  '迁移移植', '移植', '迁移',
+  '扫描检视', '检视', '扫描', '检查',
+  '聚合汇总', '汇总', '聚合',
+  '执行检视', '执行',
+  '代码修复', '修复', '纠错', '修正', '调试',
+  '版本分析','差异生成'
+];
+
+// 领域/产出物特征词（非动作，不参与动作加权，供领域通道匹配用）
+export const DOMAIN_WORDS = [
+  '接口规格', '接口签名', '方法签名', '方法级接口', '导出链',
+  '覆盖率', '覆盖', 'xts', 'demo',
+  '鸿蒙', '鸿蒙化', 'arkts', 'typescript',
+  '报告', '文档', '代码', '测试',
+];
+
+// 动作词权重（BM25 打分时放大倍数）
+export const ACTION_WORD_WEIGHT = 3;
+
+/**
+ * 判断一个 token 是否为动作词（子串包含匹配，容忍"验收测试/验收检查"等变体）
+ * @param {string} token - 小写待判 token
+ * @returns {boolean}
+ */
+export function isActionWord(token) {
+  if (!token) return false;
+  return ACTION_WORDS.some((w) => token.includes(w));
+}
+
+/**
+ * 判断一个 token 是否为领域/产出物特征词（子串包含匹配）
+ * @param {string} token - 小写待判 token
+ * @returns {boolean}
+ */
+export function isDomainWord(token) {
+  if (!token) return false;
+  return DOMAIN_WORDS.some((w) => token.includes(w));
+}
+
+export default { ACTION_WORDS, DOMAIN_WORDS, ACTION_WORD_WEIGHT, isActionWord, isDomainWord };