@winspan/claude-forge 8.51.1 → 8.54.3

package/DEVELOPMENT.md

@@ -2,80 +2,128 @@
 
 面向 claude-forge 贡献者的架构与工作流说明。
 
+> 高层架构 + 设计决策见 [docs/architecture/README.md](./docs/architecture/README.md)
+
 ---
 
 ## 仓库布局
 
 ```
 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
+├── core/                       共享核心，不反向依赖业务层
+│   ├── storage/                SQLite 存储（schema.sql + sqlite.ts），WAL 模式，单一 data.db
+│   │   ├── schema.sql            建表初始化
+│   │   ├── migrations/           增量 .sql 迁移
+│   │   ├── events.ts             writeEvent / queryEvents
+│   │   ├── sessions.ts           querySessions / upsertSession / countAllSessions
+│   │   ├── tasks.ts              writeTask / queryTasks / task_events
+│   │   ├── injections.ts         hook 注入审计
+│   │   ├── routing.ts            routing_events 表
+│   │   ├── skills.ts             skill_invocations 表
+│   │   ├── token-usage.ts        token_usage 聚合
+│   │   ├── base.ts / rows.ts     连接 + 行映射工具
+│   │   ├── maintenance.ts        清理/压缩
+│   │   └── performance-indexes.sql  附加索引
+│   ├── ai/                     ClaudeProvider 封装（用于 classifier、distiller、skill-upgrade）
+│   ├── queue/                  通用 SQLite 队列工具
+│   ├── utils/                  logger / git / path / time / lru-cache / forge-resume-block 等
+│   ├── config.ts               ConfigManager（~/.claude-forge/config.yaml）
+│   ├── constants.ts            FORGE_PATHS、各类阈值常量
+│   ├── event-fields.ts         hook 事件字段统一抽取
+│   └── types.ts                ForgeEvent / HookResult 等核心类型契约
+│
+├── daemon/                     后台守护进程
+│   ├── index.ts                  入口：socket server + 生命周期 + 同步任务
+│   ├── server.ts                 Unix socket 接收 hook payload
+│   ├── router.ts                 按 hook_type 分发到 handler
+│   ├── lifecycle.ts              启停 / 信号处理
+│   ├── event-parser.ts           hook 原始 JSON → ForgeEvent
+│   ├── hook-sync.ts              启动时把 dist/hooks/ 同步到 ~/.claude/hooks/
+│   ├── skill-sync.ts             启动时把 dist/skills/official/ 同步到 ~/.claude/skills/
+│   ├── launchd-installer.ts      macOS launchd 安装
+│   ├── launchd/                  launchd plist 模板
 │   ├── handlers/
-│   │   ├── user-prompt.ts          UserPromptSubmit：分类 + 路由 + 方法论
-│   │   ├── pre-tool-use.ts         PreToolUse：规则阻断
-│   │   ├── post-tool-use.ts        PostToolUse：质量检查 + 方法论推进
-│   │   ├── stop.ts                 Stop：蒸馏 + 方法论兜底
-│   │   ├── methodology-formatter.ts 生成前/后台 directive 文本
+│   │   ├── user-prompt.ts          UserPromptSubmit：分类 + skill 推荐 + agent 路由
+│   │   ├── post-tool-use.ts        PostToolUse：观察，按需注入提示
+│   │   ├── stop.ts                 Stop：写 session 摘要、distill 决策
 │   │   └── 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
+│   └── services/
+│       └── task-segmenter.ts       UserPromptSubmit 按时间窗划分任务段
+│
+├── skills/                     Skill 推荐与方法论分发
+│   ├── registry.ts               扫描 ~/.claude/skills/ + src/skills/official/，提供 match()
+│   ├── matcher.ts                关键词匹配
+│   ├── semantic-matcher.ts       AI 语义匹配（可选，需 API key）
+│   ├── invocation-guard.ts       防止 agent 重复 invoke 同一 skill
+│   ├── upgrade-engine.ts         社区 skill 升级核心：pull / match / evaluate / apply
+│   ├── upgrade-prompt.ts         AI evaluator prompt 模板
+│   ├── official-skills.ts        加载内置官方 skill
+│   ├── official/                 内置官方 skill .md 源（随发布打包）
+│   ├── tools/                    MCP 工具：skill_invoke / skill_list / pipeline_suggest
+│   └── index.ts                  对外导出
+│
+├── web/                        Web 管理后台
+│   ├── server.ts                 Express 服务器 + 路由注册
+│   ├── auth-middleware.ts        本地 token 校验
+│   ├── ssrf-guard.ts             SSRF 防护
+│   ├── routes/                   每个 API 模块独立文件（sessions / events / tasks / skills / ai / patch ...）
+│   ├── analytics/                趋势/统计计算
+│   └── static/                   React 前端构建产物的最终落点（dist/web/static/）
+│
+├── cli/
+│   ├── index.ts                  CLI 入口（commander）
+│   ├── init/                     `cf init`：安装 hook 脚本
+│   └── commands/                 子命令：daemon / config / skills / claudemd / status / logs / stats / menu / trace / mcp / executions / template
+│
+├── claudemd/                   CLAUDE.md 生成与维护
+│   ├── tech-detector.ts          项目技术栈识别
+│   ├── claudemd-generator.ts     生成 CLAUDE.md 正文
+│   ├── convention-extractor.ts   从已有规则提取约定
+│   ├── resume-manager.ts         forge:resume 块续接管理
+│   ├── persona-manager.ts        用户 persona 段管理
+│   ├── templates/                各类模板（含 swarm-protocol.md）
+│   └── index.ts                  对外导出
+│
+├── hooks/                      Shell 脚本：从 Claude Code 桥接到 daemon socket
+│   ├── hook-lib.sh                 共用工具（payload 拼装、容错）
+│   ├── user-prompt-submit.sh
+│   ├── pre-tool-use.sh
+│   ├── post-tool-use.sh
+│   ├── stop.sh
+│   └── notification.sh
+│
+├── mcp/                        MCP server（暴露 skill_invoke / skill_list / pipeline_suggest 给 agent）
+│   └── server.ts
+│
+└── templates/                  新项目初始化模板
+
+web/                            React 前端源码（独立 npm workspace）
+  ├── src/pages/                 各业务页面（lazy-loaded）
+  ├── src/components/            通用组件
+  └── vite.config.ts             Vite + 手动 manualChunks
+
+tests/
+  └── unit/                      vitest 单测（vitest.config.ts include 此目录）
+       ├── core/ daemon/ skills/ storage/ utils/ web/ hooks/  各模块独立子目录
+       └── *.test.ts             顶层综合测试
+
+scripts/                        辅助脚本：dev-daemon / dev-web / e2e-* / sync-agent-skills / check-spec-changelog 等
+docs/
+  ├── design/                    spec（planner 输出）
+  ├── implementation/            changelog（coder 输出）
+  └── skill-upgrade-guide.md     skill 升级流程
 ```
 
 ## 目录依赖约束
 
 - `core` 不反向依赖业务层
-- `engine` 可依赖 `core`
-- `intelligence` 可依赖 `core` / `engine`
-- `capability` 可依赖 `core` / `engine` / `intelligence`
-- `daemon` 可依赖 `core` / `engine` / `intelligence` / `capability` / `agents` / `skills`
-- `cli` 做命令分发，不塞核心规则逻辑
+- `skills` 可依赖 `core`
+- `claudemd` 可依赖 `core`
+- `daemon` 可依赖 `core` / `skills` / `claudemd`
+- `web` 可依赖 `core` / `skills` / `claudemd`（不依赖 `daemon`）
+- `mcp` 可依赖 `core` / `skills`
+- `cli` 做命令分发，可依赖任意模块，但不塞核心规则逻辑
+- `hooks/*.sh` 不依赖代码，只通过 socket payload 跟 daemon 通信
 
 ---
 
@@ -86,225 +134,246 @@ scripts/                 开发/调试脚本：dev-web、demo-v2、smoke-backgro
 npm install
 npm run build
 
-# 启动 daemon（开发模式，用 tsx 直跑 ts）
-npm run dev:daemon
+# 启动 daemon（开发模式，复用 ./scripts/dev-daemon.sh）
+npm run dev:daemon:start
+npm run dev:daemon:restart
+npm run dev:daemon:logs
+npm run dev:daemon:stop
 
-# 启动 web dev 同步（监听 web/src 变化自动拷贝到 dist/web/static/）
-npm run dev:web
+# 前端开发（在 web/ 目录）
+cd web && npm install && npm run dev
 ```
 
-CLI 开发：`npm run dev -- <command>`（比如 `npm run dev -- status`）。
+Daemon / CLI 都用系统 node（项目要求 Node 18+，实际跑在 24/26 上）。
 
 ---
 
 ## 构建与测试
 
 ```bash
-# 后端：tsc + 拷贝 hooks/schema/yaml 到 dist/
+# 后端：tsc + 拷贝 hooks / schema / templates / 前端产物到 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       # 覆盖率
+npm test                      # vitest run（只跑 tests/unit/）
+npm run test:watch            # watch 模式
 
-# TS 双侧检查
+# TS 类型检查
 npx tsc --noEmit
 cd web && npx tsc --noEmit
+
+# spec / changelog 配对检查（开发流程治理）
+npm run check:specs
 ```
 
-> 发布流程：`npm run prepublishOnly`（= `npm run build`）会自动跑一遍，之后 `npm publish` 即可。发布前记得 `bump version`（两处：`package.json` + `package-lock.json`）。
+> 发布流程：用户手动 `npm publish`。AI 只做 `git commit / git push` 和 bump version（`package.json` 一处）。
 
 ---
 
 ## 架构要点
 
-### 方法论执行链路
+### Hook 事件流
 
 ```
-┌───────────────────────┐       ┌──────────────────┐
-│  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 Code  ──hook payload(JSON via stdin)──►  src/hooks/*.sh
+                                                      │
+                                                      ▼
+                            $(socat / nc) ──►  ~/.claude-forge/daemon.sock
+                                                      │
+                                                      ▼
+                              src/daemon/server.ts (接收 + 反序列化)
+                                                      │
+                                                      ▼
+                              src/daemon/event-parser.ts (统一 ForgeEvent)
+                                                      │
+                                                      ▼
+                              src/daemon/router.ts ──┬──► handlers/user-prompt.ts
+                                                     ├──► handlers/post-tool-use.ts
+                                                     ├──► handlers/stop.ts
+                                                     └──► (PreToolUse / Notification: 直接 allow)
+                                                      │
+                                                      ▼
+                              core/storage/* 持久化 + 返回 HookResult
+                                                      │
+                                                      ▼
+                              Claude Code 读取 HookResult.systemMessage / additionalContext / allow
 ```
 
-### 存储
+要点：
+- daemon 必须在 100ms 内返回，超时则 Claude Code 视为放行
+- handler 抛错被 router 捕获，不会让 daemon 崩溃
+- `PreToolUse` 当前不做规则阻断，统一放行
+- daemon 不主动推消息：任何延后的指令必须等下一次 UserPromptSubmit 注入
 
-- `~/.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` 检测）
+### Skill 系统
 
-### Hook 注入原则
+```
+┌─────────────────────┐
+│ UserPromptSubmit    │
+│ handler             │
+└─────────┬───────────┘
+          │
+          ▼
+┌──────────────────────────┐         ┌──────────────────────────┐
+│ SkillRegistry.match()    │ ───────►│ semantic-matcher (AI)    │
+│ (registry.ts)            │         │ 若配置了 API key 则优先  │
+│                          │         └────────────┬─────────────┘
+│ 扫描两类来源：           │                      │ 失败/无 key
+│  - 内置 src/skills/      │                      ▼
+│    official/*.md         │         ┌──────────────────────────┐
+│  - 用户 ~/.claude/skills/│ ───────►│ keyword matcher          │
+│    {name}.md             │         │ (matcher.ts)             │
+│    or {name}/SKILL.md    │         └────────────┬─────────────┘
+└──────────────────────────┘                      │
+          │                                       │
+          ▼                                       ▼
+┌──────────────────────────────────────────────────────┐
+│ invocation-guard 防重复 → 注入 systemMessage 推荐    │
+│ (skill_invocations 表落库)                            │
+└──────────────────────────────────────────────────────┘
+
+Agent 通过 MCP 工具：
+  - skill_list           列出可用 skill
+  - skill_invoke <id>    取完整方法论
+  - pipeline_suggest     根据 intent 拼工作流
+```
 
-- UserPromptSubmit 返回 `{ systemMessage, additionalContext, allow }`；systemMessage 优先级高于 additionalContext
-- PostToolUse 只能观察，不能修改工具结果；返回 systemMessage 会拼到 Claude 下一轮的系统消息
-- Stop 返回 systemMessage 会作为"本轮结束"的最后一条系统提示
-- **daemon 无法主动推送消息**。前台方法论的兜底设计正是基于这条约束（Stop → 写 pending 队列 → 下一次 UserPromptSubmit 消费）
+frontmatter 必须有 `name: string`，否则 registry 静默跳过（debug 日志，不打扰用户）。`keywords` 与 `tags` 都接受。
 
-### Agent Worker 隔离
+### Skill 远程升级
 
-后台 BackgroundExecutor spawn `claude -p` 时：
+`cf skills upgrade` 由 `src/skills/upgrade-engine.ts` 驱动，三阶段：
 
-- **不用 `--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`
+1. `pullCandidates(DEFAULT_SOURCES, ~/.claude-forge/skill-candidates/)`
+   - 默认源：`addyosmani/agent-skills` + `obra/superpowers`
+   - 已存在则 `git pull`，不存在则 `git clone`
+2. 对每个候选用 `matchToOfficial()` 找最相似官方 skill，再用 `evaluateWithAI()` 让 AI 给出 `upgrade / merge / skip`，AI 解析失败 → `needs_review`
+3. `generateReport()` 写到 `~/.claude-forge/skill-upgrade-report.md`，每条带 `<!-- upgrade-entry: ... -->` 标记
+4. `cf skills upgrade --apply` 读报告 → 备份 `~/.claude-forge/backups/skills/<ts>/` → 覆盖 `src/skills/official/`
+5. `--rollback <ts>` 反向拷回
 
----
+详见 `docs/skill-upgrade-guide.md`。
 
-## 调试技巧
+### CLAUDE.md 生成与维护
 
-```bash
-# 看 daemon 日志（启动时写在 stderr，daemon 模式写入 ~/.claude-forge/daemon.log）
-tail -f ~/.claude-forge/daemon.log
+`src/claudemd/` 负责项目级规则文件的生成、续接与扩充：
 
-# 直接查 SQLite 运行时数据
-sqlite3 ~/.claude-forge/data.db "SELECT id, methodology_id, status, mode, current_phase_index FROM methodology_executions ORDER BY id DESC LIMIT 10"
+- `tech-detector.ts` — 识别项目语言/框架（读 `package.json` / `pyproject.toml` 等）
+- `claudemd-generator.ts` — 拼装结果到 `CLAUDE.md`
+- `convention-extractor.ts` — 把已有规则段抽离合并
+- `resume-manager.ts` — 维护 `<!-- forge:resume-begin -->` 续接块（daemon 在 Stop 时写入）
+- `persona-manager.ts` — 用户自定义 persona 段
+- 模板存放在 `src/claudemd/templates/`（build 时拷到 `dist/claudemd/templates/`）
 
-# 查看后台 worker 的完整 stream-json 日志
-ls ~/.claude-forge/logs/
+入口命令：`cf claudemd detect` / `cf claudemd init` / `cf claudemd update`（详见 `src/cli/commands/claudemd.ts`）。
 
-# Hook 脚本手工模拟（绕开 Claude Code）
-echo '{"session_id":"test","hook_type":"UserPromptSubmit","user_prompt":"重构xxx"}' | ~/.claude/hooks/user-prompt-submit.sh
+### Daemon 自动同步
 
-# Web 后台 SSE 实时监控（默认 3456，可在 ~/.claude-forge/config.yaml 修改 web.port）
-curl -N http://127.0.0.1:3456/api/methodology-executions/events
-```
+daemon 启动时（`src/daemon/index.ts`）执行两个一次性同步：
 
----
+- `syncHooks()` — 把 `dist/hooks/*.sh` 对照 sha256 同步到 `~/.claude/hooks/`，避免用户忘了重跑 `cf init`
+- `syncSkills()` — 把 `dist/skills/official/*.md` 同步到 `~/.claude/skills/`，user-owned 文件（已存在）跳过
 
-## 新增方法论
-
-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]
----
+### 数据流（事件 → API → UI）
 
-完整 agent 系统指令...
+```
+hook event ──► writeEvent()            ──┐
+            ──► writeTask()/task_events ─┤
+            ──► writeRoutingEvent()     ─┼─► ~/.claude-forge/data.db
+            ──► writeSkillInvocation()  ─┤
+            ──► writeInjection()        ─┘
+                       │
+                       ▼
+              src/web/routes/*.ts (queryXxx)
+                       │
+                       ▼
+              GET /api/events / sessions / tasks / skill-invocations ...
+                       │
+                       ▼
+              web/src/pages/*.tsx (TanStack Query)
 ```
 
-或通过 Web UI `/agents` 可视化编辑。daemon 启动时 AgentRegistry 会扫描并加载。
+存储：
+- 主库 `~/.claude-forge/data.db`，表：`events`、`sessions`、`tasks`、`task_events`、`injections`、`routing_events`、`token_usage`、`skill_invocations`
+- Schema 由 `src/core/storage/schema.sql` 初始化
+- 增量改动放 `src/core/storage/migrations/*.sql`（按文件名顺序执行）
 
----
+### 长跑稳定性（v8.53.6 加）
+
+daemon 通过三个机制保证长时间运行不膨胀：
 
-## 测试规范
+- **多表 GC**：`cleanOldData(30)` 定期清理 30 天前的 events / routing_events / skill_invocations / token_usage，防止数据库无限增长
+- **SQLite VACUUM**：`runMaintenance(500)` 在数据库超过 500 MB 时触发 `VACUUM`，回收空间；上次 VACUUM 超 7 天也强制执行
+- **Stale task 回收**：`staleTaskGcInterval` 每 5 分钟扫描并关闭异常 active 状态的 task（避免僵尸任务阻塞计数）
 
-- 单元测试放 `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 一个单测，关键路径需要集成测试
+相关代码：`src/core/storage/maintenance.ts`（cleanOldData / runMaintenance），daemon 在 `src/daemon/index.ts` 启动时注册定时任务。
 
 ---
 
-## 发布流程
+## 添加新 Hook
 
-```bash
-# 1. 本地全量验证
-npm run build:all
-npx tsc --noEmit && (cd web && npx tsc --noEmit)
-npm test
+1. 在 `src/hooks/` 加 `.sh` 脚本，复用 `hook-lib.sh` 的 payload 工具
+2. `src/daemon/event-parser.ts` 加 hook_type 解析（如有新字段）
+3. `src/daemon/router.ts` 加分发分支；如需 handler 新建 `src/daemon/handlers/<name>.ts`
+4. `src/core/types.ts` 加事件类型 + type guard
+5. 重 build 后 `cf init` 重装 hook，或重启 daemon 让 `syncHooks()` 自动覆盖
+6. 测试覆盖：hook 脚本 + handler 都要补 `tests/unit/`
+
+> hooks/*.sh 无单元测试覆盖，改 hook 必走 Hybrid 工作流（见根 CLAUDE.md「工作流升级判定」）。
 
-# 2. bump version
-# package.json + package-lock.json 两处同步改
+## 添加新 Skill
 
-# 3. commit + tag
-git commit -am "chore: bump version to X.Y.Z"
-git tag vX.Y.Z
+最简方式：在 `src/skills/official/<name>.md` 写 frontmatter：
 
-# 4. publish
-npm publish   # 自动触发 prepublishOnly
+```markdown
+---
+name: my-skill
+description: 用一句话说明 skill 触发场景
+keywords: [refactor, legacy, test]
+version: 1.0.0
+---
 
-# 5. push
-git push && git push --tags
+# 方法论正文
+
+完整的多 phase 工作流...
 ```
 
+发布后 daemon 启动会自动 sync 到用户的 `~/.claude/skills/`。如果是只面向自己的 skill，直接放 `~/.claude/skills/` 即可。
+
+社区 skill 升级走 `cf skills upgrade`，详见 `docs/skill-upgrade-guide.md`。
+
+## 添加新 CLI 子命令
+
+1. 在 `src/cli/commands/<name>.ts` 写 `register(program)`
+2. 在 `src/cli/index.ts` 引入并调用 `register()`
+3. 子命令测试放 `tests/unit/cli-<name>.test.ts`
+
 ---
 
-## 排障清单
+## 故障排查
 
-| 现象 | 可能原因 |
+| 现象 | 排查 |
 |---|---|
-| 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` 追加分组 |
+| Hook 没触发 | `ls -la ~/.claude/hooks/` 看是否指向 `dist/hooks/`；缺失就跑 `cf init`；或重启 daemon 让 `syncHooks()` 自动补 |
+| daemon 启动报 `EADDRINUSE` | 上次进程没退；`cf daemon stop` 或 `lsof -i :3721` 找 pid 杀 |
+| Web 后台 404 | `dist/web/static/` 是否存在；`npm run build` 是否成功；Vite 前端 `cd web && npm run build` 后再 root build |
+| Skill 没被推荐 | `cf skills list` 看是否加载；frontmatter 检查是否缺 `name` 字段；语义匹配需要 `cf config` 配 API key |
+| `cf skills upgrade` 无候选 | `~/.claude-forge/skill-candidates/` 是否拉成功；网络问题用代理重试 |
+| better-sqlite3 native binding error | Node 版本与 binding 不匹配；`npm rebuild better-sqlite3` |
+| Schema 改动后查不到字段 | 手动加 `src/core/storage/migrations/<n>_<desc>.sql`，daemon 启动会自动执行 |
+
+调试入口：
+
+```bash
+# daemon 日志
+tail -f ~/.claude-forge/daemon.log
+
+# 查 SQLite 运行时数据
+sqlite3 ~/.claude-forge/data.db "SELECT id, hook_type, timestamp FROM events ORDER BY id DESC LIMIT 10"
+
+# 手工模拟 hook 调用（绕开 Claude Code）
+echo '{"session_id":"test","hook_type":"UserPromptSubmit","user_prompt":"重构 xxx"}' \
+  | ~/.claude/hooks/user-prompt-submit.sh
+```