ZF-novel-writer

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的模型生成内容。

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

【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

bash

# 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

text

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

text

┌─────────────────────────────────────────────┐
│ 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):

python

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

Quality Agent (Spawned):

python

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

6. Data Architecture

canon_bible.json — Central continuity database:

json

{
  "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:

text

# 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. 快速开始

bash

# 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. 工作流程

text

步骤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）：

text

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

Quality Agent（spawned）：

text

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 输出格式

text

# 章节标题

[章节正文：3000-3500字]

【下一章预告】
简短悬念预告（≤30字）

【变量更新】
本章变量变化（可选）

【本章创建的铺垫 (setups)】
铺垫列表（可选JSON）

【本章兑现的铺垫 (payoffs)】
兑现列表（可选JSON）