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~Q4 已全部收口，2026-06-12。结论见 Decision 各条：Q0→术语/账本/机制系列，Q1→范围-1，Q2→旅程-1，Q3→发布-1，Q4→流程-1。）

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；操作动词埋下/推进/回收/放弃（"埋伏笔""回收伏笔"为圈内最高频原生短语）；「节奏债」改为"悬了太久"预警。~~悬念/感情线/立旗/爽点铺垫统一登记为伏笔~~（2026-06-12 修订：大一统外延被作者推翻——承诺是承诺，伏笔是伏笔，爽点/钩子是 v6 已有的独立体系，见账本-1）。
Consequences: 目录 大纲/承诺/ → 大纲/伏笔/；commit 协议前缀不变（机器域）。

账本-1：账本拆分——统一引擎、分类型目录（2026-06-12，修正术语-1 的大一统外延）

Context: 作者指出「伏笔」吞掉悬念/感情线/爽点是和「承诺」大一统同一个错误。查 v6 资料证实：爽点根本不是账本条目——追读力分类（危机钩/悬念钩/渴望钩/情绪钩/选择钩）、爽点与节奏.csv（压抑爆发/微反转补刀/黄金三章等几十种，按题材有偏好和毒点）是指导每章怎么写的知识体系，不是能登记"铺垫→兑现"的流水账。
Decision（三层各归各位）:
- 账本层（有生命周期的才进账本，引擎一套共用：每条一文件、"悬了太久"预警、定稿结转；机器内部状态同构 open/advance/resolve/drop）：大纲/伏笔/（埋下→回收）、大纲/悬念/（设下→揭晓）、大纲/感情线/（开启→推进→修成正果/无疾而终）。冲突、立旗不设类（冲突每章都有不是条目；立旗是黑话直译，可归悬念或爽点知识）。
- 知识层：v6 references 体系（追读力分类、爽点与节奏 CSV、题材模板）平移继承，喂给细纲（按题材推荐本章钩子类型/情绪定位/爽点节拍）和三审读者审。
- 每章属性（章 front matter）：本章钩子类型与强弱、情绪定位（压抑/铺垫/小爽/大爽/转折）——单章的事不进账本。
- "装逼打脸蓄积了多少章"（原"爽点库存"）= 信息差的派生报表，不需要独立机制。
同步拍板（2026-06-12，作者确认）：plot_threads（剧情线）不进账本、并入卷纲正文（主线支线推进本来就是总纲/卷纲内容，再开一类账=重复记账）；v6→v7 迁移映射 foreshadowing→伏笔、plot_threads→并入卷纲、chase_debt/reading_power→知识层与章属性；"悬了太久"阈值分类型默认（感情线宽如 30 章、悬念/伏笔紧如 10 章量级，具体数值 spec 定）。

术语-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）。

术语-3：条目编号用全称（2026-06-12，作者拍板，消解 O6）

Decision: 编号前缀不压缩，用全称：伏笔-031、悬念-008、感情线-012、信息差-021（原 P-031/S-021 与单字前缀方案废止）。理由：减少作者心智压力，与命名原则④（不过度压缩）一致。commit 前缀（ch/vol/retcon/fix）等机器协议不变。
Consequences: spec §2"条目编号保留 ASCII"条款废止；文件名、履历、对话引用全部用全称编号。

机制-6：自动模式不直接定稿，按批次定稿（2026-06-12，作者拍板，消解 O7）

Context: spec 0.5 §8.1 的"自动验收过线即 settle"让错误能不经人眼溜进定稿区，且攒批审稿单会被定稿清空工作区（O7 设计洞）。
Decision:
- 入宪：定稿永远需要作者敲定，系统没有任何不经作者确认就写入定稿区的路径。"自动验收"开关删除。
- 自动模式与手动模式的差异只是确认粒度：手动逐章审、逐章定稿；自动模式攒一个批次（默认与连写体检周期一致 8 章，可配）批量审稿、作者敲定后逐章按序定稿（原子性按章保留）。
- 连写中草稿与预入账数据攒在工作区不定稿；写后续章的材料组装支持"定稿 + 待定稿批次"叠加视图（脚本提供）。
Consequences: spec §8.1 重写；O7 消解（待审材料不再跨定稿存在）；错误最多污染一个批次且未定稿可直接改；机制-3 的"已发布后发现错误→顺势圆"路径保留，"自动验收溜进定稿"场景消失。

安装-2：工作目录书目录登记（jsonl）+ hook 注入，支持多本书切换（2026-06-12，作者提出并修订，消解 O3）

Decision（修订：原"单行指针文件"升级为书目录登记）:
- 工作目录放一个 jsonl 登记文件（候选 .webnovel/books.jsonl，机器域），每行一本书：书名/目录/是否当前在写/最后打开时间。脚本由它解析"当前书"与全部书单。
- SessionStart hook 注入上下文（Claude Code）：会话启动时自动注入"当前在写哪本、工作目录共几本书、全书近况入口"。无 hook 宿主由状态机入口启动时读同一文件，行为等价（多宿主 spec §5.5 原则）。
- 切换书 = 作者一句话（"换到《另一本》"），AI 改登记文件（对话即编辑器）；作者不需要手编 jsonl。
启动点规则（修订 2，2026-06-12，作者指正）: 只支持从工作目录启动——各宿主只在启动目录自动加载 skills/配置（.claude/、.codex/ 都住工作目录），在书目录启动插件根本不会加载，原"所在书目录优先"规则不可达，废止；安装-1 配套①"从书目录向上定位工作目录"一并废止。当前书一律由登记文件决定。脚本启动时校验当前目录含 .webnovel/，否则人话提示"请从工作目录启动"。
优先级规则: ~~启动位置已在某书目录内（向上定位命中）→ 以所在书为准~~（废止，见启动点规则）；登记文件缺失/损坏 → 扫描工作目录下含 book.yaml 的子目录重建书单（书单是可重建派生物），"当前在写"标记请作者选一次。
Consequences: 工作目录布局图与两份 spec 的安装/hook 章节加该文件；同时写两本按"一书一会话"自然成立。

安装-3：书仓库根部放指路 AGENTS.md（2026-06-12，作者确认，消解 O1）

Context: 限制工作目录启动后，误在书目录启动 AI 工具会一片寂静（什么都不加载）；单独 clone 书仓库同理。
Decision: 书仓库根部放 AGENTS.md（建书/迁移时自动生成），内容一段中文："这是 webnovel-writer 管理的小说仓库，请回上一层工作目录启动 AI 工具；若单独 clone 了本仓库，运行 npx webnovel-writer init 重建工作目录。"选 AGENTS.md 而非自造中文文件名，因为误启动场景里能救场的是 AI 工具会自动读的文件（30+ 工具认的开放标准）。
Consequences: "书仓库零工程文件"原则收一个显式例外（仅此一个文件）；目录图与 spec §2 更新。

范围-2：按需静态 HTML 简报保留，归 7.x（2026-06-12，作者反问拍板）

Context: Claude 曾建议砍掉 Dashboard 残余；作者反问"不用 HTML 渲染简报，全书近况的表达方式适合人类读吗"——成立。
Decision: 全书近况与简报分工：全书近况是对话内 5-8 行文本，管"此刻决策"；浏览级信息（账本全貌、体检统计/情绪波形、时间线翻阅、卷复盘材料）归按需静态简报——零 token Node 脚本读 .cache/源文件，渲染单文件 HTML（内联样式、无外链、无服务器），作者一句"给我看全书简报"即生成。即 spec 0.5 §13 原案"Dashboard 改为按需静态简报"的落实。
版本: 7.x（简报内容尚未设计，按切线原则不进 7.0）。

流程-2：不做术语禁用词 CI 检查（2026-06-12，作者拍板）

Claude 曾建议把"作者界面禁用词清单"做成 CI 检查防术语回潮；作者裁决不做——术语一致性靠自审与评审把关，避免误杀与维护负担。

旅程-1：主旅程定为新书作者（2026-06-12，作者拍板，Q2）

Context: 三条作者旅程（新书 / v6 迁移 / 连写党）都要完整覆盖，但需一条主旅程定 PRD 叙事主线、7.0 打磨深度排序与发布判据权重。
Decision: 新书作者优先。零基础新书旅程（npx 安装→建书→写第一章）是产品定义本身；v6 迁移作者排第二，连写党作为日常写作的一种模式（§8.1 开关）而非独立门面。
Consequences: PRD 叙事主线按"一个没用过的作者从零到稳定日更"展开；迁移章节独立成节但不绑架主叙事；自动模式在"日常写作"内作为进阶小节出现。

发布-1：三阶段发布判据（2026-06-12，作者确认，Q3）

发 RFC：PRD 定稿 + 术语表/目录图/三条作者旅程齐 → 征求意见至少开放 1 周。
beta：用 v7 真实写一本书到 50 章（自用验证）+ Windows 中文路径全链路 CI 绿 + "删光 .cache 全量重建" CI 绿。
7.0.0：/migrate 在 ≥3 个真实 v6 项目跑通 + beta 期无数据丢失级 bug + 迁移指引文档齐。

流程-1：PRD 落点与 RFC 渠道（2026-06-12，作者拍板，Q4）

PRD 落盘 docs/architecture/v7-prd.md，PR 进 v7 分支。
RFC 是 PRD 的大白话裁剪版，发 GitHub Discussions（需先给仓库开启 Discussions），按"issue 回复用大白话、面向写小说的用户"的口径撰写；可在 issue 区发一条置顶指引链接过去。

原则-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），研究全部内联

prd.md 22 KB Permalink Histórico Raw