voocel/ainovel-cli

ainovel‑cli – 自动化长篇小说创作引擎

What it is – ainovel-cli is a command‑line (and optional TUI) application that orchestrates multiple LLM agents to write a complete novel without human intervention. It combines a deterministic “engine” that decides what to do with three autonomous agents (Architect, Writer, Editor) that actually generate text, plus a lightweight Arbiter that makes occasional semantic decisions.

Key ideas

• Deterministic control flow – The Engine reads a JSON‑style store, follows a static routing table and dispatches workers. No LLM calls are made for control logic, making the process fully reproducible and testable.
• Three creative agents
  • Architect – builds the book’s title, premise, outline, character sheets and world rules.
  • Writer – for each chapter runs a fixed pipeline: load context → read previous chapter → plan the chapter → draft → consistency check → commit.
  • Editor – reviews finished chapters on seven quality dimensions (consistency, pacing, foreshadowing, hooks, aesthetic quality, etc.) and can trigger rewrites or polishing.
• Arbiter – a single‑call LLM function that decides which planner to use, how to handle user‑injected edits, or how to escape a dead‑end. Its decisions are logged and can be replayed.
• Rolling‑window planning – Only the first two “volumes” and the first “arc” are planned up‑front. As the story progresses the Architect expands the next arc/volume using summaries and character snapshots, avoiding the “plan‑everything‑once” problem of very long works.
• Context management for 500+ chapters – Hierarchical summarisation (chapter → arc → volume) plus a smart‑recommendation system that pulls relevant earlier chapters based on foreshadowing, character appearances, state changes and relationships.
• Checkpoint & recovery – After each tool finishes, a checkpoint is written. Crashes can be resumed at the exact step (plan/draft/check/commit) without losing progress.
• Interactive & headless modes – A curses‑based TUI lets users watch and inject edits in real time; a --headless flag runs unattended on servers, CI pipelines or NAS boxes.
• Multi‑model support – Works with OpenRouter, Anthropic, Gemini, OpenAI, Ollama, Bedrock, etc. Different agents can be assigned different providers/models via the roles section of the config.

How it works (high‑level flow)

User prompt → Arbiter selects Architect → Architect creates skeleton & first arc →
Writer iteratively writes chapters → Editor reviews each arc →
If needed, Writer rewrites / Editor polishes →
When an arc ends, Architect expands the next arc → repeat until the book is complete

All state (phases, flows, drafts, summaries, checkpoints) lives in a simple file‑system store under output/novel/.

Installation

# one‑liner for macOS / Linux (no Go needed)
curl -fsSL https://raw.githubusercontent.com/voocel/ainovel-cli/main/scripts/install.sh | sh

# or via Go
go install github.com/voocel/ainovel-cli/cmd/ainovel-cli@latest

The installer verifies a SHA‑256 manifest before extracting the binary. Windows users can download pre‑built releases.

Typical usage

• Interactive – Run ainovel-cli and follow the on‑screen wizard to pick a provider, enter an API key, and type a one‑sentence story idea.
• Headless – Ideal for long runs:

  ainovel-cli --headless --prompt "写一本东方玄幻长篇，主角从边陲小城起步"
  

  Logs go to logs/headless.log; the generated novel appears under output/novel/.
• Docker – Pull ghcr.io/voocel/ainovel-cli:latest and mount a config and workspace directory. Use -it for the TUI or run headless directly.

Configuration A JSONC file (~/.ainovel/config.json or ./.ainovel/config.json) stores:

• Provider selection and API credentials.
• Model list with optional per‑model context‑window sizes.
• Default reasoning effort (off/low/medium/high/xhigh/max).
• Role‑specific overrides (roles.writer, roles.architect, etc.) allowing cheap models for segmentation and expensive ones for creative writing.
• Style presets (default, suspense, fantasy, romance).
• Custom rule files (rules/*.md) to suppress “AI tone” or enforce author‑specific preferences without touching code.

Import / Export

• Import (/import <file>) ingests an existing novel, segments it with an LLM, extracts facts, builds a new foundation and then continues writing.
• Export (/export) writes the completed chapters to a plain‑text .txt or an .epub file, stripping internal metadata.

Diagnostics /diag produces a markdown report covering workflow health, quality scores, planning status, and context consistency. The report is also saved (anonymised) as meta/diag-export.md for easy bug reporting.

Who might use it

• Authors who want a “co‑author” that can generate massive drafts and keep long‑range plot consistency.
• Game designers needing extensive lore or quest narratives.
• Researchers exploring multi‑agent LLM orchestration and deterministic pipelines.

Limitations

• The system relies on external LLM APIs; cost and rate limits depend on the chosen provider.
• Quality still hinges on the prompts and the underlying models – the built‑in editor can only flag issues, not guarantee literary merit.
• Currently focused on Chinese language generation (token‑estimation logic mentions CJK), though the architecture is language‑agnostic.

---

TL;DR – ainovel-cli is a Go‑based CLI/TUI that runs a deterministic engine coordinating three LLM agents (Architect, Writer, Editor) plus an Arbiter to automatically draft, review, and polish long‑form novels (500+ chapters). It offers checkpointed recovery, hierarchical context summarisation, multi‑model support, Docker images, and rich configuration without needing to write code.