webnovel-writer/.trellis/tasks/06-11-v7-prd-webnovel-writer/prd.md

v7 完整 PRD：webnovel-writer 重构

状态：brainstorm 草稿（持续更新中） 最终交付物：docs/architecture/v7-prd.md（完整产品需求文档） 上游文档：story-repo-spec 0.5（格式法律文本）、multi-agent-adaptation-spec v3.1（多宿主）、v7-design-discussion-notes（设计纪要）、story-repo-spec-feedback（差异意见，已吸收）

Goal

为 v7 重构写一份完整 PRD——从头重新设计，spec 0.5 的既有决策也在重审范围内（作者 2026-06-11 决定：感觉 spec 仍有设计问题，0.5 的"冻结"解除，PRD 先行、spec 随 PRD 修订）。PRD 是 RFC 的母本，也是实施计划和 spec 下一版的输入。

What I already know（spec 0.5 / 纪要的现有结论——降级为"候选设计"，可被 PRD 推翻）

• 定位：长篇网文创作插件，200 万字级别，开源给非工程师写手，全中文化，Windows 中文编码优先。
• 架构已定（spec 0.5）：一书一 git 仓库；定稿/大纲/文风/工作区四区；承诺系统是心脏；章事务八阶段+settle 原子 commit；盘面状态机单入口；决策卡是作者唯一界面；.cache/index.db 唯一派生物。
• 运行时已定：Node 零依赖脚本；无 Python/pip/.env/DB/RAG。
• 自动模式已入规（§8.1）：自动拍板/自动验收两开关，体检加密 8 章，三停止条件。
• 多宿主已定（v3.1）：SKILL.md 开放标准零适配；角色单源生成三平台壳；hook 语义 ask 不 deny；npx 安装器；support.md+registry 分级（一级 Claude Code+Codex）。
• 迁移已定：spec §12 有 v6→v7 完整映射表，/migrate 一次性脚本。
• 问题空间 16 项已盘（纪要 §4）：优先级分层——1/2/5/7/14（客观事实记账/时间线/摘要分层/改稿三档/控制点滑杆）进骨架；3/8/9/11（信息差/反和解/桥段冷却/文风锚定）是差异化卖点；4/10/12（人设语气/情绪节奏/口癖）体检类后置。
• 诚实边界：承诺"读者不出戏"，不承诺过 AI 检测器；合规/敏感词不进 v1。
• 流程已定：先发 RFC 让用户拍砖，v7 新 major，v6 留 master 只修致命 bug。
• Trellis 调研结论（2026-06-11）：模板上下文+条件块编译降级路径；AGENTS.md 公约数层；update 哈希追踪——可吸收进多宿主实现。

Assumptions (temporary)

• PRD 面向两类读者：开发实施者（含 AI）+ issue 区用户（RFC 改写母本），中文撰写。
• 章节结构假设：背景与目标 / 用户画像与作者旅程 / 功能需求（按问题空间映射）/ 非功能需求 / 范围切分 / 发布判据 / 风险与开放问题。

Open Questions

• [Q0] 作者感觉到的设计问题是什么（当前问题，blocking）
• [Q1] v7.0 MVP 范围切分（暂缓，待 Q0 后重排）
• [Q2] 作者旅程优先级（新书作者 / v6 迁移作者 / 连写党）
• [Q3] 发布判据（RFC→beta→7.0.0 各阶段过线标准）
• [Q4] PRD 最终落点与 RFC 的关系

Requirements (evolving)

• PRD 必须完整覆盖问题空间 16 项的产品化映射（每项：解法、所属版本、验收方式）。
• PRD 从产品视角重审 spec 0.5 全部设计；确认保留的引用章节号，推翻的记入 ADR-lite。
• 术语全面重审（Q0 第一项发现，作者提出）：spec 0.5 大量名词有机翻感/行业黑话感（结转=会计、盘面=炒股、棘轮=机械、事务=数据库、镜头评审=lens 直译、retcon=英文）。PRD 附完整术语表，spec 随之修订。
• 命名原则（作者裁决）：①网文圈原生词优先（伏笔/吃书/钩子/审稿）；②圈内没有的用自然大白话；③财务/工程/数据库隐喻禁止出现在作者界面；④不自造两字精简词——宁可用自然的长短语，不要为了"术语感"硬压缩（作者反馈：「你很喜欢精简词」，案头/入册这类生造压缩词也属此列）。

Decision (ADR-lite)

术语-1：统一概念「承诺」改为「伏笔」（2026-06-11，作者拍板）

• Context: 「承诺」是 promise 直译，生硬；候选「坑」在圈内指整本书（挖坑=开新书、弃坑=断更），指单条线索会撞车。
• Decision: 采用方案 A「伏笔」：编号 伏-031；操作动词 埋下/推进/回收/放弃（"埋伏笔""回收伏笔"为圈内最高频原生短语）；「节奏债」改为"悬了太久"预警。悬念/感情线/立旗/爽点铺垫统一登记为伏笔，外延在 spec 内部定义清楚。
• Consequences: 目录 大纲/承诺/ → 大纲/伏笔/；commit 协议前缀不变（机器域）。

术语-2：全套术语表（2026-06-11，作者逐项裁决）

• Context: 命名四原则确立后，对 spec 0.5 全部作者可见术语重审。
• Decision: | spec 0.5 | v7 定名 | |---|---| | 承诺（P-031）| 伏笔（伏-031），埋下/推进/回收/放弃 | | 节奏债 | "悬了太久"预警 | | retcon 事务 | 吃书（吃书-87，commit 前缀仍 retcon）| | settle / 结转 | 定稿（动词，与 定稿/ 目录一致）| | 章事务 | 写章流程 | | 盘面 | 全书近况 | | 上下文包 | 本章写作材料 | | 合同 | 本章要写到的事 | | 镜头评审 | 三审（读者审/编辑审/设定校对，出版业原生）| | 棘轮 | 删除该比喻，直接说"定稿前/定稿后" | | 风格宪法 | 文风铁律 | | 决策卡 | 取消"卡"概念：环节叫"确认细纲"，文件 工作区/细纲.md | | 验收（卡）| 审稿，文件 工作区/审稿.md | | 修复卡 | 修复确认（同理去掉"卡"）| | 信息差/时间线/名册/金句库/体检/钩子/强弱钩 | 保留（原生或大白话）|
• Consequences: "卡"隐喻整体退场，每个环节用作者动作命名；spec 0.5 全文术语改写（§5、§7、§8、§10 重点）；机器协议（commit 前缀、book.yaml、编号格式）不动。「细纲」与传统细纲心智完全对齐：AI 拟细纲→作者点头或改。

安装-1：工作目录嵌套 + 强制项目级 + npx 单渠道（2026-06-11，作者拍板）

• Context: spec 0.5 只定义书仓库内容，没定义插件装到哪。v6 安装类 issue（#90/#103/#69）一半根源是用户级/项目级并存的歧义；插件市场渠道本身体验也不好（作者原话）。
• Decision:
  • 沿用 v6 的嵌套：工作目录 ⊃ 书目录。工程文件（.claude/、.codex/、.webnovel/ 脚本与角色定义、AGENTS.md）全部住工作目录；书仓库（独立 git repo）里零工程文件，可多本书共用一套安装。
  • 强制安装到工作目录（项目级），不再支持用户级安装——所有用户目录结构一字不差，可诊断性优先于灵活性。
  • 分发只走 npx（npx webnovel-writer init / update）：Claude Code 插件市场渠道放弃，市场版停在 v6 并指引 v7 新装法。
  • 配套：①脚本支持从书目录向上定位工作目录（定位规则进 spec）；②update 用 Trellis 式哈希追踪（没改过的直接更新，改过的提示）；③工作目录本身不是 git 仓库。
• Consequences: 多宿主 spec 的安装器章节重写；v6→v7 迁移要处理"市场版插件卸载+npx 重装"的引导；14 种宿主的安装拉平为同一张目录图。

格式-1：正文保留 front matter + 干净导出脚本（2026-06-11，作者拍板）

• Context: 章节文件头部的结构化档案（章号/视角/书内时间/本章要写到的事/伏笔结转）与"作者界面无机器味"的原则冲突。
• Decision: 保留完整 front matter（文件自包含、审计不依赖外部表的优势成立）；新增导出命令：一键导出去掉 front matter 的干净正文（单章/范围/全书），作者发布到平台（起点/番茄）本来就需要纯文本，一个脚本同时解决两件事。
• Consequences: 导出是零 token Node 脚本；导出目录默认 工作区/导出/（不进 git）；spec §4.1 补充导出命令。

格式-2：定稿/记忆/ 改名 定稿/摘要/（2026-06-11）

• "记忆"是 AI 视角词，作者视角就是章摘要/卷摘要。机制不变。

技术-1：要求 Node ≥ 22（2026-06-11，作者拍板）

• 用内置 node:sqlite 实现 .cache/index.db，零依赖承诺保住；安装器检测 Node 版本，不足时人话提示升级。

机制-1：机检与三审职责重划（2026-06-11，作者确认，对抗性审查 #1+#3）

• 原则（作者强调，入宪）：脚本能做的归脚本，做不到的归 AI 语义判断，一定要分清楚；禁止用正则硬凑语义判断（一点用没有）。
• 机检只留可计数项：字数、禁词/禁句式、复读、高频意象、句式体检、新专名比对名册、front matter 格式、伏笔文件是否变动（只查形式）。
• 语义判断移给三审设定校对：①"本章要写到的事"逐条核对；②信息差关键词命中的真泄密判断（机检只出候选清单，不拦截）。

机制-2：伏笔门检改声明制（2026-06-11，作者确认，对抗性审查 #2）

• 细纲声明本章定位（推进/过渡/日常），过渡章合法，消除模型撒谎动机。
• 伏笔履历行必须引用章内证据，设定校对核对。
• 自动模式连续 3 章（可配）无伏笔变动触发停止；体检统计伏笔活跃率。
• 态度（作者定调）："悬了太久"是提醒不是错误，有些伏笔收不了可以接受——大神作家也有一堆填不上的坑。系统不逼作者填所有坑。

机制-3：自动模式的错误连锁处理（2026-06-11，对抗性审查 #5）

• 攒批审稿与体检周期对齐（默认 8 章），建议存稿期完成补审。
• 已发布后发现错误：影响分析脚本列出受影响章节 → 吃书（未发布部分）或顺势圆（已发布，主路径）。
• 新增人话命令"回到第 N 章"（git 回滚的包装）。

机制-4：git 隐身铁律（2026-06-11，作者确认，对抗性审查 #6）

• 入宪不变量：作者永远不需要亲手敲 git 命令——真需要 git 操作时，由 AI 代为运行；任何 git 异常都有人话修复流程。
• 状态机第 0 步前加 git 健康检查（半提交/冲突/锁文件/.git 损坏），每种配自动修复或人话指引；检测网盘冲突副本并人话警告。

格式-3：时间线按卷拆分（2026-06-11，作者确认，对抗性审查 #7）

• 定稿/设定/时间线/第NN卷.md；写作材料默认只带当前卷+上一卷；跨卷查询走 .cache。

机制-5：金句库收割改保守 + 对话触发（2026-06-11，作者确认+补充，对抗性审查 #8）

• 自动判定只产生候选（作者改写且字数相近；净删减不算）。
• 新增触发（作者提出）：作者在对话中夸某段（"那儿写得不错"之类）也触发收割候选。
• 最终入库一律经作者审核（审稿时顺手勾选），品味决策不交给阈值。

范围-1：v7.0 MVP 切分（2026-06-11，作者拍板）

• 切线原则：已设计完且实现成本低的进 7.0；需要新设计或调参的体检类全部 7.x。
• v7.0：状态机单入口、写章流程八阶段（机检/三审新分工）、伏笔系统（声明制）、客观事实记账、时间线（按卷）、分层摘要、改稿三档、git 隐身全套、精准读取接口；自动模式（含"回到第 N 章"）、反和解规则、信息差登记（候选制）；npx 安装器、/migrate、干净导出、AGENTS.md；文风铁律 + 禁词/句式机检；金句库目录与手动放入（自动收割不进）。
• v7.x：金句库自动收割（含对话触发）、文风锚定、桥段冷却、语气盲测、情绪波形、口癖卡；多宿主二级平台（Gemini/Cursor）。
• 不做：RAG/向量库、常驻服务、敏感词、AI 检测器承诺。
• 7.0 宿主范围：一级（Claude Code + Codex）。

原则-1：精准读取，非必要不全文读（2026-06-11，作者提出）

• 所有数据文件的读取都应有"精准读到所需一段"的命令：按章号/编号/小节定位提取（如"读伏-031 的履历""读第 5 卷卷纲的高潮节点""读 0152 章结尾 500 字"），由脚本提供。
• AI 非必要不整文件读取——包括参考资料、大纲、设定。这是 v6 token 失控病根（#58/#92/#106）的根治手段之一，与"分层摘要+Grep 正文"配套。
• Consequences: 每类文件的 spec 定义都要附"定位读取"的脚本接口；.cache/index.db 的表设计要支撑这些查询；写作材料组装默认用精准片段。

Acceptance Criteria (evolving)

• 三条作者旅程完整（安装→建书/迁移→日常写作→卷复盘）
• 16 项问题空间每项有归属（v7.0 / v7.x / 不做）
• 发布判据可执行（每阶段有可验证的过线条件）
• RFC 可从 PRD 直接裁剪产出

Definition of Done

• PRD 经作者（仓库 owner）逐节确认
• 落盘 docs/architecture/v7-prd.md，PR 进 v7 分支
• docs/README.md 索引更新

Out of Scope (explicit)

• 不含实施计划（PRD 确认后另立任务）
• 合规/敏感词、AI 检测器承诺

Technical Notes

• 素材：docs/architecture/ 四份文档；v6 issue 区（#58-#106 已在纪要盘点）
• 子代理不可用（API 429），研究全部内联