@winspan/claude-forge 8.41.0 → 8.51.0

package/DEVELOPMENT.md

@@ -0,0 +1,310 @@
+# 开发指南
+
+面向 claude-forge 贡献者的架构与工作流说明。
+
+---
+
+## 仓库布局
+
+```
+src/
+├── core/
+│   ├── storage/      SQLite 存储（schema.sql + sqlite.ts），WAL 模式，单一 data.db
+│   ├── ai/           Anthropic SDK 封装（ClaudeProvider），被 classifier / planner / distiller 复用
+│   ├── utils/        logger / error-handler 等跨层工具
+│   └── types.ts      ForgeEvent / HookResult 等核心类型契约
+├── engine/
+│   ├── dsl/          治理规则 DSL 编译器（types / lexer / parser / compiler）
+│   ├── conventions/  打包进发布的默认 YAML 规则
+│   ├── rule-engine.ts         规则执行
+│   ├── context-builder.ts     Hook 事件 → 规则上下文
+│   ├── evidence-store.ts      治理证据持久化
+│   ├── agent-router.ts        Agent 路由（基于 routing.yaml）
+│   └── experiment-router.ts   A/B 实验路由（基于 experiments.yaml）
+├── intelligence/
+│   ├── classifier.ts          IntentClassifier：complexity / taskType / keywords
+│   ├── quality-gate.ts        AI 驱动的代码质量检查（PostToolUse）
+│   ├── distiller.ts           Stop 时蒸馏会话为 decisions.md / timeline.md
+│   └── task-segmenter.ts      按 UserPromptSubmit 划分任务段
+├── capability/
+│   ├── methodology-registry.ts   加载 src/capability/methodologies/*.yaml
+│   ├── methodology-planner.ts    AI Planner 根据 intent 生成 ExecutionPlan
+│   ├── execution-manager.ts      daemon 单例：前/后台路由、孤儿清理
+│   ├── executor/
+│   │   ├── types.ts                PhaseExecutor 统一抽象
+│   │   ├── foreground-executor.ts  前台：directive 入 pending 队列
+│   │   ├── background-executor.ts  后台：spawn claude -p 独立子进程
+│   │   ├── stream-parser.ts        stream-json 事件解析
+│   │   └── orchestrator.ts         串行驱动 phases
+│   └── methodologies/            harness-engineering.yaml / bmad.yaml
+├── daemon/
+│   ├── index.ts                 daemon 入口：socket server + hook router
+│   ├── router.ts                按 hook_type 分发到 handler
+│   ├── handlers/
+│   │   ├── user-prompt.ts          UserPromptSubmit：分类 + 路由 + 方法论
+│   │   ├── pre-tool-use.ts         PreToolUse：规则阻断
+│   │   ├── post-tool-use.ts        PostToolUse：质量检查 + 方法论推进
+│   │   ├── stop.ts                 Stop：蒸馏 + 方法论兜底
+│   │   ├── methodology-formatter.ts 生成前/后台 directive 文本
+│   │   └── history-exporter.ts     导出完整历史到 .claude-forge/history/
+│   ├── routing-observer.ts       观察 Agent 调用 → 标注 obeyed
+│   ├── routing-state.ts          会话级路由状态（PreToolUse 强制校验用）
+│   ├── auto-disable-scheduler.ts 自动禁用频繁违规的 (taskType, agent) 组合
+│   └── methodology-pending-queue.ts  前台 directive 持久化兜底队列
+├── hooks/               Shell 脚本：从 Claude Code 到 daemon socket 的桥
+├── agents/              内置 Agent 定义（13 个），可被 CLI 注入 ~/.claude/agents/
+├── skills/              Skill registry
+├── claudemd/            resume-manager / convention-extractor（CLAUDE.md 生成）
+├── cli/                 CLI 入口（claude-forge / cf），按命令组织在 cli/commands/
+├── templates/           新项目初始化模板
+└── web/                 Express + SSE 服务器（react 前端产物从 web/dist 拷入）
+
+web/                     React + TanStack Query + Tailwind 前端（独立 npm workspace）
+  ├── src/pages/         11 个页面（每个 lazy-loaded）
+  ├── src/components/    Drawer / Toast / Confirm / SearchInput / MarkdownRenderer / CodeBlock
+  └── vite.config.ts     手动 manualChunks 切分大库
+
+tests/unit/              Vitest 单测（vitest.config.ts include 仅覆盖此目录）
+scripts/                 开发/调试脚本：dev-web、demo-v2、smoke-background-executor
+```
+
+## 目录依赖约束
+
+- `core` 不反向依赖业务层
+- `engine` 可依赖 `core`
+- `intelligence` 可依赖 `core` / `engine`
+- `capability` 可依赖 `core` / `engine` / `intelligence`
+- `daemon` 可依赖 `core` / `engine` / `intelligence` / `capability` / `agents` / `skills`
+- `cli` 做命令分发，不塞核心规则逻辑
+
+---
+
+## 开发环境
+
+```bash
+# 必须先 build 一次以生成 dist/hooks/，hook 脚本需要绝对路径
+npm install
+npm run build
+
+# 启动 daemon（开发模式，用 tsx 直跑 ts）
+npm run dev:daemon
+
+# 启动 web dev 同步（监听 web/src 变化自动拷贝到 dist/web/static/）
+npm run dev:web
+```
+
+CLI 开发：`npm run dev -- <command>`（比如 `npm run dev -- status`）。
+
+---
+
+## 构建与测试
+
+```bash
+# 后端：tsc + 拷贝 hooks/schema/yaml 到 dist/
+npm run build
+
+# 前端：vite 构建到 web/dist/，随后 npm run build 会把它复制进 dist/web/static/
+npm run build:web
+
+# 完整：先前端再后端
+npm run build:all
+
+# 测试
+npm test                    # vitest run，只跑 tests/unit/
+npm run test:watch          # watch 模式
+npm run test:coverage       # 覆盖率
+
+# TS 双侧检查
+npx tsc --noEmit
+cd web && npx tsc --noEmit
+```
+
+> 发布流程：`npm run prepublishOnly`（= `npm run build`）会自动跑一遍，之后 `npm publish` 即可。发布前记得 `bump version`（两处：`package.json` + `package-lock.json`）。
+
+---
+
+## 架构要点
+
+### 方法论执行链路
+
+```
+┌───────────────────────┐       ┌──────────────────┐
+│  UserPromptSubmit     │  or   │  POST /api/      │
+│  自动识别任务 → 创建   │       │  methodology-    │
+│  execution (mode=fg)  │       │  executions      │
+└──────────┬────────────┘       │  (mode=bg)       │
+           │                    └────────┬─────────┘
+           │                             │
+           ▼                             ▼
+    ┌──────────────────────────────────────┐
+    │  ExecutionManager.start()            │
+    │  ├─ createMethodologyExecution()     │
+    │  ├─ seed phase 0 row                 │
+    │  └─ new Orchestrator(executor).run() │
+    └──────────┬───────────────────────────┘
+               │
+    ┌──────────┴──────────┐
+    │ mode?               │
+    └──┬───────────────┬──┘
+       │ foreground    │ background
+       ▼               ▼
+  ┌──────────────┐  ┌────────────────────────┐
+  │ Foreground   │  │ Background             │
+  │ Executor     │  │ Executor               │
+  │ ─ enqueue    │  │ ─ spawn claude -p      │
+  │   directive  │  │ ─ parse stream-json    │
+  │ ─ return     │  │ ─ update phase_exec    │
+  │   'injected' │  │ ─ wait exit            │
+  └──────┬───────┘  └──────────┬─────────────┘
+         │                     │
+         ▼                     │
+  ┌──────────────┐             │
+  │ Pending      │             │
+  │ Queue        │             │
+  └──────┬───────┘             │
+         │                     │
+         ▼                     ▼
+  ┌──────────────┐      ┌─────────────────┐
+  │ Claude       │      │ Orchestrator    │
+  │ 主会话       │      │ 推进到下一 phase │
+  │ 下一次输入时 │      │ 直到完成或失败   │
+  │ 消费队列     │      └─────────────────┘
+  └──────────────┘
+```
+
+### 存储
+
+- `~/.claude-forge/data.db` —— 单一运行时数据库：events / sessions / routing_events / methodology_executions / phase_executions / tasks / injections / decisions / token_usage
+- Schema 由 `src/core/storage/schema.sql` 初始化，增量迁移放在 `runMigrations()`（幂等 `ALTER TABLE` + `PRAGMA table_info` 检测）
+
+### Hook 注入原则
+
+- UserPromptSubmit 返回 `{ systemMessage, additionalContext, allow }`；systemMessage 优先级高于 additionalContext
+- PostToolUse 只能观察，不能修改工具结果；返回 systemMessage 会拼到 Claude 下一轮的系统消息
+- Stop 返回 systemMessage 会作为"本轮结束"的最后一条系统提示
+- **daemon 无法主动推送消息**。前台方法论的兜底设计正是基于这条约束（Stop → 写 pending 队列 → 下一次 UserPromptSubmit 消费）
+
+### Agent Worker 隔离
+
+后台 BackgroundExecutor spawn `claude -p` 时：
+
+- **不用 `--bare`**（会关闭 `~/.claude/agents/` 加载，破坏 phase.agent 语义）
+- 用 `--settings <worker-settings.json>`（内容 `{"hooks": {}}`）阻断 worker 递归触发 daemon hook
+- env 里写入 `CLAUDE_FORGE_WORKER=1`，未来 daemon 侧若需识别 worker 事件可用此标记
+- `--permission-mode bypassPermissions` + `--add-dir <projectRoot>` 限制只在项目目录内动手
+- `--disallowed-tools WebFetch,WebSearch` 默认禁用爬虫类工具
+- `--max-budget-usd 2` 每 phase 预算上限
+- stream-json 全量落盘到 `~/.claude-forge/logs/execution-{id}-phase-{n}.jsonl`
+
+---
+
+## 调试技巧
+
+```bash
+# 看 daemon 日志（启动时写在 stderr，daemon 模式写入 ~/.claude-forge/daemon.log）
+tail -f ~/.claude-forge/daemon.log
+
+# 直接查 SQLite 运行时数据
+sqlite3 ~/.claude-forge/data.db "SELECT id, methodology_id, status, mode, current_phase_index FROM methodology_executions ORDER BY id DESC LIMIT 10"
+
+# 查看后台 worker 的完整 stream-json 日志
+ls ~/.claude-forge/logs/
+
+# Hook 脚本手工模拟（绕开 Claude Code）
+echo '{"session_id":"test","hook_type":"UserPromptSubmit","user_prompt":"重构xxx"}' | ~/.claude/hooks/user-prompt-submit.sh
+
+# Web 后台 SSE 实时监控（默认 3456，可在 ~/.claude-forge/config.yaml 修改 web.port）
+curl -N http://127.0.0.1:3456/api/methodology-executions/events
+```
+
+---
+
+## 新增方法论
+
+1. 在 `src/capability/methodologies/` 新建 `<id>.yaml`，参考 `harness-engineering.yaml` 结构：
+   ```yaml
+   id: my-methodology
+   name: "My Methodology"
+   description: "..."
+   trigger:
+     taskType: [refactor, migrate]
+     complexity: [moderate, complex]
+   phase_templates:
+     understand:
+       agent: researcher
+       description: ...
+       prompt_template: ...
+       artifacts:
+         - type: file
+           pattern: "docs/**/*behavior*.md"
+           required: true
+   decision_rules:
+     - condition: "complexity == 'complex' && taskType == 'migrate'"
+       phases: [understand, characterize, refactor, verify]
+       description: "full workflow"
+   ```
+2. `phase_templates.<id>.agent` 必须对应 `~/.claude/agents/` 里真实存在的 agent 名（Planner 会用它生成 `phase.agent`，matcher 会严格校验）
+3. 重启 daemon（Registry 启动时加载一次）
+4. 在 Web UI `/methodologies` 点"新建执行"选它，或发一条符合 trigger 的 prompt
+
+## 新增 Agent
+
+最简方式：`~/.claude/agents/<name>.md` 按 frontmatter 规范写：
+
+```markdown
+---
+name: my-agent
+description: "简明描述"
+tools: [Read, Grep, Edit]
+---
+
+完整 agent 系统指令...
+```
+
+或通过 Web UI `/agents` 可视化编辑。daemon 启动时 AgentRegistry 会扫描并加载。
+
+---
+
+## 测试规范
+
+- 单元测试放 `tests/unit/**/*.test.ts`，vitest include 只认这个目录
+- 集成测试：可以在 `tests/unit/executor/` 下用 fake 子进程的方式（参考 `background-executor.test.ts` 的 shell wrapper 手法）
+- E2E（真 claude -p）：写进 `scripts/smoke-*.ts`，手动触发，不进 CI
+- 新增功能必须 at least 一个单测，关键路径需要集成测试
+
+---
+
+## 发布流程
+
+```bash
+# 1. 本地全量验证
+npm run build:all
+npx tsc --noEmit && (cd web && npx tsc --noEmit)
+npm test
+
+# 2. bump version
+# package.json + package-lock.json 两处同步改
+
+# 3. commit + tag
+git commit -am "chore: bump version to X.Y.Z"
+git tag vX.Y.Z
+
+# 4. publish
+npm publish   # 自动触发 prepublishOnly
+
+# 5. push
+git push && git push --tags
+```
+
+---
+
+## 排障清单
+
+| 现象 | 可能原因 |
+|---|---|
+| Hook 没触发 | `~/.claude/hooks/` 未软链到 `dist/hooks/`；跑 `cf init` 重装 |
+| daemon 启动报 EADDRINUSE | 上次进程没退；`cf daemon stop` 或 `lsof -i :<web.port>`（默认 3456）找 pid kill |
+| 方法论 execution 长期卡 0% | 前台模式需用户输入才推进；Web UI 可改用后台模式 |
+| BackgroundExecutor 直接报 auth 失败 | 确认 `ANTHROPIC_API_KEY` 环境变量可用，或配了 OAuth |
+| stream-json 行数突然变少 | claude CLI 版本升级，对齐 `stream-parser.ts` 的 type 定义 |
+| Web 构建 chunk >500KB 警告 | 加新大依赖时，在 `web/vite.config.ts` 的 `manualChunks` 追加分组 |

package/dist/claudemd/claudemd-generator.d.ts

@@ -1,16 +1,44 @@
 /**
  * CLAUDE.md Generator — AI 驱动的 CLAUDE.md 生成与管理
  */
-import type { AIProvider } from '../core/ai/types.js';
+import type { ClaudeProvider } from '../core/ai/provider.js';
 import { TechDetector } from './tech-detector.js';
 export declare class ClaudeMdGenerator {
     private ai;
     readonly detector: TechDetector;
-    constructor(ai: AIProvider, detector?: TechDetector);
+    constructor(ai: ClaudeProvider, detector?: TechDetector);
     /**
-     * 检测技术栈 + 调 AI 生成 CLAUDE.md
+     * 检测技术栈 + 生成 CLAUDE.md
+     *
+     * 策略：Swarm 协议是固定内容（不依赖 AI），项目信息尝试用 AI 生成，
+     * 失败时回退到基于技术栈检测的模板。
      */
     generate(projectPath: string, userContent?: string): Promise<string>;
+    /**
+     * 基于技术栈检测的回退模板（不依赖 AI）
+     *
+     * 即使 AI 调用失败，也要生成足够丰富的项目指引，让 Claude Code 拿到：
+     *   - 技术栈概览（含版本、包管理器、测试 / Linter）
+     *   - 构建 / 测试 / 运行命令（按包管理器分发）
+     *   - 目录结构（扫描项目根目录真实结构）
+     *   - 代码规范（命名、提交信息、PR 流程）
+     *   - 常见陷阱（按技术栈定制）
+     *   - 贡献指南
+     */
+    private buildFallbackContent;
+    private sectionOverview;
+    private sectionTechStack;
+    private frameworkHint;
+    private ecosystemNotes;
+    private sectionBuildCommands;
+    private sectionDirectoryStructure;
+    /**
+     * 扫描项目根目录，生成树形结构（过滤噪声目录）
+     */
+    private scanDirectoryTree;
+    private sectionCodingStandards;
+    private sectionCommonPitfalls;
+    private sectionContributionGuide;
     /**
      * 写入 CLAUDE.md，保留用户手动编辑的内容
      */
@@ -23,6 +51,13 @@ export declare class ClaudeMdGenerator {
         user: string;
     };
     private buildPrompt;
+    /**
+     * 强制替换 AI 输出中的"目录结构"章节为真实扫描结果。
+     *
+     * AI 经常即使拿到真实目录也会退化成模板（project-root/com/example/project）。
+     * 做字符串替换是最稳妥的兜底。
+     */
+    private overrideDirectoryStructure;
     private merge;
 }
 //# sourceMappingURL=claudemd-generator.d.ts.map

package/dist/claudemd/claudemd-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claudemd-generator.d.ts","sourceRoot":"","sources":["../../src/claudemd/claudemd-generator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAkB,MAAM,oBAAoB,CAAC;AAKlE,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,EAAE;IAHZ,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;gBAGtB,EAAE,EAAE,UAAU,EACtB,QAAQ,CAAC,EAAE,YAAY;IAKzB;;OAEG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW1E;;OAEG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAYjD;;OAEG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IA2BzD,OAAO,CAAC,WAAW;IAoCnB,OAAO,CAAC,KAAK;CAKd"}
+{"version":3,"file":"claudemd-generator.d.ts","sourceRoot":"","sources":["../../src/claudemd/claudemd-generator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAkB,MAAM,oBAAoB,CAAC;AA+BlE,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,EAAE;IAHZ,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;gBAGtB,EAAE,EAAE,cAAc,EAC1B,QAAQ,CAAC,EAAE,YAAY;IAKzB;;;;;OAKG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkC1E;;;;;;;;;;OAUG;IACH,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,gBAAgB;IA0BxB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,oBAAoB;IA+B5B,OAAO,CAAC,yBAAyB;IASjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsGzB,OAAO,CAAC,sBAAsB;IAiD9B,OAAO,CAAC,qBAAqB;IAkC7B,OAAO,CAAC,wBAAwB;IAqChC;;OAEG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAYjD;;OAEG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IA2BzD,OAAO,CAAC,WAAW;IAgDnB;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,KAAK;CAKd"}