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