webnovel-writer/.trellis/tasks/archive/2026-07/07-02-v7-boundary-code-fixes/prd.md

v7 边界收口：格式对齐与状态机判定修复

来源：2026-07-02 设计边界回顾（作者逐项确认）。文档侧裁决已由 07-02-v7-boundary-doc-backfill 落进 spec 0.9 / PRD 1.1 / multi-agent v3.5 / 实施计划 0.3（commit 871c448）——本任务以 spec 0.9 为依据改代码。 定位：M5 安装器的前置（实施计划 0.3 §0 已登记）。deep review 的判断同样适用："否则 M5 安装器接一个跑不通的循环"。

Goal

消除"格式法律文本 ↔ 参考实现"漂移中该改代码的一侧（3 项），修复状态机三个判定边界 bug（含收卷声明制落地），补齐机检/备料/ReviewInput 三处缺料。九项全部对齐 spec 0.9。

Requirements

A. 格式对齐（spec 0.9 §2.1/§4.3/§4.6，改代码从 spec）

• A1 卷纲路径：大纲/第NN卷.md → 大纲/卷纲/第NN卷.md。涉及 OutlineReader（读取与 listVolumes 正则）、persist.js（persistCreateBook/persistVolumeReview）、测试 fixtures、相关测试。
• A2 卷摘要文件名：定稿/摘要/卷摘要/NN.md → 第NN卷.md（与时间线、卷纲同形态）。
• A3 信息差字段名：谁知道/读者知道 → 知情人/读者已知（spec §4.3）。涉及 rebuilder.js、SecretWriter/SecretReader 及注释、fixtures、机检测试。无存量用户数据，直接切换、不做旧字段兼容读取。

B. 状态机判定（spec 0.9 §10）

• B1 收卷声明制（决策 27）：序 4 判定由 maxChapter % 卷规模 === 0 改为"最新定稿章 front matter 收卷: 是"。链路：chapters 缓存表加收卷列（重建器填充；缓存可删重建，无迁移问题）→ detectors/状态机改判定 → 序 6 细纲 DTO 的期望产物文案补"可含收卷提议（依据卷纲进度与卷规模参考值）"。
• B2 序 5 体检判定（决策 29）：% 体检周期 === 0 改"距上次体检 ≥ 体检周期"；上次体检章号存 .cache（丢失重测无害，符合派生物语义）。必须配最小体检执行点，否则新语义下序 5 自第 50 章起每次启动命中、主循环卡死：新增 health-check 脚本命令（零 token），汇总既有报表（悬了太久、条目活跃率、连续弱钩）落 工作区/体检报告.md 并记录上次体检章号；文体统计项标注"随 M5.5"。
• B3 序 0 源文件清单（决策 28）：detectParseFailures 按 spec 清单补扫 book.yaml、文风/文风铁律.md front matter、定稿/设定/名册.md 表、定稿/设定/时间线/ 表；解析失败进序 0 修复确认，不再静默降级为默认值。
• B4 序 3 未完成流程（决策 29）：hasUnfinishedWork 把 细纲.md、本章写作材料.md 计入（对齐 spec 续跑映射表），已确认细纲不再被序 6 覆盖。

C. 缺料补齐（spec 0.9 §8）

• C1 机检补"条目变动形式检查"（§8 第 5 步；M2 D2 七项之一，漏做）：草稿 front matter 声明的条目变动做两条纯形式校验——①声明的条目 ID 在 threads 表存在（"埋下"相反：要求 ID 不存在）；②生命周期动词与条目当前状态兼容（推进/回收/揭晓等要求状态=进行）。查表即可，不判语义。
• C2 备料信息差边界补内容（§8 第 3 步；PRD §4 #3"注入出场人物知识边界"）：每条未揭晓信息差由只给 ID 改为注入 短题+知情人+关键词+内容首句，并明示"除知情人的对话与视角外不得出现"。
• C3 ReviewInput 补 evidence 维度数据（§8 第 6 步③）：相关条目由纯元数据扩为附 履历尾部 N 行；新增"拟条目变动"（来自草稿 front matter 的 伏笔/悬念/感情线 声明）。roles/事实审查.md 输入清单同步补"相关条目（含拟变动与近期履历）"。边界说明：含证据引用的"拟履历行"起草与核对随 M5 F1 接线（save-review/finalize 通道），不在本任务。

Constraints

• 依据只认 spec 0.9 文本；实现与 spec 再冲突时停下来改 spec（走决策记录），不得代码侧自行发挥。
• 零新增运行时依赖；错误全中文、永不带堆栈（既有规范）。
• 测试是探针不是约束：过时的路径/字段断言随格式对齐一并改；新判定逻辑各配正反用例。
• roles 单源改动后跑 drift check / package validator（v7/scripts/），dist 生成物不提交。
• Windows 中文路径 CI（双平台矩阵）保持绿。

Acceptance Criteria

• AC1 格式三项与 spec 0.9 一致：全库 grep 无扁平卷纲路径、无 谁知道/读者知道；卷摘要写出 第NN卷.md。fixtures 同步。
• AC2 收卷链路端到端：定稿一章带 收卷: 是 → 重建缓存 → next 判序 4 卷复盘；不带收卷的第 40/80 章 → 不触发卷复盘（旧整除行为消失）。
• AC3 体检按"距上次体检 ≥ 周期"触发；体检记录随 .cache 删除后重测不报错。
• AC4 序 0 用例：损坏的 book.yaml / 文风铁律 / 名册 / 时间线 各注入一例 → next 返回序 0 修复确认；不再出现"静默用默认值"路径。
• AC5 序 3 用例：工作区仅存 细纲.md → next 返回序 3（续跑），细纲文件未被改写。
• AC6 机检条目形式检查：声明不存在 ID、动词与状态不兼容、"埋下"撞已有 ID 三类各有用例并报 issue。
• AC7 备料产物含信息差 短题/知情人/关键词/内容首句；ReviewInput 含拟条目变动与履历尾部（测试断言）。
• AC8 全量 node --test 绿；「删光 .cache 全量重建」用例绿；drift check + validator 绿。

Out of Scope

• F1 宿主 CLI 缝（next --json/review-input/save-review/persist-*/finalize 命令）→ M5（实施计划 0.3 已列清单）。
• 体检统计项实现（高频意象/句式体检/指纹提取）→ M5.5。
• 拟履历行的起草流程 → M5 F1 接线。