Skill: sunshinejnjn/epic-novel-writer (version 1.1.2)

--- name: epic-novel-writer description: Novel writing full workflow — from world-building and character design to chapter planning, manuscript writing, version archiving, and HTML guide generation. Covers medium (100-250k words) to super-long (600k-1.5m words), proven with 420k words / 300 chapters / 10 volumes. Supports global continuous numbering, read-only archives, character JSON, and HTML guides. metadata: openclaw: emoji: "🖊️" version: "1.1.1" compatibility: Pure Markdown workflow, no external dependencies. Requires OpenClaw file I/O and shell execution capabilities. allowed-tools: Read, Write, Edit, Exec --- # epic-novel-writer — 史诗级长篇写作 Skill --- BSD 3-Clause License Copyright (c) 2026, sunshinejnjn@github Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ## 项目结构 ``` [小说标题]/ ├── 在编辑稿/ ← 所有编辑工作在此目录 │ ├── 01-story-premise.md # 故事设定 │ ├── 02-world-setting.md # 世界观设定 │ ├── 03-chapters-written.md # 章节完成状态 │ ├── 03-outline/ # 大纲（卷级 + 章级蓝图） │ ├── 04-chapters/ # 章节正文（按卷分目录） │ ├── 05-reports/ # 过程报告 │ ├── 06-validation/ # 验证报告 │ ├── references/ # 参考（人物卡、关系、线索台账） │ └── media/ # 图片/media ├── [小说标题]_v1/ ← 存档版本（只读） ├── [小说标题]_v2/ ← 存档版本（只读） ├── [小说标题]_v3/ ← 存档版本（只读） └── …… ``` ## ⚠️ 核心规则 ### 所有编辑必须在 在编辑稿 目录上完成 - **任何时候**修改章节、大纲、参考文档，操作对象都是 `在编辑稿/` 下的文件 - 不要修改 `在编辑稿/` 之外的任何文件 ### 存档版本（v1/v2/v3...）是只读的 - **禁止**在 v1/v2/v3 等存档目录上做任何编辑 - 存档版本只用于**对比、核对、历史回溯** - 如果需要对比编辑稿和存档，先用存档作为参考，然后修改 在编辑稿 中的内容 - 违反此规则会导致内容冲突，务必遵守 ### 阶段性存档规则 仅在用户**明确要求**某个版本作为阶段性成果时，才创建存档版本： - 用户说"存成 v1"、"这是终稿了"、"存档"等类似表述 - 存档命名：`[小说标题]_v1/`、`[小说标题]_v2/` 等，按创建顺序递增 --- ## 📦 版本存档 ### 存档流程模板 存档的完整流程定义在以下模板文件中，存档时严格参照执行： > **模板路径**：`references/archive-template.md`（本 SKILL 内） 该模板包含： - 存档目录结构（每个文件的用途） - 8 个执行步骤（从创建目录到完成检查） - 命名规则（文件编号 = 章编号） - 人物画像 JSON 生成指南 - HTML 导引文件生成要点 - 反向合并规则 ### 存档时的工作方式 1. 先读 `references/archive-template.md` 获取完整流程 2. 按模板中的步骤逐项执行 3. 模板中每个步骤都有对应的命令示例，可直接参考执行 4. 完成后用模板中的「完成检查」清单逐项验证 ### 命名规则（文件编号 = 章编号） > **这是存档流程中的核心规则，已同步到模板中：** - ❌ **禁止每卷内从第 1 章重新开始编号**（不要出现卷 1 有 1-30 章、卷 2 也有 1-30 章的情况） - ✅ **文件名 = 章编号 = 全局连续三位数**：`chapter-001.md`（第 1 章）、`chapter-300.md`（第 300 章） - ✅ 卷 1 第 1 章 = `chapter-001.md`，卷 2 第 1 章 = `chapter-031.md`（假设卷 1 有 30 章） ### 人物画像生成 存档时应生成 `char_data.json`，包含主要角色画像： **主要角色定义**：在正文中出现频率高、推动主线或关键剧情的角色。至少包含： - 主角 - 女主/重要配角 - 核心死党/对照 - 关键灵体 - 关键引导者 **每个角色的画像字段**： | 字段 | 说明 | |------|------| | `name` | 角色名 | | `role` | 角色定位（主角/灵体/引导者等） | | `portrait` | 角色图片路径（media 目录） | | `description` | 简要描述（1-3 句话） | | `key_arc` | 角色关键成长线（→ 分隔） | | `first_appearance` | 首次出场章节号（如"第 1 章"） | | `affinity` | 简称/昵称（用于图片文件匹配） | 次要角色（每卷单元灵）可在 `minor_characters` 数组中补充。 ### HTML 导引文件 存档时生成 `[小说标题]_导引.html`，这是存档的**核心导航页**： **页面必须包含四个区域：** 1. **页面头部** — 标题 + 版本 + 统计数据（如"[小说标题] v3 · N 角色 · M 章"） 2. **全文简要介绍** — 从 `01-story-premise.md` 和 `02-world-setting.md` 提取，写一段 200-300 字的小说概述，包含核心主题、故事走向、整体氛围 3. **人物卡区域** — 响应式网格，每人一张卡片（图片 + 名字 + 角色定位 + 简述），暗色主题，hover 高亮 4. **章节目录区域** — 按卷分组，**章节号全局连续编号**（不是每卷从 1 开始！），每章超链接指向对应 txt 文件 **样式要求**： - 暗色主题（背景 `#0a0a0f`，卡片 `#12121a`） - 响应式布局（CSS Grid，移动端适配） - 字体：`PingFang SC, Microsoft YaHei, sans-serif` - 章节链接 hover 效果 **关键检查**：章节号是否全局连续？每个链接是否能正确导航？ --- ## 📐 写作流程（完整生命周期） > 以下为标准写作流程，按阶段顺序执行。每个阶段输出明确文件，下游阶段依赖上游产出。 ### 阶段 1：构思沟通 与用户深入沟通，确定以下核心要素： - 故事类型（奇幻/科幻/悬疑/现实/……） - 核心主题与想要表达的情感 - 目标读者群体与文风偏好 - 预期篇幅（总章数、总字数） - 叙事视角（第一人称/第三人称/多视角轮换） - 基调（轻松/沉重/悬疑/热血/……） > **篇幅估算参考**：每章约 4,000 字，每卷约 10 章（~40,000 字）。用户给定总字数后，按此标准反推总章数和卷数。例如：12 万字 → 约 30 章 → 3 卷。 **产出**：`01-story-premise.md` ### 阶段 2：人物设定（含时间线） 根据构思创建角色设定，包含： - **主角团**：姓名、年龄、身份、外貌、性格核心、成长弧线、首次出场章 - **配角群**：核心配角、反派、辅助角色 - **人物关系**：谁和谁是朋友/敌人/恋人/师徒/对立 - **时间线**：故事起止时间、关键事件时间锚点、角色年龄变化追踪 **产出**：`references/characters/角色名.md`（每个角色一张卡片）+ `references/character-relationships.md` ### 阶段 3：核对修订人物与时间线（2 遍） **第 1 遍核对**： - 年龄一致性：角色年龄是否随时间线合理变化 - 关系一致性：A 是 B 的哥哥，B 是 A 的弟弟（双向验证） - 首次出场顺序：角色不可能在出场前出现在场景中 - 时间线逻辑：事件先后顺序是否自洽 **第 2 遍修订**： - 根据第 1 遍发现的问题修正 - 用户确认修改（或自行修正） - 最终锁定人物设定与时间线 **产出**：修订后的人物卡片 + 关系表（时间线锁定，后续不再变动基础设定） ### 阶段 4：分卷规划 - 将故事按剧情阶段划分为若干卷 - 每卷确定：卷编号、卷标题、章节范围、核心冲突、卷内主角弧光 - 全局章号规划：确定每卷首尾章号（例如卷 1: 001-030，卷 2: 031-060） **产出**：`03-outline/00-master-outline.md`（总纲） ### 阶段 5：卷级大纲 为每一卷撰写大纲，包含： - 卷内章节列表（章号 + 标题 + 简要剧情说明） - 卷内节奏规划（开篇/发展/高潮/收尾） - 卷内伏笔清单（埋设章节 + 回收章节） - 卷内人物变化节点 **产出**：`03-outline/vol-{N}-outline.md`（每卷一个） ### 阶段 6：章级蓝本 为每卷的每一个章节撰写蓝本（blueprint），包含： - 场景设定（时间、地点、环境） - 出场人物（状态 + 在本章作用） - 情节大纲（开场→发展→高潮→收尾，按百分比分配） - 关键事件清单 - 伏笔/线索记录（本章节埋设 + 回收） - 技能/设定调用 **产出**：`03-outline/vol-{N}/chapter-{XX}-blueprint.md`（每章一个） ### 阶段 7：撰写前三章（开篇定调） **先写而非先写全卷**，确保文风和叙事基调正确： 1. 按章级蓝本撰写第 1-3 章正文 2. 每章完成后进行 **2 遍校验与润色**： - 第 1 遍：逻辑校验（与蓝本是否一致、时间线是否正确） - 第 2 遍：文笔润色（节奏、对话、描写质量） 3. 用户确认前三章定调无误 **产出**：`04-chapters/vol-1/chapter-001.md` ~ `chapter-003.md`（校验润色后的定稿） ### 阶段 8：分卷并行撰写（Sub-Agent 并行） - 使用 Sub-Agent **并行**撰写同一卷内的各章（而非全卷全章同时，避免上下文过长） - 每卷内部章节**按顺序串行**撰写（前一章完成后再写下一章，保证连贯性） - 每个 Sub-Agent 负责一个卷内章节，拿到蓝本 + 前文上下文 - 写完即校验 **产出**：`04-chapters/vol-{N}/chapter-{XX}.md` ### 阶段 9：整卷校验与蓝本核对 卷内所有章节完成后，执行： 1. **整卷校验**：通读全卷，检查剧情连贯性、角色一致性、伏笔回收情况 2. **蓝本核对**：对比蓝本与正文，检查是否偏离预设、是否有遗漏的伏笔/设定 3. 修正发现的问题 4. 用户确认本卷定稿 **产出**：修订后的正文 + `06-validation/vol-{N}-validation-report.md`（校验报告） ### 阶段 10：重复阶段 4-9，依次完成各卷 - 按卷编号顺序，重复分卷规划 → 章级蓝本 → 前三章式开篇校验 → 分章撰写 → 整卷校验 - 每卷完成后锁定，不再修改（除非重大设定变更） ### 阶段 11：全卷并行修订（Sub-Agent 并行，2 遍） 所有卷完成后，使用 Sub-Agent **并行**执行修订： - 每个卷由一个 Sub-Agent 独立修订 - **第 1 遍修订**：逻辑/设定一致性校验 + 剧情润色 - **第 2 遍修订**：文笔打磨 + 细节完善 **产出**：修订后的各卷正文 ### 阶段 12：全文校验（3 遍） 全书完成后，执行全文级别校验： - **第 1 遍**：全局一致性校验（人物年龄、关系、能力随章节变化是否合理） - **第 2 遍**：剧情连贯性校验（跨卷伏笔、悬念回收、节奏分布） - **第 3 遍**：文笔终检（风格统一性、对话差异化、描写质量） **产出**：全文定稿 + `06-validation/full-book-validation-report.md` ### 阶段 13：存档 v0 全书定稿后，执行第一次完整存档： - 按 `references/archive-template.md` 执行 8 步存档流程 - 存档命名：`[小说标题]_v0/`（v0 表示全书完成的首个存档） - 生成人物画像 JSON + HTML 导引页 + 全文合并版 **产出**：`[小说标题]_v0/` 完整存档目录 --- ## 📏 适用篇幅 | 篇幅 | 章节数 | 字数范围 | 推荐程度 | |------|--------|---------|---------| | 中篇 | 30-80 章 | 10-25 万字 | ✅ 完全覆盖 | | 长篇 | 80-200 章 | 25-60 万字 | ✅ 完美匹配 | | 超长篇 | 200-500 章 | 60-150 万字 | ✅ 完全胜任 | > 💡 **实测标杆**：本项目已用于生成 **420,000 字**（300 章，10 卷），验证了全局连续编号、防崩设定体系、HTML 导引页生成等核心功能在超长篇场景下的可靠性。 ## 📏 适用篇幅 | 篇幅 | 章节数 | 字数范围 | 推荐程度 | |------|--------|---------|---------| | 中篇 | 30-80 章 | 10-25 万字 | ✅ 完全覆盖 | | 长篇 | 80-200 章 | 25-60 万字 | ✅ 完美匹配 | | 超长篇 | 200-500 章 | 60-150 万字 | ✅ 完全胜任 | > 💡 **实测标杆**：本项目已用于生成 **420,000 字**（300 章，10 卷），验证了全局连续编号、防崩设定体系、HTML 导引页生成等核心功能在超长篇场景下的可靠性。 ## 注意事项 - 不要在存档版本上做任何编辑 - 不要在 在编辑稿/ 之外创建或修改内容 - 生成存档时确保所有章节都已正确排序和合并 - 如果用户没有明确要求存档，不要擅自创建 v1/v2/v3 目录 - **文件编号 = 章编号 = 全局连续三位数，不要每卷从 1 开始** - **存档时务必生成人物画像 JSON 和 HTML 导引文件**

path: README.md
content: # epic-novel-writer — Epic Novel Writing Full Workflow

> An AI-driven creative writing SKILL for long-form serialized novels, covering the entire lifecycle from world-building and character design to chapter planning, writing, version archiving, and HTML guide generation.

**Adapted Length: Medium (100-250k words) → Long (250-600k words) → Super Long (600k-1.5m words)**
> 💡 **Proven Benchmark**: Used to generate **420,000 words** (300 chapters, 10 volumes), validating global chapter numbering, anti-collapse settings system, and HTML guide generation for super-long-form novels.

---

## 🚀 Why This SKILL?

The hardest part of writing a novel isn't "starting" — it's **surviving 300 chapters without things falling apart**. This SKILL solves the most painful problems of long-form writing:

### 1. File Names = Chapter Numbers, Never Get Lost
```
chapter-001.md → Chapter 1
chapter-150.md → Chapter 150 (regardless of which volume)
chapter-300.md → Chapter 300
```
**Restarting from 1 in every volume** is every long-form writer's nightmare. We use **global continuous numbering** — file name IS chapter number, open the folder and you know where you are.

> **文件编号 = 章编号**：`chapter-001.md` 就是第 1 章，`chapter-300.md` 就是第 300 章。不管在哪一卷，文件名直接告诉你章节号。打开文件夹就知道写到哪了。

### 2. One-Click Professional Archive
From `references/archive-template.md`, an 8-step flow auto-generates:
- ✅ **Full-text merged version** (md + txt dual format)
- ✅ **Character profile JSON** (char_data.json with name, role, growth arc, first appearance)
- ✅ **HTML guide page** (dark theme, responsive layout, character card grid, continuous chapter links)
- ✅ **Plain text table of contents** (chapter numbers + hyperlinks)

> **一键专业存档**：8 步流程自动生成全文合并版（md+txt）、人物画像 JSON、HTML 导引页（暗色主题 + 人物卡网格 + 连续章节链接）、纯文本目录。

### 3. Anti-Collapse Settings System
- **World-building template** (`world-setting-template.md`) — geography, history, power system, core conflicts
- **Character card template** (`character-card-template.md`) — personality, background, ability growth arcs, appearance tracking
- **Chapter blueprint template** (`chapter-blueprint-template.md`) — scene settings, plot outlines, foreshadowing/clue tracking, skill usage records

> **防崩设定体系**：三个模板分别覆盖世界观、角色卡、章纲。章纲模板追踪每章伏笔、线索、技能调用，确保剧情不偏离。

### 4. Read-Only Archives, Free Editing
All editing happens in `在编辑稿/` (Work-in-Progress), archive versions (v1/v2/v3…) are **read-only**,可随时对比、回溯、反向合并。

> **只读存档**：所有编辑在 `在编辑稿/` 完成，存档版本（v1/v2/v3…）只读，随时对比、回溯、反向合并。

---

## 📋 Contents

| File | Purpose |
|------|---------|
| `SKILL.md` | Core rules, workflow, naming conventions, archive process guide |
| `references/archive-template.md` | 8-step archive flow (directory structure + command examples + checklists) |
| `references/world-setting-template.md` | World-building template (geography/history/power system/rhythm planning) |
| `references/character-card-template.md` | Character card template (personality/background/ability growth/appearance tracking) |
| `references/chapter-blueprint-template.md` | Chapter blueprint template (scene/plot/foreshadowing/skill usage) |

---

## 🔧 Quick Start

### 1. Initialize Project

```bash
mkdir -p "我的小说/在编辑稿/{01-story-premise,02-world-setting,03-outline,04-chapters,05-references}"
```

### 2. Fill Core Settings

Copy templates from `references/`:
```bash
cp references/world-setting-template.md 在编辑稿/02-world-setting.md
cp references/character-card-template.md 在编辑稿/references/characters/主角.md
```

### 3. Start Writing Chapter 1

```bash
cp references/chapter-blueprint-template.md 在编辑稿/03-outline/chapter-001-blueprint.md
# Fill blueprint, then create chapter-001.md in 04-chapters/
```

### 4. Archive

When the user says "存档" (archive):
```bash
# Read references/archive-template.md and execute the 8-step flow
```

---

## 📐 Project Structure

```
MyNovel/
├── 在编辑稿/              ← 所有编辑在此 (all editing happens here)
│   ├── 01-story-premise.md     # 故事设定 (story premise)
│   ├── 02-world-setting.md     # 世界观 (world-building)
│   ├── 03-chapters-written.md  # 章节状态 (chapter status)
│   ├── 03-outline/             # 大纲 (outlines)
│   ├── 04-chapters/            # 正文 (manuscript, chapter-001.md ~ chapter-XXX.md)
│   ├── 05-reports/             # 过程报告 (process reports)
│   └── references/             # 参考文档 (reference docs)
├── MyNovel_v1/               ← 存档（只读） (archive, read-only)
├── MyNovel_v2/               ← 存档（只读） (archive, read-only)
└── ……
```

---

## ⚠️ Core Rules

1. **All editing in `在编辑稿/`**, don't touch archive directories
2. **Archive versions are read-only**, for comparison, tracking
3. **Global continuous numbering**: `chapter-001.md` = Chapter 1, doesn't reset per volume
4. **Archive must generate**: Character profile JSON + HTML guide page

> **核心规则**：所有编辑在 `在编辑稿/` 完成；存档只读；文件名=章编号=全局连续；存档必含人物画像 JSON 和 HTML 导引页。

---

## 📏 Suitable Length

| Length | Chapters | Word Count | Fit |
|--------|----------|------------|-----|
| Medium (中篇) | 30-80 chapters | 100k-250k words | ✅ Perfect fit |
| Long (长篇) | 80-200 chapters | 250k-600k words | ✅ Ideal match |
| Super Long (超长篇) | 200-500 chapters | 600k-1.5m words | ✅ Fully capable |

> 💡 **实测标杆 (Proven Benchmark)**: 已用于生成 **420,000 字**（300 章，10 卷）

**Estimation Reference (篇幅估算参考)**: ~4,000 words/chapter, ~10 chapters/volume (~40,000 words/volume). Given total word count, reverse-calculate chapters and volumes.

---

## 🏷️ Use Cases

- Long-form serialized novels (100+ chapters)
- Web novels / light novels / fantasy / sci-fi
- AI-assisted writing (LLM generation + human polishing)
- Multi-person collaboration (each works in `在编辑稿/`, archives regularly)
- Complex world-building, many characters

---

## 📦 Installation

```bash
clawhub install epic-novel-writer
```

## 🔄 Update

```bash
clawhub update epic-novel-writer
```

## 📄 License

BSD 3-Clause License

Copyright (c) 2026, sunshinejnjn@github

---

> 用结构化流程对抗长篇写作的混沌。从第 1 章到第 300 章，每一步都有据可查。
> **Structure the chaos of long-form writing. Every chapter, every step, traceable.**


path: README.zh.md
content: # epic-novel-writer — 史诗级长篇写作工作流

一个面向长篇连载小说的 AI 驱动创作 SKILL，从世界观设定、人物塑造、章纲规划，到正文写作、版本存档、HTML 导引页生成，覆盖一部小说从零到出版的全生命周期。

**适配篇幅：中篇（10-25 万字）→ 长篇（25-60 万字）→ 超长篇（60-150 万字）**
> 💡 **实测标杆**：已用于生成 **420,000 字**（300 章，10 卷），验证了全局连续编号、防崩设定体系、HTML 导引页生成在超长篇场景下的可靠性。

## 🚀 为什么需要这个 SKILL？

写小说最难的不是"开始"，而是**持续 300 章不崩**。这个 SKILL 解决的是长篇写作中最痛苦的几个问题：

### 1. 文件编号 = 章编号，永远不迷路
```
chapter-001.md → 第 1 章
chapter-150.md → 第 150 章（不管它在哪一卷）
chapter-300.md → 第 300 章
```
**每卷内从 1 重新开始**是每个长篇写作者的噩梦。我们采用**全局连续编号**——文件名即章节号，打开文件夹就知道写到哪了。

### 2. 一键生成专业级存档
从 `references/archive-template.md` 出发，8 步流程自动生成：
- ✅ **全文合并版**（md + txt 双格式）
- ✅ **人物画像 JSON**（char_data.json，含角色名、定位、成长线、首次出场）
- ✅ **HTML 导引页**（暗色主题、响应式布局、人物卡网格、连续编号章节目录）
- ✅ **纯文本目录**（章节号 + 超链接）

### 3. 防崩设定体系
- **世界观模板**（`world-setting-template.md`）— 地理、历史、力量体系、核心矛盾
- **角色卡片模板**（`character-card-template.md`）— 性格、背景、能力成长弧线、登场退出追踪
- **章纲模板**（`chapter-blueprint-template.md`）— 每章场景设定、情节大纲、伏笔/线索追踪、技能调用记录

### 4. 只读存档，编辑自由
所有编辑在 `在编辑稿/` 下完成，存档版本（v1/v2/v3…）**只读**，随时可以对比、回溯、反向合并。

## 📋 包含什么

| 文件 | 用途 |
|------|------|
| `SKILL.md` | 核心规则、工作流、命名规范、存档流程指引 |
| `references/archive-template.md` | 版本存档 8 步完整流程（目录结构 + 命令示例 + 检查清单） |
| `references/world-setting-template.md` | 世界观设定模板（地理/历史/力量体系/节奏规划） |
| `references/character-card-template.md` | 角色卡片模板（性格/背景/能力成长/登场追踪） |
| `references/chapter-blueprint-template.md` | 章纲模板（场景/情节/伏笔/技能调用） |

## 🔧 快速开始

### 1. 初始化项目

```bash
mkdir -p "我的小说/在编辑稿/{01-story-premise,02-world-setting,03-outline,04-chapters,05-references}"
```

### 2. 填写核心设定

从 `references/` 复制模板：
```bash
cp references/world-setting-template.md 在编辑稿/02-world-setting.md
cp references/character-card-template.md 在编辑稿/references/characters/主角.md
```

### 3. 开始写第一章

```bash
cp references/chapter-blueprint-template.md 在编辑稿/03-outline/chapter-001-blueprint.md
# 填写章纲后，在 04-chapters/ 创建 chapter-001.md
```

### 4. 存档

用户说"存成 v1"时：
```bash
# 阅读 references/archive-template.md，按 8 步流程执行
```

## 📐 项目结构

```
我的小说/
├── 在编辑稿/              ← 所有编辑在此
│   ├── 01-story-premise.md     # 故事设定
│   ├── 02-world-setting.md     # 世界观
│   ├── 03-chapters-written.md  # 章节状态
│   ├── 03-outline/             # 大纲
│   ├── 04-chapters/            # 正文（chapter-001.md ~ chapter-XXX.md）
│   ├── 05-reports/             # 过程报告
│   └── references/             # 参考文档
├── 我的小说_v1/               ← 存档（只读）
├── 我的小说_v2/               ← 存档（只读）
└── ……
```

## ⚠️ 核心规则

1. **所有编辑在 `在编辑稿/` 下完成**，不碰存档目录
2. **存档版本只读**，用于对比、回溯
3. **全局连续编号**：`chapter-001.md` = 第 1 章，不随卷重置
4. **存档时需生成人物画像 JSON + HTML 导引页**

## 📏 适用篇幅

| 篇幅 | 章节数 | 字数范围 | 推荐程度 |
|------|--------|---------|---------|
| 中篇 | 30-80 章 | 10-25 万字 | ✅ 完全覆盖 |
| 长篇 | 80-200 章 | 25-60 万字 | ✅ 完美匹配 |
| 超长篇 | 200-500 章 | 60-150 万字 | ✅ 完全胜任 |

> 💡 **实测标杆**：本项目已用于生成 **420,000 字**（300 章，10 卷），验证了全局连续编号、防崩设定体系、HTML 导引页生成等核心功能在超长篇场景下的可靠性。

## 🏷️ 适用场景

- 长篇连载小说（100 章+）
- 网络文学/轻小说/奇幻/科幻
- AI 辅助写作（大模型生成 + 人工润色）
- 多人协作（每人在 `在编辑稿/` 下工作，定期存档）
- 世界观复杂、角色众多的作品

## 📦 安装

```bash
clawhub install epic-novel-writer
```

## 🔄 更新

```bash
clawhub update epic-novel-writer
```

## 📄 协议

BSD 3-Clause License

Copyright (c) 2026, sunshinejnjn@github

---

> 用结构化流程对抗长篇写作的混沌。从第 1 章到第 300 章，每一步都有据可查。


path: references/archive-template.md
content: # 版本存档模板

> 本模板定义了版本存档的标准流程与输出结构。存档时参照此模板执行，生成新的 `[小说标题]_vN/` 目录。

---

## 存档触发条件

仅在用户**明确要求**时执行存档：
- 用户说"存成 vN"、"这是终稿了"、"存档"等类似表述
- 按创建顺序递增命名：`[小说标题]_v1/`、`[小说标题]_v2/`…

---

## 命名规则（文件编号 = 章编号）

**所有章节文件名使用全局连续三位数编号，不随卷重置：**

| 卷 | 章节范围 | 文件名 |
|----|---------|--------|
| 卷 1 | 第 1-30 章 | `chapter-001.md` ~ `chapter-030.md` |
| 卷 2 | 第 31-60 章 | `chapter-031.md` ~ `chapter-060.md` |
| 卷 3 | 第 61-100 章 | `chapter-061.md` ~ `chapter-100.md` |
| … | … | … |
| 卷 N | 最后一卷 | `chapter-XXX.md` |

**关键规则：**
- ❌ 禁止每卷内从第 1 章重新开始编号（不要出现卷 1 有 1-30 章、卷 2 也有 1-30 章的情况）
- ✅ 文件名直接反映全局章号：`chapter-031.md` = 第 31 章，`chapter-271.md` = 第 271 章
- ✅ 三位数补零：`chapter-001.md`、`chapter-300.md`

---

## 存档目录结构

```
[小说标题]_vN/
├── 01-story-premise.md          # 故事设定（复制）
├── 02-world-setting.md          # 世界观设定（复制）
├── 03-chapters-written.md       # 章节完成状态（复制，反映存档时进度）
├── 03-outline/                  # 大纲目录（复制）
│   ├── 00-master-outline.md
│   ├── vol-1-outline.md
│   └── ……
├── 04-chapters/                 # 正文文件（txt，按卷分目录）
│   ├── vol-1/
│   │   ├── chapter-001.txt
│   │   ├── chapter-002.txt
│   │   └── ……
│   ├── vol-2/
│   │   ├── chapter-031.txt
│   │   └── ……
│   └── ……
├── 05-reports/                  # 过程报告（复制）
├── references/                  # 参考文件（复制）
│   ├── ai-ledger/
│   ├── character-relationships.md
│   ├── characters/
│   └── skill-database.md
├── media/                       # 图片（复制）
│   └── comfyui/images/
│       └── ……
├── [小说标题]_全文.md           # 全文合并版（md）
├── [小说标题]_全文.txt          # 全文合并版（纯文本）
├── [小说标题]_目录.txt          # 纯文本目录导航
├── [小说标题]_导引.html         # ★ HTML 导引文件（核心导航页）
└── char_data.json              # 人物数据（JSON，供导引页使用）
```

---

## 执行步骤

### 步骤 1：创建存档目录

```bash
N=下一个序号（从现有最大序号 +1）
mkdir -p "[小说标题]_v${N}/"
```

### 步骤 2：复制只读文件

将 `在编辑稿/` 下的非正文文件原样复制到存档目录：

```bash
cd "[小说标题]_v${N}/"
# 复制根文件
cp ../在编辑稿/01-story-premise.md ./
cp ../在编辑稿/02-world-setting.md ./
cp ../在编辑稿/03-chapters-written.md ./

# 复制大纲目录
cp -r ../在编辑稿/03-outline/ ./

# 复制参考文件
cp -r ../在编辑稿/references/ ./
cp -r ../在编辑稿/media/ ./

# 复制报告
cp -r ../在编辑稿/05-reports/ ./
```

### 步骤 3：复制正文为 txt

`在编辑稿/04-chapters/` 下所有章节已使用全局连续三位数编号，直接转为 txt 复制：

```bash
mkdir -p chapters
for vol_dir in ../在编辑稿/04-chapters/vol-*; do
    vol_num=$(basename "$vol_dir")
    mkdir -p "chapters/${vol_num}"
    for chapter_file in "$vol_dir"/*.md; do
        # 文件名已是全局连续三位数（chapter-NNN.md），直接转换格式
        sed 's/^#\+ //; s/`//g; s/\*\*/\n/g' "$chapter_file" > "chapters/${vol_num}/$(basename "$chapter_file" .md).txt"
    done
done
```

### 步骤 4：生成全文合并版

将 `chapters/vol-*/chapter-*.txt` 按**全局章节号**顺序合并：

```bash
# 按卷 + 章号排序后合并（文件名已是三位数全局连续编号）
cat chapters/vol-*/chapter-*.txt > [小说标题]_全文.txt
```

**文件名 = 章编号 = 全局连续三位数**：`chapter-001.txt`（第 1 章）、`chapter-300.txt`（第 300 章），不随卷重置。

### 步骤 5：生成目录

生成 `[小说标题]_目录.txt`，格式：

```
# [小说标题] 目录 — vN

## 第 001 章 [章节标题] → chapters/vol-1/chapter-001.txt
## 第 002 章 [章节标题] → chapters/vol-1/chapter-002.txt
……
## 第 300 章 [章节标题] → chapters/vol-10/chapter-300.txt
```

**关键：章节号全局连续编号，不随卷重置。**
- 卷 1 第 1 章 = 第 001 章
- 卷 2 第 1 章 = 第 031 章（如果卷 1 有 30 章）
- 卷 10 第 1 章 = 第 271 章（以此类推）

### 步骤 6：生成人物画像 JSON

扫描所有章节，提取**主要角色画像**，生成 `char_data.json`：

```json
{
  "project": "[小说标题]",
  "version": "vN",
  "total_chapters": 300,
  "characters": [
    {
      "name": "主角名",
      "role": "主角",
      "portrait": "media/comfyui/images/主角图片.png",
      "description": "主角的简要描述",
      "key_arc": "成长线 1 → 成长线 2",
      "first_appearance": "第 1 章",
      "affinity": "主角简称"
    }
  ]
}
```

**生成规则：**
- **主要角色**：指在正文中出现频率高、推动主线/关键剧情的角色
- 至少包含：主角、女主/重要配角、核心灵体、关键引导者
- 次要角色（每卷单元灵）可在 `char_data.json` 中以 `minor_characters` 字段补充

### 步骤 7：生成 HTML 导引文件

生成 `[小说标题]_导引.html`，要求：

#### 页面结构

1. **页面头部**
   - 小说标题 + 版本信息 + 统计数据
   - 示例：`[小说标题] v3 · 12 角色 · 300 章`

2. **全文简要介绍**
   - 一段对整个小说的简要概述（200-300 字）
   - 包含核心主题、故事走向、整体氛围
   - 从 `01-story-premise.md` 和 `02-world-setting.md` 提取

3. **人物卡区域**
   - 响应式网格布局（CSS Grid）
   - 每人一张卡片，包含：
     - 角色图片（`portrait` 字段）
     - 角色名 + 角色定位（如"主角"、"灵体"）
     - 简要描述（1-2 句话）
   - 暗色主题，hover 高亮边框

4. **章节目录区域**
   - 按卷分组，每卷一个区块
   - **章节号全局连续编号**（关键要求）
   - 每章一个超链接指向 `chapters/vol-X/chapter-NNN.txt`
   - 格式：`第 001 章 [标题]`

5. **页脚**
   - 版本信息、生成时间、统计数据

#### 章节编号规则（非常重要）

- ❌ **禁止**：每卷内从第 1 章重新开始编号
- ✅ **必须**：全局连续编号（卷 1 第 1 章 = 第 001 章，卷 10 第 1 章 = 第 271 章）
- 编号格式：三位数（第 001 章、第 300 章）
- HTML 目录中显示为 `第 001 章 · 章节标题`

#### 样式要求

- 暗色主题（背景 `#0a0a0f`，卡片 `#12121a`）
- 响应式布局（CSS Grid，移动端适配）
- 字体：`PingFang SC, Microsoft YaHei, sans-serif`
- 章节链接 hover 效果

### 步骤 8：完成检查

存档完成后验证：
- [ ] 所有章节已提取为 txt
- [ ] 全文合并版完整（无缺失、无重复）
- [ ] 目录章节号全局连续
- [ ] HTML 导引页人物卡完整
- [ ] HTML 导引页章节链接全部有效
- [ ] 全文介绍已添加
- [ ] 存档目录内无可编辑文件（只读确认）

---

## 反向合并

当存档版本与 `在编辑稿` 不一致时：

1. 先确认以哪个版本为准
2. **以 `在编辑稿` 为准**：不需要反向合并
3. **以存档版为准**：将存档版全文按章节拆分，覆盖 `在编辑稿/04-chapters/` 中的对应文件

---

## 注意事项

- ❌ 不要在存档版本上做任何编辑
- ❌ 不要在 `在编辑稿/` 之外创建或修改内容
- ✅ 生成存档时确保所有章节已正确排序和合并
- ✅ 如果用户没有明确要求存档，不要擅自创建 vN 目录
- ✅ **文件编号 = 章编号 = 全局连续三位数**，不要每卷从 1 开始
- ✅ HTML 导引文件必须包含：人物卡 + 全文介绍 + 连续编号章节目录


path: references/chapter-blueprint-template.md
content: # 章纲模板

> 复制到 [小说项目目录]/03-outline/vol-{N}/chapter-{XX}-blueprint.md

```markdown
# 第 [X] 章：[章名]

## 基本信息
- **位置**: 第 [X] 章（卷 [N] 第 [M] 章）
- **字数目标**: ~1500 字
- **视角**: [主角/其他角色]

## 场景设定
- **时间**: 
- **地点**: 
- **天气/环境**: 

## 出场人物
- [角色名]：状态 + 在本章的作用

## 情节大纲
1. **开场**（~10%）：[快速交代时间/地点/人物状态]
2. **发展**（~40%）：[核心冲突逐步展开]
3. **高潮**（~30%）：[冲突爆发/关键转折]
4. **收尾**（~20%）：[情绪沉淀 + 下章钩子]

## 关键事件
- [事件 1]
- [事件 2]

## 伏笔/线索
- [埋下的伏笔 → 预计在第 X 章回收]

## 技能/设定调用
- [本章节需要展示/用到的设定]

## 注意事项
- [遵守的设定限制]
- [不能做的事情]
```


path: references/character-card-template.md
content: # 角色卡片模板

> 复制此模板创建新角色卡，保存到 [小说项目目录]/references/characters/

```markdown
# 角色名

## 基本信息
- **身份**: 
- **年龄**: 
- **性别**: 
- **外貌**: 
- **口头禅/说话风格**: 

## 性格
- **核心性格**: 
- **优点**: 
- **缺点/弱点**: 
- **内在冲突**: 

## 背景故事
- **成长经历**: 
- **动机**: 
- **秘密**: 
- **人际关系**: 
  - 与 [角色名] 的关系：

## 能力/技能
- **初始能力**: 
- **技能变化节点**:
  - 第 X 章：获得 XX 技能
  - 第 Y 章：技能升级/蜕变

## 成长弧线
- **起点状态**: 
- **转折点**: 
- **终点状态**: 
- **可能的黑化/反转**: 

## 登场与退出
- **首次登场**: 第 [X] 章
- **最后登场**: 第 [X] 章
- **缺席期间**: 第 [X] 至 [Y] 章

## 状态追踪
- **当前状态**: 
- **当前位置**: 
- **当前目标**: 
- **携带物品**: 
```


path: references/world-setting-template.md
content: # 世界设定模板

> 复制到 [小说项目目录]/02-world-setting.md 并开始填充

```markdown
# [世界名称] 设定

## 世界观

### 地理/空间
- 世界层级：
- 主要地点：
- 区域规则：

### 历史/背景
- 起源：
- 重大事件：
- 当前局势：

### 社会/文化
- 权力结构：
- 经济体系：
- 信仰/宗教：

## 力量体系

### 等级
- 等级 1：[描述]
- 等级 2：[描述]
- ...

### 技能
| 技能名 | 等级 | 效果 | 代价 |
|--------|------|------|------|

### 规则与限制
- [限制 1]
- [限制 2]

## 故事基调

### 核心矛盾
- 

### 主题表达
- 

### 节奏规划
- 开篇：
- 总体曲线：
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)