Webnovel Writer: 基于 Claude Code 的长篇网文创作实战

难度: 中等 | 时长: 30 分钟 | 收获: 掌握用 AI Agent 系统进行长篇网文创作的核心方法

目标读者

1-5 年经验的开发者，对 AI Agent 感兴趣
想用 AI 辅助写作的网文作者
正在构建 AI 写作系统的工程师

核心依赖与环境

必需: Claude Code（最新版本）
语言: Python 3.10+
RAG: Embedding API（ModelScope）+ Rerank API（Jina）
可选: Node.js 18+（用于 Dashboard）

项目结构树

webnovel-writer/
├── .claude-plugin/
│   └── marketplace.json          # 插件市场配置
├── agents/                       # 8 个 Agent
│   ├── context-agent.md         # 创作任务书生成
│   ├── data-agent.md            # 实体与状态管理
│   ├── consistency-checker.md   # 设定一致性校验
│   ├── continuity-checker.md    # 叙事连贯性校验
│   ├── high-point-checker.md    # 爽点密度检查
│   ├── ooc-checker.md           # 人设偏离检查
│   ├── pacing-checker.md        # 节奏比例检查
│   └── reader-pull-checker.md   # 追读力检查
├── dashboard/                   # 可视化面板
│   ├── server.py                # Flask 后端
│   ├── watcher.py               # 文件监控
│   └── frontend/                # React 前端
├── genres/                      # 题材模板
│   ├── xuanhuan/               # 玄幻
│   ├── dog-blood-romance/      # 狗血虐恋
│   ├── period-drama/           # 古言
│   └── ...
├── skills/                      # Skills 定义
│   ├── init.md                  # 项目初始化
│   ├── plan.md                  # 大纲规划
│   ├── write.md                 # 正文写作
│   ├── review.md                # 章节审核
│   └── ...
└── docs/                        # 详细文档
    ├── architecture.md
    ├── commands.md
    └── rag-and-config.md

手把手步骤

Step 1: 安装插件

打开 Claude Code，执行以下命令安装插件：

claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user

TIP

如果只想在当前项目生效，将 --scope user 改为 --scope project。

Step 2: 安装 Python 依赖

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

这个命令会同时安装核心写作链路与 Dashboard 的所有依赖。

Step 3: 初始化小说项目

在 Claude Code 中执行：

/webnovel-init

系统会提示你输入书名，然后在当前 Workspace 下创建项目目录，并在 workspace/.claude/.webnovel-current-project 中写入当前项目指针。

Step 4: 配置 RAG 环境（必做）

进入初始化后的书项目根目录，创建 .env 文件：

cp .env.example .env

编辑 .env，填入你的 API 配置：

# Embedding 模型（用于向量检索）
EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key

# Rerank 模型（用于结果重排）
RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_rerank_api_key

WARNING

RAG 配置是必做项，否则无法使用上下文检索功能，写作时 AI 会"失忆"。

Step 5: 开始创作

现在你可以开始写作了：

# Step 5a: 规划大纲
/webnovel-plan 1

# Step 5b: 写作第 1 章
/webnovel-write 1

# Step 5c: 审核第 1-5 章
/webnovel-review 1-5

每个命令的执行逻辑：

命令	说明
`/webnovel-plan N`	生成 N 章的大纲
`/webnovel-write N`	写作第 N 章正文
`/webnovel-review N-M`	审核第 N 到 M 章

Step 6: 启动可视化 Dashboard（可选）

/webnovel-dashboard

Dashboard 提供以下功能：

项目状态总览
实体图谱可视化
章节/大纲浏览
追读力指标查看

TIP

Dashboard 是只读面板，前端构建产物已随插件发布，无需本地 npm build。

（可选）Step 7: 自定义 Agent 模型

本项目所有内置 Agent 默认使用 inherit（继承当前 Claude 会话模型）。如果你想单独指定某个 Agent 的模型，编辑对应文件的 frontmatter：

---
name: context-agent
description: 生成创作任务书
tools: Read, Grep, Bash
model: sonnet  # 指定使用 Sonnet 模型
---

常见可选值：inherit / sonnet / opus / haiku。

核心架构解析

防幻觉三定律

Webnovel Writer 用三定律从根本上解决 AI 写作的"幻觉"问题：

定律	说明	执行方式
大纲即法律	严格遵循大纲，不擅自发挥	Context Agent 强制加载章节大纲
设定即物理	遵守所有设定，不自相矛盾	Consistency Checker 实时校验
发明需识别	新实体必须入库管理	Data Agent 自动提取并消歧

双 Agent 架构

系统采用经典的「读-写分离」架构：

Context Agent（读）

在写作前构建"创作任务书"
加载本章上下文、约束条件、追读力策略
确保 AI 知道"要写什么"和"不能写什么"

Data Agent（写）

从正文中提取实体与状态变化
自动更新 state.json、index.db、vectors.db
保证数据链闭环，让后续章节能"记得"前面发生的事

六维并行审查

每章写完后，会同时启动 6 个 Checker 进行审查：

Checker	检查重点
High-point Checker	爽点密度与质量
Consistency Checker	设定一致性（战力/地点/时间线）
Pacing Checker	Strand 比例与断档（Quest 60% / Fire 20% / Constellation 20%）
OOC Checker	人物行为是否偏离人设
Continuity Checker	场景与叙事连贯性
Reader-pull Checker	钩子强度、期待管理、追读力

Strand Weave 节奏系统

系统内置节奏控制机制：

Quest（主线剧情）：理想占比 60%，连续不超过 5 章
Fire（感情线）：理想占比 20%，断档不超过 10 章
Constellation（世界观扩展）：理想占比 20%，断档不超过 15 章

常见问题排查

Q1: RAG 配置后仍然无法检索

症状: 执行写作时提示 "no results from RAG"

排查:

确认 .env 文件在项目根目录
检查 API Key 是否正确
尝试手动调用 Embedding API 验证连通性

curl -X POST $EMBED_BASE_URL \
  -H "Authorization: Bearer $EMBED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "测试文本"}'

Q2: 写作时模型调用超时

症状: /webnovel-write 执行很久后报错 timeout

排查:

检查网络到 API 服务商是否稳定
尝试换成更快的模型（如 Haiku）
在 Agent 配置中增加 timeout 参数

Q3: 状态文件损坏

症状: state.json 或 index.db 报错 "invalid json" 或 "database locked"

排查:

备份当前文件
运行项目自带的恢复脚本（见 docs/operations.md）
手动修复 JSON 格式错误

Q4: Dashboard 启动失败

症状: /webnovel-dashboard 无响应或报错

排查:

确认 Python 依赖已完整安装
检查端口 5000 是否被占用
查看日志输出具体错误信息

Q5: Agent 模型不生效

症状: 修改了 Agent 的 model 配置但没生效

排查:

确认修改的是正确的 Agent 文件
检查 YAML 格式是否正确（冒号后有空格）
重启 Claude Code 会话

Q6: 追读力检查总是失败

症状: Reader-pull Checker 提示"钩子不够强"

排查:

检查本章结尾是否有悬念设置
是否留下明确的"坑"待填
是否缺少对下一章的期待引导

扩展阅读 / 进阶方向

1. 自定义题材模板

项目内置了多种网文题材模板（玄幻、古言、狗血虐恋等），你可以在 genres/ 目录下添加自己的题材配置。

2. 与 OpenClaw 集成

Webnovel Writer 可以作为 OpenClaw 的 Skill 使用，实现更强大的自动化创作流程。

3. 深度定制 Agent

通过修改 agents/*.md 文件的 prompt 和 tools，你可以让 AI 按照你的个人风格写作。

4. 多模型混合使用

尝试用不同模型处理不同任务：用 Opus 写正文，用 Haiku 做审查，用 Sonnet 做规划。