@winspan/claude-forge 8.41.0 → 8.51.0

package/src/claudemd/claudemd-generator.ts

@@ -0,0 +1,568 @@
+/**
+ * CLAUDE.md Generator — AI 驱动的 CLAUDE.md 生成与管理
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ClaudeProvider } from '../core/ai/provider.js';
+import { TechDetector, type TechStack } from './tech-detector.js';
+
+const AUTO_START = '<!-- forge:claudemd-auto -->';
+const AUTO_END = '<!-- forge:end-claudemd-auto -->';
+
+/**
+ * Swarm Protocol — fixed CLAUDE.md preface injected into every project.
+ *
+ * Loaded from `templates/swarm-protocol.md` (same directory as this module's
+ * compiled output). `fileURLToPath(import.meta.url)` resolves to either
+ * `src/claudemd/` (dev via tsx) or `dist/claudemd/` (npm install) — both
+ * have a sibling `templates/` directory after build (see package.json `build`
+ * script which copies *.md into dist/claudemd/templates/).
+ *
+ * Cached at module level: the file is read at most once per process.
+ */
+let _swarmProtocolCache: string | null = null;
+function getSwarmProtocol(): string {
+  if (_swarmProtocolCache !== null) return _swarmProtocolCache;
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const p = join(thisDir, 'templates', 'swarm-protocol.md');
+  if (!existsSync(p)) {
+    throw new Error(
+      `[ClaudeMdGenerator] swarm-protocol.md not found at ${p}. ` +
+        `This indicates a broken build/install. Run \`npm run build\` or reinstall the package.`,
+    );
+  }
+  _swarmProtocolCache = readFileSync(p, 'utf-8');
+  return _swarmProtocolCache;
+}
+
+export class ClaudeMdGenerator {
+  readonly detector: TechDetector;
+
+  constructor(
+    private ai: ClaudeProvider,
+    detector?: TechDetector,
+  ) {
+    this.detector = detector ?? new TechDetector();
+  }
+
+  /**
+   * 检测技术栈 + 生成 CLAUDE.md
+   *
+   * 策略：Swarm 协议是固定内容（不依赖 AI），项目信息尝试用 AI 生成，
+   * 失败时回退到基于技术栈检测的模板。
+   */
+  async generate(projectPath: string, userContent?: string): Promise<string> {
+    const stack = this.detector.detect(projectPath);
+
+    // 1. 尝试 AI 生成项目特定内容
+    let projectContent = '';
+    try {
+      const prompt = this.buildPrompt(stack, projectPath);
+      const aiResult = await this.ai.complete(prompt, {
+        system: 'You are a technical writer. Output ONLY markdown content for a CLAUDE.md file. Do NOT ask questions or explain what you will do. Start directly with ## headers.',
+        maxTokens: 4096,
+        // 4096-token 生成在转发网关（如 one.iflytek 等）下容易超过默认 30s；
+        // 给 CLAUDE.md 生成单独拉长超时，失败再回退到本地模板。
+        timeoutMs: 120_000,
+      });
+      // 验证 AI 输出是否有效（至少包含一个 ## 标题）
+      if (aiResult && aiResult.includes('##')) {
+        // AI 经常在"目录结构"章节退化成 project-root/com/example/project 模板，
+        // 不可信任；强制替换为真实扫描结果。
+        projectContent = this.overrideDirectoryStructure(aiResult, stack, projectPath);
+      }
+    } catch {
+      // AI 失败，使用模板回退
+    }
+
+    // 2. 如果 AI 失败或返回无效内容，使用模板
+    if (!projectContent) {
+      projectContent = this.buildFallbackContent(stack, projectPath);
+    }
+
+    // 3. Swarm 协议 + 项目内容
+    const full = getSwarmProtocol() + '\n\n' + projectContent;
+    return this.merge(full, userContent);
+  }
+
+  /**
+   * 基于技术栈检测的回退模板（不依赖 AI）
+   *
+   * 即使 AI 调用失败，也要生成足够丰富的项目指引，让 Claude Code 拿到：
+   *   - 技术栈概览（含版本、包管理器、测试 / Linter）
+   *   - 构建 / 测试 / 运行命令（按包管理器分发）
+   *   - 目录结构（扫描项目根目录真实结构）
+   *   - 代码规范（命名、提交信息、PR 流程）
+   *   - 常见陷阱（按技术栈定制）
+   *   - 贡献指南
+   */
+  private buildFallbackContent(stack: TechStack, projectPath: string): string {
+    const sections: string[] = [];
+
+    sections.push(this.sectionOverview(stack));
+    sections.push(this.sectionTechStack(stack));
+    sections.push(this.sectionBuildCommands(stack));
+    sections.push(this.sectionDirectoryStructure(stack, projectPath));
+    sections.push(this.sectionCodingStandards(stack));
+    sections.push(this.sectionCommonPitfalls(stack));
+    sections.push(this.sectionContributionGuide(stack));
+
+    return sections.filter(Boolean).join('\n\n');
+  }
+
+  private sectionOverview(stack: TechStack): string {
+    const lang = stack.language[0] || '未识别';
+    const framework = stack.framework.length > 0 ? ` + ${stack.framework.join(' / ')}` : '';
+    return [
+      '## 项目概述',
+      '',
+      `本项目基于 ${lang}${framework} 构建。请根据实际业务补充项目目标、核心模块职责与上下游依赖。`,
+    ].join('\n');
+  }
+
+  private sectionTechStack(stack: TechStack): string {
+    const lines: string[] = ['## 技术栈', ''];
+
+    if (stack.language.length > 0) {
+      lines.push(`- **语言**: ${stack.language.join(', ')}`);
+    }
+    if (stack.framework.length > 0) {
+      const descs = stack.framework.map(fw => `${fw}${this.frameworkHint(fw)}`);
+      lines.push(`- **框架**: ${descs.join(', ')}`);
+    }
+    lines.push(`- **包管理器**: ${stack.packageManager}`);
+    if (stack.testFramework) {
+      lines.push(`- **测试框架**: ${stack.testFramework}`);
+    }
+    if (stack.linter) {
+      lines.push(`- **代码检查**: ${stack.linter}`);
+    }
+
+    const ecosystem = this.ecosystemNotes(stack);
+    if (ecosystem) {
+      lines.push('', ecosystem);
+    }
+
+    return lines.join('\n');
+  }
+
+  private frameworkHint(fw: string): string {
+    const hints: Record<string, string> = {
+      'Spring Boot': '（IoC 容器 + 自动配置，所有组件通过注解注入）',
+      MyBatis: '（SQL 映射，Mapper 接口 + XML）',
+      Dubbo: '（RPC 框架，服务注册与发现）',
+      React: '（组件化 UI，单向数据流）',
+      'Next.js': '（React 全栈框架，支持 SSR / SSG）',
+      Vue: '（渐进式 UI 框架）',
+      Express: '（Node.js Web 框架，中间件模型）',
+      Fastify: '（高性能 Node.js Web 框架）',
+      NestJS: '（Node.js 企业级框架，装饰器 + DI）',
+    };
+    return hints[fw] || '';
+  }
+
+  private ecosystemNotes(stack: TechStack): string {
+    if (stack.language.some(l => l.startsWith('Java'))) {
+      return '> Java 生态约定：包名全小写，类名 PascalCase，方法 camelCase；Maven / Gradle 依赖统一在顶层 pom.xml / build.gradle 管理，子模块只声明坐标不重复版本。';
+    }
+    if (stack.language.includes('TypeScript')) {
+      return '> TypeScript 生态约定：开启 strict 模式，模块边界用 interface，内部用 type；async/await 优先，禁止混用 Promise 链。';
+    }
+    if (stack.language.some(l => l.startsWith('Go'))) {
+      return '> Go 生态约定：使用 gofmt 自动格式化；错误值必须显式处理，不得丢弃；包名全小写且与目录名一致。';
+    }
+    if (stack.language.includes('Rust')) {
+      return '> Rust 生态约定：`cargo fmt` + `cargo clippy` 双重检查；尽量使用 Result / Option，避免 panic；mod.rs 或 `<name>.rs` 二选一。';
+    }
+    if (stack.language.includes('Python')) {
+      return '> Python 生态约定：遵循 PEP8；建议启用 mypy / ruff；虚拟环境隔离依赖。';
+    }
+    return '';
+  }
+
+  private sectionBuildCommands(stack: TechStack): string {
+    const lines: string[] = ['## 构建与测试', '', '```bash'];
+    const pm = stack.packageManager;
+
+    if (pm === 'npm') {
+      lines.push('# 安装依赖', 'npm install', '', '# 开发模式（如适用）', 'npm run dev', '', '# 构建产物', 'npm run build', '', '# 运行测试', 'npm test', '', '# 类型检查（TypeScript）', 'npx tsc --noEmit');
+    } else if (pm === 'pnpm') {
+      lines.push('pnpm install', 'pnpm dev', 'pnpm build', 'pnpm test');
+    } else if (pm === 'yarn') {
+      lines.push('yarn', 'yarn dev', 'yarn build', 'yarn test');
+    } else if (pm === 'bun') {
+      lines.push('bun install', 'bun run dev', 'bun run build', 'bun test');
+    } else if (pm === 'maven') {
+      lines.push('# 清理并编译', 'mvn clean compile', '', '# 运行测试', 'mvn test', '', '# 打包（跳过测试加 -DskipTests）', 'mvn clean package', '', '# 本地安装到 ~/.m2', 'mvn clean install', '', '# 启动 Spring Boot（若适用）', 'mvn spring-boot:run');
+    } else if (pm === 'gradle') {
+      lines.push('# 构建', './gradlew build', '', '# 运行测试', './gradlew test', '', '# 清理', './gradlew clean', '', '# 启动 Spring Boot（若适用）', './gradlew bootRun');
+    } else if (pm === 'go mod') {
+      lines.push('go mod tidy', 'go build ./...', 'go test ./...', 'go vet ./...');
+    } else if (pm === 'cargo') {
+      lines.push('cargo build', 'cargo test', 'cargo clippy -- -D warnings', 'cargo fmt --check');
+    } else if (pm === 'pip' || pm === 'poetry' || pm === 'pipenv') {
+      const prefix = pm === 'poetry' ? 'poetry run ' : pm === 'pipenv' ? 'pipenv run ' : '';
+      lines.push(`${prefix}pytest`, `${prefix}python -m build`);
+    } else {
+      lines.push('# 请补充构建与测试命令');
+    }
+
+    lines.push('```');
+    return lines.join('\n');
+  }
+
+  private sectionDirectoryStructure(stack: TechStack, projectPath: string): string {
+    // Java 项目需要更深的层级才能看到包结构
+    const isJava = stack.language.some(l => l.startsWith('Java'));
+    const maxDepth = isJava ? 4 : 2;
+    const tree = this.scanDirectoryTree(projectPath, maxDepth, isJava);
+    if (!tree) return '';
+    return ['## 目录结构', '', '```', tree, '```'].join('\n');
+  }
+
+  /**
+   * 扫描项目根目录，生成树形结构（过滤噪声目录）
+   */
+  private scanDirectoryTree(projectPath: string, maxDepth: number, addComments = false): string {
+    const IGNORE = new Set([
+      'node_modules', '.git', '.idea', '.vscode', '.DS_Store',
+      'dist', 'build', 'target', 'out', '.next', '.nuxt',
+      '__pycache__', '.pytest_cache', '.mypy_cache',
+      'vendor', 'coverage', '.nyc_output', 'tmp', 'temp',
+    ]);
+
+    // 深目录噪声：这些目录即使不在 IGNORE 里，也不递归进去（避免爆炸）
+    const SHALLOW_ONLY = new Set([
+      'executions', 'by-route', 'history', 'logs', 'cache',
+    ]);
+
+    // Java 项目目录注释映射
+    const JAVA_COMMENTS: Record<string, string> = {
+      'controller': '# 控制器层',
+      'service': '# 服务层',
+      'impl': '# 服务实现类',
+      'mapper': '# MyBatis Mapper 接口',
+      'entity': '# 实体类',
+      'dto': '# 数据传输对象',
+      'vo': '# 视图对象',
+      'config': '# 配置类',
+      'util': '# 工具类',
+      'utils': '# 工具类',
+      'common': '# 公共模块',
+      'exception': '# 异常类',
+      'interceptor': '# 拦截器',
+      'filter': '# 过滤器',
+      'aspect': '# 切面',
+      'resources': '# 配置文件、静态资源',
+      'application.yml': '# 应用配置文件',
+      'application.yaml': '# 应用配置文件',
+      'pom.xml': '# Maven 配置文件',
+      'build.gradle': '# Gradle 配置文件',
+      'README.md': '# 项目说明文档',
+    };
+
+    const lines: string[] = [];
+
+    const walk = (dir: string, prefix: string, depth: number) => {
+      if (depth > maxDepth) return;
+
+      let entries: string[] = [];
+      try {
+        entries = readdirSync(dir).filter(e => !IGNORE.has(e));
+      } catch {
+        return;
+      }
+
+      // 文件在前，目录在后
+      const stats = entries.map(e => {
+        try {
+          return { name: e, isDir: statSync(join(dir, e)).isDirectory() };
+        } catch {
+          return { name: e, isDir: false };
+        }
+      });
+      const files = stats.filter(s => !s.isDir).map(s => s.name);
+      const dirs = stats.filter(s => s.isDir).map(s => s.name);
+      const sorted = [...dirs.sort(), ...files.sort()];
+
+      sorted.forEach((name, idx) => {
+        const isLast = idx === sorted.length - 1;
+        const connector = isLast ? '└── ' : '├── ';
+        const childPrefix = isLast ? '    ' : '│   ';
+
+        const fullPath = join(dir, name);
+        let isDir = false;
+        try {
+          isDir = statSync(fullPath).isDirectory();
+        } catch {
+          // ignore
+        }
+
+        // 构建行：名称 + 可选注释
+        let line = prefix + connector + name + (isDir ? '/' : '');
+        if (addComments) {
+          const comment = JAVA_COMMENTS[name] || JAVA_COMMENTS[name.toLowerCase()];
+          if (comment) {
+            // 对齐注释（假设最长路径 60 字符）
+            const padding = Math.max(1, 60 - line.length);
+            line += ' '.repeat(padding) + comment;
+          }
+        }
+        lines.push(line);
+
+        // 递归条件：是目录 + 未达深度上限 + 不在浅层名单里
+        if (isDir && depth < maxDepth && !SHALLOW_ONLY.has(name)) {
+          walk(fullPath, prefix + childPrefix, depth + 1);
+        }
+      });
+    };
+
+    // 根目录名：从路径提取真实项目名
+    const rootName = projectPath.split('/').filter(Boolean).pop() || 'project';
+    lines.push(rootName + '/');
+    walk(projectPath, '', 1);
+
+    return lines.join('\n');
+  }
+
+  private sectionCodingStandards(stack: TechStack): string {
+    const isJava = stack.language.some(l => l.startsWith('Java'));
+    const isTs = stack.language.includes('TypeScript');
+
+    const lines: string[] = ['## 代码规范', ''];
+
+    lines.push('### 命名约定', '');
+    if (isJava) {
+      lines.push('- 包名：全小写，使用反向域名（`com.company.project.module`）');
+      lines.push('- 类名：PascalCase（`UserService`、`OrderController`）');
+      lines.push('- 方法名 / 变量名：camelCase（`getUserById`、`orderList`）');
+      lines.push('- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`）');
+      lines.push('- DTO 后缀：`*Request` / `*Response` / `*DTO` / `*VO` 根据团队约定');
+    } else if (isTs) {
+      lines.push('- 文件名：kebab-case（`user-service.ts`）或 camelCase（视团队约定）');
+      lines.push('- 类型 / 接口：PascalCase（`interface User`、`type OrderStatus`）');
+      lines.push('- 函数 / 变量：camelCase');
+      lines.push('- 常量：UPPER_SNAKE_CASE 或 camelCase（不可变配置）');
+    } else {
+      lines.push('- 遵循所在语言生态的官方风格指南');
+    }
+
+    lines.push('', '### 代码组织', '');
+    lines.push('- 单文件职责单一，超过 300 行考虑拆分');
+    lines.push('- 避免循环依赖；模块边界清晰');
+    lines.push('- 公共工具函数沉淀到 `utils` / `common`，不重复造轮子');
+    lines.push('- **先读再改**：修改已有文件前必须先 Read，理解上下文再编辑');
+
+    lines.push('', '### 注释', '');
+    lines.push('- 默认不写注释；仅在"为什么这么做"不明显时补充');
+    lines.push('- 不要写"这个函数做什么"（代码本身应该自解释）');
+    lines.push('- 禁止遗留 `// TODO` 不跟单号、`// 临时` 不标日期');
+
+    lines.push('', '### 错误处理', '');
+    if (isJava) {
+      lines.push('- 优先抛出明确的业务异常，不吞异常');
+      lines.push('- Controller 层统一异常处理器（`@ControllerAdvice`）');
+      lines.push('- 事务边界清晰：`@Transactional` 只标注 Service 层');
+    } else if (isTs) {
+      lines.push('- async/await 配合 try/catch，不要混用 Promise 链');
+      lines.push('- 错误类型显式声明，不要 throw 裸字符串');
+      lines.push('- 边界层（HTTP handler、消息消费者）必须有统一错误出口');
+    } else {
+      lines.push('- 显式处理每一个错误返回值，不静默吞异常');
+    }
+
+    return lines.join('\n');
+  }
+
+  private sectionCommonPitfalls(stack: TechStack): string {
+    const pitfalls: string[] = [];
+
+    if (stack.framework.includes('Spring Boot')) {
+      pitfalls.push('- **循环依赖**：优先重构为单向依赖，不要用 `@Lazy` 掩盖');
+      pitfalls.push('- **配置覆盖**：`application-{profile}.yml` 会覆盖 `application.yml`，排查配置问题时两边都要看');
+      pitfalls.push('- **事务失效**：`@Transactional` 同类内部方法调用不生效，需要通过 Spring 代理调用');
+    }
+    if (stack.framework.includes('MyBatis')) {
+      pitfalls.push('- **Mapper XML `#{}` vs `${}`**：`${}` 会导致 SQL 注入，只用于表名 / 列名等元数据');
+      pitfalls.push('- **N+1 查询**：使用 `<resultMap>` + `<collection>` 一次 JOIN 获取，避免循环查询');
+    }
+    if (stack.language.includes('TypeScript')) {
+      pitfalls.push('- **类型断言滥用**：`as unknown as T` 通常是设计问题的信号，优先修正类型定义');
+      pitfalls.push('- **Promise 未 await**：async 函数返回 Promise，调用方忘记 await 会导致错误被吞');
+    }
+    if (stack.framework.includes('React')) {
+      pitfalls.push('- **useEffect 依赖**：依赖数组遗漏变量会导致闭包陷阱；使用 ESLint `exhaustive-deps` 规则');
+      pitfalls.push('- **列表 key**：不要用 index 作为 key，列表重排时会错乱');
+    }
+    if (stack.language.some(l => l.startsWith('Go'))) {
+      pitfalls.push('- **goroutine 泄漏**：启动 goroutine 必须有退出路径（context.Done / channel close）');
+      pitfalls.push('- **for 循环变量捕获**：Go 1.21 之前循环变量在 goroutine 里共享，需要局部变量拷贝');
+    }
+
+    if (pitfalls.length === 0) {
+      pitfalls.push('- 依赖升级前先运行全量测试');
+      pitfalls.push('- 修改公共接口前先 grep 所有调用方，评估影响面');
+      pitfalls.push('- 禁止在 main 分支直接提交，所有改动走 PR / MR 流程');
+    }
+
+    return ['## 常见陷阱', '', ...pitfalls].join('\n');
+  }
+
+  private sectionContributionGuide(stack: TechStack): string {
+    const isJava = stack.language.some(l => l.startsWith('Java'));
+    const lines: string[] = ['## 贡献指南', ''];
+
+    lines.push('### 分支策略', '');
+    lines.push('- `main` / `master`：受保护分支，只接受 PR 合并');
+    lines.push('- `feature/<ticket>-<slug>`：新功能开发');
+    lines.push('- `fix/<ticket>-<slug>`：Bug 修复');
+    lines.push('- `refactor/<scope>`：重构');
+
+    lines.push('', '### 提交信息（Conventional Commits）', '');
+    lines.push('```');
+    lines.push('<type>(<scope>): <subject>');
+    lines.push('');
+    lines.push('类型（type）：feat / fix / refactor / perf / test / docs / chore / style');
+    lines.push('范围（scope）：模块或目录名，例如 auth / api / ui');
+    lines.push('主题（subject）：50 字以内，祈使句，不加句号');
+    lines.push('```');
+    lines.push('');
+    lines.push('示例：`feat(auth): 新增 OAuth2 Google 登录`');
+
+    lines.push('', '### PR / MR 检查清单', '');
+    lines.push('- [ ] 通过所有自动化测试');
+    if (isJava) {
+      lines.push('- [ ] 通过 `mvn verify` / `./gradlew check`');
+    } else if (stack.language.includes('TypeScript')) {
+      lines.push('- [ ] 通过 `npx tsc --noEmit`（类型检查）');
+      if (stack.linter) lines.push(`- [ ] 通过 ${stack.linter} 检查`);
+    }
+    lines.push('- [ ] 新增代码有对应测试（除纯文档 / 配置外）');
+    lines.push('- [ ] 公共接口变更已更新文档');
+    lines.push('- [ ] 无敏感信息（密钥、token、内网地址）');
+    lines.push('- [ ] 经过至少一位 reviewer 审核');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 写入 CLAUDE.md，保留用户手动编辑的内容
+   */
+  write(projectPath: string, content: string): void {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    const { user } = this.read(projectPath);
+
+    const autoBlock = `${AUTO_START}\n${content.trim()}\n${AUTO_END}`;
+    const final = user
+      ? `${autoBlock}\n\n${user}\n`
+      : `${autoBlock}\n`;
+
+    writeFileSync(claudeMdPath, final, 'utf-8');
+  }
+
+  /**
+   * 读取并分离自动生成和用户内容
+   */
+  read(projectPath: string): { auto: string; user: string } {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    if (!existsSync(claudeMdPath)) {
+      return { auto: '', user: '' };
+    }
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    const startIdx = content.indexOf(AUTO_START);
+    const endIdx = content.indexOf(AUTO_END);
+
+    if (startIdx === -1 || endIdx === -1) {
+      return { auto: '', user: content.trim() };
+    }
+
+    const auto = content
+      .substring(startIdx + AUTO_START.length, endIdx)
+      .trim();
+
+    const before = content.substring(0, startIdx).trim();
+    const after = content.substring(endIdx + AUTO_END.length).trim();
+    const user = [before, after].filter(Boolean).join('\n\n');
+
+    return { auto, user };
+  }
+
+  // ── Private Methods ────────────────────────────────────────────────────
+
+  private buildPrompt(stack: TechStack, projectPath: string): string {
+    const projectName = projectPath.split('/').filter(Boolean).pop() || 'project';
+    const isJava = stack.language.some(l => l.startsWith('Java'));
+    const realTree = this.scanDirectoryTree(projectPath, isJava ? 4 : 2, isJava);
+
+    const sections = [
+      `请为项目 "${projectName}" 生成 CLAUDE.md 文件内容，包含以下章节：`,
+      '',
+      '1. 项目概述',
+      '2. 技术栈',
+      '3. 开发规范',
+      '4. 构建与测试命令',
+      '5. 目录结构（**必须**直接使用下方给出的真实目录树，不得编造或改名）',
+      '6. 代码风格',
+      '7. 常见陷阱',
+      '8. 贡献指南',
+      '',
+      '## 检测到的技术栈',
+      '',
+      `- 语言: ${stack.language.join(', ') || '未检测到'}`,
+      `- 框架: ${stack.framework.join(', ') || '无'}`,
+      `- 包管理器: ${stack.packageManager}`,
+    ];
+
+    if (stack.testFramework) {
+      sections.push(`- 测试框架: ${stack.testFramework}`);
+    }
+    if (stack.linter) {
+      sections.push(`- Linter: ${stack.linter}`);
+    }
+
+    sections.push(
+      '',
+      '## 项目真实目录结构（必须原样使用）',
+      '',
+      '```',
+      realTree,
+      '```',
+      '',
+      '⚠️ 生成"目录结构"章节时，**必须**用上面这个真实目录树，禁止使用 `project-root/`、`com/example/project/` 等占位符。',
+      '',
+      '请直接输出 Markdown 内容，不要包含代码块包裹。',
+      '使用中文撰写。每个章节保持简洁，总长度控制在 200 行以内。',
+    );
+
+    return sections.join('\n');
+  }
+
+  /**
+   * 强制替换 AI 输出中的"目录结构"章节为真实扫描结果。
+   *
+   * AI 经常即使拿到真实目录也会退化成模板（project-root/com/example/project）。
+   * 做字符串替换是最稳妥的兜底。
+   */
+  private overrideDirectoryStructure(content: string, stack: TechStack, projectPath: string): string {
+    const isJava = stack.language.some(l => l.startsWith('Java'));
+    const realTree = this.scanDirectoryTree(projectPath, isJava ? 4 : 2, isJava);
+    const realSection = ['## 目录结构', '', '```', realTree, '```'].join('\n');
+
+    // 匹配 "## 目录结构" 到下一个 "##" 之前的所有内容
+    const pattern = /^##\s+目录结构[\s\S]*?(?=^##\s|\Z)/m;
+    if (pattern.test(content)) {
+      return content.replace(pattern, realSection + '\n\n');
+    }
+    // 如果 AI 没生成目录结构章节，追加到末尾
+    return content.trimEnd() + '\n\n' + realSection + '\n';
+  }
+
+  private merge(generated: string, userContent?: string): string {
+    if (!userContent) return generated;
+
+    return [generated.trim(), '', '---', '', userContent.trim()].join('\n');
+  }
+}

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';