webnovel-writer/.trellis/tasks/06-26-rfc-followup/prd.md

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 进度说明