WebNovel-Writer 数据流与存储架构实战理解.webnovel/投影层、index.db 表结构与查询工作流【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer导读本文围绕 webnovel-writer 项目中面向查询与理解的数据流规范文档webnovel-writer/skills/webnovel-query/references/system-data-flow.md展开完整讲解长篇网文辅助创作系统中的「写后数据投影层」.webnovel/目录的组织约定、state.json与index.db的分工、双 Agent 读写架构、每章数据链以及实体消歧与伏笔字段规范。读者读完后将能准确回答项目数据存在哪里、谁写入、谁读取、如何查询并掌握基于统一 CLIwebnovel.py的实体、别名、关系、状态变化与伏笔紧急度查询实战方法同时理解 v6.0.0 之后该系统向 Story System 合同树演进的背景。一、文档定位查询技能加载的数据结构参考system-data-flow.md是 webnovel-query 技能的私有参考文档其 frontmatter 明确声明了加载时机与用途name: system-data-flow purpose: 项目初始化和状态查询时加载理解数据结构该文档的职责是补充网文工作流特定的目录约定和脚本职责Claude 已知一般文件组织这里只补充网文专属部分并用于查询时理解read-model读模型。需要特别注意的是文档开头有一段重要的版本警示⚠️ 本文件描述.webnovel/投影层数据结构与早期写作流程供查询时理解 read-model。v6.0.0 写后主链已改为 Story System.story-system/合同树 acceptedCHAPTER_COMMIT下文「双 Agent 架构 / 每章数据链 / Data Agent 直接写入」等描述为历史流程事实以 Story System 为准。也就是说本文所述的双 Agent 架构与.webnovel/投影层在 v6.0.0 之前是写后事实的唯一落点在 v6.0.0 之后降级为查询视图投影层真正的写后事实以.story-system/合同树与 acceptedCHAPTER_COMMIT为准。这一点在阅读下文所有内容时都应保持清醒。二、项目目录约定正文、大纲、设定集与.webnovel/网文项目的目录结构遵循固定约定.webnovel/是系统运行时数据目录投影层其余为用户可见的创作内容目录项目根目录/ ├── 正文/ # 章节文件第0001章.md 或 第1卷/第001章-标题.md ├── 大纲/ # 卷纲/章纲/场景纲 ├── 设定集/ # 世界观/力量体系/角色卡/物品卡 └── .webnovel/ ├── state.json # 精简状态 ( 5KB)进度/主角/strand_tracker/消歧 ├── index.db # SQLite 主存储实体/别名/关系/状态变化/章节/场景 ├── workflow_state.json # 工作流断点legacyv6 写章主链改用 Story System chapter-commit ├── vectors.db # RAG 向量数据库 ├── summaries/ # 章节摘要chNNNN.md └── archive/ # 归档数据不活跃角色/已回收伏笔各目录的职责划分路径内容角色正文/第0001章.md 或 第1卷/第001章-标题.md成稿正文纯文本大纲/卷纲/章纲/场景纲写前规划设定集/世界观/力量体系/角色卡/物品卡静态设定真源.webnovel/state.json精简状态 5KB进度/主角/伏笔线/消歧.webnovel/index.dbSQLite 主存储实体/别名/关系/状态变化/章节/场景.webnovel/vectors.dbRAG 向量库语义检索.webnovel/summaries/chNNNN.md 章节摘要章节记忆.webnovel/archive/归档 JSON不活跃角色/已回收伏笔在源码层面DataModulesConfigwebnovel-writer/scripts/data_modules/config.py以 property 形式固化了这些路径约定webnovel_dir指向.webnovel、state_file指向state.json、index_db指向index.db、chapters_dir指向正文、settings_dir指向设定集、outline_dir指向大纲并额外定义了.story-system/系列路径MASTER_SETTING.json、chapters/等与文档中 v6 演进的说明相互印证。三、架构演进解决 state.json 膨胀问题的存储迁移文档点出了本次架构变更的核心动因state.json 膨胀问题——20 章后 token 爆炸。随着章节增长实体、别名、状态变化、关系等数据结构全部堆积在单个 JSON 文件中导致每次读取与写入都要序列化/反序列化整份文件token 消耗急剧上升。解决思路是存储职责拆分把高频增长、需要按需查询的大数据迁入 SQLiteindex.db把高频读取、需要精简快照的小数据留在state.json。具体迁移对照如下数据类型旧版存储位置当前存储位置entities_v3state.jsonindex.db(entities 表)alias_indexstate.jsonindex.db(aliases 表)state_changesstate.jsonindex.db(state_changes 表)structured_relationshipsstate.jsonindex.db(relationships 表)progressstate.jsonstate.json (保留)protagonist_statestate.jsonstate.json (保留)strand_trackerstate.jsonstate.json (保留)disambiguation_*state.jsonstate.json (保留)从源码看这次迁移在IndexManagerwebnovel-writer/scripts/data_modules/index_manager.py的版本注释中留下了完整轨迹v5.1 引入entities、aliases、state_changes、relationships四张表替代 state.json 中的对应字段v5.3 新增追读力债务体系override_contracts、chase_debt、debt_events、chapter_reading_powerv5.4 新增invalid_facts无效事实追踪、tool_call_stats工具调用统计、review_metrics审查指标等表。可见index.db不仅是实体存储还承载了追读力、审查、可观测性等多维数据。四、双 Agent 架构Context Agent读与 Data Agent写在 v6 之前的写后主链中读写职责被拆分为两个 Agent中间以index.db state.json为数据中枢写作前: Context Agent 读取数据 → 组装上下文包 ├── 从 state.json 读取精简数据进度/配置 └── 从 index.db SQL 按需查询实体/关系 写作中: Writer 使用上下文包生成纯正文无 XML 标签 写作后: Data Agent 处理正文 → AI 提取实体 → 写入数据链 ├── 写入 index.db实体/别名/状态变化/关系 ├── 更新 state.json进度/主角快照 chapter_meta └── 写入 summaries/chNNNN.md章节摘要 Context Agent (读) ←→ index.db state.json ←→ Data Agent (写)这一架构的设计要点读写分离查询路径Context Agent与写入路径Data Agent互不耦合均可独立演进按需查询Context Agent 不再整份加载 state.json而是用 SQL 按需查询实体/关系控制 token 消耗纯正文生成Writer 生成的是无 XML 标签的正文结构化信息提取全部后置到 Data Agent避免污染成稿。对应到源码模块写入侧由SQLStateManagerwebnovel-writer/scripts/data_modules/sql_state_manager.py提供与旧StateManager兼容的高层接口——upsert_entity、record_state_change、upsert_relationship、get_protagonist、get_core_entities等底层委托IndexManager落库读取侧则由IndexManager的查询接口如get-entity、get-by-alias、get-state-changes、get-relationships支撑。五、每章数据链写后处理的 7 步完整流程文档给出的「每章数据链」是理解系统如何从章节正文沉淀为结构化记忆的关键共 7 步1. Context Agent 组装创作任务书 → 读取 state.json精简版进度/配置 → SQL 查询 index.db核心实体/按需实体 → RAG 检索相关场景 2. Step 1.5 章节设计 → 选开头/钩子/爽点模式避开最近3章 3. Writer 生成章节内容 → 2A 粗稿纯正文 → 2B 风格适配可选 4. 审查统一 reviewer agent → 设定一致性/时间线/叙事连贯/角色一致性/逻辑 五维度检查 → 输出审查报告 5. 网文化润色 → 基于审查报告修复问题 → 强化口感规则 6. Data Agent 处理数据链 → AI 实体提取替代 XML 标签解析 → 实体消歧置信度策略 → 写入 index.db实体/别名/状态变化/关系 → 更新 state.json进度/主角快照 chapter_meta → 写入 summaries/chNNNN.md章节摘要 → 向量嵌入 (RAG) → 风格样本评估 7. Git 备份强制流程要点解读第 1 步是读路径的完整展开state.json精简负责进度与配置index.dbSQL负责实体与关系vectors.dbRAG负责语义检索相关场景——三种数据源各司其职第 4 步的审查是五个维度设定一致性/时间线/叙事连贯/角色一致性/逻辑的机器检查审查报告是第 5 步润色的输入第 6 步是数据沉淀的核心AI 实体提取取代了早期的 XML 标签解析方案随后依次完成消歧、落库index.db、精简状态更新state.json、章节摘要summaries/chNNNN.md、向量嵌入与风格样本评估第 7 步强制 Git 备份保证每个章节都有可回滚的快照。文档同时提醒update_state.py用于手动/脚本化更新progress/protagonist_state/strand_tracker等字段主流程通常由 Data Agent 在处理数据链时同步推进进度手动脚本仅作为补充手段。六、state.json 精简结构 5KB 的轻量快照迁移后state.json只保留高频读取的精简数据文档给出了完整结构{ project_info: {title: , genre: }, progress: {current_chapter: N, total_words: W, current_volume: 1}, protagonist_state: { name: , power: {realm: , layer: 1, bottleneck: }, location: {current: , last_chapter: 0}, golden_finger: {name: , level: 1, skills: []} }, strand_tracker: { last_quest_chapter: 0, last_fire_chapter: 0, last_constellation_chapter: 0, current_dominant: quest, chapters_since_switch: 0, history: [] }, relationships: {}, plot_threads: {active_threads: [], foreshadowing: []}, world_settings: {}, disambiguation_warnings: [], disambiguation_pending: [], review_checkpoints: [], chapter_meta: {}, _migrated_to_sqlite: true }字段语义字段含义project_info书名与题材progress当前章节号、累计字数、当前卷号protagonist_state主角快照境界realm/layer/bottleneck、位置当前地点最近出场章节、金手指名称/等级/技能strand_tracker追读线切换记录上次任务线/爽点线/星座线的章节当前主导线、距上次切换章节数及历史relationships简化版关系完整关系在 index.dbplot_threads活跃线索与伏笔清单world_settings世界观骨架仅等级名/势力名/地名等轻量信息disambiguation_warnings/disambiguation_pending消歧警告与待人工确认队列review_checkpoints审查检查点chapter_meta章节元数据_migrated_to_sqlite迁移标记True 表示大数据已迁入 index.db文档强调entities_v3、alias_index、state_changes、structured_relationships 已迁移到 index.db不再存储在 state.json 中。这一精简策略与迁移脚本 webnovel-writer/scripts/data_modules/migrate_state_to_sqlite.py 中的slim_state构建逻辑完全一致world_settings只保留力量体系前 20 个等级名、前 30 个势力名、前 50 个地点名review_checkpoints只保留最近 10 个disambiguation_warnings保留最近 20 条、disambiguation_pending保留最近 10 条从而把整个文件压到 5KB 量级。七、index.db 表结构SQLite 主存储详解文档给出了index.db的核心表结构v5.1 引入的四张表这是理解整个投影层的基石-- 实体表 CREATE TABLE entities ( id TEXT PRIMARY KEY, type TEXT NOT NULL, -- 角色/地点/物品/势力/招式 canonical_name TEXT NOT NULL, tier TEXT DEFAULT 装饰, -- 核心/重要/次要/装饰 desc TEXT, current_json TEXT, -- JSON: {realm, location, ...} first_appearance INTEGER, last_appearance INTEGER, is_protagonist INTEGER DEFAULT 0, is_archived INTEGER DEFAULT 0 ); -- 别名表一对多 CREATE TABLE aliases ( alias TEXT NOT NULL, entity_id TEXT NOT NULL, entity_type TEXT NOT NULL, PRIMARY KEY (alias, entity_id, entity_type) ); -- 状态变化表 CREATE TABLE state_changes ( id INTEGER PRIMARY KEY AUTOINCREMENT, entity_id TEXT NOT NULL, field TEXT NOT NULL, old_value TEXT, new_value TEXT, reason TEXT, chapter INTEGER NOT NULL ); -- 关系表 CREATE TABLE relationships ( id INTEGER PRIMARY KEY AUTOINCREMENT, from_entity TEXT NOT NULL, to_entity TEXT NOT NULL, type TEXT NOT NULL, description TEXT, chapter INTEGER NOT NULL, UNIQUE(from_entity, to_entity, type) ); -- 原有表保留 CREATE TABLE chapters (...); CREATE TABLE scenes (...); CREATE TABLE appearances (...);各表设计意图entities实体主表tier四档核心/重要/次要/装饰用于区分重要度current_json以 JSON 存储实体当前状态境界/位置/物品等first_appearance/last_appearance记录首次与最近出场章节is_archived支持归档不活跃实体aliases别名表是一对多结构——同一别名可映射到多个实体主键为(alias, entity_id, entity_type)三元组同一别名指向多实体时靠entity_type区分详见第九节state_changes追加式状态变化流水field记录变化的字段如realmold_value/new_value记录前后值reason记录变化原因chapter记录发生章节——这是某角色在第 N 章时处于什么状态这类时序查询的数据基础relationships实体关系边UNIQUE(from_entity, to_entity, type)防止同类型关系重复插入chapter记录关系确立章节。对照源码 webnovel-writer/scripts/data_modules/index_manager.py 的_init_db实际建表还包含chapters章节元数据含 title/location/word_count/characters/summary、scenes场景索引含 start_line/end_line、appearances实体出场记录含 mentions/confidence、relationship_events关系事件时序流含 polarity/strength/evidence/confidence用于图谱与时间线回放以及 v5.3/v5.4 引入的override_contracts、chase_debt、debt_events、chapter_reading_power、invalid_facts、review_metrics、rag_query_log、tool_call_stats、writing_checklist_scores。文档中原有表保留的表述在源码中均有完整定义且每张表都配套了查询索引如idx_aliases_alias、idx_state_changes_entity、idx_relationships_from等保证按实体、按章节的查询路径高效。八、Data Agent AI 提取流程与实体消歧置信度策略v6 之前的主流程不再要求正文携带 XML 标签结构化信息由 Data Agent 智能提取文档给出 5 个步骤实体识别从正文语义识别角色/地点/物品/势力实体匹配优先匹配已有实体通过 alias_index消歧处理置信度 0.8: 自动采用置信度 0.5-0.8: 采用但记录 warning置信度 0.5: 标记待人工确认状态变化识别境界突破/位置移动/关系变化写入存储直接写入 index.db实体/别名/关系/状态变化。置信度阈值在配置层被固化为可调参数webnovel-writer/scripts/data_modules/config.py# 实体提取配置 extraction_confidence_high: float 0.8 extraction_confidence_medium: float 0.5实现层面EntityLinkerwebnovel-writer/scripts/data_modules/entity_linker.py的evaluate_confidence正是文档策略的代码化def evaluate_confidence(self, confidence: float) - Tuple[str, bool, Optional[str]]: if confidence self.config.extraction_confidence_high: return (auto, True, None) elif confidence self.config.extraction_confidence_medium: return (warn, True, f中置信度匹配 (confidence: {confidence:.2f})) else: return (manual, False, f需人工确认 (confidence: {confidence:.2f}))confidence 0.8→auto自动采用0.5 confidence 0.8→warn采用但附带警告可经DisambiguationResult.warning汇总为disambiguation_warningsconfidence 0.5→manual不采用进入disambiguation_pending待人工确认。lookup_alias/lookup_alias_all实现了一对多别名的匹配与按类型过滤process_extraction_result批量处理 AI 提取结果中的 uncertain 项并汇总警告。九、伏笔字段规范与 alias_index 一对多格式伏笔字段规范伏笔状态字段有严格的取值约束历史值需迁移对齐字段规范值兼容值历史status未回收/已回收待回收/进行中/active/pending推荐字段content伏笔内容、status状态、planted_chapter埋设章节、target_chapter回收目标章节、tier重要度。配套的紧急度计算参数同样定义在配置层webnovel-writer/scripts/data_modules/config.py# 伏笔紧急度 foreshadowing_urgency_pending_high: int 100 foreshadowing_urgency_pending_medium: int 50 foreshadowing_urgency_target_proximity: int 5 foreshadowing_urgency_score_high: int 100 foreshadowing_urgency_score_medium: int 60 foreshadowing_urgency_score_target: int 80 foreshadowing_urgency_score_low: int 20 foreshadowing_urgency_threshold_show: int 60即pending 状态的高/中档阈值100/50、距离目标章节的临近判定5 章内、紧急度分值档位100/60/80/20以及展示阈值≥60 才在报告中提示。这也解释了为什么文档示例中status -- --focus urgency能输出伏笔紧急度——status_reporter.py依赖的就是这套评分体系。alias_index 格式一对多{ 林天: [{type: 角色, id: lintian}], 天云宗: [ {type: 地点, id: loc_tianyunzong}, {type: 势力, id: faction_tianyunzong} ] }关键点同一别名可映射到多个实体如天云宗既是地点又是势力消歧时根据type或上下文判断。文档的错误纠正条目明确提醒alias_index 期望单对象是常见误区当前结构必须使用数组格式一对多。这一语义在 SQLite 的aliases表中通过(alias, entity_id, entity_type)联合主键得到等价表达。十、统一 CLI 查询实战webnovel.py 全命令速查文档附带的 examples 全部通过统一入口webnovel.py执行。该脚本webnovel-writer/scripts/webnovel.py本身只负责把scripts/目录加入sys.path并转发到data_modules.webnovel的main()真正的命令分派在 webnovel-writer/scripts/data_modules/webnovel.py其中PASSTHROUGH_TOOLS定义了index、state、rag、style、entity、context、memory、migrate、status、update-state、backup、archive、init、story-system、memory-contract、project-memory等转发工具所有写入类命令统一前置注入--project-root避免参数位置与引号问题。以下命令均以SCRIPTS_DIR指向脚本目录、PROJECT_ROOT指向书项目根目录必须包含.webnovel/state.json为前提。1. 查询当前进度cat $PROJECT_ROOT/.webnovel/state.json | jq .progress # 输出: { current_chapter: 45, total_words: 135000 }2. 查询实体SQLpython ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-entity --id xiaoyan # 输出: {id: xiaoyan, type: 角色, canonical_name: 萧炎, ...} python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-core-entities # 输出: 所有核心实体主角 tier核心/重要get-core-entities的筛选语义在IndexManager的查询接口中实现get-entities-by-type还可按角色/地点/物品/势力/招式类型过滤get-protagonist直接返回主角实体。3. 按别名查找实体一对多python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-by-alias --alias 天云宗 # 输出: [{id: loc_tianyunzong, type: 地点}, {id: faction_tianyunzong, type: 势力}]4. 查询状态变化python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-state-changes --entity xiaoyan --limit 10 # 输出: [{entity_id, field, old_value, new_value, reason, chapter}, ...]--limit默认为 20可通过参数调整返回条数。5. 查询关系python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-relationships --entity xiaoyan # 输出: [{from_entity, to_entity, type, description, chapter}, ...]进阶命令还包括get-relationship-graph --center id --depth 2 --format json|mermaid关系图谱可输出 mermaid 供可视化、get-relationship-timeline --a A --b B两实体关系时间线、get-relationship-events关系事件流支持--from-chapter/--to-chapter区间过滤。6. 检查伏笔紧急度python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT status -- --focus urgency注意status转发的是status_reporter.py参数前需加--分隔紧急度评分依据第九节的配置参数计算。7. 查询实体出场记录python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index entity-appearances --entity lintian8. 迁移旧 state.json 到 SQLitepython ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT migrate -- --backup # 自动备份 state.json迁移数据到 index.db精简 state.json迁移脚本 webnovel-writer/scripts/data_modules/migrate_state_to_sqlite.py 的完整参数为--dry-run只分析不写入、--backup默认开启迁移前备份为state.json.backup-时间戳、--no-backup、--quiet迁移统计覆盖 entities/aliases/state_changes/relationships/skipped/errors 六项指标若存在错误则保留原字段不精简。补充更高层的知识查询v6 记忆编排在 v6 演进后webnovel-query 技能的查询流程webnovel-writer/skills/webnovel-query/SKILL.md进一步引入knowledge与memory-contract两组命令按查询类型选择最窄工具# 角色历史状态某实体在指定章节时的状态 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} knowledge query-entity-state --entity {entity_id} --at-chapter {N} # 实体关系某实体在指定章节时的所有关系 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} knowledge query-relationships --entity {entity_id} --at-chapter {N} # 世界规则 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} memory-contract query-rules --chapter {chapter_num} # 伏笔 / open loop python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} memory-contract get-open-loops # 仅综合 / 复杂查询需要时间线 长期记忆联合时才用 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} memory-contract load-context --chapter {chapter_num}其中knowledge query-entity-state --at-chapter正是基于state_changes表的章节维度时序查询能力将本文第七节表结构与查询实践直接打通。十一、v6.0.0 演进Story System 合同树与真源优先级回到文档开头的警示——v6.0.0 之后写后主链已切换为 Story System.story-system/合同树MASTER_SETTING.json、volumes/*.json、chapters/*.json acceptedCHAPTER_COMMIT。.webnovel/投影层退居为查询视图。webnovel-query 技能按如下优先级定位写前真源 → 写后真源 → 投影层.story-system/MASTER_SETTING.json- 全书主设定题材、调性、核心禁忌.story-system/volumes/*.json- 卷级合同本卷目标、节奏策略.story-system/chapters/*.json- 章级合同本章焦点、动态上下文latest accepted.story-system/commits/chapter_XXX.commit.json- 写后事实已发布章节的定稿状态不可篡改memory-contract系列查询 - 记忆编排结果长期记忆、伏笔、时间线.webnovel/state.json/index.db- 投影层仅 fallback / read-model类比网文后台的角色卡、章节列表。也就是说写前真源1-3是作者开写前必须遵守的大纲、设定、禁区写后真源4是已发布章节的定稿状态投影层5-6是从写后真源自动生成的查询视图。当.story-system/合同与 accepted commit 缺失时SKILL.md 要求查询必须显式声明已降级到 legacy fallback。因此本文第七、八、九节介绍的 index.db 结构与消歧策略在当前架构中的正确定位是理解 read-model 的数据结构、支持快速检索的投影层而写后事实的权威来源以.story-system/为准。十二、常见错误规避清单文档 errors 段列出了实践中最高频的八类错误及正确做法整理如下这也是查询与初始化阶段判断数据是否健康的快速检查表❌ 常见错误✅ 正确做法伏笔状态写成待回收使用规范值未回收手工更新忘记加 planted_chapter脚本已自动补全归档路径混淆固定为.webnovel/archive/*.jsonalias_index 期望单对象当前结构使用数组格式一对多期望 XML 标签提取当前主流程由 Data Agent AI 自动提取使用旧版 data_modules.state_manager schema统一使用 entities_v3 结构后迁入 index.db entities 表仍从 state.json 读取 entities_v3改用 SQL 查询 index.db仍写入 state.json 大数据改用 SQLite 增量写入让 state.json 持续膨胀运行迁移脚本:python ${SCRIPTS_DIR}/webnovel.py migrate其中最后一条的完整写法是python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT migrate -- --backup迁移前自动备份、迁移后自动精简详见第十节。这套清单对维护一个 200 万字量级连载项目的数据健康至关重要——只要遵循大数据进 SQLite、小快照留 state.json、写后事实进 Story System的原则就不会重蹈 token 爆炸与数据割裂的覆辙。结语从.webnovel/目录约定、state.json 精简快照、index.db 表结构到双 Agent 读写架构、每章数据链与消歧置信度策略本文完整还原了 webnovel-writer 投影层数据流的全貌并给出了统一 CLI 的查询实战命令与 v6 Story System 演进后的真源优先级。对于希望理解该系统数据存在哪里、如何写入、如何查询的开发者或 Agent 而言system-data-flow.md连同其配套源码index_manager.py、sql_state_manager.py、entity_linker.py、migrate_state_to_sqlite.py构成了一套自洽、可验证的参考体系可作为排查数据问题、扩展查询能力或设计类似创作辅助系统时的直接范本。【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WebNovel-Writer 数据流与存储架构实战理解.webnovel/投影层、index.db 表结构与查询工作流【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer导读本文围绕 webnovel-writer 项目中面向查询与理解的数据流规范文档webnovel-writer/skills/webnovel-query/references/system-data-flow.md展开完整讲解长篇网文辅助创作系统中的「写后数据投影层」.webnovel/目录的组织约定、state.json与index.db的分工、双 Agent 读写架构、每章数据链以及实体消歧与伏笔字段规范。读者读完后将能准确回答项目数据存在哪里、谁写入、谁读取、如何查询并掌握基于统一 CLIwebnovel.py的实体、别名、关系、状态变化与伏笔紧急度查询实战方法同时理解 v6.0.0 之后该系统向 Story System 合同树演进的背景。一、文档定位查询技能加载的数据结构参考system-data-flow.md是 webnovel-query 技能的私有参考文档其 frontmatter 明确声明了加载时机与用途name: system-data-flow purpose: 项目初始化和状态查询时加载理解数据结构该文档的职责是补充网文工作流特定的目录约定和脚本职责Claude 已知一般文件组织这里只补充网文专属部分并用于查询时理解read-model读模型。需要特别注意的是文档开头有一段重要的版本警示⚠️ 本文件描述.webnovel/投影层数据结构与早期写作流程供查询时理解 read-model。v6.0.0 写后主链已改为 Story System.story-system/合同树 acceptedCHAPTER_COMMIT下文「双 Agent 架构 / 每章数据链 / Data Agent 直接写入」等描述为历史流程事实以 Story System 为准。也就是说本文所述的双 Agent 架构与.webnovel/投影层在 v6.0.0 之前是写后事实的唯一落点在 v6.0.0 之后降级为查询视图投影层真正的写后事实以.story-system/合同树与 acceptedCHAPTER_COMMIT为准。这一点在阅读下文所有内容时都应保持清醒。二、项目目录约定正文、大纲、设定集与.webnovel/网文项目的目录结构遵循固定约定.webnovel/是系统运行时数据目录投影层其余为用户可见的创作内容目录项目根目录/ ├── 正文/ # 章节文件第0001章.md 或 第1卷/第001章-标题.md ├── 大纲/ # 卷纲/章纲/场景纲 ├── 设定集/ # 世界观/力量体系/角色卡/物品卡 └── .webnovel/ ├── state.json # 精简状态 ( 5KB)进度/主角/strand_tracker/消歧 ├── index.db # SQLite 主存储实体/别名/关系/状态变化/章节/场景 ├── workflow_state.json # 工作流断点legacyv6 写章主链改用 Story System chapter-commit ├── vectors.db # RAG 向量数据库 ├── summaries/ # 章节摘要chNNNN.md └── archive/ # 归档数据不活跃角色/已回收伏笔各目录的职责划分路径内容角色正文/第0001章.md 或 第1卷/第001章-标题.md成稿正文纯文本大纲/卷纲/章纲/场景纲写前规划设定集/世界观/力量体系/角色卡/物品卡静态设定真源.webnovel/state.json精简状态 5KB进度/主角/伏笔线/消歧.webnovel/index.dbSQLite 主存储实体/别名/关系/状态变化/章节/场景.webnovel/vectors.dbRAG 向量库语义检索.webnovel/summaries/chNNNN.md 章节摘要章节记忆.webnovel/archive/归档 JSON不活跃角色/已回收伏笔在源码层面DataModulesConfigwebnovel-writer/scripts/data_modules/config.py以 property 形式固化了这些路径约定webnovel_dir指向.webnovel、state_file指向state.json、index_db指向index.db、chapters_dir指向正文、settings_dir指向设定集、outline_dir指向大纲并额外定义了.story-system/系列路径MASTER_SETTING.json、chapters/等与文档中 v6 演进的说明相互印证。三、架构演进解决 state.json 膨胀问题的存储迁移文档点出了本次架构变更的核心动因state.json 膨胀问题——20 章后 token 爆炸。随着章节增长实体、别名、状态变化、关系等数据结构全部堆积在单个 JSON 文件中导致每次读取与写入都要序列化/反序列化整份文件token 消耗急剧上升。解决思路是存储职责拆分把高频增长、需要按需查询的大数据迁入 SQLiteindex.db把高频读取、需要精简快照的小数据留在state.json。具体迁移对照如下数据类型旧版存储位置当前存储位置entities_v3state.jsonindex.db(entities 表)alias_indexstate.jsonindex.db(aliases 表)state_changesstate.jsonindex.db(state_changes 表)structured_relationshipsstate.jsonindex.db(relationships 表)progressstate.jsonstate.json (保留)protagonist_statestate.jsonstate.json (保留)strand_trackerstate.jsonstate.json (保留)disambiguation_*state.jsonstate.json (保留)从源码看这次迁移在IndexManagerwebnovel-writer/scripts/data_modules/index_manager.py的版本注释中留下了完整轨迹v5.1 引入entities、aliases、state_changes、relationships四张表替代 state.json 中的对应字段v5.3 新增追读力债务体系override_contracts、chase_debt、debt_events、chapter_reading_powerv5.4 新增invalid_facts无效事实追踪、tool_call_stats工具调用统计、review_metrics审查指标等表。可见index.db不仅是实体存储还承载了追读力、审查、可观测性等多维数据。四、双 Agent 架构Context Agent读与 Data Agent写在 v6 之前的写后主链中读写职责被拆分为两个 Agent中间以index.db state.json为数据中枢写作前: Context Agent 读取数据 → 组装上下文包 ├── 从 state.json 读取精简数据进度/配置 └── 从 index.db SQL 按需查询实体/关系 写作中: Writer 使用上下文包生成纯正文无 XML 标签 写作后: Data Agent 处理正文 → AI 提取实体 → 写入数据链 ├── 写入 index.db实体/别名/状态变化/关系 ├── 更新 state.json进度/主角快照 chapter_meta └── 写入 summaries/chNNNN.md章节摘要 Context Agent (读) ←→ index.db state.json ←→ Data Agent (写)这一架构的设计要点读写分离查询路径Context Agent与写入路径Data Agent互不耦合均可独立演进按需查询Context Agent 不再整份加载 state.json而是用 SQL 按需查询实体/关系控制 token 消耗纯正文生成Writer 生成的是无 XML 标签的正文结构化信息提取全部后置到 Data Agent避免污染成稿。对应到源码模块写入侧由SQLStateManagerwebnovel-writer/scripts/data_modules/sql_state_manager.py提供与旧StateManager兼容的高层接口——upsert_entity、record_state_change、upsert_relationship、get_protagonist、get_core_entities等底层委托IndexManager落库读取侧则由IndexManager的查询接口如get-entity、get-by-alias、get-state-changes、get-relationships支撑。五、每章数据链写后处理的 7 步完整流程文档给出的「每章数据链」是理解系统如何从章节正文沉淀为结构化记忆的关键共 7 步1. Context Agent 组装创作任务书 → 读取 state.json精简版进度/配置 → SQL 查询 index.db核心实体/按需实体 → RAG 检索相关场景 2. Step 1.5 章节设计 → 选开头/钩子/爽点模式避开最近3章 3. Writer 生成章节内容 → 2A 粗稿纯正文 → 2B 风格适配可选 4. 审查统一 reviewer agent → 设定一致性/时间线/叙事连贯/角色一致性/逻辑 五维度检查 → 输出审查报告 5. 网文化润色 → 基于审查报告修复问题 → 强化口感规则 6. Data Agent 处理数据链 → AI 实体提取替代 XML 标签解析 → 实体消歧置信度策略 → 写入 index.db实体/别名/状态变化/关系 → 更新 state.json进度/主角快照 chapter_meta → 写入 summaries/chNNNN.md章节摘要 → 向量嵌入 (RAG) → 风格样本评估 7. Git 备份强制流程要点解读第 1 步是读路径的完整展开state.json精简负责进度与配置index.dbSQL负责实体与关系vectors.dbRAG负责语义检索相关场景——三种数据源各司其职第 4 步的审查是五个维度设定一致性/时间线/叙事连贯/角色一致性/逻辑的机器检查审查报告是第 5 步润色的输入第 6 步是数据沉淀的核心AI 实体提取取代了早期的 XML 标签解析方案随后依次完成消歧、落库index.db、精简状态更新state.json、章节摘要summaries/chNNNN.md、向量嵌入与风格样本评估第 7 步强制 Git 备份保证每个章节都有可回滚的快照。文档同时提醒update_state.py用于手动/脚本化更新progress/protagonist_state/strand_tracker等字段主流程通常由 Data Agent 在处理数据链时同步推进进度手动脚本仅作为补充手段。六、state.json 精简结构 5KB 的轻量快照迁移后state.json只保留高频读取的精简数据文档给出了完整结构{ project_info: {title: , genre: }, progress: {current_chapter: N, total_words: W, current_volume: 1}, protagonist_state: { name: , power: {realm: , layer: 1, bottleneck: }, location: {current: , last_chapter: 0}, golden_finger: {name: , level: 1, skills: []} }, strand_tracker: { last_quest_chapter: 0, last_fire_chapter: 0, last_constellation_chapter: 0, current_dominant: quest, chapters_since_switch: 0, history: [] }, relationships: {}, plot_threads: {active_threads: [], foreshadowing: []}, world_settings: {}, disambiguation_warnings: [], disambiguation_pending: [], review_checkpoints: [], chapter_meta: {}, _migrated_to_sqlite: true }字段语义字段含义project_info书名与题材progress当前章节号、累计字数、当前卷号protagonist_state主角快照境界realm/layer/bottleneck、位置当前地点最近出场章节、金手指名称/等级/技能strand_tracker追读线切换记录上次任务线/爽点线/星座线的章节当前主导线、距上次切换章节数及历史relationships简化版关系完整关系在 index.dbplot_threads活跃线索与伏笔清单world_settings世界观骨架仅等级名/势力名/地名等轻量信息disambiguation_warnings/disambiguation_pending消歧警告与待人工确认队列review_checkpoints审查检查点chapter_meta章节元数据_migrated_to_sqlite迁移标记True 表示大数据已迁入 index.db文档强调entities_v3、alias_index、state_changes、structured_relationships 已迁移到 index.db不再存储在 state.json 中。这一精简策略与迁移脚本 webnovel-writer/scripts/data_modules/migrate_state_to_sqlite.py 中的slim_state构建逻辑完全一致world_settings只保留力量体系前 20 个等级名、前 30 个势力名、前 50 个地点名review_checkpoints只保留最近 10 个disambiguation_warnings保留最近 20 条、disambiguation_pending保留最近 10 条从而把整个文件压到 5KB 量级。七、index.db 表结构SQLite 主存储详解文档给出了index.db的核心表结构v5.1 引入的四张表这是理解整个投影层的基石-- 实体表 CREATE TABLE entities ( id TEXT PRIMARY KEY, type TEXT NOT NULL, -- 角色/地点/物品/势力/招式 canonical_name TEXT NOT NULL, tier TEXT DEFAULT 装饰, -- 核心/重要/次要/装饰 desc TEXT, current_json TEXT, -- JSON: {realm, location, ...} first_appearance INTEGER, last_appearance INTEGER, is_protagonist INTEGER DEFAULT 0, is_archived INTEGER DEFAULT 0 ); -- 别名表一对多 CREATE TABLE aliases ( alias TEXT NOT NULL, entity_id TEXT NOT NULL, entity_type TEXT NOT NULL, PRIMARY KEY (alias, entity_id, entity_type) ); -- 状态变化表 CREATE TABLE state_changes ( id INTEGER PRIMARY KEY AUTOINCREMENT, entity_id TEXT NOT NULL, field TEXT NOT NULL, old_value TEXT, new_value TEXT, reason TEXT, chapter INTEGER NOT NULL ); -- 关系表 CREATE TABLE relationships ( id INTEGER PRIMARY KEY AUTOINCREMENT, from_entity TEXT NOT NULL, to_entity TEXT NOT NULL, type TEXT NOT NULL, description TEXT, chapter INTEGER NOT NULL, UNIQUE(from_entity, to_entity, type) ); -- 原有表保留 CREATE TABLE chapters (...); CREATE TABLE scenes (...); CREATE TABLE appearances (...);各表设计意图entities实体主表tier四档核心/重要/次要/装饰用于区分重要度current_json以 JSON 存储实体当前状态境界/位置/物品等first_appearance/last_appearance记录首次与最近出场章节is_archived支持归档不活跃实体aliases别名表是一对多结构——同一别名可映射到多个实体主键为(alias, entity_id, entity_type)三元组同一别名指向多实体时靠entity_type区分详见第九节state_changes追加式状态变化流水field记录变化的字段如realmold_value/new_value记录前后值reason记录变化原因chapter记录发生章节——这是某角色在第 N 章时处于什么状态这类时序查询的数据基础relationships实体关系边UNIQUE(from_entity, to_entity, type)防止同类型关系重复插入chapter记录关系确立章节。对照源码 webnovel-writer/scripts/data_modules/index_manager.py 的_init_db实际建表还包含chapters章节元数据含 title/location/word_count/characters/summary、scenes场景索引含 start_line/end_line、appearances实体出场记录含 mentions/confidence、relationship_events关系事件时序流含 polarity/strength/evidence/confidence用于图谱与时间线回放以及 v5.3/v5.4 引入的override_contracts、chase_debt、debt_events、chapter_reading_power、invalid_facts、review_metrics、rag_query_log、tool_call_stats、writing_checklist_scores。文档中原有表保留的表述在源码中均有完整定义且每张表都配套了查询索引如idx_aliases_alias、idx_state_changes_entity、idx_relationships_from等保证按实体、按章节的查询路径高效。八、Data Agent AI 提取流程与实体消歧置信度策略v6 之前的主流程不再要求正文携带 XML 标签结构化信息由 Data Agent 智能提取文档给出 5 个步骤实体识别从正文语义识别角色/地点/物品/势力实体匹配优先匹配已有实体通过 alias_index消歧处理置信度 0.8: 自动采用置信度 0.5-0.8: 采用但记录 warning置信度 0.5: 标记待人工确认状态变化识别境界突破/位置移动/关系变化写入存储直接写入 index.db实体/别名/关系/状态变化。置信度阈值在配置层被固化为可调参数webnovel-writer/scripts/data_modules/config.py# 实体提取配置 extraction_confidence_high: float 0.8 extraction_confidence_medium: float 0.5实现层面EntityLinkerwebnovel-writer/scripts/data_modules/entity_linker.py的evaluate_confidence正是文档策略的代码化def evaluate_confidence(self, confidence: float) - Tuple[str, bool, Optional[str]]: if confidence self.config.extraction_confidence_high: return (auto, True, None) elif confidence self.config.extraction_confidence_medium: return (warn, True, f中置信度匹配 (confidence: {confidence:.2f})) else: return (manual, False, f需人工确认 (confidence: {confidence:.2f}))confidence 0.8→auto自动采用0.5 confidence 0.8→warn采用但附带警告可经DisambiguationResult.warning汇总为disambiguation_warningsconfidence 0.5→manual不采用进入disambiguation_pending待人工确认。lookup_alias/lookup_alias_all实现了一对多别名的匹配与按类型过滤process_extraction_result批量处理 AI 提取结果中的 uncertain 项并汇总警告。九、伏笔字段规范与 alias_index 一对多格式伏笔字段规范伏笔状态字段有严格的取值约束历史值需迁移对齐字段规范值兼容值历史status未回收/已回收待回收/进行中/active/pending推荐字段content伏笔内容、status状态、planted_chapter埋设章节、target_chapter回收目标章节、tier重要度。配套的紧急度计算参数同样定义在配置层webnovel-writer/scripts/data_modules/config.py# 伏笔紧急度 foreshadowing_urgency_pending_high: int 100 foreshadowing_urgency_pending_medium: int 50 foreshadowing_urgency_target_proximity: int 5 foreshadowing_urgency_score_high: int 100 foreshadowing_urgency_score_medium: int 60 foreshadowing_urgency_score_target: int 80 foreshadowing_urgency_score_low: int 20 foreshadowing_urgency_threshold_show: int 60即pending 状态的高/中档阈值100/50、距离目标章节的临近判定5 章内、紧急度分值档位100/60/80/20以及展示阈值≥60 才在报告中提示。这也解释了为什么文档示例中status -- --focus urgency能输出伏笔紧急度——status_reporter.py依赖的就是这套评分体系。alias_index 格式一对多{ 林天: [{type: 角色, id: lintian}], 天云宗: [ {type: 地点, id: loc_tianyunzong}, {type: 势力, id: faction_tianyunzong} ] }关键点同一别名可映射到多个实体如天云宗既是地点又是势力消歧时根据type或上下文判断。文档的错误纠正条目明确提醒alias_index 期望单对象是常见误区当前结构必须使用数组格式一对多。这一语义在 SQLite 的aliases表中通过(alias, entity_id, entity_type)联合主键得到等价表达。十、统一 CLI 查询实战webnovel.py 全命令速查文档附带的 examples 全部通过统一入口webnovel.py执行。该脚本webnovel-writer/scripts/webnovel.py本身只负责把scripts/目录加入sys.path并转发到data_modules.webnovel的main()真正的命令分派在 webnovel-writer/scripts/data_modules/webnovel.py其中PASSTHROUGH_TOOLS定义了index、state、rag、style、entity、context、memory、migrate、status、update-state、backup、archive、init、story-system、memory-contract、project-memory等转发工具所有写入类命令统一前置注入--project-root避免参数位置与引号问题。以下命令均以SCRIPTS_DIR指向脚本目录、PROJECT_ROOT指向书项目根目录必须包含.webnovel/state.json为前提。1. 查询当前进度cat $PROJECT_ROOT/.webnovel/state.json | jq .progress # 输出: { current_chapter: 45, total_words: 135000 }2. 查询实体SQLpython ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-entity --id xiaoyan # 输出: {id: xiaoyan, type: 角色, canonical_name: 萧炎, ...} python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-core-entities # 输出: 所有核心实体主角 tier核心/重要get-core-entities的筛选语义在IndexManager的查询接口中实现get-entities-by-type还可按角色/地点/物品/势力/招式类型过滤get-protagonist直接返回主角实体。3. 按别名查找实体一对多python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-by-alias --alias 天云宗 # 输出: [{id: loc_tianyunzong, type: 地点}, {id: faction_tianyunzong, type: 势力}]4. 查询状态变化python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-state-changes --entity xiaoyan --limit 10 # 输出: [{entity_id, field, old_value, new_value, reason, chapter}, ...]--limit默认为 20可通过参数调整返回条数。5. 查询关系python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index get-relationships --entity xiaoyan # 输出: [{from_entity, to_entity, type, description, chapter}, ...]进阶命令还包括get-relationship-graph --center id --depth 2 --format json|mermaid关系图谱可输出 mermaid 供可视化、get-relationship-timeline --a A --b B两实体关系时间线、get-relationship-events关系事件流支持--from-chapter/--to-chapter区间过滤。6. 检查伏笔紧急度python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT status -- --focus urgency注意status转发的是status_reporter.py参数前需加--分隔紧急度评分依据第九节的配置参数计算。7. 查询实体出场记录python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT index entity-appearances --entity lintian8. 迁移旧 state.json 到 SQLitepython ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT migrate -- --backup # 自动备份 state.json迁移数据到 index.db精简 state.json迁移脚本 webnovel-writer/scripts/data_modules/migrate_state_to_sqlite.py 的完整参数为--dry-run只分析不写入、--backup默认开启迁移前备份为state.json.backup-时间戳、--no-backup、--quiet迁移统计覆盖 entities/aliases/state_changes/relationships/skipped/errors 六项指标若存在错误则保留原字段不精简。补充更高层的知识查询v6 记忆编排在 v6 演进后webnovel-query 技能的查询流程webnovel-writer/skills/webnovel-query/SKILL.md进一步引入knowledge与memory-contract两组命令按查询类型选择最窄工具# 角色历史状态某实体在指定章节时的状态 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} knowledge query-entity-state --entity {entity_id} --at-chapter {N} # 实体关系某实体在指定章节时的所有关系 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} knowledge query-relationships --entity {entity_id} --at-chapter {N} # 世界规则 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} memory-contract query-rules --chapter {chapter_num} # 伏笔 / open loop python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} memory-contract get-open-loops # 仅综合 / 复杂查询需要时间线 长期记忆联合时才用 python -X utf8 ${SCRIPTS_DIR}/webnovel.py --project-root ${PROJECT_ROOT} memory-contract load-context --chapter {chapter_num}其中knowledge query-entity-state --at-chapter正是基于state_changes表的章节维度时序查询能力将本文第七节表结构与查询实践直接打通。十一、v6.0.0 演进Story System 合同树与真源优先级回到文档开头的警示——v6.0.0 之后写后主链已切换为 Story System.story-system/合同树MASTER_SETTING.json、volumes/*.json、chapters/*.json acceptedCHAPTER_COMMIT。.webnovel/投影层退居为查询视图。webnovel-query 技能按如下优先级定位写前真源 → 写后真源 → 投影层.story-system/MASTER_SETTING.json- 全书主设定题材、调性、核心禁忌.story-system/volumes/*.json- 卷级合同本卷目标、节奏策略.story-system/chapters/*.json- 章级合同本章焦点、动态上下文latest accepted.story-system/commits/chapter_XXX.commit.json- 写后事实已发布章节的定稿状态不可篡改memory-contract系列查询 - 记忆编排结果长期记忆、伏笔、时间线.webnovel/state.json/index.db- 投影层仅 fallback / read-model类比网文后台的角色卡、章节列表。也就是说写前真源1-3是作者开写前必须遵守的大纲、设定、禁区写后真源4是已发布章节的定稿状态投影层5-6是从写后真源自动生成的查询视图。当.story-system/合同与 accepted commit 缺失时SKILL.md 要求查询必须显式声明已降级到 legacy fallback。因此本文第七、八、九节介绍的 index.db 结构与消歧策略在当前架构中的正确定位是理解 read-model 的数据结构、支持快速检索的投影层而写后事实的权威来源以.story-system/为准。十二、常见错误规避清单文档 errors 段列出了实践中最高频的八类错误及正确做法整理如下这也是查询与初始化阶段判断数据是否健康的快速检查表❌ 常见错误✅ 正确做法伏笔状态写成待回收使用规范值未回收手工更新忘记加 planted_chapter脚本已自动补全归档路径混淆固定为.webnovel/archive/*.jsonalias_index 期望单对象当前结构使用数组格式一对多期望 XML 标签提取当前主流程由 Data Agent AI 自动提取使用旧版 data_modules.state_manager schema统一使用 entities_v3 结构后迁入 index.db entities 表仍从 state.json 读取 entities_v3改用 SQL 查询 index.db仍写入 state.json 大数据改用 SQLite 增量写入让 state.json 持续膨胀运行迁移脚本:python ${SCRIPTS_DIR}/webnovel.py migrate其中最后一条的完整写法是python ${SCRIPTS_DIR}/webnovel.py --project-root $PROJECT_ROOT migrate -- --backup迁移前自动备份、迁移后自动精简详见第十节。这套清单对维护一个 200 万字量级连载项目的数据健康至关重要——只要遵循大数据进 SQLite、小快照留 state.json、写后事实进 Story System的原则就不会重蹈 token 爆炸与数据割裂的覆辙。结语从.webnovel/目录约定、state.json 精简快照、index.db 表结构到双 Agent 读写架构、每章数据链与消歧置信度策略本文完整还原了 webnovel-writer 投影层数据流的全貌并给出了统一 CLI 的查询实战命令与 v6 Story System 演进后的真源优先级。对于希望理解该系统数据存在哪里、如何写入、如何查询的开发者或 Agent 而言system-data-flow.md连同其配套源码index_manager.py、sql_state_manager.py、entity_linker.py、migrate_state_to_sqlite.py构成了一套自洽、可验证的参考体系可作为排查数据问题、扩展查询能力或设计类似创作辅助系统时的直接范本。【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
