Acasă Explorează Ajutor
Înregistrare Autentificare
haiany
/
webnovel-writer
oglindă de https://github.com/lingfengQAQ/webnovel-writer.git
1
0
Bifurcare 0
Fisiere Probleme 0 Wiki
Arbore: a91c28cace
Ramuri Etichete
webnovel-writer
/
docs
/
superpowers
/
specs
/
2026-04-12-story-system-evolution-spec.md

2026-04-12-story-system-evolution-spec.md 27 KB
Istoric Crud

Webnovel Writer Story System 渐进演进 Spec

日期: 2026-04-12 状态: 草案 v1 定位: 基于当前系统真实状态的 superpowers 架构收敛 spec

1. 文档定位

1.1 这份 spec 解决什么问题

current-system-diagnosis.md 已经明确指出：当前系统的主要问题，不是模型能力不够，而是：

  1. 真理源分散
  2. 缺少统一故事合同
  3. 缺少统一章节提交主链
  4. 上下文装配与数据回写都存在结构性缺口

但诊断报告只回答了“哪里有问题”，没有回答“如何从当前系统稳态演进到新系统”。

这份 spec 补的就是中间层：

  • 不重写现有项目历史
  • 不假装当前系统一无所有
  • 不直接把理想态蓝图当实施方案
  • 而是定义一条从现状出发、逐步收束为 Story Contract 主链的演进路线

1.2 与其他文档的关系

这份文档与现有文档的关系如下：

这份 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 总体链路

用户意图 / 书籍题材诉求
        ↓
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

未来可选：

  1. 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/）

建议目录如下：

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 接入点更新任务