Webnovel Writer 数据层设计揭秘：state.json、index.db 与 vectors.db 三库分工全解析
【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统，解决 AI 写作中的「遗忘」和「幻觉」问题，支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer
Webnovel Writer 是一款基于 Claude Code 的长篇网文辅助创作系统，用 state.json、index.db、vectors.db 三层存储分工协作，解决 AI 写作中的遗忘与幻觉问题，支持 200 万字量级连载。
为什么长篇网文 AI 写作要先解决「记忆」问题
写 200 万字网文，最大的敌人不是灵感，而是记忆。写到第 300 章时，AI 很容易把主角的境界写错、把伏笔忘了回收、甚至编出没设定过的新设定。
Webnovel Writer 的思路很直接：把故事的全部事实拆成三层存储，各司其职——
| 存储 | 角色 | 一句话定位 |
|---|---|---|
state.json | 仪表盘 | <5KB 精简状态：进度、主角快照、节奏追踪 |
index.db | 结构化主库 | SQLite：实体、别名、关系、状态变化 |
vectors.db | 语义检索引擎 | 向量 + BM25 混合检索，按需找回旧场景 |
三者都位于项目的.webnovel/目录下，完整目录约定见 system-data-flow.md，架构总览见 overview.md。
state.json：小于 5KB 的「仪表盘」
早期版本里，实体、关系、状态变化全都塞在 state.json 里，结果 20 章之后文件爆炸，token 成本飙升。于是团队做了一个关键架构决策：把大数据迁出，state.json 只留「最常读、体积小」的状态。
现在它只保留这些高频字段：
- progress：当前章节、总字数、卷进度
- protagonist_state：主角境界、位置、金手指快照
- strand_tracker：主线/感情线/世界观线的节奏追踪
- chapter_meta：每章的钩子类型、开场模式，避免连续重复套路
- disambiguation_pending：待人工确认的消歧记录
完整字段说明见 state-schema.md。它被刻意压到5KB 以内，Context Agent 每章都可以全量读入，几乎零成本。
index.db：SQLite 主存储，实体关系全在这里
index.db承担了原本 state.json 里最膨胀的几块数据，核心表结构如下：
| 表 | 存什么 | 解决的痛点 |
|---|---|---|
entities | 角色/地点/物品/势力/招式，含当前状态 JSON | 主角境界、位置不再散落在各章 |
aliases | 别名一对多映射（如「天云宗」→地点+势力） | 同名实体自动消歧 |
state_changes | 字段变更流水：旧值→新值+章节号 | 任何变化都可审计回溯 |
relationships | 实体间关系图谱 | 人物关系网不丢失 |
chapters/scenes/appearances | 章节元数据与出场记录 | 快速查询「谁在第几章出场」 |
此外还有追读力债务、审查指标等运营型表（v5.3/v5.4 引入）。表结构文档见 index-schema.md。
它的读接口由 index_manager.py 统一管理，写入则走 sql_state_manager.py 的增量写入。SQLite 让按需查询成为可能——不需要把几千个实体全塞进上下文，一句 SQL 就能只取核心角色。
老项目可以通过一条命令完成迁移，自动备份旧 state.json 再精简：
python webnovel-writer/scripts/webnovel.py migrate --backup实现见 migrate_state_to_sqlite.py。
vectors.db：向量 + BM25 混合检索，把 200 万字「装回」上下文
结构化数据解决「是什么」，但「第 47 章那场雨夜戏是怎么写的」这类问题，需要语义检索。
vectors.db由 rag_adapter.py 管理，内部有两张关键表：
- vectors 表：章节切块（chunk）+ 向量嵌入，支持语义相似度搜索
- bm25_index 表：倒排索引，支持关键词精确匹配
查询时走混合检索：向量和 BM25 并行召回，用 RRF 融合排序，再经 rerank 精排取 Top 结果。这样「语义相近」和「精确命中」各占一半，检索质量远超单一方式。
检索配置（Top-K、超时、降级策略等）集中在 config.py，API 接入方法见 rag-and-config.md。更妙的是：即使嵌入 API 不可用，BM25 索引仍能让关键词检索正常工作——这是典型的优雅降级设计。
一条单向数据链：谁在读，谁在写
三库不是各自为政，而是嵌在一条清晰的读写链里：
写作前—— Context Agent 全量读 state.json（便宜），SQL 按需查 index.db（精准），RAG 检索 vectors.db（兜底），组装出本章「创作任务书」。
写作后—— Data Agent 从正文提取 accepted 提交物，驱动投影写入器一次性更新：index.db（新实体/关系/状态变化）→ state.json（进度/主角快照）→ summaries（章节摘要）→ vectors.db（向量嵌入）。
💡 这套分工背后是明确的「真源」原则：
.story-system/合同树是写后主链真源，而 state.json、index.db、vectors.db 都是它的投影/read-model——可以随时重建，永不与正文打架。
快速自检：三库健康度怎么看
用内置状态报告即可检查三者是否正常生成：
python webnovel-writer/scripts/webnovel.py status若 state.json 意外膨胀（比如手动塞了实体数据），跑一次migrate就能收回 SQLite。日常维护命令清单见 commands.md。
小结：三库分工是「不遗忘」的工程底座
- state.json：小到能全量读，负责「现在到哪了」
- index.db：结构化可查询，负责「设定是什么、变了没」
- vectors.db：语义可检索，负责「以前写过类似的吗」
三者配合，让 AI 在 200 万字连载里既不遗忘、也不幻觉——这正是 Webnovel Writer 数据层设计的精髓。
【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统，解决 AI 写作中的「遗忘」和「幻觉」问题，支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
