ZF-novel-writer

---

name: ZF-novel-writer description: > Three-agent collaborative novel writing system. Orchestrator plans chapters, Writer Agent generates content via coding agent (sessions_spawn), Quality Agent checks quality. Supports multi-book management, chapter archiving, Truth Files tracking, and story_outline.xlsx driven writing. No external API keys required - uses the host agent's model for content generation. 三Agent协作小说写作系统。Orchestrator规划章节，Writer Agent通过coding agent生成内容， Quality Agent检查质量。支持多书籍管理、章节归档、Truth Files追踪、story_outline.xlsx驱动写作。 无需额外API key——使用宿主agent的模型生成内容。 version: 1.0 author: Felix tags: [novel, writing, multi-agent, creative-writing, 小说, 写作, AI写作] triggers: - "write novel" - "写小说" - "生成章节" - "generate chapter" - "/novel"

---

帮你们测试过了一个男主八个女主再复杂再狗血的关系都能轻松难捏！自带🍅小说自动发布脚本。

【ZF-novel-writer】三Agent协作小说写作系统

🔥 亮点速览：

无需API Key — 全部通过 sessions_spawn 调用本地 coding agent，零配置开写

三Agent流水线 — Orchestrator 规划 → Writer 写作 → Quality 质检，全自动循环

串行执行架构 — 章节严格顺序推进，每章依赖前章的铺垫数据和 summary，杜绝逻辑断裂

前章末尾300字自动衔接 — 写下一章时自动提取上一章最后300字注入提示词，确保场景、情绪、节奏无缝过渡

Truth Files 连续性系统 — canonbible.json 追踪角色、纪元、铺垫/兑现，emotionalarcs.json 追踪情感弧线，角色状态跨章节一致

story_outline.xlsx 驱动 — 一张表定义全书结构（事件、爽点、悬念钩子），Writer Agent 严格按大纲执行

三大硬指标质检 — ① 3000-3500字/章 ② comprehensive_check.py 8项全过 ③ 评分≥90（S/A级），不达标自动重写根据 skill 文档和 config.json 的描述，comprehensive_check.py 包含 8 项质量检查：

1. 字数检查 — 3000-3500汉字（不含标点） 2. 格式检查 — 章节结构是否符合规范（标题、正文、预告等） 3. 逻辑检查 — 情节是否自洽、有无矛盾 4. 节奏检查 — 叙事节奏是否合理、有无拖沓或跳跃 5. 连续性检查 — 与 Truth Files（canon_bible 等）是否一致 6. 铺垫/兑现检查 — setups/payoffs 是否合理追踪 7. 角色一致性 — 角色行为、性格是否符合设定 8. 悬念钩子检查 — 章末是否有有效钩子

📊 写作流程： 抓取大纲+Truth Files → 生成章节规划 → Writer输出全文 → 质检打分 → 归档更新 → 下一章

🎯 适合：长篇网文、系统文、多线叙事，任何需要连续性和质量把控的创作场景

ZF-novel-writer / 三Agent协作小说写作系统

> ⚠️ No external API keys required. Content is generated by spawning coding agents (sessions_spawn) that use the host agent's model. > ⚠️ 无需额外API key。 通过 sessions_spawn 调用 coding agent，使用宿主agent的模型生成内容。

---

ENGLISH

1. Overview

ZF-novel-writer is a three-agent collaborative system for long-form novel writing:

| Agent | Role | How It Works | |-------|------|-------------| | Orchestrator | Plans chapters, coordinates agents | Main session. Reads story_outline.xlsx + Truth Files, generates chapter plans, spawns Writer/Quality agents, handles archiving | | Writer Agent | Generates chapter content | Spawned via sessions_spawn with mode="run". Receives chapter plan + context, outputs full chapter (3000-3500 words) | | Quality Agent | Quality checks | Spawned via sessions_spawn. Runs comprehensive_check.py, scores chapter, approves or requests rewrite |

Key Principles:

story_outline.xlsx is the Writer Agent's single source of truth for what to write

Truth Files (canon_bible.json, emotional_arcs.json, etc.) maintain continuity

Serial execution: One chapter at a time — archive complete before starting next

No API keys: Everything runs through the host OpenClaw instance

2. Quick Start

# 1. Copy example-book to your books directory
cp -r skills/ZF-novel-writer/example-book books/{YOUR_BOOK_NAME}
2. Edit canon_bible.json with your book's settings
3. Create/edit story_outline.xlsx with your chapter plans
4. Edit genre_rules.md, WORLD_SETTING.md for your world
5. Start writing
In OpenClaw, trigger: "写小说" or "/novel"
Orchestrator will handle everything automatically

3. Directory Structure

books/{BOOK_NAME}/
├── meta/
│   ├── canon_bible.json        # Core settings + continuity tracking
│   ├── emotional_arcs.json     # Character emotional states
│   └── character_matrix.json   # Character relationships
├── chapters/                   # Archived chapter text files
│   └── chapter-N_标题.txt
├── summaries_json/             # Per-chapter summary JSON
│   └── chapter_NNN.json
├── temp_chapters/              # Temporary output from Writer Agent
├── plans/                      # Chapter plans from Orchestrator
│   └── chapter_NNN_plan.json
├── genre_rules.md              # Genre-specific writing rules
├── WORLD_SETTING.md            # World building document
└── story_outline.xlsx          # Full book outline (chapter-by-chapter)
skills/ZF-novel-writer/
├── SKILL.md                    # This file
├── README.md                   # Project readme
├── config.json                 # Quality standards config
├── ORCHESTRATOR_ARCHIVE_GUIDE.md
├── example-book/               # Template book project
├── docs/
│   └── ARCHITECT_AGENT_DESIGN.md
└── tools/                      # Python tools for quality checks
    ├── simple_writer_enhanced.py
    ├── comprehensive_check.py
    ├── archive_chapter_with_truth.py
    ├── world_context_loader.py
    └── ... (see tools/README.md)

4. Workflow

┌─────────────────────────────────────────────┐
│ Step 1: PLAN (Orchestrator / Main Session)  │
│  • Read story_outline.xlsx                  │
│  • Read Truth Files (canon_bible, etc.)     │
│  • Generate chapter_NNN_plan.json           │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ Step 2: WRITE (Writer Agent)                │
│  • Spawn via sessions_spawn (mode="run")    │
│  • Read plan + story_outline + context      │
│  • Output: temp_chapters/chapter-N.txt      │
│  • Target: 3000-3500 words                  │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ Step 3: QC (Quality Agent)                  │
│  • Spawn via sessions_spawn                 │
│  • Run comprehensive_check.py               │
│  • Score ≥ 90 = PASS                        │
│  • Score < 90 = REWRITE → Step 2           │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ Step 4: ARCHIVE (Orchestrator)              │
│  • Update canon_bible.json                  │
│  • Create chapter_NNN.json summary          │
│  • Move to chapters/                        │
│  • Clean temp files                         │
└──────────────────┬──────────────────────────┘
                   ▼
              Next chapter → Step 1

5. Agent Configuration

Orchestrator (Main Session):

No spawn needed — this is the main conversation

Reads files, makes plans, spawns sub-agents, performs archiving

Writer Agent (Spawned):

sessions_spawn(
    task="Write chapter N based on plan and context...",
    agentId="writer",
    runtime="run"  # coding agent mode
)

Quality Agent (Spawned):

sessions_spawn(
    task="Quality check chapter N...",
    agentId="quality",
    runtime="run"
)

6. Data Architecture

canon_bible.json — Central continuity database:

{
  "version": "1.0",
  "book_name": "{BOOK_NAME}",
  "protagonist": { "name": "...", "description": "..." },
  "eras": [...],
  "heroines": { ... },
  "continuity": {
    "setups": [],
    "payoffs": [],
    "pending_setups": []
  }
}

story_outline.xlsx — Chapter-by-chapter outline: | Column | Description | |--------|-------------| | 章节 | Chapter number | | 标题 | Chapter title | | 主要事件 | Core events | | 地点 | Scene location | | 女主 | Appearing heroines | | 冲突类型 | Conflict type | | 系统提示 | System feedback | | 系统等级 | System level | | 爽点 | Expected payoff points | | 悬念钩子 | End-of-chapter hook |

7. Quality Standards — Three Hard Metrics

1. Word count: 3000-3500 Chinese characters (excluding punctuation) 2. All checks pass: comprehensive_check.py returns no errors 3. Score ≥ 90: Quality grade S or A

See config.json for detailed scoring criteria and penalties.

8. Tools Reference

See tools/README.md for complete tool documentation. Key tools:

| Tool | Purpose | |------|---------| | simple_writer_enhanced.py | Generate writing prompts with full context | | comprehensive_check.py | 8-item quality check (word count, format, logic, pacing, etc.) | | archive_chapter_with_truth.py | Archive chapter + update continuity | | world_context_loader.py | Load world settings + previous summaries | | chapter_planner.py | Generate chapter plans | | novel_planner.py | Generate full book outline |

9. Writer Agent Output Format

Writer Agent should output a single text file with this structure:

# Chapter Title
[Chapter body: 3000-3500 words of narrative]
【下一章预告】
Brief suspenseful teaser (≤30 words)
【变量更新】
Variable changes this chapter (optional)
【本章创建的铺垫 (setups)】
List of setups created (optional JSON)
【本章兑现的铺垫 (payoffs)】
List of payoffs resolved (optional JSON)

---

中文

1. 系统概述

ZF-novel-writer 是一个三Agent协作的长篇小说写作系统：

| Agent | 角色 | 工作方式 | |-------|------|---------| | Orchestrator | 规划章节、协调Agent | 主会话。读取 story_outline.xlsx + Truth Files，生成章节规划，spawn Writer/Quality Agent，处理归档 | | Writer Agent | 生成章节内容 | 通过 sessions_spawn 以 mode="run" 启动。接收章节规划+上下文，输出完整章节（3000-3500字） | | Quality Agent | 质量检查 | 通过 sessions_spawn 启动。运行 comprehensive_check.py，评分，通过或要求重写 |

核心理念：

story_outline.xlsx 是 Writer Agent 的唯一基本来源

Truth Files（canon_bible.json、emotional_arcs.json 等）维护连续性

串行执行： 每次只跑一个章节，归档完毕才开始下一章

无需API key： 全部通过宿主 OpenClaw 实例运行

2. 快速开始

# 1. 复制示例项目
cp -r skills/ZF-novel-writer/example-book books/{你的书名}
2. 编辑 canon_bible.json 设置你的小说
3. 创建/编辑 story_outline.xlsx 大纲
4. 编辑 genre_rules.md、WORLD_SETTING.md
5. 开始写作
触发词："写小说" 或 "/novel"

3. 目录结构

（与英文部分相同，见上方）

4. 工作流程

步骤1：规划（Orchestrator）
  → 读取 story_outline.xlsx + Truth Files
  → 生成 chapter_NNN_plan.json
步骤2：写作（Writer Agent）
  → sessions_spawn 启动
  → 输出到 temp_chapters/chapter-N.txt
  → 目标：3000-3500字
步骤3：质检（Quality Agent）
  → sessions_spawn 启动
  → 运行 comprehensive_check.py
  → 评分≥90 = 通过，<90 = 重写
步骤4：归档（Orchestrator）
  → 更新 canon_bible.json
  → 创建 chapter_NNN.json
  → 移动文件、清理临时文件
→ 下一章

5. Agent 配置

Orchestrator（主会话）： 无需 spawn，在主对话中执行

Writer Agent（spawned）：

sessions_spawn(task="写第N章...", agentId="writer", runtime="run")

Quality Agent（spawned）：

sessions_spawn(task="质检第N章...", agentId="quality", runtime="run")

6. 数据架构

canon_bible.json： 核心连续性数据库（角色、纪元、铺垫追踪）

story_outline.xlsx： 逐章大纲（章节、事件、爽点、悬念钩子等）

Truth Files： emotional_arcs.json、character_matrix.json 等

7. 质量标准 — 三大硬指标

1. 字数： 3000-3500汉字（不含标点） 2. 全部检查通过： comprehensive_check.py 无错误 3. 评分≥90： S级或A级

详细评分标准见 config.json。

8. 工具参考

见 tools/README.md 完整文档。

9. Writer Agent 输出格式

# 章节标题
[章节正文：3000-3500字]
【下一章预告】
简短悬念预告（≤30字）
【变量更新】
本章变量变化（可选）
【本章创建的铺垫 (setups)】
铺垫列表（可选JSON）
【本章兑现的铺垫 (payoffs)】
兑现列表（可选JSON）