@winspan/claude-forge 4.1.0 → 6.0.0

package/README.md

@@ -1,801 +1,199 @@
-# Claude Forge
+# Claude Forge v3
 
-> SDLC 智能编排引擎 — 让 Claude Code 越用越聪明
+> 极简治理引擎 — 4 条核心通路，4000 行代码
 
-Claude Forge 是一个为 Claude Code 设计的智能编排引擎，通过透明旁听对话、自动分析意图、注入最佳实践，让 AI 辅助开发更高效、更可靠。
+Claude Forge 是一个为 Claude Code 设计的轻量级治理引擎，通过 Hook 机制在后台运行，提供规则阻断、技能推荐、质量检查和历史记录功能。
 
-[![npm version](https://img.shields.io/npm/v/@winspan/claude-forge.svg)](https://www.npmjs.com/package/@winspan/claude-forge)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+## 核心特性
 
-## ✨ 核心特性
+### 1. 规则阻断（PreToolUse）
+基于 DSL 的规则引擎，实时阻断危险操作：
+- 阻止 `rm -rf /` 等破坏性命令
+- 警告 `git push --force` 等风险操作
+- 支持自定义 YAML 规则
 
-- 🎯 **智能意图识别** - 自动分析任务复杂度，决定执行策略（三层架构：Ground Truth 规则 + 学习规则 + AI 降级层，支持上下文感知和活跃计划检测） [x] 2026-04-25
-- 🔄 **Pipeline 编排** - 复杂任务自动拆分为多阶段流程（分析→设计→编码→测试→审查），支持纯事件溯源架构和状态机约束，确保状态一致性，daemon 启动时自动迁移历史数据，阶段产物统一输出到 docs/时间戳/ 目录，支持动态节点系统（Convention 定义节点类型，Skill 作为执行策略，NodeTypeRegistry 聚合节点类型，DynamicNodeExecutor 驱动执行，INodeExecutor 接口统一 PhaseManager 和 DynamicNodeExecutor，DynamicAggregator 支持动态节点事件聚合，启发式完成检测增强支持 file_patterns 和 keywords，Web API 支持动态流水线创建和手动推进，SemanticValidator 支持语义一致性校验），管理后台深度审查与修复完成（9个核心页面4750行代码，发现28个问题，修复20个P0/P1/P2/P3问题，新增质量问题上下文查询接口，优化事件展开性能和UX体验，完成P0级数据正确性和稳定性修复），节点类型管理页面和动态流水线节点展示组件已实现，NodeTypes 页面和 PipelineDetail 动态节点展示已集成，Legacy Pipeline 迁移脚本已完成，节点类型 API 路由已注册，动态节点系统全栈集成完成，全栈集成验证通过（NodeTypes页面正常展示节点类型，PipelineDetail页面正常展示动态节点，API路由正常响应），节点类型持久化到数据库（node_types表），启动时自动恢复到内存注册表，Convention加载时同步节点类型定义，流水线节点产物约束设计与实现完成（ArtifactType定义、ArtifactConstraint约束、ArtifactCollector收集器、ArtifactValidator验证器支持复杂度驱动约束、NodeOutput结构化输出、启发式完成检测集成产物验证、Web前端展示产物列表和验证状态），DynamicPipelineRepository 支持动态流水线和节点的完整 CRUD 操作，Web 管理后台集成动态流水线 API 路由和前端展示，产物约束验证支持复杂度驱动（simple/moderate/complex 动态调整约束严格度），git 操作强制归类为 simple 复杂度，Analyzer 集成 Convention 上下文到 pipeline-decompose 提示词，产物验证器支持复杂度驱动约束动态调整，流程可控能力分析与实施方案文档已完成（审计范围覆盖 src/pipeline/*, src/autopilot/*, src/convention/*, src/daemon/handlers/*，当前满足度95%（已完成核心改进），提供MVP方案和严格模式实施路径），INodeExecutor 接口统一 PhaseManager 和 DynamicNodeExecutor 实现完成，流程可控硬阻断实现完成（产物验证失败10次重试后硬阻断、质量门禁must级别问题硬阻断、PhaseManager和DynamicNodeExecutor统一阻断传播链、post-tool-use-handler集成阻断检测和强制中断），产物生成状态机与骨架预创建机制已实现（PreToolUse 阶段骨架预创建、状态机驱动产物生成、DynamicNodeExecutor 集成状态机逻辑、SemanticValidator 支持骨架内容识别），分步驱动执行模型设计与实现完成（Step 定义、StepOrchestrator 编排器、StepValidator 验证器、StepGateKeeper 门禁守卫、StepPromptBuilder 提示词构建器、PendingPromptsManager 集成、PreToolUse/PostToolUse 集成点、状态机驱动、失败重试与人工接管机制、SemanticValidator 集成、NodeTypeRegistry 集成、DynamicAggregator 事件聚合支持），产物强制执行引擎实现完成（三层防护机制：阶段指令引导 + 实时产物追踪 + 阶段推进门禁，ArtifactEnforcer 集成到 PhaseManager 和 DynamicNodeExecutor，支持产物类型推断、豁免规则、缺失提示生成，已集成到 PipelineEngine），NodeRuntime 统一节点运行时状态管理（替代 DynamicNodeExecutor 中的 12 个独立缓存，将节点运行时状态统一为一个对象，支持状态持久化和恢复） [x] 2026-04-25
-- 🛡️ **质量门禁** - 每个阶段自动 AI 审查，支持需求规格、安全性、代码质量、测试覆盖、性能等多维度检查，问题追踪和解决状态管理，支持上下文查询，支持 must/should 分级硬阻断（产物验证硬阻断 + 质量门禁分级阻断实现完成，代码审查通过，流程可控彻底审计报告已完成，阶段工具白名单策略已实现，Checkpoint 失败回滚机制已实现），产物生成状态机与骨架预创建机制已实现（PreToolUse 阶段骨架预创建、状态机驱动产物生成、DynamicNodeExecutor 集成状态机逻辑、SemanticValidator 支持骨架内容识别、产物阶段状态机改造完成、PreToolUse 骨架预创建集成、DynamicNodeExecutor 状态机驱动逻辑集成），分步驱动执行模型支持 Step 级别质量检查（StepCheck 定义、StepValidator 验证器、must/should/may 分级、失败重试与人工接管、StepGateKeeper 工具白名单门禁），CompletionEngine 节点完成综合决策引擎实现完成（聚合 CompletionDetector 和 ArtifactValidator 结果、基于置信度综合决策、支持复杂度驱动约束），产物强制执行引擎实现完成（三层防护机制：阶段指令引导 + 实时产物追踪 + 阶段推进门禁，ArtifactEnforcer 集成到 PhaseManager 和 DynamicNodeExecutor，支持产物类型推断、豁免规则、缺失提示生成，已集成到 PipelineEngine） [x] 2026-04-25
-- 📊 **Web 管理后台** - 实时监控会话、Pipeline、质量问题（支持上下文查询和批量解决）、知识图谱、项目管理、自定义规范管理、技能管理、CLAUDE.md 管理（支持模块化查看和蒸馏压缩）、项目规范绑定管理、项目元数据管理（标签/备注/归档）、全局规范管理（同步/安装/删除/进化/YAML编辑/使用统计/进化历史）、阶段产物统一管理（docs/时间戳/目录结构+INDEX.md索引）、动态节点类型管理（NodeTypeRegistry 可视化）、TemplateRegistry 支持三种来源（builtin/user/convention）、动态流水线创建和手动推进操作、事件日志管理（查看/搜索/导出/清理）、数据库维护功能（备份/恢复/历史记录/诊断修复）、数据分析页面（会话统计、事件统计、API使用统计、成本分析、趋势图表），深度代码审查完成（9个核心页面28个问题，修复20个P0/P1/P2/P3问题，包括运行时错误、性能优化、竞态条件、UX改进、数据正确性和稳定性修复），节点类型管理页面和动态流水线节点展示组件已实现，NodeTypes 页面和 PipelineDetail 动态节点展示已集成，Legacy Pipeline 数据迁移支持已完成，节点类型 API 路由已注册，动态节点系统全栈集成完成，全栈集成验证通过（NodeTypes页面正常展示节点类型，PipelineDetail页面正常展示动态节点，API路由正常响应），节点类型持久化和恢复机制已实现，DynamicPipelineNodes组件支持产物展示（artifacts列表、验证状态、类型图标、路径链接），知识图谱页面集成完成（搜索/概览/邻居/图谱可视化/CRUD操作），Analytics 页面支持会话统计、事件统计、API使用统计和成本分析，动态流水线 API 路由完整集成（创建/查询/更新/删除/手动推进） [x] 2026-04-24
-- 🧠 **知识积累** - 自动提炼决策日志、时间线、项目规范，支持树索引和语义检索，Web管理后台集成知识图谱页面（搜索/概览/邻居/图谱可视化/CRUD操作） [x] 2026-04-25
-- 🎨 **技能编排** - 根据意图自动匹配并注入最佳实践（TDD、重构、调试等），支持关键词映射和命中率统计 [x] 2026-04-25
-- 📈 **数据分析** - 成本统计、满意度趋势、ROI 分析，支持延迟追踪和 SLA 告警 [x] 2026-04-25
-- 🔌 **多 AI 提供商** - 支持 Claude、OpenAI、Ollama，统一网关层（速率限制、熔断、缓存、预算管理） [x] 2026-04-25
+### 2. 技能推荐（UserPromptSubmit）
+自动分析用户意图，推荐相关技能：
+- 意图分类：simple / moderate / complex
+- 关键词匹配技能库
+- 注入技能内容到 systemMessage
 
----
-
-## 核心功能
-
-| 功能 | 说明 |
-|------|------|
-| 意图识别 | 自动分析任务复杂度（simple/moderate/complex），决定执行策略，三层架构（Ground Truth 规则 + 学习规则 + AI 降级层），支持上下文感知和活跃计划检测 [x] 2026-04-24 |
-| Pipeline 编排 | 复杂任务自动拆分为多阶段流程，支持纯事件溯源、状态机约束、质量门禁、阶段产物生成（统一输出到 docs/时间戳/ 目录+INDEX.md索引）、daemon 启动时自动迁移历史数据、动态节点系统（Convention 定义节点类型，NodeTypeRegistry 聚合，DynamicNodeExecutor 驱动，Skill 作为执行策略，INodeExecutor 接口统一，TemplateRegistry 支持三种来源，启发式完成检测增强，Web API 操作端点，SemanticValidator 支持语义一致性校验），管理后台深度审查与修复完成（修复运行时错误、性能问题、竞态条件、UX体验、数据正确性和稳定性等20个P0/P1/P2/P3问题），节点类型管理页面和动态流水线节点展示组件已实现，NodeTypes 页面和 PipelineDetail 动态节点展示已集成，Legacy Pipeline 迁移脚本已完成，节点类型 API 路由已注册，动态节点系统全栈集成完成，全栈集成验证通过（NodeTypes页面正常展示节点类型，PipelineDetail页面正常展示动态节点，API路由正常响应），节点类型持久化到数据库（node_types表+NodeTypeRepository），启动时自动恢复到内存注册表，Convention加载时同步节点类型定义，流水线节点产物约束系统完成（ArtifactCollector追踪Write/Edit工具调用、ArtifactValidator验证产物约束支持复杂度驱动、NodeOutput结构化输出、DynamicPipelineNodes组件展示产物列表和验证状态），DynamicPipelineRepository 支持动态流水线和节点的完整 CRUD 操作，Web 管理后台动态流水线 API 路由完整注册，产物约束验证支持复杂度驱动（simple/moderate/complex 动态调整约束严格度），git 操作强制归类为 simple 复杂度，Analyzer 集成 Convention 上下文到 pipeline-decompose 提示词，产物验证器支持复杂度驱动约束动态调整，流程可控能力分析与实施方案文档已完成（审计范围覆盖 src/pipeline/*, src/autopilot/*, src/convention/*, src/daemon/handlers/*，当前满足度95%（已完成核心改进），提供MVP方案和严格模式实施路径），INodeExecutor 接口统一 PhaseManager 和 DynamicNodeExecutor 实现完成，流程可控硬阻断实现完成（产物验证失败10次重试后硬阻断、质量门禁must级别问题硬阻断、统一阻断传播链、post-tool-use-handler集成阻断检测和强制中断），产物生成状态机与骨架预创建机制已实现（PreToolUse 阶段骨架预创建、状态机驱动产物生成、DynamicNodeExecutor 集成状态机逻辑、SemanticValidator 支持骨架内容识别、产物阶段状态机改造完成、PreToolUse 骨架预创建集成、DynamicNodeExecutor 状态机驱动逻辑集成），分步驱动执行模型设计与实现完成（Step 定义、StepOrchestrator 编排器、StepValidator 验证器、StepGateKeeper 门禁守卫、StepPromptBuilder 提示词构建器、PendingPromptsManager 集成、PreToolUse/PostToolUse 集成点、状态机驱动、失败重试与人工接管机制、SemanticValidator 集成、NodeTypeRegistry 集成、DynamicAggregator 事件聚合支持），OrchestrationEnforcer 编排约束补全器实现完成（must 规则补全、内置 after-node 规则、DAG 环检测、失败降级策略），CompletionEngine 节点完成综合决策引擎实现完成（聚合 CompletionDetector 和 ArtifactValidator 结果、基于置信度综合决策、支持复杂度驱动约束），产物强制执行引擎实现完成（三层防护机制：阶段指令引导 + 实时产物追踪 + 阶段推进门禁，ArtifactEnforcer 集成到 PhaseManager 和 DynamicNodeExecutor，支持产物类型推断、豁免规则、缺失提示生成，已集成到 PipelineEngine），NodeRuntime 统一节点运行时状态管理（替代 DynamicNodeExecutor 中的 12 个独立缓存，将节点运行时状态统一为一个对象，支持状态持久化和恢复） [x] 2026-04-25 |
-| 质量门禁 | 每个阶段自动 AI 审查（需求规格、安全性、代码质量、测试、性能），不合格则阻止推进，支持 must/should 分级硬阻断（产物验证失败10次重试后硬阻断、质量门禁must级别问题硬阻断、统一阻断传播链、post-tool-use-handler集成阻断检测和强制中断，流程可控彻底审计报告已完成，阶段工具白名单策略已实现，Checkpoint 失败回滚机制已实现），产物生成状态机与骨架预创建机制已实现（PreToolUse 阶段骨架预创建、状态机驱动产物生成、DynamicNodeExecutor 集成状态机逻辑、SemanticValidator 支持骨架内容识别、产物阶段状态机改造完成、PreToolUse 骨架预创建集成、DynamicNodeExecutor 状态机驱动逻辑集成），分步驱动执行模型支持 Step 级别质量检查（StepCheck 定义、StepValidator 验证器、must/should/may 分级、失败重试与人工接管、StepGateKeeper 工具白名单门禁），CompletionEngine 节点完成综合决策引擎实现完成（聚合 CompletionDetector 和 ArtifactValidator 结果、基于置信度综合决策、支持复杂度驱动约束），产物强制执行引擎实现完成（三层防护机制：阶段指令引导 + 实时产物追踪 + 阶段推进门禁，ArtifactEnforcer 集成到 PhaseManager 和 DynamicNodeExecutor，支持产物类型推断、豁免规则、缺失提示生成，已集成到 PipelineEngine） [x] 2026-04-25 |
-| 技能编排 | 根据意图自动匹配并注入最佳实践，支持关键词映射和命中率统计 [x] 2026-04-25 |
-| 知识蒸馏 | 自动提炼决策日志、时间线、项目规范，支持树索引和语义检索，Web管理后台集成知识图谱页面（搜索/概览/邻居/图谱可视化/CRUD操作） [x] 2026-04-25 |
-| 会话续接 | 中断后自动恢复上次工作状态 [x] 2026-04-25 |
-| 用户画像 | 根据行为自适应调整干预深度（已废弃，移除完整方案文档已创建至 docs/2026-04-25/架构设计/移除UserProfile完整方案.md） [x] 2026-04-25（已废弃） |
-| 多 AI 提供商 | 支持 Claude、OpenAI、Ollama，统一网关层 [x] 2026-04-25 |
-| Web 管理后台 | 实时监控、项目管理、Pipeline 控制、质量追踪（支持上下文查询和批量解决）、自定义规范管理、技能管理、CLAUDE.md 管理、项目规范绑定管理、项目元数据管理（标签/备注/归档）、全局规范管理（同步/安装/删除/进化/YAML编辑/使用统计/进化历史）、阶段产物索引管理、动态节点类型管理（NodeTypeRegistry 可视化）、TemplateRegistry 可视化、动态流水线创建和手动推进、事件日志管理、数据库维护功能（备份/恢复/历史记录/诊断修复）、数据分析页面（会话统计、事件统计、API使用统计、成本分析、趋势图表），深度代码审查完成（9个核心页面4750行代码，发现28个问题，修复20个P0/P1/P2/P3问题，包括运行时错误修复、性能优化、竞态条件处理、UX体验改进、数据正确性和稳定性修复），节点类型管理页面和动态流水线节点展示组件已实现，NodeTypes 页面和 PipelineDetail 动态节点展示已集成，Legacy Pipeline 数据迁移支持已完成，节点类型 API 路由已注册，动态节点系统全栈集成完成，全栈集成验证通过（NodeTypes页面正常展示节点类型，PipelineDetail页面正常展示动态节点，API路由正常响应），节点类型持久化和恢复机制已实现，DynamicPipelineNodes组件支持产物可视化（类型图标、路径链接、验证状态徽章、复杂度驱动约束验证），知识图谱页面集成完成（搜索/概览/邻居/图谱可视化/CRUD操作），Analytics 页面支持会话统计、事件统计、API使用统计和成本分析，动态流水线 API 路由完整集成（/api/pipelines/dynamic 端点支持创建/查询/更新/删除/手动推进），产物约束验证支持复杂度驱动（simple/moderate/complex 动态调整约束严格度），Knowledge 页面集成知识图谱可视化和 CRUD 操作，产物验证器支持复杂度驱动约束动态调整，流程可控能力分析文档已集成到 docs/2026-04-25/架构设计/ 目录，流程可控硬阻断实现审查文档已集成到 docs/2026-04-25/代码审查/ 目录 [x] 2026-04-25 |
-| 阶段产物 | 每个阶段自动生成结构化文档 [x] 2026-04-25 |
-| 模式学习 | 从历史失败中提炼预防建议，支持 Thompson Sampling 策略选择 [x] 2026-04-25 |
-| 项目规范 | 根据技术栈自动蒸馏项目级规范，支持自动初始化和 AI 自进化 [x] 2026-04-25 |
+### 3. 质量检查（PostToolUse）
+AI 驱动的代码质量审查：
+- 每 3 次 Write/Edit 触发一次审查
+- 检测安全漏洞、代码质量问题
+- 终端红色警告 + 修复建议注入
 
----
+### 4. 历史记录（Stop）
+会话结束时自动生成：
+- `decisions.md` — 决策摘要
+- `timeline.md` — 时间线
+- `.claude-forge/history/YYYY-MM-DD-{session}.md` — 完整历史
 
-## 🚀 快速开始
+## 快速开始
 
-### 1. 安装
+### 安装
 
 ```bash
-# 从 npm 安装（推荐）
 npm install -g @winspan/claude-forge
-
-# 或从源码构建
-git clone https://github.com/your-org/claude-forge
-cd claude-forge
-npm install && npm run build && npm link
 ```
 
-### 2. 初始化
+### 初始化
 
 ```bash
 cf init
 ```
 
-初始化会完成：
-- ✅ 创建数据目录 `~/.claude-forge/`
-- ✅ 生成默认配置 `config.yaml`
-- ✅ 安装双向通信 Hook 脚本（PreToolUse/PostToolUse）
-- ✅ 注册到 Claude Code
+这会：
+1. 创建 `~/.claude-forge/` 目录
+2. 复制 Hook 脚本到 `~/.claude-forge/hooks/`
+3. 复制规则文件到 `~/.claude/conventions/`
+4. 注入 Hooks 到 Claude Code settings.json
 
-> ⚠️ 初始化后需要重启 Claude Code 会话，Hook 才会生效。
-
-### 3. 启动守护进程
+### 启动守护进程
 
 ```bash
-# 交互式 TUI 菜单
-cf
-
-# 或直接启动
 cf daemon start
 ```
 
-### 4. 打开 Web 管理后台
-
-```bash
-cf web
-```
-
-访问 http://localhost:3721 查看：
-- 📊 实时仪表盘
-- 💬 会话管理
-- 🔄 Pipeline 可视化
-- 🛡️ 质量门禁
-- 🧠 知识图谱
-- 📈 数据分析
-
-### 5. 验证运行
-
-在 Claude Code 中发送一条消息，观察回复前是否出现执行路径卡片：
-
-```
-┏━━━ Forge 执行路径 ━━━
-┃ 🎯 意图：重构认证模块（复杂度：complex）
-┃ 🛤️  路径：编排流程
-┃ 📋 计划：analyze → design → code → test → review
-┃ ⏱️  预估：30-45分钟
-┗━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## 📖 核心概念
-
-### Pipeline 编排
-
-复杂任务自动拆分为多阶段流程：
-
-```
-analyze（需求分析）
-  ↓
-design（架构设计）
-  ↓
-code（编码实现）
-  ↓
-test（测试验证）
-  ↓
-review（代码审查）
-```
-
-每个阶段完成时：
-- 🤖 AI 自动生成阶段产物文档
-- 🛡️ 质量门禁自动审查（含产物约束与语义一致性校验）
-- 📊 进度实时更新到 Web 后台
-
-### 分步驱动执行模型（Step Mode）
-
-**新特性**：将复杂节点拆分成多个小步骤，每次只告诉 Claude Code 当前这一步要干什么。
-
-```yaml
-# Convention 中定义 steps
-node_types:
-  - id: requirement-analysis
-    name: 需求分析
-    steps:
-      - id: collect-requirements
-        name: 收集需求信息
-        goal: 通过阅读文档收集需求关键信息
-        allowed_tools: [Read, Grep, Glob, Bash]  # 工具白名单
-        done_definition:
-          signal: FORGE_STEP_DONE
-        checks:
-          - type: file_exists
-            config:
-              path: docs/需求收集笔记.md
-        max_retries: 3
-      
-      - id: analyze-requirements
-        name: 分析需求
-        goal: 分析需求的核心要点、技术栈、复杂度
-        allowed_tools: [Read, Write, Edit, Bash]
-        # ... 更多配置
-```
-
-**核心特性**：
-- ✅ **精准控制** - 每次只暴露当前步骤的信息，不泄露后续步骤
-- ✅ **硬阻断** - 工具白名单拦截，不在白名单的工具直接拒绝
-- ✅ **状态透明** - 任何时刻都能知道执行到哪一步
-- ✅ **失败隔离** - 某一步失败只影响该步，不污染全流程
-- ✅ **精准重试** - 只重试失败的步骤，不重复已完成的工作
-- ✅ **人工接管** - 超过重试次数自动暂停，等待人工介入
-
-**使用方法**：
-1. 在 Convention 的 `node_types` 中添加 `steps` 字段
-2. 系统自动检测并切换到 Step 模式
-3. 无需修改现有 Convention（向后兼容）
-
-详细示例：[docs/step-mode-example.md](docs/step-mode-example.md)
-
-### 质量门禁
-
-每个阶段完成时强制触发 AI 审查与产物语义一致性校验：
-- ❌ 质量不过 → 阻止推进到下一阶段
-- ✅ 质量通过 → 自动推进
-- 📝 问题记录与缺失项 → 持久化到数据库（支持 must/should 分级阻断）
-
-### 知识积累
-
-自动提炼并持久化：
-- 📋 **决策日志** (`decisions.md`) - 关键决策和理由
-- ⏱️ **时间线** (`timeline.md`) - 项目演进历史
-- 📊 **复盘报告** (`retrospective.md`) - 任务执行分析
-- 📐 **项目规范** (`custom-convention.yaml`) - 自定义规范
-
-### 技能编排
-
-根据意图自动匹配并注入最佳实践：
-- 🧪 TDD（测试驱动开发）
-- 🐛 调试工作流
-- ♻️ 重构策略
-- 👀 代码审查清单
-- 🔒 安全加固
-
----
-
-## ⚙️ 配置
-
-### API Key 设置
-
-Forge 自动从以下位置获取 API Key（优先级从高到低）：
+守护进程会在后台运行，监听 Claude Code 的 Hook 事件。
 
-1. 环境变量 `ANTHROPIC_AUTH_TOKEN`
-2. 环境变量 `ANTHROPIC_API_KEY`
-3. 配置文件 `~/.claude-forge/config.yaml`
-
-**推荐方式**：
+### 查看状态
 
 ```bash
-# 设置 API Key
-cf config api --key "sk-ant-..."
-
-# 设置自定义端点（如代理）
-cf config api --url https://your-proxy.example.com
-
-# 切换 AI 提供商
-cf config api --provider openai    # 使用 OpenAI
-cf config api --provider ollama    # 使用 Ollama（本地）
-cf config api --provider claude    # 使用 Claude（默认）
+cf status
 ```
 
-### 配置文件
-
-配置文件位于 `~/.claude-forge/config.yaml`：
-
-```yaml
-# 存储
-storage:
-  path: ~/.claude-forge/data.db
-  max_size_mb: 1024
-
-# AI 提供商
-distill:
-  model: claude-sonnet-4-6
-  api_key: ""                   # 留空自动从环境变量获取
-  base_url: ""                  # 自定义端点
-
-# Autopilot
-autopilot:
-  enabled: true
-  intent_analysis: true         # 意图识别
-  knowledge_search: true        # 知识检索
-  quality_gate: true            # 质量门禁
-  auto_start_pipeline: true     # 自动启动 Pipeline
-  pipeline_confirm_mode: prompt # prompt | auto | preview
-
-# 会话续接
-resume:
-  enabled: true
-  timeout_minutes: 10
-  max_age_days: 7
-```
-
-### pipeline_confirm_mode 说明
-
-| 值 | 行为 |
-|----|------|
-| `prompt` | 展示 A/B/C 选项，等待用户选择（默认） |
-| `auto` | 自动启动完整编排，无需确认 |
-| `preview` | 仅展示执行卡片，不启动 Pipeline |
-
----
-
-## 工作原理
-
-### 事件流
-
-```
-用户输入
-  ↓
-Hook 脚本（bash）发送 JSON 事件到 Unix Socket
-  ↓
-守护进程接收 → 解析 → 分发到对应 Handler → 写入 events.jsonl
-  ↓
-UserPromptHandler  →  意图分析 + Pattern 路由 + 知识注入 + Pipeline 建议
-PreToolUseHandler  →  技能推荐注入 + Pipeline 阶段指令
-PostToolUseHandler →  质量门禁 + Pipeline 进度跟踪 + 命中率记录
-StopHandler        →  蒸馏 + 续接快照 + 技能进化 + CLAUDE.md 自动更新 + 任务复盘分析 + 阶段产物生成
-  ↓
-HookResponse（allow + additionalContext）返回给 Claude Code
-  ↓
-Claude 读取 additionalContext，按指令执行
-```
-
-### 关键路径
-
-| 路径 | 说明 |
-|------|------|
-| `~/.claude-forge/daemon.sock` | Unix Socket 通信 |
-| `~/.claude-forge/data.db` | SQLite 数据库 |
-| `~/.claude-forge/config.yaml` | 配置文件 |
-| `~/.claude-forge/daemon.log` | 守护进程日志 |
-| `~/.claude-forge/events.jsonl` | 结构化事件日志（JSONL，按项目分类） |
-| `~/.claude-forge/orchestration-config.json` | 技能编排关键词映射 |
-| `~/.claude-forge/patterns/` | Pattern 工作流定义（YAML，自动被 TemplateRegistry 加载转换为 PipelineTemplate） |
-| `{project}/.claude-forge/decisions.md` | 项目决策日志（含树索引 decisions.tree.json，支持 AI 推理检索；IntentEngine 优先走树索引，降级到关键词切片） |
-| `{project}/.claude-forge/timeline.md` | 项目时间线 |
-| `{project}/.claude-forge/retrospective.md` | 任务复盘日志（每次 Stop 自动追加） |
-| `{project}/docs/YYYY-MM-DD_HH-MM-SS/` | 阶段产物目录（Pipeline 各阶段文档，按时间戳分组，统一存放在项目 docs/ 下，包含 INDEX.md 索引；支持计划文档、质量报告、复盘报告、阶段产物统一管理） |
-| `{project}/.claude-forge/custom-convention.yaml` | 项目级自定义规范 |
-| `{project}/docs/plan-*.md` | Plan-First 计划文件（按版本存储，Claude 负责写，Forge 负责读；自动启动 Plan Mode 而非阻断；Stop 时兜底同步 ~/.claude/plans/ 最新计划到项目 docs/） |
-
----
-
-## CLI 命令参考
-
-CLI 入口：`claude-forge`（完整命令）或 `cf`（别名）。无子命令时自动启动交互式 TUI 菜单。
-
-### daemon — 守护进程管理
+### 配置 API Key
 
 ```bash
-cf daemon start [-f]    # 启动（-f 前台模式）
-cf daemon stop          # 停止
-cf daemon status        # 查看状态
-cf daemon restart       # 重启
-```
-
-### convention — 项目规范管理
+# 方式 1：环境变量
+export ANTHROPIC_API_KEY=sk-ant-...
 
-Convention 系统根据项目技术栈和已安装的源规范，自动蒸馏生成项目级自定义规范，并注入 CLAUDE.md。
-
-```bash
-cf convention list                    # 列出所有已安装的源规范
-cf convention show <id>               # 查看规范详情
-cf convention add <url|path>          # 安装源规范（自动触发蒸馏）
-cf convention distill                 # 将已安装规范蒸馏为项目自定义规范
-cf convention status                  # 查看当前项目规范绑定状态
-cf convention evolve                  # AI 自进化自定义规范（基于决策日志）
+# 方式 2：配置文件
+cf config edit
+# 添加：
+# distill:
+#   api_key: sk-ant-...
 ```
 
-**蒸馏逻辑**：
-- 无源规范时：根据项目技术栈自动生成规范
-- 有源规范时：融合所有源规范的核心优势，冲突维度生成"视场景而定"的折中原则
-- 已有自定义规范时：增量合并，不删除现有内容
-
-**自动初始化**：在未初始化的项目中打开 Claude Code 时，Forge 会自动提示是否初始化，确认后自动执行 `cf convention distill`。
-
-### pattern — Pattern 工作流
-
-Pattern 是多阶段工作流定义，存储在 `~/.claude-forge/patterns/*.yaml`。Forge 根据用户意图 AI 语义匹配最合适的 Pattern，并按阶段注入结构化执行指令。
+## 架构
 
-```bash
-cf pattern list                       # 列出所有已安装的 Pattern
-cf pattern show <id>                  # 查看 Pattern 详情
-cf pattern evolve [id]                # AI 自进化（基于执行历史优化 YAML）
-```
-
-**内置 Pattern**：
-- `bmad` — BMad 敏捷开发模式（产品分析 → 架构设计 → 编码实现 → 代码审查）
-- `harness-engineering` — 安全重构模式（理解 → 织网 → 修改 → 验证）
-- `spec-driven` — 规格驱动开发
-
-### skill — 技能管理
-
-```bash
-cf skill list                         # 列出所有技能
-cf skill search <query>               # 搜索技能
-cf skill install <url>                # 从 URL 安装技能
-cf skill evolve                       # 触发技能进化（质量修复、淘汰低质量、生成项目专属）
-cf skill distill                      # 手动触发社区蒸馏
-cf skill repair [--dry-run] [--limit N] # 检测并修复残缺/低质量技能
-cf skill add <name> -d <desc> [-t tags] # 添加自定义技能
-cf skill remove <name>                  # 移除自定义技能
-cf skill source list                    # 列出所有社区渠道（内置+用户）
-cf skill source add <repo> -d <dir>     # 添加自定义社区渠道
-cf skill source remove <repo>           # 移除自定义渠道
-cf skill orchestration list           # 查看编排关键词映射（含命中率统计）
-cf skill orchestration set <skill> -k <keywords> # 设置技能编排关键词
-cf skill orchestration remove <skill>   # 移除技能编排映射
 ```
-
-### pipeline — Pipeline 编排
-
-```bash
-cf pipeline list                      # 查看活跃 Pipeline
-cf pipeline close --expired           # 关闭过期 Pipeline（>2小时未更新）
-cf pipeline close --all               # 关闭全部 Pipeline
-cf pipeline close <id>                # 关闭指定 Pipeline
-```
-
-### profile — 用户画像
-
-```bash
-cf profile show                       # 查看当前画像
-cf profile init [--infer]             # 初始化（--infer 从现有数据推断）
-cf profile set                        # 更新画像字段
-cf profile reset                      # 重置为默认值
-cf profile export                     # 导出画像文件
-cf profile evolve                     # AI 分析行为日志，自动进化画像
-```
-
-`profile set` 支持的选项：
-
-| 选项 | 说明 |
-|------|------|
-| `--role <role>` | 角色（backend / frontend / fullstack） |
-| `--level <level>` | 经验水平（junior / mid / senior） |
-| `--style <style>` | 工作风格（guided / balanced / autonomous） |
-| `--stack <stack>` | 技术栈（逗号分隔） |
-
-### claudemd — CLAUDE.md 管理
-
-```bash
-cf claudemd detect                    # 检测项目技术栈（无需 API）
-cf claudemd init                      # 生成项目级 CLAUDE.md
-cf claudemd init -m                   # 生成模块级 CLAUDE.md（继承父项目规范）
-cf claudemd init -f                   # 强制重新生成（覆盖已有）
-cf claudemd scan                      # 扫描并批量生成所有子模块的 CLAUDE.md
-cf claudemd refine                    # 基于蒸馏数据手动触发 CLAUDE.md 细化
-cf claudemd show                      # 查看当前 CLAUDE.md 内容
-cf claudemd modules show              # 查看业务模块配置
-cf claudemd modules add-root <dir>    # 将目录下每个子目录视为独立模块
-cf claudemd modules add-dir <path>    # 将具体路径注册为独立模块
-cf claudemd modules skip <dir>        # 扫描时跳过该目录
-```
-
-### logs — 事件日志查看
-
-```bash
-cf logs                               # 查看最近事件（过滤 PreToolUse/PostToolUse 噪音）
-cf logs --verbose                     # 查看所有事件（含 PreToolUse/PostToolUse）
-cf logs -p <name>                     # 按项目名过滤
-cf logs -n <N>                        # 只看最后 N 条
-cf logs -f                            # 实时跟踪（follow）
-cf logs latency [--engine <name>] [--type <type>] [--days <n>] # 查看各引擎端到端延迟统计（P50/P95/max）
-cf logs --projects                    # 列出所有有日志的项目名
-```
-
-### distill — 手动蒸馏
-
-```bash
-cf distill                            # 立即蒸馏
-cf distill -s <session-id>            # 蒸馏指定会话
-cf distill -p <project-path>          # 蒸馏指定项目
-```
-
-### config — 配置管理
-
-```bash
-cf config show                        # 查看当前配置
-cf config set <key> <value>           # 设置配置项（支持嵌套键，如 distill.base_url）
-cf config api --key <key>             # 设置 API Key
-cf config api --url <url>             # 设置 API 端点
-cf config api --provider <type>       # 切换 AI 提供商（claude/openai/ollama）
-cf config reset                       # 重置为默认值
+src/
+├── cli/           363 行  — 4 个命令（init, daemon, status, config）
+├── core/          532 行  — 类型、配置、存储、AI、工具
+├── daemon/        825 行  — 守护进程 + 4 个 handler
+├── engine/       1743 行  — RuleEngine + DSL
+├── intelligence/  465 行  — 意图分析、质量门禁、蒸馏
+└── skills/        118 行  — 技能注册、匹配
 ```
 
-### backup — 备份与恢复
+### 4 条数据通路
 
-```bash
-cf backup                             # 创建备份
-cf restore <file>                     # 从备份恢复
-cf export -p <project>                # 导出指定项目数据
 ```
-
-### 其他
-
-```bash
-cf init                               # 初始化（注册 Hook）
-cf uninit                             # 卸载（移除 Hook，数据保留）
-cf query stats                        # 统计信息
-cf query sessions                     # 会话列表
+UserPromptSubmit → IntentClassifier → SkillRegistry → 注入技能推荐
+PreToolUse       → RuleEngine → block/warn/allow
+PostToolUse      → QualityGate → 注入纠偏 + 终端警告
+Stop             → Distiller → 导出历史
 ```
 
----
-
-## 配置说明
+## 自定义规则
 
-配置文件位于 `~/.claude-forge/config.yaml`。
+编辑 `~/.claude/conventions/*.yaml`：
 
 ```yaml
-# 存储
-storage:
-  path: ~/.claude-forge/data.db
-  max_size_mb: 1024
-
-# 蒸馏
-distill:
-  auto_trigger: true
-  event_threshold: 20           # 触发蒸馏的事件数阈值
-  timer_interval_minutes: 5
-  model: claude-sonnet-4-6
-  api_key: ""                   # 留空自动从环境变量获取
-  base_url: ""                  # 自定义 API 端点（留空使用官方）
-
-# 会话续接
-resume:
-  enabled: true
-  timeout_minutes: 10
-  max_age_days: 7
-
-# CLAUDE.md 自动生成
-claudemd:
-  auto_generate: true
-  auto_refine: true
-  refine_interval: 3            # 每 N 次蒸馏优化一次
-
-# Autopilot（意图识别 + 技能编排）
-autopilot:
-  enabled: true
-  intent_analysis: true
-  knowledge_search: true
-  quality_gate: true
-  quality_review_interval: 3   # 每 N 次代码修改触发一次审查
-  auto_start_pipeline: true
-  pipeline_confirm_mode: prompt  # prompt | auto | preview
-
-# Pattern 引擎
-pattern_engine:
-  enabled: true
-  route_timeout_ms: 60000
-  evolve_interval_days: 7
-  evolve_min_executions: 20
-```
-
-### pipeline_confirm_mode 说明
-
-| 值 | 行为 |
-|----|------|
-| `prompt` | 展示 A/B/C 选项，等待用户选择（默认） |
-| `auto` | 自动启动完整编排，无需确认 |
-| `preview` | 仅展示执行卡片，不启动 Pipeline |
-
----
-
-## 意图识别与编排
-
-### 复杂度分级
-
-| 复杂度 | 条件 | 执行路径 |
-|--------|------|---------|
-| `simple` | 查询、git 操作、无代码改动 | 直接放行 |
-| `moderate` | 1-5 个文件改动、范围明确 | 注入技能提示 |
-| `complex` | 6+ 文件、架构变更、范围不清 | Pattern 路由 → Pipeline |
-
-### Pattern 路由优先级
-
-1. **Pattern 路由**（AI 语义匹配）— 命中则按 Pattern 阶段执行
-2. **Pipeline 编排**（复杂度 complex）— 未命中 Pattern 时启动
-3. **技能注入**（moderate）— 直接注入相关技能提示
-
-### Pipeline 方案
-
-意图分析判断为 `complex` 且未命中 Pattern 时，Forge 展示三种方案：
-
-```
-A. 完整编排（推荐）— analyze → design → code → test → review
-B. 快速编排 — design → code → test
-C. 手动控制 — 不使用自动编排
-```
-
-### 多 AI 提供商
-
-Forge 通过 AIProvider 接口抽象支持多种 AI 提供商：
-
-| 提供商 | 配置值 | 说明 |
-|--------|--------|------|
-| Claude | `claude` | 默认，使用 Anthropic API |
-| OpenAI | `openai` | 支持 GPT-4 等模型 |
-| Ollama | `ollama` | 本地部署，无需 API Key |
-
-```bash
-cf config api --provider openai --key "sk-..."
+name: my-rules
+version: 1.0.0
+rules:
+  - id: no-force-push
+    when: tool == 'Bash' && args.command.contains('push --force')
+    level: warn
+    reason: Force push 会覆盖远程历史
 ```
 
----
-
-## 用户画像
-
-| work_style | 行为 |
-|------------|------|
-| `guided`（默认）| 提供建议和编排选项 |
-| `balanced` | 根据经验水平和复杂度决定 |
-| `autonomous` | 静默模式，不注入任何上下文 |
+重启 daemon 生效：
 
 ```bash
-cf profile set --style autonomous
-```
-
----
-
-## 开发
-
-```bash
-npm install
-npm run test           # 运行测试（Vitest）
-npm run build          # 构建（tsc）
-npm run lint           # 代码检查（ESLint）
-npm run format:check   # 格式检查（Prettier）
-npx tsc --noEmit       # 仅类型检查
+cf daemon stop
+cf daemon start
 ```
 
-Node.js 版本更换后需重新编译 native 模块：
+## 自定义技能
 
-```bash
-npm rebuild better-sqlite3
-```
+在 `~/.claude/skills/` 创建 Markdown 文件：
 
+```markdown
 ---
-
-## 技术栈
-
-- TypeScript + Node.js 18+
-- better-sqlite3（本地 SQLite 存储）
-- @anthropic-ai/sdk（Claude API）
-- Commander.js（CLI）
-- Zod（配置校验）
-- Vitest（测试）
-
+name: React 组件开发
+keywords: [react, 组件, component]
 ---
 
-## 💡 最佳实践
-
-### 1. 合理使用 Pipeline
-
-**适合使用 Pipeline 的场景**：
-- ✅ 架构重构
-- ✅ 新功能开发（涉及多个模块）
-- ✅ 性能优化（需要分析 + 实施 + 验证）
-- ✅ 复杂 Bug 修复（需要深入分析）
-
-**不适合使用 Pipeline 的场景**：
-- ❌ 简单的文本修改
-- ❌ 配置文件调整
-- ❌ 文档更新
-- ❌ 单文件小改动
-
-**提示**：可以通过 `pipeline_confirm_mode` 控制 Pipeline 启动方式。
+# React 组件开发最佳实践
 
-### 2. 充分利用知识积累
-
-**定期查看项目文档**：
-```bash
-# 查看决策日志
-cat .claude-forge/decisions.md
-
-# 查看时间线
-cat .claude-forge/timeline.md
-
-# 查看复盘报告
-cat .claude-forge/retrospective.md
+1. 使用函数组件 + Hooks
+2. Props 类型定义用 TypeScript interface
+3. 状态管理优先 useState，复杂场景用 useReducer
+...
 ```
 
-**在 Web 后台查看知识图谱**：
-- 访问 http://localhost:3721/knowledge
-- 搜索相关知识节点
-- 查看节点关系图
-
-### 3. 质量门禁配置
-
-**调整审查频率**：
-```yaml
-autopilot:
-  quality_review_interval: 3  # 每 3 次代码修改触发一次审查
-```
-
-**临时关闭质量门禁**（不推荐）：
-```yaml
-autopilot:
-  quality_gate: false
-```
-
-### 4. 用户画像调整
-
-**根据经验水平调整**：
-```bash
-# 新手模式（更多指导）
-cf profile set --style guided --level junior
-
-# 专家模式（最小干预）
-cf profile set --style autonomous --level senior
-```
+## 开发
 
-### 5. 监控和调试
+### 构建
 
-**实时查看日志**：
 ```bash
-cf logs -f
+npm run build
 ```
 
-**查看 Pipeline 状态**：
-```bash
-cf pipeline list
-```
+### 测试
 
-**查看 Web 管理后台**：
 ```bash
-cf web
+npm run test
 ```
 
----
-
-## ❓ 常见问题
-
-### Q: 守护进程没有启动，Claude Code 还能正常用吗？
-
-**A**: 可以。Hook 脚本在守护进程不可用时会静默失败，不影响 Claude Code 正常使用。
+### 端到端测试
 
-### Q: 如何查看 Forge 是否在工作？
-
-**A**: 
 ```bash
-cf daemon status
-cf logs -f
-```
-
-或者在 Claude Code 中发送消息，观察是否出现执行路径卡片。
+# 启动 daemon
+cf daemon start -f
 
-### Q: 重装 Node.js 后守护进程启动失败？
-
-**A**: 
-```bash
-npm rebuild better-sqlite3
+# 另一个终端发送测试事件
+./test-e2e.sh
 ```
 
-### Q: 如何关闭某个功能？
+## 对比 v2
 
-**A**: 编辑 `~/.claude-forge/config.yaml`，例如关闭质量门禁：
+| 指标 | v2 | v3 | 变化 |
+|------|----|----|------|
+| 文件数 | 212 | 37 | -82.5% |
+| 代码行数 | 35,617 | 4,046 | -88.6% |
+| CLI 命令 | 14 | 4 | 精简 |
+| Web UI | 有 | 无 | 第一版移除 |
+| 核心通路 | 4（被淹没） | 4（清晰可见） | ✅ |
 
-```yaml
-autopilot:
-  quality_gate: false
-```
+v3 移除了：
+- Web UI（可单独重写）
+- Pipeline 编排系统
+- 知识图谱
+- 技能自进化
+- CLAUDE.md 自动精炼
+- Convention 管理
 
-重启守护进程生效：`cf daemon restart`
+保留了：
+- RuleEngine + DSL（完整复用）
+- SQLite 存储（精简 schema）
+- AI Provider（Claude only）
+- Hook 脚本（完整复用）
 
-### Q: decisions.md 和 timeline.md 在哪里？
+## 许可证
 
-**A**: 
-```
-your-project/
-  └── .claude-forge/
-      ├── decisions.md
-      ├── timeline.md
-      ├── retrospective.md
-      └── custom-convention.yaml
-```
-
-### Q: Pipeline 卡住了怎么办？
-
-**A**: 
-1. 打开 Web 管理后台：`cf web`
-2. 进入 Pipeline 详情页
-3. 点击"继续执行"按钮
-4. 或者手动标记任务为完成
-
-### Q: 如何查看成本统计？
-
-**A**: 
-```bash
-cf query stats
-```
-
-或访问 Web 管理后台的"数据分析"页面。
-
-### Q: 如何完全卸载？
-
-**A**: 
-```bash
-cf uninit              # 移除 Hook（保留数据）
-rm -rf ~/.claude-forge # 彻底清除数据
-```
-
-### Q: 支持哪些 AI 提供商？
-
-**A**: 
-- **Claude**（默认）- Anthropic API
-- **OpenAI** - GPT-4 等模型
-- **Ollama** - 本地部署，无需 API Key
-
-切换方式：
-```bash
-cf config api --provider openai --key "sk-..."
-```
-
-### Q: Web 管理后台无法访问？
-
-**A**: 
-1. 确认守护进程已启动：`cf daemon status`
-2. 检查端口是否被占用：`lsof -i :3721`
-3. 查看日志：`tail -f ~/.claude-forge/daemon.log`
-
-### Q: 如何备份数据？
-
-**A**: 
-```bash
-cf backup
-```
+MIT
 
-备份文件保存在 `~/.claude-forge/backups/`。
+## 贡献
 
----
+欢迎提交 Issue 和 PR。
 
-## License
+## 相关链接
 
-MIT
+- [Claude Code](https://claude.ai/code)
+- [Anthropic API](https://docs.anthropic.com/)