ZF-novel-writer

Three-agent collaborative novel writing system. Orchestrator plans chapters, Writer Agent generates content via coding agent (sessions_spawn), Quality Agent...

Security Scan

The skill's files, instructions, and requested resources are coherent with a multi-agent novel-writing tool: it reads/writes local book files, spawns writer/quality sub‑agents, runs included Python tools, and does not request unrelated credentials or installs.

Purpose & Capability

Name/description (three-agent novel writer) match the provided code and SKILL.md. The repo contains planners, writer helpers, quality checks, archiving and canon/cosmos management—all consistent with long-form novel orchestration. No unrelated cloud credentials, binaries, or config paths are requested.

Instruction Scope

SKILL.md instructs the orchestrator to read story_outline.xlsx and Truth Files, spawn Writer/Quality agents via sessions_spawn, run Python tools, produce temp chapters, and update canon_bible.json and other meta files. This is in-scope for the stated purpose, but the agent will autonomously read and write files under books/{BOOK_NAME}/ and execute included Python tools (and spawn coding-agent runtimes). Users should be aware this involves executing bundled code and modifying project files.

Install Mechanism

No install spec is provided (instruction-only skill). That reduces supply-chain risk. The skill includes many Python scripts which would be executed from disk; no external downloads or URL-based install steps are present in the metadata.

Credentials

The skill declares no required environment variables or credentials, which is consistent. However some tools attempt to import optional modules (e.g., openpyxl, the local llm_api abstraction) and may call an LLM API if that module/config is present. If llm_api or other optional network-enabled modules exist in the environment, the tools could make outbound requests; these behaviors are not declared as required but are optional fallbacks in the code.

Persistence & Privilege

always:false (normal). The skill writes and updates files within book project directories (canon_bible.json, emotional_arcs.json, summaries_json, chapters/). That file I/O is appropriate to the purpose but does modify local project files — users should accept that the skill will persist changes to their books/ directories.

Assessment

This skill appears to be what it claims: a three-agent novel-writing pipeline that reads your story_outline.xlsx and Truth Files, spawns writer/quality sub-agents (sessions_spawn), runs bundled Python tools, and updates files in the book project. Before installing or running: 1) Review the tools/ Python files and README yourself (they will be executed and can modify files). 2) Back up any book directories you care about (canon_bible.json and chapters/) — the orchestrator will write/update them. 3) Be aware optional modules (e.g., openpyxl, any llm_api implementation) can enable network calls if present; if you do not want remote LLM calls, ensure llm_api or similar integrations are not installed or configured. 4) If you want tighter control, run the skill in a sandboxed environment or inspect/execute scripts manually rather than allowing autonomous agent spawning. Overall: coherent for its purpose but exercise standard caution because it executes bundled code and modifies local files.

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）