@winspan/claude-forge 8.39.0 → 8.50.6

package/dist/claudemd/claudemd-generator.js

@@ -1,7 +1,7 @@
 /**
  * CLAUDE.md Generator — AI 驱动的 CLAUDE.md 生成与管理
  */
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { TechDetector } from './tech-detector.js';
 const AUTO_START = '<!-- forge:claudemd-auto -->';
@@ -14,16 +14,378 @@ export class ClaudeMdGenerator {
         this.detector = detector ?? new TechDetector();
     }
     /**
-     * 检测技术栈 + 调 AI 生成 CLAUDE.md
+     * 检测技术栈 + 生成 CLAUDE.md
+     *
+     * 策略：Swarm 协议是固定内容（不依赖 AI），项目信息尝试用 AI 生成，
+     * 失败时回退到基于技术栈检测的模板。
      */
     async generate(projectPath, userContent) {
         const stack = this.detector.detect(projectPath);
-        const prompt = this.buildPrompt(stack, projectPath);
-        const generated = await this.ai.complete(prompt, {
-            system: 'You are a senior developer writing CLAUDE.md project instructions.',
-            maxTokens: 4096,
-        });
-        return this.merge(generated, userContent);
+        // 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 = SWARM_PROTOCOL + '\n\n' + projectContent;
+        return this.merge(full, userContent);
+    }
+    /**
+     * 基于技术栈检测的回退模板（不依赖 AI）
+     *
+     * 即使 AI 调用失败，也要生成足够丰富的项目指引，让 Claude Code 拿到：
+     *   - 技术栈概览（含版本、包管理器、测试 / Linter）
+     *   - 构建 / 测试 / 运行命令（按包管理器分发）
+     *   - 目录结构（扫描项目根目录真实结构）
+     *   - 代码规范（命名、提交信息、PR 流程）
+     *   - 常见陷阱（按技术栈定制）
+     *   - 贡献指南
+     */
+    buildFallbackContent(stack, projectPath) {
+        const sections = [];
+        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');
+    }
+    sectionOverview(stack) {
+        const lang = stack.language[0] || '未识别';
+        const framework = stack.framework.length > 0 ? ` + ${stack.framework.join(' / ')}` : '';
+        return [
+            '## 项目概述',
+            '',
+            `本项目基于 ${lang}${framework} 构建。请根据实际业务补充项目目标、核心模块职责与上下游依赖。`,
+        ].join('\n');
+    }
+    sectionTechStack(stack) {
+        const lines = ['## 技术栈', ''];
+        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');
+    }
+    frameworkHint(fw) {
+        const hints = {
+            '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] || '';
+    }
+    ecosystemNotes(stack) {
+        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 '';
+    }
+    sectionBuildCommands(stack) {
+        const lines = ['## 构建与测试', '', '```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');
+    }
+    sectionDirectoryStructure(stack, projectPath) {
+        // 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');
+    }
+    /**
+     * 扫描项目根目录，生成树形结构（过滤噪声目录）
+     */
+    scanDirectoryTree(projectPath, maxDepth, addComments = false) {
+        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 = {
+            '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 = [];
+        const walk = (dir, prefix, depth) => {
+            if (depth > maxDepth)
+                return;
+            let entries = [];
+            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');
+    }
+    sectionCodingStandards(stack) {
+        const isJava = stack.language.some(l => l.startsWith('Java'));
+        const isTs = stack.language.includes('TypeScript');
+        const lines = ['## 代码规范', ''];
+        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');
+    }
+    sectionCommonPitfalls(stack) {
+        const pitfalls = [];
+        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');
+    }
+    sectionContributionGuide(stack) {
+        const isJava = stack.language.some(l => l.startsWith('Java'));
+        const lines = ['## 贡献指南', ''];
+        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，保留用户手动编辑的内容
@@ -61,14 +423,17 @@ export class ClaudeMdGenerator {
     }
     // ── Private Methods ────────────────────────────────────────────────────
     buildPrompt(stack, projectPath) {
+        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 = [
-            '请为以下项目生成 CLAUDE.md 文件内容，包含以下章节：',
+            `请为项目 "${projectName}" 生成 CLAUDE.md 文件内容，包含以下章节：`,
             '',
             '1. 项目概述',
             '2. 技术栈',
             '3. 开发规范',
             '4. 构建与测试命令',
-            '5. 目录结构',
+            '5. 目录结构（**必须**直接使用下方给出的真实目录树，不得编造或改名）',
             '6. 代码风格',
             '7. 常见陷阱',
             '8. 贡献指南',
@@ -85,13 +450,266 @@ export class ClaudeMdGenerator {
         if (stack.linter) {
             sections.push(`- Linter: ${stack.linter}`);
         }
-        sections.push('', '请直接输出 Markdown 内容，不要包含代码块包裹。', '使用中文撰写。每个章节保持简洁，总长度控制在 200 行以内。');
+        sections.push('', '## 项目真实目录结构（必须原样使用）', '', '```', realTree, '```', '', '⚠️ 生成"目录结构"章节时，**必须**用上面这个真实目录树，禁止使用 `project-root/`、`com/example/project/` 等占位符。', '', '请直接输出 Markdown 内容，不要包含代码块包裹。', '使用中文撰写。每个章节保持简洁，总长度控制在 200 行以内。');
         return sections.join('\n');
     }
+    /**
+     * 强制替换 AI 输出中的"目录结构"章节为真实扫描结果。
+     *
+     * AI 经常即使拿到真实目录也会退化成模板（project-root/com/example/project）。
+     * 做字符串替换是最稳妥的兜底。
+     */
+    overrideDirectoryStructure(content, stack, projectPath) {
+        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';
+    }
     merge(generated, userContent) {
         if (!userContent)
             return generated;
         return [generated.trim(), '', '---', '', userContent.trim()].join('\n');
     }
 }
+/**
+ * Ruflo-style Swarm Protocol — injected into every project's CLAUDE.md
+ * so Claude autonomously invokes multi-agent pipelines for complex tasks.
+ */
+/**
+ * Core behavioral rules — injected into every project's CLAUDE.md.
+ * Simplified to ~140 lines for clarity and reduced instruction drift.
+ */
+/**
+ * Core behavioral rules — injected into every project's CLAUDE.md.
+ * Simplified to ~140 lines for clarity and reduced instruction drift.
+ */
+const SWARM_PROTOCOL = `# claude-forge 工作区规范
+
+## 自检（每次响应前必读）
+
+**在开始任何操作前，先问自己**：
+
+1. 我是否要修改 ≥2 个文件？
+2. 我是否要修改 ≥10 行代码？
+3. 这是否是新功能/重构/Bug 修复？
+4. 我修改的代码所在模块**测试覆盖率 < 50%** 吗？
+
+**如果 1-3 任一答案是"是"，且我没有 spawn Agent**：
+- ❌ 停下来 → 重新评估例外 → 否则立即 spawn Agent
+
+**如果 4 答案是"是"**（改老代码 + 测试薄弱）：
+- ❌ 不要 spawn 普通 \`coder\` / \`planner\`
+- ✅ 必须走 **Harness 或 Hybrid 工作流**（详见下方「工作流升级判定」）
+
+**违规示例**：
+- "修复 daemon handler bug（改老代码 + 0 测试）" → 应走 \`harness-hotfix\`，不是 \`coder\`
+- "重构 738 行字面量为 .md 文件" → 应走 \`refactor-safe\`，不是 \`coder\`
+- "新功能加在 hook 脚本" → 应走 \`hybrid-feature-with-safety\`，不是 \`planner+coder\`
+
+---
+
+## 核心行为规则
+
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless absolutely necessary
+- ALWAYS prefer editing existing files to creating new ones
+- ALWAYS read a file before editing it
+- Never continuously check status after spawning agents — wait for results
+
+---
+
+## Two-Phase Workflow (BMAD 默认路径)
+
+**适用范围**：≥3 文件改动 / 新功能 / 重构 / 架构调整
+**前提**：通过「工作流升级判定」确认为 BMAD 路径（测试覆盖充分 / 全新模块）
+**如果改老代码 + 测试薄弱** → 改走 Harness/Hybrid 三阶段（见下方）
+
+### Phase 1: Generate Spec
+
+1. Spawn planner/researcher agent with \`run_in_background: true\`
+2. Agent 输出 \`docs/design/[task]-spec-YYYYMMDD-HHMM.md\`，包含：
+   - 目标、改动文件清单、关键设计决策、风险点、测试策略
+   - **禁止写任何代码**
+3. 主线程告诉用户"已 spawn planner，等待 spec 生成"，**然后结束响应**
+
+### Phase 1.5: User Review (Critical Gate)
+
+Agent 完成后，**主线程必须停止并等待用户确认**：
+
+\`\`\`
+设计方案已生成：docs/design/xxx-spec.md
+
+请 review 后回复：
+- "批准" / "approve" → 我会 spawn coder 实现
+- "修改 [意见]" → 我会调整 spec
+- "取消" → 停止任务
+\`\`\`
+
+**绝对禁止**：
+- ❌ 主线程自行判断 spec 质量并进入 Phase 2
+- ❌ 主线程直接 spawn coder 而不等用户确认
+
+### Phase 2: Implement per Spec
+
+收到用户"批准"后：
+1. Spawn coder agent with \`run_in_background: true\`
+2. 严格按 spec 执行，完成后写 \`docs/implementation/[task]-changelog-YYYYMMDD-HHMM.md\`
+
+### 例外
+
+可跳过两阶段：
+- 单文件 1-2 行修改
+- 用户明确说"不需要 spec"
+- 纯查询/调研任务
+
+---
+
+## Agent 委托规则
+
+### 默认行为：spawn Agent
+
+接到任务时，**第一反应是 spawn Agent**。主线程只做协调。
+
+### 不 spawn 的例外（仅 4 条）
+
+1. **单行 typo**：1 文件 1 行拼写错误
+2. **协调与汇总**：整合 Agent 结果
+3. **元任务（极小改动）**：git commit/push、daemon 启停、单行规则调整
+4. **即时问答**：不涉及代码/文件的纯对话
+
+**注意**：
+- 例外 #3 不包括"重构 CLAUDE.md"、"修改多个配置文件"等大改动
+- 如果改动 ≥2 文件或 ≥10 行，必须 spawn Agent
+
+### 强制 spawn 的场景
+
+以下必须 spawn Agent：
+- 查/找/看/列出 → Explore agent
+- 函数分析/代码阅读 → doc-reviewer
+- 单文件 2+ 行修改 → coder
+- 实现/修复/重构/优化 → 对应 agent
+
+### 强制理由声明
+
+每次不 spawn 时，必须在响应开头说明：
+
+> 不 spawn 理由：例外 #N [具体原因]
+
+---
+
+## 工作流升级判定（spawn agent 前必查）
+
+**默认是 BMAD（planner+coder）**，但满足下表条件**必须升级到 Harness/Hybrid**。
+
+### 判定表
+
+| 任务特征 | 推荐 agent | 工作流序列 |
+|---------|-----------|----------|
+| **改老代码 + 模块测试覆盖 < 50%** | \`refactor-safe\` | safety-net → design → implement → test → review |
+| **已知原因的 Bug 修复**（紧急/明确）| \`harness-hotfix\` | safety-net → fix → verify |
+| **未知/偶发 Bug**（需先定位）| \`harness-debug-full\` | reproduce → safety-net → root-cause → fix → verify |
+| **新功能改老代码 + 测试薄弱** | \`hybrid-feature-with-safety\` | safety-net → analyze → design → implement → test → review |
+| **先修 bug 再加功能** | \`hybrid-fix-then-feature\` | reproduce → fix → verify → design → implement → review |
+| **全新模块 / 测试充分**（覆盖 ≥50%）| \`planner\` + \`coder\` | BMAD analyze → design → implement |
+| **纯调研 / 单行 typo / 元任务** | 不 spawn 或 \`Explore\` | — |
+
+### 测试覆盖快速判定
+
+修改 \`src/<module>/\` 前必查：
+
+\`\`\`bash
+SRC=$(find src/<module> -name "*.ts" -not -name "*.test.ts" 2>/dev/null | wc -l)
+TST=$(find tests/unit/<module> src/tests -name "*.test.ts" 2>/dev/null | wc -l)
+echo "ratio: $TST / $SRC"
+\`\`\`
+
+\`TST/SRC < 50%\` → **触发 Harness safety-net 阶段**（不要直接改代码）
+
+### 项目模块覆盖现状（提醒）
+
+| 模块 | 覆盖判定 | 默认走 |
+|------|---------|--------|
+| \`src/daemon/handlers/\` | 部分（≥50%）| BMAD，但 hotfix 类 bug 走 \`harness-hotfix\` |
+| \`src/daemon/services/\` | **零测试** | **Harness/Hybrid 强制** |
+| \`src/core/storage/\` | 高（≥80%）| BMAD |
+| \`src/core/queue/\` | 高（新写时已加）| BMAD |
+| \`src/skills/\` | 中（~40%）| 大改走 \`refactor-safe\` |
+| \`src/web/routes/\` | 中 | BMAD |
+| \`src/hooks/*.sh\` | 0（无 sh 测试）| 改 hook 必走 Hybrid |
+| \`src/claudemd/\` | 低 | \`refactor-safe\` |
+
+### 违规自查
+
+过去 5 次任务全踩坑，请引以为戒：
+
+- ❌ "修复 daemon schema 收紧拒收 bug"（改 events.ts + 5 个 hook）→ 走了 \`coder\`，应走 \`harness-hotfix\`
+- ❌ "Official Skills 数据分离"（重构 738 行老代码）→ 走了 \`planner+coder\`，应走 \`refactor-safe\`
+- ❌ "Hook 失败缓冲队列"（新功能 + 改 4 个老 hook）→ 走了 \`planner+coder\`，应走 \`hybrid-feature-with-safety\`
+
+**判定时机**：在「自检」之后、「Two-Phase Workflow」之前。判定结果若是 Harness/Hybrid，跳过 Two-Phase，直接 spawn 对应 agent。
+
+---
+
+## 并发规则
+
+- All operations MUST be concurrent/parallel in ONE message
+- ALWAYS batch ALL agents in ONE message with \`run_in_background: true\`
+- ALWAYS batch ALL file reads/writes/edits in ONE message
+- ALWAYS batch ALL terminal operations in ONE Bash message
+
+---
+
+## 项目特定信息
+
+### 技术栈
+
+- **语言**: TypeScript (Node.js 24+)
+- **数据库**: SQLite (better-sqlite3)
+- **前端**: 原生 HTML + Vanilla JS（单文件 SPA），无打包
+- **测试**: Vitest
+
+### 架构要点
+
+**分层**：
+- \`src/cli/\` — CLI 命令
+- \`src/daemon/\` — 后台守护进程（事件处理）
+- \`src/web/\` — Web 仪表盘
+- \`src/core/\` — 共享核心（storage/config/types）
+- \`src/claudemd/\` — CLAUDE.md 生成器
+- \`src/skills/\` — Skill 匹配与注入
+
+**存储**：
+- 主库：\`~/.claude-forge/data.db\`
+- 表：sessions, events, tasks, routing_events, skill_invocations, token_usage
+
+### 开发规范
+
+**构建与测试**：
+\`\`\`bash
+npm run build        # 构建前后端
+npm test             # 运行测试
+./scripts/dev-daemon.sh restart  # 重启 daemon
+\`\`\`
+
+**守护进程事件推送**：
+- PreToolUse / PostToolUse / UserPromptSubmit / Stop / Notification
+- 通过 Unix socket 推送到 daemon
+
+**注意**：
+- daemon 和 CLI 都用系统 node（v26）
+- better-sqlite3 12.10.0 支持 v26
+- 修改 schema 需要手动迁移（无自动 migration）
+
+---
+
+## 上次工作续接
+
+（由 daemon 自动更新，记录最近任务上下文）
+`;
 //# sourceMappingURL=claudemd-generator.js.map