@winspan/claude-forge 8.53.2 → 8.54.3

package/src/skills/upgrade-engine.ts

@@ -1,541 +0,0 @@
-/**
- * upgrade-engine.ts
- *
- * Orchestrates the AI-assisted official skill upgrade pipeline.
- * Does NOT contain AI prompt strings — those live in upgrade-prompt.ts.
- */
-
-import { execSync, exec } from 'node:child_process';
-import { promises as fs, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { promisify } from 'node:util';
-import matter from 'gray-matter';
-import type { OfficialSkill } from './official-skills.js';
-import { buildEvaluationPrompt } from './upgrade-prompt.js';
-import type { ClaudeProvider } from '../core/ai/provider.js';
-import { logger } from '../core/utils/logger.js';
-
-const execAsync = promisify(exec);
-
-// ── Public types ────────────────────────────────────────────────────────────
-
-export interface CandidateSkill {
-  id: string;
-  source: string;        // 'agent-skills' | 'superpowers'
-  filePath: string;
-  name: string;
-  description: string;
-  keywords: string[];
-  content: string;
-}
-
-export interface MatchResult {
-  officialId: string;
-  score: number;         // 0-100
-}
-
-export type UpgradeAction = 'upgrade' | 'merge' | 'skip';
-
-export interface UpgradeDecision {
-  action: UpgradeAction;
-  confidence: number;    // 0-100
-  reasoning: string;
-  merged_content: string | null;
-}
-
-export interface ReportEntry {
-  officialId: string;
-  candidateId: string;
-  candidateSource: string;
-  action: UpgradeAction | 'error' | 'needs_review';
-  confidence: number;
-  reasoning: string;
-  candidateFilePath: string;
-  merged_content: string | null;
-}
-
-// ── Default candidate sources ───────────────────────────────────────────────
-
-export const DEFAULT_SOURCES: Array<{ name: string; url: string }> = [
-  { name: 'agent-skills', url: 'https://github.com/addyosmani/agent-skills.git' },
-  { name: 'superpowers',  url: 'https://github.com/obra/superpowers.git' },
-];
-
-// ── Helpers ─────────────────────────────────────────────────────────────────
-
-/**
- * Parse a .md file into a CandidateSkill.
- * If frontmatter is missing, falls back to filename-based id.
- */
-function parseCandidateFile(filePath: string, sourceName: string): CandidateSkill | null {
-  try {
-    const raw = readFileSync(filePath, 'utf-8');
-    const parsed = matter(raw);
-    const { data } = parsed;
-
-    const fileName = path.basename(filePath, '.md');
-    const id = typeof data.name === 'string' ? data.name : fileName;
-    const name = typeof data.name === 'string' ? data.name : fileName;
-    const description = typeof data.description === 'string' ? data.description : '';
-
-    const rawKeywords: unknown = data.keywords ?? data.tags;
-    const keywords: string[] = Array.isArray(rawKeywords)
-      ? rawKeywords.filter((k): k is string => typeof k === 'string')
-      : [];
-
-    return {
-      id,
-      source: sourceName,
-      filePath,
-      name,
-      description,
-      keywords,
-      content: raw,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Recursively scan a directory for .md files.
- * Supports both directory/SKILL.md format (agent-skills) and flat *.md format.
- */
-async function scanMdFiles(dir: string): Promise<string[]> {
-  const results: string[] = [];
-
-  async function walk(current: string): Promise<void> {
-    let entries: import('node:fs').Dirent[];
-    try {
-      entries = await fs.readdir(current, { withFileTypes: true });
-    } catch {
-      return;
-    }
-
-    for (const entry of entries) {
-      const fullPath = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        // Check for SKILL.md inside this directory (agent-skills format)
-        const skillMd = path.join(fullPath, 'SKILL.md');
-        try {
-          await fs.access(skillMd);
-          results.push(skillMd);
-        } catch {
-          // Recurse into sub-directories that don't have SKILL.md directly
-          await walk(fullPath);
-        }
-      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md') {
-        results.push(fullPath);
-      }
-    }
-  }
-
-  await walk(dir);
-  return results;
-}
-
-// ── Exported pipeline functions ─────────────────────────────────────────────
-
-/**
- * Clone or pull each source into `candidatesDir/<source.name>/`, then scan
- * all .md files and parse them into CandidateSkill objects.
- * Individual source failures are caught and logged; they do not abort the run.
- */
-export async function pullCandidates(
-  sources: Array<{ name: string; url: string }>,
-  candidatesDir: string,
-): Promise<CandidateSkill[]> {
-  await fs.mkdir(candidatesDir, { recursive: true });
-
-  const candidates: CandidateSkill[] = [];
-
-  for (const source of sources) {
-    const targetDir = path.join(candidatesDir, source.name);
-
-    let exists = false;
-    try {
-      await fs.access(targetDir);
-      exists = true;
-    } catch { /* not exists */ }
-
-    // Try pull/clone, but don't abort scan if pull fails on existing dir
-    try {
-      if (exists) {
-        logger.info(`[upgrade] Pulling ${source.name}...`);
-        await execAsync(`git -C "${targetDir}" pull --ff-only`, { timeout: 60_000 });
-      } else {
-        logger.info(`[upgrade] Cloning ${source.name}...`);
-        await execAsync(`git clone --depth=1 "${source.url}" "${targetDir}"`, { timeout: 120_000 });
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (exists) {
-        logger.warn(`[upgrade] ${source.name} pull failed (using existing checkout): ${msg}`);
-      } else {
-        logger.warn(`[upgrade] ${source.name} clone failed, skipping: ${msg}`);
-        continue;
-      }
-    }
-
-    // Always scan if dir exists (even when pull fails — old checkout is better than nothing)
-    try {
-      const mdFiles = await scanMdFiles(targetDir);
-      for (const filePath of mdFiles) {
-        const candidate = parseCandidateFile(filePath, source.name);
-        if (candidate) {
-          candidates.push(candidate);
-        }
-      }
-      logger.info(`[upgrade] ${source.name}: ${mdFiles.length} .md files found`);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      logger.warn(`[upgrade] Skipping source ${source.name}: ${msg}`);
-    }
-  }
-
-  return candidates;
-}
-
-/**
- * Match a candidate skill to the best official skill using keyword + name token
- * overlap. Returns null if the best score is below the 30-point threshold.
- */
-export function matchToOfficial(
-  candidate: CandidateSkill,
-  officialSkills: OfficialSkill[],
-): MatchResult | null {
-  /** Tokenise a string into lowercase words / tokens. */
-  function tokenise(text: string): Set<string> {
-    return new Set(
-      text
-        .toLowerCase()
-        .replace(/[^a-z0-9一-鿿\s-]/g, ' ')
-        .split(/[\s-]+/)
-        .filter((t) => t.length > 1),
-    );
-  }
-
-  /** Jaccard-like overlap score (0–100). */
-  function overlapScore(aSet: Set<string>, bSet: Set<string>): number {
-    if (aSet.size === 0 && bSet.size === 0) return 0;
-    let intersection = 0;
-    for (const t of aSet) {
-      if (bSet.has(t)) intersection++;
-    }
-    const union = new Set([...aSet, ...bSet]).size;
-    return union === 0 ? 0 : Math.round((intersection / union) * 100);
-  }
-
-  const candidateKeywordTokens = tokenise(candidate.keywords.join(' '));
-  const candidateNameTokens = tokenise(candidate.name + ' ' + candidate.description);
-
-  let best: MatchResult | null = null;
-
-  for (const official of officialSkills) {
-    const officialKeywordTokens = tokenise(official.keywords.join(' '));
-    const officialNameTokens = tokenise(official.name + ' ' + official.description);
-
-    // keyword overlap (weight 60) + name/description token overlap (weight 40)
-    const keywordScore = overlapScore(candidateKeywordTokens, officialKeywordTokens);
-    const nameScore = overlapScore(candidateNameTokens, officialNameTokens);
-    let combined = Math.round(keywordScore * 0.6 + nameScore * 0.4);
-
-    // Substring boost: candidate id/name contains official keyword (or vice versa)
-    // helps with English↔中文 token mismatch (e.g. "debugging" ↔ "debug"/"调试")
-    const candidateText = (candidate.id + ' ' + candidate.name + ' ' + candidate.description).toLowerCase();
-    const officialText = (official.name + ' ' + official.description).toLowerCase();
-    for (const kw of official.keywords) {
-      const kwLower = kw.toLowerCase();
-      if (kwLower.length >= 3 && candidateText.includes(kwLower)) {
-        combined = Math.max(combined, 50);
-        break;
-      }
-    }
-    for (const kw of candidate.keywords) {
-      const kwLower = kw.toLowerCase();
-      if (kwLower.length >= 3 && officialText.includes(kwLower)) {
-        combined = Math.max(combined, 50);
-        break;
-      }
-    }
-
-    if (combined >= 15) {
-      if (!best || combined > best.score) {
-        best = { officialId: official.name, score: combined };
-      }
-    }
-  }
-
-  return best;
-}
-
-/**
- * Ask the AI provider to evaluate whether a candidate should upgrade / merge /
- * skip the matched official skill. Returns a parsed UpgradeDecision.
- *
- * On JSON parse failure → returns { action: 'skip', confidence: 0, reasoning:
- * 'AI response could not be parsed', merged_content: null } with needs_review=true
- * embedded in the reasoning (caller promotes to needs_review).
- */
-export async function evaluateWithAI(
-  candidate: CandidateSkill,
-  official: OfficialSkill,
-  aiProvider: ClaudeProvider,
-): Promise<UpgradeDecision & { needs_review?: boolean }> {
-  const { system, user } = buildEvaluationPrompt(candidate, official);
-
-  let raw: string;
-  try {
-    raw = await aiProvider.complete(user, {
-      system,
-      maxTokens: 1200,
-      timeoutMs: 45_000,
-      maxRetries: 2,
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      action: 'skip',
-      confidence: 0,
-      reasoning: `AI 调用失败: ${msg}`,
-      merged_content: null,
-      needs_review: true,
-    };
-  }
-
-  // Strip markdown code fences if model wrapped the JSON
-  const stripped = raw
-    .replace(/^```(?:json)?\s*/im, '')
-    .replace(/\s*```$/im, '')
-    .trim();
-
-  try {
-    const parsed = JSON.parse(stripped) as Record<string, unknown>;
-
-    const validActions = new Set<string>(['upgrade', 'merge', 'skip']);
-    const action = typeof parsed.action === 'string' && validActions.has(parsed.action)
-      ? (parsed.action as UpgradeAction)
-      : 'skip';
-
-    const confidence =
-      typeof parsed.confidence === 'number'
-        ? Math.max(0, Math.min(100, parsed.confidence))
-        : 0;
-
-    const reasoning =
-      typeof parsed.reasoning === 'string' ? parsed.reasoning : '';
-
-    const merged_content =
-      typeof parsed.merged_content === 'string' ? parsed.merged_content : null;
-
-    return { action, confidence, reasoning, merged_content };
-  } catch {
-    return {
-      action: 'skip',
-      confidence: 0,
-      reasoning: `AI 返回内容无法解析为 JSON，需人工审核。原始响应片段: ${stripped.slice(0, 200)}`,
-      merged_content: null,
-      needs_review: true,
-    };
-  }
-}
-
-/**
- * Write the upgrade report as a markdown file with embedded HTML comment
- * machine markers for `applyDecisions` to parse.
- */
-export async function generateReport(
-  entries: ReportEntry[],
-  outputPath: string,
-  stats: { total: number; matched: number; unmatched: number },
-): Promise<void> {
-  const now = new Date();
-  const timestamp = now.toISOString().replace('T', ' ').slice(0, 16);
-
-  const actionCounts = { upgrade: 0, merge: 0, skip: 0, error: 0, needs_review: 0 };
-  for (const e of entries) {
-    if (e.action in actionCounts) {
-      actionCounts[e.action as keyof typeof actionCounts]++;
-    }
-  }
-
-  const lines: string[] = [
-    '# Skill Upgrade Report',
-    '',
-    `Generated: ${timestamp}`,
-    '',
-    '## Summary',
-    '',
-    '| Metric | Count |',
-    '|--------|-------|',
-    `| Candidates scanned | ${stats.total} |`,
-    `| Matched to official | ${stats.matched} |`,
-    `| Action: upgrade | ${actionCounts.upgrade} |`,
-    `| Action: merge | ${actionCounts.merge} |`,
-    `| Action: skip | ${actionCounts.skip} |`,
-    `| Needs review | ${actionCounts.needs_review} |`,
-    `| Error | ${actionCounts.error} |`,
-    `| Unmatched | ${stats.unmatched} |`,
-    '',
-    '## Per-Skill Decisions',
-    '',
-  ];
-
-  for (const entry of entries) {
-    lines.push(`### ${entry.officialId}`);
-    lines.push(`- **Action**: ${entry.action}`);
-    lines.push(`- **Confidence**: ${entry.confidence}%`);
-    lines.push(`- **Candidate**: \`${entry.candidateSource}/${entry.candidateId}\``);
-    lines.push(`- **Candidate path**: \`${entry.candidateFilePath}\``);
-    lines.push(`- **Reasoning**: ${entry.reasoning}`);
-
-    // Machine-readable marker for applyDecisions
-    lines.push('');
-    lines.push(`<!-- upgrade-entry: ${entry.officialId} | ${entry.candidateFilePath} | ${entry.action} -->`);
-
-    if (entry.action === 'merge' && entry.merged_content) {
-      lines.push('');
-      lines.push('<!-- merged-content-begin -->');
-      lines.push(entry.merged_content);
-      lines.push('<!-- merged-content-end -->');
-    }
-
-    lines.push('');
-  }
-
-  await fs.mkdir(path.dirname(outputPath), { recursive: true });
-  await fs.writeFile(outputPath, lines.join('\n'), 'utf-8');
-  logger.info(`[upgrade] Report written to ${outputPath}`);
-}
-
-/**
- * Apply the decisions recorded in a report file to the official skills directory.
- *
- * Safety checks:
- * 1. `git status --porcelain <officialDir>` must be clean
- * 2. Full backup created in `backupBaseDir/<YYYYMMDD-HHMM>/` (conflict → -2/-3)
- *
- * Returns { applied, skipped, backupPath }.
- */
-export async function applyDecisions(
-  reportPath: string,
-  officialDir: string,
-  backupBaseDir: string,
-): Promise<{ applied: number; skipped: number; backupPath: string }> {
-  // 1. Check git working tree is clean
-  try {
-    const { stdout } = await execAsync(`git status --porcelain "${officialDir}"`);
-    if (stdout.trim().length > 0) {
-      throw new Error(
-        `Working tree is dirty in ${officialDir}. Commit or stash changes before applying.\n${stdout}`,
-      );
-    }
-  } catch (err) {
-    // If git is not available or it's not a repo, rethrow only for dirty-tree errors
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes('Working tree is dirty')) throw err;
-    logger.warn(`[upgrade] git status check failed (not a git repo?): ${msg}`);
-  }
-
-  // 2. Create timestamped backup directory
-  const ts = new Date()
-    .toISOString()
-    .replace(/[-:]/g, '')
-    .replace('T', '-')
-    .slice(0, 13); // YYYYMMDD-HHM -> need YYYYMMDD-HHMM format
-  const tsFormatted = (() => {
-    const d = new Date();
-    const YYYY = d.getFullYear();
-    const MM = String(d.getMonth() + 1).padStart(2, '0');
-    const DD = String(d.getDate()).padStart(2, '0');
-    const HH = String(d.getHours()).padStart(2, '0');
-    const mm = String(d.getMinutes()).padStart(2, '0');
-    return `${YYYY}${MM}${DD}-${HH}${mm}`;
-  })();
-
-  let backupPath = path.join(backupBaseDir, tsFormatted);
-  // Handle conflict: try -2, -3, ...
-  let suffix = 2;
-  while (true) {
-    try {
-      await fs.access(backupPath);
-      // Directory exists — try next suffix
-      backupPath = path.join(backupBaseDir, `${tsFormatted}-${suffix}`);
-      suffix++;
-    } catch {
-      break; // doesn't exist, we can use it
-    }
-  }
-  await fs.mkdir(backupPath, { recursive: true });
-
-  // Copy all .md files from officialDir into backup
-  const officialFiles = (await fs.readdir(officialDir)).filter((f) => f.endsWith('.md'));
-  for (const file of officialFiles) {
-    await fs.copyFile(path.join(officialDir, file), path.join(backupPath, file));
-  }
-  logger.info(`[upgrade] Backed up ${officialFiles.length} files to ${backupPath}`);
-
-  // 3. Parse report
-  const reportContent = await fs.readFile(reportPath, 'utf-8');
-
-  // Parse <!-- upgrade-entry: id | path | action --> markers
-  const entryPattern = /<!-- upgrade-entry: (.+?) \| (.+?) \| (.+?) -->/g;
-  let match: RegExpExecArray | null;
-
-  const entries: Array<{ officialId: string; candidatePath: string; action: string }> = [];
-  while ((match = entryPattern.exec(reportContent)) !== null) {
-    entries.push({
-      officialId: match[1].trim(),
-      candidatePath: match[2].trim(),
-      action: match[3].trim(),
-    });
-  }
-
-  // Parse merged content blocks
-  const mergedContentMap = new Map<string, string>();
-  // Associate merged-content blocks with the preceding entry
-  const mergedPattern =
-    /<!-- upgrade-entry: (.+?) \| (.+?) \| merge -->[\s\S]*?<!-- merged-content-begin -->\n([\s\S]*?)\n<!-- merged-content-end -->/g;
-  while ((match = mergedPattern.exec(reportContent)) !== null) {
-    mergedContentMap.set(match[1].trim(), match[3]);
-  }
-
-  let applied = 0;
-  let skipped = 0;
-
-  for (const entry of entries) {
-    if (entry.action === 'skip' || entry.action === 'error' || entry.action === 'needs_review') {
-      skipped++;
-      continue;
-    }
-
-    const targetFile = path.join(officialDir, `${entry.officialId}.md`);
-
-    try {
-      if (entry.action === 'upgrade') {
-        // Copy candidate file content
-        const candidateContent = await fs.readFile(entry.candidatePath, 'utf-8');
-        await fs.writeFile(targetFile, candidateContent, 'utf-8');
-        applied++;
-        logger.info(`[upgrade] Applied upgrade: ${entry.officialId}`);
-      } else if (entry.action === 'merge') {
-        const mergedContent = mergedContentMap.get(entry.officialId);
-        if (mergedContent) {
-          await fs.writeFile(targetFile, mergedContent, 'utf-8');
-          applied++;
-          logger.info(`[upgrade] Applied merge: ${entry.officialId}`);
-        } else {
-          logger.warn(`[upgrade] Merge entry ${entry.officialId} has no merged content; skipping`);
-          skipped++;
-        }
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      logger.error(`[upgrade] Failed to apply ${entry.officialId}: ${msg}`);
-      skipped++;
-    }
-  }
-
-  logger.info(`[upgrade] Apply complete: ${applied} applied, ${skipped} skipped`);
-  return { applied, skipped, backupPath };
-}

package/src/skills/upgrade-prompt.ts

@@ -1,84 +0,0 @@
-/**
- * upgrade-prompt.ts
- *
- * Builds the system + user prompts for AI-assisted skill evaluation.
- * Pure functions — no I/O, no side effects.
- */
-
-import type { CandidateSkill } from './upgrade-engine.js';
-import type { OfficialSkill } from './official-skills.js';
-
-const MAX_CONTENT_CHARS = 2000;
-
-/**
- * Truncate content to at most `maxChars` characters, appending an ellipsis
- * marker so the model knows the text was cut.
- */
-function truncate(text: string, maxChars = MAX_CONTENT_CHARS): string {
-  if (text.length <= maxChars) return text;
-  return text.slice(0, maxChars) + '\n\n...[content truncated]';
-}
-
-/**
- * Build system + user prompts for evaluating whether a candidate skill should
- * upgrade, merge with, or skip an official skill.
- *
- * The system prompt defines the decision criteria and output JSON contract.
- * The user prompt contains the two skill bodies (capped at 2000 chars each).
- */
-export function buildEvaluationPrompt(
-  candidate: CandidateSkill,
-  official: OfficialSkill,
-): { system: string; user: string } {
-  const system = `你是 Claude Code skill 内容评估专家。
-
-你的任务是比较"候选 skill"和"官方 skill"，决定如何处理。
-
-## 评估维度
-- **主题重叠度**：两个 skill 覆盖的领域是否高度相关
-- **内容质量**：深度、广度、实例丰富程度、可操作性
-- **互补性**：候选是否包含官方 skill 未涵盖的独特章节
-
-## 决策标准
-- **skip**：主题不重叠，或官方 skill 已完整覆盖候选内容，合并无额外价值
-- **upgrade**：候选覆盖官方 skill 的全部核心要点，且整体质量明显更高（深度/广度提升 ≥30%），用候选直接替换官方版本
-- **merge**：主题相同但各有独特章节，合并后整体价值更高，需要生成合并后完整内容
-
-## 输出格式
-必须返回严格的 JSON，不含任何其他文本、代码块标记或注释：
-{"action":"upgrade|merge|skip","confidence":0-100,"reasoning":"简短中文说明（<200字）","merged_content":null或合并后完整md字符串}
-
-## merged_content 规则
-- action = merge  → 提供合并后的完整 .md 文件内容（含 frontmatter）
-- action = upgrade → null（直接使用候选原文）
-- action = skip   → null`;
-
-  const user = `## 官方 Skill（目标）
-
-**ID**: ${official.name}
-**描述**: ${official.description}
-**关键词**: ${official.keywords.join(', ') || '（无）'}
-
-\`\`\`markdown
-${truncate(official.content)}
-\`\`\`
-
----
-
-## 候选 Skill（来源: ${candidate.source}）
-
-**ID**: ${candidate.id}
-**名称**: ${candidate.name}
-**描述**: ${candidate.description}
-**关键词**: ${candidate.keywords.join(', ') || '（无）'}
-
-\`\`\`markdown
-${truncate(candidate.content)}
-\`\`\`
-
----
-
-请评估候选 skill 相对于官方 skill 的升级价值，返回 JSON。`;
-
-  return { system, user };
-}

package/src/templates/go.yaml

@@ -1,53 +0,0 @@
-# Go Project Template
-# 为 Go 项目提供开箱即用的规则配置
-
-name: "Go Project"
-description: "Go 项目的推荐规则配置，包含 goroutine 管理、错误处理、并发安全等"
-version: "1.0.0"
-
-# 启用的规则文件
-conventions:
-  - go-best-practices
-  - basic-security
-  - git-safety
-
-# 项目配置
-config:
-  # 文件扩展名
-  file_extensions:
-    - .go
-
-  # 忽略的目录
-  ignore_paths:
-    - vendor/
-    - bin/
-    - .git/
-    - testdata/
-
-  # 推荐的工具
-  recommended_tools:
-    - golangci-lint
-    - gofmt
-    - go vet
-    - staticcheck
-
-# 初始化脚本
-init_commands:
-  - go mod download
-  - go build ./...
-
-# 推荐的 Makefile targets
-recommended_make_targets:
-  lint: "golangci-lint run"
-  fmt: "gofmt -s -w ."
-  test: "go test -v -race -coverprofile=coverage.out ./..."
-  build: "go build -o bin/app ./cmd/app"
-
-# 文档链接
-documentation:
-  - name: "Go 官方文档"
-    url: "https://go.dev/doc/"
-  - name: "Effective Go"
-    url: "https://go.dev/doc/effective_go"
-  - name: "Go Code Review Comments"
-    url: "https://github.com/golang/go/wiki/CodeReviewComments"