@winspan/claude-forge 8.41.0 → 8.50.6

package/src/skills/semantic-matcher.ts

@@ -0,0 +1,231 @@
+/**
+ * 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';
+
+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 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) {
+    if (apiKey) {
+      this.client = new Anthropic({ apiKey });
+    }
+  }
+
+  /**
+   * 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: 'claude-3-5-haiku-20241022',
+      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();
+  }
+}

package/src/skills/tools/pipeline-suggest.ts

@@ -0,0 +1,226 @@
+/**
+ * PipelineSuggest — 帮助 Claude 决策是否调用 Swarm Pipeline
+ *
+ * 根据任务特征（文件数量、任务类型等）判断是否需要启动多 Agent 协作的 Pipeline，
+ * 并生成可直接使用的 Task({...}) 调用代码。
+ *
+ * 内置 10 种模板，覆盖：
+ *   - 基础：bug_fix / feature / refactor / investigation / performance
+ *   - BMAD 风格：bmad_feature（完整产品开发流程）
+ *   - Harness 风格：harness_safe_refactor（安全重构）/ harness_debug（深度调试）
+ *   - 扩展：migration（技术迁移）/ security_audit（安全审计）
+ */
+
+import { logger } from '../../core/utils/logger.js';
+
+export interface PipelineSuggestParams {
+  task_description: string;
+  file_count?: number;
+  is_new_feature?: boolean;
+  is_refactor?: boolean;
+  is_bug_fix?: boolean;
+  is_performance?: boolean;
+  is_migration?: boolean;
+  is_security?: boolean;
+}
+
+export interface PipelineSuggestResult {
+  should_invoke: boolean;
+  pipeline_type: string | null;
+  reason: string;
+  task_calls: string;
+}
+
+/** Pipeline 模板定义
+ *
+ * 每个 Agent 的 prompt 都强制要求在 docs/<phase>/ 下输出对应阶段文档。
+ * 文件名采用 kebab-case + 时间戳前缀（由 agent 自行生成 yyyymmdd-hhmm 格式）。
+ *
+ * 文档目录结构约定：
+ *   docs/
+ *   ├── requirements/   # 需求分析、问题发现、范围定义
+ *   ├── design/         # 架构设计、详细设计、ADR
+ *   ├── implementation/ # 改造点分析、详细执行计划
+ *   ├── testing/        # 测试报告、回归记录
+ *   ├── review/         # 审查报告、安全审计、性能报告
+ *   └── operations/     # 迁移手册、回滚预案
+ */
+const PIPELINE_TEMPLATES = {
+  // ── 基础模板 ──────────────────────────────────────────────────────────────
+
+  bug_fix: (desc: string) => `Task({ subagent_type: "researcher", name: "investigator", prompt: "${desc}: Investigate root cause. Read error logs, trace call stack, identify the exact failure point. **Write findings to docs/requirements/bug-investigation-<yyyymmdd-hhmm>.md** (问题现象/复现步骤/影响范围/根因假设). SendMessage findings + doc path to 'fixer'.", run_in_background: true })
+Task({ subagent_type: "coder", name: "fixer", prompt: "${desc}: Wait for 'investigator'. Implement minimal, targeted fix. Do NOT refactor surrounding code. **Write change log to docs/implementation/bugfix-changes-<yyyymmdd-hhmm>.md** (改动文件清单/改动原因/兼容性影响). SendMessage changed files + doc path to 'verifier'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "verifier", prompt: "${desc}: Wait for 'fixer'. Write regression test, run full test suite, verify no side effects. **Write test report to docs/testing/bugfix-test-report-<yyyymmdd-hhmm>.md** (新增测试用例/通过情况/回归覆盖范围).", run_in_background: true })`,
+
+  feature: (desc: string) => `Task({ subagent_type: "researcher", name: "analyst", prompt: "${desc}: Analyze requirements, identify affected modules, check existing patterns. **Write requirements doc to docs/requirements/feature-requirements-<yyyymmdd-hhmm>.md** (用户故事/验收标准/范围边界/依赖模块/风险). SendMessage doc path to 'designer'.", run_in_background: true })
+Task({ subagent_type: "planner", name: "designer", prompt: "${desc}: Wait for 'analyst'. Design implementation approach: API contracts, data flow, component boundaries. **Write architecture doc to docs/design/feature-architecture-<yyyymmdd-hhmm>.md** (架构图/组件职责/接口契约/数据模型/错误处理). SendMessage doc path to 'developer'.", run_in_background: true })
+Task({ subagent_type: "feature-developer", name: "developer", prompt: "${desc}: Wait for 'designer'. Read the architecture doc. **First write execution plan to docs/implementation/feature-plan-<yyyymmdd-hhmm>.md** (改造点列表/文件级任务拆解/实施顺序). Then implement following the plan. SendMessage to 'tester'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "tester", prompt: "${desc}: Wait for 'developer'. Write unit + integration tests covering all acceptance criteria. **Write test report to docs/testing/feature-test-report-<yyyymmdd-hhmm>.md** (用例清单/覆盖率/边界场景). SendMessage to 'reviewer'.", run_in_background: true })
+Task({ subagent_type: "reviewer", name: "reviewer", prompt: "${desc}: Wait for 'tester'. Review code quality, security, performance. **Write review report to docs/review/feature-review-<yyyymmdd-hhmm>.md** (代码质量评分/安全/性能/可维护性/改进建议).", run_in_background: true })`,
+
+  refactor: (desc: string) => `Task({ subagent_type: "tester", name: "safety-net", prompt: "${desc}: Write characterization tests capturing current behavior. **Write safety-net report to docs/testing/refactor-safety-net-<yyyymmdd-hhmm>.md** (现有行为清单/测试用例/覆盖范围). SendMessage test paths + doc path to 'planner'.", run_in_background: true })
+Task({ subagent_type: "planner", name: "planner", prompt: "${desc}: Wait for 'safety-net'. Design refactoring strategy. **Write refactor plan to docs/design/refactor-plan-<yyyymmdd-hhmm>.md** (目标态/分步迁移路径/依赖变更/回滚预案). SendMessage doc path to 'refactorer'.", run_in_background: true })
+Task({ subagent_type: "refactor-specialist", name: "refactorer", prompt: "${desc}: Wait for 'planner'. Read the plan. **Write change log to docs/implementation/refactor-changes-<yyyymmdd-hhmm>.md** while executing (每步改动/影响文件/验证点). Execute step by step. SendMessage to 'verifier'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "verifier", prompt: "${desc}: Wait for 'refactorer'. Run ALL tests, verify zero regressions. **Write verification report to docs/testing/refactor-verification-<yyyymmdd-hhmm>.md** (测试通过/失败列表/性能对比).", run_in_background: true })`,
+
+  investigation: (desc: string) => `Task({ subagent_type: "tester", name: "reproducer", prompt: "${desc}: Reproduce the issue with a minimal test case. **Write reproduction doc to docs/requirements/issue-reproduction-<yyyymmdd-hhmm>.md** (现象/复现步骤/环境/触发条件). SendMessage doc path to 'analyst'.", run_in_background: true })
+Task({ subagent_type: "researcher", name: "analyst", prompt: "${desc}: Wait for 'reproducer'. Deep-dive root cause: trace execution, check git blame, identify when it broke. **Write root cause analysis to docs/review/issue-root-cause-<yyyymmdd-hhmm>.md** (根因/引入时间/相关 commit/修复建议).", run_in_background: true })`,
+
+  performance: (desc: string) => `Task({ subagent_type: "tester", name: "benchmarker", prompt: "${desc}: Profile and benchmark current performance. **Write baseline report to docs/testing/perf-baseline-<yyyymmdd-hhmm>.md** (基线指标/测试场景/采样方法). SendMessage doc path to 'analyst'.", run_in_background: true })
+Task({ subagent_type: "researcher", name: "analyst", prompt: "${desc}: Wait for 'benchmarker'. Identify top bottlenecks. **Write analysis to docs/review/perf-analysis-<yyyymmdd-hhmm>.md** (瓶颈定位/根因/优化方案排序). SendMessage doc path to 'optimizer'.", run_in_background: true })
+Task({ subagent_type: "coder", name: "optimizer", prompt: "${desc}: Wait for 'analyst'. **Write execution plan to docs/implementation/perf-optimization-plan-<yyyymmdd-hhmm>.md** before coding (改造点/预期收益/风险). Implement the highest-impact optimizations. SendMessage to 'verifier'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "verifier", prompt: "${desc}: Wait for 'optimizer'. Re-run benchmarks, compare with baseline. **Write final report to docs/testing/perf-verification-<yyyymmdd-hhmm>.md** (优化前后对比/达成/未达成项).", run_in_background: true })`,
+
+  // ── BMAD 风格（完整产品开发流程）─────────────────────────────────────────
+
+  bmad_feature: (desc: string) => `Task({ subagent_type: "researcher", name: "product-analyst", prompt: "${desc}: Analyze user requirements, identify acceptance criteria, define scope boundaries. **Write PRD to docs/requirements/bmad-prd-<yyyymmdd-hhmm>.md** (用户故事/验收标准/in-scope/out-of-scope/优先级). SendMessage doc path to 'architect'.", run_in_background: true })
+Task({ subagent_type: "planner", name: "architect", prompt: "${desc}: Wait for 'product-analyst'. Design technical architecture. **Write to docs/design/bmad-architecture-<yyyymmdd-hhmm>.md** (架构图/组件/接口/数据模型/错误处理) AND docs/design/bmad-detailed-design-<yyyymmdd-hhmm>.md** (类/方法/算法/状态机). SendMessage doc paths to 'developer'.", run_in_background: true })
+Task({ subagent_type: "feature-developer", name: "developer", prompt: "${desc}: Wait for 'architect'. **Write implementation checklist to docs/implementation/bmad-impl-plan-<yyyymmdd-hhmm>.md** (任务拆解/文件清单/依赖顺序/验证点). Implement following the design. SendMessage to 'qa'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "qa", prompt: "${desc}: Wait for 'developer'. Write tests covering all acceptance criteria. **Write QA report to docs/testing/bmad-qa-report-<yyyymmdd-hhmm>.md** (用例对应验收标准/边界/错误路径/覆盖率). SendMessage to 'reviewer'.", run_in_background: true })
+Task({ subagent_type: "reviewer", name: "reviewer", prompt: "${desc}: Wait for 'qa'. Final review: code quality, security, performance, accessibility. **Write final review to docs/review/bmad-final-review-<yyyymmdd-hhmm>.md** (验收标准达成/质量评分/遗留问题/上线建议).", run_in_background: true })`,
+
+  // ── Harness 风格（安全重构）─────────────────────────────────────────────
+
+  harness_safe_refactor: (desc: string) => `Task({ subagent_type: "tester", name: "safety-net", prompt: "${desc}: Write comprehensive characterization tests for ALL touched behavior. **Write to docs/testing/harness-safety-net-<yyyymmdd-hhmm>.md** (现有行为清单/测试矩阵/已知边界). SendMessage doc path to 'analyzer'.", run_in_background: true })
+Task({ subagent_type: "researcher", name: "analyzer", prompt: "${desc}: Wait for 'safety-net'. Map all dependencies and side effects. **Write to docs/requirements/harness-impact-analysis-<yyyymmdd-hhmm>.md** (依赖图/调用方/隐藏耦合/风险评级). SendMessage doc path to 'planner'.", run_in_background: true })
+Task({ subagent_type: "planner", name: "planner", prompt: "${desc}: Wait for 'analyzer'. Design step-by-step plan. **Write to docs/design/harness-refactor-plan-<yyyymmdd-hhmm>.md** (分步路径/每步独立验证点/回滚策略). SendMessage doc path to 'executor'.", run_in_background: true })
+Task({ subagent_type: "refactor-specialist", name: "executor", prompt: "${desc}: Wait for 'planner'. Execute ONE step at a time. **Write change log to docs/implementation/harness-execution-<yyyymmdd-hhmm>.md** (每步改动/验证结果/checkpoint). SendMessage to 'validator'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "validator", prompt: "${desc}: Wait for 'executor'. Run full test suite, type checker, dead code check. **Write to docs/testing/harness-validation-<yyyymmdd-hhmm>.md** (测试通过/失败/类型错误/dead code 报告).", run_in_background: true })`,
+
+  // ── Harness 风格（深度调试）─────────────────────────────────────────────
+
+  harness_debug: (desc: string) => `Task({ subagent_type: "tester", name: "reproducer", prompt: "${desc}: Write a FAILING test reproducing the bug. **Write to docs/requirements/debug-reproduction-<yyyymmdd-hhmm>.md** (复现步骤/环境/失败测试路径/出现频率). SendMessage doc path to 'tracer'.", run_in_background: true })
+Task({ subagent_type: "researcher", name: "tracer", prompt: "${desc}: Wait for 'reproducer'. Trace execution, log state at each step. **Write to docs/review/debug-trace-<yyyymmdd-hhmm>.md** (执行路径/期望 vs 实际/分歧点). SendMessage doc path to 'root-cause'.", run_in_background: true })
+Task({ subagent_type: "researcher", name: "root-cause", prompt: "${desc}: Wait for 'tracer'. Determine root cause. **Write to docs/review/debug-root-cause-<yyyymmdd-hhmm>.md** (根因/git blame 引入点/regression 还是 latent bug/修复方向). SendMessage doc path to 'fixer'.", run_in_background: true })
+Task({ subagent_type: "coder", name: "fixer", prompt: "${desc}: Wait for 'root-cause'. **Write fix plan to docs/implementation/debug-fix-plan-<yyyymmdd-hhmm>.md** (改动点/兼容性/副作用评估). Implement minimal targeted fix. SendMessage to 'verifier'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "verifier", prompt: "${desc}: Wait for 'fixer'. Verify reproducer test passes, run full suite. **Write to docs/testing/debug-verification-<yyyymmdd-hhmm>.md** (测试结果/相关 issue 排查/上线建议).", run_in_background: true })`,
+
+  // ── 技术迁移 ──────────────────────────────────────────────────────────────
+
+  migration: (desc: string) => `Task({ subagent_type: "researcher", name: "impact-analyst", prompt: "${desc}: Map affected files, APIs, dependencies, breaking changes. **Write to docs/requirements/migration-impact-<yyyymmdd-hhmm>.md** (影响清单/breaking changes/兼容性要求). SendMessage doc path to 'planner'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "safety-net", prompt: "${desc}: Write integration tests at migration boundaries. **Write to docs/testing/migration-safety-net-<yyyymmdd-hhmm>.md** (边界测试/前后必须通过的用例). SendMessage doc path to 'planner'.", run_in_background: true })
+Task({ subagent_type: "planner", name: "planner", prompt: "${desc}: Wait for both. Design migration plan. **Write to docs/design/migration-plan-<yyyymmdd-hhmm>.md** AND docs/operations/migration-runbook-<yyyymmdd-hhmm>.md** (执行顺序/feature flags/回滚步骤/灰度策略). SendMessage doc paths to 'migrator'.", run_in_background: true })
+Task({ subagent_type: "coder", name: "migrator", prompt: "${desc}: Wait for 'planner'. Execute migration step by step. **Write change log to docs/implementation/migration-changes-<yyyymmdd-hhmm>.md** (每步改动/兼容层/废弃标记). SendMessage to 'verifier'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "verifier", prompt: "${desc}: Wait for 'migrator'. Verify old + new paths work. **Write to docs/testing/migration-verification-<yyyymmdd-hhmm>.md** (新旧路径测试/deprecation warnings/上线 checklist).", run_in_background: true })`,
+
+  // ── 安全审计 ──────────────────────────────────────────────────────────────
+
+  security_audit: (desc: string) => `Task({ subagent_type: "researcher", name: "threat-modeler", prompt: "${desc}: Identify attack surfaces, trust boundaries, threat vectors. **Write to docs/requirements/security-threat-model-<yyyymmdd-hhmm>.md** (攻击面/信任边界/数据流/威胁向量 OWASP 对应). SendMessage doc path to 'code-auditor'.", run_in_background: true })
+Task({ subagent_type: "researcher", name: "code-auditor", prompt: "${desc}: Wait for 'threat-modeler'. Audit code for each threat. **Write to docs/review/security-audit-<yyyymmdd-hhmm>.md** (漏洞清单/位置/严重级别/PoC/修复建议). SendMessage doc path to 'fixer'.", run_in_background: true })
+Task({ subagent_type: "coder", name: "fixer", prompt: "${desc}: Wait for 'code-auditor'. **Write fix plan to docs/implementation/security-fix-plan-<yyyymmdd-hhmm>.md** (改动点/防护层/副作用). Fix all vulnerabilities. SendMessage to 'verifier'.", run_in_background: true })
+Task({ subagent_type: "tester", name: "verifier", prompt: "${desc}: Wait for 'fixer'. Write security tests (injection/auth bypass/boundary). **Write to docs/testing/security-verification-<yyyymmdd-hhmm>.md** (测试场景/通过情况/残留风险).", run_in_background: true })`,
+} as const;
+
+type PipelineType = keyof typeof PIPELINE_TEMPLATES;
+
+/**
+ * Determine the pipeline type based on task flags.
+ * Priority: security > migration > bug_fix > feature > refactor > performance > investigation.
+ */
+function determinePipelineType(params: PipelineSuggestParams): PipelineType | null {
+  if (params.is_security) return 'security_audit';
+  if (params.is_migration) return 'migration';
+  if (params.is_bug_fix) return 'bug_fix';
+  if (params.is_new_feature) return 'feature';
+  if (params.is_refactor) return 'refactor';
+  if (params.is_performance) return 'performance';
+
+  // file_count >= 3 without explicit type → investigation
+  if (params.file_count !== undefined && params.file_count >= 3) return 'investigation';
+
+  return null;
+}
+
+/**
+ * Keyword-based auto-detection from task description.
+ * Supplements explicit flags when caller doesn't set them.
+ */
+function inferFromDescription(params: PipelineSuggestParams): PipelineSuggestParams {
+  const desc = params.task_description.toLowerCase();
+  const inferred = { ...params };
+
+  if (!inferred.is_bug_fix && (desc.includes('bug') || desc.includes('fix') || desc.includes('修复') || desc.includes('报错'))) {
+    inferred.is_bug_fix = true;
+  }
+  if (!inferred.is_new_feature && (desc.includes('implement') || desc.includes('add') || desc.includes('实现') || desc.includes('新增') || desc.includes('开发'))) {
+    inferred.is_new_feature = true;
+  }
+  if (!inferred.is_refactor && (desc.includes('refactor') || desc.includes('重构') || desc.includes('拆分') || desc.includes('迁移到'))) {
+    inferred.is_refactor = true;
+  }
+  if (!inferred.is_performance && (desc.includes('perf') || desc.includes('slow') || desc.includes('优化') || desc.includes('性能') || desc.includes('慢'))) {
+    inferred.is_performance = true;
+  }
+  if (!inferred.is_migration && (desc.includes('migrat') || desc.includes('upgrade') || desc.includes('升级') || desc.includes('迁移'))) {
+    inferred.is_migration = true;
+  }
+  if (!inferred.is_security && (desc.includes('security') || desc.includes('vulnerab') || desc.includes('安全') || desc.includes('漏洞') || desc.includes('注入'))) {
+    inferred.is_security = true;
+  }
+
+  return inferred;
+}
+
+/**
+ * Escape task description for safe embedding in template strings.
+ */
+function escapeDescription(desc: string): string {
+  return desc.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export async function pipelineSuggest(
+  params: PipelineSuggestParams,
+): Promise<PipelineSuggestResult> {
+  const enriched = inferFromDescription(params);
+  const { task_description, file_count, is_new_feature, is_refactor, is_bug_fix, is_performance, is_migration, is_security } = enriched;
+
+  logger.info(
+    `[PipelineSuggest] task="${task_description}" file_count=${file_count ?? 'N/A'} ` +
+    `feature=${!!is_new_feature} refactor=${!!is_refactor} bug=${!!is_bug_fix} perf=${!!is_performance} ` +
+    `migration=${!!is_migration} security=${!!is_security}`,
+  );
+
+  // 激进策略：默认 invoke，除非明确是简单任务
+  const shouldInvoke =
+    (file_count !== undefined && file_count >= 2) ||
+    !!is_new_feature ||
+    !!is_refactor ||
+    !!is_bug_fix ||
+    !!is_performance ||
+    !!is_migration ||
+    !!is_security ||
+    task_description.length > 30; // 描述超过 30 字符 → 大概率不是简单任务
+
+  if (!shouldInvoke) {
+    return {
+      should_invoke: false,
+      pipeline_type: null,
+      reason: 'Task appears trivial (very short description, no complexity flags).',
+      task_calls: '',
+    };
+  }
+
+  const pipelineType = determinePipelineType(enriched) || 'feature'; // 默认用 feature pipeline
+  const escapedDesc = escapeDescription(task_description);
+  const taskCalls = PIPELINE_TEMPLATES[pipelineType](escapedDesc);
+
+  const typeLabels: Record<PipelineType, string> = {
+    bug_fix: 'Bug Fix Pipeline (3 agents: investigate → fix → verify)',
+    feature: 'Feature Pipeline (5 agents: analyze → design → develop → test → review)',
+    refactor: 'Refactor Pipeline (4 agents: safety-net → plan → refactor → verify)',
+    investigation: 'Investigation Pipeline (2 agents: reproduce → analyze)',
+    performance: 'Performance Pipeline (4 agents: benchmark → analyze → optimize → verify)',
+    bmad_feature: 'BMAD Feature Pipeline (5 agents: product-analyst → architect → developer → qa → reviewer)',
+    harness_safe_refactor: 'Harness Safe Refactor (5 agents: safety-net → analyzer → planner → executor → validator)',
+    harness_debug: 'Harness Debug Pipeline (5 agents: reproducer → tracer → root-cause → fixer → verifier)',
+    migration: 'Migration Pipeline (5 agents: impact-analyst + safety-net → planner → migrator → verifier)',
+    security_audit: 'Security Audit Pipeline (4 agents: threat-modeler → code-auditor → fixer → verifier)',
+  };
+
+  return {
+    should_invoke: true,
+    pipeline_type: pipelineType,
+    reason: typeLabels[pipelineType],
+    task_calls: taskCalls,
+  };
+}

package/src/skills/tools/skill-invoke.ts

@@ -0,0 +1,168 @@
+/**
+ * SkillInvoke — Agent 动态调用 Skill 的工具实现
+ *
+ * Agent 通过 MCP 工具 `skill_invoke`（snake_case，由 claude-forge MCP 服务器注册）
+ * 调用此函数，获取任何 Skill 的方法论内容。
+ *
+ * 示例（Agent 视角的调用，MCP 协议）：
+ *   skill_invoke({ skill_id: "official-tdd", reason: "需要 TDD 方法论指导" })
+ *   → 返回 TDD 方法论的完整内容
+ *
+ * 调用链路追踪：当 context 里同时提供 storage 和 sessionId 时，每次调用都会
+ * 写入 skill_invocations 表，形成"一次路由 → Agent → N 次 Skill 调用"的证据链。
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { SkillRegistry } from '../registry.js';
+import type { InvocationGuard } from '../invocation-guard.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { logger } from '../../core/utils/logger.js';
+
+export interface SkillInvokeParams {
+  skill_id: string; // Skill ID，如 "official-tdd"
+  reason?: string; // 调用理由（可选，用于审计）
+}
+
+export interface SkillInvokeResult {
+  skill_id: string;
+  skill_name: string;
+  content: string;
+  keywords: string[];
+}
+
+export interface SkillInvokeContext {
+  skillRegistry: SkillRegistry;
+  guard?: InvocationGuard;
+  sessionId?: string;
+  // 追踪链路所需上下文；storage + sessionId 同时存在时写入 skill_invocations。
+  storage?: SQLiteStorage;
+  routeRequestId?: string;
+  agentId?: string;
+  invocationType?: 'static' | 'dynamic' | 'slash_command';
+}
+
+/**
+ * 从 reason 字段解析工作流元信息。
+ *
+ * 支持格式：
+ *   "bmad/analyze"                — workflow=bmad, phase=analyze
+ *   "bmad/design:login-feature"   — workflow=bmad, phase=design, feature_slug=login-feature
+ *   "bmad/analyze:用户认证"        — workflow=bmad, phase=analyze, feature_slug=用户认证（支持中文）
+ *   "其他任意文本 / 中文 / 空"      — 所有字段为 null（向后兼容）
+ *
+ * 大小写归一化：`Bmad/Analyze` → `bmad/analyze`，确保 SQL 聚合稳定。
+ * feature_slug 支持 Unicode 字符（中文、日文等），但建议使用英文以提高可读性。
+ */
+export function parseWorkflowMeta(reason: string | undefined | null): {
+  workflow: string | null;
+  phase: string | null;
+  feature_slug: string | null;
+} {
+  if (!reason) return { workflow: null, phase: null, feature_slug: null };
+
+  // 匹配 "<workflow>/<phase>" 或 "<workflow>/<phase>:<feature-slug>"
+  // workflow/phase 规则：以字母开头，可含字母 / 数字 / 连字符
+  // feature_slug 规则：支持任意非空白、非冒号字符（包括 Unicode）
+  const match = reason.match(/^([a-z][a-z0-9-]*)\/([a-z][a-z0-9-]*)(?::([^\s:]+))?\s*$/iu);
+  if (!match) return { workflow: null, phase: null, feature_slug: null };
+
+  return {
+    workflow: match[1].toLowerCase(),
+    phase: match[2].toLowerCase(),
+    feature_slug: match[3] ? match[3].toLowerCase() : null,
+  };
+}
+
+export async function skillInvoke(
+  params: SkillInvokeParams,
+  context: SkillInvokeContext,
+): Promise<SkillInvokeResult> {
+  const { skill_id, reason } = params;
+  const {
+    guard,
+    sessionId,
+    skillRegistry,
+    storage,
+    routeRequestId,
+    agentId,
+    invocationType = 'dynamic',
+  } = context;
+
+  logger.info(
+    `[SkillInvoke] Agent requested skill: ${skill_id}${reason ? ` (reason: ${reason})` : ''}`,
+  );
+
+  // 记录调用链路的辅助函数：无论成功或失败都应落库（落库失败不影响主流程）。
+  const recordInvocation = (success: boolean, error: string | null, depth: number): void => {
+    if (!storage || !sessionId) return;
+    try {
+      const meta = parseWorkflowMeta(reason);
+      storage.writeSkillInvocation({
+        id: randomUUID(),
+        route_request_id: routeRequestId ?? null,
+        session_id: sessionId,
+        agent_id: agentId ?? null,
+        skill_id,
+        invocation_type: invocationType,
+        reason: reason ?? null,
+        workflow: meta.workflow,
+        phase: meta.phase,
+        feature_slug: meta.feature_slug,
+        artifact_path: null,
+        depth,
+        success: success ? 1 : 0,
+        error,
+        timestamp: Date.now(),
+      });
+    } catch (err) {
+      logger.warn(`[SkillInvoke] Failed to persist invocation record: ${err}`);
+    }
+  };
+
+  // 防护检查（仅当同时提供 guard 和 sessionId 时生效）
+  if (guard && sessionId) {
+    const check = guard.check(sessionId, skill_id);
+    if (!check.allowed) {
+      logger.warn(
+        `[SkillInvoke] Blocked skill=${skill_id} session=${sessionId}: ${check.reason}`,
+      );
+      const stats = guard.getStats(sessionId);
+      recordInvocation(false, `Blocked: ${check.reason}`, stats?.depth ?? 0);
+      throw new Error(`Skill invocation blocked: ${check.reason}`);
+    }
+  }
+
+  let recorded = false;
+  try {
+    const skill = skillRegistry.get(skill_id);
+    if (!skill) {
+      const stats = guard && sessionId ? guard.getStats(sessionId) : null;
+      recordInvocation(false, `Skill not found: ${skill_id}`, stats?.depth ?? 0);
+      throw new Error(
+        `Skill not found: ${skill_id}. Use the \`skill_list\` MCP tool to see available skills.`,
+      );
+    }
+
+    // 通过防护检查后登记调用
+    if (guard && sessionId) {
+      guard.record(sessionId, skill_id);
+      recorded = true;
+    }
+
+    // 成功调用写入追踪链路（depth 由 guard 维护，无 guard 时回落为 0）
+    const stats = guard && sessionId ? guard.getStats(sessionId) : null;
+    recordInvocation(true, null, stats?.depth ?? 0);
+
+    return {
+      skill_id: skill.id,
+      skill_name: skill.name,
+      content: skill.content,
+      keywords: skill.keywords,
+    };
+  } finally {
+    // 仅在已登记时递减深度，避免未记录却减到负数
+    if (recorded && guard && sessionId) {
+      guard.complete(sessionId);
+    }
+  }
+}