# webnovel-writer v7 产品需求文档（PRD）

> 状态：1.0（作者逐项确认，2026-06-12 定稿）
> 日期：2026-06-12
> 读者：①开发实施者（含 AI）；②issue 区用户（RFC 母本，裁剪时换大白话）
> 地位：本 PRD 是 v7 的产品法律文本。spec 0.5 的"冻结"已解除——本 PRD 先行，`story-repo-spec` 与 `multi-agent-adaptation-spec` 随本文档修订（修订指令见 §10）。
> 上游：story-repo-spec 0.5、multi-agent-adaptation-spec v3.1、v7-design-discussion-notes、v6 issue 区（#58–#113）
> 决策过程：`.trellis/tasks/06-11-v7-prd-webnovel-writer/prd.md`（20 条 ADR）

---

## 1. 背景与目标

### 1.1 一句话

为中文网文作者做一个**开箱即用、全程中文、200 万字不崩**的 AI 长篇创作系统：一本书是一个 git 仓库，AI 负责写和审，脚本负责数和记，作者只做三件事——确认细纲、审稿、拍创作决策。

### 1.2 为什么推翻 v6 重来

v6 的病根（issue 与代码互证）：

| 病根 | 证据 |
|---|---|
| 用 prompt 驱动确定性状态机，模型不遵守 | #91、#66、#87/#76；385 行写章流程规范 |
| 派生状态（SQLite/投影）与作者手改冲突，无解 | #100、#77、#63、#67、#70、#71、#89 |
| Token/时间消耗失控（每章 3 subagent + 4 份 JSON + 多道 gate） | #58、#92、#106 |
| 安装门槛高（Python 依赖 + .env + RAG key） | #90、#103、#69 |
| 禁词表治不了 AI 味 | #94 |
| 连写缺失/质量漂移 | #79、#95、#74 |

**核心教训：v6 信任流程、不信任模型和作者；v7 信任 markdown 和作者，把流程压到最薄。**

### 1.3 继承与归零

- **继承**：仓库/star/用户群/issue 区；37 个题材模板；追读力分类与爽点节奏知识库；审查维度；踩坑记录。
- **归零**：Story System、SQLite 双库、RAG、Python runtime、8 个命令、Dashboard 常驻服务。
- v6 留 master 分支只修致命 bug；v7 新 major + `/migrate` 一次性迁移。

### 1.4 产品原则（宪法级）

1. **文件即真相**：作者面对的一切状态都是中文 Markdown，可手改、可 git diff。系统检测手改并提议入账，永不报错拒绝。
2. **脚本能做的归脚本，做不到的归 AI 语义判断——一定要分清楚**。禁止用正则硬凑语义判断（一点用没有）；能数的不让模型估，能模型判的不打扰作者。
3. **git 隐身铁律**：作者永远不需要亲手敲 git 命令——真需要 git 操作时由 AI 代为运行；任何 git 异常都有人话修复流程。
4. **可靠性来自自愈，不来自门禁**：宁停勿崩；hook 语义是 ask 不是 deny（#113 教训）。
5. **精准读取，非必要不全文读**：所有数据文件都有"精准读到所需一段"的脚本命令；AI 默认读片段，不整文件读取（v6 token 失控的根治手段）。
6. **作者界面零机器味**：术语全部用网文圈原生词或大白话（§8 术语表）；财务/工程/数据库隐喻和自造精简词禁止出现在作者界面。
7. **品味决策归人**：**定稿永远由作者敲定（没有"自动定稿"）**；金句入库、文风规则入铁律，一律作者审核，不交给阈值或模型。

---

## 2. 用户画像与作者旅程

用户是**中文网文作者，非工程师**，Windows 为主力环境，目标体量 200 万字。三条旅程全部支持，**主旅程是新书作者**——它是产品定义本身；迁移作者第二；连写党是日常写作的一种模式而非独立门面。

### 2.1 主旅程：新书作者（从零到稳定日更）

```text
① 安装        npx webnovel-writer init
              （检测 Node ≥22 与已装的 AI 工具，生成工作目录；缺 Node 时人话提示升级）
② 建书        打开 AI 工具说"开始写书"→ 引导式问答生成 book.yaml、总纲、第一卷卷纲
③ 写第一章    确认细纲（AI 拟，作者点头或改）→ AI 写稿 → 机检 → 三审 → 审稿 → 定稿
④ 日常        每次打开，AI 先报全书近况（写到哪、哪些伏笔悬了太久、连续几章钩子弱）
              → 继续写下一章，或说"改第 N 章""把这条感情线收了"
⑤ 卷末        卷复盘：伏笔清账、卷摘要、与作者对谈定下卷卷纲、伏笔机会扫描
⑥ 发布        一键导出干净正文（单章/范围/全书，去 front matter），贴到起点/番茄
```

体验底线：全程看不到 git、看不到报错堆栈、看不到英文术语；目录里只有 定稿/大纲/文风/工作区 四个中文文件夹。

### 2.2 旅程二：v6 迁移作者

```text
① 引导        市场版插件页面与 README 指引：v7 换了安装方式 → 卸载市场版 → npx 安装
② 迁移        在工作目录说"迁移我的书"→ /migrate 一次性脚本（映射表见 §10.3）
③ 校对        迁移报告人话列出：迁了什么、哪些条目标了"迁移待校对"、建议先看哪
④ 继续写作    进入主旅程 ④
```

体验底线：迁移不丢任何一个字；v6 的伏笔/剧情线/追读账本全部有去处；失败可整体回退。

### 2.3 旅程三：连写党（自动模式）

```text
① 前提        当前卷卷纲已确认（自动模式的控制边界——全自动 ≠ 无控制，是控制上移到大纲层）
② 开关        自动确认细纲 + 连写批次大小（默认与体检周期一致 8 章；开关中文名 spec 定稿时敲定）
③ 挂机        连写一个批次：草稿与预入账数据攒在工作区，**不定稿**；
              写后续章的材料从"定稿 + 待定稿批次"叠加组装（脚本提供）
④ 停止        批次写满 / 体检不过线 / 卷纲耗尽（绝不让模型裸奔编纲）
              + 连续 3 章（可配）无账本变动也停
⑤ 批量审稿    作者过一遍攒下的审稿单：整批接受 / 改某几章 / 从某章起打回重写
              （批内错误未定稿，直接改，影响最多波及一个批次）
⑥ 批量定稿    作者敲定后逐章按序定稿（原子性按章保留）→ 继续下一批次
              整批不要 → "回到第 N 章"（git 回滚的人话包装）
              已发布后才发现错误 → 影响分析 → 顺势圆（向后兼容；已发布不可改是铁律）
```

**定稿永远需要作者敲定——系统没有任何不经作者确认就写入定稿区的路径**（宪法级）。自动模式与手动模式的差异只是确认粒度：逐章 vs 按批次。

---

## 3. 系统形态

### 3.1 安装布局：工作目录 ⊃ 书目录

```text
工作目录/                      ← AI 工具在这里启动；本身不是 git 仓库
├── AGENTS.md                  # 公约数层：没装插件的 AI 也能看懂这里是什么、入口在哪
├── .claude/  .codex/ …        # 各平台壳（按检测到的环境生成）
├── .webnovel/                 # 插件本体：Node 脚本、角色定义、版本与模板哈希清单
│   └── books.jsonl            # ★ 书目录登记：每行一本书（书名/目录/是否当前在写/最后打开）
├── 我的第一本书/               # 书仓库（独立 git 仓库）
└── 我的第二本书/               # 多本书共用一套安装
```

- **强制安装到工作目录（项目级），不支持用户级**——所有用户目录结构一字不差，可诊断性优先于灵活性（v6 安装类 issue 半数根源是"装哪了/读的哪份"歧义）。
- **分发只走 npx**（`npx webnovel-writer init` / `update`）。Claude Code 插件市场渠道放弃，市场版停在 v6 并指引新装法。
- `update` 用模板哈希追踪：用户没改过的文件直接更新，改过的提示（Trellis 模式）。
- **当前书与书单由登记文件解析**（`.webnovel/books.jsonl`，机器域，每行一本书：书名/目录/是否当前在写/最后打开）：
  - **SessionStart hook 注入上下文**（Claude Code）：会话启动自动注入"当前在写哪本、共几本书、全书近况入口"；无 hook 宿主由状态机入口启动时读同一文件，行为等价——关键能力不得只存在于 hook 中。
  - 换书 = 一句话让 AI 改登记（对话即编辑器）；作者不需要手编 jsonl。
  - 自愈：登记文件缺失/损坏 → 扫描工作目录下含 book.yaml 的子目录**重建书单**（书单是可重建派生物），"当前在写"标记请作者选一次。
- **只支持从工作目录启动**：各宿主只在启动目录自动加载 skills/配置（`.claude/`、`.codex/` 都住工作目录），在书目录里启动插件根本不会加载。当前书一律由登记文件决定。脚本启动时校验当前目录含 `.webnovel/`，不是工作目录 → 人话提示"请从工作目录启动"。
- 运行时要求 **Node ≥ 22**（用内置 `node:sqlite` 实现缓存，零依赖承诺保住）；无 Python、无 pip、无 .env。

### 3.2 书仓库目录（spec 0.5 §2 修订版）

```text
<书名>/
├── .git/  .gitignore  book.yaml
├── AGENTS.md                   # ★ 指路文件（建书时自动生成）：误在书目录启动 AI 工具 /
│                               #   单独 clone 时，指引回工作目录或 npx 重建
├── 定稿/                       # ── 审稿通过后的一切，只进不改 ──
│   ├── 正文/0152-北境的雪.md    # 正文 + 章信息 front matter（自包含档案）
│   ├── 设定/
│   │   ├── 角色/林晚.md
│   │   ├── 信息差/信息差-021-灭门真凶.md
│   │   ├── 世界观.md
│   │   ├── 时间线/第05卷.md     # ★ 按卷拆分（原单文件）
│   │   └── 名册.md
│   └── 摘要/                   # ★ 原「记忆/」
│       ├── 章摘要/0152.md
│       └── 卷摘要/第05卷.md
├── 大纲/                       # ── 作者意图，随时可改 ──
│   ├── 总纲.md
│   ├── 卷纲/第05卷.md          # 主线支线的推进写在这里，不另记账
│   ├── 伏笔/伏笔-031-灭门真凶.md  # ★ 账本三类（原「承诺/」大一统拆分）
│   ├── 悬念/悬念-008-神秘老者身份.md
│   └── 感情线/感情线-012-林晚主线.md
├── 文风/
│   ├── 文风铁律.md             # ★ 原「风格宪法.md」；含反和解标准段
│   └── 金句库/战斗.md …
├── 工作区/                     # ── 没定稿的一切，默认不进 git ──
│   ├── 细纲.md                 # ★ 原「决策卡.md」：全书近况+本章提案+要写到的事+备选
│   ├── 本章写作材料.md          # ★ 原「上下文包.md」
│   ├── 草稿-A.md
│   ├── 审稿.md                 # ★ 原「验收卡」
│   ├── 评审报告/
│   └── 导出/                   # ★ 新增：干净正文导出落点（不进 git）
└── .cache/index.db             # 唯一派生物，删了能全量重建（CI 验收项）
```

书仓库里**零工程文件**——作者打开文件夹只看到书。唯一显式例外是指路 `AGENTS.md`：误在书目录启动 AI 工具或单独 clone 时，它是唯一会被 AI 自动读到的求生通道。

### 3.3 账本：三类，统一引擎

有"开启→推进→收尾"生命周期的才进账本；引擎一套共用（每条一个文件、平铺 front matter、履历、"悬了太久"预警、定稿时入账；机器内部状态同构 open/advance/resolve/drop）：

| 类型 | 编号 | 生命周期动词 | "悬了太久"默认阈值 |
|---|---|---|---|
| 伏笔 | 伏笔-031 | 埋下 → 推进 → 回收 / 放弃 | 紧（10 章量级） |
| 悬念 | 悬念-008 | 设下 → 推进 → 揭晓 / 放弃 | 紧（10 章量级） |
| 感情线 | 感情线-012 | 开启 → 推进 → 修成正果 / 无疾而终 | 宽（30 章量级） |

**条目编号一律用全称**（伏笔-031，不是 伏-031 或 P-031）——作者天天要念的编号必须是人话，不过度压缩；信息差同理（信息差-021）。

不进账本的（各归各位）：

- **爽点**：不是账本条目，是**知识层**——v6 的追读力分类（危机钩/悬念钩/渴望钩/情绪钩/选择钩）、爽点与节奏知识库（压抑爆发/微反转补刀/黄金三章等，按题材有偏好和毒点）、37 个题材模板**平移继承**，喂给细纲（按题材推荐本章钩子类型/情绪定位/爽点节拍）和三审读者审。
- **钩子、情绪定位**：每章属性，住章节 front matter（本章钩子类型与强弱、情绪定位：压抑/铺垫/小爽/大爽/转折）。
- **剧情线（主线/支线）**：推进本来就是总纲/卷纲正文内容，再开一类账=重复记账。
- **冲突、立旗**：不设类（冲突每章都有；立旗是黑话直译，归悬念或爽点知识）。
- **"装逼打脸蓄积了多少章"**：信息差的派生报表（数据源就是"谁还不知道主角的底牌"），不需要独立机制。

账本态度："悬了太久"是提醒不是错误，**有些伏笔收不了可以接受**——系统不逼作者填所有坑。

> 注：「账本」是开发侧词汇，仅用于本文档与 spec 内部指代这套机制；作者界面只出现 伏笔/悬念/感情线 三个具体名字，不出现"账本"二字。

### 3.4 写章流程（八阶段，spec 0.5 §8 修订版）

| # | 阶段 | 执行体 | 说明 |
|---|------|--------|------|
| 1 | 起草细纲 | 脚本读全书近况 + AI 拟 | 生成 `工作区/细纲.md`；**细纲声明本章定位（推进/过渡/日常）**——过渡章合法，消除模型撒谎动机（替代 0.5 的"每章必须动一条承诺"硬门检与豁免机制） |
| 2 | 确认细纲 | **作者** | 点头 / 改 / 选备选；自动模式可跳过 |
| 3 | 备料 | 脚本 | 组装 `工作区/本章写作材料.md`：全书近况+要写到的事+事实切片+信息差边界+近章结尾+反复读清单+文风锚点+反和解规则；**默认用精准片段**（当前卷+上一卷时间线、按编号取账本条目） |
| 4 | 写稿 | AI（干净上下文） | `工作区/草稿-*.md`；关键章 best-of-N |
| 5 | 机检 | 脚本，零 token | **只做可计数项**：字数、禁词/禁句式、复读、高频意象统计、句式体检（句长方差/段落分布/高频开头）、新专名比对名册、front matter 格式、账本文件是否变动（只查形式）、信息差关键词命中（**只出候选清单，不拦截**）。不过关打回第 4 步，不打扰作者 |
| 6 | 三审 | AI ×3（各自新鲜上下文） | 读者审（爽不爽/哪段想划走，用追读力知识库的标准）、编辑审（结构与商业性）、**设定校对**（语义判断在这里：①"本章要写到的事"逐条核对正文写没写到；②机检的泄密候选是不是真泄密；③账本履历引用的章内证据是否属实） |
| 7 | 审稿 | **作者** | `工作区/审稿.md` = 草稿 + 三句话审意见 + 待确认新人名 + 章摘要（扫一眼可改）。动作：接受 / 改完接受 / 打回。手动模式逐章审；自动模式按批次审（§2.3）。**定稿永远需要作者敲定，没有"自动定稿"** |
| 8 | 定稿 | 脚本，**原子** | 一次 git commit：正文进定稿、设定/时间线/名册更新、账本各条目写入履历、章摘要存入 `定稿/摘要/`、工作区清空。要么完成要么原样保留，没有中间态 |

写评分离：写稿与三审必须在不同上下文中进行；机检先于 AI 审。

### 3.5 单入口状态机（spec 0.5 §10 修订版）

系统启动按序判定，命中即停。**第 0 步之前加 git 健康检查**：半提交/冲突/锁文件/.git 损坏/网盘冲突副本（"xxx (1).md"），每种配自动修复或人话指引——作者永远不直面 git 报错。

| 序 | 条件 | 下一步 |
|----|------|--------|
| 0 | 任一源文件解析失败 | **修复确认**（原"修复卡"）：定位到行、AI 提议保留意图的修复、作者确认；全角标点结构性错误直接预修复只报不问。永不带堆栈崩溃 |
| 1 | 定稿/大纲有未入账手改 | 提议补登（系统适应作者，不报错） |
| 2 | 工作区有未完成流程 | 从中断的阶段继续 |
| 3 | 刚定稿的章是卷末章 | 卷复盘 |
| 4 | 章号到达体检周期 | 体检 |
| 5 | 其余 | 起草新章细纲 |

v6 的 8 个命令全部内化为以上状态；作者只需要一个入口和"继续"。

### 3.6 精准读取接口（新增，宪法级原则的落地）

每类数据文件的 spec 定义都附带"定位读取"脚本接口，例如：

- 读伏笔-031 的履历 / 读感情线-012 的当前状态
- 读第 5 卷卷纲的高潮节点 / 读总纲的结局承诺段
- 读 0152 章结尾 500 字 / 读第 148–152 章的章摘要
- 查"玄阶令牌"在全书的出现章（Grep 正文，正文本身就是无损数据库）

`.cache/index.db` 的表设计必须支撑这些查询；写作材料组装默认用精准片段。

---

## 4. 功能需求：问题空间 16 项的产品化映射

| # | 问题 | 解法 | 版本 | 验收方式 |
|---|---|---|---|---|
| 1 | 客观事实吃书（修为/资产/物品） | 角色卡结构化字段增量记账，定稿时脚本更新 | 7.0 | 改 100 章前的设定，影响分析能列全受影响章 |
| 2 | 时间线混乱 | 每章强制时间锚点；时间线按卷拆分，append-only | 7.0 | 从第 1 章起强制；体检报告时间线孤儿为零 |
| 3 | 信息差泄密 | 登记表（每条一文件：知情人/读者已知/关键词）+ 机检出候选 + 设定校对判真伪；写作材料注入出场人物知识边界 | 7.0 | 构造泄密样章，三审能逮住；误报不拦截流程 |
| 4 | 人设语气漂移 | 角色卡存典型对话原文 few-shot + 周期语气体检 + 遮名盲测 | 7.x（体检后置） | 盲测准确率报告 |
| 5 | 摘要信息损耗 | 分层摘要（章≤200字/卷≤500字/全书骨架按需拼接、不落盘）+ Grep 正文管细节 + 账本即"人工标注的未来相关性" | 7.0 | 写第 0153 章时，写作材料能召回第 12 章埋下、第 152 章推进的伏笔 |
| 6 | 大纲漂移 | 偏离是决策点不是 bug：细纲阶段给"拉回/改纲/进灵感池"三选 | 7.0 | 细纲模板含偏离报告段 |
| 7 | 改稿三档 | 未发布：直接改+自动重入账；已发布：只读，生成"顺势圆"方案；设定/大纲：影响分析出已发布/未发布两清单 | 7.0 | 三档各有端到端用例 |
| 8 | AI 和解倾向毒害爽文 | 反和解规则入文风铁律标准段，随写作材料前置注入，按题材配浓度 | 7.0 | 题材模板含反和解预设；样章对比可感 |
| 9 | 桥段循环 | 高频意象统计（零 token 脚本，7.0）+ 桥段使用史"冷却中"清单（7.x） | 7.0/7.x | "空气仿佛凝固"全书 47 次这类能被机检报出 |
| 10 | 情绪节奏失控 | 每章情绪定位入 front matter（7.0）+ 波形体检与平台预设周期（7.x） | 7.0/7.x | 体检报告含情绪波形图 |
| 11 | AI 味 | 分布问题分层打：禁词表（第一层）+ 句式体检脚本（7.0）+ 文风锚定 few-shot（7.x）。**诚实边界：承诺"读者不出戏"，不承诺过 AI 检测器** | 7.0/7.x | 句式体检指标进体检报告 |
| 12 | 对话同质化 | 口癖卡 + 遮名盲测 | 7.x | 盲测用例 |
| 13 | 诚实边界 | README/RFC 明示承诺口径；合规/敏感词不进 v1 | 全程 | 文档口径一致 |
| 14 | 控制点滑杆 | 确认细纲/审稿两个开关；全关=逐章交互，全开=自动模式；一套实现 | 7.0 | 开关组合矩阵全测 |
| 15 | 连写质量漂移 | **按批次定稿**（错误最多污染一个批次，且未定稿可直接改）+ 体检与批次对齐（默认 8 章）+ 停止条件（写满/体检不过线/卷纲耗尽/连续 3 章无账本变动）+ 已发布错误走顺势圆 | 7.0 | 自动模式端到端 + 注入错误的恢复演练 |
| 16 | 真源唯一 | 正文+摘要 markdown 即全部状态；`.cache` 删了全量重建 | 7.0 | 重建 CI（重建器即格式的参考实现） |

---

## 5. 非功能需求

| 维度 | 要求 |
|---|---|
| 运行时 | Node ≥ 22，零第三方依赖（`node:sqlite`）；安装器检测版本并人话提示 |
| 平台 | Windows 中文环境一等公民：全链路 UTF-8 无 BOM、`core.quotepath false`、CI 含 Windows 中文路径全链路测试（建库→写章→定稿→重建缓存） |
| Token 成本 | 机检零 token；精准读取默认片段化；分层摘要控制长程上下文；每章 AI 调用次数有预算上限（实现时定数） |
| 健壮性 | 永不带堆栈崩溃（修复确认兜底）；定稿原子性；git 健康检查；容错读取（未知字段保留原样写回） |
| 可诊断性 | 强制项目级安装，目录结构全网统一；issue 里贴目录清单即可定位 |
| 防呆 | 系统写出的 YAML 一律平铺、块列表、危险值加引号；多条记录每条一文件 |
| 多宿主 | 格式层平台无关；SKILL.md 开放标准零适配；角色单源生成三平台壳 + drift check；降级诚实（不允许声称调用了不存在的能力）；hook 语义 ask 不 deny |
| 许可证 | MIT/Apache-2.0（v7 从零写） |

---

## 6. 范围切分

**切线原则**：已设计完且实现成本低的进 7.0；需要新设计或调参的体检类全部 7.x。

### v7.0（首发）

- 骨架：状态机单入口、写章流程八阶段（机检/三审新分工）、三类账本（声明制）、客观事实记账、时间线（按卷）、分层摘要、改稿三档、git 隐身全套（含健康检查与"回到第 N 章"）、精准读取接口
- 高呼声卖点：自动模式（连写，**按批次定稿**）、反和解规则、信息差登记（候选制泄密检查）
- 配套：npx 安装器（工作目录布局）+ update、`/migrate`、干净导出、AGENTS.md
- 文风层基础：文风铁律 + 禁词/句式机检 + 高频意象统计（v6 资产平移）；金句库目录与手动放入
- 宿主：一级（Claude Code + Codex），亲测过 smoke

### v7.x（增量）

- 金句库自动收割（候选制：作者改写且字数相近才候选，净删减不算；**对话触发**：作者聊天中夸某段也触发；最终一律作者审核入库）
- **按需静态简报**（单文件 HTML，内联样式无外链无服务器；账本全貌、体检统计与情绪波形、时间线浏览——"全书近况"管对话里的决策瞬间，浏览级信息归简报。**生成方式：脚本从缓存渲染固定模板，零 token，AI 不参与 HTML 构造**；模板随插件分发并入模板哈希清单；可选"近况点评"小节由 AI 以数据形式提供给脚本嵌入）
- 文风锚定（对标作者 few-shot）、桥段冷却清单、语气盲测、情绪波形、口癖卡
- 多宿主二级平台（Gemini CLI / Cursor，社区反馈确认）

### 不做（封死）

- RAG/向量库（语义检索=可选插件，永不做事实召回主路径）、常驻服务、敏感词/合规、AI 检测器承诺
- 大一统 YAML 数据文件、事件级 witnesses 投影、自建提交链、模型自由评"文笔好坏"、模型裸奔编纲
- 术语禁用词 CI 检查（术语一致性靠自审与评审把关，不上机器）

---

## 7. 发布判据

| 阶段 | 过线标准 |
|---|---|
| **发 RFC** | 本 PRD 定稿；术语表/目录图/三条作者旅程齐；RFC 以大白话裁剪发 GitHub Discussions（需先开启 Discussions，issue 区发置顶指引），征求意见至少开放 1 周 |
| **beta** | 用 v7 真实写一本书到 50 章（自用验证，覆盖建书→日更→吃书→卷复盘）；Windows 中文路径全链路 CI 绿；"删光 .cache 全量重建" CI 绿 |
| **7.0.0** | `/migrate` 在 ≥3 个真实 v6 项目跑通；beta 期无数据丢失级 bug；迁移指引文档齐 |

---

## 8. 术语表（作者界面词汇的法律文本）

**命名四原则**：①网文圈原生词优先；②圈内没有的用自然大白话；③财务/工程/数据库隐喻禁止出现在作者界面；④不自造两字精简词——宁可用自然的长短语。

| spec 0.5 旧词 | v7 定名 | 备注 |
|---|---|---|
| 承诺（P-031） | **账本拆三类**：伏笔（伏笔-031）/ 悬念（悬念-008）/ 感情线（感情线-012） | 各用各的生命周期动词（埋下→回收 / 设下→揭晓 / 开启→修成正果）；**编号一律全称** |
| 节奏债 | "悬了太久"预警 | 是提醒不是错误 |
| retcon 事务 | 吃书（吃书-87） | commit 前缀仍 retcon（机器域） |
| settle / 结转 | 定稿（动词） | 与 `定稿/` 目录一致 |
| 章事务 | 写章流程 | |
| 盘面 | 全书近况 | |
| 上下文包 | 本章写作材料 | |
| 合同 | 本章要写到的事 | |
| 镜头评审 | 三审（读者审/编辑审/设定校对） | 出版业原生词 |
| 棘轮 | 删除该比喻 | 直接说"定稿前/定稿后" |
| 风格宪法 | 文风铁律 | |
| 决策卡 | **取消"卡"概念**：环节叫"确认细纲"，文件 `工作区/细纲.md` | AI 拟细纲→作者点头或改 |
| 验收（卡） | 审稿，文件 `工作区/审稿.md` | |
| 修复卡 | 修复确认 | |
| 定稿/记忆/ | 定稿/摘要/ | "记忆"是 AI 视角词 |
| 信息差/时间线/名册/金句库/体检/钩子/强弱钩 | 保留 | 原生或大白话 |

机器协议不动（机器域，作者看不到）：commit 前缀 ch/vol/retcon/fix、`book.yaml`、`spec_version`、`.cache` 表名。**条目编号全部中文全称**（伏笔-031/悬念-008/感情线-012/信息差-021，原 P-031/S-021 废止）——编号是作者天天要念的，必须是人话且不过度压缩。

---

## 9. 风险与开放问题

| 风险 | 控制 |
|---|---|
| 三审每章 3 次 AI 调用，弱模型宿主上质量参差 | 三审任务书单源；设定校对给的是核对清单不是开放问题；降级模式（无 subagent 顺序执行）如实声明 |
| 自动模式错误连锁 | 按批次定稿——错误不经作者审稿不入定稿，污染上限一个批次且未定稿可直接改；已发布后的错误走影响分析+顺势圆 |
| 中文路径在小众平台/工具链上出幺蛾子 | CI 全链路 + 一级宿主 smoke；问题平台降级到二三级，不硬保 |
| Node 22 普及度 | 安装器人话提示升级；22 已是 LTS，写手装最新版无历史包袱 |
| Codex skill 列表 8k 字符预算 | description 精简纪律 + validator 检查 |
| 金句库 few-shot 注入旧文加重自我重复 | 7.x 才做自动收割；候选制+作者审核；按场景分文件轮换 |

开放问题（不阻塞 RFC，spec 修订时解决）：

- [O2] 自动模式开关的中文定名（"自动确认细纲"+"连写批次大小"候选）。
- [O3] 灵感池（偏离大纲的素材去向）的文件落点——`大纲/灵感池.md` 候选。
- [O4] 精准读取接口的完整清单与 `.cache` 表设计（实现 spec 定）。

（已消解，均为作者 2026-06-12 拍板：编号体系→全称中文编号；攒批审稿落点→按批次定稿后问题不复存在；多本书切换→`.webnovel/books.jsonl` 登记 + hook 注入；启动点→只支持工作目录启动；O1 书仓库自描述→根部指路 `AGENTS.md`。）---

## 10. spec 修订指令清单（本 PRD 对两份 spec 的下行要求）

### 10.1 story-repo-spec 0.5 → 0.6

1. §0/§1：删"棘轮"比喻；不变量补三条——git 隐身铁律、精准读取、"脚本/AI 语义分界"。
2. §2：目录按 §3.2 修订（账本三目录、摘要/、时间线按卷、细纲/审稿/导出、工作区文件改名）；**条目编号改中文全称**（"编号保留 ASCII"条款废止）；新增"工作目录 ⊃ 书目录"安装布局、书目录登记（`.webnovel/books.jsonl`）、**启动点限制**（只支持从工作目录启动——宿主只在启动目录加载 skills/配置；脚本校验 cwd 含 `.webnovel/`，否则人话提示）。
3. §2.1：Node ≥ 22，`node:sqlite`。
4. §3 book.yaml：**删除"自动验收"开关**（定稿永远归作者），新增"连写批次大小"（默认与体检周期一致）；开关中文名随术语表（O2）；新增分类型"悬了太久"阈值。
5. §5：大一统"承诺"拆三类账本；"每章必须结转"硬门检改**声明制**（细纲声明本章定位）；履历行必须引用章内证据；删豁免机制。
6. §6.1 改名文风铁律；§6.2 金句库 7.0 仅目录+手动，自动收割条款移入 7.x 附录（候选制+对话触发+作者审核）。
7. §7 决策卡 → 细纲.md，固定段落改为：全书近况 / 本章提案与定位声明 / 本章要写到的事 / 备选。
8. §8：第 5 步机检删"合同断言比对"（移三审设定校对）、信息差扫描改"只出候选"；第 6 步三审职责按 §3.4 重写。§8.1 **整节重写**：删除"自动验收过线即 settle"——**定稿永远由作者敲定**；自动模式改为按批次定稿（批内草稿与预入账数据攒工作区、写作材料组装支持"定稿+待定稿批次"叠加视图、批量审稿、作者敲定后逐章按序定稿）；停止条件增加"连续 3 章无账本变动即停"。
9. §9：retcon 作者界面叫吃书；新增影响分析脚本、"回到第 N 章"命令、顺势圆主路径。
10. §10：第 0 步前加 git 健康检查；修复卡→修复确认。
11. §11：表设计须支撑精准读取接口（O4）。
12. §4.1 章节 front matter：字段名随术语表与账本三类改写（开启/推进/兑付承诺 → 分类型的 埋下/推进/回收 等；"合同"→"本章要写到的事"）；**新增章属性字段**：钩子类型与强弱、情绪定位（压抑/铺垫/小爽/大爽/转折）。
13. **新增"建书"入口**：状态机目前假设书已存在，需补"无书/空仓库"态——引导式问答生成 book.yaml、总纲、第一卷卷纲（主旅程 §2.1 ② 的依据）；建书时同步生成书仓库根部指路 `AGENTS.md`（误启动/单独 clone 的指引）并登记进 `books.jsonl`。
14. §12 迁移映射更新：foreshadowing→伏笔、plot_threads→并入卷纲（不进账本）、chase_debt/reading_power→知识层与章属性；新增"市场版插件卸载+npx 重装"引导。
15. 新增章节：干净导出命令、精准读取接口。

### 10.2 multi-agent-adaptation-spec v3.1 → v3.2

1. §8 安装器重写：工作目录布局、强制项目级、npx init/update、模板哈希追踪、Node 版本检测、书目录登记初始化（建书时写入 `.webnovel/books.jsonl`）。
2. §5.5 hook 条款扩充：SessionStart 注入"当前在写哪本/书单/全书近况入口"（读 `books.jsonl`）；无 hook 宿主由状态机入口读同一文件，行为等价。
3. 新增 AGENTS.md 公约数层条款（工作目录根部，`<!-- WEBNOVEL:START/END -->` 标记块管理）。
4. 吸收 Trellis 调研：共享模板 + 平台上下文/条件块编译降级路径（降级在安装时定稿，不靠运行时判断）。
5. 删除 §5.2 中插件市场相关表述（`.claude-plugin/` 仅作为 v6 遗留说明）。

### 10.3 迁移映射（v6 → v7，更新版）

| v6 | v7 |
|----|----|
| `正文/` | `定稿/正文/`（补 front matter，"要写到的事"标"迁移"） |
| `设定集/` | `定稿/设定/` |
| `大纲/` | `大纲/总纲.md`、`大纲/卷纲/` |
| foreshadowing | `大纲/伏笔/` 逐条成文件 |
| plot_threads | 并入卷纲正文（不进账本） |
| chase_debt / reading_power | 知识层与章属性（不进账本） |
| `.webnovel/state.json` | 一次性展开进 `定稿/设定/` |
| `summaries/` | `定稿/摘要/` |
| project_memory patterns / scratchpad | `文风/文风铁律.md`（人工过一遍再入） |
| `.story-system/` 提交链 | 压成初始 commit，原目录只读归档 |
| index.db / vectors.db / projection_log | 删除（缓存重建；向量为可选插件） |
| references（题材模板/追读力/爽点节奏） | 知识层平移继承 |

---

## 11. 验收清单（PRD 自身）

- [x] 三条作者旅程完整（安装→建书/迁移→日常写作→卷复盘→发布）
- [x] 问题空间 16 项每项有归属（7.0 / 7.x / 不做）与验收方式
- [x] 发布判据可执行（每阶段有可验证的过线条件）
- [x] RFC 可从本 PRD 直接裁剪产出（§1.1、§2、§3.2、§6、§8 为裁剪主体）
- [x] spec 修订指令完整（两份 spec 的每处冲突都有下行指令）
