Story System 最终收束 Spec

日期: 2026-04-14 状态: 草案 v1 定位: 基于当前代码真实状态，把 Story System 从“半成品并存”收束到“六层主链 + 消费端同步”的最终 spec

1. 文档定位

1.1 这份 spec 解决什么问题

前面的文档已经分别回答了三个问题：

current-system-diagnosis.md
- 当前系统哪里散、哪里重复、哪里有半成品
2026-04-12-story-system-evolution-spec.md
- 六层主链应该长什么样
2026-04-14-context-agent-writing-brief-design.md
- 写前任务书入口怎么收束

这份 spec 解决的是更直接的问题：

在不考虑向后兼容的前提下，如何把现在的代码、CSV、合同、提交链、投影链和消费端，一次性收束到最终可用状态。

1.2 一句话结论

这次收束的目标不是“再补一个模块”，而是：

六层全做
旧散写路径直接删
context_manager 降级为纯 JSON 组装器
CSV_CONFIG + 裁决表 + 合同树 + commit/projection 成为唯一主链
所有消费者只吃合同和投影视图

2. 已确认的关键决策

这轮 brainstorming 已经确认以下决策，不再反复摇摆：

2.1 范围

做 六层全覆盖
不只改代码层
必须同步改 skill / agent / CLI / eval / docs 等消费端

2.2 向后兼容

不考虑向后兼容
旧散写路径、旧直读路径、旧 fallback 路径，能删就删
不保留 deprecated 双路径

2.3 `context_manager`

降级为 纯 JSON payload 组装器
不再负责 text 渲染
不再保留为旧说明书式文本输出服务的 snapshot 逻辑

2.4 `CSV_CONFIG`

放在 reference_search.py 里
形态模仿 ui-ux-pro-max/core.py
每张表显式声明 file / search_cols / output_cols / poison_cols / role

2.5 裁决层

新建独立 裁决规则.csv
key 为题材
它回答的是“命中后怎么裁决、优先谁、注入哪层”，不是“查哪些表”

2.6 `anti-ai-guide.md` 与 `core-constraints.md`

anti-ai-guide.md 保留为 md 真源
- 不拆 CSV
- 不给消费者直读
- 只在需要的步骤被上游吸收后转写
core-constraints.md 不再整篇读取
- 拆成具体约束
- 分步骤落到合同、runtime、review、commit 校验和消费端文案里

2.7 消费端真源

所有消费者只允许直接吃：
- 合同树
- CHAPTER_COMMIT
- 投影视图
不再允许运行时直接读 CSV / md / reference 来补洞

2.8 首批题材范围

这次先做好 7 个题材：

西方奇幻
东方仙侠
科幻末世
都市日常
都市修真
都市高武
历史古代

其余题材不在本轮收束范围内。

2.9 实施顺序

从底层往上推
走串行，不走并行
先把基础收稳，再做消费者同步

3. 总体链路

最终链路固定为：

知识表 / 裁决表
        ↓
CSV_CONFIG + reference_search
        ↓
story_system_engine
        ↓
MASTER / VOLUME / CHAPTER / REVIEW
        ↓
context_manager（只出 JSON）
        ↓
context-agent（按示例写任务书）
        ↓
webnovel-write Step 2（只吃任务书）
        ↓
review / data-agent
        ↓
CHAPTER_COMMIT
        ↓
projection writers
        ↓
state / index / summaries / memory / vector

这里有两个硬边界：

消费端不再运行时直读知识层
写后事实只允许经 CHAPTER_COMMIT -> projection 进入各存储

4. Section 1：`CSV_CONFIG` 注册层

4.1 要做什么

在 reference_search.py 里引入注册式 CSV_CONFIG，替代当前全局硬编码的：

_SEARCH_FIELD_WEIGHTS
_CONTENT_COLUMNS

改成每张表自己定义：

file
search_cols
output_cols
poison_cols
role

4.2 目标形态

CSV_CONFIG = {
    "命名规则": {
        "file": "命名规则.csv",
        "search_cols": ["关键词", "意图与同义词", "核心摘要"],
        "output_cols": ["编号", "命名对象", "核心摘要", "大模型指令", "详细展开"],
        "poison_cols": ["毒点"],
        "role": "base",
    },
    "场景写法": {
        "file": "场景写法.csv",
        "search_cols": ["关键词", "意图与同义词", "核心摘要"],
        "output_cols": ["编号", "模式名称", "核心摘要", "大模型指令", "详细展开"],
        "poison_cols": ["毒点"],
        "role": "base",
    },
    "题材与调性推理": {
        "file": "题材与调性推理.csv",
        "search_cols": ["题材关键词", "别名"],
        "output_cols": ["题材", "默认调性", "推荐基础表", "推荐动态表"],
        "poison_cols": ["毒点"],
        "role": "route",
    },
    "裁决规则": {
        "file": "裁决规则.csv",
        "search_cols": ["题材"],
        "output_cols": [
            "题材",
            "风格优先级",
            "爽点优先级",
            "节奏默认策略",
            "毒点权重",
            "冲突裁决",
            "contract注入层",
            "反模式",
        ],
        "poison_cols": [],
        "role": "reasoning",
    },
}

4.3 改动要求

reference_search.py
- 改为从 CSV_CONFIG 读取 per-table 配置
story_system_engine.py
- 不再内部硬编码表角色
- 改为使用 CSV_CONFIG
新增校验脚本
- 校验 CSV_CONFIG
- 校验 CSV 表头
- 校验 README.md

4.4 验收

同一 CLI 在不同表上确实用的是不同 search_cols
CSV_CONFIG 的每张表字段都能在 CSV 头里找到
校验脚本通过

5. Section 2：CSV 内容修补

5.1 要做什么

对现有表做一次统一审计和修补，让它们能稳定被裁决层和合同层消费。

5.2 重点问题

毒点列命名不统一
路由表字段不足
同义词填充不足
各题材覆盖不均衡

5.3 具体改造

5.3.1 毒点列统一

把以下旧列统一改名为 毒点：

反面写法
忌讳写法
常见误区
常见崩盘误区

5.3.2 路由表补字段

题材与调性推理.csv 至少补齐：

推荐基础表
推荐动态表
默认调性
风格锚点

5.3.3 内容补全规则

所有补全都手工做，不写自动迁移脚本。

最低要求：

每张表至少覆盖这 7 个题材的常见场景
每条 意图与同义词 至少 3 个同义表达
每条 毒点 非空

5.3.4 README 同步

README.md 必须同步更新：

毒点列统一命名
路由表新字段
各表 schema 描述

5.4 验收

所有表的毒点列统一叫 毒点
路由表能返回推荐基础表和动态表
README 与 CSV_CONFIG 对齐

6. Section 3：裁决表

6.1 要做什么

新建 裁决规则.csv，作为独立 Reasoning Layer。

它不负责“查哪些表”，只负责：

多条命中后怎么选
哪类爽点优先
哪类毒点更致命
结果注入合同树哪一层

6.2 与路由表的边界

路由表：回答“查哪些表”
裁决表：回答“查到之后怎么用”

这正是 ui-ux-pro-max 里：

products.csv
ui-reasoning.csv

的对应关系。

6.3 字段

裁决规则.csv 至少包含：

题材
风格优先级
爽点优先级
节奏默认策略
毒点权重
冲突裁决
contract注入层
反模式

6.4 首批覆盖

先覆盖 7 个题材，各 1 行。

6.5 验收

source_trace 能追溯到裁决表
多表命中时，顺序符合 冲突裁决
同题材输出能解释“为什么是这些条目进入合同”

7. Section 4：engine 接入裁决表

7.1 当前问题

现在的 story_system_engine.build() 只有：

路由
检索
直接组装

没有显式裁决层。

7.2 目标流程

改成：

_route()
_collect_tables()
_load_reasoning()
_apply_reasoning()
_rank_anti_patterns()
_assemble_contract()

7.3 新增方法

_load_reasoning(genre)
_apply_reasoning(reasoning, base, dynamic)
_rank_anti_patterns(reasoning, ...)
_assemble_contract(ranked, anti_patterns, reasoning)

7.4 `source_trace`

最终进入合同的内容都要带：

source_table
source_id
reasoning_rule
priority_rank
inject_target

7.5 验收

writing_guidance 顺序符合裁决表
source_trace 都有 reasoning_rule
低优先级冲突条目能被过滤或降级

8. Section 5：`context_manager` 瘦身

8.1 目标

把 context_manager.py 从：

数据组装
文本渲染
snapshot 缓存
checklist/评分说明书

降级为：

纯 JSON payload 组装器

8.2 保留职责

读 contracts
读 runtime sources
组装 genre_profile
组装 writing_guidance
组装 reader_signal
组装 plot_structure
组装 prewrite_validation
返回统一 dict

8.3 删除职责

所有 _render_*
所有旧说明书式 text 输出
为 text 渲染服务的 snapshot 管理
与已拆 builder 重复的内联逻辑

8.4 输出形态

build_context() 只返回：

{
  "meta": {"context_contract_version": "v3", "chapter": 12},
  "story_contract": {},
  "runtime_status": {},
  "latest_commit": {},
  "prewrite_validation": {},
  "plot_structure": {},
  "scene": {},
  "writing_guidance": {},
  "reader_signal": {},
  "genre_profile": {},
  "long_term_memory": {},
  "core": {}
}

8.5 相关要求

snapshot_manager.py
- 若无其他消费方，整文件删除
extract_chapter_context.py
- 不再承担旧审计式文本说明书职责
最终写作任务书
- 由 context-agent 直接根据 JSON payload + 示例生成

8.6 验收

context_manager.py 行数压到 400 行以下
不再有字符串拼接型说明书输出
snapshot 逻辑已删除

9. Section 6：旧散写路径清理

9.1 问题

现在仍有两条写入路径并存：

新链：data-agent -> chapter-commit -> projection
旧链：skill / agent 直接写 state / index / summaries / memory

这必须收束成一条。

9.2 要删的路径

`webnovel-write`

Step 2 直接 state set-chapter-status
Step 4 直接 state set-chapter-status

其他直写入口

skill / agent 中任何 index process-chapter
data-agent 中任何直接写 state/index/memory 的描述

9.3 合法直写保留

只保留：

webnovel-init
webnovel-plan
运维类人工修复命令

都不在创作主链内。

9.4 `chapter_status`

不再由 skill 分步手推。

改成：

accepted commit -> projection 推到 chapter_committed
rejected commit -> projection 推到 chapter_rejected

9.5 验收

skills/ 和 agents/ 里不再有 state set-chapter-status
skills/ 和 agents/ 里不再有 index process-chapter
各存储只由对应 projection writer 写入

10. Section 7：projection 层收束

10.1 目标

确认 CHAPTER_COMMIT -> projection 是唯一写入链路，并补完 event 路由覆盖。

10.2 要做的事

10.2.1 补全 `EventProjectionRouter`

对照 story_event_schema.py，确保事件类型覆盖完整。

10.2.2 `chapter_status` 统一由 `state_projection_writer` 推进

accepted -> chapter_committed
rejected -> chapter_rejected

10.2.3 `projection_status` 回写 commit

最终 commit 文件里不允许残留 pending。

10.2.4 失败隔离

单个 writer 失败：

不阻断其他 writer
失败项写 failed
允许只补跑失败 writer

10.3 验收

projection_status 最终都是 done / failed / skipped
accepted commit 后状态自动推进
单个 writer 失败不拖死全链

11. Section 8：消费端同步

11.1 要改的文件

agents/context-agent.md
agents/data-agent.md
agents/reviewer.md（必要时）
skills/webnovel-write/SKILL.md
skills/webnovel-review/SKILL.md
skills/webnovel-query/SKILL.md
skills/webnovel-plan/SKILL.md（检查）
skills/webnovel-init/SKILL.md（检查）
skills/webnovel-dashboard/SKILL.md
skills/webnovel-write/evals/evals.json
docs/guides/commands.md

11.2 关键改动

`webnovel-write`

删除 Step 2/4 的状态直写
删除 Step 2 直接加载 core-constraints / anti-ai-guide
Step 1 生成任务书
Step 2 只吃任务书
Step 5 简化为：
- 调 data-agent
- 调 chapter-commit
- 确认 projection 完成

`context-agent`

research 用底稿
最终按示例写任务书
不再输出旧执行包三层结构

`data-agent`

只提取事实
只产出 commit artifacts
不再直接写 state/index/memory

`webnovel-query`

查询路径改成 commit / projection
不再运行时直接拼旧真源

11.3 静态测试

test_prompt_integrity.py 至少新增：

skill / agent 不得引用已删散写命令
data-agent 不直写
CLI 子命令引用都在注册表里

11.4 验收

skills / agents 不再引用旧散写路径
静态测试通过
eval 与命令文档同步

12. Section 9：向量索引增强 + 时序查询接口

12.1 这轮只做轻量增强

不引入真正的图引擎，不做新项目级图谱系统。

这轮只做两件轻量事：

commit 后把实体/事件写进向量索引
给现有 SQLite 表加统一的时序查询接口

12.2 向量索引补实体语义

`EventProjectionRouter`

给关键事件加 vector 路由：

character_state_changed
power_breakthrough
relationship_changed
world_rule_revealed
world_rule_broken
artifact_obtained

新增 `vector_projection_writer.py`

职责：

把 accepted_events
把 entity_deltas

转成自然语言句子，再写入向量库。

例如：

第47章：韩立突破筑基初期
第47章：韩立与陈巧倩关系变为合作

12.3 时序查询接口

新建 knowledge_query.py，提供：

entity_state_at_chapter(entity_id, chapter)
entity_relationships_at_chapter(entity_id, chapter)

供 context-agent research 阶段调用。

12.4 不做的事

不引入 neo4j
不引入 petgraph
不做图遍历
不做关系可视化

12.5 验收

事件 chunk 能进向量库
指定章节状态查询可用
指定章节关系查询可用
RAG 能同时命中正文 chunk 和事件 chunk

13. 实施顺序

这轮按严格串行走：

CSV_CONFIG
CSV 内容修补
裁决表
engine 接入裁决表
context_manager 瘦身
旧散写路径清理
projection 层收束
消费端同步
向量索引增强 + 时序查询

原因很简单：

这不是日常迭代
这是一次性系统收束
中间态存在多久不重要
重要的是每一步的验收标准清楚，最终状态正确

14. 最终判断

这份 spec 的最终判断可以压成五句话：

六层必须一起收束，不能只补前四层
消费端不能再直读知识层，必须只吃合同和投影视图
core-constraints 要被拆成具体约束，不再整篇读
anti-ai-guide 保留，但只由上游吸收后转写
CHAPTER_COMMIT -> projection 是唯一写后真源路径

做到这一步，webnovel-writer 才算真正从“半成品并存”进入“统一主链”状态。

2026-04-14-story-system-final-convergence-spec.md 15 KB Patstāvīgā saite Vēsture Neapstrādāts

Story System 最终收束 Spec

1. 文档定位

1.1 这份 spec 解决什么问题

1.2 一句话结论

2. 已确认的关键决策

2.1 范围

2.2 向后兼容

2.3 context_manager

2.4 CSV_CONFIG

2.5 裁决层

2.6 anti-ai-guide.md 与 core-constraints.md

2.7 消费端真源

2.8 首批题材范围

2.9 实施顺序

3. 总体链路

4. Section 1：CSV_CONFIG 注册层

4.1 要做什么

4.2 目标形态

4.3 改动要求

4.4 验收

5. Section 2：CSV 内容修补

5.1 要做什么

5.2 重点问题

5.3 具体改造

5.3.1 毒点列统一

5.3.2 路由表补字段

5.3.3 内容补全规则

5.3.4 README 同步

5.4 验收

6. Section 3：裁决表

6.1 要做什么

6.2 与路由表的边界

6.3 字段

6.4 首批覆盖

6.5 验收

7. Section 4：engine 接入裁决表

7.1 当前问题

7.2 目标流程

7.3 新增方法

7.4 source_trace

7.5 验收

8. Section 5：context_manager 瘦身

8.1 目标

8.2 保留职责

8.3 删除职责

8.4 输出形态

8.5 相关要求

8.6 验收

9. Section 6：旧散写路径清理

9.1 问题

9.2 要删的路径

webnovel-write

其他直写入口

9.3 合法直写保留

9.4 chapter_status

9.5 验收

10. Section 7：projection 层收束

10.1 目标

10.2 要做的事

10.2.1 补全 EventProjectionRouter

10.2.2 chapter_status 统一由 state_projection_writer 推进

10.2.3 projection_status 回写 commit

10.2.4 失败隔离

10.3 验收

11. Section 8：消费端同步

11.1 要改的文件

11.2 关键改动

webnovel-write

context-agent

data-agent

webnovel-query

11.3 静态测试

11.4 验收

12. Section 9：向量索引增强 + 时序查询接口

12.1 这轮只做轻量增强

12.2 向量索引补实体语义

EventProjectionRouter

新增 vector_projection_writer.py

12.3 时序查询接口

2026-04-14-story-system-final-convergence-spec.md 15 KB

Patstāvīgā saite Vēsture Neapstrādāts

2.3 `context_manager`

2.4 `CSV_CONFIG`

2.6 `anti-ai-guide.md` 与 `core-constraints.md`

4. Section 1：`CSV_CONFIG` 注册层

7.4 `source_trace`

8. Section 5：`context_manager` 瘦身

`webnovel-write`

9.4 `chapter_status`

10.2.1 补全 `EventProjectionRouter`

10.2.2 `chapter_status` 统一由 `state_projection_writer` 推进

10.2.3 `projection_status` 回写 commit

`webnovel-write`

`context-agent`

`data-agent`

`webnovel-query`

`EventProjectionRouter`

新增 `vector_projection_writer.py`