Webnovel Writer 写章失败排查手册从 projection_log 到 run_last.log 定位问题【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writerWebnovel Writer 是一个基于 Claude Code 的长篇网文 AI 写作辅助系统主打解决 AI 写作中的「遗忘」与「幻觉」问题支持 200 万字量级连载。当执行/webnovel-write写章失败时你只需按本手册的顺序排查最终报告 → doctor 体检 → projection_log.jsonl → commit.json → run_last.log五步定位问题根源并快速修复。先搞懂一次写章的证据都在哪里写章是一条六步流水线检查环境 → 整理写作依据 → 起草正文 → 写作检查 → 保存故事事实并提交 → Git 备份。任何一步失败系统都会留下对应的案发现场文件。 排查前先记住这 3 个核心日志文件都位于你的书项目根目录内文件位置记录内容投影日志.webnovel/projection_log.jsonl每次故事资料同步的执行记录追加写历史全保留事实提交.story-system/commits/chapter_{NNN}.commit.json本章是否正式入账accepted / rejected运行日志.webnovel/logs/run_last.log最近一次不可恢复故障的脱敏技术详情对应源码实现分别是 projection_log.py、chapter_commit_service.py 和 run_logger.py想了解字段细节可以直接翻源码。 一个核心概念.story-system/是故事主链的真源.webnovel/下的文件是从主链**投影projection**出来的读模型。所谓故事资料更新失败就是指投影环节出了问题。快速诊断先跑一次 /webnovel-doctor 体检遇到写章失败第一步永远建议运行只读体检命令不写入项目、不安装依赖/webnovel-doctor /webnovel-doctor --chapter 12它会按当前项目阶段检查并给出影响说明和修复建议包括✅ 项目骨架必备目录与文件是否齐全✅ 关键 JSON.webnovel/state.json、.story-system/MASTER_SETTING.json是否可解析✅ 数据库index.db、vector.db 表是否可读✅ RAG 配置embed / rerank 的 API key 是否已配置✅ 投影日志最新一次 projection 是否 done/skipped✅ Python 环境版本是否 ≥ 3.10aiohttp、filelock、pydantic 等依赖是否齐全体检逻辑见 doctor.py。报告里blocking项必须处理warning项按影响自行判断。读最终报告四种总状态决定排查方向每次写章结束都会输出一份作者友好报告实现见 user_report.py以一句总状态开头分三段说明产生的文件 / 遇到的问题 / 下一步建议。先看总状态总状态含义排查方向✅ 已完成产物与关键校验全部通过无需排查直接写下一章 部分完成主要产物已保留但有跳过项或待确认项看建议确认段落 需要你处理系统停在安全位置等你裁决按必须处理段落操作❌ 未完成关键产物没有可信生成进入下面的日志排查报告中的问题会按三级分类已自动处理如投影补跑成功、建议确认如新增角色名、必须处理如 commit rejected、projection failed。问题分类目录维护在 author_error_catalog.json。深入 projection_log.jsonl判断故事资料是否同步成功本章事实提交后系统会把本章更新投影到五类故事资料state/index/summary/memory/vector。每次投影执行都会向.webnovel/projection_log.jsonl追加一条 JSON 记录关键字段chapter章号排查时先按章号过滤记录status整体状态done/skipped正常pending等待中failed失败writers五个投影器各自的状态失败时看这个字段定位是哪个环节挂了commit_hash/commit_status对应的事实提交指纹与状态三种典型情形某条记录 statusfailed说明故事资料没同步完整dashboard、角色查询、伏笔追踪会读到旧数据。定位writers中 failed 的环节后补跑python -X utf8 插件目录/scripts/webnovel.py --project-root 项目根 projections retry --chapter 12statuspending 或缺失投影还没跑完或没跑。同样是补跑projections retry跨章批量重放用projections replay --from-chapter A --to-chapter B。历史记录里有 failed但最新一条是 done说明系统曾失败又自动补跑成功了这种情况报告会归入已自动处理无需干预只是核对时留意一下即可。命令细节见 commands.md投影写入流程见 postcommit.py。检查 commit.json本章事实到底入账没有打开.story-system/commits/chapter_{NNN}.commit.json看meta.statusaccepted本章事实正式进入故事主链 ✅rejected被拒。自动判定规则是blocking_count0、missed_nodes非空或pending非空时 rejected——通常意味着审查阻断问题未处理、章节目标节点没写完或存在未消歧的实体。处理对应问题后重新执行同一章的写章命令即可如果连 commit 文件都没生成说明流程卡在了提交前。用提交前关卡校验定位python -X utf8 插件目录/scripts/webnovel.py --project-root 项目根 write-gate --chapter 12 --stage precommit --format json关卡会明确报出正文缺失/为空、四份提交 artifactreview_results / fulfillment_result / disambiguation_result / extraction_result哪份缺失或 schema 不完整。关卡实现见 precommit.py。最后一道防线脱敏运行日志 run_last.log当报告总状态为未完成且上面的线索都不足以定位时查看.webnovel/logs/run_last.log。它由 run_logger.py 写入每条记录包含created_atUTC 时间戳判断是哪次运行留下的event事件名如write_failedpayload失败上下文章号、原因等API key、token、密码等敏感字段已自动脱敏为redacted可以安全地贴给他人协助排查注意它默认只保留最近一条记录新事件会覆盖旧事件所以故障发生后要第一时间查看。常见故障速查表故障现象先看哪里修复动作正文文件没生成最终报告必须处理段重新运行/webnovel-write {章号}会从断点继续审查结果缺失.webnovel/tmp/review_results.json重跑 Step 3 审查环节commit 状态 rejectedcommit.json 的判定依据处理 blocking 问题/补写目标节点后重新提交故事资料没更新projection_log.jsonl 的 writers 字段projections retry --chapter {章号}摘要/状态/记忆缺失projection_log.jsonl重跑 Step 5提交环节RAG 召回异常doctor 报告rag.*检查项在.env填好 embed/rerank 的 API keyPython 依赖报错doctor 报告python.*检查项python -m pip install -r scripts/requirements.txt重复跑同一章不确定从哪继续run-ledger write-resume按续跑建议执行不覆盖作者手改正文断点续跑说明重复执行同一章时系统会读取正文、审查结果、commit、projection 和备份状态只补跑失败步骤、不回退正文保留只从失败的环节继续。总结五步排查流程 看最终报告总状态与必须处理段80% 的问题这里就有答案 运行/webnovel-doctor --chapter {章号}做只读体检 打开.webnovel/projection_log.jsonl按章号找最新记录看status和writers 打开本章chapter_{NNN}.commit.json确认accepted还是rejected 仍无头绪时查看.webnovel/logs/run_last.log的脱敏技术详情写章流程的完整规范见 SKILL.md。记住系统的设计原则失败只补跑失败步骤不回退——只要你按顺序核对以上证据几乎总能找到卡点并一条命令恢复。【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考