Webnovel Writer

# Webnovel Writer

[![License](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-purple.svg)](https://claude.ai/claude-code)

基于 Claude Code 的长篇网文辅助创作系统，解决 AI 写作中的「遗忘」和「幻觉」问题，支持 **200 万字量级** 连载创作。

---

## 目录

- [核心理念](#核心理念)
- [系统架构](#系统架构)
- [快速开始](#快速开始)
- [命令详解](#命令详解)
- [双 Agent 架构](#双-agent-架构)
- [五维并行审查](#五维并行审查)
- [RAG 检索系统](#rag-检索系统)
- [题材模板](#题材模板)
- [配置说明](#配置说明)
- [项目结构](#项目结构)
- [故障恢复](#故障恢复)
- [License](#license)

---

## 核心理念

### 防幻觉三定律

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

### Strand Weave 节奏系统

三线交织的叙事节奏控制：

| 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│                     │
│  │ (状态)   │ │ (索引)   │ │ (向量)   │                     │
│  └──────────┘ └──────────┘ └──────────┘                     │
└─────────────────────────────────────────────────────────────┘
```

---

## 快速开始

### 1. 安装

```bash
# 进入你的小说项目目录
cd your-novel-project

# 克隆插件到 .claude 目录
git clone https://github.com/lingfengQAQ/webnovel-writer.git .claude
```

### 2. 初始化项目

```bash
# 在 Claude Code 中执行
/webnovel-init
```

系统会引导你完成：
- 选择初始化模式（Quick/Standard/Deep）
- 选择题材类型
- 设计金手指/核心卖点
- 生成项目结构和设定模板

### 3. 规划大纲

```bash
# 规划第1卷大纲
/webnovel-plan 1
```

### 4. 开始创作

```bash
# 创作第1章
/webnovel-write 1
```

### 5. 质量审查（可选）

```bash
# 审查第1-5章
/webnovel-review 1-5
```

---

## 命令详解

### /webnovel-init - 项目初始化

初始化项目结构、题材模板、世界观设定。

**初始化模式**：

| 模式 | 时间 | 内容 |
|------|------|------|
| ⚡ Quick | 5分钟 | 基础结构 + 核心卖点 |
| 📝 Standard | 15-20分钟 | + 金手指设计 + 题材模板 |
| 🎯 Deep | 30-45分钟 | + 深度世界观 + 创意验证 |

**产出文件**：
- `.webnovel/state.json` - 项目状态
- `设定集/` - 世界观、力量体系、角色卡
- `大纲/总纲.md` - 故事框架

---

### /webnovel-plan [卷号] - 大纲规划

制定详细的卷大纲，规划爽点分布和节奏。

```bash
/webnovel-plan 1        # 规划第1卷
/webnovel-plan 2-3      # 规划第2-3卷
```

**产出**：
- `大纲/第N卷-详细大纲.md`
- 每章目标、爽点设计、Strand 类型
- 新增实体预告

---

### /webnovel-write [章号] - 章节创作

采用双 Agent 架构的自动化章节创作。

```bash
/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 [范围] - 质量审查

对已完成章节进行多维度深度扫描。

```bash
/webnovel-review 1-5    # 审查第1-5章
/webnovel-review 45     # 审查单章
```

**审查维度**：
- 爽点密度与质量
- 设定一致性
- 节奏 Strand 分布
- 人物 OOC 检测
- 场景连贯性

---

### /webnovel-query [关键词] - 信息查询

查询角色、境界、伏笔、系统状态等运行时信息。

```bash
/webnovel-query 萧炎         # 查询角色信息
/webnovel-query 伏笔         # 查看待回收伏笔
/webnovel-query 紧急         # 查看紧急伏笔
```

---

### /webnovel-resume - 任务恢复

在任务中断时检测中断点并提供安全恢复选项。

```bash
/webnovel-resume
```

**恢复选项**：
- 从断点继续
- 回滚到上一个安全点
- 重新开始当前步骤

---

## 双 Agent 架构

### Context Agent（上下文包工程师）

**职责**：为写作准备精准的上下文

**工作流程**：
1. 读取本章大纲，分析需要什么信息
2. 从 `state.json` 获取主角状态快照
3. 调用 `index.db` (v5.1 schema) 查询相关实体和别名
4. 调用 RAG 语义检索相关历史场景
5. 搜索设定集获取相关设定
6. 评估伏笔紧急度
7. 组装上下文包 JSON

**输出结构**：
```json
{
  "core": {
    "chapter_outline": "本章大纲",
    "protagonist_snapshot": {...},
    "r

... (truncated)