skillhelper 0.4.2

package/packages/scanner/src/adapters/tier2-user-skills.mjs

@@ -0,0 +1,218 @@
+/**
+ * @file tier2-user-skills.mjs
+ * 扫描第2层：用户根目录 ~/skills/
+ * 与第1层的 pathHashes 进行去重
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import fg from 'fast-glob';
+import { expandTilde, readFileSafe, sha1Id } from '../utils.mjs';
+import { USER_TIER_2_CONFIG } from '../config/editor-tiers.mjs';
+import { pathHashCache } from '../hash/path-hash.mjs';
+import { ensureRegistered, getDescriptor } from '../core/registry.mjs';
+import { computeConfidence } from '../core/descriptor.mjs';
+
+/**
+ * 扫描第2层：用户根目录 ~/skills/
+ * 与第1层的 pathHashes 进行去重
+ *
+ * @param {Object} options
+ * @param {Set<string>} options.tier1PathHashes - 第1层的所有 pathHash 集合
+ * @param {Object} [options.limits] - { maxFiles, maxFileBytes }
+ * @returns {Promise<{items: SkillItem[], pathHashes: Set<string>}>}
+ */
+export async function scanTier2UserSkills(options = {}) {
+  const { tier1PathHashes = new Set(), limits = {} } = options;
+  const mergedLimits = {
+    maxFiles: limits.maxFiles ?? 5000,
+    maxFileBytes: limits.maxFileBytes ?? 1024 * 1024,
+  };
+
+  // descriptor registry 化（渐进迁移）
+  ensureRegistered();
+  const desc = getDescriptor('tier2:user-skills');
+  const relPatterns = desc?.detect?.globPatterns || [`**/SKILL.md`, `**/skill.md`];
+  const ignore = desc?.detect?.ignore || ['**/node_modules/**', '**/.git/**', '**/dist/**'];
+  const deep = desc?.detect?.deep ?? 10;
+
+  const items = [];
+  const pathHashes = new Set();
+
+  // 置信度统计
+  const basePath = expandTilde(USER_TIER_2_CONFIG.globalPath);
+  const dirExists = safeDirExists(basePath);
+  let matchedFiles = 0;
+  let parsedValid = 0;
+  let metadataComplete = 0;
+
+  try {
+    const patterns = relPatterns.map(p => `${basePath}/${p}`);
+
+    const seen = new Set();
+
+    for (const pattern of patterns) {
+      if (items.length >= mergedLimits.maxFiles) break;
+
+      try {
+        const matches = await fg(pattern, {
+          absolute: true,
+          onlyFiles: true,
+          dot: true,
+          followSymbolicLinks: true,
+          deep,
+          ignore,
+        });
+
+        for (const filePath of matches) {
+          if (items.length >= mergedLimits.maxFiles) break;
+          if (seen.has(filePath)) continue;
+          seen.add(filePath);
+          matchedFiles++;
+
+          // 路径去重：检查是否已在 Tier 1 中
+          const hash = pathHashCache.getOrCompute(filePath);
+          if (tier1PathHashes.has(hash)) {
+            continue; // 跳过重复项
+          }
+
+          try {
+            const skill = parseSkillFile({
+              abs: filePath,
+              editor: 'my-skills',
+              limits: mergedLimits,
+            });
+            if (skill) {
+              skill.tierId = 'tier-2';
+              skill.pathHash = hash;
+              if (skill.name) parsedValid++;
+              if (skill.name && skill.description) metadataComplete++;
+              items.push(skill);
+              pathHashes.add(hash);
+            }
+          } catch (e) {
+            console.warn(`[scanTier2] parse failed: ${filePath}`, e.message);
+          }
+        }
+      } catch (e) {
+        // glob 模式失败，继续下一个
+      }
+    }
+  } catch (e) {
+    console.warn(`[scanTier2] scan failed:`, e.message);
+  }
+
+  const confidence = computeConfidence({ dirExists, matchedFiles, parsedValid, metadataComplete });
+  if (confidence) {
+    for (const item of items) item.confidence = confidence;
+  }
+
+  return { items, pathHashes, confidence };
+}
+
+function safeDirExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 解析单个技能文件
+ * @private
+ */
+function parseSkillFile({ abs, 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;
+
+  return {
+    id,
+    kind: 'skill',
+    source: 'tier2-user',
+    editor,
+    name,
+    description,
+    category,
+    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;
+}

package/packages/scanner/src/adapters/tier3-other-skills.mjs

@@ -0,0 +1,225 @@
+/**
+ * @file tier3-other-skills.mjs
+ * 扫描第3层：其他位置的 skill.md 文件
+ * 仅在 scanTier3=true 时启用
+ * 与第1、2层的 pathHashes 进行去重
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import fg from 'fast-glob';
+import { expandTilde, readFileSafe, sha1Id } from '../utils.mjs';
+import { OTHER_TIER_3_CONFIGS } from '../config/editor-tiers.mjs';
+import { pathHashCache } from '../hash/path-hash.mjs';
+import { ensureRegistered, getDescriptor } from '../core/registry.mjs';
+import { computeConfidence } from '../core/descriptor.mjs';
+
+/**
+ * 扫描第3层：其他位置
+ * 仅扫描小写 skill.md（精确大小写敏感）
+ * 与第1、2层的 pathHashes 进行去重
+ *
+ * @param {Object} options
+ * @param {Set<string>} options.tier1PathHashes - 第1层的所有 pathHash 集合
+ * @param {Set<string>} options.tier2PathHashes - 第2层的所有 pathHash 集合
+ * @param {Object} [options.limits] - { maxFiles, maxFileBytes }
+ * @returns {Promise<{items: SkillItem[]}>}
+ */
+export async function scanTier3OtherSkills(options = {}) {
+  const { tier1PathHashes = new Set(), tier2PathHashes = new Set(), limits = {} } = options;
+  const mergedLimits = {
+    maxFiles: limits.maxFiles ?? 5000,
+    maxFileBytes: limits.maxFileBytes ?? 1024 * 1024,
+  };
+
+  // descriptor registry 化（渐进迁移）
+  ensureRegistered();
+
+  const items = [];
+
+  // 合并第1、2层的 pathHashes
+  const existingHashes = new Set([...tier1PathHashes, ...tier2PathHashes]);
+
+  for (const location of OTHER_TIER_3_CONFIGS) {
+    if (items.length >= mergedLimits.maxFiles) break;
+
+    const desc = getDescriptor(`tier3:${location.name}`);
+    const relPatterns = desc?.detect?.globPatterns || [`**/skill.md`];
+    const ignore = desc?.detect?.ignore || ['**/node_modules/**', '**/.git/**', '**/dist/**'];
+    const deep = desc?.detect?.deep ?? 10;
+
+    const basePath = expandTilde(location.path);
+    const dirExists = safeDirExists(basePath);
+    let matchedFiles = 0;
+    let parsedValid = 0;
+    let metadataComplete = 0;
+
+    try {
+      const patterns = relPatterns.map(p => `${basePath}/${p}`);
+
+      const seen = new Set();
+
+      for (const pattern of patterns) {
+        const matches = await fg(pattern, {
+          absolute: true,
+          onlyFiles: true,
+          dot: true,
+          followSymbolicLinks: true,
+          deep,
+          ignore,
+        });
+
+        for (const filePath of matches) {
+          if (items.length >= mergedLimits.maxFiles) break;
+          if (seen.has(filePath)) continue;
+          seen.add(filePath);
+          matchedFiles++;
+
+          // 路径去重
+          const hash = pathHashCache.getOrCompute(filePath);
+          if (existingHashes.has(hash)) {
+            continue; // 跳过重复项
+          }
+
+          try {
+            const skill = parseSkillFile({
+              abs: filePath,
+              editor: 'other-skills',
+              limits: mergedLimits,
+              location: location.name,
+            });
+            if (skill) {
+              skill.tierId = 'tier-3';
+              skill.pathHash = hash;
+              if (skill.name) parsedValid++;
+              if (skill.name && skill.description) metadataComplete++;
+              items.push(skill);
+              existingHashes.add(hash);
+            }
+          } catch (e) {
+            console.warn(`[scanTier3] parse failed: ${filePath}`, e.message);
+          }
+        }
+      }
+    } catch (e) {
+      console.warn(`[scanTier3] scan ${location.name} failed:`, e.message);
+    }
+
+    // 每个 location 独立计算置信度
+    const confidence = computeConfidence({ dirExists, matchedFiles, parsedValid, metadataComplete });
+    if (confidence) {
+      for (const item of items) {
+        if (item.tierId === 'tier-3' && !item.confidence) item.confidence = confidence;
+      }
+    }
+  }
+
+  return { items };
+}
+
+function safeDirExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 解析单个技能文件
+ * @private
+ */
+function parseSkillFile({ abs, editor, limits, location }) {
+  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;
+
+  return {
+    id,
+    kind: 'skill',
+    source: 'tier3-other',
+    editor,
+    name,
+    description,
+    category,
+    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;
+}

package/packages/scanner/src/config/editor-tiers.mjs

@@ -0,0 +1,191 @@
+/**
+ * @file editor-tiers.mjs
+ * 22个编辑器工具的配置，按优先级排序
+ * 用于第1层扫描的路径和品牌映射
+ */
+
+/**
+ * Tier 1：22 个编辑器工具（按优先级）
+ */
+export const EDITOR_TIER_1_CONFIGS = [
+  {
+    id: 1,
+    brand: 'hermes',
+    name: 'Hermes',
+    globalPath: '~/.hermes/skills',
+    projectPath: '.hermes/skills',
+  },
+  {
+    id: 2,
+    brand: 'claude',
+    name: 'Claude',
+    globalPath: '~/.claude/skills',
+    projectPath: '.claude/skills',
+  },
+  {
+    id: 3,
+    brand: 'cursor',
+    name: 'Cursor',
+    globalPath: '~/.cursor/skills',
+    projectPath: '.cursor/skills',
+  },
+  {
+    id: 4,
+    brand: 'vscode',
+    name: 'VSCode',
+    globalPath: '~/.vscode/skills',
+    projectPath: '.vscode/skills',
+  },
+  {
+    id: 5,
+    brand: 'codeium',
+    name: 'Codeium',
+    globalPath: '~/.codeium/skills',
+    projectPath: '.codeium/skills',
+  },
+  {
+    id: 6,
+    brand: 'windsurf',
+    name: 'Windsurf',
+    globalPath: '~/.windsurf/skills',
+    projectPath: '.windsurf/skills',
+  },
+  {
+    id: 7,
+    brand: 'continue',
+    name: 'Continue',
+    globalPath: '~/.continue/skills',
+    projectPath: '.continue/skills',
+  },
+  {
+    id: 8,
+    brand: 'tauri',
+    name: 'Tauri',
+    globalPath: '~/.tauri/skills',
+    projectPath: '.tauri/skills',
+  },
+  {
+    id: 9,
+    brand: 'trae',
+    name: 'Trae',
+    globalPath: '~/.trae/skills',
+    projectPath: '.trae/skills',
+  },
+  {
+    id: 10,
+    brand: 'trae-cn',
+    name: 'Trae-CN',
+    globalPath: '~/.trae-cn/skills',
+    projectPath: '.trae-cn/skills',
+  },
+  {
+    id: 11,
+    brand: 'qoder',
+    name: 'QoDer',
+    globalPath: '~/.qoder/skills',
+    projectPath: '.qoder/skills',
+  },
+  {
+    id: 12,
+    brand: 'codex',
+    name: 'Codex',
+    globalPath: '~/.codex/skills',
+    projectPath: '.codex/skills',
+  },
+  {
+    id: 13,
+    brand: 'vim',
+    name: 'Vim',
+    globalPath: '~/.vim/skills',
+    projectPath: '.vim/skills',
+  },
+  {
+    id: 14,
+    brand: 'neovim',
+    name: 'Neovim',
+    globalPath: '~/.config/nvim/skills',
+    projectPath: '.nvim/skills',
+  },
+  {
+    id: 15,
+    brand: 'emacs',
+    name: 'Emacs',
+    globalPath: '~/.emacs.d/skills',
+    projectPath: '.emacs.d/skills',
+  },
+  {
+    id: 16,
+    brand: 'sublime',
+    name: 'Sublime',
+    globalPath: '~/.config/sublime-text/skills',
+    projectPath: '.sublime-text/skills',
+  },
+  {
+    id: 17,
+    brand: 'jetbrains',
+    name: 'Jetbrains IDE',
+    globalPath: '~/.config/JetBrains/skills',
+    projectPath: '.jetbrains/skills',
+  },
+  {
+    id: 18,
+    brand: 'nova',
+    name: 'Nova',
+    globalPath: '~/.nova/skills',
+    projectPath: '.nova/skills',
+  },
+  {
+    id: 19,
+    brand: 'zed',
+    name: 'Zed',
+    globalPath: '~/.config/zed/skills',
+    projectPath: '.zed/skills',
+  },
+  {
+    id: 20,
+    brand: 'copilot',
+    name: 'GitHub Copilot',
+    globalPath: '~/.copilot/skills',
+    projectPath: '.copilot/skills',
+  },
+  {
+    id: 21,
+    brand: 'replit',
+    name: 'Replit',
+    globalPath: '~/.replit/skills',
+    projectPath: '.replit/skills',
+  },
+  {
+    id: 22,
+    brand: 'glot',
+    name: 'Glot.io',
+    globalPath: '~/.glot/skills',
+    projectPath: '.glot/skills',
+  },
+];
+
+/**
+ * Tier 2：用户根目录技能库
+ */
+export const USER_TIER_2_CONFIG = {
+  name: 'My Skills Library',
+  globalPath: '~/skills', // 支持 ~/Skills / ~/SKILLS 等大小写变体
+};
+
+/**
+ * Tier 3：其他位置（可选扫描）
+ */
+export const OTHER_TIER_3_CONFIGS = [
+  {
+    name: 'System Opt',
+    path: '/opt',
+  },
+  {
+    name: 'Homebrew',
+    path: '/usr/local',
+  },
+  {
+    name: 'User Opt',
+    path: '~/opt',
+  },
+];

package/packages/scanner/src/core/atomic-write.mjs

@@ -0,0 +1,11 @@
+/**
+ * @file atomic-write.mjs
+ * 2026-07 阶段三：实现已迁入 bin/lib/atomic-write.mjs（底层公共模块）。
+ * 本文件保留为 re-export，保持 scanner 包内现有引用不变。
+ * 新代码可直接引用 ../../../bin/lib/atomic-write.mjs。
+ *
+ * 原子写工具：临时文件 + rename，保证进程中断不产生半截文件。
+ * 详见 bin/lib/atomic-write.mjs。
+ */
+
+export { atomicWriteText, atomicWriteBytes, atomicWriteJson } from '../../../../bin/lib/atomic-write.mjs';