@winspan/claude-forge 8.53.2 → 8.54.4

package/src/skills/registry.ts

@@ -1,355 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { homedir } from 'node:os';
-import matter from 'gray-matter';
-import { fileURLToPath } from 'node:url';
-import { logger } from '../core/utils/logger.js';
-import { loadOfficialSkills, OFFICIAL_SKILL_KEYWORDS } from './official-skills.js';
-import { SemanticSkillMatcher } from './semantic-matcher.js';
-
-const SKILLS_DIR = path.join(homedir(), '.claude', 'skills');
-
-export interface Skill {
-  id: string;
-  name: string;
-  keywords: string[];
-  content: string;
-  path: string;
-  isOfficial?: boolean; // Mark official built-in skills
-  description?: string; // Optional description from frontmatter (used by agent-skills format)
-}
-
-/**
- * Simple skill registry that scans ~/.claude/skills/*.md
- * and matches by keywords in frontmatter
- */
-export class SkillRegistry {
-  private skills: Map<string, Skill> = new Map();
-  private semanticMatcher: SemanticSkillMatcher | null = null;
-
-  constructor(apiKey?: string, model?: string, baseURL?: string) {
-    this.scan();
-
-    // Initialize semantic matcher if API key is provided
-    if (apiKey) {
-      this.semanticMatcher = new SemanticSkillMatcher(apiKey, model, baseURL);
-      logger.info('[SkillRegistry] Semantic matching enabled');
-    } else {
-      logger.debug('[SkillRegistry] Semantic matching disabled (no API key)');
-    }
-  }
-
-  /**
-   * Resolve the directory containing official built-in skill .md files.
-   * Uses import.meta.url for ESM compatibility (works in both dev and npm-installed environments).
-   */
-  private resolveBuiltinDir(): string {
-    const thisFile = fileURLToPath(import.meta.url);
-    return path.join(path.dirname(thisFile), 'official');
-  }
-
-  /**
-   * Scan ~/.claude/skills/ for markdown files with frontmatter
-   * Official skills are loaded first, then user skills (which can override)
-   *
-   * Supports two formats:
-   * 1. Flat format: ~/.claude/skills/skill-name.md
-   * 2. Directory format: ~/.claude/skills/skill-name/SKILL.md (agent-skills format)
-   */
-  private scan(): void {
-    // 1. Load official built-in skills from src/skills/official/*.md
-    let officialCount = 0;
-    try {
-      const officialSkills = loadOfficialSkills(this.resolveBuiltinDir());
-      for (const officialSkill of officialSkills) {
-        // Merge extended keywords from OFFICIAL_SKILL_KEYWORDS if available
-        const extendedKeywords = OFFICIAL_SKILL_KEYWORDS[officialSkill.name] || officialSkill.keywords;
-        this.skills.set(officialSkill.name, {
-          id: officialSkill.name,
-          name: officialSkill.name,
-          keywords: extendedKeywords,
-          content: officialSkill.content,
-          path: this.resolveBuiltinDir() + '/' + officialSkill.name + '.md',
-          isOfficial: true,
-          description: officialSkill.description,
-        });
-        officialCount++;
-      }
-    } catch (err) {
-      logger.warn(`[SkillRegistry] Failed to load official skills: ${err}`);
-    }
-
-    logger.info(`Loaded ${officialCount} official skill(s)`);
-
-    // 2. Load user skills from ~/.claude/skills/ (can override official skills)
-    if (!fs.existsSync(SKILLS_DIR)) {
-      logger.debug(`Skills directory not found: ${SKILLS_DIR}`);
-      return;
-    }
-
-    const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
-    let userCount = 0;
-
-    for (const entry of entries) {
-      try {
-        let filePath: string;
-        let id: string;
-
-        if (entry.isFile() && entry.name.endsWith('.md')) {
-          // Format 1: Flat .md file
-          filePath = path.join(SKILLS_DIR, entry.name);
-          id = path.basename(entry.name, '.md');
-        } else if (entry.isDirectory()) {
-          // Format 2: Directory with SKILL.md
-          const skillMdPath = path.join(SKILLS_DIR, entry.name, 'SKILL.md');
-          if (!fs.existsSync(skillMdPath)) {
-            continue; // Skip directories without SKILL.md
-          }
-          filePath = skillMdPath;
-          id = entry.name;
-        } else {
-          continue; // Skip other file types
-        }
-
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const parsed = matter(content);
-        const { data, content: body } = parsed;
-
-        const name = typeof data.name === 'string' ? data.name : id;
-        // 兼容两种字段名：keywords（claude-forge 标准）和 tags（Claude Code 官方 skill 约定）
-        const rawKeywords: unknown = data.keywords ?? data.tags;
-        const keywords: string[] = Array.isArray(rawKeywords)
-          ? rawKeywords.filter((k): k is string => typeof k === 'string')
-          : [];
-        const description = typeof data.description === 'string' ? data.description : undefined;
-
-        // User skills override official skills, but merge keywords from OFFICIAL_SKILL_KEYWORDS
-        const extendedKeywords = OFFICIAL_SKILL_KEYWORDS[id];
-        const mergedKeywords = extendedKeywords
-          ? [...new Set([...keywords, ...extendedKeywords])]
-          : keywords;
-
-        this.skills.set(id, {
-          id,
-          name,
-          keywords: mergedKeywords,
-          content: body.trim(),
-          path: filePath,
-          isOfficial: false,
-          description,
-        });
-        userCount++;
-      } catch (err) {
-        logger.warn(`Failed to parse skill ${entry.name}: ${err}`);
-      }
-    }
-
-    if (userCount > 0) {
-      logger.info(`Loaded ${userCount} user skill(s) from ${SKILLS_DIR}`);
-    }
-  }
-
-  /**
-   * Match a prompt against skill keywords with hybrid approach:
-   * 1. Try semantic matching (AI-powered) if available
-   * 2. Fall back to keyword matching if semantic fails or not configured
-   */
-  async match(prompt: string, keywords: string[] = [], context?: { recentFiles?: string[] }): Promise<Skill | null> {
-    const result = await this.matchWithConfidence(prompt, keywords, context);
-    return result?.skill ?? null;
-  }
-
-  /**
-   * Like match(), but also returns the confidence score (0-100) so callers
-   * can compare across alternatives (e.g. agent vs skill routing).
-   */
-  async matchWithConfidence(
-    prompt: string,
-    keywords: string[] = [],
-    context?: { recentFiles?: string[] },
-  ): Promise<{ skill: Skill; confidence: number; source: 'semantic' | 'keyword' } | null> {
-    // Try semantic matching first
-    if (this.semanticMatcher) {
-      try {
-        const semanticResult = await this.semanticMatcher.match(
-          Array.from(this.skills.values()),
-          {
-            prompt,
-            intentKeywords: keywords,
-            recentFiles: context?.recentFiles,
-          }
-        );
-
-        if (semanticResult) {
-          logger.info(`[SkillRegistry] Semantic match: ${semanticResult.skill.id} (${semanticResult.confidence}%)`);
-          return { skill: semanticResult.skill, confidence: semanticResult.confidence, source: 'semantic' };
-        }
-      } catch (err) {
-        logger.warn(`[SkillRegistry] Semantic matching failed, falling back to keyword matching: ${err}`);
-      }
-    }
-
-    // Fall back to keyword matching
-    const kwSkill = await this.matchKeywords(prompt, keywords, context);
-    if (kwSkill) {
-      // Keyword matching has no real confidence; assign a conservative 60%
-      return { skill: kwSkill, confidence: 60, source: 'keyword' };
-    }
-    return null;
-  }
-
-  /**
-   * Keyword-based matching (fallback method)
-   * Supports fallback to description-based substring matching when keywords are empty
-   */
-  private async matchKeywords(
-    prompt: string,
-    keywords: string[] = [],
-    context?: { recentFiles?: string[] }
-  ): Promise<Skill | null> {
-    const promptLower = prompt.toLowerCase();
-    const extraLower = keywords.map(k => k.toLowerCase());
-
-    let bestSkill: Skill | null = null;
-    let bestScore = 0;
-    let bestCandidate: Skill | null = null;
-    let bestCandidateScore = 0;
-
-    for (const skill of this.skills.values()) {
-      let score = 0;
-
-      // If skill has keywords, use keyword matching
-      if (skill.keywords.length > 0) {
-        for (const kw of skill.keywords) {
-          const kwLower = kw.toLowerCase();
-
-          // Check if keyword appears in prompt or intent keywords
-          if (this.matchKeywordFlexible(promptLower, kwLower)) {
-            score += 1;
-          }
-          if (extraLower.some(ek => this.matchKeywordFlexible(ek, kwLower))) {
-            score += 1;
-          }
-        }
-      } else if (skill.description) {
-        // Fallback path 1: Use description substring matching when keywords are empty
-        const descLower = skill.description.toLowerCase();
-        if (descLower.includes(promptLower) || promptLower.includes(descLower)) {
-          score = 1; // Give a base score for description match
-        }
-      }
-      // Fallback path 2: If no keywords and no description, score remains 0
-      // This allows SemanticSkillMatcher to take over
-
-      // Track best candidate regardless of threshold
-      if (score > bestCandidateScore) {
-        bestCandidateScore = score;
-        bestCandidate = skill;
-      }
-
-      // Official skills get priority: require 1+ match, user skills require 2+ matches
-      const threshold = skill.isOfficial ? 1 : 2;
-
-      if (score >= threshold && score > bestScore) {
-        bestScore = score;
-        bestSkill = skill;
-      } else if (
-        score === bestScore &&
-        score >= threshold &&
-        skill.isOfficial &&
-        !bestSkill?.isOfficial
-      ) {
-        // Tie-break: prefer official skill when both meet threshold
-        bestSkill = skill;
-      }
-    }
-
-    if (bestSkill) {
-      logger.info(`[SkillRegistry] Keyword match: ${bestSkill.id} (score: ${bestScore})`);
-    } else {
-      logger.debug(`[SkillRegistry] Best keyword candidate: ${bestCandidate?.id ?? 'none'} (score: ${bestCandidateScore})`);
-    }
-
-    return bestSkill;
-  }
-
-  /**
-   * Flexible keyword matching with word boundary for English, substring for Chinese
-   */
-  private matchKeywordFlexible(text: string, keyword: string): boolean {
-    // For Chinese or multi-word keywords, use simple includes
-    if (/[一-龥]/.test(keyword) || keyword.includes(' ')) {
-      return text.includes(keyword);
-    }
-
-    // For single English words, require word boundaries to avoid false positives
-    // e.g., "test" won't match "latest"
-    const regex = new RegExp(`\\b${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
-    return regex.test(text);
-  }
-
-  /**
-   * Match with full result details (for debugging/logging)
-   */
-  async matchWithDetails(prompt: string, keywords: string[] = [], context?: { recentFiles?: string[] }) {
-    const promptLower = prompt.toLowerCase();
-    const extraLower = keywords.map(k => k.toLowerCase());
-
-    const results = [];
-    for (const skill of this.skills.values()) {
-      let score = 0;
-      const matchedKeywords: string[] = [];
-
-      for (const kw of skill.keywords) {
-        const kwLower = kw.toLowerCase();
-
-        if (this.matchKeywordFlexible(promptLower, kwLower)) {
-          score += 1;
-          matchedKeywords.push(kw);
-        }
-        if (extraLower.some(ek => this.matchKeywordFlexible(ek, kwLower))) {
-          score += 1;
-        }
-      }
-
-      if (score >= 1) {
-        results.push({
-          skill,
-          confidence: Math.min(100, score * 20), // Simple scoring: 1 match = 20%, 5 matches = 100%
-          matchedKeywords,
-        });
-      }
-    }
-
-    results.sort((a, b) => b.confidence - a.confidence);
-    return results;
-  }
-
-  /** Return all loaded skills */
-  getAll(): Skill[] {
-    return Array.from(this.skills.values());
-  }
-
-  /** Get a skill by ID */
-  get(id: string): Skill | undefined {
-    return this.skills.get(id);
-  }
-
-  /**
-   * Get skill manifest (id + description + keywords) for Agent pre-declaration
-   */
-  getManifest(): Array<{ id: string; name: string; description: string; keywords: string[] }> {
-    return this.getAll().map(skill => ({
-      id: skill.id,
-      name: skill.name,
-      description: skill.description || '',
-      keywords: skill.keywords,
-    }));
-  }
-
-  /** Re-scan the skills directory */
-  reload(): void {
-    this.skills.clear();
-    this.scan();
-  }
-}

package/src/skills/semantic-matcher.ts

@@ -1,234 +0,0 @@
-/**
- * AI-powered semantic skill matcher using Claude API
- * Provides more accurate skill recommendations by understanding user intent
- */
-
-import Anthropic from '@anthropic-ai/sdk';
-import type { Skill } from './registry.js';
-import { logger } from '../core/utils/logger.js';
-import { DEFAULTS } from '../core/constants.js';
-
-export interface SemanticMatchResult {
-  skill: Skill;
-  confidence: number; // 0-100
-  reasoning: string;
-}
-
-export interface SemanticMatchContext {
-  prompt: string;
-  intentKeywords?: string[];
-  recentFiles?: string[];
-  projectPath?: string;
-}
-
-/**
- * Semantic matcher using Claude API for intent understanding
- */
-export class SemanticSkillMatcher {
-  private client: Anthropic | null = null;
-  private model: string;
-  private cache: Map<string, SemanticMatchResult | null> = new Map();
-  private readonly CACHE_TTL = 5 * 60 * 1000; // 5 minutes
-  private cacheTimestamps: Map<string, number> = new Map();
-
-  constructor(apiKey?: string, model?: string, baseURL?: string) {
-    this.model = model || DEFAULTS.AI_MODEL;
-    if (apiKey) {
-      this.client = new Anthropic({ apiKey, baseURL });
-    }
-  }
-
-  /**
-   * Match skills using semantic understanding
-   * Falls back to keyword matching if API is not configured
-   */
-  async match(skills: Skill[], context: SemanticMatchContext): Promise<SemanticMatchResult | null> {
-    // Check cache first
-    const cacheKey = this.getCacheKey(context.prompt);
-    const cached = this.getFromCache(cacheKey);
-    if (cached !== undefined) {
-      return cached;
-    }
-
-    // If no API key, return null (caller will fall back to keyword matching)
-    if (!this.client) {
-      logger.debug('[SemanticMatcher] No API key configured, skipping semantic matching');
-      return null;
-    }
-
-    try {
-      const result = await this.matchWithAI(skills, context);
-      this.setCache(cacheKey, result);
-      return result;
-    } catch (err) {
-      logger.warn(`[SemanticMatcher] AI matching failed: ${err}`);
-      return null; // Fall back to keyword matching
-    }
-  }
-
-  /**
-   * Use Claude API to understand intent and match skills
-   */
-  private async matchWithAI(
-    skills: Skill[],
-    context: SemanticMatchContext
-  ): Promise<SemanticMatchResult | null> {
-    if (!this.client) return null;
-
-    // Build skill descriptions for the prompt
-    const skillDescriptions = skills
-      .filter(s => s.isOfficial) // Only consider official skills for AI matching
-      .map((s, idx) => `${idx + 1}. **${s.id}**: ${s.name} - ${this.extractDescription(s)}`)
-      .join('\n');
-
-    const prompt = this.buildMatchingPrompt(context, skillDescriptions);
-
-    const response = await this.client.messages.create({
-      model: this.model,
-      max_tokens: 500,
-      temperature: 0,
-      messages: [
-        {
-          role: 'user',
-          content: prompt,
-        },
-      ],
-    });
-
-    const content = response.content[0];
-    if (content.type !== 'text') {
-      return null;
-    }
-
-    return this.parseAIResponse(content.text, skills);
-  }
-
-  /**
-   * Build the matching prompt for Claude API
-   */
-  private buildMatchingPrompt(context: SemanticMatchContext, skillDescriptions: string): string {
-    return `You are a skill recommendation system. Analyze the user's request and recommend the most relevant skill.
-
-User Request: "${context.prompt}"
-
-${context.intentKeywords && context.intentKeywords.length > 0 ? `Intent Keywords: ${context.intentKeywords.join(', ')}` : ''}
-
-Available Skills:
-${skillDescriptions}
-
-Instructions:
-1. Understand the user's intent and task type
-2. Match to the MOST relevant skill (only ONE skill)
-3. If no skill is clearly relevant (confidence < 60%), respond with "NONE"
-4. Respond in this exact format:
-
-SKILL_ID: <skill-id or NONE>
-CONFIDENCE: <0-100>
-REASONING: <one sentence explaining why this skill matches or why no skill matches>
-
-Example responses:
-- SKILL_ID: official-tdd
-  CONFIDENCE: 85
-  REASONING: User wants to write tests before implementation, which is the core of TDD.
-
-- SKILL_ID: NONE
-  CONFIDENCE: 30
-  REASONING: Request is about simple documentation update, no specialized skill needed.`;
-  }
-
-  /**
-   * Parse AI response into match result
-   */
-  private parseAIResponse(response: string, skills: Skill[]): SemanticMatchResult | null {
-    const lines = response.trim().split('\n');
-    let skillId: string | null = null;
-    let confidence = 0;
-    let reasoning = '';
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (trimmed.startsWith('SKILL_ID:')) {
-        skillId = trimmed.substring('SKILL_ID:'.length).trim();
-      } else if (trimmed.startsWith('CONFIDENCE:')) {
-        confidence = parseInt(trimmed.substring('CONFIDENCE:'.length).trim(), 10);
-      } else if (trimmed.startsWith('REASONING:')) {
-        reasoning = trimmed.substring('REASONING:'.length).trim();
-      }
-    }
-
-    // If AI says NONE or confidence too low, return null
-    if (!skillId || skillId === 'NONE' || confidence < 60) {
-      logger.debug(`[SemanticMatcher] No match: ${reasoning}`);
-      return null;
-    }
-
-    // Find the matched skill
-    const skill = skills.find(s => s.id === skillId);
-    if (!skill) {
-      logger.warn(`[SemanticMatcher] AI returned unknown skill: ${skillId}`);
-      return null;
-    }
-
-    logger.info(`[SemanticMatcher] Matched ${skillId} with ${confidence}% confidence`);
-    return { skill, confidence, reasoning };
-  }
-
-  /**
-   * Extract description from skill content
-   * Prioritizes frontmatter description over content extraction
-   */
-  private extractDescription(skill: Skill): string {
-    // Prefer frontmatter description if available (agent-skills format)
-    if (skill.description) {
-      return skill.description;
-    }
-
-    // Fallback: Try to extract first line of description from content
-    const lines = skill.content.split('\n');
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('---')) {
-        return trimmed.substring(0, 100);
-      }
-    }
-    return skill.keywords.join(', ');
-  }
-
-  /**
-   * Cache management
-   */
-  private getCacheKey(prompt: string): string {
-    return prompt.toLowerCase().substring(0, 200);
-  }
-
-  private getFromCache(key: string): SemanticMatchResult | null | undefined {
-    const timestamp = this.cacheTimestamps.get(key);
-    if (!timestamp || Date.now() - timestamp > this.CACHE_TTL) {
-      this.cache.delete(key);
-      this.cacheTimestamps.delete(key);
-      return undefined;
-    }
-    return this.cache.get(key);
-  }
-
-  private setCache(key: string, result: SemanticMatchResult | null): void {
-    this.cache.set(key, result);
-    this.cacheTimestamps.set(key, Date.now());
-
-    // Limit cache size to 100 entries
-    if (this.cache.size > 100) {
-      const oldestKey = Array.from(this.cacheTimestamps.entries())
-        .sort((a, b) => a[1] - b[1])[0][0];
-      this.cache.delete(oldestKey);
-      this.cacheTimestamps.delete(oldestKey);
-    }
-  }
-
-  /**
-   * Clear cache
-   */
-  clearCache(): void {
-    this.cache.clear();
-    this.cacheTimestamps.clear();
-  }
-}