webnovel-writer/docs/storyteller-implementation-plan.md

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. 全程向后兼容，无节点章纲照常运行

总体架构

/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

推荐写入结构：

{
  "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 的核心思想，又避免了额外主流程和重复组件的膨胀。