Claude Forge

为 Claude Code 设计的会话治理引擎 —— 通过 Hook 机制把 Agent 路由、Skill 推荐、治理规则注入到 AI 开发流程中。

Claude Forge 是一个在本地运行的守护进程，通过 Claude Code 的 Hook API 拦截 UserPromptSubmit、PreToolUse、PostToolUse、Stop 等事件，在其中做意图分类、Agent 路由、Skill 推荐、规则阻断、治理建议。

版本: 见 cf --version · Node: >= 18（实际跑 24/26）· License: MIT

核心能力

完整架构 + drawio 图见 docs/architecture/README.md

1. Hook 驱动的治理

daemon 以 Unix socket 形式与 Claude Code 的 Hook 脚本通信。每次 UserPromptSubmit / PostToolUse 等事件，daemon 在 100ms 内决定要不要往上下文注入额外指令或建议。

2. Agent 路由

基于 intent 分析（complexity、taskType）和 YAML 规则，UserPromptSubmit 阶段建议 Claude 用哪个子 agent（researcher、tester、coder 等）。路由决策全程记录到 routing_events 表，可用于离线分析和 A/B 实验。

3. Skill 推荐系统

根据用户意图和项目上下文，自动推荐合适的 Skill（如 official-debug、official-tdd、official-refactor 等）。Skill 是可复用的工作流模板，帮助 Claude 按照最佳实践完成特定类型的任务。

Agent 还可以通过 MCP 工具 skill_invoke 按需获取 Skill 的完整方法论内容（需先运行 cf mcp register）。

4. Web 管理后台

claude-forge daemon start 默认在 http://127.0.0.1:<port>（默认端口 3721，可在 ~/.claude-forge/config.yaml 的 web.port 修改）开放一个 React 管理后台，覆盖：会话浏览、事件流、执行追踪、Agent/Skill 编辑、实时 SSE 日志。（AI Provider 配置面在 spec 0902 子 spec D R-C 永久下线，AI 流程改走本地 claude CLI 订阅）。

5. 长跑稳定性

• 自动同步：daemon 启动时自动将内置 hook 脚本同步到 ~/.claude/hooks/、将内置 skill 同步到 ~/.claude/skills/，防止 npm 升级后用户副本陈旧
• 数据 GC：每 24h 自动清理 30 天以上的 events / routing_events / skill_invocations / token_usage；每 7 天执行一次 SQLite VACUUM
• CI：GitHub Actions 在每次 push/PR 自动运行 tsc --noEmit + npm test + npm run build

安装方式说明

| 场景 | 命令 | 说明 | |---|---|---| | 普通用户 | npm i -g @winspan/claude-forge | 从 npm registry 拉最新发布版（推荐）| | 开发者本地测试 | git clone ... && cd claude-forge && npm i && npm run build && npm i -g . | 装本地代码，可能比 registry 新 | | 升级 | npm i -g @winspan/claude-forge@latest | 拉 registry 最新 |

查看实际装的版本：cf --version registry 当前最新：npm 页面

快速开始

# 1. 安装
npm install -g @winspan/claude-forge

# 2. 初始化（把 hook 脚本装到 ~/.claude/hooks/）
cf init

# 3. 启动 daemon
#    （AI Provider 配置已下线 — 见 spec 0902 子 spec D R-C，
#     AI 流程走本地 `claude` CLI 订阅，不再需要 daemon 持 API key）
cf daemon start

# 4. 打开管理后台（默认 3721，可在 ~/.claude-forge/config.yaml 修改 web.port）
open http://127.0.0.1:3721

# 4.5（可选）注册 MCP 服务器（让 Agent 能动态调用 Skill）
cf mcp register

# 5. （可选）查看架构图
open docs/architecture/diagrams/overview.drawio  # macOS 用 drawio desktop / web 打开

之后在任何目录下开 Claude Code 会话，daemon 会自动接管 hook 事件。

CLI 命令

| 命令 | 说明 | |---|---| | cf init | 初始化 hook 脚本到 ~/.claude/hooks/ | | cf daemon {start,stop,status,restart} | daemon 生命周期 | | cf daemon {install,uninstall} | 安装/卸载 macOS LaunchAgent（崩溃 auto-restart）| | cf daemon ensure-running | 心跳过期或 PID 死亡时强制重启 | | cf daemon logs [--tail] | 查看 daemon 日志 | | cf config {show,path,edit,list,get,set} | 配置管理 — runtime feature flags (forge_config 表) + YAML view/edit。ai.* / skill_matching.* 字段已在 spec 0902 子 spec D R-D 从 schema 中彻底删除（AI 流程改走 claude CLI 子进程，不再读 ANTHROPIC_API_KEY）；老 ~/.claude-forge/config.yaml 中的残留 ai: / skill_matching: 会被静默丢弃，daemon 启动时 warn 一次提示用户清理 | | cf status | 当前 daemon + Web + 存储概况 | | cf logs [--tail] | 查看 daemon 日志 | | cf stats | 近期 intent / 路由统计 | | cf agents | 列出已注册 agent | | cf decisions {register,update,outcome,...} | 决策治理：注册 spec / 回填 options / 闭环 outcome（C1 统一批准子系统）| | cf governance inject-global | 把决策治理协议写入 ~/.claude/CLAUDE.md（--remove 撤销）| | cf spec register | 注册 spec 文件等待批准（cf decisions register 的 thin alias）| | cf doctor | 环境/配置健康自检 | | cf fix | 一键修复常见环境/配置问题 | | cf skills list | 列出所有 skill（内置 + 用户层） | | cf skills invoke <id> | 调用指定 skill 并打印方法论 | | cf skills sync | 同步内置 skill 到 ~/.claude/skills/ | | cf skills upgrade | AI 辅助升级 official skill（默认 dry-run，报告到 ~/.claude-forge/skill-upgrade-report.md；--apply 应用决策，自动备份 + 提示 git commit） | | cf trace <commit> | 查看 commit 关联的 session | | cf executions {list,show} | 浏览历史执行记录 | | cf mcp | MCP 配置 | | cf claudemd | 生成/更新项目 CLAUDE.md（通过 claude CLI 子进程 + claudemd-writer agent，不再读 ANTHROPIC_API_KEY） | | cf knowledge {init,build,update,query,list,audit,clean,rollback,fix} (alias: cf kb) | 项目知识库（.forge-knowledge/）。init / build / update / fix 通过 claude CLI 子进程 + knowledge-builder agent，不再读 ANTHROPIC_API_KEY；fix 是一次性维护入口（修补陈旧/缺失 KB page）；query / list / audit / clean / rollback 纯本地 | | cf template | 模板管理 | | cf menu | 交互式菜单（推荐入口） |

也可用 claude-forge 作为 cf 的完整别名。

详细见 docs/skill-upgrade-guide.md

Web 管理后台

主要页面：

• /health — 整体健康度（默认入口）
• /tasks — 任务列表 + 详情
• /context — Knowledge / Skills / Agents 浏览（旧 /skills /knowledge redirect 进来）
• /violations — 治理违规记录
• /settings — 主题 / 关于（AI 配置面已在 spec 0902 子 spec D R-C 删除）

老 v2/v3 URL（/sessions /events /dashboard /pipeline /resources /skills /knowledge）会自动 redirect 到新位置。/ai-config 老 URL 在 R-C 永久下线，落 NotFound。

所有列表支持搜索 + JSON/CSV 导出。

Skill Distillation

claude-forge 内置 12 个开箱即用的 distilled skill（已蒸馏自上游优秀开源 skill 仓库），首次 cf daemon start 时自动同步到 ~/.claude/skills/，无需任何配置。

# 查看本机已安装的 distilled skills
ls ~/.claude/skills/distilled-*.md

# 同步触发（通常 daemon 启动时已经做了，无需手动）
cf daemon restart

# 列出所有 skill（distilled + user-owned）
cf skills list

# 调用某个 distilled skill 看完整方法论
cf skills invoke distilled-systematic-debugging

自己蒸馏额外的 skill

蒸馏入口已收敛到 Web 仪表盘：打开 http://127.0.0.1:3721/context?tab=distill → 点【开始蒸馏】。daemon 通过本地 claude CLI 子进程跑（child_process.spawn + -p --agent skill-distiller --bare --output-format stream-json），走你已经 付费的 Claude Code 订阅 / OAuth keychain，daemon 自身不持 ANTHROPIC_API_KEY。

前置条件：本机已安装 claude CLI（brew install claude 或 npm i -g @anthropic-ai/claude-code）。Web 仪表盘顶部会自动检测并显示 binary 路径（claude CLI: ✓ /opt/homebrew/bin/claude）。未安装时按钮会被 disable + 显示安装提示。

蒸馏流程（单次按钮点击发生的事情）：

1. daemon spawn claude -p --agent skill-distiller …
2. agent 读 upstream skill markdown → 按 D1-D5 维度自评分（0-5）
3. 评分 < 3 → 输出 ---SKIP--- envelope（含 score + rationale，UI 显示为 skipped）
4. 评分 ≥ 3 → 输出 ---SKILL--- envelope（含通用化 markdown body）
5. daemon parseSkillBlock() 提取 body → project-anchor-guard 自查 → 写入 src/skills/distilled/distilled-xxx.md + NOTICE 归因

设计 spec：docs/design/2026-05-28/1851-distill-via-claude-cli-shellout-spec.md

自定义 / 覆盖建议

• 不要直接编辑 ~/.claude/skills/distilled-*.md —— daemon 重启时若 hash 不一致会跳过覆盖（保护你的改动），但版本升级时新 skill 不会自动应用，需手动 diff
• 要做项目级自定义：另存为 my-<name>.md 或 team-<name>.md，my-* 前缀不在内置 sourceSet 内，永不被覆盖
• 想完全替换某个 distilled skill：删掉它然后 cf daemon restart，会按当前最新版本重新生成

更多细节见 DEVELOPMENT.md § Skill 蒸馏 与 § skill-distiller agent 使用说明。

CLAUDE.md 生成（cf claudemd init/update）

cf claudemd init / cf claudemd update 现在通过本地 claude CLI 子进程跑 —— daemon spawn claude -p --agent claudemd-writer --bare，agent 读取项目技术栈 + 目录树 + persona + 已有 conventions（由 host 通过 stdin 注入），输出包在 ---CLAUDEMD---...---END--- envelope 内的 markdown body。

前置条件：本机已安装 claude CLI（brew install claude 或 npm i -g @anthropic-ai/claude-code）—— 与 Skill Distillation 相同的 install hint。

不再依赖 ANTHROPIC_API_KEY —— 走你已经付费的 Claude Code 订阅 / OAuth keychain，daemon 自身不持 API key。

更多细节见 DEVELOPMENT.md § CLAUDE.md 生成与维护 与 § claudemd-writer agent 使用说明。

设计 spec：docs/design/2026-05-29/0902-ai-config-removal-master-spec.md 子 spec A

项目知识库（cf knowledge）

cf knowledge init / cf knowledge build / cf knowledge update 现在通过本地 claude CLI 子进程跑 —— host 起 claude -p --agent knowledge-builder --bare 子进程，agent 每个 KB page 输出一个 ---KB---...---END--- envelope，host 解析 后写入 .forge-knowledge/modules/*.md + .forge-knowledge/<cross-module>.md + .meta.json + repo-map.json。

前置条件：本机已安装 claude CLI（brew install claude 或 npm i -g @anthropic-ai/claude-code）—— 与 Skill Distillation / CLAUDE.md 生成相同的 install hint。

不再依赖 ANTHROPIC_API_KEY —— 走你已经付费的 Claude Code 订阅 / OAuth keychain，daemon 自身不持 API key。

# 首次构建（含 git hook 安装）
cf knowledge init

# 增量更新（基于 git diff）
cf knowledge update

# 查询（纯本地 keyword + repo-map，不需要 claude CLI）
cf knowledge query "daemon socket"

注意：cf knowledge query --strategy rerank（AI 重排序）已在 Spec 2 Stage B（commit 797326f8）下线 —— 现在仅 keyword + repo-map 检索。

更多细节见 DEVELOPMENT.md § knowledge-builder agent 使用说明。

设计 spec：docs/design/2026-05-29/0902-ai-config-removal-master-spec.md 子 spec B

AI 辅助 Patch 预览（Web POST /api/patch/preview）

Web 仪表盘 / 外部脚本可以 POST 一段 { targetType, targetName, recommendation, rationale } 到 /api/patch/preview，daemon 会通过本地 claude CLI 子进程跑 claude -p --agent patch-applier --bare，agent 输出 PATCH（unified diff）或 NOPATCH（连同 reason）envelope，host 解析后回 JSON。

前置条件：本机已安装 claude CLI（brew install claude 或 npm i -g @anthropic-ai/claude-code）—— 与 Skill Distillation / CLAUDE.md 生成 / 项目知识库相同的 install hint。

不再依赖 ANTHROPIC_API_KEY —— 走你已经付费的 Claude Code 订阅 / OAuth keychain，daemon 自身不持 API key。

⚠️ 响应字段 BREAKING（R-A → R-B）：R-A 阶段 /api/patch/preview 返回 {after, summary, risk}；R-B 之后改为 discriminated union {patch} | {noPatch, reason}。HTTP 错误码也细分为 499（cancel）/ 504（timeout）/ 500（missing / exit / unknown）。前端 / 脚本如果有调用 该端点，必须按新 schema 适配。

当前 web/src/ 内置前端尚未集成 patch UI（grep api/patch web/src = 0 命中）。如未来加 Web 前端 patch 预览界面，参照 spec C 「前端处理」段落。 POST /api/patch/apply 路径未变（始终是纯 fs write + backup，不走 LLM）。

更多细节见 DEVELOPMENT.md § patch-applier agent 使用说明。

设计 spec：docs/design/2026-05-29/0902-ai-config-removal-master-spec.md 子 spec C

Project Map

| 模块 | 一句话职责 | |---|---| | src/core/ | 共享内核：SQLite 存储、配置、类型契约 | | src/daemon/ | 守护进程：Unix socket server + hook 事件分发 + 服务编排 | | src/skills/ | Skill 系统：内置 12 个 distilled + 用户层 + AI 辅助升级 | | src/web/ | Express + SSE 后端 + React 仪表盘 | | src/cli/ | claude-forge / cf 命令入口 | | src/hooks/ | bash 脚本，与 daemon 通过 Unix socket 通信 | | src/knowledge/ | v9.3 项目知识库（cf knowledge build/update/query/audit/list/clean/rollback），含 5 跨模块页、3 个 MCP 工具（knowledge_query / knowledge_get_page / repo_map_lookup）。build 通过本地 claude CLI 子进程 + knowledge-builder agent（spec 0902 子 spec B），不再读 ANTHROPIC_API_KEY。注：AI rerank 检索路径已在 Spec 2 Stage B（commit 797326f8）下线，仅保留 keyword + repo-map 查询。 |

贡献

开发者文档见 DEVELOPMENT.md，包含仓库布局、构建/测试流程、架构说明、如何新增 Agent 或 Skill。

License

MIT © 2026 winspan