上一篇我们从使用者视角讲了它怎么防止设定崩坏，这一篇往下钻一层，看 lingfengQAQ/webnovel-writer 内部那条「合同 → 起草 → 审查 → 提交 → 投影」的链是怎么搭起来的。如果你只是想先把插件装起来用，完整插件清单与汉化避坑指南 里有更省事的入口；下面这些内容更偏向愿意读源码、或者打算照着它的思路自建一套的人。
先给一个坐标：仓库 7164 Star、站点综合分 72.2、GPL v3 许可、最近上游提交 2026/9/22，Story System 自 v6.0.0 起成为默认主链。
一、合同先行：runtime contract 约束的是什么
多数写作工具的顺序是"先写，再总结"。Story System 把顺序倒了过来：动笔之前先落一份合同。
这一步在 /webnovel-write 的九步里是第 2 步。它之所以放在起草之前，是因为它要回答"这一章允许出现什么"：本章承接哪些既有设定、哪些实体已经存在、哪些约束不能违反。有了合同，审查才有可判定的依据；没有合同，"审查"只能靠印象打分。
.story-system/ 是唯一的事实源头，这份合同就落在其中——它不是缓存，是账本。
二、审查环节：blocking issue 是一种阻断协议
第 5 步调用 reviewer 做多维审查，其中最需要理解的是 blocking issue：它不是一个更严重的"警告"，而是一条阻断协议——blocking issue 不通过，这一章就走不下去。
这带来两个工程上的后果。其一，未通过审查的章节不会进入第 7、8 步，也就没有机会把可疑的"事实"写进账本。其二，它可以被安全地中断重来：因为第 8 步尚未执行，重跑这一章不会留下一半入账、一半没入账的脏状态。
第 6 步的润色、排版与 Anti-AI 终检排在审查之后，说明这套设计的取舍是先保证对不对，再打磨好不好。
三、data-agent 与 CHAPTER_COMMIT：事实怎么入账
第 7 步调 data-agent 提取事实。它的职责边界很窄：从这一章的正文里把新增或变更的事实抽出来，为下一步准备数据。它不负责判断写得好不好，也不负责决定要不要接受这一章。
第 8 步才是入账：生成 CHAPTER_COMMIT，并以此驱动 state index summary memory vector 五路投影。关键点在于 accepted 的 CHAPTER_COMMIT——只有它被接受，新事实才算正式进入系统。在此之前，派生视图里看到的一切都不代表"已确认的事实"。
四、五路投影：CHAPTER_COMMIT 之后发生什么
一次提交要扇出到五个下游：
| state | .webnovel/state.json，当前项目状态 |
| index | .webnovel/index.db，结构化索引 |
| summary | .webnovel/summaries/，章节摘要 |
| memory | .webnovel/memory_scratchpad.json，长期记忆 |
| vector | 向量检索侧的数据 |
这五路全部是派生视图，只读。这一点决定了排查方式：视图之间对不上时，不要去修视图，而要回到主链核对。.webnovel/projection_log.jsonl 就是为此准备的——它是投影执行日志，逐条记录每一路是否跑过，用来定位是哪一路没有同步。
五、判据：projection_status 什么时候算干净
官方给的排查顺序是先跑 preflight 与 doctor –format text，然后看三件事：
story_runtime.mainline_ready 是否为 true
.story-system/commits/chapter_XXX.commit.json 是否存在，且为 accepted
projection_status 是否全部为 done 或 skipped
第三条是这里最容易误读的一条。判据是"全 done 或 skipped"，而不是"全 done"——也就是说「这一路本来就不需要跑」和「这一路已经跑完」同样算通过。判断某一路是否异常时，如果只盯着 done 的数量，会把 skipped 错误地算成缺漏。
真正的故障形态是：CHAPTER_COMMIT 已经生成，但某一路投影没跑完。此时面板往往表现为状态、索引、摘要互相对不上或显示不全。
六、重放与补跑：projections 子命令
定位到缺失的那一路之后，处理方式是补齐而不是重建。CLI 提供 projections 子命令来做补跑或重放：投影是由主链派生的确定性过程，所以重放一份提交不会改变事实，只是把缺失的视图重新算出来。
这也解释了为什么派生视图可以被放心删掉重建——它们不承载唯一信息。反过来，COMMIT 文件本身是账本记录，不要为了"重来一遍"去手工删除它。
七、观察入口：write-gate 与 CLI
写章流程里有几个天然的分界点，write-gate 把它们单独暴露出来，用来判断当前这一步能不能继续往下走。对照九步流水线，这些分界大致对应：预检能否开工、审查是否被 blocking issue 阻断、提交与投影是否已完成。把边界显式化的好处是每段工作各自独立——第 6 步的重排不会牵动第 8 步，第 8 步的重放也不会倒回去改正文。
日常排查用得到的常用子命令包括：where、preflight、project-status、doctor、write-gate、projections、story-system、chapter-commit、story-events、memory、rag、status。统一入口是：
python -X utf8 "<插件路径>/scripts/webnovel.py" –project-root "<书项目根>" <子命令>
按用途粗分一下：定位项目与环境用 where；开工前体检用 preflight 与 doctor；看主链与运行状态用 project-status 与 story-system；处理提交与投影用 chapter-commit 与 projections；查历史事实与记忆用 story-events 与 memory；检索侧调优用 rag。
另外，/webnovel-dashboard 是只读可视化面板，用来看项目状态、实体关系图、章节内容、伏笔与追读力数据。它的前端 dist/ 随插件发布，本地不需要跑 npm build；只有改前端源码时才进 dashboard/frontend/ 执行 npm install 与 npm run dev。
总结
这条链的设计要点可以压成一句话：把事实的写入收敛到一次可审查、可接受、可重放的提交上，其余全是可重建的投影；想对照同类插件的中文清单与安装形态见 完整插件清单与汉化避坑指南。
适合与不适合
适合：打算照着这套思路自建写作流水线的工程师；正在排查派生视图对不上、想搞清楚该看哪个日志的人；需要把长篇创作的中间状态做成可审计记录、愿意读 CLI 手册的开发者；用 Claude Code 并按官方路径安装 v6 的用户。
不适合：不打算读源码、只想让模型直接出一章的人——这套机制的全部价值建立在"每章都走合同、审查、提交、投影"的前提上，抄一半反而更慢；指望它是一套稳定 API 的产品团队——v7 已冻结未发布、v8 仍是源码预览，且官方明确没有经过验证的旧书仓迁移方案；此外 RAG 侧要自备 Embedding 与 Rerank 服务的 Key，不填会退回 BM25 关键词检索，语义召回明显偏弱。
标签：webnovel-writer、DeepSeek Harness、Story System、章节提交与投影
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。
