# Story System 最终收束 Spec

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

---

## 1. 文档定位

### 1.1 这份 spec 解决什么问题

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

- [`current-system-diagnosis.md`](../../architecture/current-system-diagnosis.md)
  - 当前系统哪里散、哪里重复、哪里有半成品
- [`2026-04-12-story-system-evolution-spec.md`](./2026-04-12-story-system-evolution-spec.md)
  - 六层主链应该长什么样
- [`2026-04-14-context-agent-writing-brief-design.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 个题材：

1. 西方奇幻
2. 东方仙侠
3. 科幻末世
4. 都市日常
5. 都市修真
6. 都市高武
7. 历史古代

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

### 2.9 实施顺序

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

---

## 3. 总体链路

最终链路固定为：

```text
知识表 / 裁决表
        ↓
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
```

这里有两个硬边界：

1. 消费端不再运行时直读知识层
2. 写后事实只允许经 `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 目标形态

```python
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()` 只有：

1. 路由
2. 检索
3. 直接组装

没有显式裁决层。

### 7.2 目标流程

改成：

1. `_route()`
2. `_collect_tables()`
3. `_load_reasoning()`
4. `_apply_reasoning()`
5. `_rank_anti_patterns()`
6. `_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()` 只返回：

```json
{
  "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 这轮只做轻量增强

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

这轮只做两件轻量事：

1. commit 后把实体/事件写进向量索引
2. 给现有 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. 实施顺序

这轮按严格串行走：

1. `CSV_CONFIG`
2. CSV 内容修补
3. 裁决表
4. engine 接入裁决表
5. `context_manager` 瘦身
6. 旧散写路径清理
7. projection 层收束
8. 消费端同步
9. 向量索引增强 + 时序查询

原因很简单：

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

---

## 14. 最终判断

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

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

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