@winspan/claude-forge 8.39.0 → 8.50.6

package/src/claudemd/convention-extractor.ts

@@ -0,0 +1,69 @@
+/**
+ * ConventionExtractor — 从 CLAUDE.md 提取项目规范
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CONVENTION_START = '<!-- forge:convention-start';
+const CONVENTION_END = '<!-- forge:convention-end';
+
+export class ConventionExtractor {
+  /**
+   * 从 CLAUDE.md 提取规范内容
+   */
+  extract(projectPath: string): string | null {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    if (!existsSync(claudeMdPath)) return null;
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+
+    // Find convention blocks
+    const conventions: string[] = [];
+    let pos = 0;
+
+    while (true) {
+      const startIdx = content.indexOf(CONVENTION_START, pos);
+      if (startIdx === -1) break;
+
+      const endIdx = content.indexOf(CONVENTION_END, startIdx);
+      if (endIdx === -1) break;
+
+      // Extract content between markers (skip the start marker line)
+      const startLineEnd = content.indexOf('\n', startIdx);
+      if (startLineEnd === -1 || startLineEnd > endIdx) break;
+
+      const block = content.slice(startLineEnd + 1, endIdx).trim();
+      if (block) {
+        conventions.push(block);
+      }
+
+      pos = endIdx + CONVENTION_END.length;
+    }
+
+    if (conventions.length === 0) return null;
+
+    return this.format(conventions);
+  }
+
+  private format(conventions: string[]): string {
+    const lines = [
+      '## 项目规范说明',
+      '',
+      '以下内容用于提供项目背景、原则和协作约束。运行时规则判定以 Convention YAML 为准。',
+      '',
+    ];
+
+    // Merge all convention blocks
+    for (const block of conventions) {
+      lines.push(block);
+      lines.push('');
+    }
+
+    lines.push('---');
+    lines.push('');
+    lines.push('在开始任何工作前，请理解这些项目约束；涉及实际阻断与告警时，以结构化 Convention 规则的判定结果为准。');
+
+    return lines.join('\n');
+  }
+}

package/src/claudemd/index.ts

@@ -0,0 +1,35 @@
+/**
+ * CLAUDE.md Management Module — 统一入口
+ *
+ * 包含 4 个子模块：
+ * - ResumeManager: 续接信息管理（统计式，不调 AI）
+ * - TechDetector: 技术栈检测
+ * - ClaudeMdGenerator: AI 驱动的 CLAUDE.md 生成
+ * - PersonaManager: 技术栈驱动的人设管理
+ */
+
+import type { SQLiteStorage } from '../core/storage/sqlite.js';
+import type { ClaudeProvider } from '../core/ai/provider.js';
+import { ResumeManager } from './resume-manager.js';
+import { ClaudeMdGenerator } from './claudemd-generator.js';
+import { TechDetector } from './tech-detector.js';
+import { PersonaManager } from './persona-manager.js';
+
+export class ClaudeMdManager {
+  readonly resume: ResumeManager;
+  readonly generator: ClaudeMdGenerator;
+  readonly detector: TechDetector;
+  readonly persona: PersonaManager;
+
+  constructor(storage: SQLiteStorage, ai: ClaudeProvider) {
+    this.detector = new TechDetector();
+    this.resume = new ResumeManager(storage);
+    this.generator = new ClaudeMdGenerator(ai, this.detector);
+    this.persona = new PersonaManager();
+  }
+}
+
+export { ResumeManager } from './resume-manager.js';
+export { ClaudeMdGenerator } from './claudemd-generator.js';
+export { TechDetector, type TechStack } from './tech-detector.js';
+export { PersonaManager } from './persona-manager.js';

package/src/claudemd/persona-manager.ts

@@ -0,0 +1,88 @@
+/**
+ * Persona Manager — 技术栈驱动的人设管理
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import type { TechStack } from './tech-detector.js';
+
+const PERSONA_TEMPLATES: Record<string, string> = {
+  'react-typescript': 'Meta 前端架构师，精通 React 和 TypeScript，擅长组件设计和性能优化',
+  'node-express': 'Node.js 后端专家，熟悉 Express 和微服务架构，注重 API 设计和安全性',
+  'next-typescript': 'Next.js 全栈工程师，精通 SSR/SSG，擅长 SEO 优化和性能调优',
+  'vue-typescript': 'Vue.js 前端专家，熟悉 Composition API，注重组件复用和状态管理',
+  'python-fastapi': 'Python 后端工程师，精通 FastAPI 和异步编程，擅长 RESTful API 设计',
+  'python-django': 'Django 全栈开发者，熟悉 ORM 和模板系统，注重安全性和可维护性',
+  'go-backend': 'Go 后端工程师，精通并发编程和微服务，擅长高性能系统设计',
+  'rust-systems': 'Rust 系统工程师，精通内存安全和并发，擅长底层系统开发',
+  'typescript-fullstack': 'TypeScript 全栈工程师，熟悉前后端开发，注重类型安全和代码质量',
+  'javascript-frontend': 'JavaScript 前端开发者，熟悉现代前端工具链，注重用户体验',
+  'python-ml': 'Python 机器学习工程师，精通数据处理和模型训练，擅长 PyTorch/TensorFlow',
+  'java-spring': 'Java 后端专家，精通 Spring Boot 和企业级应用开发',
+  'default': '全栈工程师，熟悉多种技术栈，注重代码质量和最佳实践',
+};
+
+export class PersonaManager {
+  /**
+   * 根据技术栈推断人设
+   */
+  detect(stack: TechStack): string {
+    const lang = stack.language[0]?.toLowerCase() || '';
+    const framework = stack.framework[0]?.toLowerCase() || '';
+
+    // 精确匹配
+    const key = `${framework}-${lang}`.replace(/\s+/g, '-');
+    if (PERSONA_TEMPLATES[key]) {
+      return PERSONA_TEMPLATES[key];
+    }
+
+    // 框架匹配
+    if (framework.includes('react')) return PERSONA_TEMPLATES['react-typescript'];
+    if (framework.includes('next')) return PERSONA_TEMPLATES['next-typescript'];
+    if (framework.includes('vue')) return PERSONA_TEMPLATES['vue-typescript'];
+    if (framework.includes('express')) return PERSONA_TEMPLATES['node-express'];
+    if (framework.includes('fastapi')) return PERSONA_TEMPLATES['python-fastapi'];
+    if (framework.includes('django')) return PERSONA_TEMPLATES['python-django'];
+    if (framework.includes('spring')) return PERSONA_TEMPLATES['java-spring'];
+
+    // 语言匹配
+    if (lang.includes('typescript')) return PERSONA_TEMPLATES['typescript-fullstack'];
+    if (lang.includes('javascript')) return PERSONA_TEMPLATES['javascript-frontend'];
+    if (lang.includes('python')) return PERSONA_TEMPLATES['python-fastapi'];
+    if (lang.includes('go')) return PERSONA_TEMPLATES['go-backend'];
+    if (lang.includes('rust')) return PERSONA_TEMPLATES['rust-systems'];
+
+    return PERSONA_TEMPLATES['default'];
+  }
+
+  /**
+   * 加载人设，优先读取 .forge/persona.md
+   */
+  load(projectPath: string, fallbackStack?: TechStack): string {
+    const personaPath = join(projectPath, '.forge', 'persona.md');
+
+    if (existsSync(personaPath)) {
+      const content = readFileSync(personaPath, 'utf-8').trim();
+      if (content) return content;
+    }
+
+    if (fallbackStack) {
+      return this.detect(fallbackStack);
+    }
+
+    return PERSONA_TEMPLATES['default'];
+  }
+
+  /**
+   * 保存人设到 .forge/persona.md
+   */
+  save(projectPath: string, persona: string): void {
+    const forgeDir = join(projectPath, '.forge');
+    if (!existsSync(forgeDir)) {
+      mkdirSync(forgeDir, { recursive: true });
+    }
+
+    const personaPath = join(forgeDir, 'persona.md');
+    writeFileSync(personaPath, persona.trim(), 'utf-8');
+  }
+}

package/src/claudemd/resume-manager.ts

@@ -0,0 +1,236 @@
+/**
+ * Resume Manager — 统计式生成续接信息（不调 AI）
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { SQLiteStorage, TaskRecord } from '../core/storage/sqlite.js';
+import type { ForgeEvent } from '../core/types.js';
+import {
+  buildForgeResumeEnvelope,
+  stripForgeResumeBlocks,
+  hasForgeResumeBlock,
+  decodeForgeResumeInnerFromClaudeMd,
+} from '../core/utils/forge-resume-block.js';
+import { normalizeTimestamp, timeDiff } from '../core/utils/time.js';
+import { truncateString } from '../core/utils/format.js';
+
+const RESUME_EXPIRY_HOURS = 48;
+
+export class ResumeManager {
+  constructor(private storage: SQLiteStorage) {}
+
+  /**
+   * 统计式生成续接信息（不调 AI）
+   */
+  generate(sessionId: string, projectPath: string): string {
+    // Try to get tasks first (more meaningful than raw events)
+    const tasks = this.storage.queryTasks({ session_id: sessionId, limit: 10 });
+
+    if (tasks.length > 0) {
+      return this.formatFromTasks(tasks, projectPath);
+    }
+
+    // Fallback to events
+    const events = this.storage.queryEvents({
+      session_id: sessionId,
+      project_path: projectPath,
+      limit: 50,
+    });
+
+    if (events.length === 0) {
+      return this.buildEmptyResume();
+    }
+
+    const stats = this.analyze(events);
+    return this.format(stats);
+  }
+
+  /**
+   * 写入 CLAUDE.md 的续接块
+   */
+  save(projectPath: string, content: string): void {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    let existing = '';
+
+    if (existsSync(claudeMdPath)) {
+      existing = readFileSync(claudeMdPath, 'utf-8');
+      existing = stripForgeResumeBlocks(existing);
+    }
+
+    const envelope = buildForgeResumeEnvelope(content);
+    const updated = existing.trimEnd() + '\n\n' + envelope + '\n';
+
+    writeFileSync(claudeMdPath, updated, 'utf-8');
+  }
+
+  /**
+   * 读取续接信息（检查过期）
+   */
+  load(projectPath: string): string | null {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    if (!existsSync(claudeMdPath)) return null;
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    if (!hasForgeResumeBlock(content)) return null;
+
+    const inner = decodeForgeResumeInnerFromClaudeMd(content);
+    if (!inner) return null;
+
+    // 检查时间戳是否过期
+    const timeMatch = inner.match(/_生成时间:\s*(.+)_/);
+    if (timeMatch) {
+      const timestamp = new Date(timeMatch[1]);
+      const age = Date.now() - timestamp.getTime();
+      if (age > RESUME_EXPIRY_HOURS * 3600 * 1000) {
+        return null; // 过期
+      }
+    }
+
+    return inner;
+  }
+
+  /**
+   * 清除续接块
+   */
+  clear(projectPath: string): void {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    if (!existsSync(claudeMdPath)) return;
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    const cleaned = stripForgeResumeBlocks(content);
+    writeFileSync(claudeMdPath, cleaned, 'utf-8');
+  }
+
+  // ── Private Methods ────────────────────────────────────────────────────
+
+  private analyze(events: ForgeEvent[]): ResumeStats {
+    const toolCounts = new Map<string, number>();
+    const editedFiles = new Set<string>();
+    const userPrompts: string[] = [];
+
+    for (const e of events) {
+      if (e.tool_name) {
+        toolCounts.set(e.tool_name, (toolCounts.get(e.tool_name) ?? 0) + 1);
+      }
+
+      if (e.tool_name && ['Edit', 'Write'].includes(e.tool_name)) {
+        const fp = e.tool_input?.file_path as string | undefined;
+        if (fp) editedFiles.add(fp);
+      }
+
+      if (e.user_prompt && userPrompts.length < 3) {
+        userPrompts.push(truncateString(e.user_prompt, 100));
+      }
+    }
+
+    return {
+      toolCounts,
+      editedFiles,
+      userPrompts,
+      lastTimestamp: events[0]?.timestamp,
+    };
+  }
+
+  private formatFromTasks(tasks: TaskRecord[], projectPath: string): string {
+    const recentTasks = [...tasks].sort((a, b) => new Date(b.start_time).getTime() - new Date(a.start_time).getTime());
+    const lines = ['## 上次工作续接', ''];
+
+    // Find the last task (most recent)
+    const lastTask = recentTasks[0];
+    if (lastTask) {
+      lines.push('⚠️ **IMPORTANT: 在开始新任务前，请先检查以下上下文**');
+      lines.push('');
+      lines.push('**上次在做**:');
+      lines.push(`- ${lastTask.title}`);
+      if (lastTask.status !== 'completed') {
+        lines.push(`  状态: ${lastTask.status === 'active' ? '⏳ 进行中（应优先完成）' : '📋 待处理'}`);
+      }
+      lines.push('');
+    }
+
+    // List all incomplete tasks
+    const incomplete = recentTasks.filter(t => t.status !== 'completed').slice(0, 3);
+    if (incomplete.length > 0) {
+      lines.push('**未完成任务（如果用户请求与这些相关，应优先完成）**:');
+      for (const t of incomplete) {
+        lines.push(`- ${t.title}`);
+      }
+      if (recentTasks.filter(t => t.status !== 'completed').length > 3) {
+        lines.push(`  ... 还有 ${recentTasks.filter(t => t.status !== 'completed').length - 3} 个`);
+      }
+      lines.push('');
+    }
+
+    // Time
+    if (lastTask?.end_time || lastTask?.start_time) {
+      const time = this.formatRelativeTime(lastTask.end_time || lastTask.start_time);
+      lines.push(`**上次活跃**: ${time}`);
+    }
+
+    lines.push('', `_生成时间: ${new Date().toISOString()}_`);
+    return lines.join('\n');
+  }
+
+  private format(stats: ResumeStats): string {
+    const lines = ['## 上次工作续接', ''];
+
+    // 用户最近指令（最有价值的上下文）
+    if (stats.userPrompts.length > 0) {
+      lines.push('⚠️ **IMPORTANT: 在开始新任务前，请先检查以下上下文**');
+      lines.push('');
+      lines.push('**上次在做**:');
+      for (const p of stats.userPrompts) {
+        lines.push(`- ${p}${p.length >= 100 ? '...' : ''}`);
+      }
+      lines.push('');
+      lines.push('如果用户的新请求与上述工作相关，应优先完成未完成的工作。');
+      lines.push('');
+    }
+
+    // 文件变更（只列文件名，不列完整路径）
+    if (stats.editedFiles.size > 0) {
+      const files = [...stats.editedFiles]
+        .slice(0, 5)
+        .map(f => f.split('/').slice(-2).join('/'));
+      lines.push(`**改了哪些文件**: ${files.join(', ')}`);
+    }
+
+    // 时间戳
+    if (stats.lastTimestamp) {
+      const time = this.formatRelativeTime(stats.lastTimestamp);
+      lines.push(`**上次活跃**: ${time}`);
+    }
+
+    lines.push('', `_生成时间: ${new Date().toISOString()}_`);
+    return lines.join('\n');
+  }
+
+  private buildEmptyResume(): string {
+    return [
+      '## 上次工作续接',
+      '',
+      '暂无工作记录。',
+      '',
+      `_生成时间: ${new Date().toISOString()}_`,
+    ].join('\n');
+  }
+
+  private formatRelativeTime(isoTime: string): string {
+    const normalized = normalizeTimestamp(isoTime);
+    const diff = Date.now() - new Date(normalized).getTime();
+    const mins = Math.floor(diff / 60000);
+    if (mins < 1) return '刚刚';
+    if (mins < 60) return `${mins} 分钟前`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24) return `${hours} 小时前`;
+    return `${Math.floor(hours / 24)} 天前`;
+  }
+}
+
+interface ResumeStats {
+  toolCounts: Map<string, number>;
+  editedFiles: Set<string>;
+  userPrompts: string[];
+  lastTimestamp?: string;
+}

package/src/claudemd/tech-detector.ts

@@ -0,0 +1,220 @@
+/**
+ * Tech Stack Detector — 精简版技术栈检测
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface TechStack {
+  language: string[];
+  framework: string[];
+  packageManager: string;
+  testFramework?: string;
+  linter?: string;
+}
+
+const FRAMEWORK_MAP: Record<string, string> = {
+  react: 'React',
+  'react-dom': 'React',
+  next: 'Next.js',
+  vue: 'Vue',
+  express: 'Express',
+  fastify: 'Fastify',
+  '@nestjs/core': 'NestJS',
+};
+
+const TEST_MAP: Record<string, string> = {
+  vitest: 'Vitest',
+  jest: 'Jest',
+  mocha: 'Mocha',
+  pytest: 'pytest',
+};
+
+const LINTER_MAP: Record<string, string> = {
+  eslint: 'ESLint',
+  '@eslint/js': 'ESLint',
+  biome: 'Biome',
+};
+
+export class TechDetector {
+  detect(projectPath: string): TechStack {
+    const stack: TechStack = {
+      language: [],
+      framework: [],
+      packageManager: 'npm',
+    };
+
+    this.detectJava(projectPath, stack);
+    this.detectPackageJson(projectPath, stack);
+    this.detectTypeScript(projectPath, stack);
+    this.detectGo(projectPath, stack);
+    this.detectRust(projectPath, stack);
+    this.detectPython(projectPath, stack);
+
+    return stack;
+  }
+
+  private detectPackageJson(projectPath: string, stack: TechStack): void {
+    const pkgPath = join(projectPath, 'package.json');
+    if (!existsSync(pkgPath)) return;
+
+    const pkg = this.readJson(pkgPath);
+    if (!pkg) return;
+
+    stack.language.push('JavaScript');
+
+    // Package manager
+    if (existsSync(join(projectPath, 'pnpm-lock.yaml'))) {
+      stack.packageManager = 'pnpm';
+    } else if (existsSync(join(projectPath, 'yarn.lock'))) {
+      stack.packageManager = 'yarn';
+    } else if (existsSync(join(projectPath, 'bun.lockb'))) {
+      stack.packageManager = 'bun';
+    }
+
+    const allDeps: Record<string, unknown> = {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+    };
+
+    // Frameworks
+    for (const [dep, name] of Object.entries(FRAMEWORK_MAP)) {
+      if (dep in allDeps && !stack.framework.includes(name)) {
+        stack.framework.push(name);
+      }
+    }
+
+    // Test framework
+    for (const [dep, name] of Object.entries(TEST_MAP)) {
+      if (dep in allDeps) {
+        stack.testFramework = name;
+        break;
+      }
+    }
+
+    // Linter
+    for (const [dep, name] of Object.entries(LINTER_MAP)) {
+      if (dep in allDeps) {
+        stack.linter = name;
+        break;
+      }
+    }
+  }
+
+  private detectTypeScript(projectPath: string, stack: TechStack): void {
+    if (existsSync(join(projectPath, 'tsconfig.json'))) {
+      const idx = stack.language.indexOf('JavaScript');
+      if (idx !== -1) {
+        stack.language[idx] = 'TypeScript';
+      } else {
+        stack.language.push('TypeScript');
+      }
+    }
+  }
+
+  private detectGo(projectPath: string, stack: TechStack): void {
+    const goModPath = join(projectPath, 'go.mod');
+    if (!existsSync(goModPath)) return;
+
+    const content = readFileSync(goModPath, 'utf-8');
+    const versionMatch = content.match(/^go\s+(\S+)/m);
+    stack.language.push(versionMatch ? `Go ${versionMatch[1]}` : 'Go');
+    stack.packageManager = 'go mod';
+    stack.testFramework = 'go test';
+  }
+
+  private detectRust(projectPath: string, stack: TechStack): void {
+    if (existsSync(join(projectPath, 'Cargo.toml'))) {
+      stack.language.push('Rust');
+      stack.packageManager = 'cargo';
+      stack.testFramework = 'cargo test';
+    }
+  }
+
+  private detectPython(projectPath: string, stack: TechStack): void {
+    const hasPyproject = existsSync(join(projectPath, 'pyproject.toml'));
+    const hasRequirements = existsSync(join(projectPath, 'requirements.txt'));
+
+    if (!hasPyproject && !hasRequirements) return;
+
+    stack.language.push('Python');
+
+    if (existsSync(join(projectPath, 'poetry.lock'))) {
+      stack.packageManager = 'poetry';
+    } else if (existsSync(join(projectPath, 'Pipfile.lock'))) {
+      stack.packageManager = 'pipenv';
+    } else {
+      stack.packageManager = 'pip';
+    }
+
+    if (hasPyproject) {
+      const content = readFileSync(join(projectPath, 'pyproject.toml'), 'utf-8');
+      if (content.includes('pytest')) {
+        stack.testFramework = 'pytest';
+      }
+    }
+  }
+
+  private detectJava(projectPath: string, stack: TechStack): void {
+    const hasPom = existsSync(join(projectPath, 'pom.xml'));
+    const hasGradle = existsSync(join(projectPath, 'build.gradle')) || existsSync(join(projectPath, 'build.gradle.kts'));
+
+    if (!hasPom && !hasGradle) return;
+
+    stack.language.push('Java');
+
+    if (hasGradle) {
+      stack.packageManager = 'gradle';
+      stack.testFramework = 'JUnit';
+
+      // Detect Kotlin
+      if (existsSync(join(projectPath, 'build.gradle.kts'))) {
+        stack.language.push('Kotlin');
+      }
+
+      // Detect Spring Boot from build.gradle
+      try {
+        const gradleFile = existsSync(join(projectPath, 'build.gradle.kts'))
+          ? join(projectPath, 'build.gradle.kts')
+          : join(projectPath, 'build.gradle');
+        const content = readFileSync(gradleFile, 'utf-8');
+        if (content.includes('spring-boot') || content.includes('org.springframework')) {
+          stack.framework.push('Spring Boot');
+        }
+        if (content.includes('mybatis')) {
+          stack.framework.push('MyBatis');
+        }
+      } catch { /* ignore */ }
+    } else if (hasPom) {
+      stack.packageManager = 'maven';
+      stack.testFramework = 'JUnit';
+
+      // Detect frameworks from pom.xml
+      try {
+        const content = readFileSync(join(projectPath, 'pom.xml'), 'utf-8');
+        if (content.includes('spring-boot') || content.includes('org.springframework')) {
+          stack.framework.push('Spring Boot');
+        }
+        if (content.includes('mybatis')) {
+          stack.framework.push('MyBatis');
+        }
+        if (content.includes('dubbo')) {
+          stack.framework.push('Dubbo');
+        }
+        // Detect Java version
+        const javaVersionMatch = content.match(/<java\.version>(\d+)<\/java\.version>/);
+        if (javaVersionMatch) {
+          stack.language[stack.language.indexOf('Java')] = `Java ${javaVersionMatch[1]}`;
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  private readJson(filePath: string): Record<string, unknown> | null {
+    try {
+      return JSON.parse(readFileSync(filePath, 'utf-8'));
+    } catch {
+      return null;
+    }
+  }
+}