webnovel-writer/docs/architecture/system-architecture-diagram.md

Webnovel Writer 系统架构总图

生成日期：2026-04-15 ｜ 覆盖范围：init → plan → write 全链路六层主链 + 读写映射

📖 Webnovel Writer 系统架构

init → plan → write 六层主链 ｜ 全读写映射

写入（Write）

读取（Read）

读写（R/W）

核心组件

📂 项目文件（Project Files）

大纲/总纲.md

大纲/第X卷-详细大纲.md

大纲/第X卷-时间线.md

大纲/第X卷-节拍表.md

设定集/*.md

正文/第NNNN章.md

.webnovel/idea_bank.json

📋 合同树（.story-system/）

MASTER_SETTING.json

volumes/volume_NNN.json

chapters/chapter_NNN.json

reviews/chapter_NNN.review.json

anti_patterns.json

commits/chapter_NNN.commit.json

💾 投影存储（Projection Stores）

state.json（状态）

index.db（实体/关系）

summaries/chNNNN.md（摘要）

memory_scratchpad.json（记忆）

vector_db（向量索引）

🎯 用户入口（User Entry）: /webnovel-init → /webnovel-plan → /webnovel-write

/webnovel-init（初始化）

Read
genre-tropes.md
genre-profiles.md

交互收集 7 步
题材/角色/金手指
世界观/创意约束

Write
state.json
设定集/*.md
总纲.md
idea_bank.json

/webnovel-plan（规划）

Read
state.json（genre）
总纲.md
设定集/*.md
summaries/（跨卷）

卷纲 → 时间线
→ 拆章纲
节拍表/CBN/CPNs/CEN

Write
节拍表.md
时间线.md
详细大纲.md
设定集（增量）

/webnovel-write（写章）

Step 1→6
上下文→起草→审查
→润色→提交→备份

Write
正文/第NNNN章.md
commit.json
→ 5路投影

📚 Layer 1: 知识层（Knowledge）— CSV 表 + 参考文档

题材与调性推理.csv
路由表（Route）
8 行流派

裁决规则.csv
裁决表（Reasoning）
7 题材

命名规则.csv
基础表（Base）

人设与关系.csv
基础表（Base）

写作技法.csv
基础表（Base）

场景写法.csv
基础表（Base）

金手指与设定.csv
基础表（Base）

桥段套路.csv
动态表（Dynamic）

爽点与节奏.csv
动态表（Dynamic）

CSV_CONFIG
per-table 注册
search_cols/output_cols
poison_col/role

🧠 Layer 2: 裁决层（Reasoning）— story_system_engine.py

_route()
Read: 题材与调性推理.csv
匹配题材→推荐表

_collect_tables()
Read: 基础表+动态表
BM25 检索

_load_reasoning()
Read: 裁决规则.csv
别名匹配（修仙→东方仙侠）
fallback 到原始 genre

_apply_reasoning()
冲突裁决排序
毒点加权
反模式注入

📜 Layer 3: 合同层（Contract）— .story-system/

写前合同（story-system --persist）

MASTER_SETTING
Write: 题材/调性/禁忌

VOLUME_BRIEF
Write: 卷目标/节奏

CHAPTER_BRIEF
Write: reasoning 裁决
chapter_focus（参考）

REVIEW_CONTRACT
Write: 必须节点/禁区

写后真源（chapter-commit）

CHAPTER_COMMIT
Write: accepted/rejected
events + deltas + summary

anti_patterns.json
Write: 题材毒点集合

🔍 Layer 4: 上下文层（Context）— 写前组装

context-agent（Step 1 子代理）

load-context
Read: contracts
summaries/protagonist
rules/loops/memory_pack
genre_profile_excerpt

Read 章纲原文
大纲/第X卷-详细大纲.md
（最高权重）

按需深查
query-entity
query-rules
get-timeline
get-reader-signals

输出: 写作任务书
五段格式
消费 reasoning 裁决
内化 Anti-AI 铁律

辅助查询

context_manager
纯 JSON 组装器
Read: contracts/state
runtime/guidance

knowledge_query
时序查询
entity_state_at_chapter
relationships_at_chapter

reference_search
CSV BM25 检索
per-table search_cols

⚙️ Layer 5: 提交层（Commit）— 写后事实入口

data-agent（Step 5.1 子代理）

Read 正文
正文/第NNNN章.md

查询实体
get-core-entities
recent-appearances

提取事实
Write: extraction_result
fulfillment_result
disambiguation_result

摘要生成
summary_text
100-150字 + 钩子

chapter-commit CLI（Step 5.2）

Read 4份 artifacts
tmp/*.json

判定 accepted/rejected
blocking_count=0
missed_nodes=空
pending=空

Write commit.json
→ 触发投影链

💿 Layer 6: 投影层（Projection）— EventProjectionRouter → 5 Writers

state_projection
Write: state.json
entity_state
chapter_status
（committed/rejected）

index_projection
Write: index.db
entity_deltas
relationships

summary_projection
Write: summaries/
chNNNN.md
剧情摘要

memory_projection
Write: memory_
scratchpad.json
长期记忆事实

vector_projection
Write: vector_db
event→text→embed
delta→text→embed

🔗 题材流通路径

① init 写入 state.json

② story-system 读 genre

③ 路由表匹配流派

④ 裁决表别名匹配题材

⑤ reasoning 写入 chapter.json

⑥ context-agent 消费

⑦ 任务书第4段输出

📏 数据权重（高→低）

① 用户要求

② 章纲原文

③ MASTER_SETTING

④ reasoning 裁决

⑤ CHAPTER_COMMIT

⑥ CSV 检索（参考）

⚡ Token 优化

context-agent: 2.9k tokens

write SKILL: 1.8k tokens

data-agent: 1.2k tokens

load-context 含 contracts

内化 core-constraints

内化 anti-ai-guide

get-reader-signals 合并

review-pipeline --save-metrics

🛡️ 写入保护

唯一写后入口: COMMIT

state/index/summary/memory
只由 projection 写入

skill 不直接 set-chapter-status

data-agent 不直写存储