skillhelper 0.4.2

package/packages/scanner/src/adapters/skill-adapter.mjs

@@ -0,0 +1,345 @@
+// skill-adapter.mjs — adapter for scanning generic SKILL.md files from other sources
+// Unlike markdown-skill.mjs which targets specific tools (hermes, claude-code),
+// this adapter provides a generic way to scan SKILL.md files from any source
+// and returns a standardized format with frontmatter parsing.
+
+import path from 'node:path';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fg from 'fast-glob';
+import {
+  expandRoots,
+  classifyRoot,
+  parseFrontmatter,
+  inferBrand,
+  inferProduct,
+  deriveDescription,
+  makePreview,
+  sha1Id,
+} from '../utils.mjs';
+
+const execFileP = promisify(execFile);
+
+/** Default concurrency for file reads — bounded by CPU count (R7.2). */
+const DEFAULT_CONCURRENCY = Math.max(4, Math.min(16, (os.cpus()?.length || 4)));
+
+/**
+ * Run an async mapper over items with a bounded concurrency pool.
+ * Keeps the event loop responsive and caps open file handles during scans.
+ * @template T,R
+ * @param {T[]} items
+ * @param {number} concurrency
+ * @param {(item: T, index: number) => Promise<R>} fn
+ * @returns {Promise<R[]>}
+ */
+async function mapWithConcurrency(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  const workers = new Array(Math.min(concurrency, items.length || 1)).fill(0).map(async () => {
+    while (cursor < items.length) {
+      const i = cursor++;
+      results[i] = await fn(items[i], i);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Scan SKILL.md files from arbitrary locations/sources
+ * @param {object} opts
+ * @param {string} opts.source              — IR source tag (e.g., 'other-skills', 'custom-skills')
+ * @param {string[]} opts.roots              — base dirs to scan (with ~ / globs)
+ * @param {string} [opts.fileGlob='SKILL.md'] — relative glob pattern
+ * @param {object} [opts.limits]             — { maxFiles, maxFileBytes }
+ * @param {'mini'|'full'} [opts.stage='full'] — 'mini' skips heavy fields for fast first paint (R7.1)
+ * @param {number} [opts.concurrency]        — parallel file reads (R7.2)
+ * @param {boolean} [opts.useSpotlight=false] — use `mdls` for timestamps (R7.3)
+ * @returns {Promise<{items:SkillItem[], stats:object}>}
+ */
+export async function scanSkills(opts) {
+  const {
+    source = 'other-skills',
+    roots = [],
+    fileGlob = '**/SKILL.md',
+    limits = { maxFiles: 5000, maxFileBytes: 1024 * 1024 },
+    stage = 'full',
+    concurrency = DEFAULT_CONCURRENCY,
+    useSpotlight = false,
+  } = opts;
+
+  const startedAt = Date.now();
+  const expanded = await expandRoots(roots);
+  if (!expanded.length) {
+    return { items: [], stats: { source, available: false, files: 0, stage } };
+  }
+
+  // Collect file paths
+  const files = [];
+  for (const root of expanded) {
+    const found = await fg(fileGlob, {
+      cwd: root,
+      absolute: true,
+      onlyFiles: true,
+      dot: true,
+      followSymbolicLinks: true,
+      deep: 10,
+      ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
+    });
+    for (const f of found) {
+      files.push({ abs: f, root });
+      if (files.length >= limits.maxFiles) break;
+    }
+    if (files.length >= limits.maxFiles) break;
+  }
+
+  // Optional Spotlight timestamps (R7.3) — batched, best-effort.
+  const spotlightDates = useSpotlight ? await fetchSpotlightDates(files.map(f => f.abs)) : null;
+
+  // Parse each file concurrently (R7.2)
+  const items = await mapWithConcurrency(files, concurrency, ({ abs, root }) =>
+    parseSkillFile({ abs, root, source, limits, stage, spotlightDates }),
+  );
+
+  // Stable ordering by path (R3) — concurrency must not change output order.
+  items.sort((a, b) => (a.paths?.abs || '').localeCompare(b.paths?.abs || ''));
+
+  return {
+    items,
+    stats: {
+      source,
+      available: true,
+      files: items.length,
+      roots: expanded,
+      stage,
+      duration: Date.now() - startedAt,
+    },
+  };
+}
+
+/**
+ * Best-effort batched Spotlight timestamps via `mdls` (R7.3, opt-in).
+ * Returns a Map<abs, {creationDate?, contentChangeDate?}> or null on failure.
+ * @param {string[]} paths
+ * @returns {Promise<Map<string, {creationDate?: string, contentChangeDate?: string}>|null>}
+ */
+async function fetchSpotlightDates(paths) {
+  if (process.platform !== 'darwin' || !paths.length) return null;
+  const map = new Map();
+  const CHUNK = 50;
+  try {
+    for (let i = 0; i < paths.length; i += CHUNK) {
+      const chunk = paths.slice(i, i + CHUNK);
+      const { stdout } = await execFileP('mdls', [
+        '-name', 'kMDItemFSCreationDate',
+        '-name', 'kMDItemFSContentChangeDate',
+        '-raw',
+        ...chunk,
+      ]);
+      // -raw emits values separated by NUL, in order: [creation, change] per file.
+      const values = stdout.split('\0');
+      for (let j = 0; j < chunk.length; j++) {
+        const creation = values[j * 2];
+        const change = values[j * 2 + 1];
+        const entry = {};
+        if (creation && creation !== '(null)') entry.creationDate = toIso(creation);
+        if (change && change !== '(null)') entry.contentChangeDate = toIso(change);
+        if (entry.creationDate || entry.contentChangeDate) map.set(chunk[j], entry);
+      }
+    }
+    return map;
+  } catch {
+    return null;
+  }
+}
+
+function toIso(mdlsDate) {
+  // mdls raw date looks like "2026-07-01 10:30:00 +0000"
+  const d = new Date(mdlsDate.replace(' +', '+').replace(/ (\d{4})$/, ' +$1'));
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+}
+
+/**
+ * Read a file safely with async I/O + byte limit (R7.2).
+ * @returns {Promise<{text:string, truncated:boolean, mtime:Date, error?:string}>}
+ */
+async function readFileSafeAsync(abs, maxBytes) {
+  try {
+    const stat = await fsp.stat(abs);
+    if (stat.size > maxBytes) {
+      return { text: '', truncated: true, mtime: stat.mtime };
+    }
+    return { text: await fsp.readFile(abs, 'utf8'), truncated: false, mtime: stat.mtime };
+  } catch (e) {
+    return { text: '', truncated: false, mtime: new Date(0), error: e.message };
+  }
+}
+
+/**
+ * Parse a single SKILL.md file
+ * @param {object} opts
+ * @param {string} opts.abs     — absolute path to the SKILL.md file
+ * @param {string} opts.root    — root directory for relative path calculation
+ * @param {string} opts.source  — source identifier
+ * @param {object} opts.limits  — { maxFileBytes }
+ * @param {'mini'|'full'} opts.stage — 'mini' skips heavy fields (R7.1)
+ * @param {Map|null} opts.spotlightDates — optional Spotlight timestamps (R7.3)
+ * @returns {Promise<SkillItem>}
+ */
+async function parseSkillFile({ abs, root, source, limits, stage = 'full', spotlightDates = null }) {
+  const { text, truncated, mtime, error } = await readFileSafeAsync(abs, limits.maxFileBytes);
+  const id = sha1Id(abs);
+  const rel = path.relative(root, abs);
+
+  // Extract category from directory structure
+  const relDir = path.dirname(rel);
+  const category = relDir && relDir !== '.' ? relDir.split('/')[0] : undefined;
+
+  // Extract skill name from parent directory
+  const dirName = path.basename(path.dirname(abs));
+
+  const updatedAt =
+    spotlightDates?.get(abs)?.contentChangeDate || new Date(mtime).toISOString();
+
+  // Handle file read errors
+  if (error) {
+    return createBaseItem({ abs, id, source, dirName, category, updatedAt, raw: '', parseError: error });
+  }
+
+  // Handle truncated files
+  if (truncated) {
+    return createBaseItem({
+      abs,
+      id,
+      source,
+      dirName,
+      category,
+      updatedAt,
+      raw: '',
+      parseError: `file > ${limits.maxFileBytes} bytes, skipped`,
+    });
+  }
+
+  // Parse frontmatter
+  const { data: fm, body, i18n, parseError } = parseFrontmatter(text);
+
+  const name = (fm.name || dirName).toString().trim();
+  const title = (fm.title || fm.name || dirName).toString().trim();
+  const description = deriveDescription(fm, body);
+
+  // Explicit icon override from frontmatter (e.g. "emoji:🤖", "url:...", "app:bundleId")
+  const icon = typeof fm.icon === 'string' ? fm.icon.trim() : undefined;
+
+  // Build the item — 'mini' stage omits heavy fields for a fast first paint (R7.1).
+  const item = {
+    id,
+    kind: 'skill',
+    source,
+    editor: 'Other Skills',
+    name,
+    title: title !== name ? title : undefined,
+    description,
+    category,
+    icon,
+    paths: {
+      abs,
+      rel,
+      rootKind: classifyRoot(abs),
+    },
+    updatedAt,
+  };
+
+  // Infer brand (needed by both stages for icon resolution)
+  item.brand = inferBrand({ name, description, category, raw: stage === 'mini' ? description : body });
+
+  if (stage !== 'mini') {
+    const triggers = collectTriggers(fm);
+    const tags = collectTags(fm);
+    const links = collectLinks(fm);
+    item.triggers = triggers.length ? triggers : undefined;
+    item.tags = tags.length ? tags : undefined;
+    item.preview = makePreview(body);
+    item.raw = text;
+    item.links = links.length ? links : undefined;
+    item.product = inferProduct({ name, category });
+
+    if (i18n) {
+      item.i18n = {
+        ...i18n,
+        translatedAt: new Date().toISOString(),
+        translationModel: 'frontmatter',
+      };
+    }
+  }
+
+  if (parseError) item.parseError = parseError;
+  return item;
+}
+
+/**
+ * Create a minimal skill item for error cases
+ */
+function createBaseItem({ abs, id, source, dirName, category, updatedAt, raw, parseError }) {
+  return {
+    id,
+    kind: 'skill',
+    source,
+    editor: 'Other Skills',
+    name: dirName,
+    description: undefined,
+    category,
+    paths: { abs, rootKind: classifyRoot(abs) },
+    preview: '',
+    raw,
+    updatedAt,
+    parseError,
+  };
+}
+
+/**
+ * Collect trigger strings from frontmatter
+ */
+function collectTriggers(fm) {
+  const out = [];
+  const candidates = [fm.triggers, fm.aliases, fm.when_to_use];
+  for (const c of candidates) {
+    if (!c) continue;
+    if (Array.isArray(c)) {
+      out.push(...c.filter(x => typeof x === 'string').map(x => x.trim()));
+    } else if (typeof c === 'string') {
+      out.push(c.trim());
+    }
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * Collect tags from frontmatter
+ */
+function collectTags(fm) {
+  const v = fm.tags;
+  if (!v) return [];
+  if (Array.isArray(v)) return v.filter(x => typeof x === 'string');
+  if (typeof v === 'string') return v.split(',').map(s => s.trim()).filter(Boolean);
+  return [];
+}
+
+/**
+ * Collect links from frontmatter
+ */
+function collectLinks(fm) {
+  const out = [];
+  if (Array.isArray(fm.links)) {
+    for (const l of fm.links) {
+      if (l && typeof l === 'object' && l.url) {
+        out.push({ label: l.label || l.url, url: l.url });
+      }
+    }
+  }
+  if (typeof fm.url === 'string') {
+    out.push({ label: 'docs', url: fm.url });
+  }
+  return out;
+}

package/packages/scanner/src/adapters/tier1-editor-skills.mjs

@@ -0,0 +1,278 @@
+/**
+ * @file tier1-editor-skills.mjs
+ * 扫描第1层：编辑器工具的全局和项目技能目录
+ * 支持 22 个编辑器，大小写不敏感的 skills 目录
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import fg from 'fast-glob';
+import { expandTilde, readFileSafe, parseFrontmatter, sha1Id } from '../utils.mjs';
+import { EDITOR_TIER_1_CONFIGS } from '../config/editor-tiers.mjs';
+import { getPathHash, pathHashCache } from '../hash/path-hash.mjs';
+import { ensureRegistered, getDescriptor } from '../core/registry.mjs';
+import { computeConfidence } from '../core/descriptor.mjs';
+
+/**
+ * 扫描第1层：编辑器工具的全局和项目技能目录
+ *
+ * @param {Object} options
+ * @param {string} [options.projectRoot] - 项目根目录（用于扫描 .hermes/skills 等）
+ * @param {Object} [options.limits] - { maxFiles, maxFileBytes }
+ * @returns {Promise<{items: SkillItem[], pathHashes: Set<string>}>}
+ */
+export async function scanTier1EditorSkills(options = {}) {
+  const { projectRoot, limits = {} } = options;
+  const mergedLimits = {
+    maxFiles: limits.maxFiles ?? 5000,
+    maxFileBytes: limits.maxFileBytes ?? 1024 * 1024,
+  };
+
+  // 确保 descriptor registry 已初始化（渐进迁移：registry 与现有配置并存）
+  ensureRegistered();
+
+  const items = [];
+  const pathHashes = new Set();
+  let fileCount = 0;
+
+  for (const editor of EDITOR_TIER_1_CONFIGS) {
+    if (fileCount >= mergedLimits.maxFiles) break;
+
+    const desc = getDescriptor(`tier1:${editor.brand}`);
+
+    // 尝试全局路径
+    const globalPath = expandTilde(editor.globalPath);
+    const globalResult = await scanEditorDirectory(
+      globalPath,
+      editor,
+      desc,
+      mergedLimits,
+      mergedLimits.maxFiles - fileCount
+    );
+    items.push(...globalResult.items);
+    fileCount += globalResult.items.length;
+    globalResult.items.forEach(item => {
+      const hash = pathHashCache.getOrCompute(item.paths.abs);
+      pathHashes.add(hash);
+      item.pathHash = hash;
+    });
+
+    if (fileCount >= mergedLimits.maxFiles) break;
+
+    // 尝试项目路径
+    if (projectRoot) {
+      const projectPath = path.join(projectRoot, editor.projectPath);
+      const projectResult = await scanEditorDirectory(
+        projectPath,
+        editor,
+        desc,
+        mergedLimits,
+        mergedLimits.maxFiles - fileCount
+      );
+      items.push(...projectResult.items);
+      fileCount += projectResult.items.length;
+      projectResult.items.forEach(item => {
+        const hash = pathHashCache.getOrCompute(item.paths.abs);
+        pathHashes.add(hash);
+        item.pathHash = hash;
+      });
+    }
+  }
+
+  return { items, pathHashes };
+}
+
+/**
+ * 扫描单个编辑器目录
+ * 支持大小写不敏感的 skills 目录名和 SKILL.md / skill.md 文件
+ * glob 模式 / ignore / deep 从 descriptor 读取（registry 化），desc 为 null 时回退原值
+ *
+ * @private
+ */
+async function scanEditorDirectory(basePath, editor, desc, limits, maxRemaining) {
+  const items = [];
+
+  // 从 descriptor 读检测规则，回退到原硬编码值（渐进迁移期防御）
+  const relPatterns = desc?.detect?.globPatterns || [
+    `**/[sS][kK][iI][lL][lL][sS]/**/[sS][kK][iI][lL][lL].[mM][dD]`,
+    `**/SKILL.md`,
+    `**/skill.md`,
+  ];
+  const ignore = desc?.detect?.ignore || ['**/node_modules/**', '**/.git/**', '**/dist/**'];
+  const deep = desc?.detect?.deep ?? 10;
+
+  // 置信度统计
+  const dirExists = safeDirExists(basePath);
+  let matchedFiles = 0;
+  let parsedValid = 0;
+  let metadataComplete = 0;
+
+  try {
+    const patterns = relPatterns.map(p => `${basePath}/${p}`);
+
+    for (const pattern of patterns) {
+      if (items.length >= maxRemaining) break;
+
+      try {
+        const matches = await fg(pattern, {
+          absolute: true,
+          onlyFiles: true,
+          dot: true,
+          followSymbolicLinks: true,
+          deep,
+          ignore,
+        });
+
+        const seen = new Set(items.map(i => i.paths.abs));
+
+        for (const filePath of matches) {
+          if (items.length >= maxRemaining || seen.has(filePath)) continue;
+          seen.add(filePath);
+          matchedFiles++;
+
+          try {
+            const skill = parseSkillFile({
+              abs: filePath,
+              source: 'tier1-editor',
+              editor,
+              limits,
+            });
+            if (skill) {
+              skill.tierId = 'tier-1';
+              skill.editorBrand = editor.brand;
+              // 置信度统计：L3 解析有效（name 非空），L4 元数据完整（name+description）
+              if (skill.name) parsedValid++;
+              if (skill.name && skill.description) metadataComplete++;
+              items.push(skill);
+            }
+          } catch (e) {
+            console.warn(`[scanTier1] parse failed: ${filePath}`, e.message);
+          }
+        }
+      } catch (e) {
+        // glob 模式失败，继续下一个
+      }
+    }
+  } catch (e) {
+    // 目录不存在或其他错误，静默跳过
+
+  }
+
+  // 计算置信度并注入到每个 skill（可选字段，向后兼容）
+  const confidence = computeConfidence({ dirExists, matchedFiles, parsedValid, metadataComplete });
+  if (confidence) {
+    for (const item of items) item.confidence = confidence;
+  }
+
+  return { items, confidence };
+}
+
+function safeDirExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 解析单个技能文件
+ * @private
+ */
+function parseSkillFile({ abs, source, editor, limits }) {
+  const { text, error } = readFileSafe(abs, limits.maxFileBytes);
+  if (error) return null;
+
+  const id = sha1Id(abs);
+  const dirName = path.basename(path.dirname(abs));
+
+  let frontmatter = {};
+  let body = text;
+  let parseError = null;
+
+  // 简单的 frontmatter 解析
+  if (text.startsWith('---\n')) {
+    const endIdx = text.indexOf('\n---\n', 4);
+    if (endIdx > 0) {
+      const fm = text.slice(4, endIdx);
+      try {
+        frontmatter = parseYAML(fm);
+        body = text.slice(endIdx + 5);
+      } catch (e) {
+        parseError = `Frontmatter parse error: ${e.message}`;
+      }
+    }
+  }
+
+  const name = frontmatter.name || dirName;
+  const description = frontmatter.description || '';
+  const category = frontmatter.category;
+  const brand = frontmatter.brand || editor.brand;
+
+  return {
+    id,
+    kind: 'skill',
+    source,
+    name,
+    description,
+    category,
+    brand,
+    editor: editor.name,
+    paths: {
+      abs,
+      rootKind: 'home',
+    },
+    preview: makePreview(body),
+    raw: body,
+    updatedAt: new Date().toISOString(),
+    parseError,
+  };
+}
+
+/**
+ * 极简 YAML 解析（不依赖外部库）
+ * @private
+ */
+function parseYAML(yamlStr) {
+  const obj = {};
+  const lines = yamlStr.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx <= 0) continue;
+
+    const key = trimmed.slice(0, colonIdx).trim();
+    const value = trimmed.slice(colonIdx + 1).trim();
+
+    // 去掉引号
+    const unquoted = value.startsWith('"')
+      ? value.slice(1, -1)
+      : value.startsWith("'")
+        ? value.slice(1, -1)
+        : value;
+
+    obj[key] = unquoted || null;
+  }
+
+  return obj;
+}
+
+/**
+ * 生成预览文本
+ * @private
+ */
+function makePreview(text, maxLen = 200) {
+  const lines = text.split('\n').filter(l => l.trim());
+  let preview = '';
+  for (const line of lines) {
+    if ((preview + line).length > maxLen) {
+      preview += '...';
+      break;
+    }
+    preview += (preview ? ' ' : '') + line;
+  }
+  return preview;
+}