# M1-M4 合并 Review（最终版）

> 依据：两份既有 review 的交集与差异合并而成。这里保留我自己的判断：把“会让主循环跑不起来”的问题放到最前，`F1` 级别的宿主 CLI 缝降为 follow-up，不抢 blocker 位。

## 结论

整体上，M1-M4 的架构方向是对的：DTO 隔离、确定性编排、宿主壳生成、知识迁移这几条主线都立住了。
但如果按“真实作者流程能不能稳定跑通”来审，当前仍有几处会直接卡住主循环，不能算完全收口。

**结论分层：**
- **Blocker**：主循环与持久态一致性问题，必须先修。
- **高优先级问题**：review / session / validator 的健壮性缺口，会导致静默漏料或错误接受。
- **Spec 问题**：规范本身有矛盾或责任方未钉死，需要回填，否则后续实现会继续漂。

## Blocker

### B1. 定稿后缓存不重建，`next` 可能重抄旧章

`finalize` 写入新正文后没有同步刷新 `.cache/index.db`，而 `next` 侧只会在缓存缺失/损坏/空表时重建。
这会导致磁盘已经写了新章，但状态机仍按旧 `MAX(chapter_num)` 继续跑，出现“已定稿第 3 章，却又起第 3 章细纲”的回环。

这是主循环级问题，不是 smoke 推迟能覆盖掉的。

### B2. 建书流程没有把 git 仓库初始化责任落到生产代码

当前 `persistCreateBook` 只写 `book.yaml` / `总纲.md` / `第01卷.md`，没有把 `git init`、`core.quotepath false`、`.gitignore` 这几件事真正落地。
结果是新书仓库未必可直接定稿，缓存也可能被错误跟踪，后续写章和提交链路会断。

### B3. 多文件写入没有原子边界

`persistCreateBook`、`persistVolumeReview`、`persistRepair`、`persistReviewReport` 都是顺序写多个文件。中途失败会留下半套产物。
这和“定稿必须原子”“多文件写入要么全成要么原样保留”的规范冲突，属于实打实的数据完整性风险。

## 高优先级问题

### H1. ReviewInput 组装不全，且角色命中只认正名

两审输入里，设计要求的 `相关条目`、`名册待确认新专名` 还没有真正进入 DTO。
另外，相关角色靠 `草稿全文.includes(name)` 按文件名正名命中，别名不会被纳入。这样会让审查上下文缺料，尤其是作者正文里常用别名时。

### H2. Review schema 对坏输入不够安全

`validateReviewReport` 默认假设 `issues` 里的每个元素都是对象。只要混进 `null`、字符串或别的坏值，就可能直接抛异常。
同时 `blocking` 现在是 `!!issue.blocking`，字符串 `"false"` 这类值会被当成真，语义上太松。

### H3. 审稿报告保存的是归一化结果，不是原始输出

设计文档写的是保存 raw output，但当前 `评审报告/事实审查.json`、`编辑审.json` 实际写入的是校验器复算后的对象。
这会让后续排查模型漂移、对比原始输出变难。

### H4. `books.jsonl` 部分损坏时没有触发真正的自愈

现在只要 `books.jsonl` 还能读出部分有效行，就不会进入扫描重建。坏行会被吞掉，但不会回写修复。
这会让书单长期处在“半坏不坏”的状态。

### H5. 绝对路径检测范围太窄

host shell validator 里的绝对路径正则只覆盖少数 Windows/Linux 用户目录形态，像 `/tmp/...`、`/opt/...`、UNC 路径、`C:/...` 这类都可能漏掉。
这会削弱“生成物不带本机绝对路径”的保证。

## Spec 问题

### S1. 数据表定义与实现不一致

规范里列的是五张表，但实现里实际上还有 `entity_aliases`。
这不是代码错，是 spec 漏列了，后续如果不回填，所有审查都会在这里卡一次。

### S2. “未知字段保留” 与 “禁止嵌套映射” 的边界没钉死

规范一边说未知字段要保留原样写回，一边又禁止嵌套映射。
这两个约束现在没有明确边界，作者一旦加自定义嵌套字段，脚本会和规范互相打架。

### S3. `core.quotepath false` 的责任方没明确

规范要求它必须设置，但没有说明是建书、安装器还是别的入口负责。
没有责任方，就很容易像现在这样没人真正实现。

### S4. 多文件原子性边界未豁免或未收口

错误处理规范要求多文件写入原子，但 review / persist 这条链路天然就是多文件。
规范要么补豁免边界，要么补统一的原子写入模式，否则实现永远会显得“不合规”。

### S5. 一些“待增量补充”长期未闭环

数据库列定义、错误退出码、AI 调用预算、日志/CLI 约定等都还停在“待增量补充”。
M1-M4 已经推进到能跑主流程的阶段，这些空白该回填，不然后续任务的依据会一直悬着。

## 需要保留的判断

第一份 review 提到的“宿主 CLI 缝”和真模型 smoke 推迟，我保留，但它更像后续接线问题，不是当前最核心的阻断项。
第二份 review 抓到的主循环缺口更重，所以最终版应以前者为 follow-up、以后者为 blocker。

## 最终排序

1. 先修 B1/B2/B3，保证主循环和持久态不再断。
2. 再补 H1-H5，把 review / session / validator 的漏口堵上。
3. 同步回填 S1-S5，免得后续实现继续和 spec 打架。
4. F1 级别的宿主 CLI 缝继续保留为 follow-up，不抢 blocker 位。