Skills

自主小说写作 CLI 代理 - 用于创意小说写作、小说生成、风格模仿、章节延续/导入、EPUB 导出、AIGC 检测和同人小说。母语英语支持，具有 10 个内置英语类型配置文件（LitRPG、Progression Fantasy、Isekai、Cultivation、System Apocalypse、Dungeon Core、Romantasy、Sci-Fi、Tower Climber、Cozy Fantasy）。还支持中国网络小说类型（玄幻、仙侠、都市、恐怖等）。多代理管道、两阶段编写器（创意 + 结算）、33 维审计、代币使用分析、创意概要输入、结构化日志记录（JSON Lines）、多模型路由和自定义 OpenAI 兼容提供商支持。

## 概述（中文）

自主小说写作 CLI 代理 - 用于创意小说写作、小说生成、风格模仿、章节延续/导入、EPUB 导出、AIGC 检测和同人小说。母语英语支持，具有 10 个内置英语类型配置文件（LitRPG、Progression Fantasy、Isekai、Cultivation、System Apocalypse、Dungeon Core、Romantasy、Sci-Fi、Tower Climber、Cozy Fantasy）。还支持中国网络小说类型（玄幻、仙侠、都市、恐怖等）。多代理管道、两阶段编写器（创意 + 结算）、33 维审计、代币使用分析、创意概要输入、结构化日志记录（JSON Lines）、多模型路由和自定义 OpenAI 兼容提供商支持。

## 原文

# InkOS - Autonomous Novel Writing Agent

InkOS 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 and dialogue-driven 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 InkOS

- **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
- **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
```bash
# Initialize a project directory (creates config structure)
inkos init my-writing-project

# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)
inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o
# For compatible/proxy endpoints, use --provider custom:
# inkos config set-global --provider custom --base-url https://your-proxy.com/v1 --api-key sk-xxx --model gpt-4o
```

### Multi-Model Routing (Optional)
```bash
# Assign different models to different agents — balance quality and cost
inkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY
inkos config set-model auditor gpt-4o --provider openai
inkos config show-models
```
Agents without explicit overrides fall back to the global model.

### View System Status
```bash
# Check installation and configuration
inkos doctor

# View current config
inkos status
```

## Common Workflows

### Workflow 1: Create a New Novel

1. **Initialize and create book**:
   ```bash
   inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000
   # Or with a creative brief (your worldbuilding doc / ideas):
   inkos 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):
   ```bash
   inkos 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**:
   ```bash
   inkos review list book-id
   inkos review approve-all book-id
   ```

4. **Export the book** (supports txt, md, epub):
   ```bash
   inkos export book-id
   inkos export book-id --format epub
   ```

### Workflow 2: Continue Writing Existing Novel

1. **List your books**:
   ```bash
   inkos book list
   ```

2. **Continue from last chapter**:
   ```bash
   inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"
   ```
   - InkOS 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**:
   ```bash
   inkos review approve-all
   ```

### Workflow 2.5: 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**:
   ```text
   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**:
   ```text
   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 InkOS to pick up where it left off.

1. **Import from a single text file** (auto-splits by chapter headings):
   ```bash
   inkos 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:
   ```bash
   inkos import chapters book-id --from ./chapters/
   ```
   - Reads `.md` and `.txt` files in sorted order

3. **Resume interrupted import**:
   ```bash
   inkos import chapters book-id --from novel.txt --resume-from 15
   ```

4. **Continue writing** from the imported chapters:
   ```bash
   inkos write next book-id --count 3
   ```
   - InkOS 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**:
   ```bash
   inkos style analyze reference_text.txt
   ```
   - Examines vocabulary, sentence structure, tone, pacing

2. **Import style to your book**:
   ```bash
   inkos 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 cr