# PRD: v7 RFC 后续推进

## Goal

根据 v7 RFC 反馈报告（2026-06-16）完成 v7 设计收尾，为实施做好准备，并最终合并到 master 分支。

## Background

v7 RFC 征集期已结束（Discussion #118），反馈报告已完成分析。报告指出：
- 公开反馈支持 v7 核心方向（精准读取降低 token、增加作者确认点）
- 提出了具体改进建议（规划流程停顿点、主角动机检查、文风对齐、多宿主编排）
- 识别出 3 个必须在 v7.0 实施前决策的设计问题（A1/A2/A3）
- 识别出若干需要澄清的 spec 边界问题（B1-B4）
- 识别出应放入 7.x backlog 的功能（C1-C4）

## Requirements

### R1: 核心决策（已完成）✓

三个必须在 v7.0 实施前决策的问题已明确：

**A1: 自动模式叠加视图一致性** — 版本链叠加
**A2: node:sqlite 运行时承诺** — Node >= 22.13.0
**A3: 履历证据结构化锚点** — 章节级别 + 自然语言

### R2: 文档更新（待执行）

根据决策结果和 RFC 反馈更新相关文档：

**必须更新的文档**：
1. `story-repo-spec-2026-06-10.md` (0.6 → 0.7)
   - 补充 A1 决策：自动模式待定稿批次的版本链叠加机制（§8.1）
   - 更新 A2 决策：Node >= 22.13.0 运行时要求（§2.2）
   - 明确 A3 决策：履历证据的章节级验证范围（§5 线索条目格式，§11 缓存重建器职责）
   - **调整三审定义**（§8 写章流程第 6 步）：
     - 改为**两审**：事实审查 + 编辑审
     - 事实审查：v6 的 5 维度（设定/时间线/连贯/角色/逻辑）+ v7 特有项（要写到的事核对、泄密候选判断、履历证据验证）
     - 编辑审：结构、节奏、商业性、**主角动机检查**（新增）
     - 去掉"读者审"（爽点判断留给作者）
     - 输出格式参考 v6 review schema（结构化问题清单，severity + blocking 机制）
   - 澄清 B 类问题：缓存删除代价、关键词扫描边界、两审模式（完整 vs 兼容）

2. `v7-implementation-plan.md` (0.1 → 0.2)
   - **补充 §1.5 v7 架构原则**（指导实施）：
     - AI 永远不接触文件结构（只看 DTO）
     - 状态机只管编排，不做业务判断
     - 按 Use Case 拆分（不做通用工具函数）
     - 拆小端口，不做大接口（避免上帝对象）
     - 配置只调策略，不定义流程
   - 更新 M1 里程碑：`.cache/index.db` DDL 和精准读取接口清单（O4 消解）
   - 补充 M6 里程碑：自动模式版本链叠加视图的实施要点
   - 更新 M4 里程碑：两审任务书单源（事实审查 + 编辑审）
   - 更新 "下一个可立即开工的任务" 章节

3. `v7-prd.md` (保持 1.0)
   - 不修改 PRD 1.0（已定稿）
   - 决策细节只记录在 spec 中

4. `multi-agent-adaptation-spec-2026-06-05.md` (v3.2 → v3.3)
   - 明确两审的两种模式：完整模式（两个新鲜上下文）vs 兼容模式（单 agent 顺序执行）
   - 澄清"兼容模式会诚实声明隔离度下降"
   - 更新审稿清单定义（参考 v6 reviewer schema）

**RFC 反馈采纳清单**（记录在文档中）：
- ✓ 规划流程确认点 — 已在 PRD §2 体现（建书→卷纲→章纲→初稿→审稿）
- ✓ 主角动机检查 — 纳入编辑审清单
- ✓ 多宿主编排模式 — 明确完整模式 vs 兼容模式
- ✓ 审稿维度优化 — 基于 v6 经验调整为两审（事实审查 + 编辑审）
- → 文风对齐 — 放入 7.x backlog（文风指纹、scene beat 标签）
- → 语义召回 — 放入 7.x/plugin backlog（可选能力，不作为事实来源）

## Design Decisions

### D1: 审稿维度调整（基于 v6 经验）

**决策**：从"三审"调整为"两审"，去掉主观的"读者审"

**方案对比**：

| 维度 | v6 (reviewer) | v7 spec 0.6 (三审) | v7 新方案 (两审) |
|------|--------------|-------------------|-----------------|
| 事实验证 | 5 维度 | 设定校对 | **事实审查**（5 维度 + v7 特有项） |
| 结构/商业 | 无 | 编辑审 | **编辑审**（细化 + 主角动机） |
| 主观评价 | 无（明确禁止） | 读者审（爽不爽） | **去掉**（留给作者） |

**新的两审定义**：

**1. 事实审查**（AI，新鲜上下文）
- v6 的 5 个维度：
  - 设定一致性：能力/地点/物品是否符合世界观
  - 时间线：时间衔接、倒计时、角色位置
  - 叙事连贯：钩子回应、场景转换、情绪弧
  - 角色一致性：对话风格、行为动机、知识边界
  - 逻辑：因果关系、角色决策、力量对比
- v7 特有的三项：
  - "要写到的事"逐条核对正文
  - 机检泄密候选的语义判断
  - 条目履历引用的章内证据验证
- 输出：结构化问题清单（severity + category + blocking）

**2. 编辑审**（AI，新鲜上下文）
- 结构：开头/转折/高潮/收尾是否到位
- 节奏：信息密度、情绪起伏
- 商业性：钩子强度、追读力（用知识库标准提示，不终审）
- **主角动机**（RFC 反馈新增）：
  - 主角每个主要行动是否有即时驱动、可见压力、预期收益、情绪原因
  - 或明确标注为非理性行为
- 输出：结构化问题清单

**关键原则**（继承 v6）：
- ✅ 只报可验证的问题（必须有 evidence）
- ✅ severity + blocking 机制（critical 自动阻断）
- ❌ 不评价文笔质量（除非是可计数的句式问题，归机检）
- ❌ 不评价"爽不爽"（AI 无法代替真实读者，作者自己读草稿就是最好的读者审）

**理由**：
1. v6 实践证明：5 维度事实审查是有效的，可验证的
2. "爽不爽"是高度主观的，v6 明确禁止主观评价
3. 作者在第 7 步审稿时通读草稿，本身就是最好的读者视角
4. 两个新鲜上下文比三个更经济，且覆盖了所有可验证维度

**多宿主适配**：
- 完整模式：事实审查 + 编辑审各用独立上下文
- 兼容模式：单 agent 顺序执行两审，诚实声明隔离度下降

### D2: 审稿终止机制（来自 RFC 遗漏分析）

**问题**：Discussion #118 用户 shuimushanjia 反馈："每次让AI审查修改后，再次审查又会出现新的问题，似乎无穷无尽"

**决策**：明确审稿终止条件，避免无限循环

**方案**：
1. **两审输出结构化问题清单**，每个问题包含：
   - `severity`: critical / high / medium / low
   - `category`: 问题分类
   - `blocking`: 是否阻断定稿（critical 默认 true）
   - `description` + `evidence` + `fix_hint`

2. **阻断规则**：
   - 只有 `blocking=true` 的问题阻断定稿
   - `severity=critical` 自动 `blocking=true`
   - 其他 severity 由 AI 判断是否 blocking

3. **作者审稿时的选择**：
   - 接受当前版本（即使有非阻断问题）
   - 改完接受（修改后不重新审稿，直接定稿）
   - 打回重写

4. **系统不强制完美**：
   - 非阻断问题作为"优化建议"，不强制修改
   - 作者可以在审稿单上标注"已知问题，接受现状"

**理由**：
1. v6 实际使用中存在审稿循环问题，v7 必须有明确解法
2. v6 的 reviewer 已有 severity + blocking 机制（参考 `webnovel-writer/references/review-schema.md`）
3. 两审调整减少了主观评价，但仍需要明确的终止机制
4. 作者应该有权决定"够好了"，系统不应追求不可达的完美

**实施要点**：
- spec 0.7 §8（写章流程）明确审稿终止条件
- multi-agent-spec v3.3 更新两审的输出格式（参考 v6 review schema）
- 审稿报告模板明确区分"阻断性问题"和"优化建议"

### D3: 未登记伏笔检测（来自 Discussion #118 深度核验）

**问题**：v7 伏笔系统是纯声明制，只跟踪细纲声明、front matter 登记过的条目。AI 在写稿步（§8 第 4 步，干净上下文）即兴埋的钩子，无对应条目 → 不进"悬了太久"、卷复盘扫不到 → 烂尾。正是 shuimushanjia（06-22）反馈的"埋了一个伏笔之后就没了下文，似乎没将这判定为伏笔"。

**决策**：给声明制加"补漏网"——在事实审查中检测正文里的疑似未登记伏笔，作为**非阻断候选**提示作者。

**方案**：
- **落点**：事实审查（§8 第 6 步），搭已有的整章通读。现检查是单向"声明推进了，正文真有吗"；新增反方向"正文出现疑似伏笔，反查有无条目"——同一次读取，边际成本≈0。
- **形态**：结构化问题清单新增 `category=unregistered_thread`，`severity` low/medium，**`blocking` 永远 false**；走信息差泄密扫描同款"候选制，不拦截"（§4.3 模式）。
- **作者裁决**（审稿单第 7 步三选）：登记成条目（触发"开新条目必须写收尾计划"，自动防悬空）/ 忽略（普通描写）/ 删掉。
- **误报控制**：判定门槛保守，仅捞"刻意强调 + 明显悬置 + 本章无即时解释 + 结构像 setup"者。非阻断，误报代价低，但宁紧勿松。

**理由**：
1. shuimushanjia 抱怨的不是"系统忘了已登记的坑"（v7 防得很死），而是声明制天生看不见 AI 即兴挖的坑。
2. 搭已有整章通读，成本几乎为零；非阻断，风险小。
3. 对口最高频反馈，适合纳入 v7.0。

**实施要点**：
- spec 0.7 §8 第 6 步事实审查职责增列 `unregistered_thread` 候选检测。
- multi-agent-spec v3.3 事实审查 category 取值表加 `unregistered_thread`。

### D4: 设定↔大纲单向依赖（来自 freezero2020 反馈，2026-06-26）

**问题**：freezero2020 反馈"设定集与大纲互相交叉，改一处牵连多文件、频繁不同步"，希望单向关联。v7 目录层已三分（`定稿/设定` 只进不改 / `大纲` 随时改 / `文风` 独立），主体诉求已满足，但依赖方向只是**隐含**单向，未显式成约束。

**决策**：在 spec §1 设计不变量补一条显式约束。

**方案**：
- 不变量文字：**"设定层只记已发生的客观事实，不写排程/章节安排；依赖单向：大纲 → 设定，设定不反向引用大纲条目编号或卷号排程。"**
- 纯文档约束，零代码成本。

**理由**：v7 结构本已是这个方向，写死不变量可防止后续实现把排程内容混入角色卡/世界观，直接回应 freezero2020。

**实施要点**：spec 0.7 §1 不变量列表增补一条；§4.2 角色卡说明可补一句"不写章节排程"。

### R3: RFC 公开跟进（❌ 取消）

~~在 Discussion #118 发布跟进评论~~

**决定**：暂不发布 RFC 跟进评论，只完成文档更新和 git 提交。

理由：文档更新完成后可以根据实际情况再决定是否发布评论。

### R4: master README 更新（待执行）

在 master 分支 README 添加 v7 状态板块：

**内容要点**：
- v6.x 当前稳定版状态（维护模式，仅修 bug）
- v7 设计已定稿，实施进行中
- 链接到 v7 分支的 PRD、spec、实施计划
- 里程碑进度（后续定期更新）

### R5: v7 分支清理（待执行）

处理 v7 分支当前的 git 状态：
- 14 个 `.trellis/` 修改文件需要评估：是否与 v7 任务相关？是否应提交？
- 确保所有 v7 文档更新都提交到 v7 分支

## Acceptance Criteria

- [ ] A1/A2/A3 三个决策问题都有明确方案并记录在案
- [ ] 相关文档已根据决策更新，无遗留"待定"或冲突描述
- [ ] Discussion #118 已发布跟进评论，说明反馈采纳情况
- [ ] v7 → master PR 已准备好或已提交
- [ ] 所有更新已提交到 v7 分支，git 状态干净

## Out of Scope

- v7.0 的实际实施工作（编写代码）— 这只是设计收尾和文档准备
- 7.x backlog 功能的设计细节（文风对齐、语义召回等）
- 已在报告中标记为"需要澄清"但不阻塞 v7.0 的 spec 边界问题（B1-B4）— 可以作为文档微调处理

## Confirmed Facts from Codebase

- RFC 征集期已在 2026-06-12 开始（Discussion #118），原计划 ~06-19 收口（已过期）
- v7 实施计划（`v7-implementation-plan.md`）已存在，状态为草案 0.1（2026-06-13）
- 实施计划定义了 7 个里程碑（M0-M7），RFC 收口是硬节点，收口后才能开始 M1 格式层代码
- 当前 v7 代码量为 0 行（`webnovel-writer/` 是冻结的 v6 遗产）
- 现有文档状态：
  - PRD 1.0 已定稿（2026-06-12）
  - story-repo-spec 0.6（按 PRD 1.0 修订）
  - multi-agent-adaptation-spec v3.2
  - 后端开发规范基线 1.0（`.trellis/spec/backend/`）
- 当前 git 状态：v7 分支有 14 个未提交文件（全部是 `.trellis/` 工作流系统更新）

## Technical Context

**A1 背景**：
- story-repo-spec 0.6 §8.1 描述自动模式"定稿+待定稿批次"叠加视图
- 当前 spec 未定义：批次内第 K 章打回后，K+1 到 N 章已依赖 K 的预登记事实时如何处理

**A2 背景**：
- spec 0.6 §2.2 要求 Node >= 22，使用内置 `node:sqlite` 实现零第三方依赖
- 反馈报告指出 `node:sqlite` 在早期 Node 22 需要 `--experimental-sqlite` flag
- Node v22.13.0+ 才不需要 flag，但模块仍为 release candidate 状态

**A3 背景**：
- spec 0.6 §5 定义三类线索条目（伏笔/悬念/感情线），每条有履历字段记录证据
- spec 要求 cache rebuilder 作为格式参考实现，三审负责校验证据真实性
- 当前 spec 未定义履历证据的结构化格式（如"见本章结尾对峙段"无法脚本验证）

## Decisions Summary

所有核心决策已完成，无阻塞性开放问题。

1. **A1 决策结果**：采用方案 2（版本链叠加）✓
   - 理由：符合实际写作情况，批次内章节需要连续性（新角色、伏笔在前章出现，后章继续发展）
   - 实现要点：
     - 支持批次内依赖，第 K+1 章可以使用第 K 章的预登记事实
     - 当第 K 章被打回时，标记 K+1 到 N 章为"受影响"，需重新审核或重写
     - 需要设计污染传播机制和作者确认流程（整批重写 vs 逐章确认）
   
2. **A2 决策结果**：Node >= 22.13.0 + 提示升级（无降级方案）✓
   - 版本要求：Node >= 22.13.0（`node:sqlite` 无需 flag 的最低版本）
   - 降级方案：不实现文件缓存降级，版本不足时给出清晰的升级指引
   - 理由：
     - Node 22.13.0 发布已 1.5 年，LTS 用户自然更新已覆盖
     - v7 是全新重写，可以设定更高的技术门槛
     - 保持"零第三方依赖"和单一缓存实现的简洁性
     - 本地测试确认 Node 24.15.0 中 `node:sqlite` 可用
   - 实现要点：安装器检测 Node 版本，< 22.13.0 时给出人话升级指引

3. **A3 决策结果**：章节级别锚点 + 自然语言描述 ✓
   - 格式：`第152章：主角在北境对峙时首次察觉真相`（保持现状）
   - 验证范围：
     - 重建器：只验证章节文件存在（脚本能做的）
     - 三审：读取整章验证语义（AI 能做的）
   - 理由：
     - 网文章节长度 2000-3000 字，全文读取压力可接受
     - 避免段落编号维护的复杂性和易错性
     - 符合 PRD 原则"脚本能做的归脚本，做不到的归 AI 语义判断"
     - 作者手改正文后不会破坏锚点引用
   - 实现要点：spec 需明确"履历证据的章节引用由重建器验证存在性，语义正确性由三审负责"

4. **合并时机决策**：暂不合并，master 保持 v6 稳定 ✓
   - 做法：
     - master 分支继续维护 v6（bug 修复）
     - master README 更新 v7 重要进度说明（设计状态、里程碑进展）
     - v7 分支独立开发，直到确认 v7 可以替代 v6
     - 最终合并时机：v7.0 beta 测试通过，确认可替代 v6 后一次性合并
   - 理由：
     - 避免 master 长期处于"设计已公开但不可用"状态
     - v6 用户不受 v7 开发影响，保持稳定性
     - v7 有独立分支可以自由迭代，不受 master 约束
   - 实现要点：
     - 在 master README 添加 v7 状态板块（链接到 v7 分支的 PRD/实施计划）
     - 定期（每个里程碑完成时）更新 master README 的 v7 进度说明