Webnovel Writer SQLite 迁移指南state.json 迁移到 SQL 的状态管理演进【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer一文讲清 Webnovel Writer 的 state.json 迁移到 SQLite 状态管理演进在长篇网文创作中AI 系统最怕的就是遗忘和幻觉。Webnovel Writer 是基于 Claude Code 的长篇网文辅助创作系统支持 200 万字量级连载创作其中SQLite 迁移是它解决状态文件膨胀问题的关键演进把state.json里不断增长的实体、别名、状态变化、关系数据一次性迁移到 SQLite 数据库index.db中让状态管理从一个大 JSON升级为JSON SQL 分层存储。本文面向新手用户用最短的篇幅讲清楚三件事为什么要迁移、怎么一键迁移、迁移后如何验证。为什么要迁移state.json 为什么会爆炸 在早期版本中Webnovel Writer 把故事的所有运行时状态都存在一个 JSON 文件里包括数据类型早期存储位置迁移后位置实体角色/地点/物品/势力/招式entities_v3state.jsonindex.dbentities 表别名索引alias_indexstate.jsonindex.dbaliases 表状态变化state_changesstate.jsonindex.dbstate_changes 表结构化关系structured_relationshipsstate.jsonindex.dbrelationships 表进度、主角状态、节奏追踪器等state.jsonstate.json保留写 20 章之后state.json会迅速膨胀到几十甚至上百 KB每次写作前都要把它整体读进上下文token 消耗爆炸、写作变慢、还更容易让 AI 迷失在海量数据里。SQLite 迁移的核心思路是大数据进 SQL小数据留 JSONindex.dbSQLite存会无限增长的结构化数据——实体、别名、状态变化、关系支持按需 SQL 查询比如只查主角当前境界不用加载整个文件。state.json精简后 5KB只保留写作前必须快速读取的精简数据——进度、主角快照、Strand Weave 节奏追踪、消歧告警等。迁移完成后state.json中会写入_migrated_to_sqlite: true标记后续流程会自动走 SQL 读写路径不再让文件持续膨胀。详细的数据结构说明见官方文档system-data-flow.md整体架构见 overview.md。一键迁移步骤三步完成 state.json 迁移 迁移工具是项目内置的 migrate_state_to_sqlite.py它做了四件事自动备份迁移前先把state.json复制为带时间戳的备份文件state.json.backup-YYYYmmdd_HHMMSS出问题随时可回滚四类数据入 SQL把entities_v3、alias_index、state_changes、structured_relationships逐条写入index.db对应数据表底层由 sql_state_manager.py 与 index_manager.py 完成失败即中止只要出现迁移错误就保留原字段不做精简保证数据不丢精简 state.json用原子写入生成精简版状态文件并打上迁移标记。第一步先做 dry-run 演练推荐新手先做只分析、不实际写入先看看有多少条数据会被迁移python webnovel.py --project-root . migrate -- --dry-run第二步正式执行迁移默认自动备份确认演练结果没问题后执行正式迁移python webnovel.py --project-root . migrate -- --backup运行结束后会打印一份迁移统计实体数、别名数、状态变化数、关系数、跳过数、错误数。只要错误为 0迁移即成功state.json会被精简到 5KB 以内。第三步验证迁移结果python webnovel.py --project-root . index get-core-entities能查到主角和核心角色说明 SQL 数据链路正常再确认一下state.json里出现了_migrated_to_sqlite: true标记即可。不想手动敲命令直接使用/webnovel-query技能让系统智能体帮你查询进度、实体和状态变化详见 SKILL.md。迁移后状态管理如何分工协作 迁移完成后Webnovel Writer 的状态管理进入JSON SQL 双存储模式由两个模块分工协作state_manager.py管理精简版state.json的读写进度、主角状态、节奏追踪同时把实体类大数据同步写入 SQLite保证两个存储源始终一致sql_state_manager.py提供与旧接口兼容的 SQL 写入/查询接口——upsert_entity()写实体、record_state_change()记状态变化、upsert_relationship()记关系、get_protagonist()等按需查询。这样Context Agent 写作前只需从state.json拿精简配置、从index.db按需查实体不再需要整文件加载Data Agent 写作后增量写入 SQLstate.json永远保持轻量。整个读写分工流程可在 system-data-flow.md 中查看。常见问题与注意事项 ⚠️Q1新项目需要手动迁移吗不需要。v5.1 之后的初始化流程会直接创建精简的state.json并同步使用 SQLite只有使用旧版本创建的老项目才需要跑一次迁移。Q2迁移失败了怎么办迁移脚本是失败即中止设计只要有任何一条数据迁移出错state.json的原字段会完整保留不会精简再加上默认自动备份直接重新执行即可。官方也为此准备了完整的自动化测试 test_migrate_state_to_sqlite.py覆盖缺失文件、正常流程、错误保留等场景。Q3迁移后旧数据还能查吗能。所有数据都在index.db里通过统一 CLI 查询python webnovel.py --project-root . index get-entity --id xiaoyan python webnovel.py --project-root . index get-state-changes --entity xiaoyan --limit 10Q4world_settings等大字段去哪了world_settings会被自动瘦身力量体系只保留等级名称最多 20 个、势力只保留名称与类型最多 30 个、地点只保留名称最多 50 个骨架信息仍在state.json中细节以设定集文件为准。总结从 JSON 到 SQLite 的演进价值 ✅文件更小state.json从几十上百 KB 精简到 5KB 以内上下文占用骤降查询更快实体、关系、状态变化全部 SQL 化按需查询代替全量加载写入更安全增量 upsert 原子写入 自动备份迁移零风险架构更清晰JSON 管当下SQL 管历史为 200 万字长篇连载打下数据基础。如果你想进一步了解 Webnovel Writer 的整体设计推荐阅读 架构总览 与 命令指南迁移相关的完整实现位于 data_modules/ 目录欢迎深入探索。【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
