Webnovel Writer

写网文，第一章容易，写到第二百章还能不崩盘，很难。

角色动机突然漂移、战力体系前后矛盾、伏笔写了忘了回收、时间线错乱……这些是长篇连载作者的噩梦。当引入 AI 辅助创作时，这个问题被放大了：大多数 AI 工具是“一次性生成器”，写完即忘，缺乏对长篇故事全局状态的持续记忆和约束。

Webnovel Writer 不是一个简单的文本生成插件，而是一套运行在 Claude Code 上的长篇网文一致性系统。它的核心目标很明确：让 AI 在创作数百章的过程中，依然记得住设定、接得住伏笔、守得住大纲。

目前，该项目的下一代 v7 设计已进入公开意见征集期（RFC），开发者欢迎社区通过 GitHub Discussions #118 或 Issue #119 提供反馈。

为什么需要一套“一致性系统”？

长篇创作的核心难点不在于单章的文笔，而在于长期记忆的维护。随着章节增加，以下要素必须保持严格一致：

• 角色逻辑：人物动机不能无故改变，性格不能 OOC（Out Of Character）。
• 世界观规则：战力等级、地理环境、魔法/科技规则不能互相打架。
• 剧情脉络：伏笔必须有登记、有推进、有回收；爽点和感情线的节奏需可控。
• 事实沉淀：每章发生的新情节，必须转化为可检索的结构化数据，供后续章节调用。

Webnovel Writer 将上述约束转化为 Claude Code 可自动执行的标准化步骤：动笔前查资料 -> 写作中受约束 -> 写完后审事实 -> 状态同步入库。它不只是“会写”，更是“边写边攒”，确保故事资产不断累积而非流失。

核心工作流：从初始化到可视化面板

Webnovel Writer 提供了一套完整的命令集，覆盖创作全生命周期：

独特的“Story System”架构

在 v6.0.0 版本中，系统引入了 Story System 作为唯一的事实源头：

• .story-system/：存储“合同”（创作前的约定）和“章节提交”（写完后的事实审计）。
• 派生视图：.webnovel/state.json、index.db、summaries/ 等均为只读视图，由主链派生，用于查询和展示。
• 投影日志：projection_log.jsonl 记录状态同步过程，便于排查 state、index、memory 等不同步的问题。

这种设计确保了“怎么写”（文笔发挥）与“写了什么”（事实登记）的分离。文笔可以灵活多变，但发生过的事实必须经过审核、存档，成为后续创作的可靠依据。

严谨的写章流水线

执行 /webnovel-write 并非简单调用模型生成文本，而是一条带有多重关卡的自动化流水线：

1. 预检：检查项目根目录、占位符及 Story System 健康状态。
2. 刷新合约：更新本章的 runtime contract（运行时约束）。
3. 生成任务书：调用 context-agent 生成具体的写作任务指引。
4. 起草正文：根据任务书进行内容创作。
5. 多维审查：调用 reviewer 进行审查，若存在 blocking issue（阻断性问题）则中断流程。
6. 润色与终检：进行排版优化及 Anti-AI 风格检测。
7. 事实提取：调用 data-agent 从正文中提取关键事实。
8. 状态投影：生成 CHAPTER_COMMIT，驱动 state、index、summary、memory、vector 等模块同步更新。
9. 自动备份：执行章节级备份，确保数据安全。

面向作者的最终报告

每个主要命令执行结束后，系统不会抛出晦涩的代码日志，而是提供一份清晰的最终报告：

• 总状态：已完成 / 部分完成 / 需要你处理 / 未完成。
• 产物清单：列出产生的文件及完成情况。
• 问题与耗时：记录过程中遇到的异常及自动处理项。
• 下一步建议：指导用户进行后续操作。

只有在涉及创作方向抉择、事实一致性冲突或文件覆盖风险时，系统才会暂停并请求用户裁决。重复执行同一命令时，系统会利用可信断点续传，避免重复劳动。

快速上手指南

1. 安装插件

通过 Claude Code Marketplace 安装（用户级或项目级）：

# 用户级安装
claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user

# 项目级安装（仅当前项目生效）
claude plugin marketplace add lingfengQAQ/webnovel-writer --scope project

2. 安装 Python 依赖

python -m pip install -r https://raw.githubusercontent.com/lingfengQAQ/webnovel-writer/HEAD/requirements.txt

3. 初始化项目

在 Claude Code 中输入 /webnovel-init，按指引完成问答后，系统将创建如下目录结构：

project-root/
├── .story-system/        # 合同、章节提交和事件审计
├── .webnovel/            # 状态、索引、摘要、备份和长期记忆
├── 正文/                  # 章节正文
├── 大纲/                  # 总纲、卷纲、时间线和章纲
├── 设定集/                # 世界观、角色、力量体系等设定
└── 审查报告/              # 章节审查报告

4. 配置 RAG（检索增强生成）

复制 .env.example 为 .env 并填写 API Key。最小配置示例：

EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key

RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_rerank_api_key

注：若不配置 Embedding Key，系统将自动退回到 BM25 关键词检索，虽可用但语义召回效果较弱。支持任何兼容 OpenAI 格式的接口。

5. 开始创作

/webnovel-plan 1      # 规划第 1 卷
/webnovel-write 1     # 写第 1 章
/webnovel-review 1-5  # 审查第 1-5 章
/webnovel-query 伏笔  # 查询伏笔状态
/webnovel-dashboard   # 打开可视化面板

Dashboard 前端已预先打包，无需本地运行 npm build，即可直观查看实体关系图、追读力数据等项目状态。

丰富的题材支持

内置 37 个中文网文题材模板，支持单一题材或混合题材创作：

• 玄幻修仙类：修仙、系统流、高武、西幻、无限流、末世、科幻
• 都市现代类：都市异能、日常、脑洞、现实题材、电竞、直播文
• 言情类：古言、宫斗宅斗、青春甜宠、豪门总裁、狗血言情、替身文、种田
• 特殊题材：规则怪谈、悬疑脑洞、灵异、历史古代、抗战谍战、知乎短篇、克苏鲁等