docs: reorganize docs and add story system specs

docs/README.md

@@ -1,65 +1,49 @@
 # 文档中心
 
-本目录承载 `README.md` 之外的详细说明，按模块拆分：
+`docs/` 目录已按稳定分区整理，避免所有说明文档平铺在根下。
 
-- [架构与模块](#架构与模块)
-- [LIGHT 长期记忆系统](#light-长期记忆系统)
-- [LIGHT 改造计划](#light-改造计划)
-- [长期记忆研究报告](#长期记忆研究报告)
-- [长期记忆新架构](#长期记忆新架构)
-- [STORYTELLER 论文总结](#storyteller-论文总结)
-- [STORYTELLER 落地方案](#storyteller-落地方案)
-- [命令详解](#命令详解)
-- [RAG 与配置](#rag-与配置)
-- [题材模板](#题材模板)
-- [运维与恢复](#运维与恢复)
+## 目录索引
 
-## 架构与模块
+### 架构
 
-- `architecture.md`：系统架构、核心理念、双 Agent、六维审查
+- [`architecture/overview.md`](./architecture/overview.md)：系统架构、核心理念、Agent 分工与主数据链
+- [`architecture/current-system-diagnosis.md`](./architecture/current-system-diagnosis.md)：当前实现状态的系统级诊断，聚焦读写链、提交语义与事实层问题
 
-## LIGHT 长期记忆系统
+### 使用指南
 
-- `light-memory-system.md`：LIGHT 三层记忆架构、数据流、落地实现建议
+- [`guides/commands.md`](./guides/commands.md)：`/webnovel-*` 命令入口与常见用法
+- [`guides/rag-and-config.md`](./guides/rag-and-config.md)：RAG 检索链路、环境变量与配置优先级
+- [`guides/genres.md`](./guides/genres.md)：题材模板与复合题材规则说明
 
-## LIGHT 改造计划
+### 运维
 
-- `light-retrofit-plan.md`：基于当前项目的 LIGHT 分层记忆改造方案与执行阶段
+- [`operations/operations.md`](./operations/operations.md)：项目目录、恢复、插件目录与运行期路径说明
 
-## 长期记忆研究报告
+### 记忆系统
 
-- `long-term-memory-research-report.md`：长期记忆论文、基准与开源项目调研报告
+- [`memory/long-term-memory-architecture-v2.md`](./memory/long-term-memory-architecture-v2.md)：基于当前代码状态的长期记忆现有架构说明
 
-## 长期记忆新架构
+### 研究与外部方案
 
-- `long-term-memory-architecture-v2.md`：基于调研结论重规划的长期记忆架构
+- [`research/long-term-memory-research-report.md`](./research/long-term-memory-research-report.md)：长期记忆论文、基准与开源项目调研
+- [`research/storyteller-paper-summary.md`](./research/storyteller-paper-summary.md)：`STORYTELLER` 论文总结
 
-## STORYTELLER 论文总结
+### Specs
+- [`superpowers/README.md`](./superpowers/README.md)：当前架构 spec 与设计文档导航
 
-- `storyteller-paper-summary.md`：STORYTELLER 论文方法、模块、流程与项目启发总结
+## 分类原则
 
-## STORYTELLER 落地方案
+- `architecture/`：当前系统的稳定结构说明
+- `guides/`：使用者需要直接查阅的命令、配置、题材说明
+- `operations/`：运行、恢复、目录与部署相关手册
+- `memory/`：当前已实现的长期记忆架构说明
+- `research/`：论文总结与外部方案调研
+- `superpowers/`：当前仍保留的架构 spec 与设计收敛文档
 
-- `storyteller-implementation-plan.md`：基于当前项目的 STORYTELLER 结构化章纲落地实施方案
+## 推荐阅读顺序
 
-## 命令详解
-
-- `commands.md`：`/webnovel-*` 命令详细说明
-
-## RAG 与配置
-
-- `rag-and-config.md`：RAG 检索与环境配置
-
-## 题材模板
-
-- `genres.md`：题材模板与复合题材规则
-
-## 运维与恢复
-
-- `operations.md`：项目结构与故障恢复/运维手册
-
-建议阅读顺序：
-
-1. 先看 `../README.md`（安装与上手）
-2. 再看 `architecture.md`（理解系统设计）
-3. 最后按需查阅命令和运维文档
+1. 先看 [`../README.md`](../README.md) 了解安装与基本使用。
+2. 再看 [`architecture/overview.md`](./architecture/overview.md) 建立整体结构认知。
+3. 需要配置检索时，看 [`guides/rag-and-config.md`](./guides/rag-and-config.md)。
+4. 需要实际使用命令时，看 [`guides/commands.md`](./guides/commands.md)。
+5. 需要排查运行问题时，看 [`operations/operations.md`](./operations/operations.md)。

docs/architecture/current-system-diagnosis.md

@@ -0,0 +1,107 @@
+# 当前系统架构诊断报告 (Current System Diagnosis)
+
+> **文档状态**: 诊断报告 (未引入 Story Intelligence System Spec 前)
+> **诊断前提**: 假设大语言模型（如 Opus 4.6）的指令遵循能力完美，能够完美解析并执行所有 Bash 命令和格式要求。
+> **核心结论**: 系统的痛点不在于模型写不好或执行失误，而在于**系统提供给模型的信息结构、校验时机和数据流转机制存在根本性硬伤**。系统试图用一套松散的管道脚本（Pipeline）去管理极其复杂的网文世界状态机（State Machine），最终不可避免地导致长篇连载走向崩盘。
+> 同时需要补一层更准确的校准：当前系统并不是完全没有结构化能力，而是**已经具备多个半成品中枢，但仍缺少统一故事合同（SSOT）与统一章节提交主链**。
+
+---
+
+## 一、 核心架构与真理源缺陷 (Architecture & Single Source of Truth)
+
+### 1. 多头真理（Multiple Sources of Truth）导致的认知撕裂
+
+* **现象**：系统的设定散落在 `state.json`（动态状态）、`genre-profiles.md`（静态调性）、`index.db`（碎片化实体）和 `memory`（长期事实）中。虽然 `context_manager`、`genre_*` 已经在尝试聚合这些信息，但它们本质上仍是运行时装配器和局部中枢，而不是统一的单一真理源（SSOT）。
+* **危害**：当剧情发生合理反转或设定升级时，系统无法做到全局同步。模型会同时接到冲突的指令（例如 md 要求主角废柴隐忍，而 state 显示已经天下无敌）。极度聪明的模型为了兼顾双方，反而会写出精神分裂般的割裂剧情。
+
+### 2. 设定演进账本仅有雏形，尚未覆盖核心世界设定（Override Ledger Gap）
+
+* **现象**：网文的核心规则是会随着剧情推进被打破的（如主角打破了某项世界限制）。当前系统已在 v5.3 引入了 `override_contracts` 表（见 `index_debt_mixin.py`），具备完整的 CRUD 操作（含 `constraint_type`、`rationale_type`、`rationale_text`、`payback_plan`、`due_chapter`、`status`）。但该机制目前**仅服务于追读力债务系统的软建议违背记录**，尚未扩展为核心世界设定（力量体系、角色命运、世界规则）的演进账本。对于这些核心设定的修改，系统本质上仍只有静默覆盖（Overwrite）或局部投影更新。
+* **危害**：没有机制明确告诉 AI 注意，卷五已经合法推翻了卷一的隐忍设定，现在的最高准则是无敌爽文。系统把所有的旧规则和新状态一锅端地喂给 AI，造成严重的上下文污染和逻辑死锁。Override Contract 的基础设施已经存在，但其应用范围的局限性使得它无法解决这个核心问题。
+
+---
+
+## 二、 上下文装配与知识供给痛点 (Context & Knowledge Assembly)
+
+### 3. 机械截断导致的信息黑洞（The Blind Spot of Context Truncation）
+
+* **现象**：`context_manager.py` 确实已经在做上下文聚合，且 `context_ranker.py` 已经对 alerts 等信息做了优先级排序与筛选（说明系统并非完全无脑塞上下文）。但最终输出仍采用按权重（`TEMPLATE_WEIGHTS`）和字数预算，强行截断字符串（`_compact_json_text`）的方式来组装上下文。
+* **危害**：模型再聪明，也无法遵守它没看到的规则。关键毒点、核心力量限制或重要伏笔，极容易因为刚好超出字符串预算而被底层脚本静默丢弃。导致模型不得不靠幻觉（Hallucination）填补空白，引发设定崩塌。问题不在“没有聚合”，而在于**聚合后的输入仍可能被预算逻辑打成信息黑洞**。
+
+### 4. 知识延迟绑定（Late-Binding）与泛化割裂
+
+* **现象**：系统并不只是中途临时查 CSV，它其实已经有 `md 必读 + CSV 检索 + genre_profile` 的双轨资料体系。但在写作中，系统仍要求大模型在具体阶段按需调用 `reference_search.py` 查通用条目（如如何写战斗）。
+* **危害**：查出来的大多是通用网文技巧，而不是本书专属设定。系统缺乏一个前置的聚合层把通用套路和本书主角特质、题材调性、系统边界揉合在一起，导致写出的剧情虽然套路标准，但千篇一律，缺乏本书的灵魂与特色。
+
+---
+
+## 三、 流程编排与校验机制漏洞 (Workflow & Verification)
+
+### 5. 事后验尸而非事前避坑的防线设计
+
+* **现象**：系统高度依赖 Step 3 的 Reviewer Agent 去审查**已经写完的正文**，发现 Blocking 毒点后再打回 Step 4（润色）修复。
+* **危害**：防线设得太晚。如果模型在起草时犯了方向性或结构性错误（如写死了不该死的核心角色，或触碰了严重毒点），依靠润色（改表达不改事实）是根本救不回来的。这会导致无解的死循环，或只能产出打补丁式的劣质文本。
+
+### 6. 缺乏大纲履约的强制校验（No Fulfillment Verification）
+
+* **现象**：系统已经能读取 `chapter outline`、`plot_structure`、`mandatory_nodes`、`prohibitions` 这类计划信息，但在写后提交阶段，只会提取记录实际写了什么（What is），不会严谨地进行结构化 Diff，对比大纲要求写什么（What was planned vs. achieved，如 CBN/CEN 节点）。
+* **危害**：如果模型因为篇幅原因漏写了一个关键的暗杀伏笔，系统只会完美地提取已写的内容，而不会报错大纲要求未履约。这会悄无声息地引发后续章节大纲的连锁崩盘。
+
+---
+
+## 四、 数据回写与后置处理隐患 (Data Write-back & Disambiguation)
+
+### 7. 事务割裂与幽灵状态（Fragmented DB Transactions）
+
+* **现象**：Step 5 要求将结果分别写入 `state.json`、`index.db`、`summaries` 和 `memory` 四个不同的地方。需要校准的是：当前 `state_manager` 对自身写盘已经有局部原子写和 pending 快照保护，但这仍然不是跨存储的章节级事务一致性（ACID）。此外，`StateManager` 内部还维护了 `state.json` + SQLite（`index.db`）的**双写同步逻辑**（`_sync_to_sqlite`、`_sync_pending_patches_to_sqlite`），包含 pending 快照恢复机制，这在单个模块内部就已经引入了额外的一致性复杂度。
+* **危害**：风险存在于两个层面。**内层**：`StateManager` 的 JSON + SQLite 双写如果部分失败，虽然有快照恢复，但恢复逻辑本身也可能在极端情况下不完整。**外层**：四个存储的跨库写操作一旦中途发生中断，仍然会导致 DB 记录角色已死，而 `state.json` 里角色还活着，或摘要和长期记忆没有同步更新。这种幽灵状态会在生成下一章时把模型彻底搞疯。
+
+### 8. 幻觉错误被后置消歧放大为索引污染风险（Index Pollution via Disambiguation）
+
+* **现象**：如果在 Step 2 模型产生了幻觉，把主角林辰错写成了张辰，后置消歧未必会直接报错打回。需要校准的是：当前系统对消歧有置信度分层，不是无脑把所有错误都写死；但它确实存在一个风险窗口，**一旦错误命中“可采用”区间，后置消歧就可能把错误实体归并写入后续索引链路。**
+* **危害**：这意味着纯粹的写作幻觉，不一定会被当场拦截，反而可能以“低置信但被采用”的形式被沉淀为别名、出场记录、关系记录或状态更新。长期来看，这仍会污染数据库，使后续消歧越来越乱。
+
+### 9. 消歧警告的向后传染（Context Leaking）
+
+* **现象**：如果 Step 5 发现模棱两可的名字且无法自动消歧，会将其记入 `state.json` 的 `disambiguation_pending`，高于阈值但仍不稳的则进入 `disambiguation_warnings`，并在写**下一章**时通过上下文装配链被继续读取。
+* **危害**：上一章的消歧烂账，变成了下一章起草时的噪音。这极大地分散了模型写新剧情的注意力，甚至诱导模型在新章节中强行加戏去解释上一章的名字问题，破坏行文流畅度。
+
+### 10. 状态投影主导，语义事件只有痕迹没有主链（State Overwrite vs. Delta Events）
+
+* **现象**：Data Agent 和数据链并不是完全没有 Delta 事件，实际上已经存在：
+  - `state_changes`
+  - `relationship_events`
+  - `timeline_events`
+  - `world_rules`
+  - `open_loops`
+  - `reader_promises`
+
+  其中关系事件层面，代码里已经有比 `relationships_new` 更完整的 `relationship_events` 表，具备较强的结构化能力；但这些事件整体仍分散在 `state`、`index`、`memory` 等不同层里，没有统一的 canonical event log。系统主链仍然更偏向“状态投影更新”，而不是“事件驱动更新”。
+* **危害**：结果就是系统能记录“已经变成金丹”，却很难以统一方式表达“如何突破、消耗了什么资源、引发了什么异象、这次突破应如何修改上层世界规则”。这使得系统无法自动感知并触发设定升级或力量体系阈值扩展，模型仍然需要像瞎子摸象一样去猜目前的战力天花板。
+
+---
+
+## 总结
+
+在没有引入 `Story Intelligence System Spec` 的前置契约约束之前，系统并不是完全靠大模型“裸奔”，而是已经靠多个半成品中枢在**缝缝补补**：
+
+- `context_manager` + `context_ranker` 在做上下文聚合与优先级排序
+- `genre_*` 在做题材归一化与画像构建
+- `state_manager` 在做结构化状态回写（含 JSON + SQLite 双写同步）
+- `memory writer / orchestrator` 在做长期事实沉淀
+- `override_contracts` 在做追读力债务的违背记录（Override Ledger 雏形）
+
+但这些能力还没有被收束成一个统一的故事事实系统。
+
+因此，当前系统最根本的问题不是“模型不够强”，而是：
+
+**系统已经有多个局部结构层（包括 Override Contract 雏形和 Delta 事件底座），但还没有统一故事合同（Story Contract）、统一章节提交主链（Commit Chain）和覆盖全局世界设定的统一演进账本（Override Ledger）。**
+
+这也正是新架构的核心价值所在：
+
+- 生成强约束的 `Master / Volume / Chapter` JSON 合同
+- 建立显式的 Override 账本
+- 事前给足绝对红线、系统边界和消歧域
+- 把 `state / index / summary / memory / RAG` 从“散落真理源”降级为“合同提交后的投影层”
+
+只有提供完美、无歧义、可追溯且前后一致的输入，大模型才能持续、稳定地输出高质量的长篇连载。

docs/light-memory-system.md

@@ -1,335 +0,0 @@
-# LIGHT 长期记忆系统说明
-
-## 文档目标
-
-本文档将论文中的 LIGHT 系统整理成可落地的工程方案，重点说明三层记忆结构、读写链路、核心数据结构，以及在产品化实现时需要重点处理的问题。
-
-## 一句话定义
-
-LIGHT 不是单纯把上下文窗口做大，而是把长期记忆拆成三层：
-
-- 情节记忆 `episodic memory`：负责从历史对话中检索证据
-- 工作记忆 `working memory`：负责保留最近上下文
-- 草稿板 `scratchpad`：负责沉淀长期稳定的高价值事实
-
-回答时由统一的记忆编排器组合这三层记忆，再交给生成模型。
-
-## 设计目标
-
-- 支持超长会话下的稳定问答
-- 降低“上下文很长但还是忘事”的问题
-- 兼顾近期上下文、远期事实和长期偏好
-- 为信息更新、偏好跟随、跨轮总结提供结构化基础
-
-## 总体架构
-
-```text
-┌────────────────────────────────────────────────────┐
-│                    用户对话流                      │
-└────────────────────────────────────────────────────┘
-                         │
-                         ▼
-┌────────────────────────────────────────────────────┐
-│                  回合后处理器                      │
-├────────────────────────────────────────────────────┤
-│ 1. 保存原始 turn 到会话存储                        │
-│ 2. 提取 key-value 和摘要，写入情节记忆             │
-│ 3. 提炼显著事实，增量更新 scratchpad              │
-└────────────────────────────────────────────────────┘
-                         │
-                         ▼
-┌────────────────────────────────────────────────────┐
-│                  用户新问题到达                    │
-└────────────────────────────────────────────────────┘
-                         │
-                         ▼
-┌────────────────────────────────────────────────────┐
-│                  记忆编排器                        │
-├────────────────────────────────────────────────────┤
-│ 1. 检索 episodic top-k                             │
-│ 2. 读取最近 N 轮 working memory                    │
-│ 3. 对 scratchpad 分块并过滤相关内容                │
-│ 4. 组装 prompt，交给回答模型                       │
-└────────────────────────────────────────────────────┘
-```
-
-## 三层记忆拆解
-
-### 1. 情节记忆 `episodic memory`
-
-作用：
-
-- 存储历史对话中的离散事件与事实证据
-- 在远距离问题中召回“当时具体说过什么”
-- 为答案提供可追溯的历史片段
-
-写入方式：
-
-- 每轮 `user-assistant turn pair` 结束后执行一次
-- 提取结构化 `key-value pairs`
-- 生成该轮摘要 `summary`
-- 对结构化结果或摘要做向量化
-- 将原始对话片段与索引共同存入向量库
-
-建议字段：
-
-```json
-{
-  "session_id": "session-001",
-  "turn_id": 1842,
-  "timestamp": "2026-03-19T18:00:00+08:00",
-  "entities": [
-    {"key": "居住城市", "value": "苏州"},
-    {"key": "宠物名字", "value": "团子"}
-  ],
-  "summary": "用户提到已搬到苏州，并养了一只叫团子的猫。",
-  "raw_span": "原始对话片段",
-  "embedding_text": "居住城市=苏州；宠物名字=团子；用户提到已搬到苏州，并养了一只叫团子的猫。"
-}
-```
-
-工程建议：
-
-- 不要只存全文向量，优先存“摘要 + 结构化提取”的索引文本
-- 检索后返回原始片段，避免摘要失真带来的二次误导
-- `top-k` 不要盲目调大，过多召回会引入噪声
-
-### 2. 工作记忆 `working memory`
-
-作用：
-
-- 保留最近若干轮原始对话
-- 维持局部连贯性、代词解析、刚更新的信息
-- 防止系统只看远期记忆，忽略当前上下文
-
-实现方式：
-
-- 直接从会话存储读取最近 `N` 轮
-- 或按 `token budget` 截断，而不是写死固定轮数
-
-工程建议：
-
-- 优先按 token 上限裁剪，而不是按回合数裁剪
-- 最近轮的优先级通常高于远期记忆
-- 回答冲突时，应优先检查工作记忆中是否存在更近更新
-
-### 3. 草稿板 `scratchpad`
-
-作用：
-
-- 沉淀对长期任务真正重要的高层事实
-- 存储偏好、长期约束、时间线、未完成事项等
-- 避免只依赖相似度检索导致关键信息漏召回
-
-写入方式：
-
-- 每轮结束后由 LLM 提炼“显著信息”
-- 将新信息合并到现有 scratchpad
-- 超过阈值后执行压缩
-
-推荐分槽位组织，而不是一整段自由文本：
-
-```json
-{
-  "profile": [
-    "用户当前住在苏州"
-  ],
-  "preferences": [
-    "默认使用简体中文",
-    "倾向简洁回答"
-  ],
-  "instructions": [
-    "代码注释使用中文",
-    "避免未验证结论"
-  ],
-  "timeline": [
-    "2025-12: 从杭州搬到苏州",
-    "2026-04: 计划去东京出差"
-  ],
-  "open_loops": [
-    "简历修改尚未完成"
-  ]
-}
-```
-
-工程建议：
-
-- 将 `profile / preferences / instructions / timeline / open_loops` 分开维护
-- 超过长度阈值后做压缩，但要保留高优先级槽位
-- 回答前不要整块全部注入，应先按问题相关性过滤
-
-## 读写链路
-
-### 写入链路
-
-每轮对话结束后：
-
-1. 保存原始 turn 到会话存储
-2. 用提取模型生成 `key-value + summary`
-3. 写入情节记忆索引
-4. 更新 scratchpad
-5. 超过阈值时压缩 scratchpad
-
-### 读取链路
-
-收到新问题后：
-
-1. 对问题做向量化
-2. 从情节记忆中召回 `top-k`
-3. 从会话存储取最近若干轮 working memory
-4. 将 scratchpad 分块
-5. 对每块做相关性过滤
-6. 将三层记忆拼装为回答上下文
-7. 调用生成模型作答
-
-## 关键数据存储
-
-建议至少拆成四类存储：
-
-- `conversation_store`：保存原始对话 turn
-- `episodic_index`：保存摘要、结构化提取、embedding、原始片段引用
-- `scratchpad_store`：保存长期摘要与槽位化事实
-- `memory_metadata`：保存版本号、状态、更新时间、冲突标记
-
-可选状态字段：
-
-- `active`：当前有效
-- `outdated`：已过期
-- `contradicted`：被冲突信息覆盖
-- `tentative`：不确定信息，需后续确认
-
-## 记忆编排器职责
-
-记忆编排器是系统核心，职责包括：
-
-- 控制每类记忆的 token 预算
-- 决定检索数量与排序策略
-- 在冲突信息出现时做优先级裁决
-- 过滤与问题无关的 scratchpad 块
-- 统一输出给回答模型的上下文格式
-
-一个简单的优先级顺序可以是：
-
-1. 当前轮明确指令
-2. working memory 中的最近事实
-3. scratchpad 中的长期约束与偏好
-4. episodic memory 中召回的历史证据
-
-## 最小可用实现（MVP）
-
-最小版本只需要五个组件：
-
-- `conversation_store`
-- `episodic_indexer`
-- `scratchpad_manager`
-- `memory_orchestrator`
-- `response_generator`
-
-伪代码：
-
-```python
-def on_turn_end(session_id, user_msg, assistant_msg):
-    save_raw_turn(session_id, user_msg, assistant_msg)
-
-    memory_item = extract_kv_and_summary(user_msg, assistant_msg)
-    vector_store.upsert(session_id, memory_item)
-
-    scratchpad = load_scratchpad(session_id)
-    scratchpad = update_scratchpad(scratchpad, user_msg, assistant_msg)
-    if token_len(scratchpad) > 30000:
-        scratchpad = compress_scratchpad(scratchpad, target_tokens=15000)
-    save_scratchpad(session_id, scratchpad)
-
-
-def answer(session_id, question):
-    episodic_docs = retrieve_topk(session_id, question, k=15)
-    recent_turns = load_recent_turns(session_id, token_budget=8000)
-    scratchpad = load_scratchpad(session_id)
-    scratch_chunks = semantic_chunk(scratchpad)
-    filtered_scratch = filter_relevant_chunks(question, scratch_chunks)
-
-    prompt = build_prompt(
-        question=question,
-        episodic_memory=episodic_docs,
-        working_memory=recent_turns,
-        scratchpad=filtered_scratch,
-    )
-    return llm_generate(prompt)
-```
-
-## 与普通 RAG 的区别
-
-普通 RAG 常见流程是：
-
-- 文本切块
-- 向量检索
-- 拼接上下文
-
-LIGHT 的差异在于：
-
-- 有独立的 working memory，保证近期连续性
-- 有 scratchpad，维护高层抽象事实
-- 有持续写入机制，而不是只在回答前做一次检索
-- 更接近“记忆系统”，而不是单次检索增强
-
-## 落地时最难的四个问题
-
-### 1. 信息更新
-
-同一事实会变化，例如“住在杭州”后来变成“搬到苏州”。系统不能只追加，不做状态管理。
-
-### 2. 矛盾消解
-
-不同时间的记忆可能互相冲突。系统需要判断：
-
-- 哪条是最新的
-- 哪条是已过期的
-- 哪条只是暂时猜测
-
-### 3. Scratchpad 膨胀
-
-如果长期只追加不整理，scratchpad 会退化成另一份噪声上下文，导致检索和回答质量持续下降。
-
-### 4. 写入污染
-
-每轮写入依赖 LLM 提取。如果提取错误，错误会长期保留并反复影响后续回答。
-
-## 产品化增强建议
-
-如果从论文原型继续往前做，建议增加以下能力：
-
-- 混合召回：结合 dense、keyword、时间排序和 rerank
-- 冲突检查：回答前先做 memory conflict check
-- 偏好单独建表：用户偏好和长期指令不要完全混在 scratchpad 中
-- 版本化更新：对关键事实保留变更历史和生效时间
-- 可观察性：记录每次回答用了哪些记忆，便于审计和调试
-
-## 适用场景
-
-LIGHT 适合以下系统：
-
-- 长对话助手
-- 需要记住用户偏好的智能体
-- 多轮写作/策划协作系统
-- 长期任务跟踪与提醒系统
-- 小说创作助手中的角色、设定、剧情记忆系统
-
-## 对本项目的启发
-
-如果把 LIGHT 思路引入当前小说写作系统，可以这样映射：
-
-- 情节记忆：存章节事件、角色状态变化、伏笔和回收线索
-- 工作记忆：存当前章节任务书、最近章节摘要、当前写作约束
-- 草稿板：存角色设定、长期世界观规则、主线目标、未回收伏笔
-
-这样可以把“长篇连载的一致性问题”从单次检索，升级成持续维护的记忆闭环。
-
-## 总结
-
-LIGHT 的核心价值不在于更大的上下文窗口，而在于把长期记忆拆成：
-
-- 可检索的历史证据层
-- 保持局部连贯的短期层
-- 稳定沉淀长期事实的抽象层
-
-工程上最值得复用的是这套分层记忆与统一编排思路，而不是某个固定模型或具体实现细节。

docs/light-retrofit-plan.md

@@ -1,701 +0,0 @@
-# LIGHT 改造现有系统计划
-
-## 文档目标
-
-本文档给出一份可直接执行的改造计划，用于在当前 `webnovel-writer` 基础上引入 LIGHT 风格的三层记忆系统，同时尽量复用现有的 `state.json`、`index.db`、`vectors.db`、`ContextManager` 与写作工作流。
-
-目标不是推翻现有架构，而是在低风险前提下补齐：
-
-- 独立的长期摘要记忆层 `scratchpad`
-- 统一的记忆编排层 `memory orchestrator`
-- 面向写作场景的冲突裁决与记忆状态管理
-
-## 当前系统现状摘要
-
-当前项目已经具备以下能力：
-
-- `state.json`：精简运行态与章节元信息
-- `index.db`：实体、别名、状态变化、关系、追读力、审查指标
-- `vectors.db`：章节摘要与场景切片的向量检索
-- `ContextManager`：多源上下文拼装与预算裁剪
-- `extract_chapter_context.py`：写作前统一上下文入口
-- `workflow_manager.py`：写作工作流状态机与中断恢复
-
-当前缺口主要有两项：
-
-- 缺独立维护的长期摘要记忆层
-- 缺统一调度 `working / episodic / scratchpad` 的记忆编排器
-
-## 改造目标
-
-### 总目标
-
-将系统升级为三层记忆架构：
-
-- `working memory`：近期写作上下文
-- `episodic memory`：可检索历史证据
-- `scratchpad memory`：长期高密度摘要记忆
-
-### 子目标
-
-- 不破坏现有 `/webnovel-write` 主流程
-- 不修改已有数据模型的核心职责边界
-- 新增能力尽量通过“增量接入”完成
-- 保持现有 CLI 与测试体系可持续演进
-
-## 目标架构
-
-```text
-Skills / Agents
-   │
-   ▼
-Chapter Context Facade
-   │  extract_chapter_context.py
-   │  ContextManager
-   ▼
-Memory Orchestrator
-   ├── Working Memory
-   ├── Episodic Memory
-   └── Scratchpad Memory
-   ▼
-Final Context Pack
-
-写入侧：
-Data Agent / Step 5
-   ├── state.json
-   ├── index.db
-   ├── vectors.db
-   ├── summaries/
-   └── memory_scratchpad.json
-```
-
-## 设计原则
-
-### 1. 最小侵入
-
-优先复用：
-
-- `ContextManager`
-- `extract_chapter_context.py`
-- `StateManager`
-- `IndexManager`
-- `RAGAdapter`
-
-### 2. 单一职责
-
-- `state.json` 继续保存运行态精简信息
-- `index.db` 继续保存结构化事实
-- `vectors.db` 继续保存语义检索向量
-- `memory_scratchpad.json` 专门保存长期摘要记忆
-
-### 3. 渐进替换
-
-先“旁路接入”，再逐步把逻辑迁入编排器，而不是一次性重写 `ContextManager`
-
-### 4. 可回滚
-
-每个阶段都能独立上线和回退，避免一次改太大导致写作链失稳
-
-## 记忆分层映射
-
-### Working Memory
-
-来源：
-
-- 本章大纲
-- 最近章节摘要
-- 当前 `state.json`
-- `reader_signal`
-- `writing_guidance`
-
-当前主要载体：
-
-- `scripts/extract_chapter_context.py`
-- `scripts/data_modules/context_manager.py`
-
-### Episodic Memory
-
-来源：
-
-- `index.db`
-- `vectors.db`
-- `.webnovel/summaries/chNNNN.md`
-
-当前主要载体：
-
-- `scripts/data_modules/index_manager.py`
-- `scripts/data_modules/rag_adapter.py`
-- `scripts/data_modules/state_manager.py`
-
-### Scratchpad Memory
-
-新增：
-
-- `.webnovel/memory_scratchpad.json`
-
-用途：
-
-- 汇总长期有效事实
-- 维护角色当前稳定状态
-- 沉淀世界规则与长期约束
-- 存储时间线与未回收开放环
-- 服务写作前的高密度摘要注入
-
-## 新增模块规划
-
-建议新增以下文件：
-
-```text
-webnovel-writer/scripts/data_modules/
-├── memory_orchestrator.py
-├── scratchpad_manager.py
-├── scratchpad_schema.py
-└── memory_conflict_resolver.py
-```
-
-### `scratchpad_schema.py`
-
-职责：
-
-- 定义 `memory_scratchpad.json` 结构
-- 提供默认值与校验函数
-
-建议结构：
-
-```json
-{
-  "story_facts": [],
-  "character_facts": [],
-  "world_rules": [],
-  "timeline": [],
-  "open_loops": [],
-  "reader_promises": [],
-  "active_constraints": [],
-  "meta": {
-    "version": 1,
-    "last_updated": ""
-  }
-}
-```
-
-### `scratchpad_manager.py`
-
-职责：
-
-- 读写 `memory_scratchpad.json`
-- 从章节结果增量更新长期摘要
-- 定期压缩与去噪
-- 按主题或章节生成相关片段
-
-建议能力：
-
-- `load()`
-- `save()`
-- `update_from_chapter_result()`
-- `compress_if_needed()`
-- `filter_for_chapter()`
-- `mark_fact_status()`
-
-### `memory_conflict_resolver.py`
-
-职责：
-
-- 处理新旧事实冲突
-- 给事实打状态标签
-
-建议状态：
-
-- `active`
-- `outdated`
-- `contradicted`
-- `tentative`
-
-建议处理对象：
-
-- 角色境界/地点/归属变更
-- 关系变化
-- 世界规则的显式修订
-- 伏笔从 active 到 resolved
-
-### `memory_orchestrator.py`
-
-职责：
-
-- 统一调度三层记忆
-- 控制预算与优先级
-- 输出最终 context pack
-
-建议接口：
-
-- `build_memory_pack(chapter: int) -> dict`
-- `load_working_memory(chapter: int) -> dict`
-- `load_episodic_memory(chapter: int) -> dict`
-- `load_scratchpad_memory(chapter: int) -> dict`
-- `resolve_conflicts(...)`
-- `assemble(...)`
-
-## 现有文件改造点
-
-### 第一优先级
-
-#### `scripts/data_modules/context_manager.py`
-
-改造目标：
-
-- 从“多源上下文拼装器”升级为“编排器调用方”
-- 新增 `scratchpad` section
-- 后续逐步委托给 `MemoryOrchestrator`
-
-建议改动：
-
-- `_build_pack()` 中加入 scratchpad 内容
-- `SECTION_ORDER` 中加入或重新排序 `scratchpad`
-- 新增从 orchestrator 获取结果的兼容入口
-
-#### `scripts/extract_chapter_context.py`
-
-改造目标：
-
-- 接入 `MemoryOrchestrator`
-- 输出更完整的三层记忆摘要
-
-建议改动：
-
-- 在 `build_chapter_context_payload()` 中加载 orchestrator 结果
-- 保留现有 JSON/text 输出格式兼容
-- 新增 `scratchpad_signal` 或 `long_term_memory` 字段
-
-#### `scripts/data_modules/state_manager.py`
-
-改造目标：
-
-- 在 `process_chapter_result()` 完成后触发 scratchpad 更新
-
-建议改动：
-
-- 在章节结果保存成功后调用 `ScratchpadManager.update_from_chapter_result()`
-- 失败时只记录 warning，不影响主流程完成
-
-### 第二优先级
-
-#### `scripts/data_modules/rag_adapter.py`
-
-改造目标：
-
-- 让 episodic memory 检索对“长期事实块”更友好
-
-建议改动：
-
-- 为 scratchpad 相关片段预留可选向量化能力
-- 允许对 `chunk_type=scratchpad` 做检索
-- 不作为第一阶段必做项
-
-#### `scripts/status_reporter.py`
-
-改造目标：
-
-- 利用 scratchpad 生成更高层视角的健康报告
-
-建议改动：
-
-- 报告中增加“长期约束漂移”“未回收开放环”“记忆冲突提醒”
-
-#### Dashboard
-
-改造目标：
-
-- 增加 scratchpad 可视化
-
-建议改动：
-
-- 展示当前长期事实摘要
-- 展示冲突事实与待确认事实
-
-## 新数据文件规划
-
-新增：
-
-```text
-.webnovel/memory_scratchpad.json
-```
-
-建议字段：
-
-- `story_facts`：当前剧情稳定事实
-- `character_facts`：角色稳定状态与重要变化
-- `world_rules`：长期不可违背设定
-- `timeline`：关键事件时间线
-- `open_loops`：未回收伏笔、未完成承诺、待兑现悬念
-- `reader_promises`：已对读者抛出的期待点
-- `active_constraints`：当前章节仍需遵守的重要约束
-- `meta`：版本、更新时间、压缩次数
-
-建议事实项结构：
-
-```json
-{
-  "id": "fact-char-xiaoyan-realm-001",
-  "category": "character_facts",
-  "subject": "xiaoyan",
-  "field": "realm",
-  "value": "筑基三层",
-  "status": "active",
-  "source_chapter": 128,
-  "updated_at": "2026-03-19T20:00:00+08:00",
-  "evidence": [
-    "ch0128_summary",
-    "state_change:xiaoyan:realm:128"
-  ],
-  "confidence": 0.95
-}
-```
-
-## 分阶段执行计划
-
-### Phase 0：设计冻结与接口先行
-
-目标：
-
-- 明确数据结构和接口，不立即改主流程
-
-任务：
-
-1. 定义 `memory_scratchpad.json` schema
-2. 定义 `ScratchpadManager` 最小接口
-3. 定义 `MemoryOrchestrator` 输入输出格式
-4. 补充设计文档与测试样例
-
-交付物：
-
-- `scratchpad_schema.py`
-- 设计说明文档
-- 测试用 fixture 样例
-
-验收标准：
-
-- schema 稳定
-- 接口命名与现有风格一致
-- 不影响现有命令
-
-### Phase 1：落地 Scratchpad 存储层
-
-目标：
-
-- 让项目拥有独立的长期摘要记忆文件
-
-任务：
-
-1. 实现 `scratchpad_schema.py`
-2. 实现 `scratchpad_manager.py`
-3. 支持加载、保存、初始化默认结构
-4. 编写基础单元测试
-
-交付物：
-
-- `memory_scratchpad.json`
-- `ScratchpadManager`
-- 对应 tests
-
-验收标准：
-
-- 文件创建与读写稳定
-- schema 校验通过
-- 空项目可自动初始化
-
-### Phase 2：接入章节写后更新链
-
-目标：
-
-- 在现有 Step 5 后自动维护 scratchpad
-
-任务：
-
-1. 在 `StateManager.process_chapter_result()` 后接入 scratchpad 更新
-2. 从以下来源提取增量事实：
-   - `entities_new`
-   - `state_changes`
-   - `relationships_new`
-   - `chapter_meta`
-   - `plot_threads.foreshadowing`
-3. 增加错误隔离，保证 scratchpad 失败不阻断主流程
-
-交付物：
-
-- 写后更新逻辑
-- 日志与 warning 机制
-
-验收标准：
-
-- 写完一章后 scratchpad 有可见增量
-- 工作流不因 scratchpad 失败而中断
-
-### Phase 3：接入读取链
-
-目标：
-
-- 在写作前上下文中引入 scratchpad
-
-任务：
-
-1. 在 `ContextManager` 中加入 scratchpad section
-2. 在 `extract_chapter_context.py` 中输出长期记忆摘要
-3. 为 scratchpad 分配独立预算
-4. 增加按章节相关性过滤
-
-交付物：
-
-- 上下文新增 `scratchpad` / `long_term_memory`
-- text 输出中新增相关章节说明
-
-验收标准：
-
-- 第 N 章上下文可看到长期约束与关键开放环
-- 上下文长度可控
-
-### Phase 4：引入 Memory Orchestrator
-
-目标：
-
-- 从“多源拼装”升级为“分层记忆编排”
-
-任务：
-
-1. 新建 `memory_orchestrator.py`
-2. 把以下逻辑迁入 orchestrator：
-   - Working memory 读取
-   - Episodic memory 检索
-   - Scratchpad 过滤
-   - 冲突检查
-   - 最终 pack 组装
-3. 让 `ContextManager` 调用 orchestrator，而不是自己做全部组装
-
-交付物：
-
-- `MemoryOrchestrator`
-- `ContextManager` 兼容适配
-
-验收标准：
-
-- 输出结构与旧接口兼容
-- 逻辑可单测
-- 能独立关闭 orchestrator，回退旧路径
-
-### Phase 5：冲突裁决与记忆状态化
-
-目标：
-
-- 解决“旧事实覆盖新事实”的问题
-
-任务：
-
-1. 新建 `memory_conflict_resolver.py`
-2. 对关键事实打状态：
-   - `active`
-   - `outdated`
-   - `contradicted`
-   - `tentative`
-3. 处理常见冲突：
-   - 人物境界变化
-   - 人物位置变化
-   - 势力归属变化
-   - 伏笔状态变化
-   - 关系状态变化
-
-交付物：
-
-- 冲突解析器
-- 冲突样例测试
-
-验收标准：
-
-- 最新事实优先
-- 旧事实保留历史但不进入高优先上下文
-
-### Phase 6：高级能力增强
-
-目标：
-
-- 进一步提升检索与可观察性
-
-任务：
-
-1. 可选支持 scratchpad 向量化
-2. 在 dashboard 中增加 scratchpad 可视化
-3. 增加记忆命中日志
-4. 在健康报告中加入记忆冲突提醒
-
-交付物：
-
-- dashboard 页面扩展
-- 观测指标扩展
-
-验收标准：
-
-- 能追踪每次写作用了哪些记忆
-- 可以人工审计长期记忆质量
-
-## 实施顺序建议
-
-推荐严格按以下顺序做：
-
-1. Phase 0
-2. Phase 1
-3. Phase 2
-4. Phase 3
-5. Phase 4
-6. Phase 5
-7. Phase 6
-
-原因：
-
-- 先落存储层，后接写链
-- 先让数据流起来，再做编排优化
-- 先保证稳定，再做智能化冲突处理
-
-## 测试计划
-
-### 单元测试
-
-新增测试文件建议：
-
-```text
-scripts/data_modules/tests/
-├── test_scratchpad_schema.py
-├── test_scratchpad_manager.py
-├── test_memory_orchestrator.py
-└── test_memory_conflict_resolver.py
-```
-
-重点测试：
-
-- scratchpad 初始化
-- 章节结果增量写入
-- 冲突事实状态变化
-- 上下文过滤与预算裁剪
-- orchestrator 输出兼容性
-
-### 集成测试
-
-建议扩展：
-
-- `test_context_manager.py`
-- `test_extract_chapter_context.py`
-- `test_state_manager_extra.py`
-
-验证场景：
-
-1. 连续两章更新同一角色境界
-2. 伏笔状态从 active 变为 resolved
-3. 写作上下文中出现正确的长期约束
-4. scratchpad 失败时主流程仍能成功
-
-### 回归测试
-
-必须覆盖：
-
-- `/webnovel-write` 主流程不回归
-- `/webnovel-review` 不受影响
-- 旧项目无 `memory_scratchpad.json` 时可兼容
-
-## 风险与控制策略
-
-### 风险 1：上下文变长
-
-问题：
-
-- 引入 scratchpad 后上下文膨胀
-
-控制：
-
-- 单独预算
-- 分槽位裁剪
-- 只注入相关块
-
-### 风险 2：错误事实长期污染
-
-问题：
-
-- scratchpad 写入错误后会长期影响后续章节
-
-控制：
-
-- 先基于结构化数据生成，而不是纯文本自由总结
-- 保留 evidence 字段
-- 增加 `tentative` 状态
-
-### 风险 3：和现有 ContextManager 职责冲突
-
-问题：
-
-- 逻辑迁移过快，导致重复拼装
-
-控制：
-
-- Phase 3 前只做增量 section
-- Phase 4 再逐步收口到 orchestrator
-
-### 风险 4：影响写作主链稳定性
-
-问题：
-
-- 新模块异常阻断主流程
-
-控制：
-
-- scratchpad 写入采用 best-effort
-- 失败只记录 warning
-- 主流程成功判定不依赖 scratchpad
-
-## 里程碑定义
-
-### M1：Scratchpad 可用
-
-完成标志：
-
-- 可以创建并维护 `.webnovel/memory_scratchpad.json`
-
-### M2：写后自动更新
-
-完成标志：
-
-- 每章写作完成后 scratchpad 自动更新
-
-### M3：写前自动读取
-
-完成标志：
-
-- 写作上下文中包含长期摘要记忆
-
-### M4：统一编排上线
-
-完成标志：
-
-- `MemoryOrchestrator` 成为主读取路径
-
-### M5：冲突管理完成
-
-完成标志：
-
-- 新旧事实状态化，长期记忆可持续演进
-
-## 推荐首批实现范围
-
-如果只做一个最小可落地版本，建议范围限定为：
-
-1. 新增 `memory_scratchpad.json`
-2. 实现 `scratchpad_schema.py`
-3. 实现 `scratchpad_manager.py`
-4. 在 `state_manager.py` 写后更新 scratchpad
-5. 在 `context_manager.py` 写前读取 scratchpad
-
-这五项完成后，就已经有一版可运行的 LIGHT MVP。
-
-## 最终结论
-
-当前项目不需要重构重来，而应该走一条“补层”的路线：
-
-- 保留现有 `state/index/rag/workflow`
-- 新增独立 `scratchpad`
-- 再以 `memory orchestrator` 把三层记忆统一起来
-
-这是对当前工程最稳、最符合现状、也最容易逐步验收的改造方案。

docs/long-term-memory-architecture-v2.md

@@ -1,616 +0,0 @@
-# 长期记忆新架构规划（V2）
-
-## 文档目标
-
-基于长期记忆方向的论文与工程调研结果，重新规划 `webnovel-writer` 的目标架构。
-
-这版架构不再把重点放在“补一个 scratchpad 文件”，而是把系统正式升级为：
-
-- `记忆写入层`
-- `记忆存储层`
-- `记忆编排层`
-- `写作消费层`
-
-四层协同的长期记忆系统。
-
-## 一句话结论
-
-新架构应采用：
-
-- `LIGHT` 的三层记忆分层
-- `Mem0` 的独立 memory layer 思路
-- `Zep / Graphiti` 的时态事实与关系建模
-
-也就是说，目标不是“在 ContextManager 上继续堆逻辑”，而是：
-
-**把记忆系统独立出来，让 ContextManager 退化成消费记忆编排结果的适配层。**
-
-## 为什么要重规划
-
-旧方案的问题在于：
-
-- 仍然以 `ContextManager` 为中心
-- 更像“现有系统增强”
-- 不够清晰地区分“写记忆”和“读记忆”
-
-基于调研后，新的核心认识是：
-
-1. 长期记忆的关键不只是检索，而是写入与更新
-2. 长期记忆必须有自己的生命周期管理
-3. 事实、关系、时间线应当进入同一记忆体系
-4. 上下文组装只是消费层，不应继续承担全部核心职责
-
-## 新架构核心原则
-
-### 1. 记忆系统独立化
-
-新增独立 `memory` 子系统，负责：
-
-- 记忆抽取
-- 记忆归档
-- 记忆压缩
-- 记忆检索
-- 冲突裁决
-
-### 2. 记忆分层化
-
-固定分成三层：
-
-- `Working Memory`
-- `Episodic Memory`
-- `Semantic/Scratchpad Memory`
-
-### 3. 时态事实化
-
-角色状态、关系、势力、伏笔等信息都必须支持：
-
-- 当前有效
-- 历史版本
-- 变更时间
-- 来源证据
-
-### 4. 消费与存储解耦
-
-- `ContextManager` 只负责消费记忆编排结果
-- 写作技能/查询技能不直接拼接多源原始数据
-
-## 目标总架构
-
-```text
-┌──────────────────────────────────────────────────────────────┐
-│                    Skills / Agents / Dashboard              │
-│   write / review / query / resume / dashboard              │
-└──────────────────────────┬───────────────────────────────────┘
-                           │
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                    Context Facade Layer                     │
-│  ContextManager / extract_chapter_context / query adapter   │
-│  只负责接收 Memory Orchestrator 输出并适配不同命令           │
-└──────────────────────────┬───────────────────────────────────┘
-                           │
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                    Memory Orchestrator                      │
-│  统一读取 Working / Episodic / Semantic Memory             │
-│  做预算控制、相关性过滤、冲突裁决、输出 context pack         │
-└───────────────┬───────────────────────┬──────────────────────┘
-                │                       │
-                ▼                       ▼
-     ┌───────────────────┐   ┌───────────────────────────────┐
-     │ Working Memory    │   │ Long-Term Memory Layer        │
-     │ 近期写作上下文      │   │ Episodic + Semantic           │
-     └───────────────────┘   └───────────────────────────────┘
-                                          │
-                                          ▼
-                       ┌──────────────────────────────────────┐
-                       │ Memory Write Pipeline                │
-                       │ Chapter result -> extract -> update  │
-                       └──────────────────────────────────────┘
-                                          │
-                                          ▼
-                       ┌──────────────────────────────────────┐
-                       │ Memory Storage Layer                 │
-                       │ state/index/vectors/scratchpad/graph │
-                       └──────────────────────────────────────┘
-```
-
-## 四层模型
-
-## 1. 记忆写入层
-
-这是新架构中最重要的新层。
-
-### 职责
-
-- 从章节产物中提取长期有效信息
-- 判断哪些信息进入哪种记忆层
-- 对已有事实做更新、失效、冲突标记
-- 生成可供后续读取的标准化记忆项
-
-### 写入入口
-
-主入口仍然挂在 Step 5 / Data Agent 完成之后。
-
-输入来源：
-
-- `entities_new`
-- `entities_appeared`
-- `state_changes`
-- `relationships_new`
-- `chapter_meta`
-- `summary`
-- `plot_threads`
-- 后续可扩展：审查报告、用户偏好、人工修订
-
-### 建议新增模块
-
-```text
-scripts/data_modules/memory/
-├── write_pipeline.py
-├── extractors/
-│   ├── fact_extractor.py
-│   ├── relationship_extractor.py
-│   ├── timeline_extractor.py
-│   └── promise_extractor.py
-```
-
-### 设计理由
-
-这部分吸收的是 `Mem0` 的思路：
-
-- 记忆不是原样存对话
-- 而是先做显著信息提炼，再写入 memory layer
-
-## 2. 记忆存储层
-
-新架构不废弃现有存储，而是重新定义职责。
-
-### 2.1 `state.json`
-
-继续保留，但职责进一步收缩为：
-
-- 当前写作运行态
-- 主角快照
-- 进度
-- strand tracker
-- 少量即时风险提示
-
-不再承载长期知识沉淀。
-
-### 2.2 `index.db`
-
-继续作为结构化事实库，但要明确升级为：
-
-- `episodic structured memory`
-
-主要存：
-
-- 实体
-- 别名
-- 关系
-- 关系事件
-- 状态变化
-- chapter/meta
-- 追读力和审查指标
-
-### 2.3 `vectors.db`
-
-继续作为：
-
-- `episodic retrieval memory`
-
-主要存：
-
-- 章节摘要
-- 场景切片
-- 后续可扩展：
-  - 长期摘要块 embedding
-  - 伏笔块 embedding
-  - 角色关系摘要块 embedding
-
-### 2.4 `memory_scratchpad.json`
-
-保留，但重新定义为：
-
-- `semantic memory cache`
-
-它不应该只是一个杂项摘要文件，而应该是一个可压缩、高密度、面向消费的长期摘要缓存。
-
-建议结构：
-
-```json
-{
-  "character_state": [],
-  "story_state": [],
-  "world_rules": [],
-  "timeline": [],
-  "open_loops": [],
-  "reader_promises": [],
-  "active_constraints": [],
-  "meta": {}
-}
-```
-
-### 2.5 `memory_graph.db` 或图表扩展
-
-这是新规划中和旧方案最大的差异之一。
-
-建议新增图记忆层，哪怕初期只是 SQLite 表，也要预留语义：
-
-- 实体节点
-- 关系边
-- 时间有效性
-- 来源章节
-- 版本变化
-
-形式上可以有两种方案：
-
-1. 保守方案：
-   - 先继续放在 `index.db`
-   - 新增 graph-oriented tables
-2. 进阶方案：
-   - 新建 `memory_graph.db`
-
-第一阶段建议用保守方案，避免基础设施过重。
-
-## 3. 记忆编排层
-
-这是新的核心中台。
-
-### 职责
-
-- 按章节或查询意图读取三层记忆
-- 根据任务类型动态分配预算
-- 合并 working / episodic / semantic memory
-- 对冲突事实做优先级裁决
-- 输出标准化 context pack
-
-### 建议新增模块
-
-```text
-scripts/data_modules/memory/
-├── orchestrator.py
-├── budget_manager.py
-├── relevance_filter.py
-├── conflict_resolver.py
-└── memory_pack.py
-```
-
-### 三层记忆定义
-
-#### Working Memory
-
-来源：
-
-- 本章大纲
-- 最近摘要
-- 当前状态
-- 当前 chapter guidance
-- 当前债务与风险
-
-特点：
-
-- 强时效
-- 高优先级
-- 不需要长期存档
-
-#### Episodic Memory
-
-来源：
-
-- `index.db`
-- `vectors.db`
-- `summaries`
-
-特点：
-
-- 保留历史证据
-- 可追溯
-- 适合回答“发生过什么”
-
-#### Semantic Memory
-
-来源：
-
-- `memory_scratchpad.json`
-- 图记忆层生成的高阶摘要
-
-特点：
-
-- 保留稳定抽象事实
-- 适合回答“当前应该认为是真的是什么”
-
-### 编排流程
-
-```text
-写作请求
-   │
-   ▼
-意图分析
-   │
-   ├── chapter_write
-   ├── consistency_check
-   ├── continuity_query
-   └── review
-   ▼
-Memory Orchestrator
-   │
-   ├── load working memory
-   ├── retrieve episodic memory
-   ├── load semantic memory
-   ├── resolve conflicts
-   ├── apply budget
-   └── build final pack
-```
-
-## 4. 写作消费层
-
-这一层包括：
-
-- `ContextManager`
-- `extract_chapter_context.py`
-- `/webnovel-write`
-- `/webnovel-query`
-- `/webnovel-review`
-
-### 新职责
-
-- 不直接拼装底层数据
-- 只根据任务类型请求 memory pack
-- 将 memory pack 渲染成：
-  - text
-  - json
-  - prompt context
-
-### 这意味着什么
-
-`ContextManager` 不再是记忆逻辑中心，而是：
-
-- 一个适配器
-- 一个模板层
-- 一个输出格式层
-
-## 模块目录规划
-
-建议新增独立目录：
-
-```text
-webnovel-writer/scripts/data_modules/
-├── memory/
-│   ├── __init__.py
-│   ├── schema.py
-│   ├── storage.py
-│   ├── write_pipeline.py
-│   ├── orchestrator.py
-│   ├── conflict_resolver.py
-│   ├── relevance_filter.py
-│   ├── budget_manager.py
-│   ├── summary_compactor.py
-│   └── graph_memory.py
-```
-
-### 各模块职责
-
-#### `schema.py`
-
-- 定义记忆项结构
-- 定义状态字段与版本字段
-
-#### `storage.py`
-
-- 封装对 `memory_scratchpad.json`、`index.db`、`vectors.db` 的统一读写
-
-#### `write_pipeline.py`
-
-- 章节完成后写入记忆
-
-#### `orchestrator.py`
-
-- 对外提供统一 `build_memory_pack()`
-
-#### `conflict_resolver.py`
-
-- 处理 active / outdated / contradicted / tentative
-
-#### `relevance_filter.py`
-
-- 按章节目标、大纲关键词、实体中心过滤长期记忆
-
-#### `budget_manager.py`
-
-- 控制不同任务类型的 token 预算
-
-#### `summary_compactor.py`
-
-- 负责 scratchpad 压缩和去噪
-
-#### `graph_memory.py`
-
-- 封装关系图、时间线和事实图语义
-
-## 数据模型重定义
-
-### 统一记忆项
-
-建议引入统一记忆对象结构：
-
-```json
-{
-  "id": "mem-001",
-  "layer": "semantic",
-  "category": "character_state",
-  "subject": "xiaoyan",
-  "field": "realm",
-  "value": "筑基三层",
-  "status": "active",
-  "source": {
-    "chapter": 128,
-    "type": "state_change"
-  },
-  "evidence": [
-    "state_change:xiaoyan:realm:128",
-    "summary:ch0128"
-  ],
-  "updated_at": "2026-03-19T20:00:00+08:00",
-  "confidence": 0.95
-}
-```
-
-### 为什么需要统一记忆项
-
-这样可以统一处理：
-
-- 角色状态
-- 世界规则
-- 伏笔
-- 读者承诺
-- 关系变化
-- 时间线事件
-
-## 新架构的数据流
-
-## 写入流
-
-```text
-正文完成
-   │
-   ▼
-Data Agent
-   │
-   ├── 原有写入：state/index/vectors/summaries
-   └── Memory Write Pipeline
-           │
-           ├── 提取长期事实
-           ├── 合并到 semantic memory
-           ├── 更新 graph memory
-           ├── 标记冲突和过期项
-           └── 刷新 scratchpad cache
-```
-
-## 读取流
-
-```text
-第N章写作 / 查询 / 审查
-   │
-   ▼
-Memory Orchestrator
-   │
-   ├── Working Memory
-   ├── Episodic Memory
-   ├── Semantic Memory
-   ├── Graph Memory
-   └── Conflict Resolution
-   ▼
-Memory Pack
-   ▼
-ContextManager / Query Renderer / Review Renderer
-```
-
-## 对现有模块的角色调整
-
-### `ContextManager`
-
-从：
-
-- 核心上下文拼装器
-
-变为：
-
-- memory pack 渲染器
-- 模板权重应用器
-
-### `StateManager`
-
-从：
-
-- 运行态状态 + 部分知识写入
-
-变为：
-
-- 运行态状态管理器
-- 章节结果写入入口
-- 记忆写入流水线触发器
-
-### `IndexManager`
-
-从：
-
-- 结构化索引库
-
-变为：
-
-- episodic structured memory backend
-
-### `RAGAdapter`
-
-从：
-
-- 场景检索器
-
-变为：
-
-- episodic retrieval backend
-
-## 推荐实施顺序
-
-### Stage 1：搭 memory 子系统骨架
-
-- 新增 `memory/` 目录
-- 定义统一记忆 schema
-- 抽出 scratchpad 存储
-
-### Stage 2：接写入管线
-
-- 章节写后自动更新 semantic memory
-- 建立冲突状态字段
-
-### Stage 3：接编排器
-
-- `ContextManager` 改为消费 orchestrator
-- `extract_chapter_context.py` 改为基于 memory pack 输出
-
-### Stage 4：接图记忆
-
-- 先在 `index.db` 扩展 graph-like tables
-- 后续如有必要再拆独立图库
-
-### Stage 5：扩展 dashboard 和观测
-
-- 查看长期事实
-- 查看冲突项
-- 查看记忆命中来源
-
-## 关键取舍
-
-### 不建议做的事
-
-- 继续把所有逻辑堆进 `ContextManager`
-- 只加一个 `memory_scratchpad.json` 就认为问题解决
-- 第一阶段就引入完整图数据库
-- 直接照搬 Letta/MemGPT 的 agent runtime
-
-### 建议做的事
-
-- 把 memory 作为独立子系统设计
-- 先解决记忆写入问题，再优化读取
-- 用统一记忆项结构降低后续复杂度
-- 让图语义先以轻量方式落在现有 SQLite 中
-
-## 最终目标
-
-最终系统应具备以下能力：
-
-1. 写完一章后，系统能自动沉淀长期有效事实
-2. 多章之后，系统能区分历史事实和当前事实
-3. 写作前，系统能自动提供“近期上下文 + 历史证据 + 长期约束”
-4. 当关系、设定、伏笔变化时，系统能保留版本与证据
-5. 审查和查询模块能共享同一套长期记忆底座
-
-## 总结
-
-基于调研，新的最佳架构不是“在现有系统上补一个功能点”，而是：
-
-**把长期记忆升级为一个独立子系统，并让现有写作系统围绕它重新分层。**
-
-这版架构比旧方案更适合长期演化，也更符合当前长期记忆研究和工程实践的主流方向。

docs/memory/long-term-memory-architecture-v2.md

@@ -0,0 +1,385 @@
+# 长期记忆现有架构设计
+
+## 文档定位
+
+本文只描述当前仓库里已经落地、并被主写作链路实际消费的长期记忆架构。
+
+这里不再保留历史改造计划，也不把理想态蓝图混进来。判断标准只有一个：当前代码里是否真实存在、是否已经接入主链路。
+
+## 一句话结论
+
+当前长期记忆的真实实现是：
+
+- 以 `.webnovel/memory_scratchpad.json` 作为长期语义记忆缓存
+- 以 `index.db`、`summaries/`、`state.json` 作为近期状态和历史证据层
+- 由 `MemoryOrchestrator` 组装 `working / episodic / semantic` 三层结果
+- 再由 `ContextManager`、`extract_chapter_context.py` 和 `MemoryContractAdapter` 对外消费
+
+它已经是一条可运行的数据链，但还不是完全独立的记忆子系统。
+
+## 核心边界
+
+### 已经属于长期记忆主链路
+
+- `scripts/data_modules/memory/schema.py`
+- `scripts/data_modules/memory/store.py`
+- `scripts/data_modules/memory/writer.py`
+- `scripts/data_modules/memory/orchestrator.py`
+- `scripts/data_modules/memory/bootstrap.py`
+- `scripts/data_modules/memory/compactor.py`
+- `scripts/data_modules/memory_contract_adapter.py`
+- `scripts/memory_cli.py`
+- `scripts/data_modules/context_manager.py` 中的 `long_term_memory` 注入
+
+### 仍然是旁路或相邻能力
+
+- `.webnovel/project_memory.json`
+- `/webnovel-learn` 产出的项目经验记忆
+- `ContextManager` 里的 `memory` section
+
+这部分会被上下文一起读取，但不等同于 `memory_scratchpad.json` 这条长期记忆主链路。
+
+## 现有架构图
+
+```text
+章节结果 / 审查产物
+        │
+        ▼
+MemoryWriter
+        │
+        ├── 写入 memory_scratchpad.json
+        ├── 维护 active/outdated/contradicted/tentative
+        └── 触发压缩与冲突检查
+
+state.json / index.db / summaries/ / memory_scratchpad.json
+        │
+        ▼
+MemoryOrchestrator
+        │
+        ├── working_memory
+        ├── episodic_memory
+        ├── semantic_memory
+        └── long_term_facts / active_constraints / warnings / stats
+
+        ▼
+ContextManager
+        │
+        ├── long_term_memory section
+        ├── extract_chapter_context.py
+        └── MemoryContractAdapter / memory CLI
+
+        ▼
+webnovel-write / review / query / 其他消费端
+```
+
+## 数据分层
+
+### 1. Working Memory
+
+当前不是单独存储，而是运行时临时拼装，主要来源于：
+
+- 本章章纲
+- 最近几章摘要
+- `state.json` 中的主角状态、情节线程、待消歧项
+
+这层由 `MemoryOrchestrator._build_working_memory()` 生成。
+
+### 2. Episodic Memory
+
+当前主要来自 `index.db` 的近期结构化证据，而不是独立的通用历史检索系统。
+
+主要来源：
+
+- 最近状态变化
+- 最近关系变化
+- 最近出场记录
+
+这层由 `MemoryOrchestrator._build_episodic_memory()` 生成，特点是偏“最近证据”，不是全量全库语义召回。
+
+### 3. Semantic Memory
+
+当前长期记忆的核心存储是 `.webnovel/memory_scratchpad.json`。
+
+它由 `ScratchpadManager` 读写，按分类分桶保存：
+
+- `character_state`
+- `story_facts`
+- `world_rules`
+- `timeline`
+- `open_loops`
+- `reader_promises`
+- `relationships`
+
+每条记忆项统一使用 `MemoryItem` 结构，核心字段包括：
+
+- `id`
+- `layer`
+- `category`
+- `subject`
+- `field`
+- `value`
+- `payload`
+- `status`
+- `source_chapter`
+- `evidence`
+- `updated_at`
+
+支持的状态为：
+
+- `active`
+- `outdated`
+- `contradicted`
+- `tentative`
+
+## 写入链路
+
+### 1. 章节结果进入 `MemoryWriter`
+
+写作主链在章节提交后，会把结构化结果交给 `MemoryWriter.update_from_chapter_result()`。
+
+当前已实现的写入来源包括：
+
+- `state_changes`
+- `entities_new`
+- `relationships_new`
+- `chapter_meta.hook`
+- `memory_facts`
+
+其中 `memory_facts` 用于更深一层的结构化映射，当前支持：
+
+- `timeline_events`
+- `world_rules`
+- `open_loops`
+- `reader_promises`
+
+### 2. `ScratchpadManager` 做去重与状态收敛
+
+`ScratchpadManager.upsert_item()` 的核心规则是：
+
+- 按分类主键规则计算去重 key
+- 同 key 的旧值降级为 `outdated`
+- 新值写成当前有效项
+- 保留旧值用于审计和回溯
+
+当前各分类的主键规则由 `schema.py` 统一定义，例如：
+
+- `character_state`：`subject + field`
+- `relationship`：`subject + field`
+- `world_rule`：`subject + field`
+- `open_loop`：`subject`
+
+### 3. 超阈值时压缩
+
+`ScratchpadManager.save()` 会在达到阈值后调用 `compactor.py`。
+
+当前压缩策略包括：
+
+- 同 key 的 `outdated` 只保留最新一条
+- 清理已回收的伏笔
+- 过旧时间线合并为摘要型 `story_fact`
+- 总量仍超限时按状态和新鲜度做全局截断
+
+### 4. 历史项目可回填
+
+`memory bootstrap` 会从现有 `index.db` 与 `summaries/` 回填出一版初始长期记忆。
+
+当前可回填的内容包括：
+
+- 角色当前状态
+- 历史状态变化
+- 最近关系
+- 摘要中的“伏笔”区块
+
+## 读取与编排链路
+
+### 1. `MemoryOrchestrator` 负责统一出包
+
+`MemoryOrchestrator.build_memory_pack()` 是当前长期记忆的统一读取入口。
+
+它会做四件事：
+
+1. 构建 `working_memory`
+2. 构建 `episodic_memory`
+3. 读取 `memory_scratchpad.json` 中的 `active` 项
+4. 过滤、限额、补充告警与统计信息
+
+输出的核心字段包括：
+
+- `working_memory`
+- `episodic_memory`
+- `semantic_memory`
+- `long_term_facts`
+- `active_constraints`
+- `recent_changes`
+- `warnings`
+- `stats`
+
+其中：
+
+- `semantic_memory` 与 `long_term_facts` 当前是同一批可直接注入的长期语义事实
+- `active_constraints` 主要抽取 `world_rule` 和 `open_loop`
+- `warnings` 当前主要用于暴露记忆冲突
+
+### 2. 当前过滤规则
+
+`semantic_memory` 不是全量注入，而是先做一轮轻量过滤。
+
+现有过滤依据：
+
+- 记忆项的 `subject / field / value` 是否出现在本章章纲中
+- 来源章节是否落在配置允许的窗口内
+
+然后再按预算截断。当前预算由 `budget.py` 和配置项共同控制。
+
+## 消费层
+
+### 1. `ContextManager`
+
+`ContextManager` 仍然是写作上下文的总装配器。
+
+当 `context_use_memory_orchestrator=true` 时，它会：
+
+- 调用 `MemoryOrchestrator.build_memory_pack()`
+- 把结果注入到 `long_term_memory` section
+- 再和 `reader_signal / genre_profile / writing_guidance / plot_structure` 一起组装最终 context
+
+所以当前真实关系不是“记忆系统完全替代 ContextManager”，而是“记忆系统已经接入 ContextManager”。
+
+### 2. `extract_chapter_context.py`
+
+写作前置上下文脚本会从 `ContextManager` 里抽取几个关键 section，其中已经包含：
+
+- `reader_signal`
+- `genre_profile`
+- `writing_guidance`
+- `plot_structure`
+- `long_term_memory`
+
+这意味着长期记忆已经进入主写作上下文，而不是停留在独立实验脚本里。
+
+### 3. `MemoryContractAdapter`
+
+`MemoryContractAdapter` 是对外的薄适配层。
+
+它会把现有模块包装成统一接口，提供：
+
+- `commit_chapter()`
+- `load_context()`
+- `query_entity()`
+- `query_rules()`
+- `read_summary()`
+- `get_open_loops()`
+- `get_timeline()`
+
+这层的意义是：当前记忆链路已经有稳定接口，但底层存储仍然复用现有 `state / index / scratchpad / summaries`。
+
+### 4. CLI
+
+当前长期记忆相关的 CLI 分成两类：
+
+- `webnovel.py memory ...`
+- `memory_cli.py`
+
+常用命令包括：
+
+- `memory stats`
+- `memory query`
+- `memory dump`
+- `memory conflicts`
+- `memory bootstrap`
+- `memory update`
+
+## 存储职责划分
+
+### `state.json`
+
+负责运行时状态，不负责长期知识沉淀。
+
+当前主要承载：
+
+- 主角快照
+- 进度
+- 情节线程
+- 待消歧项
+
+### `index.db`
+
+负责结构化历史证据。
+
+当前长期记忆在读取 `episodic_memory` 时，主要从这里拿：
+
+- 状态变化
+- 关系
+- 出场记录
+- 部分追读力与审查数据
+
+### `summaries/`
+
+负责章节摘要与最近写作上下文。
+
+在长期记忆链路里，它有两个作用：
+
+- 作为 `working_memory` 的最近摘要来源
+- 在 `bootstrap` 时用于回填“伏笔”类开放问题
+
+### `memory_scratchpad.json`
+
+负责长期语义记忆缓存，是当前长期记忆的主真源。
+
+### `project_memory.json`
+
+负责项目经验/学习沉淀，当前仍是独立旁路，不与 `memory_scratchpad.json` 合并。
+
+## 当前已实现的关键能力
+
+- 长期记忆已可持久化读写
+- 已有统一 schema、状态枚举和分桶结构
+- 已有冲突检测与简单状态降级
+- 已有压缩器防止 scratchpad 持续膨胀
+- 已能把长期记忆注入主写作上下文
+- 已有 CLI 查询、回填和手工更新入口
+- 已有 `MemoryContractAdapter` 作为稳定外部接口
+
+## 当前边界与限制
+
+### 1. 不是完全独立的 memory runtime
+
+当前仍依赖：
+
+- `ContextManager` 做最终装配
+- `index.db` 提供近期历史证据
+- `state.json` 提供运行时快照
+
+### 2. `episodic_memory` 偏近期，不是全量历史召回
+
+目前更像“最近结构化证据层”，不是统一的跨全书语义回忆系统。
+
+### 3. `semantic_memory` 仍是 JSON scratchpad
+
+当前没有单独的长期语义向量层，也没有图数据库层。
+
+### 4. `project_memory.json` 与长期记忆主链还未统一
+
+项目经验记忆和剧情长期记忆现在是两套并行数据源。
+
+### 5. 冲突裁决还是轻量规则
+
+当前主要是：
+
+- 主键去重
+- 旧值降级
+- 冲突统计
+
+还没有更重的跨章节语义裁决流程。
+
+## 结论
+
+当前仓库里的长期记忆已经从“方案讨论”进入“可运行架构”阶段，但它的真实定位应当是：
+
+- 已接入主写作链路
+- 已有持久化、编排、消费和运维入口
+- 仍然建立在现有 `ContextManager + state/index/summaries` 生态之上
+
+因此，这份文档只保留“现状架构说明”。
+
+历史计划文档已经移除；如果后续继续演进，应重新按当时的真实代码状态单独写新 spec。

docs/storyteller-implementation-plan.md

@@ -1,406 +0,0 @@
-# STORYTELLER 落地实施方案
-
-## 文档目标
-
-本文档基于前面对 `STORYTELLER` 论文、当前 `webnovel-writer` 架构和落地边界的讨论，给出一份从 `skills` 与 `agents` 视角出发的修正版实施方案。
-
-目标不是复制论文原系统，而是以最小破坏、最高复用的方式，将“中层情节结构”前移到规划阶段，并让写作、审查、数据回写围绕结构化章纲形成闭环。
-
-## 一句话结论
-
-最优方案不是新增独立的 `webnovel-structure` 主流程，而是：
-
-- 升级 `webnovel-plan`，输出结构化详细大纲
-- 增强 `context-agent`，把结构化章纲组装进写作包
-- 增强 `continuity-checker` 与 `consistency-checker`，分别负责节点覆盖与结构冲突
-- 增强 `data-agent`，负责落库覆盖结果与偏差说明
-
-这样可以在不打碎现有系统的前提下，为写作链补上 `STORYTELLER` 最核心的中层结构层。
-
-## 核心原则
-
-1. 不新增独立主流程 `webnovel-structure`
-2. 结构前移到 `webnovel-plan`
-3. `context-agent` 只聚合，不生成节点
-4. `continuity-checker` 负责结构覆盖
-5. `consistency-checker` 负责结构冲突
-6. `data-agent` 负责落库，不做主判断
-7. 全程向后兼容，无节点章纲照常运行
-
-## 总体架构
-
-```text
-/webnovel-init
-    -> 初始化项目骨架与状态
-
-/webnovel-plan
-    -> 节拍表
-    -> 时间线
-    -> 结构化详细大纲（新增节点字段）
-
-/webnovel-write
-    -> Step 0.5 轻量节点预检
-    -> Step 1 context-agent 组装写作包
-    -> Step 2A writer 按节点扩写
-    -> Step 3 review agents
-    -> Step 5 data-agent 持久化覆盖与偏差
-```
-
-## Skills 视角实施方案
-
-### 1. `webnovel-init`
-
-定位：保留，不做大改。
-
-职责：
-
-- 初始化 `.webnovel/state.json`
-- 初始化 `index.db / vectors.db`
-- 初始化 `大纲/`、`设定集/`、摘要目录等骨架
-
-建议新增但不强制：
-
-- 为后续结构化章纲预留约定说明
-- 为 `index.db` 预留结构化章纲缓存或索引的升级入口
-
-### 2. `webnovel-plan`
-
-定位：本次改造的主战场。
-
-目标：把现有“详细大纲”升级成“结构化详细大纲”。
-
-现有输出保留：
-
-- `大纲/第{volume_id}卷-节拍表.md`
-- `大纲/第{volume_id}卷-时间线.md`
-- `大纲/第{volume_id}卷-详细大纲.md`
-
-每章新增字段：
-
-- `章节起点（CBN）`
-- `推进节点（CPNs）`
-- `章节终点（CEN）`
-- `必须覆盖节点`
-- `本章禁区`
-
-节点格式建议：
-
-`主体 | 动作/变化 | 对象/结果`
-
-示例：
-
-- `萧炎 | 抵达 | 迦南学院入口`
-- `萧炎 | 展示 | 异火控制力`
-- `药老 | 对萧炎产生 | 明确兴趣`
-
-节点数量约束：
-
-- `1 个 CBN`
-- `2-4 个 CPN`
-- `1 个 CEN`
-
-必须覆盖规则：
-
-- 每章必须覆盖节点最多 `4` 个
-- 建议为：`CBN + CEN + 1~2 个核心 CPN`
-
-章间衔接规则：
-
-- 相邻章节 `CEN -> 下一章 CBN` 必须逻辑承接
-- 若为时间跳转章，需在时间字段中明确说明
-
-本章禁区规则：
-
-- 不超过 `5` 条
-- 只写硬禁区，不写风格建议
-
-批次建议：
-
-- 默认 `10章/批`
-- 复杂题材 `8章/批`
-- 简单升级流上限 `12章/批`
-
-不建议：
-
-- 再单独新增常规 `/webnovel-structure`
-- 在 `plan` 之外再维护一份平行节点文件作为主数据源
-
-### 3. `webnovel-write`
-
-定位：保留为唯一主写作入口。
-
-建议流程：
-
-1. `Step 0.5` 轻量节点预检
-2. `Step 1` `context-agent` 读取结构化章纲、状态和记忆，组装写作包
-3. `Step 2A` writer 按 `CBN -> CPNs -> CEN` 扩写正文
-4. `Step 3` review agents 执行结构覆盖与设定一致性检查
-5. `Step 5` `data-agent` 持久化覆盖结果与偏差说明
-
-新增 Step 0.5 的边界：
-
-- 只检查主角或 POV 角色相关节点
-- 第一版仅检查地点、境界/实力层级
-- 仅附加警告，不阻断流程
-- 不做复杂关系推理或自动重规划
-
-### 4. `webnovel-review`
-
-定位：保留，主要用于区间复盘和独立质量检查。
-
-建议增强：
-
-- 支持读取结构化章纲中的节点字段
-- 支持基于章节范围回看 `plan vs actual` 偏移趋势
-
-## Agents 视角实施方案
-
-### 1. `context-agent`
-
-定位：保留，增强为“结构化章纲聚合器”。
-
-新增读取：
-
-- `CBN`
-- `CPNs`
-- `CEN`
-- `必须覆盖节点`
-- `本章禁区`
-
-新增输出板块：
-
-- `情节结构`
-  - `章节起点`
-  - `推进节点`
-  - `章节终点`
-  - `必须覆盖节点`
-  - `本章禁区`
-
-Context Contract 新增字段：
-
-- `plot_structure`
-  - `cbn`
-  - `cpns`
-  - `cen`
-  - `mandatory_nodes`
-  - `prohibitions`
-
-Step 2A 节拍映射：
-
-- 有节点时：`CBN触发 -> CPN推进 -> CPN受阻/变化 -> CEN收束 -> 章末钩子`
-- 无节点时：保持旧节拍
-
-红线新增：
-
-- 情节结构与任务书方向冲突
-
-边界：
-
-- 不生成节点
-- 不修改节点
-- 只负责读取、聚合、压缩成写作包
-
-### 2. `plot-node-agent`
-
-当前判断：第一阶段不作为必须组件。
-
-原因：
-
-- 既然决定把结构前移到 `plan`
-- 那 `CBN/CPN/CEN` 的主产物应由 `plan` 直接生成
-- 不需要在 `write` 阶段再新增重量级 agent 重复规划
-
-保留可能性：
-
-- 若后续发现章纲与正文脱节严重
-- 再考虑引入轻量 `plot-node-agent`
-- 只做写前局部修正，不做整章重规划
-
-### 3. `continuity-checker`
-
-定位：负责“结构覆盖”和“事件承接”。
-
-新增检查：
-
-1. `CBN 承接`
-2. `CEN 落地`
-3. `必须节点覆盖`
-4. `可选节点覆盖（仅统计）`
-
-输出：
-
-- 节点覆盖表
-- 覆盖评级：`A / B / C / F`
-
-成功标准：
-
-- 有节点时，覆盖评级至少 `B`
-
-边界：
-
-- 不判断设定是否越界
-- 不判断禁区是否违背世界规则
-- 只判断“写到了没有、接顺了没有、收住了没有”
-
-### 4. `consistency-checker`
-
-定位：负责“结构与设定冲突”。
-
-新增检查：
-
-1. 是否违反 `本章禁区`
-2. 正文开头方向是否与 `CBN` 冲突
-3. 正文结尾方向是否与 `CEN` 冲突
-4. 关键节点对应的能力、身份、地点是否违背设定
-
-严重度建议：
-
-- 禁区违反：`high`
-- `CEN` 方向冲突：`medium`
-- `CBN` 方向冲突：`medium`
-
-边界：
-
-- 不负责覆盖率评级
-- 不与 `continuity-checker` 重叠
-
-### 5. `ooc-checker`
-
-定位：保留。
-
-增强方式：
-
-- 读取更结构化的角色状态上下文
-- 结合当前章的节点、角色行为红线和本章变化判断 OOC 风险
-
-### 6. `reader-pull-checker / high-point-checker / pacing-checker`
-
-定位：保留，但执行层收口。
-
-建议：
-
-- 默认写作流程强制启用：
-  - `consistency-checker`
-  - `continuity-checker`
-  - `ooc-checker`
-- 其余按题材、章节类型或区间复盘按需启用
-
-原因：
-
-- 新架构已经把部分“晚审”前移到 `plan`
-- 再全量六并发常驻会过重
-
-### 7. `data-agent`
-
-定位：从“主判断者”改成“持久化与偏差记录器”。
-
-继续保留：
-
-- 实体抽取
-- 状态变更
-- 关系更新
-- 摘要生成
-- `memory facts`
-- 向量切片
-
-新增 Step 5B：
-
-- 写入 `plot_coverage`
-- 写入 `plan_deviation_note`
-
-关键规则：
-
-- `data-agent` 不自己重复做完整覆盖判断
-- 优先消费 `continuity-checker` 与 `consistency-checker` 的结果，再写入 `chapter_meta`
-
-推荐写入结构：
-
-```json
-{
-  "plot_coverage": {
-    "cbn_covered": true,
-    "cen_covered": true,
-    "mandatory_hit_rate": 1.0,
-    "coverage_grade": "A",
-    "prohibitions_violated": []
-  },
-  "plan_deviation_note": ""
-}
-```
-
-填写规则：
-
-- `mandatory_hit_rate < 0.8` 时必须填写 `plan_deviation_note`
-- 存在禁区违反时必须填写 `plan_deviation_note`
-
-边界：
-
-- 不重规划后续章纲
-- 不做复杂 SVO 主链重建
-- 不代替 review
-
-## 实施顺序
-
-### Phase 1：最小闭环
-
-1. `skills/webnovel-plan/SKILL.md`
-2. `agents/context-agent.md`
-3. `skills/webnovel-write/SKILL.md`
-4. `agents/continuity-checker.md`
-5. `agents/consistency-checker.md`
-6. `agents/data-agent.md`
-
-原因：
-
-- 所有下游都依赖 `plan` 的新字段
-- 其余模块都只是消费这些字段
-
-### Phase 2：轻量状态增强
-
-1. 在 `index.db` 中补充结构化章纲缓存或索引
-2. 为 `context-agent` 增加“最近实际承接摘要”读取
-3. 为 `review` 增加区间级偏移复盘
-
-### Phase 3：按需局部修正
-
-1. 若出现大量“章纲和正文脱节”
-2. 再评估是否引入轻量 `plot-node-agent`
-3. 仅做写前局部修正，不做完整重规划
-
-## 验证方案
-
-1. **结构化章纲验证**
-   - 执行 `/webnovel-plan`
-   - 确认详细大纲新增：
-     - `CBN`
-     - `CPNs`
-     - `CEN`
-     - `必须覆盖节点`
-     - `本章禁区`
-
-2. **写作包验证**
-   - 执行 `/webnovel-write`
-   - 确认 `context-agent` 输出包含“情节结构”板块
-
-3. **审查验证**
-   - 确认 `continuity-checker` 输出节点覆盖评级
-   - 确认 `consistency-checker` 输出禁区/方向冲突检查
-
-4. **数据回写验证**
-   - 确认 `chapter_meta` 写入 `plot_coverage`
-   - 确认偏差时有 `plan_deviation_note`
-
-5. **向后兼容验证**
-   - 用旧章纲执行 `/webnovel-write`
-   - 全流程不阻断、不报错
-
-## 最终判断
-
-这版方案的重点不是“多加一个系统层”，而是：
-
-- 让 `plan` 产出更可执行的章纲
-- 让 `context-agent` 成为结构化章纲聚合器
-- 让 `review` 围绕节点覆盖与结构冲突形成清晰分工
-- 让 `data-agent` 成为持久化和偏差记录器
-
-这条路线既吸收了 `STORYTELLER` 的核心思想，又避免了额外主流程和重复组件的膨胀。

docs/superpowers/README.md

@@ -0,0 +1,25 @@
+# Superpowers 文档导航
+
+本目录存放通过 `superpowers` 工作流沉淀的架构 spec、设计文档与实施计划。
+
+## 目录说明
+
+- [`specs/`](./specs/)：架构设计、重构方案、评审后收敛的规范文档
+- [`plans/`](./plans/)：按 spec 拆解后的实施计划与阶段执行文档
+
+## 当前重点文档
+
+- [`specs/2026-04-09-skills-restructure-and-reference-gaps.md`](./specs/2026-04-09-skills-restructure-and-reference-gaps.md)：技能重构与参考资料缺口规范
+- [`specs/2026-04-12-story-system-pro-max-retrofit-spec.md`](./specs/2026-04-12-story-system-pro-max-retrofit-spec.md)：现有链路上的 Pro Max 架构改造规范
+- [`specs/2026-04-12-webnovel-story-intelligence-system-spec.md`](./specs/2026-04-12-webnovel-story-intelligence-system-spec.md)：最终状态的理想态架构蓝图
+- [`specs/2026-04-12-story-system-evolution-spec.md`](./specs/2026-04-12-story-system-evolution-spec.md)：基于当前系统诊断的现状导向演进规范
+- [`plans/2026-04-12-story-system-phase1-contract-seed.md`](./plans/2026-04-12-story-system-phase1-contract-seed.md)：Story System Phase 1 合同种子层实施计划
+- [`plans/2026-04-12-story-system-phase2-contract-first-runtime.md`](./plans/2026-04-12-story-system-phase2-contract-first-runtime.md)：Story System Phase 2 合同优先运行时实施计划
+- [`plans/2026-04-12-story-system-phase3-chapter-commit-chain.md`](./plans/2026-04-12-story-system-phase3-chapter-commit-chain.md)：Story System Phase 3 章节提交主链实施计划
+- [`plans/2026-04-12-story-system-phase4-event-log-and-override-ledger.md`](./plans/2026-04-12-story-system-phase4-event-log-and-override-ledger.md)：Story System Phase 4 统一事件主链与 Override Ledger 实施计划
+
+## 使用约定
+
+- 新的 spec 统一放到 `specs/`
+- 对应实施计划统一放到 `plans/`
+- 后续写 implementation plan 时，默认需要同步列出相关文档更新项

docs/superpowers/specs/2026-04-09-skills-restructure-and-reference-gaps.md

@@ -0,0 +1,863 @@
+# Webnovel Writer Skills 重构与 Reference 缺口设计
+
+> 日期：2026-04-09
+> 状态：草案 v4.3（v4.2 + Codex 二轮 review 3 处修正）
+> 目标：在 Claude 已具备通用智能与通用写作能力的前提下，重构 `skills/` 体系，并为后续 `references/` 补全提供缺口清单。
+
+---
+
+## 1. 为什么要写一份新的 spec
+
+### 1.1 与 v6 spec 的关系
+
+本 spec 是 `2026-04-02-harness-v6-design.md`（v7）的**补充**，不是替代。
+
+- **v6 spec** 解决主流程架构：废弃/合并、状态机、memory contract、审查流程、迁移退出标准。Phase 1/2A/3/4 已完成。
+- **本 spec** 解决 v6 完成后的文档体系收敛：skills 怎么瘦身、references 怎么设计和补缺。
+- **关于 reference 的设计原则**（渐进式披露、三层内容、按需加载、双轨知识库等），以本 spec 为准。
+
+v6 spec 中的以下设计决策本 spec 继承不变：
+- Write 流程 Step 0.5-6 及状态机
+- reviewer 单 agent + blocking 修复循环
+- memory contract v0/v1 接口
+- 章纲字段草案与 `writer_exposure_policy` 分层
+
+### 1.2 当前问题
+
+旧的 harness v6 spec 主要解决的是迁移问题（现已大部分完成）。当前真正的问题，已经从“主流程能力缺失”转为“文档体系不够收敛”：
+
+1. `skills/` 的结构风格混杂，有的像主链 SOP，有的像命令手册，有的像小型 spec。
+2. `references/` 的职责不稳定：有的在重复 Claude 本来就知道的常识，有的又缺少针对模型缺陷的关键约束。
+3. `skills`、`references`、`scripts` 的边界不够清楚，导致信息重复、维护成本高、补充方向模糊。
+4. 对中文网文场景下的模型缺陷补偿不足，例如人物命名复用、套路化桥段复用、题材语汇漂移、对话口吻趋同等。
+
+因此需要一份新的 spec，不再延续“迁移”叙事，而是回答一个更直接的问题：
+
+**在 Claude 已经足够聪明的前提下，这个系统还需要哪些最小必要 skills，以及哪些 references 缺口值得补？**
+
+---
+
+## 2. 核心设计哲学
+
+### 2.1 Claude 足够聪明
+
+默认前提：Claude 已具备以下能力，不需要在技能文档里重复教学：
+- 通用写作能力
+- 通用总结、提炼、润色能力
+- 常见叙事技巧与常见角色塑造常识
+- 常规软件工程与文件读写能力
+- 一般性的“如何提问用户”“如何组织步骤”“如何做检查”的能力
+
+因此，`skills` 和 `references` 不应该承载这些通用常识。
+
+### 2.2 文档只补“Claude 不稳定、不知道、易做错”的部分
+
+应保留在文档里的内容，必须至少满足以下一种：
+- **项目私有知识**：本仓库特有的状态字段、CLI、文件路径、契约、产物位置。
+- **模型缺陷补偿**：Claude 高频犯错点，且不能稳定靠通识解决。
+- **题材/平台特异约束**：中文网文场景下的特殊要求、风格偏好、禁区。
+- **流程闸门**：必须显式满足的步骤顺序、验证条件、失败恢复。
+- **高价值参考**：真实范例、反例、命名规则、反模板约束等。
+
+不满足上述条件的信息，原则上不应出现在 `skills` 或 `references` 中。
+
+### 2.3 Reference 设计四原则
+
+以下四条原则是 reference 体系设计的核心约束，所有 reference 新增、保留、删除决策都必须以此为准。
+
+#### 原则 1：渐进式披露
+
+Reference 不是按“知识主题”组织，而是按“哪个 skill 的哪个 step 在执行时需要什么指导”组织。
+
+- 每个 reference **应尽量**能映射到至少一个具体的 skill + step。
+- 若为跨 skill 通用缺陷补偿，应明确**主服务场景**与**次服务场景**。
+- Skill 的引用加载策略必须写清楚“Step N 遇到 X 条件时加载 Y reference”。
+
+#### 原则 2：三层内容分级
+
+同一个 reference 文件内，内容按三个层级组织：
+
+| 层级 | 性质 | 说明 | 示例 |
+|------|------|------|------|
+| **提醒层** | Claude 知道，但长文写作时容易忘或不稳定执行 | 轻量条目，起“别忘了”的作用 | “对话不要全员书面语”、“不要每段都以总结句收尾” |
+| **缺陷补偿层** | Claude 的系统性弱点，靠通识解决不了 | 需要明确的禁止项、替代方案、判断标准 | 命名同质化防护、“缓缓/淡淡/微微”固定语式替换、四段闭环结构检测 |
+| **知识补充层** | Claude 知道但不够深/不够全，需要领域知识注入 | 提供中文网文特有的技法、模式、正反例 | 追读力钩子技法、特定题材节奏模式、真实小说片段 |
+
+文件内三层从上到下排列，加载时可根据 token 预算裁剪深度。
+
+#### 原则 3：按需条件加载
+
+Reference 只在当前章节/任务确实触发了对应场景时才加载。
+
+- 本章没有战斗 → 不加载战斗描写参考
+- 本章没有新角色首次出场 → 不加载命名参考
+- 本章不涉及时间跳跃 → 不加载时间过渡参考
+
+Skill 的引用加载策略必须写明**触发条件**，而不是“每次都加载全部”。
+
+#### 原则 4：粒度优先对齐稳定问题域
+
+**md 文件**：优先按稳定问题域、稳定决策点组织，而不是机械切成极小碎片。只有当不同场景确实会产生冲突时，才进一步细拆。
+
+**CSV 检索**：一次检索返回的结果集等于一个子任务的粒度（同一张 CSV 可包含多种子任务的条目，靠检索过滤）。
+
+- 这个 step 需要命名 → 检索只返回命名相关条目
+- 这个 step 需要战斗描写 → 检索只返回战斗相关条目
+- 不扩展到“相关但当前不需要”的知识
+
+### 2.4 references 不是越少越好，而是越“补缺”越好
+
+本轮不追求压缩 references 数量。判断标准不是“文件是否减少”，而是：
+
+**该 reference 是否真正补到了 Claude 的稳定性缺口或项目私有知识缺口。**
+
+因此：
+- 若现有 references 冗余，应删除或合并。
+- 若现有 references 缺失，而该缺失会稳定导致错误，应新增。
+- 新增 reference 的理由必须清楚说明“它补的是什么缺口”。
+
+例如：
+- 人物命名规则
+- 题材专属命名禁区
+- 中文网文对话口吻差异
+- 特定题材常见模板腔与避坑清单
+
+这些都属于合理新增。
+
+### 2.5 skills 是工作流入口，不是百科
+
+`SKILL.md` 负责：
+- 定义适用场景
+- 组织执行顺序
+- 指定必要输入输出
+- 指明何时读哪些 reference
+- 定义验证与恢复规则
+
+`SKILL.md` 不负责：
+- 展开大量常识性方法论
+- 承载完整范例库
+- 细讲脚本内部实现
+- 变成“小型全书教程”
+
+### 2.6 中文化与网文化优先
+
+本系统服务于中文网络小说写作，文档语言应优先使用中文网文领域词汇。原则如下：
+- 正文叙述默认中文。
+- 优先使用网文专用名词：章纲、卷纲、钩子、爽点、微兑现、追读力、吃书、毒点、设定冲突等。
+- 字段名、CLI 子命令、frontmatter、JSON key、协议名保留必要英文。
+- 同一概念尽量只保留一个主称呼。
+
+#### 题材分类中文化
+
+现有 `genres/` 目录使用英文名（`xuanhuan`、`realistic` 等），本轮需统一为中文题材名。**当前第一版默认以番茄小说网题材分类作为映射基准**，后续允许扩展平台映射层。
+
+**男频：** 都市、玄幻、仙侠、奇幻、武侠、历史、军事、科幻、悬疑、游戏、体育、轻小说
+**女频：** 现言、古言、幻言、悬疑、轻小说
+
+CSV 知识库中的 `适用题材` 列使用上述中文名。`全部` 表示不限题材。
+
+现有 `genres/` 目录的映射关系：
+
+| 现有目录名 | 对应番茄题材 |
+|-----------|------------|
+| `xuanhuan/` | 玄幻 |
+| `realistic/` | 都市 |
+| `dog-blood-romance/` | 现言 |
+| `rules-mystery/` | 悬疑 |
+| `period-drama/` | 古言、历史 |
+| `zhihu-short/` | 短篇 / 轻小说（临时映射） |
+
+---
+
+## 3. 文档分层职责
+
+本轮只重构三层：
+- `skills/`
+- `references/`
+- `scripts/`
+
+### 3.1 skills 负责什么
+
+`skills` 负责：
+- 任务入口与适用场景
+- 主流程步骤
+- 前置条件
+- 必要 references 的加载策略
+- 交付物与成功标准
+- 失败恢复与补跑规则
+
+`skills` 不负责：
+- 大段方法论教学
+- 完整案例库
+- 模型常识补课
+- 重复解释底层脚本实现
+
+### 3.2 references 负责什么
+
+`references` 负责（遵循 §2.3 四原则）：
+- 绑定到具体 skill + step 的子任务指导
+- Claude 不稳定的高频缺陷补偿（缺陷补偿层）
+- Claude 知道但容易遗忘的执行要点（提醒层）
+- Claude 知道但不够深的领域知识补充（知识补充层）
+- 项目私有规范（CLI、字段、路径等）
+- 高价值正反例（真实小说片段）
+- 题材特异规则与禁区清单
+
+`references` 不负责：
+- 通用写作常识（Claude 已知且稳定执行的部分）
+- 大而空的方法论概述
+- 不带判断标准的结构模板
+- 不绑定到任何 step 的知识堆积
+
+### 3.3 scripts 负责什么
+
+`scripts` 负责：
+- 容易出错、可执行、可验证的稳定操作
+- 数据处理、验证、生成、迁移、索引等可程序化步骤
+
+`scripts` 不负责：
+- 替代 skill 的流程设计
+- 承载主业务说明
+- 替代 reference 的领域规则解释
+
+### 3.4 脚本化触发条件
+
+出现以下任一情况时，应优先评估是否脚本化，而不是继续扩写 skill 或 reference：
+
+1. 同一操作会被多个 skill 重复调用
+2. 成败可程序化判断
+3. 人工描述过长且容易误解
+4. 需要稳定过滤 / 检索 / 校验
+5. 出错代价较高，且希望避免靠人工执行记忆
+
+---
+
+## 4. 本轮重写原则
+
+### 4.1 不先写抽象模板文档，直接逐 skill 设计
+
+本轮不先产出一份“统一 skill 模板”。原因：
+- 不同 skill 的功能差异很大。
+- 先写抽象模板容易过早收敛，反而束缚设计。
+- 当前更适合直接对现有 skill 做问题导向重构。
+
+但所有 skill 重写后都应满足以下共同要求：
+- 适用场景清楚
+- 前置条件清楚
+- 流程主线清楚
+- references 加载策略清楚
+- 验证与恢复规则清楚
+- 正文语言中文化、网文化
+
+### 4.2 先 skill，后 reference 正文
+
+本轮顺序固定为：
+1. 先明确每个 skill 的职责与结构。
+2. 再列出它缺哪些 reference 文件。
+3. references 正文在下一阶段逐个补齐。
+
+因此本 spec 中，references 只写：
+- 文件名
+- 作用
+- 解决的缺陷类型
+- 归属 skill
+
+不展开全文内容设计。
+
+### 4.3 reference 新增判断标准
+
+新增 reference 必须同时满足：
+
+1. **绑定检查**：能指出“哪个 skill 的哪个 step 在什么条件下加载它”；若为跨 skill 通用 reference，需写清主服务场景与次服务场景。
+2. **缺口检查**：Claude 当前在这个子任务中是稳定犯错（缺陷补偿）、容易遗忘（提醒）、还是知识不足（补充）；至少命中一种。
+3. **独立性检查**：这个指导是否无法靠 skill 主流程的一两句话自然覆盖；若能内联解决，不独立建文件。
+4. **必要性检查**：如果不新增这份 reference，是否会稳定导致错误重复发生；若不会，优先通过 skill 流程、脚本或验证机制解决。
+
+四条全过才新增。
+
+### 4.4 Skill 正文必须包含的结构要素
+
+除 §4.1 的共同要求外，按优先级分层：
+
+- **P0 skills**：必须包含红旗 / 常见误区、优先级链、决策树入口三项
+- **P1 skills**：至少显式包含其中 1-2 项
+- **P2 skills**：按需采用，不强制
+
+#### 红旗 / 常见误区区块
+
+每个主链 skill 必须包含一个专门的“常见误区”列表，描述 Claude **真实会犯的思维错误**而非抽象禁令。
+
+示例（`webnovel-write`）：
+
+```text
+## 常见误区
+- ❌ 认为本章简单就跳过 Step 3 审查
+- ❌ Step 5 失败后直接开始下一章（状态还在 chapter_reviewed）
+- ❌ 把全部 reference 一次性读完再开始写
+- ❌ blocking issue 存在但觉得“不严重”就跳过
+- ❌ 用文件存在性替代 chapter_status 判断
+- ❌ 润色时改了事件顺序或设定
+```
+
+#### 优先级链
+
+当多个指令来源冲突时，skill 必须写明裁决顺序：
+
+```text
+1. 用户明确要求（最高）
+2. 状态机 / 流程硬门槛（chapter_status、blocking）
+3. 项目私有约束（设定集、已有剧情）
+4. skill 默认工作流
+5. reference 建议（最低）
+```
+
+#### 决策树入口
+
+Skill 正文不只是线性步骤列表，还必须在流程开头或关键分支处提供决策判断。最少覆盖：
+- 什么情况下继续下一步
+- 什么情况下阻断
+- 什么情况下回退到上一步
+- 什么情况下需要用户裁决
+
+---
+
+## 5. 技能总览矩阵
+
+| Skill | 当前主要问题 | 重写目标 | 需补 references | 优先级 |
+|------|--------------|----------|-----------------|--------|
+| `webnovel-write` | 主链过重，已有大量规则堆叠；需进一步明确主流程与引用边界 | 作为主链总控 skill，只保留主流程、闸门、交付物、恢复规则 | 高 | P0 |
+| `webnovel-review` | 结构较简，但需与 reviewer / review-pipeline / 状态机更清晰衔接 | 成为独立审查流程入口，收敛报告与阻断处理 | 中 | P0 |
+| `webnovel-plan` | 内容多、层级杂，兼有规则与参考说明 | 收敛为规划流程入口，结构化节点与卷级规划清楚 | 高 | P0 |
+| `webnovel-init` | 过重，像 mini-spec；交互采集、规则、资料混在一起 | 收敛为初始化工作流 skill，复杂知识下沉到 reference | 高 | P1 |
+| `webnovel-query` | 查询逻辑清楚，但文档像操作手册；可进一步减少低层命令暴露 | 收敛为查询 / 分析型 skill | 中 | P1 |
+| `webnovel-dashboard` | 过轻，像启动命令说明；缺验证与失败恢复结构 | 收敛为工具启动型 skill | 低 | P2 |
+| `webnovel-learn` | 过轻，像命令说明；缺边界与恢复规则 | 收敛为轻量记录型 skill | 低 | P2 |
+
+---
+
+## 6. 逐个 skill 改造方案
+
+### 6.1 `webnovel-write`
+
+#### 当前问题
+- 承载了太多细节，容易继续膨胀。
+- 某些 reference 内容仍偏“方法论说明”，未完全下沉。
+- 已有状态机闸门，但结构仍偏大而全。
+
+#### 重写目标
+- 明确它是**主链总控 skill**。
+- 保留：主流程、状态推进、阻断规则、必要 references、交付物、恢复规则。
+- 明确不承载：命名细则、对话风格方法论、题材命名库、桥段范例库，这些必须下沉到 references。
+
+#### 结构改动
+建议正文只保留这些块：
+1. 目标与适用场景
+2. 常见误区（§4.4 红旗区块）
+3. 优先级链（§4.4）
+4. 前置条件与环境准备
+5. 引用加载策略（Step 级，含 CSV 检索触发条件）
+6. 主流程（Step 0.5-6，含决策树入口）
+7. 状态推进与阻断规则
+8. 充分性闸门
+9. 验证与交付
+10. 失败恢复
+
+#### 当前 SKILL.md 段落去留表
+
+| 当前段落 | 处置 | 理由 |
+|---------|------|------|
+| 目标 | 保留 | 核心定义 |
+| 执行原则 | 保留 | 闸门硬约束 |
+| 模式定义 | 保留 | 标准 / fast / minimal 区分 |
+| 引用加载等级（L0/L1/L2） | 保留 | 按需加载策略 |
+| References 列表 | 重写 | 改为按 Step 触发条件组织，加条件加载说明 |
+| 工具策略 | 保留，精简 | 只保留 CLI 入口，不展开参数细节 |
+| 准备阶段 | 保留 | preflight + 环境变量 |
+| Step 0.5-6 | 保留 | 核心流程 |
+| 问题定向参考列表 | 下沉 | 移到 reference index 或 Step 内触发条件 |
+| 充分性闸门 | 保留 | 已切到状态机 |
+| 验证与交付 | 保留 | 已用 chapter_status |
+| 失败处理 | 保留 | 补跑规则 |
+
+#### references 触发绑定
+
+以 §2.3 四原则为标准，按 Step + 触发条件组织。**md 文件直接 Read，CSV 通过检索脚本按需获取。**
+
+##### md 必读（直接 Read）
+
+| Step | 触发条件 | 加载的 reference |
+|------|---------|-----------------|
+| Step 1 | 每次执行 | `references/reading-power-taxonomy.md`、`references/genre-profiles.md`、`skills/webnovel-write/references/style-variants.md` |
+| Step 2 | 每次执行 | `references/shared/core-constraints.md`、`skills/webnovel-write/references/anti-ai-guide.md` |
+| Step 4 | 每次执行 | `skills/webnovel-write/references/polish-guide.md`、`skills/webnovel-write/references/writing/typesetting.md`、`skills/webnovel-write/references/style-adapter.md` |
+
+##### CSV 检索（调用 `reference_search.py`）
+
+| Step | 触发条件 | 检索参数 |
+|------|---------|---------|
+| Step 2 | 本章有新角色首次出场 | `--skill write --table 命名规则 --query "角色命名" --genre {题材}` |
+| Step 2 | 本章有战斗 / 对峙场景 | `--skill write --query "战斗描写" --genre {题材}` |
+| Step 2 | 本章有多角色对话 | `--skill write --query "对话声线 口吻区分"` |
+| Step 2 | 本章有情感 / 心理描写 | `--skill write --query "情感描写 心理"` |
+| Step 2 | 本章涉及高频桥段 | `--skill write --table 场景写法 --query "{桥段类型}"` |
+| Step 4 | ai_flavor issue 存在 | `--skill write --query "AI味 反例 替换"` |
+
+#### scripts 需求
+- 暂不新增脚本作为前置条件。
+- 若后续发现命名校验可程序化，可新增轻量命名检查脚本。
+
+#### 验收点
+- 主流程阅读路径明显缩短
+- 每一步只在触发条件满足时加载对应 references
+- 状态机与交付物逻辑不弱化
+- 不再在 skill 正文中展开大段常识性写作建议
+
+---
+
+### 6.2 `webnovel-review`
+
+#### 当前问题
+- 流程清楚，但与 `reviewer` / `review-pipeline` / 报告落盘的边界还可再清楚。
+- 阻断与返工逻辑可进一步明确成“审查型 workflow”。
+
+#### 重写目标
+- 成为独立审查 skill：从输入章节到输出审查报告、落库、写回记录。
+- 不承载过多审查理论；理论交给 reviewer 和 references。
+
+#### 结构改动
+保留：
+1. 适用场景
+2. 常见误区（§4.4）
+3. 优先级链（§4.4）
+4. 项目根解析
+5. 引用加载
+6. 调用 reviewer（含决策树：blocking → 返工 / override）
+7. 生成报告与落库
+8. 处理 blocking 与用户决策
+9. 成功标准与恢复规则
+
+#### references 触发绑定
+
+##### md 必读
+
+| Step | 触发条件 | 加载的 reference |
+|------|---------|-----------------|
+| Step 2（加载参考） | 每次执行 | `references/shared/core-constraints.md`、`references/review-schema.md` |
+| Step 6（处理阻断） | 存在 blocking issue 需用户决策 | `references/review/blocking-override-guidelines.md` |
+
+##### CSV 检索
+
+| Step | 触发条件 | 检索参数 |
+|------|---------|---------|
+| Step 4（调用 reviewer） | ai_flavor issue 数量 ≥ 3 | `--skill review --query "AI味 反例 替换"` |
+
+#### scripts 需求
+- 不新增主流程脚本。
+- 后续若独立复检需要稳定接口，可考虑加 `review-ai-flavor-check.py`。
+
+#### 验收点
+- 阻断处理路径清楚
+- 审查产物路径稳定
+- 不再重复 reviewer 本身的详细检查维度
+
+---
+
+### 6.3 `webnovel-plan`
+
+#### 当前问题
+- 文档同时承担：设定补齐、卷节拍、时间线、章纲、节点规范、写回设定。
+- 很多规则适合作为 reference，而不是主 skill 正文。
+
+#### 重写目标
+- 成为**规划主流程入口**，重点强调：
+  - 卷级目标
+  - 时间线硬约束
+  - 批量拆章流程
+  - 结构化节点产物
+- 将题材节奏、冲突设计等下沉到 reference。
+
+#### 结构改动
+建议主结构为：
+1. 目标与适用范围
+2. 常见误区（§4.4 红旗区块）
+3. 优先级链（§4.4）
+4. 前置条件
+5. 引用加载策略
+6. 规划主流程（Step 1-9，含决策树入口）
+7. 结构化节点产物要求
+8. 硬失败条件
+9. 恢复规则
+
+#### references 触发绑定
+
+##### md 必读
+
+| Step | 触发条件 | 加载的 reference |
+|------|---------|-----------------|
+| 章纲拆分 | 每次执行 | `references/outlining/plot-signal-vs-spoiler.md` |
+
+##### CSV 检索
+
+| Step | 触发条件 | 检索参数 |
+|------|---------|---------|
+| 卷级规划 | 每次执行 | `--skill plan --table 场景写法 --query "卷级结构 叙事功能"` |
+| 章纲拆分 | 新增角色出现 | `--skill plan --table 命名规则 --query "角色命名" --genre {题材}` |
+
+#### scripts 需求
+- 暂不新增。
+- 后续若时间线验证继续复杂化，可考虑补独立校验脚本。
+
+#### 验收点
+- 主流程更像“规划入口”，不是“全量教程”
+- 题材与冲突知识显著下沉到 references
+- 批次、节点、时间线规则清楚且集中
+
+---
+
+### 6.4 `webnovel-init`
+
+#### 当前问题
+- 体量过大，已接近 mini-spec。
+- 用户采集、题材策略、创意约束、资料索引混在一起。
+
+#### 重写目标
+- 成为**初始化访谈与生成工作流**。
+- 主 skill 只保留信息采集流程、充分性闸门、生成与验证。
+- 题材、命名、卖点、创意约束等知识下沉到 references。
+
+#### 结构改动
+建议主结构为：
+1. 目标与适用场景
+2. 交互原则
+3. 分步采集流程
+4. 充分性闸门
+5. 生成步骤
+6. 验证与交付
+7. 最小回滚
+
+#### references 触发绑定
+
+##### md 必读
+
+| Step | 触发条件 | 加载的 reference |
+|------|---------|-----------------|
+| 卖点 / 题材采集 | 每次执行 | `references/genre-profiles.md` |
+
+##### CSV 检索
+
+| Step | 触发条件 | 检索参数 |
+|------|---------|---------|
+| 起名采集 | 用户开始设定角色 / 书名 / 势力名 | `--skill init --table 命名规则 --query "{命名对象} {题材}" --genre {题材}` |
+
+注：原 `title-patterns-and-anti-patterns.md` 和 `protagonist-flaw-patterns.md` 不直接纳入本轮缺口清单，后续若实测出现稳定缺陷再补回。
+
+#### scripts 需求
+- 暂不新增，仍以现有 `init_project.py` 为主。
+
+#### 验收点
+- skill 正文显著瘦身
+- 交互流程更清楚
+- 创意 / 题材 / 命名类细节下沉
+
+---
+
+### 6.5 `webnovel-query`
+
+#### 当前问题
+- 查询流程本身合理，但文档风格偏操作手册。
+- 暴露较多低层步骤，可进一步强调“查询类型识别 + 数据源选择 + 输出格式”。
+
+#### 重写目标
+- 成为**查询 / 分析型 skill**。
+- 强调：
+  - 查询意图识别
+  - 按需加载 reference
+  - 读取最少必要数据
+  - 输出结构化回答
+
+#### 结构改动
+建议保留：
+1. Use when
+2. 项目根保护
+3. 查询类型识别
+4. 引用加载等级
+5. 查询流程
+6. 输出格式
+7. 边界
+
+#### references 触发绑定
+
+无新增刚需。当前 query skill 的参考需求主要是项目私有知识（CLI 用法、数据源），已内联在 skill 中。
+
+注：`entity-alias-resolution.md`、`foreshadowing-urgency-rules.md` 暂列为候选，待实测若输出不稳则补回。
+
+#### scripts 需求
+- 无新增刚需。
+
+#### 验收点
+- 更像查询工作流，而不是大段说明书
+- 输出风格统一
+
+---
+
+### 6.6 `webnovel-dashboard`（P2，方向简述）
+
+收敛为**工具启动型 skill**：补齐环境检查、启动步骤、成功判定、常见故障处理。P2 不强制三件套，不挂独立 reference，现有功能已基本自洽。
+
+---
+
+### 6.7 `webnovel-learn`（P2，方向简述）
+
+收敛为**轻量记录型 skill**：重点明确何时记录、输入结构、幂等 / 去重、写回格式、失败处理。P2 不强制三件套，是否补 `pattern-taxonomy` 视实测而定。
+
+---
+
+## 7. Reference 体系设计（双轨制）
+
+本轮 reference 采用**双轨制**：流程必读型（md）+ 写作知识库型（CSV + 检索脚本）。
+
+### 7.1 双轨分工
+
+| 轨道 | 格式 | 加载方式 | 承载内容 | 示例 |
+|------|------|---------|---------|------|
+| **流程必读型** | `.md` 文件 | Skill 指定 step 直接 `Read` | 闸门规则、schema 定义、核心约束、审查标准 | `core-constraints.md`、`review-schema.md`、`polish-guide.md` |
+| **写作知识库型** | `.csv` + Python 检索脚本 | Step 遇到特定场景时调用脚本，只返回命中条目 | 写作技法、题材写法、场景灵感、命名规则、正反例 | `写作技法.csv`、`命名规则.csv`、`场景写法.csv` |
+
+分界标准：
+- **流程/契约/闸门/schema** → md（必须完整读取，不能只看片段）
+- **写作知识/技法/灵感/正反例** → CSV（条目多、按需检索、只取相关的几条）
+
+### 7.2 CSV 知识库设计
+
+#### 文件位置
+
+```
+webnovel-writer/
+  data/                          # CSV 知识库根目录
+    写作技法.csv
+    命名规则.csv
+    场景写法.csv
+  scripts/
+    reference_search.py          # 统一检索脚本（BM25）
+```
+
+#### 编码
+
+所有 CSV 文件使用 **UTF-8 with BOM**（`utf-8-sig`），确保 Windows 下 Excel 可正确打开中文。
+
+#### 通用列（所有 CSV 共有）
+
+| 列名 | 类型 | 说明 | 示例值 |
+|------|------|------|-------|
+| `编号` | string | 唯一 ID，前缀区分表 | `WT-001`、`NR-012`、`SP-003` |
+| `适用技能` | string | 粗筛，逗号分隔 | `write` 或 `init,plan` 或 `init,plan,write` |
+| `分类` | string | 场景大类 | `战斗`、`对话`、`命名`、`情感`、`场景` |
+| `层级` | string | 三层标记 | `提醒` / `缺陷补偿` / `知识补充` |
+| `关键词` | string | BM25 检索用，逗号分隔 | `打斗,武斗,对决,境界压制` |
+| `适用题材` | string | 番茄分类题材名，逗号分隔 | `全部` 或 `玄幻,仙侠` |
+
+#### 写作技法表（`写作技法.csv`）
+
+| 列名 | 说明 |
+|------|------|
+| （通用列） | |
+| `技法名称` | 技法的简短名称 |
+| `说明` | 技法描述 |
+| `正例` | 正面示范，可放长片段（200-500 字） |
+| `反例` | 反面示范，可放长片段 |
+| `修复建议` | 从反例到正例的修改方向 |
+
+示例行：
+
+```
+编号,适用技能,分类,层级,关键词,适用题材,技法名称,说明,正例,反例,修复建议
+WT-001,write,对话,缺陷补偿,"口吻趋同,对话区分,角色声线",全部,对话声线差异化,不同角色的对话应有可辨识的口语特征和节奏差异,"老张头叼着烟袋锅子，""嘿，你小子又来蹭饭？""...","两人对话风格完全一致，都是标准书面语",给每个角色设定 1-2 个口语标记词和句式习惯
+```
+
+#### 命名规则表（`命名规则.csv`）
+
+| 列名 | 说明 |
+|------|------|
+| （通用列） | |
+| `命名对象` | `角色` / `地点` / `势力` / `功法` / `道具` / `书名` |
+| `规则` | 规则描述 |
+| `正例` | |
+| `反例` | |
+
+#### 场景写法表（`场景写法.csv`）
+
+| 列名 | 说明 |
+|------|------|
+| （通用列） | |
+| `场景类型` | `告白`、`打脸`、`觉醒`、`战斗`、`谈判`、`追逐`、`日常`、`离别` 等 |
+| `模式名称` | 这种写法的名称 |
+| `说明` | 模式描述 |
+| `示例片段` | 可放长片段（200-500 字） |
+| `反面写法` | 要避免的写法 |
+
+### 7.3 检索脚本设计
+
+#### CLI 接口
+
+```bash
+# 基本用法：按当前 skill 和关键词检索
+python -X utf8 "${SCRIPTS_DIR}/reference_search.py" \
+  --skill write \
+  --query "战斗描写 境界压制" \
+  --max-results 3
+
+# 指定题材过滤
+python -X utf8 "${SCRIPTS_DIR}/reference_search.py" \
+  --skill write \
+  --query "命名 角色" \
+  --genre "玄幻" \
+  --max-results 5
+
+# 指定表
+python -X utf8 "${SCRIPTS_DIR}/reference_search.py" \
+  --skill plan \
+  --table 命名规则 \
+  --query "跨卷 角色命名" \
+  --max-results 3
+```
+
+#### 检索流程
+
+```
+1. 按 `适用技能` 列过滤（粗筛）
+2. 按 `适用题材` 列过滤（可选，若指定 --genre）
+3. 在过滤后的结果集内做 BM25 关键词检索
+4. 返回 top N 条，格式化输出
+```
+
+#### 输出格式
+
+```
+## 检索结果（写作技法）
+查询：战斗描写 境界压制 | 技能：write | 题材：玄幻 | 命中：3 条
+
+### [WT-023] 境界压制的体感描写
+- 层级：知识补充
+- 说明：通过身体反应而非数值对比来表现境界差距
+- 正例：（片段...）
+- 反例：（片段...）
+- 修复建议：...
+
+### [WT-045] ...
+```
+
+### 7.4 流程必读型 reference（md 文件，保留/新增）
+
+以下 md reference 保留或新增，由 Skill 在指定 step 直接 `Read`：
+
+| 文件 | 类型 | 服务 skill | 加载时机 |
+|------|------|-----------|---------|
+| `references/shared/core-constraints.md` | 保留 | write/Step 2 | 每次执行 |
+| `references/review-schema.md` | 保留 | write/Step 3、review/Step 4 | 每次执行 |
+| `references/shared/cool-points-guide.md` | 保留 | review | 按需 |
+| `references/shared/strand-weave-pattern.md` | 保留 | review | 按需 |
+| `references/reading-power-taxonomy.md` | 保留 | write/Step 1 | 每次执行 |
+| `references/genre-profiles.md` | 保留 | write/Step 1、init | 每次执行 |
+| `skills/webnovel-write/references/style-variants.md` | 保留 | write/Step 1 | 每次执行（差异化设计） |
+| `skills/webnovel-write/references/polish-guide.md` | 保留 | write/Step 4 | 每次执行 |
+| `skills/webnovel-write/references/anti-ai-guide.md` | 保留 | write/Step 2 | 每次执行 |
+| `skills/webnovel-write/references/style-adapter.md` | 保留 | write/Step 4 | 每次执行 |
+| `skills/webnovel-write/references/writing/typesetting.md` | 保留 | write/Step 4 | 每次执行 |
+| `references/review/blocking-override-guidelines.md` | **新增** | review/Step 6 | 存在 blocking issue 需用户决策时 |
+| `references/outlining/plot-signal-vs-spoiler.md` | **新增** | plan/章纲拆分 | 每次执行 |
+
+### 7.5 写作知识库型 reference（CSV 文件，新增）
+
+以下知识从现有 md 文件迁移或新建到 CSV：
+
+| 现有 md 文件 | 迁移到 CSV | 迁移后 md 处置 |
+|-------------|-----------|--------------|
+| `writing/combat-scenes.md` | `场景写法.csv`（场景类型=战斗） | 删除或保留为空壳指向 CSV |
+| `writing/dialogue-writing.md` | `写作技法.csv`（分类=对话） | 同上 |
+| `writing/emotion-psychology.md` | `写作技法.csv`（分类=情感） | 同上 |
+| `writing/scene-description.md` | `写作技法.csv`（分类=场景） | 同上 |
+| `writing/desire-description.md` | `写作技法.csv`（分类=情感） | 同上 |
+| `writing/genre-hook-payoff-library.md` | `场景写法.csv`（场景类型=钩子/兑现） | 同上 |
+| （新增）命名规则 | `命名规则.csv` | 无现有文件 |
+| （新增）对话声线差异化 | `写作技法.csv`（分类=对话，层级=缺陷补偿） | 无现有文件 |
+| （新增）反模板桥段 | `场景写法.csv`（层级=缺陷补偿） | 无现有文件 |
+| （新增）AI味正反例 | `写作技法.csv`（分类=AI味，层级=缺陷补偿） | 无现有文件 |
+| （新增）卷级叙事功能模式 | `场景写法.csv`（场景类型=卷级结构，适用技能=plan） | 无现有文件 |
+
+### 7.6 被过滤掉的原提案
+
+以下提案当前不纳入，但不是永久排除。判断标准：Claude 在中文网文场景下若实测输出稳定性不足，仍可后续补回。
+
+| 原提案 | 当前过滤理由 | 恢复条件 |
+|--------|------------|---------|
+| `init/title-patterns-and-anti-patterns.md` | 书名命名可作为 `命名规则.csv` 中几行条目（`命名对象=书名`） | 若 CSV 几行不够覆盖、实测书名模板化严重，升级为独立条目组 |
+| `init/protagonist-flaw-patterns.md` | Claude 通用能力可覆盖 | 若实测缺陷设计在网文场景下空泛化、标签化严重，补为 CSV 条目 |
+| `query/entity-alias-resolution.md` | 别名解析是代码逻辑（entity_linker.py） | 若代码无法覆盖的语义歧义频发，补 reference |
+| `query/foreshadowing-urgency-rules.md` | 紧急度排序已在 context-agent 实现 | 若输出解释不稳定，补 reference |
+| `learn/pattern-taxonomy.md` | learn skill 低频，分类规则内联 skill 即可 | 若分类质量持续不稳，补 CSV 条目 |
+
+---
+
+## 8. 分批实施顺序
+
+### 第零批：基础设施
+- 实现 `reference_search.py`（BM25 检索脚本）
+- 建立 `data/` 目录和 3 个 CSV 文件骨架（表头 + 少量种子数据）
+- 补测试：确认检索脚本的粗筛 → 题材过滤 → BM25 流程跑通
+- 现有 `genres/` 目录名中文化映射
+
+目标：CSV 知识库基础设施就绪，后续批次可直接往里填数据。
+
+### 第一批：主链 skills（P0）
+- `webnovel-write`
+- `webnovel-review`
+- `webnovel-plan`
+- 新增 P0 skill 依赖的 md reference：`blocking-override-guidelines.md`（review）、`plot-signal-vs-spoiler.md`（plan）
+
+目标：先收敛主链工作流入口，skill 正文切到双轨 reference 加载。
+
+**冻结点：** 第一批完成后，review 确认主链 skill 结构稳定、md/CSV 触发绑定表无遗漏，再进入第二批。
+
+### 第二批：初始化与查询（P1）
+- `webnovel-init`
+- `webnovel-query`
+
+目标：收敛前置采集和查询分析文档。
+
+### 第三批：内容填充 + 辅助类（P2）
+- `webnovel-dashboard`
+- `webnovel-learn`
+- 将现有 md reference 中的写作知识迁移到 CSV
+- 逐步扩充 CSV 条目（可持续进行，不阻塞主链）
+
+目标：完成轻量技能整理，CSV 知识库进入持续填充阶段。
+
+---
+
+## 9. 验收标准
+
+本轮重构完成时，应满足：
+
+1. 所有 `skills` 都有清晰的主功能定位，不再混合成”手册 + 教程 + spec”。
+2. `skills` 正文明显收敛为：流程、闸门、交付物、恢复规则。
+3. **skill 结构要素分层落地**：P0 skill 包含红旗/优先级链/决策树全三项，P1 至少 1-2 项，P2 按需（§4.4）。
+4. **reference 双轨制落地**：流程必读型 md + 写作知识库型 CSV，职责不混。
+5. `reference_search.py` 可正常检索，粗筛（适用技能）→ 题材过滤 → BM25 全链路跑通。
+6. CSV 文件均为 UTF-8 with BOM 编码，Windows Excel 可正确打开。
+7. 题材分类已中文化（当前以番茄小说网分类为默认基准），现有 `genres/` 目录完成映射。
+8. 不再以”减少 reference 数量”为目标，而以”高价值补缺”为目标。
+9. 技能正文语言完成中文化/网文化，字段和协议保留必要英文。
+10. 新增或重写后的 skill 可通过 prompt integrity 检查与人工走读。
+
+---
+
+## 10. 本 spec 的边界
+
+本 spec 不处理：
+- `agents/` 重写（agent 只有 prompt 本体，不挂 reference 文件）
+- references 正文具体内容撰写（仅定义文件名、触发绑定、内容层级）
+- scripts 的完整实现细节
+- v6 迁移 spec 中已确认的架构决策（状态机、memory contract、reviewer 流程等）
+
+本 spec 只回答：
+**skills 下一步应该怎么重写，以及 references 下一步该补哪些文件、在什么条件下加载。**

docs/superpowers/specs/2026-04-12-story-system-evolution-spec.md

@@ -0,0 +1,1198 @@
+# Webnovel Writer Story System 渐进演进 Spec
+
+> **日期**: 2026-04-12
+> **状态**: 草案 v1
+> **定位**: 基于当前系统真实状态的 superpowers 架构收敛 spec
+
+---
+
+## 1. 文档定位
+
+### 1.1 这份 spec 解决什么问题
+
+[`current-system-diagnosis.md`](../../architecture/current-system-diagnosis.md) 已经明确指出：当前系统的主要问题，不是模型能力不够，而是：
+
+1. 真理源分散
+2. 缺少统一故事合同
+3. 缺少统一章节提交主链
+4. 上下文装配与数据回写都存在结构性缺口
+
+但诊断报告只回答了“哪里有问题”，没有回答“如何从当前系统稳态演进到新系统”。
+
+这份 spec 补的就是中间层：
+
+- 不重写现有项目历史
+- 不假装当前系统一无所有
+- 不直接把理想态蓝图当实施方案
+- 而是定义一条**从现状出发、逐步收束为 Story Contract 主链**的演进路线
+
+### 1.2 与其他文档的关系
+
+这份文档与现有文档的关系如下：
+
+- [`current-system-diagnosis.md`](../../architecture/current-system-diagnosis.md)
+  - 负责诊断当前系统的结构性问题
+- [`2026-04-12-story-system-pro-max-retrofit-spec.md`](./2026-04-12-story-system-pro-max-retrofit-spec.md)
+  - 负责保守改造思路
+- [`2026-04-12-webnovel-story-intelligence-system-spec.md`](./2026-04-12-webnovel-story-intelligence-system-spec.md)
+  - 负责理想态目标架构
+
+这份 spec 的定位是：
+
+- **以上三者之间的桥**
+- 用“现状基线 -> 阶段性收束 -> 最终合同系统”的方式，把诊断、retrofit、理想态串起来
+
+### 1.2.1 与 diagnosis / retrofit / ideal spec 的边界
+
+为避免这份文档与另外两份 story system spec 打架，这里明确边界：
+
+#### `current-system-diagnosis`
+
+负责回答：
+
+- 当前系统到底哪里有结构性缺口
+- 哪些问题是真问题
+- 哪些地方其实已经有半成品底座
+
+它不负责给出演进实施路径。
+
+#### `retrofit spec`
+
+负责回答：
+
+- 如何在尽量不破坏现有主链的前提下，补出最小可用的 `story_system`
+
+它偏向：
+
+- phase 1
+- 保守落地
+- 最小侵入
+
+#### `理想态 spec`
+
+负责回答：
+
+- 如果不考虑最小改动原则，最终最佳架构应该长什么样
+
+它偏向：
+
+- phase 2 以后
+- 最终目标
+- 完整合同系统
+
+#### 本 spec
+
+负责回答：
+
+- 如何从真实现状出发，把半成品中枢逐步收束成合同主链
+- 哪些旧链路先接入、哪些后降级、哪些最后替换
+
+换句话说：
+
+- 诊断文档定义问题
+- retrofit spec 定义保守补法
+- 理想态 spec 定义终局目标
+- **本 spec 定义从现状走到终局的渐进路径**
+
+### 1.3 一句话结论
+
+当前系统不是“推倒重来”型问题，而是“多个半成品中枢需要收束成一个主链”型问题。
+
+因此最优策略不是：
+
+- 再堆一个新脚本
+- 再加一层提示词补丁
+- 再给 `context_manager` 增加几条预算规则
+
+而是建立：
+
+- **统一故事合同层**
+- **统一章节提交主链**
+- **统一覆盖账本**
+- **统一事件主链**
+
+再把 `state / index / summary / memory / RAG` 统统降级为合同提交后的投影层。
+
+---
+
+## 2. 当前基线
+
+### 2.1 当前系统已经存在的半成品中枢
+
+根据现状诊断，当前系统并不是完全无结构，而是已经存在以下可复用底座：
+
+1. `context_manager + context_ranker`
+   - 已能做上下文聚合、预算控制、优先级排序
+2. `genre_aliases.py + genre_profile_builder.py + genre-profiles.md`
+   - 已能做题材归一化、题材 hints 生成、题材画像构建
+3. `reference_search.py + references/csv`
+   - 已能做条目检索与轻量打分
+4. `state_manager`
+   - 已能做结构化状态回写，并承担 `state.json + SQLite` 的双写同步
+5. `index.db`
+   - 已承载实体、关系、事件、索引等结构化事实
+6. `memory writer / orchestrator / summaries`
+   - 已承担长期事实沉淀与章节摘要
+7. `override_contracts`
+   - 已经存在“违背记录”的雏形机制
+
+### 2.2 当前系统最根本的缺失
+
+真正缺失的不是某一个模块，而是四个主链能力：
+
+1. **统一故事真理源**
+   - 当前没有 `MASTER / VOLUME / CHAPTER` 合同家族作为单一真理源
+2. **统一章节提交主链**
+   - 写作后的状态回写仍是多处散写，不是一次章节提交、再多投影分发
+3. **统一设定演进账本**
+   - 当前只有追读力债务的 override 雏形，没有全局设定演进账本
+4. **统一事件主链**
+   - 当前已有很多 Delta 事件痕迹，但没有 canonical event log
+
+### 2.3 演进判断
+
+这意味着演进不能按“新增一个大模块，旧链路先不管”的方式做。
+
+必须遵守：
+
+1. 先建立统一合同
+2. 再让运行时消费合同
+3. 再让章节提交变成主链
+4. 最后把旧链路降级为投影与回退
+
+如果顺序反过来，系统只会多一个并行中枢，而不是更收敛。
+
+---
+
+## 3. 设计目标与非目标
+
+### 3.1 目标
+
+本演进 spec 要达成 8 个目标：
+
+1. 建立基于当前系统的统一故事合同体系
+2. 建立合同优先的上下文装配顺序
+3. 建立写前而不是写后的强约束输入
+4. 建立大纲履约校验与 review contract
+5. 建立统一章节提交主链
+6. 建立统一 override ledger
+7. 建立统一 canonical event log
+8. 把现有模块重定位为合同系统的底盘和投影层
+
+### 3.2 非目标
+
+本 spec 明确不做以下承诺：
+
+1. 不要求一次性替换全部旧链路
+2. 不要求一次性废弃 `context_manager`、`genre_*`、`reference_search.py`
+3. 不要求知识内容自动从 md 迁移到 csv
+4. 不要求对每个 CSV 条目编写测试
+5. 不要求在第一阶段就实现完全事件驱动架构
+
+### 3.3 硬约束
+
+整个演进过程必须持续遵守以下约束：
+
+1. `AI味`、anti-AI、润色替换规则继续保留在 md，不进入 CSV
+2. CSV 知识迁移只允许人工整理与人工录入
+3. 演进不得制造新的双真理源
+4. 任一阶段的 implementation plan 都必须把**文档更新**作为显式任务
+
+---
+
+## 4. 核心设计原则
+
+### 4.1 收束，不并列
+
+新系统的职责必须是**收束旧中枢**，不是与旧中枢并列竞争。
+
+反模式：
+
+- 新增 `story_system`，但 `context_manager` 仍单独输出另一套题材判断
+- 新增合同文件，但 `genre-profiles.md` 仍作为同级真源参与写作输入
+- 新增章节提交对象，但状态回写仍绕过它直接散写
+
+### 4.2 合同优先，运行时补充
+
+运行时输入应拆成两层：
+
+1. **合同层**
+   - 题材调性、毒点红线、系统边界、卷章目标
+2. **事实层**
+   - state、recent summaries、entity facts、reader signals
+
+原则上：
+
+- 合同负责“应该怎么写”
+- 事实负责“已经发生了什么”
+
+### 4.3 提交优先，投影随后
+
+章节完成后的正确顺序必须是：
+
+1. 形成结构化章节提交对象
+2. 校验其是否满足合同和大纲
+3. 只有提交通过，才向 `state / index / summary / memory` 投影
+
+而不是：
+
+- 先散写
+- 再在各模块里尽量圆回来
+
+### 4.4 显式覆盖，禁止静默漂移
+
+任何设定变化必须回答四个问题：
+
+1. 变了什么
+2. 基于哪一层改的
+3. 为什么改
+4. 是否影响上层合同
+
+如果回答不了，就不允许把它当作合法设定演进。
+
+### 4.5 先补主链，再补精度
+
+本项目当前最缺的是主链，不是精度。
+
+因此演进顺序必须是：
+
+1. 先补合同主链
+2. 再补提交主链
+3. 再补事件主链
+4. 最后再提升检索、推理、多标签融合精度
+
+---
+
+## 5. 诊断问题到演进工作流的映射
+
+现状诊断中的 10 个问题，可以归并为 5 条演进工作流。
+
+### 5.1 真理源收束工作流
+
+对应问题：
+
+- 1. 多头真理
+- 2. Override Ledger 缺口
+
+要解决的事：
+
+- 引入合同家族作为唯一故事真理源
+- 把 `override_contracts` 从追读力债务专用，扩展为故事设定演进账本
+
+### 5.2 上下文合同化工作流
+
+对应问题：
+
+- 3. 上下文截断黑洞
+- 4. 知识延迟绑定与泛化割裂
+
+要解决的事：
+
+- 让 `context_manager` 合同优先
+- 把通用知识预聚合为当前书的专属合同，而不是让写作时临时散查
+
+### 5.3 写前校验工作流
+
+对应问题：
+
+- 5. 事后验尸
+- 6. 缺乏大纲履约校验
+
+要解决的事：
+
+- 建立 review contract
+- 建立写前禁区、写前消歧域、写后履约 diff
+
+### 5.4 章节提交工作流
+
+对应问题：
+
+- 7. 跨存储事务割裂
+- 8. 后置消歧污染风险
+- 9. 消歧警告向后传染
+
+要解决的事：
+
+- 引入统一章节提交对象
+- 把消歧和事实提取前移到提交校验链，而不是回写尾部兜底
+
+### 5.5 事件主链工作流
+
+对应问题：
+
+- 10. 事件只有痕迹没有主链
+
+要解决的事：
+
+- 定义 canonical event log
+- 让“事件”而不是“覆盖后的状态”成为演进触发器
+
+---
+
+## 6. 演进后的总体架构
+
+### 6.1 总体分层
+
+演进后的系统分为六层：
+
+1. `Knowledge Layer`
+2. `Reasoning Layer`
+3. `Contract Layer`
+4. `Runtime Assembly Layer`
+5. `Chapter Commit Layer`
+6. `Projection Layer`
+
+### 6.2 总体链路
+
+```text
+用户意图 / 书籍题材诉求
+        ↓
+Reasoning Layer
+        ↓
+Story Contract Generator
+        ↓
+MASTER / VOLUME / CHAPTER / REVIEW / ANTI_PATTERNS
+        ↓
+context_manager(contract-first)
+        ↓
+规划 / 写作 / 审查
+        ↓
+CHAPTER_COMMIT
+        ↓
+Projection Writers
+        ↓
+state / index / summaries / memory / rag
+```
+
+### 6.3 最终判断
+
+未来系统的主链不应是：
+
+- `reference_search -> prompt -> reviewer -> data agent -> state`
+
+而应是：
+
+- `knowledge -> reasoning -> contract -> runtime pack -> chapter commit -> projections`
+
+---
+
+## 7. 单一真理源与优先级规则
+
+### 7.1 故事真理源
+
+故事系统的唯一真理源应为合同家族：
+
+1. `MASTER_SETTING.json`
+2. `VOLUME_BRIEF.json`
+3. `CHAPTER_BRIEF.json`
+4. `REVIEW_CONTRACT.json`
+5. `anti_patterns.json`
+
+其中：
+
+- 分层真源是 `MASTER / VOLUME / CHAPTER`
+- `anti_patterns.json` 是派生视图，不反向成为真源
+- `REVIEW_CONTRACT.json` 是审查用派生合同
+
+### 7.2 运行时优先级
+
+运行时拼上下文时，优先级固定为：
+
+1. `chapter contract`
+2. `volume contract`
+3. `master contract`
+4. `题材与调性推理.csv`
+5. `genre-profiles.md`
+6. `templates/genres/*.md`
+7. 其他局部 reference
+
+一旦合同存在：
+
+- `context_manager`
+- `webnovel-plan`
+- `webnovel-write`
+- `webnovel-review`
+
+都不得再输出与合同冲突的全局系统判断。
+
+### 7.3 写后真理源
+
+章节完成后，真理链固定为：
+
+1. `CHAPTER_COMMIT`
+2. 投影到 `state`
+3. 投影到 `index`
+4. 投影到 `summaries`
+5. 投影到 `memory`
+
+也就是说：
+
+- `state / index / summary / memory` 不再是章节事实的并列真源
+- 它们是 `CHAPTER_COMMIT` 的派生投影
+
+---
+
+## 8. 合同体系设计
+
+### 8.1 合同家族
+
+完整合同家族定义如下：
+
+1. `MASTER_SETTING`
+2. `VOLUME_BRIEF`
+3. `CHAPTER_BRIEF`
+4. `REVIEW_CONTRACT`
+5. `ANTI_PATTERNS`
+6. `CHAPTER_COMMIT`
+
+这里新增 `CHAPTER_COMMIT`，原因很简单：
+
+- 前五类合同负责“写之前”
+- `CHAPTER_COMMIT` 负责“写之后”
+
+如果没有它，系统就无法真正修复诊断里关于回写割裂、履约丢失、事件断链的问题。
+
+### 8.2 合同职责
+
+#### `MASTER_SETTING`
+
+负责全书级稳定系统：
+
+- 题材与调性
+- 世界规则
+- 核心人设
+- 金手指边界
+- 全局毒点
+- 全局 override policy
+
+#### `VOLUME_BRIEF`
+
+负责卷级系统：
+
+- 本卷冲突轴
+- 本卷兑现目标
+- 本卷阶段性角色关系
+- 本卷节奏波形
+- 本卷补充红线
+
+#### `CHAPTER_BRIEF`
+
+负责本章执行：
+
+- 本章目标
+- 本章场景策略
+- 本章 hook
+- must cover 节点
+- 本章禁区
+- 本章局部 override
+
+#### `REVIEW_CONTRACT`
+
+负责本次审查必须检查的事项：
+
+- blocking rules
+- 题材特定风险
+- 大纲履约检查项
+- 消歧检查项
+- 高风险事实校验项
+
+#### `ANTI_PATTERNS`
+
+负责将可见层级的所有红线聚合为运行时平面视图。
+
+#### `CHAPTER_COMMIT`
+
+负责承载本章最终提交结果：
+
+- 使用了哪些合同
+- 实际发生了哪些事实
+- 实际产生了哪些事件
+- 是否完成了 outline/mandatory nodes
+- 消歧是否通过
+- review 是否通过
+- 哪些投影已完成
+
+### 8.3 字段类型
+
+仍采用三类字段策略：
+
+1. `locked`
+2. `append_only`
+3. `override_allowed`
+
+并保留 `lock_policy`：
+
+1. `system_locked`
+2. `user_locked`
+3. `story_locked`
+
+### 8.4 覆盖规则
+
+优先级固定为：
+
+1. `chapter`
+2. `volume`
+3. `master`
+
+但这不是静默覆盖，而是必须记录：
+
+- `field`
+- `base_value`
+- `override_value`
+- `source_level`
+- `reason`
+- `reason_tag`
+- `approved_by`
+
+### 8.5 override ledger 的新定位
+
+当前 `override_contracts` 不能废弃，而应演进为统一 override ledger 的底座。
+
+演进后的职责：
+
+1. 记录追读力债务层面的软违背
+2. 记录卷章对上层故事合同的受控覆盖
+3. 记录需要上提到 `amend-master / amend-volume` 的提案
+
+最终应区分三类记录：
+
+1. `soft_deviation`
+2. `contract_override`
+3. `amend_proposal`
+
+---
+
+## 9. 章节提交主链设计
+
+### 9.1 为什么必须新增提交主链
+
+当前系统的问题不是“写完后没保存”，而是“写完后被拆成多处异步散写”。
+
+这会导致：
+
+- 状态不同步
+- 消歧后置污染
+- 履约丢失
+- 事件断链
+
+所以必须把章节完成后的提交改为：
+
+- 先形成一个统一提交对象
+- 再由投影器把它分发到各存储
+
+### 9.2 `CHAPTER_COMMIT` 最小结构
+
+最小应包含：
+
+- `meta`
+- `contract_refs`
+- `outline_snapshot`
+- `review_result`
+- `fulfillment_result`
+- `disambiguation_result`
+- `accepted_events`
+- `state_deltas`
+- `entity_deltas`
+- `projection_status`
+
+### 9.3 提交流程
+
+标准链路应为：
+
+1. 读取 `CHAPTER_BRIEF`
+2. 写作完成
+3. 生成 `REVIEW_CONTRACT`
+4. 完成审查
+5. 生成 `CHAPTER_COMMIT` 草案
+6. 校验履约、消歧、blocking rules
+7. 通过后标记 commit accepted
+8. 投影到各存储
+
+### 9.4 投影层职责
+
+投影层至少分成四个 writer：
+
+1. `state_projection_writer`
+2. `index_projection_writer`
+3. `summary_projection_writer`
+4. `memory_projection_writer`
+
+未来可选：
+
+5. `rag_projection_writer`
+
+### 9.5 失败语义
+
+一旦 `CHAPTER_COMMIT` 未通过，不允许：
+
+1. 部分写入 `state`
+2. 部分写入 `index`
+3. 先写摘要再回头补状态
+4. 让下一章读取未确认事实
+
+也就是说：
+
+- “章节已生成”不等于“章节已提交”
+- 只有 `commit accepted` 才能进入事实主链
+
+---
+
+## 10. canonical event log 设计
+
+### 10.1 当前问题
+
+当前系统已经有：
+
+- `state_changes`
+- `relationship_events`
+- `timeline_events`
+- `world_rules`
+- `open_loops`
+- `reader_promises`
+
+但这些都还是局部事件，没有统一事件主链。
+
+### 10.2 演进目标
+
+应新增统一事件视角：
+
+- 所有章节提交都必须产出 `accepted_events`
+- 投影层基于事件更新状态，而不是只根据最终值覆盖
+
+### 10.3 事件类型
+
+最小事件族建议包括：
+
+1. `character_state_changed`
+2. `relationship_changed`
+3. `world_rule_revealed`
+4. `world_rule_broken`
+5. `power_breakthrough`
+6. `artifact_obtained`
+7. `promise_created`
+8. `promise_paid_off`
+9. `open_loop_created`
+10. `open_loop_closed`
+
+### 10.4 事件与合同的关系
+
+事件不直接修改 `MASTER / VOLUME / CHAPTER`。
+
+正确做法是：
+
+1. 事件先进入 `CHAPTER_COMMIT.accepted_events`
+2. 若事件触发上层设定变更条件，则生成 `amend proposal`
+3. 人工确认后再更新上层合同
+
+这样才能兼顾：
+
+- 文学反转的灵活性
+- 合同系统的稳定性
+
+---
+
+## 11. 写前校验与写后校验
+
+### 11.1 写前校验
+
+写前必须显式检查：
+
+1. 当前章可见合同是否存在
+2. 本章禁区是否完整
+3. 是否存在高优先级消歧 pending
+4. must cover 是否明确
+5. 当前章是否需要局部 override 摘要
+
+### 11.2 写后校验
+
+写后必须显式检查：
+
+1. `blocking rules`
+2. `mandatory_nodes` 是否履约
+3. `anti_patterns` 是否命中
+4. 关键实体命名是否稳定
+5. 是否产生需要上提的设定修改
+
+### 11.3 大纲履约机制
+
+当前系统的缺口之一，是只记录“写了什么”，不校验“该写的写了没有”。
+
+因此 `CHAPTER_COMMIT` 必须新增：
+
+- `planned_nodes`
+- `covered_nodes`
+- `missed_nodes`
+- `extra_nodes`
+
+最低要求：
+
+- `missed_nodes` 非空时，不允许静默提交成功
+
+### 11.4 消歧机制前移
+
+消歧不能只在尾部回写阶段兜底。
+
+应拆成两段：
+
+1. 写前提供 `disambiguation domain`
+   - 当前章允许出现的高频实体、别名、称谓集合
+2. 写后在 `CHAPTER_COMMIT` 阶段再做提交校验
+
+只有无法通过两段机制解决时，才进入 `disambiguation_pending`。
+
+---
+
+## 12. 现有模块的演进路径
+
+### 12.1 `reference_search.py`
+
+新定位：
+
+- 底层 primitive
+- CSV 搜索内核
+- 不再承担系统聚合职责
+
+### 12.2 `context_manager.py`
+
+新定位：
+
+- 合同优先的运行时装配器
+
+演进顺序：
+
+1. phase 1 保留原有结构
+2. phase 1 新增 `story_contract` section
+3. phase 2 固定 pack 优先级为 `chapter -> volume -> master -> old profile`
+4. phase 3 移除与“全局系统生成”重叠的逻辑
+
+### 12.3 `genre_aliases.py / genre_profile_builder.py / genre-profiles.md`
+
+新定位：
+
+- route table 建设期间的活跃种子源
+
+演进顺序：
+
+1. 人工把稳定字段迁入 `题材与调性推理.csv`
+2. `story_system` 优先读 CSV
+3. `genre-profiles.md` 退化为回退源和参考源
+
+### 12.4 `state_manager`
+
+新定位：
+
+- `CHAPTER_COMMIT` 的投影写入器协调层
+
+它不再承担“章节事实真源”的角色，而只负责：
+
+- 把已接受 commit 的状态投影写入 `state.json`
+- 与 SQLite 同步
+- 维护局部原子写和恢复机制
+
+### 12.5 `index.db`
+
+新定位：
+
+- 事实检索层
+- 事件索引层
+- 审计回溯层
+
+不再承担“故事规则主源”职责。
+
+### 12.6 `memory writer / orchestrator / summaries`
+
+新定位：
+
+- 事实补充层
+- 历史回顾层
+- 伏笔回收层
+
+阶段要求：
+
+1. phase 1 可继续沿用现状
+2. phase 2 开始只消费已 accepted 的 `CHAPTER_COMMIT`
+3. phase 3 与 canonical event log 对齐
+
+### 12.7 `override_contracts`
+
+新定位：
+
+- 统一 override ledger 的底座
+
+不能继续只服务追读力债务。
+
+### 12.8 `scripts/data_modules/config.py`
+
+新定位：
+
+- 继续作为项目级统一配置入口
+
+演进约束：
+
+1. phase 1 直接复用现有 `DataModulesConfig`
+2. `story_system` 新增配置必须挂在明确命名空间下
+3. 禁止为 `story_system` 平行再造一套完全独立的配置树
+
+否则后果会非常直接：
+
+- runtime 一套预算
+- contract 一套预算
+- projection 一套路径
+
+三套配置分叉后，合同系统会在工程层面重新失真。
+
+---
+
+## 13. 分阶段演进计划
+
+### 13.1 Phase 0：现状收束准备
+
+目标：
+
+- 不改主流程，只明确真源和优先级
+
+交付：
+
+1. 统一文档化当前真源优先级
+2. 明确 `context_manager` 的 contract 注入口
+3. 明确 `genre-profiles.md` 的过渡期定位
+4. 明确 `override_contracts` 的扩展方向
+
+### 13.2 Phase 1：合同种子层
+
+目标：
+
+- 让系统第一次拥有稳定合同
+
+交付：
+
+1. `题材与调性推理.csv`
+2. 最小 `MASTER_SETTING`
+3. 最小 `CHAPTER_BRIEF`
+4. `anti_patterns.json`
+5. `context_manager` 读取合同
+
+此阶段仍允许：
+
+- 保留旧写作链
+- 保留 `genre-profiles.md` 回退
+- 不引入 `VOLUME_BRIEF`
+
+### 13.3 Phase 2：合同优先运行时
+
+目标：
+
+- 让写作、规划、审查都以合同为主输入
+
+交付：
+
+1. `VOLUME_BRIEF`
+2. `REVIEW_CONTRACT`
+3. 写前禁区与消歧域
+4. 大纲履约 diff
+5. `context_manager` contract-first pack
+
+此阶段的关键变化：
+
+- “临时拼资料”不再是默认路径
+- “合同优先 + 局部 reference 按需加载”成为默认路径
+
+### 13.4 Phase 3：章节提交主链
+
+目标：
+
+- 让所有事实回写经过统一章节提交对象
+
+交付：
+
+1. `CHAPTER_COMMIT`
+2. 四类 projection writers
+3. accepted / rejected commit 语义
+4. 写后回写改为 commit 驱动
+
+此阶段完成后：
+
+- 章节事实真源将从散写转为统一提交对象
+
+### 13.5 Phase 4：统一事件主链
+
+目标：
+
+- 让事件成为系统演进的正式输入
+
+交付：
+
+1. canonical event log
+2. 事件到投影的稳定映射
+3. 事件到 amend proposal 的触发规则
+
+### 13.6 Phase 5：旧链路降级
+
+目标：
+
+- 把旧中枢从主链降级为回退或投影层
+
+退出条件：
+
+1. 合同已成为默认主输入
+2. `CHAPTER_COMMIT` 已成为默认提交主链
+3. `genre-profiles.md` 已完成高频题材迁移
+4. `context_manager` 不再独立生成与合同冲突的全局系统判断
+
+---
+
+## 14. 数据与目录建议
+
+### 14.1 合同目录
+
+本项目已有权威**运行时**目录术语，后续 story system 必须复用，不得自造新说法。
+
+需要先明确一件事：
+
+- 当前这个仓库只是**插件源码开发目录**
+- 它不是插件安装后的运行时根目录
+- story system 的落盘路径必须基于**Claude Code 安装后的真实运行目录模型**来定义
+
+因此后续所有路径说明，都应基于运行时的三层目录：
+
+1. `CLAUDE_PLUGIN_ROOT`
+   - Claude Code 插件安装目录
+   - 存放 `skills/ agents/ scripts/ references/`
+   - **不允许**在这里写入小说项目数据
+2. `WORKSPACE_ROOT`
+   - 当前工作区根目录，可通过 `.claude/.webnovel-current-project` 指针解析当前书项目
+3. `PROJECT_ROOT`
+   - **书项目根目录**
+   - 定义为：**包含 `.webnovel/state.json` 的目录**
+
+`Story Contract` 和 `CHAPTER_COMMIT` 都是**某一本书**的持久化产物，因此必须落在 `PROJECT_ROOT`，而不是：
+
+- 当前源码仓库目录
+- `CLAUDE_PLUGIN_ROOT`
+- `WORKSPACE_ROOT`
+
+基于当前已有真实目录，可以直接参考：
+
+- `WORKSPACE_ROOT = D:\wk\xiaoshuo`
+- `PROJECT_ROOT = D:\wk\xiaoshuo\凡人资本论`
+- 指针文件 = `D:\wk\xiaoshuo\.claude\.webnovel-current-project`
+
+该例也说明两件事：
+
+1. `PROJECT_ROOT` 是工作区内的某一本书目录
+2. `PROJECT_ROOT` 自身可以是一个独立 git 仓库（例如当前示例里就存在 `.git/`）
+
+建议目录如下：
+
+```text
+WORKSPACE_ROOT/
+├── .claude/
+│   └── .webnovel-current-project
+├── 小说A/
+├── 小说B/
+└── ...
+
+PROJECT_ROOT/
+├── .git/                  # 可选：书项目自身可独立版本管理
+├── 正文/
+├── 大纲/
+├── 设定集/
+├── 审查报告/
+├── .webnovel/
+└── .story-system/
+    ├── MASTER_SETTING.json
+    ├── MASTER_SETTING.md
+    ├── anti_patterns.json
+    ├── anti_patterns.md
+    ├── volumes/
+    │   ├── volume_001.json
+    │   └── volume_001.md
+    ├── chapters/
+    │   ├── chapter_001.json
+    │   └── chapter_001.md
+    ├── reviews/
+    │   ├── chapter_001.review.json
+    │   └── chapter_001.review.md
+    └── commits/
+        ├── chapter_001.commit.json
+        └── chapter_001.commit.md
+```
+
+这里的 `.story-system/` 必须明确为：
+
+- **相对于 `PROJECT_ROOT`**
+
+而不是：
+
+- 当前源码仓库目录
+- `CLAUDE_PLUGIN_ROOT`
+- `WORKSPACE_ROOT`
+- 任意当前工作目录
+
+如果后续 implementation plan 中出现“根目录”表述，必须显式区分：
+
+1. `CLAUDE_PLUGIN_ROOT`
+2. `WORKSPACE_ROOT`
+3. `PROJECT_ROOT`
+
+### 14.1.1 路径解析约束
+
+所有运行时入口都应遵守现有统一规则：
+
+1. 允许外部传入 `WORKSPACE_ROOT`
+2. 统一经 `resolve_project_root(...)` 解析到真实 `PROJECT_ROOT`
+3. 所有 `.story-system` 读写都基于解析后的 `PROJECT_ROOT`
+
+这意味着：
+
+- CLI 可以接受 `--project-root`，但它实际允许传入“书项目根目录或工作区根目录”
+- 入口层负责解析
+- 合同层和提交层只认最终解析后的 `PROJECT_ROOT`
+- 如果用户当前只站在 `WORKSPACE_ROOT`，也应先经统一入口解析到真实书项目，再操作 `.story-system/`
+
+### 14.2 真源规则
+
+规则固定为：
+
+1. `*.json` 是真源
+2. `*.md` 是只读渲染产物
+3. `reviews/` 和 `commits/` 也遵循相同规则
+
+### 14.3 命名规范
+
+统一使用零填充：
+
+- `volume_001`
+- `chapter_001`
+
+不要把自然语言标题写进文件名。
+
+---
+
+## 15. 知识层承接策略
+
+### 15.1 CSV 的职责
+
+CSV 继续承担：
+
+- 条目知识
+- 路由知识
+- 结构化红线
+- 检索触发词与同义词
+
+### 15.2 MD 的职责
+
+MD 继续承担：
+
+- 方法论
+- 审查规则
+- anti-AI
+- 润色、口吻、排版规范
+
+### 15.3 当前阶段的结论
+
+在演进完成前，不应说“CSV 已完全替代 MD”。
+
+正确说法是：
+
+- CSV 承担规则与路由
+- MD 承担方法论与执行手册
+- 合同负责把当前书真正需要的那部分结构化知识前置收束出来
+
+---
+
+## 16. 测试与验证策略
+
+### 16.1 总原则
+
+不做“每条知识点一个测试”的重型方案。
+
+### 16.2 必须验证的内容
+
+最小验证集应覆盖：
+
+1. 合同生成成功
+2. 覆盖规则正确
+3. `anti_patterns` 聚合正确
+4. `context_manager` 能正确读取合同
+5. `REVIEW_CONTRACT` 能正确表达 blocking rules
+6. `CHAPTER_COMMIT` 能阻止未通过校验的回写
+7. projection writers 只消费 accepted commit
+8. 事件能进入 canonical event log
+
+### 16.3 不需要做的事
+
+不需要：
+
+1. 为每条 CSV 内容单独断言
+2. 为每个知识点做机械语义测试
+3. 把数据内容测试做成主工作量
+
+---
+
+## 17. 文档与运维要求
+
+### 17.1 文档更新要求
+
+后续任何 implementation plan 都必须显式包含：
+
+1. 合同 schema 文档更新
+2. 目录结构文档更新
+3. 运行流程文档更新
+4. 迁移说明文档更新
+
+### 17.2 运维接入要求
+
+`.story-system` 不得成为运维盲区。
+
+至少应接入：
+
+1. preflight
+2. dashboard
+3. health check
+4. backup / restore
+
+### 17.3 健康检查最低项
+
+最低应检查：
+
+1. `MASTER_SETTING.json` 是否存在
+2. 合同 schema 是否可读
+3. `chapter commit` 是否存在 rejected 未处理积压
+4. projection status 是否出现长期未完成
+
+---
+
+## 18. 最终架构结论
+
+这份演进 spec 的最终判断可以压缩成四句话：
+
+1. 当前系统的主要问题不是模块太少，而是主链缺失
+2. 现有的 `context_manager / genre_* / state_manager / memory / override_contracts` 都应保留，但要重定位
+3. 真正要新增的核心不是又一个检索入口，而是 `Story Contract + Chapter Commit + Override Ledger + Canonical Event Log`
+4. 当合同成为写前真源、提交成为写后真源后，系统才算真正从“多中枢缝合”进化为“统一故事操作系统”
+
+---
+
+## 19. 实施建议
+
+如果后续进入开发，不建议直接从“事件总线”开工。
+
+正确顺序应是：
+
+1. 先把合同种子层跑通
+2. 再让运行时 contract-first
+3. 再建立 `CHAPTER_COMMIT`
+4. 最后统一事件主链
+
+否则项目会先陷入“事件建模很完整，但写作主链仍然散乱”的伪进展。
+
+这份 spec 的直接后续产物应当是：
+
+- implementation plan
+
+并且该 plan 必须显式包含：
+
+1. 文档更新任务
+2. 目录与路径语义更新任务
+3. runtime 接入点更新任务

docs/superpowers/specs/2026-04-12-story-system-pro-max-retrofit-spec.md

@@ -0,0 +1,878 @@
+# Webnovel Writer Story System Pro Max 架构改造 Spec
+
+> 日期：2026-04-12
+> 状态：草案 v1
+> 目标：在不破坏现有 `reference_search.py` 与 CSV 检索契约的前提下，为 Webnovel Writer 增加“题材推理 + 多表聚合 + Master/Chapter 持久化覆盖”能力。
+
+---
+
+## 1. 文档定位
+
+### 1.1 与既有 spec 的关系
+
+本 spec 是以下文档的补充，不替代它们：
+
+- `2026-04-02-harness-v6-design.md`
+- `2026-04-09-skills-restructure-and-reference-gaps.md`
+
+其中：
+
+- `2026-04-02-harness-v6-design.md` 负责主流程与 harness 架构。
+- `2026-04-09-skills-restructure-and-reference-gaps.md` 负责 `skills / references / scripts` 的职责边界与 reference 设计原则。
+- **本 spec** 负责在现有 CSV 知识库之上，补出一个新的系统层：`Story System`。
+
+### 1.2 本 spec 要解决的问题
+
+当前系统已经能做离散检索，但仍存在三个结构性问题：
+
+1. 检索结果是“散条目”，不是“系统设定”。
+2. 大模型看完单次搜索结果后，容易遗忘全局约束与毒点。
+3. 不同章节缺少稳定的“局部覆盖全局”的持久化承载方式。
+
+因此需要引入一个新的上层能力：
+
+- 先做题材/流派层面的全局路由
+- 再做多表聚合
+- 最后持久化为 `MASTER + Chapter Overrides`
+
+---
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+本轮改造目标只有五个：
+
+1. 新增一张“题材与调性推理”路由表，用来把模糊题材输入转成结构化写作方向。
+2. 新增 `story_system.py`，作为现有 CSV 检索之上的聚合器。
+3. 定义 `StorySystemDict` 的稳定数据契约。
+4. 建立 `.story-system/` 的持久化规范，并明确 `Master + Overrides` 的覆盖规则。
+5. 为后续 skills / prompt 集成预留稳定挂点。
+
+### 2.2 非目标
+
+本轮**不做**以下事情：
+
+1. 不替换或改写现有 `reference_search.py` 的职责。
+2. 不把所有 md reference 全量迁入 CSV。
+3. 不强制把所有现有 CSV 表的毒点字段改成同一个列名。
+4. 不在本 spec 中假定某个具体 `SKILL.md` 文件一定存在于当前仓库。
+5. 不要求重型测试矩阵，也不要求对每个知识点逐条写测试。
+
+---
+
+## 3. 设计原则
+
+### 3.1 保留底层检索 primitive
+
+[`reference_search.py`](D:/wk/novel%20skill/webnovel-writer/webnovel-writer/scripts/reference_search.py) 当前已经稳定承担以下职责：
+
+- 读取 CSV
+- 按 `skill / table / query / genre` 过滤
+- 做 BM25-lite 评分
+- 返回稳定 JSON envelope
+
+该脚本已有回归测试保护，见：
+
+- [`test_reference_search.py`](D:/wk/novel%20skill/webnovel-writer/webnovel-writer/scripts/tests/test_reference_search.py)
+
+因此本轮不应把它改造成系统级聚合器。正确分层应为：
+
+- `reference_search.py`：底层单次搜索 primitive
+- `story_system.py`：系统级 orchestration 与持久化入口
+
+### 3.2 不强推现有表结构大改
+
+现有 CSV 契约已在 [`README.md`](D:/wk/novel%20skill/webnovel-writer/webnovel-writer/references/csv/README.md) 中明确，当前内容量也已经较大。
+
+本轮应坚持：
+
+- **新增优于重写**
+- **映射优于大规模改列名**
+- **只对真正缺失的能力加新结构**
+
+### 3.3 Master 与 Chapter 必须可机读
+
+如果 `.story-system/` 只保存“给人看的 markdown”，后续 agent 仍需要再次解析半结构化文本，容易变脆。
+
+因此本轮持久化必须采用**双产物**：
+
+- Markdown：给人读
+- JSON：给脚本和 agent 读
+
+### 3.4 覆盖规则必须显式，不允许模糊覆盖
+
+不能只写“chapter 覆盖 master”。
+
+必须把字段分成三类：
+
+1. `locked`：禁止局部覆盖
+2. `append_only`：局部只能补充
+3. `override_allowed`：局部允许覆盖
+
+否则局部设定会轻易冲掉全局设定与全局红线。
+
+### 3.5 Anti-Patterns 只做归一化聚合，不做强行同名
+
+现有各表的“毒点/误区”字段不统一，例如：
+
+- `场景写法.csv`：`反面写法`
+- `写作技法.csv`：`常见误区`
+- `爽点与节奏.csv`：`常见崩盘误区`
+- `人设与关系.csv`：`忌讳写法`
+
+这本身没有问题。
+
+本轮正确做法是：
+
+- 在 `story_system.py` 内建立 anti-pattern source field 映射
+- 在渲染阶段统一归一化为 `Anti-Patterns`
+- 只对真正缺失毒点承载的表，新增专门字段
+
+---
+
+## 4. 当前基线
+
+### 4.1 当前可用 CSV 表
+
+当前 `references/csv` 中已存在：
+
+- `命名规则.csv`
+- `场景写法.csv`
+- `写作技法.csv`
+- `桥段套路.csv`
+- `人设与关系.csv`
+- `爽点与节奏.csv`
+- `金手指与设定.csv`
+
+### 4.2 当前 CSV 通用契约
+
+现有通用列已稳定：
+
+- `编号`
+- `适用技能`
+- `分类`
+- `层级`
+- `关键词`
+- `意图与同义词`
+- `适用题材`
+- `大模型指令`
+- `核心摘要`
+- `详细展开`
+
+因此新增表应继续遵守这个契约，而不是重新发明一套列体系。
+
+### 4.3 当前缺失能力
+
+当前系统缺失的不是“知识量”，而是以下能力：
+
+1. 对模糊题材输入做全局路由的能力
+2. 在多张表之间做分层聚合的能力
+3. 把聚合结果稳定落地为章节级覆盖文档的能力
+
+---
+
+## 5. 新增数据结构：题材与调性推理.csv
+
+### 5.1 文件位置
+
+新增文件：
+
+- `webnovel-writer/references/csv/题材与调性推理.csv`
+
+建议前缀：
+
+- `GR-`
+
+### 5.2 文件职责
+
+这不是普通知识条目表，而是**路由表**。
+
+它的职责不是提供某一个桥段/某一种技法，而是回答：
+
+- 这个题材的大基调是什么
+- 这个题材的节奏应该怎么起
+- 这个题材优先查哪些基础表
+- 这个题材优先查哪些动态表
+- 这个题材绝对不能碰哪些毒点
+
+### 5.3 列设计
+
+除通用列外，新增以下专属列：
+
+| 列名 | 必填 | 说明 |
+|------|------|------|
+| `题材/流派` | 是 | 主标签，如“赘婿流”“赛博朋克黑客流”“规则动物园” |
+| `题材别名` | 是 | 同义词、平台黑话、俗称，使用 `|` |
+| `核心调性` | 是 | 全局情绪与气质 |
+| `节奏策略` | 是 | 开局节奏、兑现节奏、章节节拍 |
+| `主冲突模板` | 否 | 默认冲突骨架 |
+| `必选爽点` | 否 | 该题材高频必备交付 |
+| `强制禁忌/毒点` | 是 | 题材级全局红线 |
+| `推荐基础检索表` | 是 | 如 `命名规则|人设与关系|金手指与设定` |
+| `推荐动态检索表` | 是 | 如 `桥段套路|爽点与节奏|场景写法` |
+| `基础检索权重` | 否 | 对基础表的排序提示 |
+| `动态检索权重` | 否 | 对动态表的排序提示 |
+| `默认查询词` | 否 | 当用户输入过于模糊时的默认扩展检索词 |
+
+### 5.4 设计说明
+
+这张表必须能同时服务三类输入：
+
+1. 明确题材输入
+   例如：`赘婿流`
+
+2. 组合题材输入
+   例如：`赛博朋克黑客流`
+
+3. 模糊风格输入
+   例如：`压抑一点，后面爆`
+
+因此 `题材别名` 和 `默认查询词` 是必要字段，不是可有可无。
+
+---
+
+## 6. Anti-Patterns 归一化规则
+
+### 6.1 现有表的归一化映射
+
+本轮不强制全表改名，采用映射层：
+
+```python
+ANTI_PATTERN_SOURCE_FIELDS = {
+    "场景写法": ["反面写法"],
+    "写作技法": ["常见误区"],
+    "爽点与节奏": ["常见崩盘误区"],
+    "人设与关系": ["忌讳写法"],
+    "桥段套路": ["忌讳写法"],
+    "题材与调性推理": ["强制禁忌/毒点"],
+}
+```
+
+### 6.2 桥段套路.csv 的处理
+
+当前 `桥段套路.csv` 只有：
+
+- `桥段名称`
+- `前置铺垫`
+- `核心爽点`
+- `转折设计`
+- `反套路变种`
+
+其中 `反套路变种` 不是 anti-pattern 字段，不能直接拿来当“毒点”。
+
+因此本轮建议：
+
+- 为 `桥段套路.csv` **新增** `忌讳写法` 列
+- 新录入条目逐步补齐
+- 老条目允许暂时为空
+
+### 6.3 最终聚合规则
+
+系统渲染时的 `Anti-Patterns` 为以下内容的并集：
+
+1. `题材与调性推理.csv` 的全局毒点
+2. 动态检索命中的条目级毒点
+3. Chapter 局部追加毒点
+
+注意：
+
+- Chapter 可以**新增**局部毒点
+- Chapter 不能删除 Master 的全局毒点
+
+---
+
+## 7. 新增脚本：story_system.py
+
+### 7.1 文件位置
+
+新增：
+
+- `webnovel-writer/scripts/story_system.py`
+
+### 7.2 角色定位
+
+`story_system.py` 是系统聚合层，不是底层检索层。
+
+它负责：
+
+1. 题材路由
+2. 多表查询编排
+3. 结果聚合
+4. Markdown / JSON 双格式输出
+5. `.story-system/` 持久化
+
+它不负责：
+
+1. 替代 `reference_search.py`
+2. 直接生成正文
+3. 解析或执行具体 skill 主流程
+
+### 7.3 CLI 设计
+
+建议 CLI：
+
+```bash
+python story_system.py "玄幻退婚流"
+python story_system.py "玄幻退婚流" --persist
+python story_system.py "拍卖会打脸" --persist --chapter chapter_015
+python story_system.py "压抑一点，后面爆" --genre 现言 --persist
+python story_system.py "规则动物园" --format json
+```
+
+建议参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| 位置参数 `query` | 是 | 用户当前意图或题材描述 |
+| `--genre` | 否 | 手动指定题材 |
+| `--chapter` | 否 | 章节 override 名，如 `chapter_015` |
+| `--persist` | 否 | 是否写入 `PROJECT_ROOT/.story-system/` |
+| `--format` | 否 | `markdown` / `json` / `both` |
+| `--csv-dir` | 否 | 兼容测试与自定义目录 |
+| `--story-root` | 否 | 指定显式 `.story-system/` 目录；仅开发/测试场景使用，主链运行时默认基于 `PROJECT_ROOT` 解析 |
+
+### 7.4 主流程
+
+`story_system.py` 的执行顺序应固定为：
+
+#### Step 1：题材推理
+
+输入 `query` 后，优先查 `题材与调性推理.csv`：
+
+- 若命中明确题材 → 使用题材路由结果
+- 若命中多个题材 → 做加权排序并返回主路由 + 候选路由
+- 若未命中 → 进入 fallback
+
+#### Step 2：fallback 路由
+
+未命中时，按以下顺序降级：
+
+1. 用户手动传入 `--genre` 时，以 `--genre` 为主
+2. 从 `query` 中抽取与现有各表高频关键词最接近的题材名
+3. 若仍失败，进入“通用写作路由”：
+   - 基础表默认查：`命名规则|人设与关系|金手指与设定`
+   - 动态表默认查：`桥段套路|爽点与节奏|场景写法`
+
+#### Step 3：基础表检索
+
+根据题材路由表给出的 `推荐基础检索表`：
+
+- 对每张基础表取 Top 1
+- 基础表默认包括：
+  - `命名规则`
+  - `人设与关系`
+  - `金手指与设定`
+  - 未来可扩展：`题材与调性推理`
+
+#### Step 4：动态表检索
+
+根据题材路由表给出的 `推荐动态检索表`：
+
+- 对每张动态表取 Top 2
+- 动态表默认包括：
+  - `桥段套路`
+  - `爽点与节奏`
+  - `场景写法`
+  - 可选补充：`写作技法`
+
+#### Step 5：Anti-Patterns 聚合
+
+把题材级毒点和条目级误区字段做统一归并。
+
+#### Step 6：渲染与持久化
+
+输出：
+
+- `StorySystemDict`
+- Markdown 视图
+- 可选写入 `.story-system/`
+
+---
+
+## 8. StorySystemDict 数据契约
+
+### 8.1 顶层结构
+
+建议数据结构：
+
+```json
+{
+  "meta": {},
+  "route": {},
+  "master_constraints": {},
+  "base_context": {},
+  "dynamic_context": {},
+  "anti_patterns": [],
+  "override_policy": {},
+  "source_trace": []
+}
+```
+
+### 8.2 详细字段
+
+#### `meta`
+
+记录：
+
+- 查询词
+- 显式题材
+- 推理命中题材
+- 是否 chapter 模式
+- 生成时间
+
+#### `route`
+
+记录：
+
+- 主路由题材
+- 候选题材
+- 路由命中依据
+- 推荐基础表
+- 推荐动态表
+
+#### `master_constraints`
+
+记录全局不可轻易改动的内容：
+
+- 核心调性
+- 节奏策略
+- 主冲突模板
+- 金手指硬限制
+- 主角硬约束
+- 全局毒点
+
+#### `base_context`
+
+保存基础表检索结果：
+
+- `命名规则`
+- `人设与关系`
+- `金手指与设定`
+- 可选 `写作技法`
+
+#### `dynamic_context`
+
+保存动态表检索结果：
+
+- `桥段套路`
+- `爽点与节奏`
+- `场景写法`
+
+#### `anti_patterns`
+
+统一格式：
+
+```json
+[
+  {
+    "source_table": "爽点与节奏",
+    "source_id": "PA-054",
+    "text": "质疑太弱没有压迫"
+  }
+]
+```
+
+#### `override_policy`
+
+显式写出：
+
+- `locked`
+- `append_only`
+- `override_allowed`
+
+#### `source_trace`
+
+记录本次命中的来源：
+
+- 表名
+- 编号
+- 摘要
+- 指令
+
+这部分主要用于调试和回溯。
+
+---
+
+## 9. Markdown Formatter 规范
+
+### 9.1 输出目标
+
+Markdown 不是原始数据，而是人类和 agent 的可读视图。
+
+它必须做到：
+
+1. 有明显层次
+2. 一眼能看见全局基调
+3. 一眼能看见本章覆盖项
+4. 一眼能看见绝对毒点
+
+### 9.2 建议结构
+
+建议 Markdown 输出结构：
+
+```markdown
+# Story System
+
+## Meta
+
+## Route
+
+## Master Constraints
+
+## Base Context
+
+## Dynamic Context
+
+## Anti-Patterns
+
+## Source Trace
+```
+
+### 9.3 Anti-Patterns 章节要求
+
+必须保留一个显著章节：
+
+```markdown
+## Anti-Patterns（绝对毒点，切勿触碰）
+```
+
+展示规则：
+
+- 每条红线单独成条
+- 用反引号包裹短句
+- 标明来源表与编号
+
+例如：
+
+```markdown
+- `严禁配角连续抢戏超过 300 字`（来源：GR-003）
+- `打脸节奏不能缺最后一拍补刀`（来源：PA-054）
+```
+
+### 9.4 JSON 与 Markdown 的关系
+
+规则必须明确：
+
+- JSON 是真实源数据
+- Markdown 是 JSON 的投影视图
+- 任何覆盖合并逻辑以 JSON 为准，不以 Markdown 反向解析为准
+
+---
+
+## 10. 持久化架构：.story-system
+
+### 10.1 目录结构
+
+这里必须遵守项目现有运行时目录术语，而不是使用当前源码仓库目录做推断：
+
+1. `CLAUDE_PLUGIN_ROOT`
+   - 插件安装目录
+   - 存放 `skills / scripts / references`
+   - 不写入书项目数据
+2. `WORKSPACE_ROOT`
+   - Claude 工作区根目录
+   - 通过 `.claude/.webnovel-current-project` 指针解析当前书项目
+3. `PROJECT_ROOT`
+   - 真实书项目根目录
+   - 定义为：包含 `.webnovel/state.json` 的目录
+
+因此 `.story-system/` 的默认落盘位置必须是：
+
+- `PROJECT_ROOT/.story-system/`
+
+而不是：
+
+- 当前源码仓库目录
+- `CLAUDE_PLUGIN_ROOT`
+- `WORKSPACE_ROOT`
+
+建议目录：
+
+```text
+PROJECT_ROOT/
+  .webnovel/
+  正文/
+  大纲/
+  设定集/
+  .story-system/
+    MASTER_SETTING.md
+    MASTER_SETTING.json
+    chapters/
+      chapter_001.md
+      chapter_001.json
+      chapter_015.md
+      chapter_015.json
+```
+
+运行时约束补充：
+
+1. skills 默认从 `WORKSPACE_ROOT` 出发
+2. 统一经 `webnovel.py --project-root "${WORKSPACE_ROOT}" where` 解析到真实 `PROJECT_ROOT`
+3. `story_system` 若进入主链，应只认解析后的 `PROJECT_ROOT`
+4. `--story-root` 只作为开发期 override，不应成为 skills 的默认输入
+
+### 10.2 MASTER 的职责
+
+`MASTER_SETTING.*` 负责保存：
+
+- 题材主路由
+- 全局调性
+- 主角硬约束
+- 金手指硬约束
+- 世界级约束
+- 长线节奏策略
+- 全局 anti-patterns
+
+### 10.3 Chapter 的职责
+
+`chapters/chapter_xxx.*` 负责保存：
+
+- 本章桥段
+- 本章场景
+- 本章局部节奏
+- 本章局部额外毒点
+- 本章特殊强调项
+
+### 10.4 覆盖分类
+
+#### 10.4.1 `locked`
+
+以下内容只能从 Master 读取，chapter 不允许覆盖：
+
+- 主路由题材
+- 核心调性
+- 主角底层人设
+- 金手指硬限制
+- 世界规则闭环
+- 全局 anti-patterns
+
+#### 10.4.2 `append_only`
+
+以下内容 chapter 只能补充，不可删除 master 已有内容：
+
+- 命名语系
+- 长线伏笔
+- 长线关系提醒
+- 全局禁区补充
+- 重要 source trace
+
+合并方式：
+
+- 并集
+- 去重
+
+#### 10.4.3 `override_allowed`
+
+以下内容 chapter 可覆盖 master 默认值：
+
+- 本章桥段
+- 本章场景
+- 本章节奏目标
+- 本章局部情绪侧重
+- 本章输出重点
+
+### 10.5 Anti-Patterns 合并规则
+
+最终写作时生效的红线为：
+
+```text
+生效红线 = Master 全局红线 ∪ Chapter 局部红线
+```
+
+注意：
+
+- Chapter 可以加新红线
+- Chapter 不能移除 Master 红线
+
+### 10.6 文件更新策略
+
+为避免覆盖人工修改，本轮建议采用以下策略：
+
+1. JSON 文件由脚本完全管理
+2. Markdown 文件可带人工备注区
+3. 脚本只更新带 marker 的自动生成区块
+
+建议 marker：
+
+```markdown
+<!-- STORY-SYSTEM:BEGIN -->
+... 自动生成内容 ...
+<!-- STORY-SYSTEM:END -->
+```
+
+marker 外的手写内容，脚本不得改动。
+
+---
+
+## 11. Prompt / Skill 集成契约
+
+### 11.1 本轮只定义契约，不假定具体挂点
+
+当前仓库中未直接暴露可改的 `webnovel-plan` / `webnovel-write` 的 `SKILL.md` 文件落点。
+
+因此本 spec 不假定：
+
+- prompt 一定在本仓库
+- skill 一定在本仓库
+- 运行时一定从哪个路径自动读取
+
+本轮只定义**接入契约**。
+
+### 11.2 标准读取逻辑
+
+未来接入层必须满足：
+
+1. 如果存在 `chapters/[当前章节].json`，优先读取它。
+2. 对于 `override_allowed` 字段，chapter 优先。
+3. 对于 `append_only` 字段，chapter 与 master 合并。
+4. 对于 `locked` 字段，只能读取 master。
+5. 最终始终附带全局与局部合并后的 `Anti-Patterns`。
+
+### 11.3 标准提示词片段
+
+接入层建议使用如下约束：
+
+```markdown
+【核心状态读取逻辑】
+1. 若存在 `.story-system/chapters/[当前章节].json`，先读 chapter。
+2. `override_allowed` 字段以 chapter 为准。
+3. `append_only` 字段按并集合并。
+4. `locked` 字段只能服从 `.story-system/MASTER_SETTING.json`。
+5. `Anti-Patterns` 为全局与局部的并集，任何一条都不可违反。
+```
+
+---
+
+## 12. 实施阶段
+
+### Phase 1：数据层
+
+交付：
+
+1. 新增 `题材与调性推理.csv`
+2. 为 `桥段套路.csv` 新增 `忌讳写法`
+3. 更新 `references/csv/README.md`
+
+本阶段不要求批量改写既有表内容。
+
+### Phase 2：聚合脚本
+
+交付：
+
+1. 新增 `story_system.py`
+2. 保持 `reference_search.py` 不改职责
+3. 实现 `StorySystemDict`
+4. 实现 Markdown / JSON 输出
+
+### Phase 3：持久化
+
+交付：
+
+1. `.story-system/` 自动创建
+2. `MASTER_SETTING.*` 持久化
+3. `chapter_xxx.*` 持久化
+4. marker 区块更新逻辑
+
+### Phase 4：接入层
+
+交付：
+
+1. 定位真实的 skill / prompt 挂点
+2. 按本 spec 的读取优先级接入
+3. 验证 chapter override 能正确覆盖局部字段
+
+---
+
+## 13. 测试策略
+
+### 13.1 测试原则
+
+本项目不需要把每个知识点都写成测试。
+
+本轮测试只保护系统契约，不保护内容细节。
+
+### 13.2 必要测试
+
+至少新增以下轻量测试：
+
+1. **题材路由测试**
+   - 输入明确题材时能命中 `题材与调性推理.csv`
+   - 输入模糊 query 时能走 fallback
+
+2. **聚合结构测试**
+   - `StorySystemDict` 顶层字段完整
+   - 基础表与动态表结果落在正确 section
+
+3. **anti-pattern 聚合测试**
+   - 不同表的误区字段能被统一提取
+   - Master 与 Chapter 的红线会做并集
+
+4. **覆盖规则测试**
+   - `locked` 不会被 chapter 覆盖
+   - `append_only` 正确并集
+   - `override_allowed` chapter 优先
+
+5. **持久化测试**
+   - `--persist` 会写出 md + json
+   - marker 外的人工内容不会被覆盖
+
+6. **底层搜索回归**
+   - 现有 `reference_search.py` 测试继续通过
+
+### 13.3 不要求的测试
+
+本轮不要求：
+
+1. 每条 CSV 知识点逐条断言
+2. Markdown 渲染的视觉细节快照测试
+3. 复杂端到端 agent 测试
+
+---
+
+## 14. 风险与约束
+
+### 14.1 最大风险
+
+最大风险不是代码复杂度，而是职责混淆。
+
+必须避免：
+
+1. 把 `reference_search.py` 改坏
+2. 把 Markdown 当源数据
+3. 让 Chapter 冲掉 Master 硬限制
+4. 把 `反套路变种` 错当成毒点字段
+
+### 14.2 数据录入约束
+
+本轮仍遵守当前 CSV 原则：
+
+- 新内容以人工整理为主
+- 不做 md 全量自动迁移
+- 不要求一次性补全所有题材
+
+### 14.3 上线顺序约束
+
+正确上线顺序必须是：
+
+1. 先补路由表
+2. 再写聚合器
+3. 再做持久化
+4. 最后才接入 prompt / skill
+
+不能跳过中间层，直接让 prompt 去拼 CSV 检索结果。
+
+---
+
+## 15. 最终结论
+
+本轮架构升级的核心不是“把检索做得更大”，而是：
+
+1. **保留现有检索 primitive 的稳定性**
+2. **新增一层 Story System 聚合器**
+3. **把全局约束与局部覆盖持久化**
+4. **让大模型服从结构化系统，而不是每次重新理解散乱结果**
+
+最终目标不是“搜索更花”，而是：
+
+**开书有 Master，写章有 Override，任何时刻都有可追溯、可持久、可服从的系统级上下文。**

docs/superpowers/specs/2026-04-12-webnovel-story-intelligence-system-spec.md

@@ -0,0 +1,1845 @@
+# Webnovel Writer Story Intelligence System 理想态重构 Spec
+
+> 日期：2026-04-12
+> 状态：草案 v2
+> 定位：理想态总架构蓝图
+
+---
+
+## 1. 文档定位
+
+### 1.1 这份 spec 解决什么问题
+
+当前 `webnovel-writer` 已经具备以下能力：
+
+- `references/csv/` 提供条目化知识检索
+- `references/*.md` 提供方法论与流程约束
+- `scripts/data_modules/` 提供 state / index / memory / context 的运行时能力
+- `skills/webnovel-*` 提供初始化、规划、写作、审查等执行入口
+
+但当前系统更准确的状态是：
+
+- 已经具备 `L0 / L1 / L2` 的按步加载能力
+- 已经具备 `md 必读 + CSV 检索` 的双轨 reference 体系
+- 已经具备 `context_manager + genre_*` 这类半成品聚合能力
+
+真正缺的不是“会不会按需读取资料”，而是：
+
+1. 缺少统一的**聚合中间层**，把题材、节奏、桥段、毒点、人设、金手指装成一个系统
+2. `reference_search.py` 只能返回散条目，不能生成稳定的故事系统合同
+3. `context_manager / genre_*` 还没有演进成可持久化的 `Story Contract`
+4. 全局设定与章节局部要求没有稳定的 `Master + Overrides` 承载结构
+
+本 spec 的目标不是继续增强“检索”，而是把项目升级成一个：
+
+- 先推理
+- 再聚合
+- 再持久化
+- 最后由 skill 消费合同
+
+的 `Story Intelligence System`。
+
+### 1.2 与现有 spec 的关系
+
+仓库中已有：
+
+- `2026-04-09-skills-restructure-and-reference-gaps.md`
+- `2026-04-12-story-system-pro-max-retrofit-spec.md`
+
+它们分别解决：
+
+- `2026-04-09`：`skills / references / scripts` 的职责边界与资料缺口
+- `2026-04-12 retrofit`：在不大改现有链路的前提下，为现系统补一个较保守的 `story_system`
+
+本 spec 与它们不同：
+
+- 本 spec **不以兼容旧入口为前提**
+- 本 spec **不遵守最小改动原则**
+- 本 spec 讨论的是项目的**理想态重构目标**
+
+换句话说：
+
+- `retrofit spec` 是“怎么稳妥地补”
+- 本 spec 是“如果重做一版，最优架构应该长什么样”
+
+### 1.2.1 与 retrofit spec 的复用 / 替代边界
+
+为避免后续实施时两份 spec 相互打架，这里明确边界：
+
+#### 可直接复用的部分
+
+- CSV 通用列契约
+- `reference_search.py` 作为底层 primitive 的定位
+- `.story-system/` 作为持久化目录的基本方向
+- anti-pattern 的“显式负面字段优先”原则
+- `StorySystemDict` 作为 phase 1 JSON contract 的种子结构
+
+#### 本 spec 对 retrofit 的超集扩展
+
+- 把两层持久化扩展为 `Master / Volume / Chapter` 三层
+- 把 `StorySystemDict` 扩展为合同家族，而不再只是一份聚合结果
+- 把 `skills` 的定位从“直接读 reference”升级为“合同优先 + 局部按需加载”
+- 把 `state / memory / index` 明确下沉为运行时事实层
+
+#### 本 spec 对 retrofit 的替代决策
+
+- `story_system.py` 不再只是一个附加脚本，而是未来的一线中枢
+- `genre-profiles.md` 不再担任核心配置中心
+- `templates/genres/*.md` 不再担任题材主知识源
+
+如果两份 spec 出现冲突，裁决原则为：
+
+1. phase 1 工程落地，优先服从 `retrofit spec`
+2. phase 2 及以后重构目标，优先服从本 spec
+
+### 1.3 借鉴对象
+
+本 spec 明确借鉴 `ui-ux-pro-max-skill` 的核心链路，而不是照搬它的文件名：
+
+1. 多域数据仓
+2. reasoning engine
+3. 聚合器
+4. anti-patterns 汇总
+5. 稳定输出 contract
+6. skill 以 contract 为主消费系统信息
+
+对 `webnovel-writer` 来说，真正需要学习的是这条系统链，而不是“多几个 CSV”。
+
+---
+
+## 2. 设计结论
+
+### 2.1 一句话结论
+
+`webnovel-writer` 的理想态，不应再是：
+
+- `md reference + csv search + skill 手动拼装`
+
+而应重构为：
+
+- `Reasoning Layer + Multi-domain Knowledge Layer + Story System Generator + Persistence Contracts + Skill Runtime`
+
+### 2.2 核心判断
+
+#### 判断 1：CSV 应成为主知识层
+
+`references/csv/` 已经具备良好的条目化方向，理想态中它应升级为：
+
+- 主知识层
+- 主检索层
+- 主规则层
+
+而不是“补充资料”。
+
+#### 判断 2：MD 应降级为方法论层
+
+`references/*.md` 中的方法论、审查规则、AI 味规避、流程规范，仍应保留为 md。
+
+但它们不再直接承担：
+
+- 题材配置中心
+- 故事系统主设定
+- skill 主输入源
+
+#### 判断 3：skill 不应再直接读散乱 reference
+
+`webnovel-init / plan / write / review` 的最佳状态是：
+
+- 不直接拼装多份 reference
+- 不直接决定先查什么表、再查什么 md
+- 只消费统一生成的 story contract
+
+但这里的“只消费合同”，不是说 skill 从此不再按步加载任何 reference，而是指：
+
+- 全局设定、题材调性、毒点红线、系统边界应优先来自 contract
+- 局部写作技法、场景模式、命名规则、排版和审查规范仍可按 step 按需加载
+
+#### 判断 4：原有 data_modules 不是废弃，而是下沉为运行时底盘
+
+现有：
+
+- `state.json`
+- `memory_contract`
+- `index.db / vectors / bm25`
+- `context_manager`
+- `query_router`
+
+都仍然有价值。
+
+但它们的定位应从“主流程拼装器”变为：
+
+- 运行时事实层
+- 检索证据层
+- 写作执行支持层
+
+### 2.3 Contract 与渐进式披露的分工
+
+本 spec 不推翻 `2026-04-09` 中“渐进式披露 + 双轨制 + 按需加载”的哲学，而是重新划分消费边界。
+
+#### 由 contract 优先承接的内容
+
+- 题材推理结果
+- 全局调性与节奏承诺
+- `anti_patterns`
+- `system_constraints`
+- 卷级 / 章级目标
+- override ledger
+
+这些内容的共同特点是：
+
+- 影响全局
+- 需要跨 step 稳定一致
+- 不适合每个 skill 临时再拼一次
+
+但运行时还必须补一条消费边界：
+
+- skill 默认消费的是**最终结算态**
+- 完整 override ledger 默认属于**审计 / debug / dashboard 数据**
+- 写作 prompt 只应拿到“本章相关的 override 摘要”，不应注入全量历史账本
+
+#### 继续由按需 reference 承接的内容
+
+- 写作技法
+- 场景模式
+- 命名规则
+- 对话口吻
+- 排版规范
+- 润色与 anti-ai 修正
+- review schema 与 blocking override 规则
+
+这些内容的共同特点是：
+
+- 强依赖具体 step
+- 触发条件明确
+- 更像“局部执行手册”而不是“全局故事合同”
+
+因此理想态不是“contract 替代所有 reference”，而是：
+
+- contract 接管全局系统信息
+- step-bound reference 保留局部执行知识
+
+---
+
+## 3. 目标与非目标
+
+### 3.1 目标
+
+理想态重构要达成 8 个目标：
+
+1. 建立统一的题材推理层
+2. 建立统一的多域知识仓
+3. 建立统一的故事系统生成器
+4. 建立统一的 anti-pattern 汇总机制
+5. 建立统一的 `Master / Volume / Chapter` 合同结构
+6. 建立统一的持久化目录 `.story-system/`
+7. 让 `skills` 只消费合同，不再直接拼 reference
+8. 让现有 state / index / memory 数据链继续作为运行时事实层
+
+### 3.2 非目标
+
+本 spec 明确不追求以下事情：
+
+1. 不保留旧 CLI 的完全兼容调用方式
+2. 不要求 `reference_search.py` 继续作为一线入口
+3. 不要求 `genre-profiles.md` 继续担任核心配置中心
+4. 不要求每个旧模板都被保留原职责
+5. 不要求为每条知识点编写测试
+
+### 3.3 知识迁移边界
+
+知识迁移必须遵守以下硬规则：
+
+1. `AI味`、去 AI 腔、润色替换规则，不进入 CSV
+2. 这类内容继续保留在独立 md 文件
+3. 知识迁移只允许人工整理和人工录入
+4. 禁止编写“把 md 自动抽成 csv 条目”的迁移脚本
+
+这里的“禁止脚本迁移”，针对的是知识内容迁移，不针对正常的工程脚本开发。
+
+---
+
+## 4. 理想态总架构
+
+### 4.1 总体分层
+
+理想态系统分为五层：
+
+1. `Reasoning Layer`
+2. `Knowledge Layer`
+3. `Contract Layer`
+4. `Persistence Layer`
+5. `Skill Runtime Layer`
+
+### 4.2 分层关系
+
+```text
+用户意图 / 题材诉求
+        ↓
+Reasoning Layer
+        ↓
+Knowledge Layer
+        ↓
+Story System Generator
+        ↓
+Contract Layer
+        ↓
+Persistence Layer
+        ↓
+Skill Runtime Layer
+        ↓
+正文 / 大纲 / 审查 / 状态回写
+```
+
+### 4.3 推荐目录
+
+```text
+${CLAUDE_PLUGIN_ROOT}/
+├── story_system/
+│   ├── data/
+│   │   ├── reasoning/
+│   │   ├── rules/
+│   │   ├── tropes/
+│   │   ├── characters/
+│   │   ├── pacing/
+│   │   └── naming/
+│   ├── engine/
+│   │   ├── search_engine.py
+│   │   ├── reasoning_engine.py
+│   │   ├── aggregator.py
+│   │   ├── anti_pattern_engine.py
+│   │   ├── contract_builder.py
+│   │   ├── renderer.py
+│   │   └── persistence.py
+│   ├── runtime/
+│   │   ├── memory_bridge.py
+│   │   ├── state_bridge.py
+│   │   ├── index_bridge.py
+│   │   └── review_bridge.py
+│   ├── templates/
+│   │   ├── master_setting.md.j2
+│   │   ├── volume_brief.md.j2
+│   │   ├── chapter_brief.md.j2
+│   │   ├── anti_patterns.md.j2
+│   │   └── review_contract.md.j2
+│   └── cli.py
+├── references/
+│   ├── csv/
+│   ├── shared/
+│   ├── outlining/
+│   └── review/
+├── skills/
+└── scripts/
+
+${PROJECT_ROOT}/
+├── .webnovel/
+└── .story-system/
+```
+
+说明：
+
+- 这里采用的是**插件运行时目录模型**，不是当前源码仓库目录模型
+- 当前开发仓库只用于产出插件，不参与运行时 story contract 的落盘路径判定
+- `CLAUDE_PLUGIN_ROOT` 是插件安装目录，负责承载代码、skills、scripts、references
+- `PROJECT_ROOT` 是真实书项目根目录，定义为包含 `.webnovel/state.json` 的目录
+- `.story-system/` 必须落在 `PROJECT_ROOT` 下，而不是 `CLAUDE_PLUGIN_ROOT`
+- `story_system/` 是新的一线中枢
+- 旧 `scripts/reference_search.py` 与 `scripts/data_modules/` 可继续存在，但不再承载主设计中心
+- `engine/` 下的多个文件表示“职责分层目标”，不是 day 1 必须拆成 7 个文件
+
+### 4.4 初始实现颗粒度
+
+理想态需要清晰的职责边界，但不意味着第一版工程实现必须把每个职责拆成独立文件。
+
+推荐做法：
+
+1. phase 1 可先合并为 `search_reasoning.py + contract_runtime.py + persistence.py`
+2. phase 2 再按职责拆成更细模块
+
+也就是说：
+
+- 架构分层要先定清
+- 文件颗粒度可以渐进收敛
+
+---
+
+## 5. Reasoning Layer 设计
+
+### 5.1 职责
+
+`Reasoning Layer` 是整个系统的大脑，负责把模糊的创作意图，转成可执行的系统约束。
+
+它回答的不是：
+
+- “某个技巧怎么写”
+
+而是：
+
+- 这本书本质上是什么题材
+- 核心读者承诺是什么
+- 应该优先交付什么爽点
+- 节奏应该偏快还是偏压抑
+- 哪些毒点绝对不能碰
+- 后续应该优先检索哪些知识域
+
+### 5.2 核心数据表
+
+新增核心路由表：
+
+- 文件名：`题材与调性推理.csv`
+- 中文名：`题材与调性推理`
+
+### 5.3 建议字段
+
+`题材与调性推理.csv` 仍然必须遵守现有 CSV 通用契约。
+
+这里列出的，是**通用列之外的专属列**：
+
+| 字段 | 说明 |
+|------|------|
+| `题材/流派` | 主题材名 |
+| `中文名` | 供人读的标准名 |
+| `题材别名` | 黑话、俗称、平台常用叫法 |
+| `核心调性` | 草根逆袭、极致拉扯、压抑蓄爆、诡异压迫等 |
+| `节奏策略` | 黄金三章、慢热蓄势、持续兑现、节点爆发等 |
+| `主爽点` | 该题材最核心的兑现类型 |
+| `辅助爽点` | 次级交付 |
+| `冲突引擎` | 冲突主要如何生成 |
+| `适配人设` | 推荐的人设框架 |
+| `适配金手指` | 推荐的外挂或设定类型 |
+| `适配桥段` | 高频桥段方向 |
+| `强制禁忌/毒点` | 题材级红线 |
+| `推荐基础检索表` | 生成系统时优先查的基础域 |
+| `推荐动态检索表` | 生成卷/章简报时优先查的动态域 |
+| `默认查询词` | 当用户输入模糊时的扩展查询词 |
+
+### 5.4 题材推理原则
+
+推理顺序应为：
+
+1. 识别主题材
+2. 识别辅题材
+3. 识别核心承诺
+4. 锁定调性
+5. 锁定节奏
+6. 锁定毒点
+7. 生成后续多域检索计划
+
+这里必须允许“主辅题材”结构，而不是只识别单一标签。
+
+### 5.5 多标签推理规则
+
+网文题材经常不是单标签，而是：
+
+- `赛博朋克 + 克苏鲁`
+- `修仙 + 直播`
+- `都市异能 + 恋爱修罗场`
+
+因此 reasoning engine 不应采用简单的 `Top 1` 命中逻辑，而应支持多标签加权融合。
+
+建议规则如下：
+
+1. 先识别 `主题材`
+2. 再识别 `辅题材`
+3. `核心调性` 以主题材为主，辅题材只允许调味，不得反客为主
+4. `强制禁忌/毒点` 采用并集策略
+5. `主爽点` 按主题材排序，`辅助爽点` 允许来自辅题材
+6. `推荐基础检索表 / 推荐动态检索表` 采用加权合并，而不是单条覆盖
+
+简化说法：
+
+- 调性允许主次
+- 毒点必须并集
+- 检索计划必须融合
+
+这条规则必须写进实现，而不能只停留在概念层。
+
+### 5.6 Reasoning Engine 实现边界
+
+reasoning engine 不能走向两个极端：
+
+- 不能试图用纯规则代码“理解一切文学语义”
+- 也不能把题材识别、调性融合、毒点判断全部放给 LLM 黑盒完成
+
+推荐采用 `L0 / L1 / L2` 三层：
+
+1. `L0 Deterministic Router`
+2. `L1 Deterministic Fusion`
+3. `L2 LLM Classifier / Synthesizer`
+
+#### L0：确定性路由
+
+负责：
+
+- alias 归一化
+- 显式标签提取
+- BM25 / 关键词候选召回
+- 置信度初算
+
+这层的职责是把自然语言意图收敛成**候选集合**，而不是直接输出最终文学判断。
+
+#### L1：确定性融合
+
+负责：
+
+- 主辅题材候选加权
+- 毒点并集
+- 基础检索计划融合
+- 生成“可离线运行”的 baseline contract
+
+这层保证：即便没有 LLM，也能对清晰输入产出一个可用但偏保守的 `MASTER`。
+
+#### L2：LLM 分类 / 融合
+
+只有在以下场景才启用：
+
+- 输入低置信
+- 题材混搭明显
+- 调性描述高度模糊
+- 多候选之间差距不足以稳定裁决
+
+LLM 的职责不是自由发挥，而是：
+
+- 在候选集合内做分类或重排
+- 解释为什么某个融合更合理
+- 产出严格结构化 JSON
+
+随后必须经过本地 schema 校验，失败则回退到 L1 baseline。
+
+默认要求：
+
+- 离线可运行
+- 不依赖 LLM 也能生成可用的 `MASTER`
+- LLM 负责语义补洞与模糊融合，不负责绕过规则层直接产生命令式合同
+
+fallback 策略：
+
+1. 若 `L0 + L1` 已得到高置信结果，则不调用 LLM
+2. 若结果低置信，先输出候选题材列表和冲突点
+3. 若启用 LLM 辅助，再让 LLM 仅基于候选集合输出结构化融合建议
+4. 若 LLM 输出未通过校验，则丢弃该结果并回退到确定性 baseline
+
+这样做的目的，是把：
+
+- 成本
+- 延迟
+- 可用性
+- 可解释性
+- 可测试性
+
+同时控制在工程可接受范围内
+
+---
+
+## 6. Knowledge Layer 设计
+
+### 6.1 知识分层
+
+理想态中，知识层应分成三类，而不是全塞在一起：
+
+1. `Reasoning Tables`
+2. `Rule Tables`
+3. `Methodology Docs`
+
+### 6.2 Reasoning Tables
+
+这些表负责“全局推理与路由”：
+
+| 文件名 | 中文名 | 角色 |
+|------|------|------|
+| `题材与调性推理.csv` | 题材与调性推理 | 题材路由与全局调度 |
+
+### 6.3 Rule Tables
+
+这些表负责“结构化规则与条目知识”：
+
+| 文件名 | 中文名 | 角色 |
+|------|------|------|
+| `命名规则.csv` | 命名规则 | 人名、地名、势力、功法等命名规则 |
+| `场景写法.csv` | 场景写法 | 战斗、对话、冲突、桥段场景的写法模式 |
+| `写作技法.csv` | 写作技法 | 技法与误区 |
+| `桥段套路.csv` | 桥段套路 | 套路、铺垫、反转、变种 |
+| `人设与关系.csv` | 人设与关系 | 人设原型、关系互动、禁区 |
+| `爽点与节奏.csv` | 爽点与节奏 | 节奏阶段、情绪调度、崩盘误区 |
+| `金手指与设定.csv` | 金手指与设定 | 金手指、世界规则、限制、代价 |
+
+建议后续补两张表：
+
+| 文件名 | 中文名 | 角色 |
+|------|------|------|
+| `冲突设计.csv` | 冲突设计 | 冲突触发源、升级链、回收方式 |
+| `反派机制.csv` | 反派机制 | 反派逻辑、层级、失败方式、禁区 |
+
+### 6.4 Methodology Docs
+
+这些内容继续保留 md，不进 csv：
+
+- `review-schema.md`
+- `reading-power-taxonomy.md`
+- `shared/core-constraints.md`
+- `webnovel-write/references/anti-ai-guide.md`
+- `webnovel-write/references/polish-guide.md`
+- `webnovel-write/references/style-adapter.md`
+
+原因很简单：
+
+- 它们是流程与方法论
+- 不是检索条目
+- 强行塞入 csv 会劣化表达
+
+---
+
+## 7. Contract Layer 设计
+
+### 7.1 核心思想
+
+skill 不应再直接消费：
+
+- 散乱 CSV 结果
+- 多份 md 引用
+- 零散模板
+
+skill 只应消费标准合同。
+
+### 7.2 合同类型
+
+理想态至少有五类合同：
+
+1. `MASTER_SETTING`
+2. `VOLUME_BRIEF`
+3. `CHAPTER_BRIEF`
+4. `ANTI_PATTERNS`
+5. `REVIEW_CONTRACT`
+
+### 7.3 每类合同的职责
+
+#### MASTER_SETTING
+
+负责全书级稳定设定：
+
+- 题材与调性
+- 主角与核心角色基线
+- 世界规则与金手指边界
+- 全局节奏策略
+- 全局毒点
+
+#### VOLUME_BRIEF
+
+负责卷级目标：
+
+- 本卷核心冲突
+- 本卷兑现目标
+- 本卷反派层级
+- 本卷关键桥段
+- 本卷节奏波形
+
+#### CHAPTER_BRIEF
+
+负责本章执行要求：
+
+- 本章目标
+- 本章桥段
+- 本章场景策略
+- 本章情绪预期
+- 本章禁区
+
+#### ANTI_PATTERNS
+
+负责把所有题材级、桥段级、角色级、节奏级毒点聚合成显式红线。
+
+#### REVIEW_CONTRACT
+
+负责告诉审查环节：
+
+- 本章/本卷必须检查什么
+- 哪些红线最优先
+- 哪些风险点是题材特定风险
+
+### 7.4 双产物要求与单一真理源
+
+每份合同可以同时存在两种产物：
+
+1. Markdown
+2. JSON
+
+但必须明确：
+
+- `JSON` 是唯一真理源
+- `Markdown` 只是从 `JSON` 渲染出的只读产物
+
+原因：
+
+- Markdown 给人看
+- JSON 给程序和 skill 稳定消费
+- 一旦允许人手改 Markdown，就会出现双重真理源
+
+因此必须执行以下硬规则：
+
+1. 所有持久化更新先改 JSON，再渲染 Markdown
+2. Markdown 顶部必须显式标注 `GENERATED FILE / DO NOT EDIT`
+3. skill、runtime、dashboard、测试一律只消费 JSON，不消费 Markdown 作为真值
+4. 人工修订只能通过 CLI / Dashboard / 显式 JSON 编辑入口完成，不支持“手改 Markdown 自动回写”
+
+如果 Markdown 被人工修改：
+
+- 视为非受支持操作
+- 下次渲染时允许被覆盖
+
+### 7.4.1 与 Retrofit Spec 的 Markdown 迁移裁决
+
+这里需要与 `retrofit spec` 的 marker 方案明确裁决，避免两份 spec 在 phase 1/2 打架。
+
+#### phase 1
+
+- 服从 `retrofit spec`
+- 若 Markdown 中存在 `<!-- STORY-SYSTEM:BEGIN -->` / `END` 自动生成区块，则脚本只更新 marker 内内容
+- marker 外的人工备注区可暂时保留
+
+#### phase 2 及以后
+
+- 服从本 spec
+- Markdown 退化为从 JSON 全量重建的只读渲染产物
+- phase 1 的 marker 兼容逻辑可以废弃
+
+无论 phase 1 还是 phase 2，都必须坚持：
+
+- `JSON` 是唯一真理源
+- marker 外人工备注不构成合同真值
+- skill/runtime/test 一律不以 Markdown 作为真值输入
+
+### 7.5 JSON 合同校验
+
+既然 JSON 要作为 skill 的稳定输入，就不能只“尽量输出正确”，而必须做结构校验。
+
+建议实现：
+
+1. 为 `MASTER_SETTING / VOLUME_BRIEF / CHAPTER_BRIEF / REVIEW_CONTRACT` 定义显式 schema
+2. 使用 `Pydantic` 或等价 schema 校验机制
+3. 在生成 JSON 后先做本地校验，再落盘
+4. 校验失败时不得生成“看起来成功、实际结构不稳定”的伪合同
+
+最低要求：
+
+- `anti_patterns` 必须始终是列表
+- `overrides` 必须始终是结构化对象
+- `locked / append_only / override_allowed` 必须可机读
+- `lock_policy` 必须始终可机读
+- 缺省值要稳定，不能时而为空字符串、时而为空数组
+
+这不是“测试增强”，而是合同系统的基础完整性约束。
+
+### 7.5.1 Schema Version 与兼容策略
+
+所有合同 JSON 都必须带版本元数据，最低要求：
+
+- `schema_version`
+- `contract_type`
+- `generator_version`
+
+推荐规则：
+
+1. `schema_version` 使用显式字符串，例如 `story-system/v1`
+2. 读取方必须先校验 `schema_version`，再决定：
+   - 直接读取
+   - 运行显式 migrator
+   - 报错并要求人工升级
+3. 禁止在 schema 不兼容时静默忽略字段
+4. phase 1 由 `StorySystemDict` 过渡来的合同，也必须显式写入版本号，而不是默认“无版本”
+
+否则 phase 1 生成的旧合同进入 phase 2 后，会在新代码下出现“静默丢字段”或“校验失败但原因不明”的问题。
+
+### 7.6 合同 JSON 基线
+
+本 spec 不从零重新发明 JSON contract，而采用以下策略：
+
+1. phase 1 复用 `retrofit spec` 中的 `StorySystemDict` 作为基础结构
+2. phase 2 在其外层扩展出 `MASTER / VOLUME / CHAPTER / REVIEW / ANTI_PATTERNS` 五类合同
+
+最小字段要求如下。
+
+#### `MASTER_SETTING.json`
+
+至少包含：
+
+- `meta`
+- `genre_reasoning`
+- `core_rules`
+- `anti_patterns`
+- `system_constraints`
+- `contracts`
+- `overrides`
+
+#### `VOLUME_BRIEF.json`
+
+至少包含：
+
+- `meta`
+- `volume_goal`
+- `selected_tropes`
+- `selected_pacing`
+- `selected_scenes`
+- `anti_patterns`
+- `system_constraints`
+- `overrides`
+
+#### `CHAPTER_BRIEF.json`
+
+至少包含：
+
+- `meta`
+- `chapter_goal`
+- `scene_strategy`
+- `hook_strategy`
+- `must_cover`
+- `anti_patterns`
+- `system_constraints`
+- `overrides`
+
+这里的 `system_constraints` 与 `anti_patterns` 必须区分：
+
+- `anti_patterns`：明确禁止项
+- `system_constraints`：能力边界、世界规则、数值限制
+
+一个实用判据是：
+
+- 违反后会直接让读者觉得“有毒、崩盘、降智”的，归入 `anti_patterns`
+- 违反后会先造成设定自洽性破裂、逻辑漏洞或数值失衡的，归入 `system_constraints`
+
+例如：
+
+- `金手指每天只能用三次` 属于 `system_constraints`
+- `打脸桥段必须靠反派强行降智才能成立` 属于 `anti_patterns`
+
+#### `REVIEW_CONTRACT.json`
+
+至少包含：
+
+- `meta`
+- `must_check`
+- `blocking_rules`
+- `genre_specific_risks`
+- `anti_patterns`
+- `system_constraints`
+- `review_thresholds`
+- `overrides`
+
+其中：
+
+- `must_check`：本章/本卷必须重点检查的审查项
+- `blocking_rules`：命中后直接阻断通过的规则
+- `genre_specific_risks`：题材特定高风险点
+- `review_thresholds`：各维度最低通过阈值或 blocking 条件
+
+### 7.6.1 `StorySystemDict` 到合同家族的映射
+
+为避免 phase 1 的 `StorySystemDict` 到 phase 2 的合同家族迁移时产生歧义，这里给出最小映射。
+
+| `StorySystemDict` 字段 | phase 2 目标位置 | 说明 |
+|------|------|------|
+| `meta` | `MASTER_SETTING.meta` | 生成来源、查询词、时间戳等元信息 |
+| `route` | `MASTER_SETTING.genre_reasoning` | 题材路由、候选题材、命中依据 |
+| `master_constraints` | `MASTER_SETTING.core_rules` + `MASTER_SETTING.system_constraints` | 题材调性、世界边界、硬约束分拆进入核心规则与系统边界 |
+| `base_context` | `MASTER_SETTING.contracts.base_context_seed` | 基础表命中结果作为全书级种子上下文 |
+| `dynamic_context` | `VOLUME_BRIEF.selected_*` + `CHAPTER_BRIEF.scene_strategy / hook_strategy / must_cover` | phase 2 由“动态上下文”拆成卷级选择与章级执行要求 |
+| `anti_patterns` | 各级合同中的 `anti_patterns` + 派生 `anti_patterns.json` | 条目级与题材级毒点进入各合同，再生成运行时聚合视图 |
+| `override_policy` | `MASTER_SETTING.contracts.override_policy` | 字段覆盖规则与默认 policy |
+| `source_trace` | 各合同 `meta.source_trace` 或审计区 | 调试、审计与追溯信息 |
+
+这张映射表的作用不是冻结最终字段名，而是明确：
+
+- phase 1 的扁平聚合结果不会直接消失
+- 它会被拆分并沉淀到更细粒度的合同家族中
+- 实施时不得靠“语义猜测”去决定字段归属
+
+---
+
+## 8. Persistence Layer 设计
+
+### 8.1 目录规范
+
+在真实书项目根目录 `PROJECT_ROOT` 下建立：
+
+```text
+PROJECT_ROOT/
+├── .webnovel/
+└── .story-system/
+    ├── MASTER_SETTING.md
+    ├── MASTER_SETTING.json
+    ├── anti_patterns.md
+    ├── anti_patterns.json
+    ├── volumes/
+    │   ├── volume_001.md
+    │   ├── volume_001.json
+    │   └── ...
+    └── chapters/
+        ├── chapter_001.md
+        ├── chapter_001.json
+        └── ...
+```
+
+补充规则：
+
+- `*.json` 是合同真源
+- `*.md` 是渲染产物
+- 渲染器必须支持“从 JSON 全量重建 Markdown”
+- skills/agents 默认从 `WORKSPACE_ROOT` 出发，但必须先统一解析到真实 `PROJECT_ROOT` 再读写 `.story-system/`
+
+### 8.1.1 `ANTI_PATTERNS` 独立文件与各级合同的关系
+
+这里必须避免双真理源：
+
+1. `MASTER_SETTING / VOLUME_BRIEF / CHAPTER_BRIEF` 中各自的 `anti_patterns` 字段，才是**分层真源**
+2. `.story-system/` 根目录下的 `anti_patterns.json` 是**派生聚合视图**
+3. `anti_patterns.md` 只从 `anti_patterns.json` 渲染
+
+也就是说：
+
+- `MASTER_SETTING.json.anti_patterns` 负责全书级红线
+- `VOLUME_BRIEF.json.anti_patterns` 负责卷级补充红线
+- `CHAPTER_BRIEF.json.anti_patterns` 负责章级补充红线
+- `anti_patterns.json` 负责把“当前可见层级”的红线汇总成运行时/审计友好的扁平视图
+
+若出现冲突，以各级合同中的分层字段为准，`anti_patterns.json` 必须重算，不得反向成为真源。
+
+### 8.1.2 命名与版本控制约束
+
+文件命名规范：
+
+- 卷文件统一使用零填充编号：`volume_001.json`
+- 章文件统一使用零填充编号：`chapter_001.json`
+- 人类可读标题放在 `meta.title` 中，而不是写进文件名
+
+版本控制建议：
+
+- `.story-system/*.json` 与其对应的主 Markdown 渲染文件应默认纳入 git 追踪
+- 它们属于项目级合同，不是临时缓存
+- 仅调试 diff、health report、临时审计快照等可放入 `.gitignore`
+
+### 8.2 覆盖规则
+
+覆盖优先级固定为：
+
+1. `chapter_xxx`
+2. `volume_xxx`
+3. `MASTER_SETTING`
+
+但覆盖不是“静默替换”，而必须显式记录覆盖行为。
+
+### 8.2.1 三层覆盖矩阵
+
+`Master / Volume / Chapter` 的覆盖关系必须按字段类型区分，而不是统一“下层覆盖上层”。
+
+| 字段类型 | Master -> Volume | Volume -> Chapter | 说明 |
+|------|------|------|------|
+| `locked` | 默认不可直接覆盖 | 默认不可直接覆盖 | 是否允许通过 `amend-*` 突破，取决于 `lock_policy` |
+| `append_only` | 可追加，不可删除 | 可追加，不可删除 | 最终值为并集 |
+| `override_allowed` | 可覆盖，需记录 reason | 可覆盖，需记录 reason | 最终值取最近一层 |
+
+补充规则：
+
+1. `Master.locked` 对 `Volume / Chapter` 都生效
+2. `Volume.locked` 只约束本卷下属 `Chapter`
+3. `Chapter` 不能直接“解锁”上层已锁定字段
+4. `append_only` 字段的最终值始终是 `Master + Volume + Chapter` 的合并结果
+5. `override_allowed` 字段的最终值采用最近一层，但必须保留 override ledger
+
+### 8.2.1.1 `lock_policy`
+
+为避免把小说创作中的“合理反转”也物理锁死，所有 `locked` 字段都必须额外带一个 `lock_policy`：
+
+1. `system_locked`
+2. `user_locked`
+3. `story_locked`
+
+含义如下：
+
+- `system_locked`：系统 schema、基础运行约束、不可被下游合同修改
+- `user_locked`：用户明确给出的硬约束，运行时不得自动修改，只能由用户显式确认后上游修订
+- `story_locked`：当前故事系统中的核心稳定设定，不能被 `Volume / Chapter` 直接覆盖，但允许通过 `amend-master / amend-volume proposal + 人工确认` 上游改写
+
+也就是说：
+
+- `locked` 仍然存在
+- 但不是所有 `locked` 都是同一强度
+- 真正允许剧情反转的出口，是“先提修订建议，再改上层合同”，而不是让 `Chapter` 直接冲破锁
+
+### 8.2.2 冲突覆盖记录
+
+当 `chapter_xxx` 或 `volume_xxx` 与上层合同发生冲突时，生成器必须产出显式 override 标记，而不是只保留最终值。
+
+Markdown 层建议使用类似格式：
+
+- `本章节奏：[Override 自 MASTER: 慢热蓄势 -> 极限爆发]`
+- `本章桥段：[Override 自 VOLUME: 试探对峙 -> 当场打脸]`
+
+JSON 层至少要记录：
+
+- `field`
+- `base_value`
+- `override_value`
+- `source_level`
+- `reason`
+
+目的不是给人审美，而是让模型和后续脚本明确知道：
+
+- 这里发生了状态切换
+- 这是受控覆盖，不是随机漂移
+
+### 8.2.3 Override Ledger 消费边界
+
+override ledger 必须保留，但默认不应整包注入写作 prompt。
+
+推荐分成两种消费模式：
+
+1. `audit/debug mode`
+2. `runtime prompt mode`
+
+#### audit/debug mode
+
+允许读取完整账本，用于：
+
+- dashboard 审计
+- 合同 diff
+- 健康检查
+- 问题排查
+
+#### runtime prompt mode
+
+只应暴露：
+
+- 当前字段的最终生效值
+- 本章 / 本卷直接相关的 override 摘要
+- 必要的覆盖原因短句
+
+默认禁止：
+
+- 把历史全量 override ledger 直接塞进 `webnovel-write` prompt
+- 把几十章前的覆盖记录反复注入当前章节上下文
+
+原因很简单：
+
+- 这会浪费 token
+- 会制造噪音
+- 会让模型更关注“历史解释”而不是“当前执行约束”
+
+### 8.2.4 覆盖原因字段
+
+所有 `override_allowed` 字段在发生覆盖时，都应尽量附带 `reason`。
+
+推荐原因标签：
+
+- `ARC_ESCALATION`
+- `CHAPTER_PAYOFF`
+- `TWIST_REQUIREMENT`
+- `POV_SWITCH`
+- `CONFLICT_INTENSIFICATION`
+
+这些标签是推荐值，不是封闭枚举。
+
+允许格式：
+
+- `reason_tag + free_text`
+- 纯 `free_text`
+
+没有原因的覆盖，只能视为低可信覆盖。
+
+### 8.3 字段类型
+
+字段必须被标记为三类之一：
+
+1. `locked`
+2. `append_only`
+3. `override_allowed`
+
+示例：
+
+- `世界规则`：`locked`
+- `全局毒点`：`append_only`
+- `本章桥段策略`：`override_allowed`
+
+没有这个字段级规则，后续局部覆盖会失控。
+
+补充规则：
+
+- 若字段为 `locked`，则必须同时声明 `lock_policy`
+- `lock_policy` 未声明时，默认按 `story_locked` 处理，不允许静默放宽
+
+对于 `append_only` 字段，还应补一条规则：
+
+- 允许新增
+- 不允许删除既有上层约束
+
+尤其是：
+
+- `anti_patterns`
+- `世界规则限制`
+- `金手指边界`
+
+这些字段一旦下层能删除上层内容，合同体系就会失去刚性。
+
+此外必须明确 phase 1 的去重策略：
+
+1. `append_only` 默认**不做语义级自动合并**
+2. 对字符串列表，去重键为规范化后的文本：
+   - 去首尾空白
+   - 折叠连续空白
+   - 统一常见全角/半角分隔差异
+3. 对结构化对象，去重键必须显式定义；若未定义，则保留并标记为待审计
+4. 对 `anti_patterns`：
+   - 文本完全一致时去重
+   - 文本不同但语义相近时，phase 1 默认**同时保留**
+   - 若上层和下层只是数值阈值不同（如 300 字 vs 200 字），不得静默删除更严格版本
+
+也就是说，phase 1 的策略是：
+
+- 宁可保留重叠项
+- 不可静默弱化上层红线
+- 更激进的语义去重留到后续显式规则或人工审计
+
+### 8.4 持久化入口
+
+对 skill / agent / 测试体系可见的**稳定入口**，必须挂到现有统一 CLI `webnovel.py` 下，而不是在主链里直接引入第二套平行入口。
+
+理想态 CLI 应支持：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" story-system generate-master --genre "修仙退婚流"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" story-system generate-volume --title "拍卖会卷"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" story-system generate-chapter --query "拍卖会打脸"
+```
+
+如果保留 `story_system/cli.py`，它也只能作为：
+
+- 开发期本地调试入口
+- 内部封装入口
+
+而不应成为 skill/prompt 直接依赖的外部命令。
+
+原因：
+
+- 当前项目已有统一 CLI、project_root 解析、workspace pointer、registry、prompt 完整性校验
+- 若 story system 另起一套外部 CLI，skills、tests、dashboard、文档会立刻分叉
+- 因此对外只保留 `webnovel.py story-system ...` 一条稳定入口
+
+参数设计补充规则：
+
+- 优先使用命名参数，而不是依赖带空格的位置参数
+- 这样可以降低 PowerShell / Bash / zsh 下的转义差异
+- 对 skill 暴露的示例命令也应遵守这个约束
+
+此外必须预留显式合同修订入口：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" story-system amend-master --event "主角获得第二核心金手指"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" story-system amend-volume --volume 2 --event "阵营关系反转"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" story-system refresh-chapter --chapter 15
+```
+
+这类命令的职责不是“随便重算”，而是：
+
+1. 读取当前合同
+2. 读取运行时重大事件
+3. 只在允许变更的字段上做受控修订
+4. 记录修订原因与修订时间
+
+### 8.4.1 幂等性与覆盖策略
+
+合同生成与修订命令必须遵守幂等性规则。
+
+#### `generate-*`
+
+1. 若目标合同不存在：创建
+2. 若目标合同已存在且输入指纹相同：直接返回现有合同，不重复覆盖
+3. 若目标合同已存在且输入指纹不同：默认拒绝静默覆盖，并提示使用：
+   - `amend-*`
+   - 或显式 `--force-rebuild`
+
+也就是说：
+
+- `generate-master` 不是“无限次覆盖”
+- 它是“首次生成 + 相同输入幂等返回”
+
+#### `amend-*`
+
+- 是合同的**语义修订入口**
+- 用于在已有合同基础上追加或修改受控字段
+- 不应伪装成重新生成
+
+#### `--force-rebuild`
+
+- 属于显式破坏性再生成
+- 必须由调用方主动声明
+- 执行前应先备份旧 JSON 或写入历史快照
+
+### 8.4.2 phase 1 并发约束
+
+phase 1 不应假定 `.story-system/*.json` 已具备复杂的多写者并发合并能力。
+
+因此最低要求是：
+
+1. `generate-* / amend-* / refresh-*` 对同一目标文件必须串行执行
+2. 实现上应使用文件锁或等价互斥机制
+3. 若目标已被其他进程持有写锁，应返回显式 `BUSY / RETRY` 错误，而不是继续写入
+4. 真正的多写者合并策略留到 day 2+ 单独设计
+
+---
+
+## 9. Skill Runtime Layer 设计
+
+### 9.1 总原则
+
+skill 只负责执行，不负责系统拼装。
+
+### 9.2 `webnovel-init`
+
+职责应收敛为：
+
+1. 理解开书意图
+2. 调用 `generate-master`
+3. 先落 `.story-system/MASTER_SETTING.json`
+4. 再渲染 `.story-system/MASTER_SETTING.md`
+5. 最后把结果写入设定集骨架
+
+### 9.3 `webnovel-plan`
+
+职责应收敛为：
+
+1. 读取 `MASTER_SETTING`
+2. 调用 `generate-volume`
+3. 调用 `generate-chapter`
+4. 产出卷纲、章纲、时间线
+
+如果规划阶段发现以下事件，允许提出 `amend-master / amend-volume`：
+
+- 新核心阵营形成
+- 世界规则新增硬限制
+- 金手指边界发生明确扩展
+- 题材承诺发生结构性偏移
+
+默认流程应为：
+
+1. plan skill 识别到“可能需要修订”
+2. 调用 `contract-auditor / diff analyzer` 生成结构化修订建议
+3. 输出人类可读的修订摘要与受影响字段
+4. 由用户确认后再执行 `amend-master / amend-volume`
+
+除非系统明确配置了自动修订策略，否则不应由 plan skill 自行改写 `MASTER`
+
+它不应该再自己决定：
+
+- 先读哪些题材 md
+- 再查哪些 csv
+- 再拼哪些规则
+
+这些应该由 story system 统一处理。
+
+### 9.4 `webnovel-write`
+
+职责应收敛为：
+
+1. 读取 `chapter brief`
+2. 若不存在则回退 `volume brief`
+3. 再回退 `master`
+4. 读取该层级最终结算后的有效字段
+5. 只注入本章直接相关的 override 摘要
+6. 再结合 runtime memory/state/context 写正文
+
+写作阶段默认不允许直接修改 `MASTER_SETTING`。
+
+只有在检测到“重大结构事件”时，才允许通过显式 hook 进入：
+
+- `amend-master`
+- `amend-volume`
+
+重大结构事件示例：
+
+- 主角新增长期保留的核心能力
+- 世界观新增不可逆规则
+- 核心阵营关系永久翻转
+- 主线承诺发生升级而非临时偏移
+
+也就是说：
+
+- 运行时事实可以推动合同修订
+- 但必须通过显式修订入口
+- 不能让 `MASTER` 因章节波动而持续漂移
+
+推荐增加一个独立钩子：
+
+- `contract-auditor`
+
+它的职责不是改合同，而是：
+
+1. 比较当前运行时事实与上层合同
+2. 判断是“临时章节偏移”还是“应升级为合同修订”
+3. 生成 `amend proposal`
+4. 等待用户确认
+
+### 9.5 `webnovel-review`
+
+职责应收敛为：
+
+1. 读取 `review contract`
+2. 读取 `anti_patterns`
+3. 按合同做结构化审查
+4. 将结果回写 review/index/state
+
+---
+
+## 10. 原有数据链的承接方案
+
+这是本 spec 最关键的部分之一：不是抛弃旧数据链，而是重新定位。
+
+### 10.1 `references/csv/`
+
+新定位：
+
+- 主知识层
+- 主规则层
+- 主检索层
+
+### 10.2 `references/*.md`
+
+新定位：
+
+- 方法论层
+- 流程规范层
+- 审查规则层
+- 在 CSV 覆盖度不足的阶段，仍可作为过渡期活跃知识源
+
+### 10.3 `templates/genres/*.md`
+
+新定位：
+
+- 降级为“样例模板层”
+- 可作为人工参考和初始化草稿
+- 在 route table 覆盖度不足前，仍可作为补充题材源
+
+### 10.4 `templates/output/*.md`
+
+新定位：
+
+- 升级为 story-system 的渲染模板来源
+
+### 10.5 `scripts/reference_search.py`
+
+新定位：
+
+- 底层 primitive
+- 可复用的 CSV 搜索内核
+- 不再作为 skill 主入口
+
+### 10.6 `scripts/data_modules/context_manager.py`
+
+新定位：
+
+- 运行时上下文装配器
+- 消费 `story-system contract + memory/state/index`
+- 不再负责“全局故事系统生成”
+
+演进路径应为：
+
+1. phase 1 保留 `context_manager`，不做平地重写
+2. phase 1 让它优先消费 contract，同时继续聚合 state / summaries / reader_signal / plot_structure
+3. phase 2 把其中与“全局系统生成”重叠的逻辑逐步抽到 `story_system`
+4. phase 3 再把 `context_manager` 收敛为纯运行时上下文装配器
+
+也就是说：
+
+- 不是直接废弃
+- 而是先接入，再抽离，再收敛
+
+### 10.6.1 Contract 注入口
+
+Day 2 以后，`context_manager` 必须有明确的 contract 注入口，而不是只在文档层说“合同优先”。
+
+最小要求：
+
+1. `_build_pack()` 读取 `.story-system/` 中当前章可见的合同
+2. pack 中新增显式 section，例如 `story_contract`
+3. `story_contract` 的优先级高于旧的 `genre_profile` 摘要和临时全局拼装结果
+4. 若合同缺失，再回退到现有 `genre_profile + global + reader_signal` 组装链
+
+推荐顺序：
+
+1. `chapter contract`
+2. `volume contract`
+3. `master contract`
+4. 现有 `genre_profile / global / references`
+
+换句话说，contract-first 必须落成真实的 pack 组装顺序，而不是停留在 skill 文本。
+
+### 10.6.2 `genre_aliases.py` / `genre_profile_builder.py` / `genre-profiles.md`
+
+这些模块和文档不是“旧包袱”，而是 route table 建设前的重要种子源。
+
+新定位：
+
+- `genre_aliases.py`：继续作为题材归一化字典的现役来源
+- `genre_profile_builder.py`：继续作为复合题材 hints 的现役来源
+- `genre-profiles.md`：在 phase 1 / phase 2 期间，继续作为结构化题材参考源
+
+它们的退出方式不应是“一刀切降级”，而应是：
+
+1. 先把其中稳定字段人工迁入 `题材与调性推理.csv`
+2. 再让 `story_system` 优先读 CSV、缺省回退 md
+3. 只有在 CSV 覆盖度达到阈值后，`genre-profiles.md` 才从主源降级为参考源
+
+### 10.6.3 过渡期题材真源优先级
+
+在 phase 1 / phase 2 期间，题材相关信息不能出现“双真源并列”。
+
+优先级必须固定为：
+
+1. `.story-system` 中的 contract
+2. `题材与调性推理.csv`
+3. `genre-profiles.md`
+4. `templates/genres/*.md`
+
+约束：
+
+- 一旦 contract 已存在，`context_manager` 不得再独立输出与 contract 冲突的题材结论
+- `genre-profiles.md` 在过渡期只能作为回退源或补充说明源
+- `templates/genres/*.md` 在过渡期只能作为样例/补充题材源
+
+否则就会出现：
+
+- contract 说 A
+- context pack 仍在塞 B
+- skill 最终又混用了 C
+
+这会直接破坏 contract-first 目标
+
+### 10.7 `state.json`
+
+新定位：
+
+- 写作过程状态机
+- 角色当前状态
+- 章节推进状态
+
+它不是故事总设定中心。
+
+### 10.8 `index.db / vectors / bm25`
+
+新定位：
+
+- 运行期检索证据层
+- 剧情事实回溯层
+- 不是规则知识层
+
+### 10.9 `memory_contract / orchestrator / summaries`
+
+新定位：
+
+- 长期记忆层
+- 已发生事实层
+- 伏笔与回收跟踪层
+
+这一层与 CSV 的关系应为：
+
+- `CSV` 给规则
+- `memory` 给事实
+- `story_system` 负责把规则和事实一起装进合同
+
+### 10.9.1 Memory 最低可用标准
+
+理想态合同系统不能假设 memory 所有子模块都已经工业化完成。
+
+phase 1 的最低事实输入标准应为：
+
+1. `state.json`
+2. 最近章节摘要
+3. `index.db` 中可直接读取的实体、关系、状态变化
+
+`MemoryOrchestrator` 可作为增强项，但不是 phase 1 的硬依赖。
+
+如果 memory 子系统某些组件不可用，合同系统的降级策略应为：
+
+- 继续生成规则合同
+- 对事实合同降级为“state + summaries + index facts”
+- 不因 memory 半成品状态阻断 `generate-master / generate-volume`
+
+### 10.10 迁移阶段划分
+
+这部分虽然是理想态 spec，也需要给出最基本的迁移判断标准。
+
+#### Day 1 变更
+
+- 新增 `题材与调性推理.csv`
+- 新增最小 `generate-master`
+- 保留现有 `reference_search.py`
+- 保留现有 `context_manager`
+- 保留 `genre-profiles.md` 作为活跃题材源
+- skill 继续按 `2026-04-09` 的 L0/L1/L2 策略运行
+- `story-system` 先以内核模块存在，不强制对 skill 暴露
+- 若提供 CLI，仅先以 `webnovel.py story-system ...` 形式接入统一入口
+
+#### Day 2 变更
+
+- 引入 `Volume` 层合同
+- skill 改为“合同优先 + 局部 reference 按需加载”
+- `genre-profiles.md` 仍可作为回退源，不应提前降级
+- `context_manager` 正式注入 `story_contract`
+- dashboard / preflight / health / backup 开始识别 `.story-system`
+
+#### Day 3 及以后
+
+- 在满足知识密度阈值后，`templates/genres/*.md` 逐步退出主链
+- `reference_search.py` 只作为底层 primitive
+- `story_system` 成为技能层的唯一系统入口
+
+### 10.10.1 知识密度切换阈值
+
+在以下条件满足前，不应把 `genre-profiles.md` 和 `templates/genres/*.md` 提前降级：
+
+1. `题材与调性推理.csv` 已覆盖当前系统支持的主流主题材
+2. `genre_aliases.py` 中的高频别名能在 route table 中找到稳定归一化目标
+3. init / plan / write 的代表性题材输入，经人工抽样验证后，大部分可以直接由 `CSV + contract` 生成可用结果
+4. 对当前活跃题材家族，至少已有一轮真实项目验证，而不是只靠静态录入
+
+简单说：
+
+- 不是 CSV 一出现就替换 md
+- 而是 CSV 达到“可稳定承接主链”的知识密度后，才逐步切换
+
+### 10.10.2 Contract 接管边界
+
+Day 2 以后，contract 应优先接管：
+
+- 题材调性
+- 毒点红线
+- 全局系统边界
+- 卷级 / 章级执行目标
+
+继续由 step-bound reference 保留：
+
+- 局部写作技法
+- 局部场景模式
+- 命名与语汇
+- 润色、排版、anti-ai、review schema
+
+运行时还必须补一条：
+
+- `context_manager` 和 `webnovel-write` 默认读取**最终结算态合同**
+- 完整 override ledger 只在 debug / dashboard / health report 中默认展开
+
+### 10.11 `scripts/data_modules/config.py`
+
+当前 `DataModulesConfig` 已经是项目级事实上的统一配置入口，覆盖：
+
+- 路径
+- 检索参数
+- 上下文预算
+- memory / index / review 相关调优
+
+理想态 `story_system` 不应再平行发明第二套完全独立的配置树。
+
+推荐策略：
+
+1. phase 1 直接复用 `DataModulesConfig`
+2. 新增配置统一采用 `story_system_*` 命名空间
+3. 若后续单独拆出 `StorySystemConfig`，也应只是 `DataModulesConfig` 的薄包装或子视图，而不是完全分家
+
+必须避免的反模式：
+
+- 一套配置给 runtime 用
+- 另一套配置给 story system 用
+- 两边字段重名但语义不同
+
+那样会让 contract、context、memory 三条链路重新分叉。
+
+### 10.12 `.story-system` 的运维接入
+
+既然 `.story-system` 被定义为新的持久化真源，它就不能处于现有运维链路的盲区。
+
+至少需要接入以下四类系统：
+
+#### preflight
+
+在 Day 2 以后，`preflight` 至少应增加：
+
+- `.story-system/MASTER_SETTING.md` 是否存在
+- `.story-system/MASTER_SETTING.json` 是否存在
+- JSON 合同是否可读
+
+#### dashboard / watcher
+
+dashboard 不应只监听 `.webnovel/`。
+
+至少还应关注：
+
+- `.story-system/MASTER_SETTING.*`
+- `.story-system/volumes/*.json`
+- `.story-system/chapters/*.json`
+
+否则合同变更后，前端不会刷新。
+
+#### health / status report
+
+状态报告不应只覆盖 `.webnovel/state.json` 和现有运行时数据。
+
+还应增加：
+
+- 合同存在性检查
+- 合同新鲜度检查
+- override ledger 摘要
+- contract / state 是否明显冲突的健康提醒
+
+#### backup / fallback backup
+
+Git 模式下通常天然覆盖 `.story-system/`，但本地降级备份也必须覆盖它。
+
+最低要求：
+
+- Git 不可用时，fallback backup 不能只备份 `.webnovel/state.json`
+- 至少应同时备份 `.story-system/` 的当前合同文件
+
+否则恢复点会丢失新的系统真源。
+
+---
+
+## 11. 旧模块去留决策
+
+### 11.1 保留并降级
+
+以下模块保留，但降级为下层能力：
+
+- `reference_search.py`
+- `query_router.py`
+- `context_manager.py`
+- `genre_aliases.py`
+- `genre_profile_builder.py`
+
+其中：
+
+- `context_manager.py` 更准确的路径是“保留并演进后收敛”
+- `genre_aliases.py / genre_profile_builder.py` 更准确的路径是“保留并迁移其知识到 route table”
+
+### 11.2 保留并重定位
+
+以下目录保留，但职责改变：
+
+- `references/csv/`
+- `references/shared/`
+- `references/outlining/`
+- `templates/output/`
+
+### 11.3 保留但不再担任主源
+
+以下内容继续保留，但不再是主系统输入：
+
+- `references/genre-profiles.md`
+- `templates/genres/*.md`
+
+### 11.4 应新增的一线模块
+
+理想态应新增：
+
+- `story_system/engine/search_engine.py`
+- `story_system/engine/reasoning_engine.py`
+- `story_system/engine/aggregator.py`
+- `story_system/engine/anti_pattern_engine.py`
+- `story_system/engine/contract_builder.py`
+- `story_system/engine/renderer.py`
+- `story_system/engine/persistence.py`
+
+---
+
+## 12. Anti-Patterns 统一机制
+
+### 12.1 统一原则
+
+理想态不要求所有旧表立即统一字段名，但要求 story system 统一抽取。
+
+### 12.2 建议映射
+
+```python
+ANTI_PATTERN_SOURCE_FIELDS = {
+    "题材与调性推理": ["强制禁忌/毒点"],
+    "人设与关系": ["忌讳写法"],
+    "爽点与节奏": ["常见崩盘误区"],
+    "场景写法": ["反面写法"],
+    "写作技法": ["常见误区"],
+    "桥段套路": ["忌讳写法"],
+}
+```
+
+说明：
+
+- 若 phase 1 按 `retrofit spec` 为 `桥段套路.csv` 新增了 `忌讳写法` 列，phase 2 必须继续读取该列，避免两份 spec 再次分叉
+- `桥段套路.反套路变种` 是变体灵感来源，不默认纳入 anti-pattern 聚合
+- `金手指与设定.数值控制边界` 属于 `system_constraints`，不应直接等同于 anti-pattern
+- 只有显式负面字段，才进入 `ANTI_PATTERN_SOURCE_FIELDS`
+
+### 12.3 输出要求
+
+所有生成合同中，必须存在醒目的：
+
+- `## Anti-Patterns`
+
+该区块是不可逾越的硬红线。
+
+---
+
+## 13. 运行时工作流
+
+### 13.1 开书阶段
+
+输入：
+
+- `写个赛博朋克黑客流`
+
+流程：
+
+1. reasoning engine 锁定主辅题材
+2. 多域聚合基础表
+3. 生成 `MASTER_SETTING`
+4. 写入 `.story-system/`
+5. 初始化设定集
+
+### 13.2 规划阶段
+
+输入：
+
+- `规划第一卷拍卖会逆袭`
+
+流程：
+
+1. 读取 `MASTER`
+2. 聚合桥段、节奏、场景、人设补充
+3. 生成 `VOLUME_BRIEF`
+4. 再拆 `CHAPTER_BRIEF`
+
+### 13.3 写作阶段
+
+输入：
+
+- `写第 15 章`
+
+流程：
+
+1. 读取 `chapter_015`
+2. 若不存在则回退 `volume`
+3. 再回退 `master`
+4. 读取该层级最终结算后的有效字段
+5. 只注入本章直接相关的 override 摘要，而不是完整历史账本
+6. 结合 state / memory / recent context 起草正文
+
+### 13.4 审查阶段
+
+输入：
+
+- `审查第 15 章`
+
+流程：
+
+1. 读取 `review contract`
+2. 读取 `anti_patterns`
+3. 结合 review schema 输出结构化问题
+
+---
+
+## 14. 测试与验证策略
+
+### 14.1 总原则
+
+这个 CSV 数据库不需要做“每条知识点一个测试”的重型方案。
+
+测试只需要覆盖：
+
+1. 合同生成是否成功
+2. 覆盖规则是否正确
+3. 关键字段是否落地
+4. anti-pattern 是否被聚合
+5. runtime 是否能读取合同
+
+### 14.2 不建议的测试
+
+不建议：
+
+1. 为每个 CSV 条目写测试
+2. 为每个知识点写断言
+3. 为内容语义质量写机械化单测
+
+### 14.3 应保留的验证
+
+建议保留：
+
+1. reasoning 命中 smoke test
+2. contract schema test
+3. persistence 覆盖规则 test
+4. CLI 生成最小链路 test
+
+建议额外补两类低成本高价值验证：
+
+5. 多标签推理融合 test
+6. override ledger 生成 test
+7. JSON -> Markdown 渲染一致性 test
+8. `locked + lock_policy` 行为 test
+
+验证重点不是“知识点对不对”，而是：
+
+- 合同结构稳不稳定
+- 多标签毒点是否并集
+- 覆盖是否有显式记录
+- JSON 是否通过 schema 校验
+
+---
+
+## 15. 实施约束
+
+### 15.1 知识迁移约束
+
+知识迁移必须人工完成。
+
+禁止：
+
+- 自动抽取 md 为 csv
+- 自动翻译后批量入库
+- 自动拆句生成知识条目
+
+允许：
+
+- 人工阅读旧资料
+- 人工提炼摘要、关键词、同义词
+- 人工翻译英文 prompt 后录入
+
+### 15.2 工程实现约束
+
+工程层可以写脚本、CLI、渲染器、聚合器、持久化模块。
+
+禁止脚本迁移，不等于禁止工程脚本开发。
+
+---
+
+## 16. 最终架构决策
+
+本 spec 给出的理想态决策如下：
+
+1. `references/csv` 升级为主知识仓
+2. `references/*.md` 保留为方法论层
+3. `templates/genres` 降级为样例模板层
+4. `templates/output` 升级为合同模板层
+5. `reference_search.py` 退出一线，降级为底层 primitive
+6. `genre-profiles.md` 退出核心配置中心，职责转入结构化 reasoning 数据
+7. `skills/webnovel-*` 改为“contract 优先 + 局部 step-bound reference 按需加载”
+8. `state / index / memory` 继续保留，作为运行时事实与证据层
+9. `story_system` 对外只通过统一 CLI `webnovel.py story-system ...` 暴露稳定入口
+10. `.story-system` 必须接入 preflight / dashboard / health / backup，不能成为运维盲区
+11. `.story-system/*.json` 是唯一真理源，`*.md` 只是只读渲染产物
+12. reasoning engine 采用 `L0 / L1 / L2`，由确定性路由保底、LLM 负责低置信语义融合
+13. `locked` 字段必须带 `lock_policy`，剧情级核心设定的变更只能走 `amend proposal + 用户确认`
+
+---
+
+## 17. 结语
+
+这次重构真正要完成的，不是“把参考资料查得更准一点”。
+
+真正的目标是：
+
+- 不再让模型每一章都从散资料临时拼世界
+- 而是先建立一个稳定的故事系统
+- 再让规划、写作、审查都机械地服从这个系统
+
+这就是 `webnovel-writer` 从“离散检索工具”升级为“系统级智能写作底座”的关键跃迁。