---

name: jiaos description: Autonomous novel writing CLI agent with web workbench (JiaOS Studio) - use for creative fiction writing, standalone short-fiction packages, cover generation, novel generation, style imitation, chapter continuation/import, EPUB export, AIGC detection, and fan fiction. Native English support with 10 built-in English genre profiles (LitRPG, Progression Fantasy, Isekai, Cultivation, System Apocalypse, Dungeon Core, Romantasy, Sci-Fi, Tower Climber, Cozy Fantasy). Also supports Chinese web novel genres (xuanhuan, xianxia, urban, horror, other). Multi-agent pipeline, two-phase writer (creative + settlement), stronger long-form chapter craft rules, hook-ledger payoff checks, 33-dimension auditing, token usage analytics, creative brief input, structured logging (JSON Lines), multi-model routing, custom OpenAI-compatible provider support, and JiaOS Studio web UI for visual book management, short-fiction runs, cover generation, chapter review, real-time writing progress, market radar, and analytics. version: 2.3.4 metadata: { "openclaw": { "emoji": "📖", "requires": { "bins": ["jiaos", "node"], "env": ["OPENAI_API_KEY"] }, "primaryEnv": "OPENAI_API_KEY", "homepage": "https://github.com/zxerai/jiaos", "install": [{ "id": "npm", "kind": "node", "package": "@actalk/jiaos", "label": "Install JiaOS (npm)" }] } }

JiaOS - Autonomous Novel Writing Agent

JiaOS is a CLI tool for autonomous fiction writing powered by LLM agents. It orchestrates a multi-agent pipeline (Radar → Planner → Composer → Architect → Writer → Observer → Reflector → Normalizer → Auditor → Reviser) to generate, audit, and revise novel content with zero human intervention per chapter.

The pipeline operates in three phases:

• Phase 1 (Creative Writing, temp 0.7): Planner generates chapter intent with hook agenda, Composer selects relevant context, Writer produces prose with length governance, first-screen hooks, semantic density, hook-ledger payoff, and mobile paragraph rhythm guidance.
• Phase 2 (State Settlement, temp 0.3): Observer over-extracts 9 categories of facts, Reflector outputs a JSON delta (not full markdown), code-layer applies Zod schema validation and immutable state update. Hook operations use upsert/mention/resolve/defer semantics.
• Phase 3 (Quality Loop): Normalizer adjusts chapter length, Auditor runs 33-dimension check including hook health analysis, Reviser auto-fixes critical issues. Self-correction loop runs until all critical issues clear.

Truth files are persisted as schema-validated JSON (story/state/*.json) with markdown projections for human readability. SQLite temporal memory database (story/memory.db) enables relevance-based retrieval on Node 22+.

When to Use JiaOS

• English novel writing: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set --lang en
• Chinese web novel writing: 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other)
• Fan fiction: Create fanfic from source material with 4 modes (canon, au, ooc, cp)
• Batch chapter generation: Generate multiple chapters with consistent quality
• Import & continue: Import existing chapters from a text file, reverse-engineer truth files, and continue writing
• Style imitation: Analyze and adopt writing styles from reference texts
• Spinoff writing: Write prequels/sequels/spinoffs while maintaining parent canon
• Standalone short fiction: Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image
• Cover generation: Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing
• Quality auditing: Detect AI-generated content and perform 33-dimension quality checks
• Genre exploration: Explore trends and create custom genre rules
• Analytics: Track word count, audit pass rate, and issue distribution per book

Initial Setup

First Time Setup

# Initialize a project directory (creates config structure)
jiaos init my-writing-project

# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)
# Prefer --api-key-env so the key never appears in shell history:
export OPENAI_API_KEY=sk-xxx
jiaos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o
# For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints:
# jiaos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o

Multi-Model Routing (Optional)

# Assign different models to different agents — balance quality and cost
jiaos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY
jiaos config set-model auditor gpt-4o --provider openai
jiaos config show-models

Agents without explicit overrides fall back to the global model.

Provider setup tip

When the user needs an aggregator provider, point them to Studio's service settings. JiaOS includes kkaiapi and OpenRouter as optional aggregator choices. For kkaiapi, use:

• Chinese website: https://kkaiapi.com/
• English website: https://en.kkaiapi.com/
• Chinese API docs: https://kkaiapi.com/docs
• English API docs: https://en.kkaiapi.com/docs
• Chinese models/pricing: https://kkaiapi.com/models
• English models/pricing: https://en.kkaiapi.com/models

View System Status

# Check installation and configuration
jiaos doctor

# View current config
jiaos status

Common Workflows

Workflow 1: Create a New Novel

1. Initialize and create book:

   jiaos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000
   # Or with a creative brief (your worldbuilding doc / ideas):
   jiaos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md
   

   • Genres: xuanhuan (cultivation), xianxia (immortal), urban (city), horror, other
   • Returns a book-id for all subsequent operations

2. Generate initial chapters (e.g., 5 chapters):

   jiaos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"
   

   • The write next command runs the full pipeline: draft → audit → revise
   • --context provides guidance to the Architect and Writer agents
   • Returns JSON with chapter details and quality metrics

3. Review and approve chapters:

   jiaos review list book-id
   jiaos review approve-all book-id
   

4. Export the book (supports txt, md, epub):

   jiaos export book-id
   jiaos export book-id --format epub
   

Workflow 2: Continue Writing Existing Novel

1. List your books:

   jiaos book list
   

2. Continue from last chapter:

   jiaos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"
   

   • JiaOS maintains 7 truth files (world state, character matrix, emotional arcs, etc.) for consistency
   • If only one book exists, omit book-id for auto-detection

3. Review and approve:

   jiaos review approve-all
   

Workflow 2.5: Shared Natural-Language Control (Recommended For OpenClaw)

When JiaOS is being driven by OpenClaw or another external agent, prefer the shared interaction executor instead of stitching together many ad-hoc CLI calls:

jiaos interact --json --message "continue the current book, but keep the pacing tighter"
jiaos interact --json --message "rewrite chapter 3"
jiaos interact --json --book my-book --message "switch to auto mode"

This returns a structured payload containing:

• the routed request
• assistant response text
• updated interaction session
• execution state
• pending decision
• recent interaction events

Use this as the primary OpenClaw entry because it shares the same control layer as the project TUI.

Workflow 2.6: Steering Chapter Focus Before Writing

Use this when the user says things like "pull focus back to the mentor conflict", "pause the merchant guild subplot", or "change what the next chapter should prioritize".

1. Update the book-level control docs when needed:

   • Use update_author_intent to change the long-horizon identity of the book
   • Use update_current_focus to change the next 1-3 chapters' focus

2. Compile the next chapter intent:

   plan_chapter(bookId, guidance?)
   

   • Generates story/runtime/chapter-XXXX.intent.md
   • Use this to verify what the system thinks the next chapter should do

3. Compose the actual runtime input package:

   compose_chapter(bookId, guidance?)
   

   • Generates story/runtime/chapter-XXXX.context.json
   • Generates story/runtime/chapter-XXXX.rule-stack.yaml
   • Generates story/runtime/chapter-XXXX.trace.json

4. Only then write:

   • write_draft if the user wants intermediate review
   • write_full_pipeline if they want the usual write → audit → revise flow

Recommended orchestration:

• user asks to redirect focus
• update_current_focus
• plan_chapter
• compose_chapter
• inspect the resulting intent/paths
• write_draft or write_full_pipeline

Workflow 3: Import Existing Chapters & Continue

Use this when you have an existing novel (or partial novel) and want JiaOS to pick up where it left off.

1. Import from a single text file (auto-splits by chapter headings):

   jiaos import chapters book-id --from novel.txt
   

   • Automatically splits by 第X章 pattern
   • Custom split pattern: --split "Chapter\\s+\\d+"

2. Import from a directory of separate chapter files:

   jiaos import chapters book-id --from ./chapters/
   

   • Reads .md and .txt files in sorted order

3. Resume interrupted import:

   jiaos import chapters book-id --from novel.txt --resume-from 15
   

4. Continue writing from the imported chapters:

   jiaos write next book-id --count 3
   

   • JiaOS reverse-engineers all 7 truth files from the imported chapters
   • Generates a style guide from the existing text
   • New chapters maintain consistency with imported content

Workflow 4: Style Imitation

1. Analyze reference text:

   jiaos style analyze reference_text.txt
   

   • Examines vocabulary, sentence structure, tone, pacing

2. Import style to your book:

   jiaos style import reference_text.txt book-id --name "Author Name"
   

   • All future chapters adopt this style profile
   • Style rules become part of the Reviser's audit criteria

Workflow 5: Spinoff/Prequel Writing

1. Import parent canon:

   jiaos import canon spinoff-book-id --from parent-book-id
   

   • Creates links to parent book's world state, characters, and events
   • Reviser enforces canon consistency

2. Continue spinoff:

   jiaos write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20"
   

Workflow 6: Fine-Grained Control (Draft → Audit → Revise)

If you need separate control over each pipeline stage:

1. Generate draft only:

   jiaos draft book-id --words 3000 --context "protagonist escapes" --json
   

2. Audit the chapter (33-dimension quality check):

   jiaos audit book-id chapter-1 --json
   

   • Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more

3. Revise with specific mode:

   jiaos revise book-id chapter-1 --mode polish --json
   

   • Modes: polish (minor), spot-fix (targeted), rewrite (major), rework (structure), anti-detect (reduce AI traces)

Workflow 7: Monitor Platform Trends

jiaos radar scan

• Analyzes trending genres