@winspan/claude-forge 8.54.4 → 9.12.0

package/DEVELOPMENT.md

@@ -24,13 +24,17 @@ src/
 │   │   ├── 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 等
+│   ├── diagnostics/            自检 / 健康诊断工具
+│   ├── governance/            治理协议注入（inject-global 等）
+│   ├── utils/                  logger / git / path / time / lru-cache / forge-resume-block /
+│   │                            claude-cli-spawn（headless `claude` 子进程）等
 │   ├── config.ts               ConfigManager（~/.claude-forge/config.yaml）
 │   ├── constants.ts            FORGE_PATHS、各类阈值常量
 │   ├── event-fields.ts         hook 事件字段统一抽取
 │   └── types.ts                ForgeEvent / HookResult 等核心类型契约
+│   （注：曾经的 core/ai/ ClaudeProvider 目录已整组删除，spec 0902 起所有 LLM
+│    调用收敛为 `child_process.spawn('claude', ...)` headless 子进程）
 │
 ├── daemon/                     后台守护进程
 │   ├── index.ts                  入口：socket server + 生命周期 + 同步任务
@@ -39,41 +43,67 @@ src/
 │   ├── lifecycle.ts              启停 / 信号处理
 │   ├── event-parser.ts           hook 原始 JSON → ForgeEvent
 │   ├── hook-sync.ts              启动时把 dist/hooks/ 同步到 ~/.claude/hooks/
-│   ├── skill-sync.ts             启动时把 dist/skills/official/ 同步到 ~/.claude/skills/
+│   ├── skill-sync.ts             启动时把 dist/skills/distilled/ 同步到 ~/.claude/skills/
+│   ├── agent-sync.ts             启动时把 templates/agents/ 同步到 ~/.claude/agents/
+│   ├── config-store.ts           daemon 运行期配置缓存
 │   ├── launchd-installer.ts      macOS launchd 安装
 │   ├── launchd/                  launchd plist 模板
-│   ├── handlers/
-│   │   ├── user-prompt.ts          UserPromptSubmit：分类 + skill 推荐 + agent 路由
+│   ├── templates/agents/         canonical agent .md 源（build → dist，sync → ~/.claude/agents/）
+│   ├── handlers/                 （5 个 hook handler）
+│   │   ├── user-prompt.ts          UserPromptSubmit：分类 + skill 推荐 + agent 路由 + KB 注入
+│   │   ├── pre-tool-use.ts         PreToolUse：规则引擎，按 tool_intercept 规则 deny/warn/allow
 │   │   ├── post-tool-use.ts        PostToolUse：观察，按需注入提示
 │   │   ├── stop.ts                 Stop：写 session 摘要、distill 决策
 │   │   └── history-exporter.ts     导出完整历史到 .claude-forge/history/
-│   └── services/
-│       └── task-segmenter.ts       UserPromptSubmit 按时间窗划分任务段
+│   ├── rules/                    （5 个，PreToolUse 规则引擎）
+│   │   ├── defaults.ts             默认 tool_intercept 规则（edit/write-multi-file-hard 等 deny）
+│   │   ├── registry.ts             规则注册与首个匹配查找
+│   │   ├── workflow-defaults.ts    workflow 推荐 / Task spawn 匹配规则
+│   │   ├── whitelist.ts            白名单 / 项目级关闭
+│   │   └── types.ts                ToolInterceptRule / RuleContext 类型
+│   └── services/                 （约 20 个后台服务）
+│       ├── spec-gate.ts            SpecGate：spec/decision 批准短路
+│       ├── spec-approval.ts        bare「批准 / approve <token>」批准解析
+│       ├── context-injector.ts     上下文注入
+│       ├── kb-injector.ts          知识库注入
+│       ├── task-segmenter.ts       UserPromptSubmit 按时间窗划分任务段
+│       ├── task-boundary-classifier.ts  任务边界分类
+│       ├── violation-reporter.ts   主线程合规违规汇总
+│       ├── decision-hint.ts        [DECISION HINT] mint
+│       ├── outcome-classifier.ts / outcome-classification-service.ts / outcome-nudge.ts  决策结果回填
+│       ├── experience-extractor.ts / feedback-aggregator.ts  经验/反馈聚合
+│       ├── intercept-revive.ts / intercept-rollback-guard.ts / intercept-timeout-sweeper.ts  拦截治理
+│       ├── idle-session-sweeper.ts / idle-task-budget.ts / event-ttl-sweep.ts  GC / 预算
+│       └── heartbeat-writer.ts     心跳写盘
 │
 ├── skills/                     Skill 推荐与方法论分发
-│   ├── registry.ts               扫描 ~/.claude/skills/ + src/skills/official/，提供 match()
+│   ├── registry.ts               扫描 ~/.claude/skills/ + src/skills/distilled/，提供 match()（keyword-only since spec 0902 D R-B）
 │   ├── 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 源（随发布打包）
+│   ├── builtin-skills.ts         加载内置 distilled skill（来自 src/skills/distilled/）
+│   ├── distilled/                内置 distilled 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 ...）
+│   ├── routes/                   每个 API 模块独立文件（sessions / events / tasks / skills /
+│   │                            decisions / knowledge / patch / health / diagnostics / drift /
+│   │                            insights / pipeline / reports / rules / trace / violations ...）
 │   ├── analytics/                趋势/统计计算
+│   ├── services/                 路由共享服务层
 │   └── static/                   React 前端构建产物的最终落点（dist/web/static/）
+│   （注：曾经的 ssrf-guard.ts 与 routes/ai.ts 已删除）
 │
 ├── cli/
 │   ├── index.ts                  CLI 入口（commander）
 │   ├── init/                     `cf init`：安装 hook 脚本
-│   └── commands/                 子命令：daemon / config / skills / claudemd / status / logs / stats / menu / trace / mcp / executions / template
+│   └── commands/                 27 个子命令：daemon / config / skills / claudemd / status /
+│                                 logs / stats / menu / trace / mcp / executions / template /
+│                                 init / decisions / governance / knowledge / spec / doctor /
+│                                 fix / entropy / agents / bypass / insights / insights-goal-check /
+│                                 project / admin / violations
 │
 ├── claudemd/                   CLAUDE.md 生成与维护
 │   ├── tech-detector.ts          项目技术栈识别
@@ -95,6 +125,23 @@ src/
 ├── mcp/                        MCP server（暴露 skill_invoke / skill_list / pipeline_suggest 给 agent）
 │   └── server.ts
 │
+├── knowledge/                  项目知识库系统（27 src）
+│   ├── builder.ts                KB page 构建（分析 src/ → .forge-knowledge/，每 page 一次 claude spawn）
+│   ├── cli-provider.ts           CliKnowledgeProvider：经 claude-cli-spawn headless 生成 KB
+│   ├── repo-map.ts               仓库结构快照生成
+│   ├── module-hash.ts            模块内容 hash（增量 rebuild 判定）
+│   ├── cross-module.ts           跨模块 page 生成
+│   ├── query.ts                  关键词查询接口
+│   ├── audit-applier.ts          KB 审计修订应用
+│   ├── project-detector.ts       项目类型探测（选择 adapter）
+│   ├── git-hooks.ts              Git hooks 集成（commit 后自动 rebuild）
+│   ├── validator.ts              KB 完整性校验
+│   ├── prompt.ts                 agent prompt 注入工具
+│   ├── constants.ts / types.ts   路径常量 + 类型
+│   ├── adapters/                 多语言项目适配器（typescript / js-vue / python / go /
+│   │                            java / kotlin / rust / monorepo）
+│   └── tools/                    MCP 工具：knowledge-query / knowledge-get-page / repo-map-lookup
+│
 └── templates/                  新项目初始化模板
 
 web/                            React 前端源码（独立 npm workspace）
@@ -144,7 +191,7 @@ npm run dev:daemon:stop
 cd web && npm install && npm run dev
 ```
 
-Daemon / CLI 都用系统 node（项目要求 Node 18+，实际跑在 24/26 上）。
+Daemon / CLI 都用系统 node（项目要求 Node 24+，实际跑在 24/26 上）。
 
 ---
 
@@ -188,9 +235,10 @@ Claude Code  ──hook payload(JSON via stdin)──►  src/hooks/*.sh
                                                       │
                                                       ▼
                               src/daemon/router.ts ──┬──► handlers/user-prompt.ts
+                                                     ├──► handlers/pre-tool-use.ts (规则引擎 deny/warn/allow)
                                                      ├──► handlers/post-tool-use.ts
                                                      ├──► handlers/stop.ts
-                                                     └──► (PreToolUse / Notification: 直接 allow)
+                                                     └──► (Notification: 直接 allow)
                                                       │
                                                       ▼
                               core/storage/* 持久化 + 返回 HookResult
@@ -202,7 +250,12 @@ Claude Code  ──hook payload(JSON via stdin)──►  src/hooks/*.sh
 要点：
 - daemon 必须在 100ms 内返回，超时则 Claude Code 视为放行
 - handler 抛错被 router 捕获，不会让 daemon 崩溃
-- `PreToolUse` 当前不做规则阻断，统一放行
+- `PreToolUse` **做规则阻断**：`handlers/pre-tool-use.ts` 跑 `rules/registry.ts`
+  规则引擎，命中 `rules/defaults.ts` 的 `tool_intercept` 规则（如
+  `edit-multi-file-hard` / `write-multi-file-hard` / `bash-grep-multi-file`）时
+  decision=`deny`（allow=false + hookSpecificOutput），warn 规则注入
+  additionalContext。每次决策落 `tool_intercepts` 表（事实表，写失败不阻断 tool）。
+  显式 bypass 标记（`forge:bypass=<reason>`）转 decision=`bypass` 放行
 - daemon 不主动推消息：任何延后的指令必须等下一次 UserPromptSubmit 注入
 
 ### Skill 系统
@@ -214,16 +267,16 @@ Claude Code  ──hook payload(JSON via stdin)──►  src/hooks/*.sh
 └─────────┬───────────┘
           │
           ▼
-┌──────────────────────────┐         ┌──────────────────────────┐
-│ 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    │         └────────────┬─────────────┘
+┌──────────────────────────┐
+│ SkillRegistry.match()    │         （semantic-matcher 已在 spec 0902 D R-B 删除）
+│ (registry.ts, keyword-only)
+│                          │         ┌──────────────────────────┐
+│ 扫描两类来源：           │ ───────►│ keyword matcher          │
+│  - 内置 src/skills/      │         │ (matcher.ts)             │
+│    distilled/*.md        │         └────────────┬─────────────┘
+│  - 用户 ~/.claude/skills/│                      │
+│    {name}.md             │
+│    or {name}/SKILL.md    │
 └──────────────────────────┘                      │
           │                                       │
           ▼                                       ▼
@@ -240,19 +293,47 @@ Agent 通过 MCP 工具：
 
 frontmatter 必须有 `name: string`，否则 registry 静默跳过（debug 日志，不打扰用户）。`keywords` 与 `tags` 都接受。
 
-### Skill 远程升级
-
-`cf skills upgrade` 由 `src/skills/upgrade-engine.ts` 驱动，三阶段：
-
-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`。
+### Skill 蒸馏
+
+> **架构改写已完成**（spec [`1851`](docs/design/2026-05-28/1851-distill-via-claude-cli-shellout-spec.md) R-A + R-B）：
+> `cf skills distill` CLI 子命令族**已删除**；蒸馏入口收敛到 Web UI 一处
+> （`http://127.0.0.1:3721/context?tab=distill`）。daemon 通过
+> `child_process.spawn('claude', ...)` headless 调用本地 claude CLI，走用户
+> 订阅计费（OAuth/keychain），daemon 自身不再持 `ANTHROPIC_API_KEY`。
+
+**实施流程**（R-B 已 ship）:
+
+1. `findClaudeBin()` (`src/skills/distill/claude-cli-resolver.ts`) 探测 `claude`
+   binary —— 先跑 `which claude`，失败后探测 `/opt/homebrew/bin/claude` /
+   `/usr/local/bin/claude` / `~/.local/bin/claude`。结果缓存 5 分钟。
+2. `/api/skills/distill/status` 调 `findClaudeBin()` 返回
+   `{ claudeCliAvailable: boolean, claudeCliPath: string | null }`。
+   UI disable 按钮 + 显示安装提示（`brew install claude` /
+   `npm i -g @anthropic-ai/claude-code`）。
+3. 按【开始蒸馏】 → `spawnSkillDistillerAgent(prompt)` 起子进程：
+   ```bash
+   claude -p --agent skill-distiller --bare \
+     --output-format stream-json --include-partial-messages --input-format text
+   ```
+   prompt 通过 stdin 喂入（含 `<upstream_skill>` / `<upstream_url>` /
+   `<target_name>` / `<topic_id>` tagged blocks）。
+4. 解析 stream-json 事件（`assistant_message` / `content_block_delta` /
+   `message_delta` / `text_delta` / `result` 多版本兼容）累加 assistant text。
+   每个事件回调 `onProgress({ type, charCount, raw })` →
+   distill-manager 桥接为 SSE `progress` event（UI 显示 `chars=N` + topicId）。
+5. 子进程 exit 0 → `parseSkipBlock()` 优先检测 SKIP envelope →
+   有则抛 `SkillSkippedError`（agent 自评分 < 3，topicId 加入 state.skipped 继续下一个）→
+   否则 `parseSkillBlock()` 抽 SKILL envelope body →
+   `detectAnchors()` lint 命中即 throw `ProjectAnchorRejection`（**无 retry**，per Q2）→
+   写入 `src/skills/distilled/distilled-xxx.md` + 追加 NOTICE。
+6. 用户【取消】→ `distill-manager.cancel(runId)` → AbortController abort →
+   `child.kill('SIGTERM')`。
+
+**Hard-fail 错误**（agent path 一律不 retry）:
+- `ClaudeCliMissingError` —— `findClaudeBin()` 返回 null
+- `SkillSkippedError` —— agent emit `---SKIP---` envelope（score < 3）
+- `SkillBlockMissingError` —— agent 输出既无 SKILL 也无 SKIP envelope
+- `ProjectAnchorRejection` —— SKILL body lint 命中项目锚点
 
 ### CLAUDE.md 生成与维护
 
@@ -272,7 +353,7 @@ frontmatter 必须有 `name: string`，否则 registry 静默跳过（debug 日
 daemon 启动时（`src/daemon/index.ts`）执行两个一次性同步：
 
 - `syncHooks()` — 把 `dist/hooks/*.sh` 对照 sha256 同步到 `~/.claude/hooks/`，避免用户忘了重跑 `cf init`
-- `syncSkills()` — 把 `dist/skills/official/*.md` 同步到 `~/.claude/skills/`，user-owned 文件（已存在）跳过
+- `syncSkills()` — 把 `dist/skills/distilled/*.md` 同步到 `~/.claude/skills/`，user-owned 文件（已存在）跳过
 
 两者都幂等，文件相同时不写盘。
 
@@ -300,7 +381,7 @@ hook event ──► writeEvent()            ──┐
 - Schema 由 `src/core/storage/schema.sql` 初始化
 - 增量改动放 `src/core/storage/migrations/*.sql`（按文件名顺序执行）
 
-### 长跑稳定性（v8.53.6 加）
+### 长跑稳定性
 
 daemon 通过三个机制保证长时间运行不膨胀：
 
@@ -325,7 +406,7 @@ daemon 通过三个机制保证长时间运行不膨胀：
 
 ## 添加新 Skill
 
-最简方式：在 `src/skills/official/<name>.md` 写 frontmatter：
+最简方式：在 `src/skills/distilled/<name>.md` 写 frontmatter：
 
 ```markdown
 ---
@@ -352,6 +433,602 @@ version: 1.0.0
 
 ---
 
+## decision-maker agent 使用说明
+
+### 首次使用必读：TUI restart 必要
+
+`decision-maker` agent 定义在 `.claude/agents/decision-maker.md`。Claude Code TUI
+在**启动时**一次性扫描 `.claude/agents/`，运行中新增的 agent 不会被自动识别。
+
+**首次使用（或更新 template 后）必须重启 TUI**：
+- macOS: `Cmd+R` 或关闭窗口重新打开
+- 重启后验证: 在 Task tool 输入 `subagent_type='decision-maker'` 不报 not found 即可
+
+### TUI restart 后仍 not found 的 fallback
+
+若重启 TUI 后 `subagent_type='decision-maker'` 仍报 not found，使用以下 inline 方式：
+
+```
+spawn general-purpose agent with prompt:
+  "你扮演 decision-maker 角色。Read .claude/agents/decision-maker.md 然后按其 Workflow 执行。
+   用户 prompt: <your actual prompt>"
+```
+
+### decision-maker catalog 预生成
+
+Build 时 `scripts/dump-catalogs.ts` 会生成：
+- `dist/catalogs/agents.json` — 14 agents, ~3KB
+- `dist/catalogs/skills.json` — skills catalog, ~5KB
+
+这两个文件由 decision-maker Step 2-3 读取（`cat dist/catalogs/*.json`），
+替代原来的全读 3250 行 markdown，可减少 ~90% catalog token 消耗。
+
+如果 `dist/catalogs/` 不存在（fresh clone）：先运行 `npm run build`。
+
+---
+
+## task-boundary-classifier agent 使用说明
+
+`task-boundary-classifier` agent 定义在 `.claude/agents/task-boundary-classifier.md`
+（canonical 在 `src/daemon/templates/agents/`，agent-sync 启动时镜像到
+`~/.claude/agents/`）。它判断一段连续操作是否构成同一任务边界，供
+`src/daemon/services/task-boundary-classifier.ts` 在任务分段时调用。
+
+与其它 agent 一致：程序化调用走 `child_process.spawn('claude', ...)` headless
+子进程（不受 TUI restart 影响）；TUI 内手动 `subagent_type='task-boundary-classifier'`
+spawn 首次需 TUI restart（macOS Cmd+R）。
+
+---
+
+## skill-distiller agent 使用说明
+
+`skill-distiller` agent 定义在 `.claude/agents/skill-distiller.md`（与
+`src/daemon/templates/agents/skill-distiller.md` 完全镜像，agent-sync 启动时
+拷到 `~/.claude/agents/`）。
+
+### R-A 状态（spec 1851）
+
+- **程序化调用路径已删除**：`runSonnetDistillationViaAgent()` /
+  `CF_SKILL_DISTILLER_AGENT=1` env flag 在 R-A 阶段一并下线。
+- **R-B 接 claude CLI shell-out**：daemon 通过 `child_process.spawn('claude',
+  ['-p', '--agent', 'skill-distiller', ...])` 调用本地 claude CLI，agent body
+  作为 system prompt 由 CLI 自身加载（不再由 daemon 进程读取 .md 注入）。
+- **agent body R-B 会重写**：评分（D1-D5）+ 决策 + 输出 SKILL/SKIP envelope
+  三步合一。当前 .md 仍是 Phase B 版本，等 R-B spec 推进后会更新。
+
+### 方式 2：在 Claude Code TUI 里手动 spawn（仍可用）
+
+```
+Task tool subagent_type='skill-distiller' with prompt:
+  "<upstream_skill>...</upstream_skill>
+   <upstream_url>https://github.com/owner/repo</upstream_url>
+   <target_name>distilled-xxx</target_name>
+   <it_universal_score>4</it_universal_score>
+   <it_universal_rationale>...</it_universal_rationale>"
+```
+
+agent 会返回 `---SKILL---\n<full md>\n---END---` 格式的 markdown，需要手动
+保存到 `src/skills/distilled/distilled-xxx.md`（caller 责任）。**首次新增/改 agent
+需 TUI restart**（macOS Cmd+R）。
+
+### 首次使用必读：TUI restart 必要
+
+与 decision-maker 同样的 quirk —— Claude Code TUI 在**启动时**一次性扫描
+`.claude/agents/`，运行中新增的 agent 不会被自动识别。
+
+**首次使用（或更新 template 后）必须重启 TUI**：
+- macOS: `Cmd+R` 或关闭窗口重新打开
+- 重启后验证：在 Task tool 输入 `subagent_type='skill-distiller'` 不报 not found 即可
+
+> 注意：方式 1（程序化 distill）**不受** TUI restart 影响 —— 它直接读文件，
+> 不走 TUI 的 agent registry。
+
+### TUI restart 后仍 not found 的 fallback
+
+若重启 TUI 后 `subagent_type='skill-distiller'` 仍报 not found，使用以下
+inline 方式：
+
+```
+spawn general-purpose agent with prompt:
+  "你扮演 skill-distiller 角色。Read .claude/agents/skill-distiller.md
+   然后按其 Workflow 执行。
+
+   输入 tags 如下：
+   <upstream_skill>...</upstream_skill>
+   <upstream_url>...</upstream_url>
+   ..."
+```
+
+### Agent 文件三处镜像
+
+```
+src/daemon/templates/agents/skill-distiller.md   ← canonical source (git tracked)
+.claude/agents/skill-distiller.md                ← repo mirror (git -f tracked, TUI scan)
+dist/daemon/templates/agents/skill-distiller.md  ← npm payload (build cp produces)
+~/.claude/agents/skill-distiller.md              ← user sync target (agent-sync.ts)
+```
+
+修改 agent .md 时**只改 canonical**（`src/daemon/templates/agents/`），然后：
+
+```bash
+# 同步到 repo mirror
+cp src/daemon/templates/agents/skill-distiller.md .claude/agents/skill-distiller.md
+# build 自动同步到 dist/
+npm run build
+# daemon restart 自动同步到 ~/.claude/agents/
+cf daemon restart
+```
+
+repo mirror 与 canonical 必须 **byte-identical**（CI 不强制，但 lint 检查
+计划在未来 phase 加入）。
+
+---
+
+## claudemd-writer agent 使用说明
+
+`claudemd-writer` agent 定义在 `.claude/agents/claudemd-writer.md`（与
+`src/daemon/templates/agents/claudemd-writer.md` 完全镜像，agent-sync 启动时
+拷到 `~/.claude/agents/`）。
+
+引入背景：spec [`0902`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md)
+子 spec A — 把 `cf claudemd init/update` 从「daemon 进程内 `ClaudeProvider.complete()`
++ 用户配的 `ANTHROPIC_API_KEY`」迁到「`child_process.spawn('claude', ...)` headless
+CLI 子进程」。daemon 自身不再持 API key，走用户 Claude Code 订阅计费。
+
+### 两种使用方式
+
+#### 方式 1：作为 `cf claudemd` 的 prompt 模板（程序化调用，默认入口）
+
+`src/cli/commands/claudemd.ts` 的 `runClaudeMdWriter()` 把 agent name + stdin
+prompt 传给 `spawnClaudeCli()` (`src/core/utils/claude-cli-spawn.ts`)：
+
+```bash
+claude -p --agent claudemd-writer --bare \
+  --output-format stream-json --include-partial-messages \
+  --allowedTools "Read,Grep" --input-format text
+```
+
+prompt 通过 stdin 注入，含 tagged blocks（`<target_command>` / `<project_name>` /
+`<project_tech_stack>` / `<project_directory_tree>` / `<project_persona>` /
+`<project_conventions>`）。agent 解析这些 block，按既定模板写完整 CLAUDE.md
+body，包在 `---CLAUDEMD---\n...\n---END---` envelope 内。host 调
+`parseClaudeMdBlock()` 抽 body，写盘。
+
+这种用法**不需要** TUI restart —— 不走 Claude Code 的 Task tool agent registry，
+是 host CLI 直接 spawn `claude` 子进程。
+
+#### 方式 2：在 Claude Code TUI 里手动 spawn（调试 / 一次性生成）
+
+```
+Task tool subagent_type='claudemd-writer' with prompt:
+  "<target_command>init</target_command>
+   <project_name>my-app</project_name>
+   <project_tech_stack>{\"language\":[\"TypeScript\"],...}</project_tech_stack>
+   <project_directory_tree>my-app/\n├── src/\n└── package.json</project_directory_tree>
+   <project_persona></project_persona>
+   <project_conventions></project_conventions>"
+```
+
+agent 返回 `---CLAUDEMD---\n<full md>\n---END---` envelope。**调用方手动**
+copy body 写入 `<project>/CLAUDE.md`。
+
+### 首次使用必读：TUI restart 必要
+
+与 `decision-maker` / `skill-distiller` 同样的 quirk —— Claude Code TUI 在**启动时**
+一次性扫描 `.claude/agents/`，运行中新增的 agent 不会被自动识别。
+
+**首次使用（或更新 template 后）必须重启 TUI**：
+- macOS: `Cmd+R` 或关闭窗口重新打开
+- 重启后验证：在 Task tool 输入 `subagent_type='claudemd-writer'` 不报 not found 即可
+
+> 注意：方式 1（程序化 `cf claudemd`）**不受** TUI restart 影响 —— 它走
+> `child_process.spawn('claude', ...)`，与 TUI 的 agent registry 无关。
+
+### TUI restart 后仍 not found 的 fallback
+
+若重启 TUI 后 `subagent_type='claudemd-writer'` 仍报 not found，使用以下
+inline 方式：
+
+```
+spawn general-purpose agent with prompt:
+  "你扮演 claudemd-writer 角色。Read .claude/agents/claudemd-writer.md
+   然后按其 Workflow 执行。
+
+   输入 tags 如下：
+   <target_command>init</target_command>
+   <project_name>...</project_name>
+   <project_tech_stack>...</project_tech_stack>
+   <project_directory_tree>...</project_directory_tree>
+   <project_persona>...</project_persona>
+   <project_conventions>...</project_conventions>"
+```
+
+### Agent 文件三处镜像
+
+```
+src/daemon/templates/agents/claudemd-writer.md   ← canonical source (git tracked)
+.claude/agents/claudemd-writer.md                ← repo mirror (git -f tracked, TUI scan)
+dist/daemon/templates/agents/claudemd-writer.md  ← npm payload (build cp produces)
+~/.claude/agents/claudemd-writer.md              ← user sync target (agent-sync.ts)
+```
+
+修改 agent .md 时**只改 canonical**（`src/daemon/templates/agents/`），然后：
+
+```bash
+# 同步到 repo mirror
+cp src/daemon/templates/agents/claudemd-writer.md .claude/agents/claudemd-writer.md
+# build 自动同步到 dist/
+npm run build
+# daemon restart 自动同步到 ~/.claude/agents/
+cf daemon restart
+```
+
+repo mirror 与 canonical 必须 **byte-identical**（同 skill-distiller，CI 不
+强制，lint 检查计划未来 phase 加入）。
+
+### Hard-fail 错误（不会 fallback 到 stub）
+
+- `ClaudeCliMissingError` —— PATH 中找不到 `claude` binary，install hint：
+  `brew install claude` 或 `npm i -g @anthropic-ai/claude-code`
+- `ClaudeCliExitError` —— 子进程 exit code ≠ 0（stderr snippet 打印）
+- `ClaudeCliTimeoutError` —— 超过 5 分钟未完成（默认 timeout 300_000ms）
+- `ClaudeCliCancelledError` —— 调用方主动 abort
+- `ClaudeMdBlockMissingError` —— agent 输出缺 `---CLAUDEMD---...---END---`
+  envelope（前 200 字符 snippet 打印）
+
+所有错误**直接 exit 1**，不退化到模板（与 R-A 时期的 fallback 行为不同；
+fallback 已移除，spec 0902 §2.4.1）。
+
+---
+
+## knowledge-builder agent 使用说明
+
+`knowledge-builder` agent 定义在 `.claude/agents/knowledge-builder.md`（与
+`src/daemon/templates/agents/knowledge-builder.md` 完全镜像，agent-sync 启动时
+拷到 `~/.claude/agents/`）。
+
+引入背景：spec [`0902`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md)
+子 spec B — 把 `cf knowledge build / init / update` 从「daemon 进程内
+`ClaudeProvider.completeWithUsage()` + 用户配的 `ANTHROPIC_API_KEY`」迁到
+「`child_process.spawn('claude', ...)` headless CLI 子进程」。daemon 自身不再
+持 API key，走用户 Claude Code 订阅计费。
+
+### 两种使用方式
+
+#### 方式 1：作为 `cf knowledge build` 的 prompt 模板（程序化调用，默认入口）
+
+`src/cli/commands/knowledge.ts` 的 `buildCmd()` 调 `buildKnowledge()`，后者默认
+创建 `CliKnowledgeProvider`（`src/knowledge/cli-provider.ts`），由它把 agent
+name + stdin prompt 传给 `spawnClaudeCli()`（`src/core/utils/claude-cli-spawn.ts`，
+与 `claudemd-writer` 共用）：
+
+```bash
+claude -p --agent knowledge-builder --bare \
+  --output-format stream-json --include-partial-messages \
+  --allowedTools "Read,Grep" --input-format text
+```
+
+每个 KB page 一次 spawn。prompt 通过 stdin 注入，含 routing hints
+（`<page_kind>module</page_kind>` / `<page_kind>cross-module</page_kind>` +
+`<page_name>daemon</page_name>` 等 system-prompt 标签）。agent 解析后，按既定
+模板写 KB body，包在 `---KB---\n<body>\n---END---` envelope 内（每个 page 一个
+envelope，多 page 输出多 envelope 拼接）。host 调 `parseKbBlocks()` 抽 body，
+分发给 module page / cross-module page 的 sink。
+
+这种用法**不需要** TUI restart —— 不走 Claude Code 的 Task tool agent registry，
+是 host CLI 直接 spawn `claude` 子进程。
+
+#### 方式 2：在 Claude Code TUI 里手动 spawn（调试 / 一次性生成）
+
+```
+Task tool subagent_type='knowledge-builder' with prompt:
+  "<page_kind>module</page_kind>
+   <page_name>daemon</page_name>
+   <repo_map>...JSON 片段...</repo_map>
+   <source_files>...必要的 ts 源码摘录...</source_files>"
+```
+
+agent 返回 `---KB---\n<full md body>\n---END---` envelope。**调用方手动** copy
+body 写入 `.forge-knowledge/modules/daemon.md`。
+
+### Routing hints（host 注入到 system prompt）
+
+R-B 引入 `withKnowledgeRoutingHints()`（`src/knowledge/cli-provider.ts`）：在
+传给 `spawnClaudeCli` 的 `system` 字段拼上：
+
+- `<page_kind>module|cross-module</page_kind>` — agent 据此决定输出 JSON
+  `{content, refs}`（module page）还是纯 markdown（cross-module page）
+- `<page_name>daemon|architecture|...</page_name>` — agent 据此为 envelope 命名
+
+routing hints 通过 system prompt 而不是 prompt body 传，避免污染 LLM 看的
+"用户输入"部分。
+
+### 首次使用必读：TUI restart 必要
+
+与 `decision-maker` / `skill-distiller` / `claudemd-writer` 同样的 quirk ——
+Claude Code TUI 在**启动时**一次性扫描 `.claude/agents/`，运行中新增的 agent
+不会被自动识别。
+
+**首次使用（或更新 template 后）必须重启 TUI**：
+- macOS: `Cmd+R` 或关闭窗口重新打开
+- 重启后验证：在 Task tool 输入 `subagent_type='knowledge-builder'` 不报 not
+  found 即可
+
+> 注意：方式 1（程序化 `cf knowledge build`）**不受** TUI restart 影响 —— 它
+> 走 `child_process.spawn('claude', ...)`，与 TUI 的 agent registry 无关。
+
+### TUI restart 后仍 not found 的 fallback
+
+若重启 TUI 后 `subagent_type='knowledge-builder'` 仍报 not found，使用以下
+inline 方式：
+
+```
+spawn general-purpose agent with prompt:
+  "你扮演 knowledge-builder 角色。Read .claude/agents/knowledge-builder.md
+   然后按其 Workflow 执行。
+
+   输入 tags 如下：
+   <page_kind>module</page_kind>
+   <page_name>daemon</page_name>
+   <repo_map>...</repo_map>
+   <source_files>...</source_files>"
+```
+
+### Agent 文件三处镜像
+
+```
+src/daemon/templates/agents/knowledge-builder.md   ← canonical source (git tracked)
+.claude/agents/knowledge-builder.md                ← repo mirror (git -f tracked, TUI scan)
+dist/daemon/templates/agents/knowledge-builder.md  ← npm payload (build cp produces)
+~/.claude/agents/knowledge-builder.md              ← user sync target (agent-sync.ts)
+```
+
+修改 agent .md 时**只改 canonical**（`src/daemon/templates/agents/`），然后：
+
+```bash
+# 同步到 repo mirror
+cp src/daemon/templates/agents/knowledge-builder.md .claude/agents/knowledge-builder.md
+# build 自动同步到 dist/
+npm run build
+# daemon restart 自动同步到 ~/.claude/agents/
+cf daemon restart
+```
+
+repo mirror 与 canonical 必须 **byte-identical**（同 skill-distiller /
+claudemd-writer，CI 不强制，lint 检查计划未来 phase 加入）。
+
+### Hard-fail 错误（不会 fallback 到 stub）
+
+- `ClaudeCliMissingError` —— PATH 中找不到 `claude` binary，install hint：
+  `brew install claude` 或 `npm i -g @anthropic-ai/claude-code`
+- `ClaudeCliExitError` —— 子进程 exit code ≠ 0（stderr snippet 打印）
+- `ClaudeCliTimeoutError` —— 超过 5 分钟未完成（默认 timeout 300_000ms）
+- `ClaudeCliCancelledError` —— 调用方主动 abort
+- `KbBlockMissingError` —— agent 输出缺 `---KB---...---END---` envelope
+  （前 300 字符 snippet 打印；通常是 agent template drift，pull 最新
+  `.claude/agents/knowledge-builder.md` 后重试）
+
+所有错误**直接 exit 1**，不退化到模板（与 R-A 时期临时 `KnowledgeStubError`
+行为不同；R-B 之后 stub 类型保留但永不抛，R-D 将彻底删除）。
+
+`src/cli/commands/knowledge.ts` 的 `reportKnowledgeBuildError()` 把这些错误
+映射成 operator-friendly 提示（含 install hint / snippet / 安全行动建议），
+build / init / update 三个 action handler 共享。
+
+### `cf knowledge query --strategy rerank` 已下线
+
+历史上 v9.3 引入过 Haiku rerank 检索路径（`--strategy rerank` + LRU 缓存 +
+优雅降级）。该路径在 **Spec 2 Stage B（commit `797326f8`）已整组下线**，
+连同 `kb_query_log` 表的 `strategy` / `rerank_cache_hit` / `rerank_failed` 列
+与 `idx_kb_query_log_project_strategy` 索引一起迁移删除。
+
+子 spec B R-C 评估时确认：当前 src/ 没有任何活跃的 rerank stub / 入口需要
+接通；本期 R-C **无 rerank 改动**。R-D 评估时如果发现 type 残留再清扫。
+
+如果未来要重新引入 AI rerank：应在新 spec 里走 `claude` CLI 子进程 +
+`knowledge-reranker` agent（不要再引入 ClaudeProvider 实例 / API key 依赖）。
+
+---
+
+## patch-applier agent 使用说明
+
+`patch-applier` agent 定义在 `.claude/agents/patch-applier.md`（与
+`src/daemon/templates/agents/patch-applier.md` 完全镜像，agent-sync 启动时
+拷到 `~/.claude/agents/`）。
+
+引入背景：spec [`0902`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md)
+子 spec C — 把 Web `POST /api/patch/preview` 从「daemon 进程内
+`ClaudeProvider.complete()` + 用户配的 `ANTHROPIC_API_KEY`」迁到
+「`child_process.spawn('claude', ...)` headless CLI 子进程」。daemon 自身不再
+持 API key，走用户 Claude Code 订阅计费。
+
+### 两种使用方式
+
+#### 方式 1：作为 `/api/patch/preview` 的 prompt 模板（程序化调用，默认入口）
+
+`src/web/routes/patch.ts` 的 `registerPatchRoutes()` 在每次 POST 时调
+`spawnClaudeCli()`（`src/core/utils/claude-cli-spawn.ts`，与 `claudemd-writer` /
+`knowledge-builder` 共用）：
+
+```bash
+claude -p --agent patch-applier --bare \
+  --output-format stream-json --include-partial-messages \
+  --allowedTools "Read,Grep" --input-format text
+```
+
+每次 `POST /api/patch/preview` 一次 spawn。stdin 注入由 `buildPatchApplierPrompt()`
+拼接的 tagged blocks：
+
+```
+<target_path>agents/decision-maker</target_path>
+<file_content>...current full file content...</file_content>
+<instruction>...natural-language change description...</instruction>
+<context_files></context_files>
+<rationale>...optional reason...</rationale>
+```
+
+agent 解析后输出**正好一个** envelope（两种之一，**discriminated union**）：
+
+- `---PATCH---\n<unified diff>\n---END---` —— 实际可应用的 `patch -p0` 格式 diff
+- `---NOPATCH---\nreason: <短语>\n---END---` —— 拒绝改动（文件已满足要求 /
+  指令模糊 / 破坏性 / >50% 行需改写等场景）
+
+host 调 `parsePatchEnvelope()` 抽 body：PATCH 优先（双 envelope 同现取 PATCH），
+解析失败抛 `PatchBlockMissingError`。
+
+响应 JSON shape：
+
+```typescript
+// PATCH 路径
+{ targetType, targetName, filePath, patch: string, recommendation, rationale }
+// NOPATCH 路径
+{ targetType, targetName, filePath, noPatch: true, reason: string, recommendation, rationale }
+```
+
+这种用法**不需要** TUI restart —— 不走 Claude Code 的 Task tool agent registry，
+是 host CLI 直接 spawn `claude` 子进程。
+
+#### 方式 2：在 Claude Code TUI 里手动 spawn（调试 / 一次性生成）
+
+```
+Task tool subagent_type='patch-applier' with prompt:
+  "<target_path>src/foo/bar.ts</target_path>
+   <file_content>...</file_content>
+   <instruction>把 logger.warn 全部换成 logger.error</instruction>
+   <context_files></context_files>
+   <rationale>warn level 太低，alert 漏触发</rationale>"
+```
+
+agent 返回 `---PATCH---\n<diff>\n---END---` 或
+`---NOPATCH---\nreason: ...\n---END---` envelope。**调用方手动** copy diff
+本地 `patch -p0 <` 应用。
+
+### 首次使用必读：TUI restart 必要
+
+与 `decision-maker` / `skill-distiller` / `claudemd-writer` / `knowledge-builder`
+同样的 quirk —— Claude Code TUI 在**启动时**一次性扫描 `.claude/agents/`，
+运行中新增的 agent 不会被自动识别。
+
+**首次使用（或更新 template 后）必须重启 TUI**：
+- macOS: `Cmd+R` 或关闭窗口重新打开
+- 重启后验证：在 Task tool 输入 `subagent_type='patch-applier'` 不报 not
+  found 即可
+
+> 注意：方式 1（程序化 `/api/patch/preview`）**不受** TUI restart 影响 —— 它
+> 走 `child_process.spawn('claude', ...)`，与 TUI 的 agent registry 无关。
+
+### TUI restart 后仍 not found 的 fallback
+
+若重启 TUI 后 `subagent_type='patch-applier'` 仍报 not found，使用以下
+inline 方式：
+
+```
+spawn general-purpose agent with prompt:
+  "你扮演 patch-applier 角色。Read .claude/agents/patch-applier.md
+   然后按其 Workflow 执行。
+
+   输入 tags 如下：
+   <target_path>...</target_path>
+   <file_content>...</file_content>
+   <instruction>...</instruction>
+   <context_files>...</context_files>
+   <rationale>...</rationale>"
+```
+
+### Agent 文件三处镜像
+
+```
+src/daemon/templates/agents/patch-applier.md   ← canonical source (git tracked)
+.claude/agents/patch-applier.md                ← repo mirror (git -f tracked, TUI scan)
+dist/daemon/templates/agents/patch-applier.md  ← npm payload (build cp produces)
+~/.claude/agents/patch-applier.md              ← user sync target (agent-sync.ts)
+```
+
+修改 agent .md 时**只改 canonical**（`src/daemon/templates/agents/`），然后：
+
+```bash
+# 同步到 repo mirror
+cp src/daemon/templates/agents/patch-applier.md .claude/agents/patch-applier.md
+# build 自动同步到 dist/
+npm run build
+# daemon restart 自动同步到 ~/.claude/agents/
+cf daemon restart
+```
+
+repo mirror 与 canonical 必须 **byte-identical**（同 skill-distiller /
+claudemd-writer / knowledge-builder；CI 不强制，lint 检查计划未来 phase 加入）。
+
+### PATCH / NOPATCH 双 envelope 协议（discriminated union 响应）
+
+这是 patch-applier 与 claudemd-writer / knowledge-builder 的**关键差异**：
+
+| Agent | Envelope | 响应字段 |
+|---|---|---|
+| `claudemd-writer` | 单一 `---CLAUDEMD---...---END---` | 始终是 markdown body |
+| `knowledge-builder` | 多 `---KB---...---END---` 拼接 | 每 page 一个 envelope |
+| `patch-applier` | **二选一** `---PATCH---` 或 `---NOPATCH---` | discriminated union `{patch?, noPatch?, reason?}` |
+
+`/api/patch/preview` 响应 shape 的 discriminated union 由 `parsePatchEnvelope()`
+保证：成功路径**恰好返回一个 patch 或一个 noPatch+reason**，调用方判断响应字段：
+
+```typescript
+const r = await fetch('/api/patch/preview', { method: 'POST', body: ... });
+const data = await r.json();
+if (data.noPatch) {
+  // 拒绝改动，data.reason 显示拒因
+} else if (data.patch) {
+  // 拿到 unified diff，调 /api/patch/apply 或本地 patch -p0
+} else {
+  // 错误响应（500 / 504 / 499 等），看 data.error / data.message
+}
+```
+
+### HTTP 错误码细分（R-B 引入）
+
+| code | 错误类型 | 触发场景 |
+|---|---|---|
+| 400 | input validation | targetType / targetName / recommendation 缺失或非法 |
+| 404 | not found | 解析后的 filePath 不存在 |
+| 499 | `ClaudeCliCancelledError` | 调用方主动 abort（HTTP 499 借用 Nginx semantics）|
+| 500 | `ClaudeCliMissingError` | PATH 找不到 `claude` binary（含 install hint） |
+| 500 | `ClaudeCliExitError` | 子进程 exit code ≠ 0（含 stderr snippet） |
+| 500 | `PatchBlockMissingError` | agent 输出缺 envelope（含 200 字符 rawSnippet） |
+| 500 | `PatchSpawnError` | 未识别异常的兜底 |
+| 504 | `ClaudeCliTimeoutError` | 超过 5 分钟未完成（默认 timeout 300_000ms） |
+
+所有错误**直接 hard-fail**，不退化到模板（与 R-A 时期临时 `PatchStubError`
+行为不同；R-B 之后 stub 类型保留但永不抛，R-D 将彻底删除）。
+
+### 非 SSE 流式决策（R-C 评估结果）
+
+R-B 阶段 `runWithChildProcess` 留下了 `spawnClaudeCli.onProgress` 接口未接通，
+R-C 评估是否升级为 SSE 流式（前端能实时累加 diff partial）：
+
+- 当前 `web/src/` 内置前端**没有任何** `/api/patch` 消费者（`grep -rn "api/patch" web/src` = 0 命中）
+- 加 SSE 会引入 `text/event-stream` + 前端 EventSource 订阅逻辑，复杂度高
+- 子 spec A / B 也未引入 SSE，保持一致
+- **决策：本期 R-C 不加 SSE**，前端如需进度提示可用 spinner + "生成 patch 中..." 文案。
+- 未来若加 patch web UI，可在新 spec 中评估 SSE 升级；spawnClaudeCli 已具
+  `onProgress` 接口，桥接 SSE event 较低成本
+
+### Hard-fail 错误（不会 fallback 到 stub）
+
+- `ClaudeCliMissingError` —— PATH 中找不到 `claude` binary，install hint：
+  `brew install claude` 或 `npm i -g @anthropic-ai/claude-code`
+- `ClaudeCliExitError` —— 子进程 exit code ≠ 0（stderr snippet 打印）
+- `ClaudeCliTimeoutError` —— 超过 5 分钟未完成
+- `ClaudeCliCancelledError` —— 调用方主动 abort
+- `PatchBlockMissingError` —— agent 输出缺 `---PATCH---...---END---` 或
+  `---NOPATCH---...---END---` envelope（前 200 字符 snippet 入响应 JSON；
+  通常是 agent template drift，pull 最新 `.claude/agents/patch-applier.md`
+  后重试）
+
+> `PatchStubError` 仍作 `@deprecated` named export 保留（R-A → R-D 兼容窗口），
+> R-B 之后永不被抛；R-D 删除整个类 + tests/unit/web/routes/patch.test.ts 中
+> `PatchStubError` describe 块。
+
+---
+
 ## 故障排查
 
 | 现象 | 排查 |
@@ -359,7 +1036,7 @@ version: 1.0.0
 | 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 |
+| Skill 没被推荐 | `cf skills list` 看是否加载；frontmatter 检查是否缺 `name` 字段。**注**：语义匹配 (`SemanticSkillMatcher`) 已在 spec `0902` 子 spec D R-B 删除，现在仅 keyword 匹配 — 确保 skill frontmatter 的 `keywords: [...]` 列表覆盖关键词 |
 | `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 启动会自动执行 |