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