基于 Claude Code 的长篇网文辅助创作系统，解决 AI 写作中的「遗忘」和「幻觉」问题，支持 200 万字量级 连载创作。
| 定律 | 说明 | 执行方式 |
|---|---|---|
| 大纲即法律 | 遵循大纲，不擅自发挥 | Context Agent 强制加载章节大纲 |
| 设定即物理 | 遵守设定，不自相矛盾 | Consistency Checker 实时校验 |
| 发明需识别 | 新实体必须入库管理 | Data Agent 自动提取并消歧 |
三线交织的叙事节奏控制：
| Strand | 含义 | 理想占比 | 说明 |
|---|---|---|---|
| Quest | 主线剧情 | 60% | 推动核心冲突 |
| Fire | 感情线 | 20% | 人物关系发展 |
| Constellation | 世界观扩展 | 20% | 背景/势力/设定 |
节奏红线：
- Quest 连续不超过 5 章
- Fire 断档不超过 10 章
- 每章至少包含 2 种 Strand
┌─────────────────────────────────────────────────────────────┐
│ Claude Code │
├─────────────────────────────────────────────────────────────┤
│ Skills (6个) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ init │ │ plan │ │ write │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ review │ │ query │ │ resume │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Agents (8个) │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Context Agent │ │ Data Agent │ │
│ │ (读取) │ │ (写入) │ │
│ └─────────────────┘ └─────────────────┘ │
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ 爽点 │ │ 一致性│ │ 节奏 │ │ OOC │ │ 连贯性│ │
│ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ │
├─────────────────────────────────────────────────────────────┤
│ Data Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │state.json│ │ index.db │ │vectors.db│ │
│ │ (状态) │ │ (索引) │ │ (向量) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Python | >= 3.8 | 数据处理脚本运行环境 |
| Claude Code | 最新版 | Anthropic 官方 CLI 工具 |
| Git | 任意版本 | 版本控制和章节备份 |
# 进入你的小说项目目录
cd your-novel-project
# 克隆插件到 .claude 目录
git clone https://github.com/lingfengQAQ/webnovel-writer.git .claude
# 安装 Python 依赖
pip install -r .claude/scripts/requirements.txtPython 依赖说明：
| 包名 | 用途 |
|---|---|
| aiohttp | 异步 HTTP 客户端，用于 Embedding/Reranker API 调用 |
| filelock | 文件锁，防止 state.json 并发写入冲突 |
# 在 Claude Code 中执行
/webnovel-init系统会引导你完成：
- 选择初始化模式（Quick/Standard/Deep）
- 选择题材类型
- 设计金手指/核心卖点
- 生成项目结构和设定模板
# 规划第1卷大纲
/webnovel-plan 1# 创作第1章
/webnovel-write 1# 审查第1-5章
/webnovel-review 1-5初始化项目结构、题材模板、世界观设定。
初始化模式：
| 模式 | 时间 | 内容 |
|---|---|---|
| ⚡ Quick | 5分钟 | 基础结构 + 核心卖点 |
| 📝 Standard | 15-20分钟 | + 金手指设计 + 题材模板 |
| 🎯 Deep | 30-45分钟 | + 深度世界观 + 创意验证 |
产出文件：
.webnovel/state.json- 项目状态设定集/- 世界观、力量体系、角色卡大纲/总纲.md- 故事框架
制定详细的卷大纲，规划爽点分布和节奏。
/webnovel-plan 1 # 规划第1卷
/webnovel-plan 2-3 # 规划第2-3卷产出：
大纲/第N卷-详细大纲.md- 每章目标、爽点设计、Strand 类型
- 新增实体预告
采用双 Agent 架构的自动化章节创作。
/webnovel-write 1 # 创作第1章
/webnovel-write 45 # 创作第45章创作流程：
Step 1: Context Agent 搜集上下文
↓
Step 2: 生成 3000-5000 字正文
↓
Step 3: 5 Agent 并行审查
↓
Step 4: 润色 + AI 痕迹检测
↓
Step 5: Data Agent 提取实体/更新索引
↓
Step 6: Git 自动提交备份
产出：
正文/第N章-标题.md- 章节末尾自动附加摘要
对已完成章节进行多维度深度扫描。
/webnovel-review 1-5 # 审查第1-5章
/webnovel-review 45 # 审查单章审查维度：
- 爽点密度与质量
- 设定一致性
- 节奏 Strand 分布
- 人物 OOC 检测
- 场景连贯性
查询角色、境界、伏笔、系统状态等运行时信息。
/webnovel-query 萧炎 # 查询角色信息
/webnovel-query 伏笔 # 查看待回收伏笔
/webnovel-query 紧急 # 查看紧急伏笔在任务中断时检测中断点并提供安全恢复选项。
/webnovel-resume恢复选项：
- 从断点继续
- 回滚到上一个安全点
- 重新开始当前步骤
职责：为写作准备精准的上下文
工作流程：
- 读取本章大纲，分析需要什么信息
- 从
state.json获取主角状态快照 - 调用
index.db(v5.1 schema) 查询相关实体和别名 - 调用 RAG 语义检索相关历史场景
- 搜索设定集获取相关设定
- 评估伏笔紧急度
- 组装上下文包 JSON
输出结构：
{
"core": {
"chapter_outline": "本章大纲",
"protagonist_snapshot": {...},
"recent_summaries": [...]
},
"scene": {
"location_context": {...},
"appearing_characters": [...],
"urgent_foreshadowing": [...]
},
"global": {
"worldview_skeleton": "...",
"power_system_skeleton": "...",
"style_contract_ref": "..."
},
"rag": [...],
"alerts": {
"disambiguation_warnings": [...],
"disambiguation_pending": [...]
}
}职责：从正文中语义化提取实体并同步状态
工作流程：
- 实体提取：识别角色/地点/物品/招式/势力
- 实体消歧：
- 高置信度 (>0.8)：自动采用
- 中置信度 (0.5-0.8)：采用但记录 warning
- 低置信度 (<0.5)：标记待人工确认
- 写入存储：更新
index.db(entities/aliases/state_changes) - 场景切片：按地点/时间/视角切分场景
- 向量嵌入：调用 RAG 存入向量库
输出格式：
{
"entities_extracted": [...],
"state_changes": [...],
"scenes": [...],
"warnings": [...],
"stats": {
"new_entities": 3,
"updated_entities": 2,
"scenes_created": 4
}
}| Checker | 检查内容 | 关键指标 |
|---|---|---|
| High-point Checker | 爽点密度与质量 | 6种执行模式、30/40/30结构 |
| Consistency Checker | 战力/地点/时间线 | 设定即物理定律 |
| Pacing Checker | Strand 比例分布 | Quest/Fire/Constellation |
| OOC Checker | 人物言行是否符合人设 | 角色卡片对照 |
| Continuity Checker | 场景转换流畅度 | 伏笔回收情况 |
| 模式 | 模式标识 | 典型触发 |
|---|---|---|
| 装逼打脸 | Flex & Counter | 嘲讽 → 反转 → 震惊 |
| 扮猪吃虎 | Underdog Reveal | 示弱 → 暴露 → 碾压 |
| 越级反杀 | Underdog Victory | 差距 → 策略 → 逆转 |
| 打脸权威 | Authority Challenge | 权威 → 挑战 → 成功 |
| 反派翻车 | Villain Downfall | 得意 → 反杀 → 落幕 |
| 甜蜜超预期 | Sweet Surprise | 期待 → 超预期 → 升华 |
- 每章：≥ 1 cool-point (任何单一模式)
- 每5章：≥ 1 combo cool-point (2种以上模式叠加)
- 每10章：≥ 1 milestone victory (改变主角地位的阶段性胜利)
混合检索系统，支持语义搜索历史场景：
查询 → [向量检索] + [BM25关键词] → RRF融合 → Rerank排序 → Top-K结果
| 组件 | 默认提供商 | 默认模型 |
|---|---|---|
| Embedding | ModelScope (魔搭) | Qwen/Qwen3-Embedding-8B |
| Reranker | Jina AI | jina-reranker-v3 |
# .env 文件
# Embedding 配置 (默认使用魔搭)
EMBED_API_TYPE=openai # openai 兼容接口
EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your-modelscope-token
# Reranker 配置
RERANK_API_TYPE=openai # openai (兼容 Jina/Cohere)
RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=jina_xxx- Context Agent 自动调用 RAG 检索相关历史场景
- Data Agent 自动将章节场景向量化存入数据库
- 支持失败重试（指数退避，最多3次）
系统内置 10+ 种热门网文题材模板：
| 题材 | 说明 |
|---|---|
| 修仙 | 境界体系、宗门体系、秘境夺宝 |
| 系统流 | 面板设计、任务系统、奖励机制 |
| 都市异能 | 隐藏实力、家族势力、权贵互动 |
| 规则怪谈 | 规则推理、恐怖氛围、反杀怪谈 |
| 替身文 | 五阶段心理线、追妻火葬场、身份反转 |
| 多子多福 | 后宫系统、子嗣养成、系统奖励 |
| 黑暗题材 | 吞噬进化、势力建立、压扬比例 |
| ... | 更多模板持续更新 |
# API 设置
embed_concurrency = 50 # 嵌入并发数
cold_start_timeout = 120 # 冷启动超时(秒)
normal_timeout = 30 # 正常超时(秒)
api_max_retries = 3 # 最大重试次数
api_retry_delay = 1.0 # 重试延迟(秒)
# 节奏红线
strand_quest_max_consecutive = 5 # Quest 最大连续章数
strand_fire_max_gap = 10 # Fire 最大断档章数
# 爽点密度
pacing_words_per_point = (1000, 2000) # 每个爽点字数范围
# 实体置信度
extraction_confidence_high = 0.8 # 高置信度阈值（自动采用）
extraction_confidence_low = 0.5 # 低置信度阈值（待确认）
# 上下文窗口
context_recent_summaries_window = 5 # 最近摘要数量
context_max_appearing_characters = 10 # 最大出场角色数
context_max_urgent_foreshadowing = 5 # 最大紧急伏笔数your-novel-project/
├── .claude/ # 插件目录
│ ├── agents/ # 8 个专职 Agent
│ │ ├── context-agent.md # 上下文包工程师
│ │ ├── data-agent.md # 数据链工程师
│ │ ├── high-point-checker.md
│ │ ├── consistency-checker.md
│ │ ├── pacing-checker.md
│ │ ├── ooc-checker.md
│ │ └── continuity-checker.md
│ ├── skills/ # 6 个核心 Skill
│ │ ├── webnovel-init/
│ │ ├── webnovel-plan/
│ │ ├── webnovel-write/
│ │ ├── webnovel-review/
│ │ ├── webnovel-query/
│ │ └── webnovel-resume/
│ ├── scripts/ # Python 脚本
│ │ ├── data_modules/
│ │ │ ├── index_manager.py # SQLite 索引管理 (v5.1)
│ │ │ ├── rag_adapter.py # RAG 检索层
│ │ │ ├── api_client.py # API 客户端
│ │ │ └── config.py # 配置管理
│ │ ├── context_pack_builder.py # 上下文包构建器
│ │ └── ...
│ ├── templates/ # 题材模板
│ │ └── genres/
│ │ ├── 修仙.md
│ │ ├── 系统流.md
│ │ ├── 替身文.md
│ │ ├── 多子多福.md
│ │ ├── 黑暗题材.md
│ │ └── ...
│ └── references/ # 写作指南
│ ├── strand-weave.md
│ ├── cool-points-guide.md
│ └── ...
├── .webnovel/ # 运行时数据
│ ├── state.json # 权威状态 (< 5KB)
│ ├── index.db # SQLite 索引
│ └── vectors.db # RAG 向量库
├── 正文/ # 章节文件
│ ├── 第1章-标题.md
│ └── ...
├── 大纲/ # 卷纲/章纲
│ ├── 总纲.md
│ ├── 第1卷-详细大纲.md
│ └── ...
└── 设定集/ # 世界观/角色/力量体系
├── 世界观.md
├── 力量体系.md
└── 角色/
└── ...
当 index.db 损坏或与实际数据不一致时：
# 重新处理单章
python -m data_modules.index_manager process-chapter --chapter 1 --project-root "."
# 批量重新处理
for i in $(seq 1 50); do
python -m data_modules.index_manager process-chapter --chapter $i --project-root "."
done
# 查看索引统计
python -m data_modules.index_manager stats --project-root "."当 vectors.db 损坏或嵌入模型更换时：
# 重新索引单章
python -m data_modules.rag_adapter index-chapter --chapter 1 --project-root "."
# 查看向量统计
python -m data_modules.rag_adapter stats --project-root "."每章自动创建 Git 标签，支持按章回滚：
# 查看章节标签
git tag | grep "ch"
# 回滚到第45章
git checkout ch0045- SQLite 存储：entities/aliases/state_changes 迁移到 index.db
- state.json 精简至 < 5KB
- API 重试机制（指数退避）
- 6 种爽点执行模式
- 双 Agent 架构 (Context + Data)
- 纯正文写作，无需 XML 标签
- 5 维并行审查
GPL v3 - 详见 LICENSE
本项目使用 Claude Code + Gemini CLI + Codex 配合 Vibe Coding 方式开发。
灵感来源：Linux.do 帖子
欢迎提交 Issue 和 PR！
# Fork 项目后
git checkout -b feature/your-feature
git commit -m "feat: add your feature"
git push origin feature/your-feature