# novel-write — Claude Code 小说写作技能

长中短篇小说写作技能，覆盖题材诊断→深度问诊→设定→大纲共创→单章流水线（细纲→写作→质检→进化→审批）全流程。

**核心能力：**
- **六条铁律** — 展示而非讲述、冲突驱动、悬念承上启下、爽点密度、类型框架内新鲜感、自动进化
- **三根支柱** — 项目铁律（宪法级规则）+ 事件钩子账本（伏笔全生命周期）+ 情感矩阵（角色情感连贯性）
- **四维引擎** — 爽点、笑点、代入感、反同质化，每章自动四维检查
- **质检体系** — 五遍编辑评估（结构→角色→原创性→对话→文本）+ 自修正循环 + 章节审批门
- **自优化进化** — 每次写作后自动进化提示词和质量阈值，同题材越写越好
- **15 个题材** — 仙侠、玄幻、都市、恐怖、科幻、末世、无限流、游戏、奇幻、言情、轻小说、种田、地下城、修真、通用

**前置依赖：** 本技能在 [Claude Code](https://claude.ai/code) 中运行，利用 Claude 的大语言模型进行小说创作。无需 GPU、无外部 API、完全本地运行。

远程仓库: `ssh://git@数学.top:10022/nonvioce/novel-skill.git`

---

## 目录

- [安装](#安装)
- [快速开始](#快速开始)
- [对话示例](#对话示例)
- [技能架构](#技能架构)
- [进化系统](#进化系统)
- [多用户 Git 共享](#多用户-git-共享含多设备)
- [题材管理](#题材管理)
- [全部 CLI 命令](#全部-cli-命令)
- [关键文件参考](#关键文件参考)
- [常见问题](#常见问题)
- [参考来源](#参考来源)

---

## 安装

完全自包含，零外部依赖。内置 15 个中文题材配置文件。

```bash
# Linux/macOS：克隆仓库
git clone ssh://git@数学.top:10022/nonvioce/novel-skill.git ~/.claude/skills/novel-write

# 或：如果已有本地项目，直接软链接
ln -s /path/to/novel-skill ~/.claude/skills/novel-write
```

Windows 用户将 `~/.claude/skills/novel-write` 替换为 `%USERPROFILE%\.claude\skills\novel-write`，软链接替换为 `mklink /D` 或直接克隆到该路径。

安装后，在 Claude Code 对话中输入"写小说""开新书""续写第X章"等自动触发技能。

## 快速开始

### 创建新项目

按以下结构创建小说项目目录：

```
{书名}/
├── 项目铁律.md          # 必须。POV、时态、禁用词、世界观硬限制。frontmatter 写 genre 字段
├── 设定/
│   ├── 世界观.md
│   ├── 角色/{角色名}.md
│   ├── 势力.md
│   ├── 关系图.md
│   └── 题材定位.md
├── 大纲/
│   ├── 全書大纲.md
│   ├── 卷纲_第N卷.md
│   └── 细纲_第NNN章.md
├── 正文/
│   └── 第NNN章_章名.md
├── 对标/
│   └── {书名}/风格报告.md    # 可选。用于风格注入进化
└── 追踪/
    ├── 钩子账本.md
    ├── 情感矩阵.md
    ├── 时间线.md
    └── 上下文.md
```

`项目铁律.md` 示例 frontmatter：

```yaml
---
title: "重生囤货：绑定诡异种田"
genre: "末世"           # ← 题材识别关键字段
sub_genre: "种田+诡异+重生"
pov: "第三人称有限"
tense: "过去时"
target_words: 3000
---
```

### 写作对话中（全自动）

在 Claude Code 中直接说"写第33章"，技能自动完成全部流程：

1. 确认/创建细纲（Step 0）→ 进化脚本 git pull + compile
2. 加载细纲、钩子账本、情感矩阵、上下文
3. 从 `evolution/genres/{genre_id}/` 加载题材最优提示词 + 阈值
4. 边写边对照六条铁律 + 四维引擎检查
5. 写后自检 + 长度标准化
6. 更新钩子账本、情感矩阵、时间线、上下文
7. **质检**：五遍编辑评估（P1→P5）→ 自修正循环（最多5轮，<80废弃）
8. **进化**：evolve.sh --project → git add + commit + push
9. **审批**（单章续写）：review 检查清单 → approved / rejected

**用户不需要输入任何 git 或进化命令。** 所有 git pull、git commit、git push 由进化脚本自动完成。网络不通时自动降级为纯本地模式，不会报错中断。

## 对话示例

### 开新书

```
用户：开新书，我想写一本末世种田文
Claude：先做题材诊断。五句话——
  1. 类型：末世 + 种田 + 诡异（system-apocalypse × cozy × horror）
  2. 核心卖点：...
  ...
  诊断通过。开始深度问诊——
  第一问：核心类型是末世，子方向更偏向废土求生还是系统降临？
```

### 续写

```
用户：写第33章
Claude：[自动运行 evolve.sh → git pull + compile]
  → 加载项目铁律、细纲第33章、钩子账本、情感矩阵
  → 加载末世题材最优提示词
  → 写作...
  → [自动运行 evolve.sh --project → 进化 → git push]
```

### 质检

```
用户：质检最近3章
Claude：→ 执行五遍编辑评估
  P1 结构编辑：...  P2 角色编辑：...  P3 原创性：...  P4 对话：...  P5 文本：...
  综合评分 83 → 通过
  一致性检查：无 S1/S2 问题 ✓
  去 AI 味检查：通过 ✓
```

### 修改

```
用户：修改第33章，主角情绪太突兀
Claude：→ 读取第32-34章 + 情感矩阵
  → 定位情感跳变点 → 精确编辑
  → 更新情感矩阵
```

### 更多触发词

| 想做什么 | 说什么 |
|---------|--------|
| 批量写 | "批量写第40到45章" |
| 风格模仿 | "分析风格 三体.txt" |
| 导入已有书 | "导入小说 我的书.txt" |
| 全书改名 | "改名 张三 李四" |
| 查看数据 | "仪表板" |
| 新建角色 | "添加角色 王五" |
| 调整大纲 | "调整大纲" |

## 技能架构

本仓库的 AI 指令由三个文件组成，按需加载：

```
novel-skill/
├── README.md              # 本文件，用户手册（给人看）
├── SKILL.md               # 技能主入口（197行），铁律+流程+场景路由（AI 日常使用）
├── WORKFLOWS.md           # 完整流程展开（题材诊断/深度问诊/大纲共创/续写/质检体系等）
├── REFERENCE.md           # 理论与参考（三根支柱/四维引擎/自优化系统详解/语言规则）
├── scripts/               # 进化引擎脚本
│   ├── evolve.sh          # Linux/macOS 进化编排器
│   ├── evolve.ps1         # Windows PowerShell 进化编排器
│   ├── prompt_evolver.py  # 提示词遗传进化
│   ├── quality_tuner.py   # 质量阈值自适应
│   ├── pattern_mine.py    # 写作模式挖掘
│   ├── event_store.py     # 事件溯源引擎
│   ├── seed_extractor.py  # 内置15题材种子提取
│   └── utils.py           # 共享工具
├── genres/                # 内置15题材配置文件
├── evolution/             # 进化输出数据
└── docs/                  # 设计文档（如有）
```

**原理：** Claude Code 加载 `SKILL.md` 获取核心操作指令（铁律、总写作流程、场景路由、紧凑版流程）。`WORKFLOWS.md` 提供完整流程展开（题材诊断、深度问诊、大纲共创、续写详细步骤、质检完整体系等），`REFERENCE.md` 提供理论参考（三根支柱、四维引擎、进化系统详解等）。用户参考 `README.md` 了解安装、配置和手动操作。

## 进化系统

### 架构

题材级共享 — 同题材所有项目共用进化数据。写第二本末世时，第一本的优化直接可用。

```
evolution/
├── thresholds.json                 # [gitignored] 技能级默认阈值，--compile 重建
├── prompts/
│   ├── population.json             # [gitignored] 技能级种群，--compile 从事件重建
│   └── current_best.json           # [gitignored] 技能级最优，--compile 从事件重建
├── patterns/
│   └── pattern_library.json        # 跨题材模式库
└── genres/                         # 题材级共享目录
    └── {genre_id}/                 # other, xianxia, urban, horror ...
        ├── thresholds.json         # [gitignored] 题材特定质量阈值，--compile 重建
        ├── prompts/
        │   ├── population.json     # [gitignored] 5岛种群，--compile 从事件重建
        │   └── current_best.json   # [gitignored] 各岛最优，--compile 从事件重建
        ├── patterns/
        │   └── pattern_library.json
        └── events/                 # ★ 唯一纳入 git 追踪的进化数据
            └── {timestamp}_{user}.json   # 不可变事件，永远不冲突
```

`[gitignored]` 文件不纳入版本控制。`git pull` 后 `evolve.sh` 自动调用 `--compile` 从事件重建。

### 五大岛屿

| 岛屿 | 作用 | 写作阶段 |
|------|------|---------|
| writing | 写作规则（密度/去AI味/人物/心理） | 写前注入 |
| revision | 修稿规则（润色边界/字数治理） | 修改时注入 |
| quality_check | 质检标准（37维审查/五遍评估） | 质检时参照 |
| outline | 大纲规则（章节类型轮换/世界观一致性） | 大纲阶段参照 |
| hook_management | 伏笔管理（生命周期/准入控制/健康分析） | 全程参照 |

### 遗传算子

- **交叉** — 两父本按句切分拼接
- **突变** — 同义词替换 + 句序重排 + 前缀注入
- **简化** — 保留首尾句，去中间
- **注入** — 从对标/风格报告提取句式/对话/节奏特征，编码为提示词变体

### 自适应机制

| 机制 | 触发条件 | 行为 |
|------|---------|------|
| 早停 | 单岛连续2代提升<3% | 跳过该岛变异 |
| 灭绝重播 | 连续3代提升<5% | 删底30%，重播：题材种子50%+风格注入30%+交叉20% |
| 阈值调优 | 通过率>90% | 提高 pass 线 (+3) |
| 阈值调优 | 通过率<30% | 降低 pass 线 (-3) |
| 权重调优 | 某P维度持续最低 | 该维度增权 |
| 岛屿迁移 | 每2代 | 各岛最优2个体注入相邻岛（分×0.9）|

### 多维评分

不再用单一 composite score。每个提示词变体按 P1-P5 独立追踪：

```
变体 "abc123" → {P1: 88 (trials=3), P2: 72 (trials=3), P3: 65 (trials=3), P4: 80 (trials=3), P5: 90 (trials=3)}
综合分 = 88×0.35 + 72×0.25 + 65×0.15 + 80×0.15 + 90×0.10 = 80.6
```

新反馈用滑动平均合并：`new = (old × trials + score) / (trials + 1)`

## 多用户 Git 共享（含多设备）

### 原理：事件溯源 + 编译重建

Git 仓库**只追踪事件文件**（`evolution/genres/*/events/*.json`）和 README。

以下共享可变文件已加入 `.gitignore`，**不纳入版本控制**：
- `population.json` / `current_best.json` / `thresholds.json`（skill 级和题材级）
- `evolution_log.md`（追加型日志，多设备并行写入自然冲突）

这些文件是**编译产物**，每次 `git pull` 后由 `evolve.sh` 自动从事件重建。事件文件名含时间戳和用户名（`{timestamp}_{user}.json`），永远不冲突。

### 同一用户多设备

同一 git 用户在不同设备上写作，**零冲突**：

| 设备 A | 设备 B | 结果 |
|--------|--------|------|
| 写第 35 章 → 进化 → push | — | A 的事件文件推送成功 |
| — | `git pull` → 自动 `--compile` | B 从事件重建 population，包含 A 的优化 |
| — | 写第 36 章 → 进化 → push | B 的事件文件推送成功 |
| A `git pull` → 自动 `--compile` | — | A 从事件重建 population，包含 B 的优化 |

两个设备在不同时间产生的进化数据，通过事件文件合并到同一题材种群中，互不覆盖。

### 自动工作流（进化脚本全自动）

> **操作系统：** `evolve.sh` 用于 Linux/macOS (bash)，`evolve.ps1` 用于 Windows (PowerShell)。两个脚本功能完全相同。

```bash
# 写前：进化脚本自动执行
#   → git pull（获取其他设备/用户的进化事件）
#   → event_store.py compile（从事件重建 population/thresholds/current_best）
#   → 加载最新最优提示词，开始写作

# 写后：进化脚本 --project /path/to/novel 自动执行
#   → 收集反馈 → 分析质量 → 提示词进化
#   → git add evolution/genres/*/events/（只推送事件文件）
#   → git commit + git push
```

用户不需要手动执行任何 git 命令。网络不通时自动降级为纯本地模式。

### 手动 compile（仅在自动流程失效时使用）

```bash
# 从指定项目检测题材，重建所有编译产物
bash scripts/evolve.sh --project /path/to/novel --compile
# Windows PowerShell:
# .\scripts\evolve.ps1 -Project /path/to/novel -Compile

# 或直接指定题材
python3 scripts/event_store.py compile --genre xianxia
```

### 冲突场景覆盖

| 场景 | 冲突？ | 原因 |
|------|--------|------|
| 同一用户多设备交替写作 | 无 | 事件文件 `{ts}_{user}.json`，不同时间戳 |
| 不同用户同题材写不同书 | 无 | 各自写事件文件，不同用户名+时间戳 |
| 不同用户同时给同一题材进化 | 无 | 进化事件记录不同变体 ID，合并后种群更丰富 |
| 不同用户给同一变体评分 | 无 | 反馈事件各自独立，编译器回放时滑动平均合并 |
| `population.json` / `thresholds.json` | 无（已解决） | 已 gitignore，不在仓库中；由 `--compile` 从事件重建 |
| 新设备首次克隆后 | 无 | `evolve.sh` 自动检测到缺失编译产物，从事件重建 |
| 题材尚无任何事件 | 无 | `compile_all()` 从内置种子初始化，与事件回放结果一致 |

## 题材管理

### 支持的 15 个题材（全部内置中文配置）

| 中文题材 | 题材 ID | 章类型 | 爽点类型示例 |
|---------|---------|--------|------------|
| 仙侠、修仙 | xianxia | 战斗/悟道/布局/过渡/回收 | 悟道突破、斗法碾压、天劫渡过 |
| 玄幻 | xuanhuan | 战斗/功法/升级/过渡/回收 | 越级反杀、神体觉醒、血脉吞噬 |
| 都市、现代、职场 | urban | 商战/社交/布局/过渡/回收 | 商战碾压、身份揭示、人脉兑现 |
| 恐怖、惊悚、灵异、悬疑 | horror | 铺垫/诡异/恐怖/过渡/回收 | 恐惧具现化、逃脱、规则破解 |
| 科幻、星际、未来 | sci-fi | 探索/战斗/布局/过渡/回收 | 发现、科技突破、首次接触 |
| 末世、废土、末日 | system-apocalypse | 求生/战斗/布局/过渡/回收 | 绝境求生、领土占领、社会重建 |
| 无限流、轮回 | tower-climber | 关卡挑战/升级/布局/过渡/回收 | 楼层通关、Boss击败、登顶进度 |
| 游戏、网游、系统 | litrpg | 升级/布局/过渡/回收/战斗 | 升级、技能解锁、装备掉落 |
| 奇幻、西幻、魔法 | progression | 修炼/突破/布局/过渡/回收 | 等阶突破、技能精通、对手超越 |
| 言情、古言、恋爱 | romantasy | 感情/动作/布局/过渡/回收 | 化学反应、初吻、关系确认 |
| 轻小说、异世界、穿越 | isekai | 探索/适应/布局/过渡/回收/战斗 | 世界规则发现、现实技能应用 |
| 种田、日常、温馨、治愈 | cozy | 日常/社区/布局/过渡/回收 | 关系深化、情感突破、技艺精通 |
| 地下城、地城 | dungeon-core | 策略/冒险者视角/布局/过渡/回收 | 陷阱成功、楼层扩展、仆从进化 |
| 东方修真 | cultivation | 修炼/突破/战斗/布局/过渡/回收 | 境界突破、功法大成、天劫渡过 |
| 通用回退 | other | 推进/布局/过渡/回收 | 目标达成、困难克服、真相揭示 |

### 添加新题材

在 `genres/` 目录下创建新 `.md` 文件，遵循 YAML frontmatter + Markdown body 格式：

```bash
# 预览提取结果
python3 scripts/seed_extractor.py --genre {新题材} --show

# 初始化题材进化目录
python3 scripts/seed_extractor.py --genre {新题材}
```

### 查看某题材进化状态

```bash
python3 scripts/prompt_evolver.py show --genre xianxia
python3 scripts/event_store.py list --genre xianxia
```

## 全部 CLI 命令

> **操作系统：** `evolve.sh` 用于 Linux/macOS，`evolve.ps1` 用于 Windows PowerShell。功能完全相同，参数格式略有差异（`--flag` vs `-Flag`）。下面以 bash 为例：

```bash
# === 进化编排 ===
bash scripts/evolve.sh                                    # 快速进化（自动检测项目）
# Windows: .\scripts\evolve.ps1
bash scripts/evolve.sh --project /path/to/novel           # 指定项目
# Windows: .\scripts\evolve.ps1 -Project /path/to/novel
bash scripts/evolve.sh --project /path/to/novel --full    # 完整进化
# Windows: .\scripts\evolve.ps1 -Project /path/to/novel -Full
bash scripts/evolve.sh --project /path/to/novel --report  # 状态报告
# Windows: .\scripts\evolve.ps1 -Project /path/to/novel -Report
bash scripts/evolve.sh --project /path/to/novel --compile # 从事件重建
# Windows: .\scripts\evolve.ps1 -Project /path/to/novel -Compile

# === 提示词进化 ===
python3 scripts/prompt_evolver.py evolve                      # 技能级进化
python3 scripts/prompt_evolver.py evolve --genre xianxia -g 5 # 题材级进化
python3 scripts/prompt_evolver.py evolve --project /path/to/novel  # 自动检测题材
python3 scripts/prompt_evolver.py show                        # 查看技能级最优
python3 scripts/prompt_evolver.py show --genre xianxia        # 查看某题材最优

# === 质量阈值 ===
python3 scripts/quality_tuner.py show                             # 当前阈值
python3 scripts/quality_tuner.py analyze --project /path/to/novel # 分析
python3 scripts/quality_tuner.py tune --project /path/to/novel    # 分析并应用


# === 事件溯源 ===
python3 scripts/event_store.py compile --genre other    # 编译 population
python3 scripts/event_store.py list --genre other       # 列出事件摘要

# === 种子提取 ===
python3 scripts/seed_extractor.py --genre xianxia --show   # 预览某题材种子
python3 scripts/seed_extractor.py --genre urban             # 初始化某题材进化目录

# === 模式挖掘 ===
python3 scripts/pattern_mine.py show --top 10
python3 scripts/pattern_mine.py mine --project /path/to/novel
```

## 关键文件参考

| 文件 | 用途 |
|------|------|
| `SKILL.md` | 技能主入口（197行），铁律+总写作流程+场景路由+紧凑版流程 |
| `WORKFLOWS.md` | 完整流程展开（题材诊断/深度问诊/大纲共创/续写/质检体系等）|
| `REFERENCE.md` | 理论与参考（三根支柱/四维引擎/自优化系统详解/语言规则）|
| `README.md` | 本文件，用户手册 |
| `scripts/evolve.sh` | 进化编排器入口 (Linux/macOS)，自动检测项目/题材 |
| `scripts/evolve.ps1` | 进化编排器入口 (Windows PowerShell)，功能与 .sh 完全相同 |
| `scripts/prompt_evolver.py` | 岛屿模型 + 遗传算法 + 早停 + 灭绝 |
| `scripts/seed_extractor.py` | 内置15题材配置 → 5岛种子提取 |
| `scripts/event_store.py` | 事件溯源引擎（编译/写入/列出事件） |
| `scripts/quality_tuner.py` | 质量阈值自适应调优 |
| `scripts/pattern_mine.py` | MAP-Elites 写作模式挖掘 |
| `scripts/utils.py` | 共享工具（路径解析/题材映射/持久化）|

## 常见问题

### Claude Code 提示"技能未找到"

确认技能已安装到正确路径：
- Linux/macOS: `~/.claude/skills/novel-write/SKILL.md`
- Windows: `%USERPROFILE%\.claude\skills\novel-write\SKILL.md`

如果使用软链接，确保链接目标存在且可读。

### git pull 失败

进化脚本在网络不通时自动降级为纯本地模式，不影响写作。手动重试：

```bash
cd ~/.claude/skills/novel-write && git pull
```

### 进化数据没有更新

```bash
# 从事件重建编译产物
bash scripts/evolve.sh --project /path/to/novel --compile
```

如果题材尚无任何事件，compile 会自动从内置种子初始化。

### 新增题材后进化不生效

1. 确认题材配置文件在 `genres/` 目录下，格式为 YAML frontmatter + Markdown body
2. 运行 `python3 scripts/seed_extractor.py --genre {新题材}` 初始化题材进化目录
3. 写下一章时，技能会自动识别 `项目铁律.md` 中的 `genre` 字段并匹配

### 换新设备后如何恢复

1. 克隆仓库到技能目录
2. 克隆你的小说项目
3. 首次写作时 `evolve.sh` 自动检测缺失的编译产物，从事件重建
4. 无需手动操作

### 小说项目目录可以放在哪里

任意位置。写作时告诉 Claude Code 项目路径即可。推荐放在独立的工作目录而非技能目录内。

### 如何贡献新题材

1. 在 `genres/` 目录下创建新 `.md` 文件，参考现有题材格式
2. 运行 `python3 scripts/seed_extractor.py --genre {新题材} --show` 预览提取结果
3. 运行 `python3 scripts/seed_extractor.py --genre {新题材}` 初始化进化目录
4. 提交 PR，只包含 `genres/` 下的新文件和进化事件文件

题材配置文件格式：
```yaml
---
genre_id: xinxitai
display_name: "新题材"
chapter_types: ["类型A", "类型B", "过渡", "回收"]
pleasure_points: ["爽点1", "爽点2", "爽点3"]
seeds:
  writing: |
    写作规则提示词...
  revision: |
    修稿规则提示词...
  quality_check: |
    质检标准提示词...
  outline: |
    大纲规则提示词...
  hook_management: |
    伏笔管理提示词...
---
```

## 参考来源

- [InkOS](https://github.com/Narcooo/inkos) — 题材配置、37维质检、伏笔全生命周期
- [OpenEvolve](https://github.com/codelion/openevolve) — MAP-Elites、岛屿模型、双选择