@seanyao/roll 4.630.2 → 4.702.2

package/guide/zh/practices/engineering-common-sense.md

@@ -0,0 +1,393 @@
+# Roll 工程常识清单
+
+> **这些不是"最佳实践"——它们是基线要求。** 违反即为 Bug。
+
+## 1. 幂等性 🔁
+
+**定义：** 同一操作执行 N 次，结果与执行一次相同。
+
+**必须测试：**
+```typescript
+it('should be idempotent', async () => {
+  await operation(data)  // 第 1 次
+  const result1 = await getState()
+
+  await operation(data)  // 第 2 次
+  const result2 = await getState()
+
+  await operation(data)  // 第 3 次
+  const result3 = await getState()
+
+  expect(result1).toEqual(result2)
+  expect(result2).toEqual(result3)
+})
+```
+
+**常见场景：**
+- [ ] 导入 / 摄取操作
+- [ ] 配置更新
+- [ ] 状态变更
+- [ ] API 调用
+- [ ] 文件写入
+
+**本次反面案例：** 重复运行 ingest -> 文件被复制了 7 次
+
+---
+
+## 2. 跨模块契约一致性 🔗
+
+**定义：** 在多个模块间共享的数据 / ID / 格式必须完全一致。
+
+**必须检查：**
+```typescript
+// 检查清单
+- [ ] ID 生成算法是否一致？
+- [ ] 数据序列化格式是否一致？
+- [ ] 路径处理是否一致？（例如 / vs -）
+- [ ] 是否已抽取为共享函数 / 常量？
+```
+
+**测试模板：**
+```typescript
+it('should generate same ID across modules', () => {
+  const scannerId = generateScannerId('articles/test.md')
+  const inboxId = generateInboxId('articles/test.md')
+  expect(scannerId).toEqual(inboxId)
+})
+```
+
+**本次反面案例：** Scanner 用 `-` 替换 `/`，inbox 用原始路径 -> 去重失败
+
+---
+
+## 3. 数据流完整性 🌊
+
+**定义：** 从生产者到消费者的完整管道必须端到端贯通。
+
+**必须验证：**
+```typescript
+// 集成测试 —— 必须存在
+describe('Data Flow: Producer -> Consumer', () => {
+  it('should write data that consumer can read', async () => {
+    await producer.write(testData)
+    const result = await consumer.read()
+    expect(result).toEqual(testData)
+  })
+})
+```
+
+**检查清单：**
+- [ ] 谁写入数据？（生产者）
+- [ ] 谁读取数据？（消费者）
+- [ ] 中间存储是什么？（state / 文件 / 缓存）
+- [ ] 是否有集成测试来验证？
+
+**本次反面案例：** Ingest 没有写 state，status 读不到 -> 显示为 0
+
+---
+
+## 4. 原子性 ⚛️
+
+**定义：** 一个操作要么完全成功，要么完全不执行（没有中间状态）。
+
+**必须考虑：**
+- [ ] 部分失败时如何回滚？
+- [ ] 是否有事务机制？
+- [ ] 崩溃后如何保证数据一致性？
+
+**测试模板：**
+```typescript
+it('should be atomic', async () => {
+  try {
+    await operation([item1, item2, INVALID_ITEM, item4])
+  } catch (e) {
+    // 失败后，已处理的项应被回滚
+    const state = await getState()
+    expect(state).toEqual(initialState)
+  }
+})
+```
+
+---
+
+## 5. 输入校验 🛡️
+
+**定义：** 永远不要信任任何外部输入 —— 必须校验。
+
+**必须检查：**
+- [ ] Null / undefined 处理
+- [ ] 类型检查
+- [ ] 范围检查（数组长度、数值范围）
+- [ ] 特殊字符 / 注入攻击防护
+- [ ] 文件路径穿越防护
+
+**测试模板：**
+```typescript
+it('should handle invalid inputs gracefully', async () => {
+  await expect(operation(null)).rejects.toThrow()
+  await expect(operation('')).rejects.toThrow()
+  await expect(operation({})).rejects.toThrow()
+})
+```
+
+---
+
+## 6. 优雅降级 🪂
+
+**定义：** 当依赖失败时，系统仍应提供有限的功能。
+
+**必须考虑：**
+- [ ] 外部 API 失败怎么办？
+- [ ] 数据库连接断开怎么办？
+- [ ] 是否有兜底机制？
+- [ ] 用户能得到什么反馈？
+
+**测试模板：**
+```typescript
+it('should degrade gracefully when dependency fails', async () => {
+  mockDependency.toThrow('Network error')
+
+  // 不应崩溃
+  const result = await operation()
+
+  // 应返回兜底值或部分结果
+  expect(result).toEqual(fallbackValue)
+})
+```
+
+---
+
+## 7. 可观测性 👁️
+
+**定义：** 系统状态必须可见、可追踪。
+
+**必须提供：**
+- [ ] 进度反馈（针对长时间运行的操作）
+- [ ] 状态查询接口（例如 status 命令）
+- [ ] 错误日志（失败原因）
+- [ ] 关键指标（计数、耗时）
+
+**本次改进：**
+- 新增 `kkb status` 展示原始文件统计 ✅
+- 新增 `kkb compile` 进度反馈 ✅
+
+---
+
+## 8. 并发安全 🧵
+
+**定义：** 多线程 / 多进程对共享资源的访问必须安全。
+
+**必须考虑：**
+- [ ] 文件读写冲突
+- [ ] 数据库事务隔离级别
+- [ ] 内存中共享状态的加锁
+- [ ] 竞态条件
+
+**测试模板：**
+```typescript
+it('should handle concurrent writes', async () => {
+  await Promise.all([
+    operation(data1),
+    operation(data2),
+    operation(data3)
+  ])
+
+  // 验证最终状态一致性
+  const state = await getState()
+  expect(state).toBeValid()
+})
+```
+
+---
+
+## 强制检查流程
+
+在每个 Story 的 **测试设计评审（Test Design Review）** 阶段，必须回答以下问题：
+
+```markdown
+### 工程常识检查清单
+- [ ] **幂等性**：能否重复运行？是否有测试？
+- [ ] **跨模块契约**：ID / 格式 / 算法是否一致？
+- [ ] **数据流**：生产者 -> 消费者管道是否完整？
+- [ ] **原子性**：部分失败时是否回滚？
+- [ ] **输入校验**：所有输入是否都已校验？
+- [ ] **优雅降级**：依赖失败时会发生什么？
+- [ ] **可观测性**：用户能否看到进度 / 状态？
+- [ ] **并发安全**：多线程访问是否安全？
+
+**任何一项不满足，都必须在编写实现代码之前补齐测试 / 设计。**
+```
+
+---
+
+## 9. Shell 脚本性能 🐚
+
+**定义：** `$()` 命令替换会 fork 一个子 shell。在热路径（每个测试、每条目录项、每次消息查找都调用的函数）中，这是主要开销来源。
+
+**经验法则：**
+- 1 次子 shell fork ≈ Linux 上 2–3 ms
+- 测试套件 setup 中 fork 1000 次 = 每次运行 +2–3 秒
+- 1739 个测试 × 2.3 秒 = **约 67 分钟被浪费的 CI 时间**（本仓库实测）
+
+**热路径中必须避免：**
+```bash
+# ❌ 子 shell fork —— 被调用上千次时很慢
+upper="$(echo "$lang" | tr '[:lower:]' '[:upper:]')"
+upper="$(_some_helper_function "$lang")"
+safe="$(_sanitize_key "$key")"
+
+# ✅ 内联等价写法 —— 零 fork
+case "$lang" in
+  en|EN) upper=EN ;;
+  zh|ZH) upper=ZH ;;
+  *)     upper="$(printf '%s' "$lang" | tr '[:lower:]' '[:upper:]')" ;;  # 罕见路径可接受
+esac
+safe="${key//[^A-Za-z0-9_]/_}"   # 参数扩展，无 fork
+printf -v "$varname" '%s' "$val"  # 用 printf -v 代替子 shell 赋值
+```
+
+**兼容性陷阱 —— "修了两次"反模式：**
+```
+PR #211: 修 $(echo | tr) → ${lang^^}      ✅ 快，但仅限 bash 4+
+PR #213: 修 bash 3.2 兼容 → $(_helper)    ❌ 重新引入了子 shell
+PR #218: 两者都修 → 内联 case             ✅ 快且 bash 3.2 安全
+```
+为兼容性修复时，要验证修复没有重新引入原来的问题。
+加一个时延断言或基准测试来守护回归。
+
+**内联后的死代码：**
+内联一个 helper 函数的逻辑时，删掉原函数并 grep 所有调用方。
+留下一个零调用方的函数会误导后续贡献者通过 `$()` 调用它，从而重新引入 fork。
+
+**必须检查：**
+- [ ] 这个函数是否在循环、setup() 或逐条目录加载中被调用？
+- [ ] 它是否在任何地方用了 `$()`？能否用 `case`、`${var//...}` 或 `printf -v` 替换？
+- [ ] 内联之后，原 helper 是否已成为死代码？删掉它。
+- [ ] 是否有时延测试或 CI 上限来捕获回归？（见 `ROLL_TEST_TIME_CAP`）
+
+---
+
+## 10. Shell 资源清理 🧹
+
+**定义：** 每个设置的 `trap` 都必须显式重置。临时文件和锁文件绝不能比拥有它的进程存活更久。
+
+**trap - EXIT 模式：**
+```bash
+# ❌ 悬挂的 trap —— 函数返回后 EXIT handler 仍留在调用方 shell 中
+local tmp; tmp=$(mktemp)
+trap "rm -f '$tmp'" EXIT
+# ... 干活 ...
+mv "$tmp" "$dst"
+return 0   # EXIT trap 仍然 armed —— 之后任何 exit 都会对陈旧路径触发 rm
+
+# ✅ 用完后总是重置
+local tmp; tmp=$(mktemp)
+trap "rm -f '$tmp'" EXIT
+# ... 干活 ...
+mv "$tmp" "$dst" 2>/dev/null || rm -f "$tmp"
+trap - EXIT   # 返回前解除
+return 0
+```
+
+**清理 helper 中的目录作用域：**
+```bash
+# ❌ 错误 —— 扫描的是环境变量默认值，而不是实际使用的路径
+_cleanup_tmp() {
+  local dir; dir=$(dirname "${MY_PATH:-$HOME/.default/path}")
+  ...
+}
+_do_work() {
+  local custom_path="$1"   # 可能与 MY_PATH 不同
+  _cleanup_tmp             # 扫描了错误的目录！
+}
+
+# ✅ 显式传入实际目录
+_cleanup_tmp() {
+  local dir="${1:-$(dirname "${MY_PATH:-$HOME/.default/path}")}"
+  ...
+}
+_do_work() {
+  local custom_path="$1"
+  _cleanup_tmp "$(dirname "$custom_path")"
+}
+```
+
+**必须检查：**
+- [ ] 每个 `trap "…" EXIT` 在函数返回前都有匹配的 `trap - EXIT`。
+- [ ] 清理 helper 接受目标目录作为参数 —— 不依赖隐式的环境变量路径。
+- [ ] trap 字符串中临时文件名被引号包住：`"rm -f '$tmp'"` 而不是 `"rm -f $tmp"`。
+
+---
+
+## 11. 测试可靠性 🧪
+
+**定义：** 测试不得依赖在不同主机上可能静默失败的环境假设。
+
+**PID 假设：**
+```bash
+# ❌ 假设 pid_max ≤ 99999 —— 在 pid_max 较大的容器中会静默失败
+local stale_tmp="runs.jsonl.tmp.99999"
+
+# ✅ 使用一个确定已死的进程
+bash -c 'exit 0' &
+local dead_pid=$!
+wait "$dead_pid" 2>/dev/null || true
+local stale_tmp="runs.jsonl.tmp.${dead_pid}"
+```
+
+**Heredoc 作用域：**
+在 heredoc 之外定义的函数，在生成的脚本执行时无法在其内部使用。
+调用它们会静默 no-op（若用 `|| true` 守护）或直接崩溃。
+```bash
+# ❌ _some_helper 在生成脚本的作用域中未定义
+cat > script.sh <<'EOF'
+_some_helper 2>/dev/null || true   # 静默 no-op —— 永远"成功"
+EOF
+
+# ✅ 要么内联逻辑，要么在 heredoc 内部定义该函数
+```
+
+**必须检查：**
+- [ ] 测试是否使用了可能在主机上冲突的硬编码 PID、端口或路径？
+- [ ] 测试是否调用了只在外层 shell 定义、而非 heredoc 内部定义的函数？
+- [ ] "死进程"检查是否使用了真正已退出的进程，而不是猜测的 PID？
+
+---
+
+## 自动化防护
+
+### CI 闸门规则
+```yaml
+# .github/roll-checks.yml —— 作为 CI 闸门在每个 PR 上强制执行
+checks:
+  idempotency:
+    - pattern: "ingest|import|sync"
+      require_test: "idempotency"
+
+  cross_module_contract:
+    - files: ["src/*/index.ts"]
+      check: "shared_id_generation"
+
+  data_flow:
+    - require_integration_test: true
+```
+
+这些作为 CI 闸门在每个 PR 上运行。慢性问题 —— 死代码、文档过期、结构漂移 ——
+由 `roll-.dream`（每晚代码健康扫描）捕获，并把 `REFACTOR-XXX` 条目写回 backlog。
+
+### Pre-Commit 钩子
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+echo "🔍 Checking engineering common sense..."
+
+# 检查幂等性测试
+if git diff --cached --name-only | grep -q "ingest\|import\|sync"; then
+  if ! grep -r "idempotency\|repeated run\|multiple times" tests/ 2>/dev/null; then
+    echo "❌ Missing idempotency tests!"
+    exit 1
+  fi
+fi
+
+echo "✅ Basic checks passed"
+```

package/guide/zh/pricing.md

@@ -0,0 +1,97 @@
+# Pricing — 成本可见性与价格快照
+
+Roll 按**模型公开单价**（而非你的订阅价格）计算每轮 cycle 的成本 — 它是一个可跨项目、跨 agent 对比的基准数字。本文档介绍 `roll config prices` 命令、价格快照机制、以及历史成本如何不受调价影响。
+
+## 成本显示在哪里
+
+dashboard（`roll loop status`）在每轮 cycle 显示两列成本相关数据：
+
+| 列 | 含义 |
+|----|------|
+| **model** | 使用的 agent + 版本（如 `deepseek-v4-pro`、`claude-sonnet-4-6`），决定了哪套价格生效 |
+| **cost** | 按公开单价 × 该轮实际 token 用量计算。币种跟随厂商：Anthropic 显示 `$`（USD），DeepSeek / Kimi 显示 `¥`（CNY） |
+
+Roll 通过**价格快照文件**（而非硬编码常量）查询单价。快照存放在 Roll 安装目录下的 `lib/prices/` 中。
+
+## 支持的厂商
+
+| 厂商 | 币种 | 数据来源 |
+|------|------|----------|
+| Anthropic (Claude) | USD | `platform.claude.com/docs/en/about-claude/pricing` |
+| DeepSeek | CNY | `api-docs.deepseek.com/zh-cn/quick_start/pricing/` |
+| Kimi (Moonshot) | CNY | `platform.kimi.com/docs/pricing/chat` |
+
+## `roll config prices` 命令
+
+```bash
+roll config prices show        # 打印当前所有厂商的价格快照表
+roll config prices refresh     # 拉取所有厂商官方定价文档、对比、有变化才落新快照
+```
+
+### `roll config prices show`
+
+打印当前生效快照的元数据和所有已知模型的每百万 token 单价表：
+
+```
+in       基础输入 token
+out      输出 token
+cw       缓存写入 token（单价比输入略高）
+cr       缓存读取 token（单价极低）
+```
+
+费率单位：**每百万 token，厂商本地币种**。
+
+### `roll config prices refresh`
+
+从各厂商拉取官方定价页面，解析价格表，与本地最新快照对比。支持按厂商刷新：
+`roll config prices refresh anthropic|deepseek|kimi`。
+
+- **价格有变** → 写入新快照文件（`snapshot-YYYY-MM-DD.json`），终端打印 diff（红色减、绿色加），dashboard 下次渲染时自动使用新价格。
+- **无变化** → 打印 `up to date` 后退出。
+
+网络故障或页面解析失败时，命令会报错退出 — **已有的快照不会被失败的拉取覆盖**。
+
+## 价格快照
+
+每个快照是一个 JSON 文件，按日期命名，存放在 `lib/prices/` 下：
+
+```
+lib/prices/
+  snapshot-2026-05-22.json
+  snapshot-2026-06-01.json   ← refresh 检测到价格变化后写入
+```
+
+快照内容：
+
+| 字段 | 说明 |
+|------|------|
+| `version` | 快照创建时的 ISO 8601 时间戳 |
+| `effective_at` | 厂商开始执行此价格的日期 |
+| `source_url` | 使用的官方定价页面 URL |
+| `prices` | 字典：`模型名 → {in, out, cache_create, cache_read}` 每百万 token 单价 |
+
+快照**永不删除** — 每个版本都保留，方便回溯任意时间点生效的费率表。
+
+## 历史成本固化
+
+loop cycle 结束时，Roll 会在 usage 事件中额外写入两个字段：
+
+| 字段 | 用途 |
+|------|------|
+| `cost_list_usd` | 按当时快照计算出的成本 — 永久固定 |
+| `prices_version` | 计算时使用的快照版本号 |
+
+dashboard 渲染历史 cycle 时优先读取 `cost_list_usd`。如果该字段缺失（此功能上线之前的旧 cycle），则回退到用*当前*快照现算，并在行末追加浅灰色 `[legacy]` 标记。
+
+**核心效果：** 厂商调价、`roll config prices refresh`、Roll 版本升级都不会回头改写历史 cycle 的成本数字。"当时实际花了多少"是事实，不动。
+
+## 常见问题
+
+**Q: cost 列反映的是我的实际账单吗？**
+不是。它使用的是公开单价。如果你是订阅用户（Claude Pro、Team 等），实际成本会更低。把它当成一个可横向对比的基准数字。
+
+**Q: 价格变动后怎么办？**
+运行 `roll config prices refresh`。如果有变化会自动写新快照，后续 cycle 使用新价格。旧 cycle 的历史成本保持不变。
+
+**Q: 能加其他厂商的价格吗？**
+可以 — `roll config prices refresh --vendor deepseek`（或 `kimi`）。`--vendor` 参数告诉抓取器去爬哪个厂商的定价页面。

package/guide/zh/project-setup.md

@@ -0,0 +1,114 @@
+# Roll — 项目初始化
+
+## 初始化项目
+
+在项目根目录执行：
+
+```bash
+roll init
+```
+
+`roll init` 会先诊断当前目录状态，再决定是否改动文件：
+
+1. **空目录** —— 全新起点。Roll 直接写入 `AGENTS.md`、空的 `.roll/`
+   骨架（`backlog.md`、`features/`、`domain/`），可继续在 `.roll/agents.yaml`
+   声明 scoped agent binding。不问问题。这是
+   **seed（播种）** 接入模式 —— 见 [patterns/seed-pattern.md](patterns/seed-pattern.md)。
+2. **PRD/文档-only** —— Roll 发现需求或产品文档，但没有源码和 manifest。
+   这是新项目路径，会指向设计；不会进入已有代码库接入。
+3. **已有代码库但未接入 Roll** —— Roll 检测到源码但没有 `.roll/`。它**不会**默默
+   生成骨架，而是引导你用 `$roll-onboard`：扫描代码、问一组认知 / 范围 /
+   隐私问题、产出 `.roll/init-diagnosis.yaml` 和 `.roll/onboard-plan.yaml`
+   供审阅。审阅成对产物后执行
+   `roll init --apply`：它会打印审阅检查点，列出每个计划文件操作的动作、目标路径、
+   合并/创建模式和用户内容处理方式，并在交互终端等待确认。非交互自动化里，审阅后必须显式执行
+   `roll init --apply --auto`。这是 **graft（嫁接）** 模式 —— 见
+   [legacy-onboarding.md](legacy-onboarding.md) 与
+   [patterns/graft-pattern.md](patterns/graft-pattern.md)。
+4. **已初始化** —— `.roll/`、`AGENTS.md`、backlog、features 都存在。Roll
+   打印 `Already initialized` 和 `Next: roll status`。
+5. **部分接入 Roll** —— 有一部分 Roll 标记但不完整。Roll 打印
+   缺失项和仍存在的 pre-v2 旧标记。`roll init --repair` 会先预览修复计划，
+   在交互终端等待确认；非交互自动化必须显式执行 `roll init --repair --auto`。
+   修复只创建缺失的 Roll-owned 文件或合并 Roll-owned 区块，并写入
+   `.roll/onboard-changeset.yaml`，之后 `roll setup offboard` 可以反向移除这些改动。
+
+任一路径之后，都可以用 `roll next` 接着走。它读取相同的 Roll 标记，以及
+`.roll/brief.md`、`.roll/onboard-plan.yaml`、`.roll/backlog.md`，只输出一个下一步：
+从 brief 进入设计、审阅并 apply onboard plan、修复 partial 标记、执行旧布局迁移、
+对下一张 Todo 开 loop，或在没有可执行项时查看 status。
+
+正在从 2.0 之前的布局升级（`BACKLOG.md` 在根目录或 `docs/features/`）？
+先跑 `npx @seanyao/roll@2 migrate` —— 见
+[migration-2.0.md](migration-2.0.md)。`roll init` 会拒绝在迁移到一半的
+项目上叠加骨架。
+
+## 更新约定和技能
+
+roll 发布新版本后，将新约定同步到项目：
+
+```bash
+roll sync
+```
+
+`sync` 只覆盖 roll 管理的文件（技能和全局约定），不会动你的 `.roll/backlog.md`、项目源码等文件。
+
+## 典型首次使用流程
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash   # 安装 roll
+roll setup                 # 全机器配置 AI 工具（仅需一次）
+cd my-project
+roll init                  # 诊断并路由该项目
+roll next                  # 接续 design/apply/repair/migrate/loop/status
+roll loop on               # 开启自主执行
+```
+
+`roll setup` 会为本机已安装的 AI 工具同步约定。Agent 语义写在
+`~/.roll/agents.yaml`（Machine Scope）和 `.roll/agents.yaml`（Project Scope）。
+旧的 `primary_agent`、local agent、pairing 或 v3 route-slot 数据可以通过
+`roll agent migrate --dry-run` 预览迁移到 scoped 模型。
+
+## 创建的文件
+
+| 文件 | 用途 |
+|------|------|
+| `AGENTS.md` | Agent 约定：领域模型、作用域、编码规范（根目录 — 所有 AI 客户端的入口） |
+| `.roll/backlog.md` | 故事跟踪（Epic / Feature / Story / Fix / Refactor） |
+| `.roll/features/` | 每个 Feature 的深度文档 |
+| `.roll/domain/` | DDD 模型、context map、架构记录 |
+
+## 幂等性
+
+`roll init` 可安全重复执行：完整项目会提示 `roll status`，部分项目会提示
+`roll init --repair`，不会再次强行跑脚手架。
+
+## 另见
+
+- [installation.md](installation.md) — 安装和更新 roll
+- [conventions.md](conventions.md) — AGENTS.md 结构和约定
+- [patterns/](patterns/README.md) — 三种接入模式（seed / graft / replant）
+- [legacy-onboarding.md](legacy-onboarding.md) — 将 Roll 嫁接到已有代码库
+- [migration-2.0.md](migration-2.0.md) — 从 2.0 之前的布局升级到 `.roll/`
+- [loop.md](loop.md) — 开启自主执行
+
+## Git Hooks 自动配置（US-INFRA-008/009）
+
+Roll 的 TCR 提交前检查在 `hooks/pre-commit` 里。
+Git 默认忽略这个目录——需要把 `core.hooksPath` 指向它才能生效。
+Roll 在三个地方自动完成配置，不会出现"检查门被绕过"的时间窗口：
+
+1. **`roll setup`** — 在当前仓库设置 `core.hooksPath=hooks`。
+2. **自主 loop 每轮 cycle preflight** — 每轮启动时确保 worktree 的 hooks 路径正确。
+3. **Claude Code SessionStart hook**（`.claude/settings.json`）— 每次新开 Claude Code 会话时自动执行 `git config core.hooksPath hooks`。
+
+**手动覆盖：** 如果你已经把 `core.hooksPath` 设成了别的值，Roll 不会覆盖它。
+自动配置只在该值未设或等于 git 默认值 `.git/hooks` 时才触发。
+
+**排查：** 提交时没有运行测试：
+
+```bash
+git config core.hooksPath   # 应该显示: hooks
+ls hooks/pre-commit          # 应该存在且可执行
+roll setup                   # 重新执行配置步骤
+```

package/guide/zh/roll-doc-audit.md

@@ -0,0 +1,90 @@
+# roll-doc-audit —— 文档/产品一致性审计
+
+`roll-doc-audit` 核对用户可见文档表面与真实实现: README、指南、网站页面、CLI help、
+测试和源码。需要文档盘点时,它也会产出草稿文档:文档索引、为缺文档目录补的模块
+README,以及 Phase 3b 阶段的跨目录主题文档(数据流、状态机、外部集成等)。它不会
+在没有源码证据时编造行为。
+
+```
+$roll-doc-audit              # 完整运行(全部 phase)
+$roll-doc-audit --dry-run    # 仅 Phase 1–2;打印 Phase 3 / 3b 计划,不写任何文件
+$roll-doc-audit --force      # 即便目标文件已存在也重新生成草稿
+```
+
+## 四 Phase 全流程
+
+roll-doc-audit 依序运行四个 phase,外加深度读取的 Phase 3b——当项目存在值得记录的
+跨目录结构时触发。
+
+| Phase | 名称 | 做什么 |
+|-------|------|--------|
+| 1 | Scan & Index | 遍历目录树,分类每个 `*.md` 与约定文件,(覆盖)写出 `docs/INDEX.md`,含覆盖率摘要与缺口报告。 |
+| 2 | Gap Analysis | 找出有 ≥ 3 个源文件(或被 ≥ 5 个文件引用)却无 `README.md` 的模块目录,以及特殊缺口(领域模型图、约定文档)。 |
+| 3 | Fill | 对每个目录级缺口,读取至多 20 个源文件并生成草稿 `README.md` / 上下文图 / 约定文档。已存在的文件除非 `--force` 否则跳过。 |
+| 3b | Deep Read | 构建完整项目符号表(全量读取,不截断),侦测 Phase 3 单独无法发现的六类跨目录主题。 |
+| 4 | Report | 打印各 phase 摘要:索引文档数、缺口数、生成草稿数、Phase 3b 符号表计数与主题文档。 |
+
+Phase 3b 是"逐目录"文档与"贯穿整个代码库逻辑"文档之间的分水岭。Phase 3 孤立地
+读取每个缺口目录(且每个目录至多 20 个文件);Phase 3b 全量读取每个源文件并跨文件
+推理。
+
+## Phase 3b —— 六类主题
+
+Phase 3b 在**满足任一条件**时运行:Phase 2 发现了缺口,**或**项目展现出 Phase 3
+无法捕捉的代码特征(跨 ≥ 3 个目录的 import 链、被共享的状态枚举、外部端点调用,
+或 CI 配置)。纯文档项目若无源码缺口则完全跳过 Phase 3b。
+
+构建符号表(`exports`、`imports`、`enums`、`external_urls`、`configs`)后,
+Phase 3b 侦测六类主题。每类在其侦测规则无命中时跳过,目标文件已存在时也跳过
+(除非 `--force`)。
+
+| # | 主题 | 触发条件 | 输出 |
+|---|------|----------|------|
+| 1 | 数据流 / 调用链 | 从入口文件(`bin/`、`main.*`、`index.*`)出发的 import 链跨越 ≥ 3 个不同源目录 | `docs/data-flows.md` |
+| 2 | 状态机 | 名为 `*State` / `*Status` 的枚举被 ≥ 2 个源文件引用 | `docs/state-machines.md` |
+| 3 | 外部集成 | `fetch` / `axios` / `http.*` 调用或 `*_URL` / `*_HOST` 常量(排除注释与测试夹具) | `docs/integrations.md` |
+| 4 | 部署管线 | 存在 CI 配置文件(`.github/workflows/*.yml`、`.gitlab-ci.yml`、`circle.yml`、`Jenkinsfile`)加部署 URL 模式 | `docs/deployment.md` |
+| 5 | Agent 入口 | 根目录无 `AGENTS.md` 且源码根有 ≥ 3 个子目录 | `AGENTS.md` |
+| 6 | 高引用目录 | 某目录被 ≥ 5 个其他源文件引用,即使自身 < 3 个源文件 | `<dir>/README.md` |
+
+每篇主题文档都为每条论断标注 `file:line`,均来自真实符号表记录——roll-doc-audit 绝不
+伪造行号。
+
+## dry-run / force 行为
+
+**`--dry-run`** 运行 Phase 1–2,随后打印 Phase 3 填充计划与 Phase 3b 计划
+(符号表摘要计数,加上*将要*生成的主题文档,每条标 `(plan)`)。不写任何磁盘文件。
+用它在完整运行前先预览。
+
+**`--force`** 即便目标文件已存在也重新生成草稿。它只影响草稿生成(Phase 3 与
+Phase 3b 的输出文件);无论带不带 flag,符号表每次运行都从头重建。`--force` 不改变
+`docs/INDEX.md` 的行为(始终重建),也绝不覆盖草稿目标之外的人工内容。
+
+**默认(无 flag)** 是幂等的:无新缺口时重新运行是 no-op——不写文件,不改已有
+草稿。
+
+## 典型输出文件清单
+
+对一个含代码的项目完整运行,可能产出:
+
+```
+docs/INDEX.md            # Phase 1 —— 始终(覆盖)写出
+src/<module>/README.md   # Phase 3 —— 每个模块缺口一个
+docs/CONVENTIONS.md      # Phase 3 —— 当无约定文档时
+.roll/domain/context-map.md  # Phase 3 —— 当无领域条目时
+docs/data-flows.md       # Phase 3b —— 跨目录调用链
+docs/state-machines.md   # Phase 3b —— 共享状态枚举
+docs/integrations.md     # Phase 3b —— 外部端点
+docs/deployment.md       # Phase 3b —— CI 管线
+AGENTS.md                # Phase 3b —— 仅当不存在时
+<dir>/README.md          # Phase 3b —— 高引用目录
+```
+
+只有 `docs/INDEX.md` 会被覆盖——它是派生产物。其余每个文件都是草稿,以下面这行
+开头:
+
+```
+> **Draft** —— auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
+```
+
+审阅每篇草稿,按需修改,提交你想保留的那些。