InkOS
Multi-Agent Novel Production System
中文 | English
---
Open-source multi-agent system that autonomously writes, audits, and revises novels — with human review gates that keep you in control.
## v0.3 Update (2026-03-13)
Three-layer rule separation: core guardrails → genre-specific rules → per-book custom rules.
### Genre Customization
5 built-in genres, each with a complete set of writing rules: chapter types, prohibition lists, fatigue words, language rules, and audit dimensions.
| Genre | Built-in Rules |
|-------|---------------|
| Xuanhuan (Fantasy) | Numerical system, power scaling, same-type absorption decay formula, face-slap/upgrade/payoff pacing |
| Xianxia (Cultivation) | Cultivation/enlightenment pacing, artifact system, heavenly dao rules |
| Urban | Era research, business/social-driven plot, era-matched legal terminology, no numerical system |
| Horror | Atmosphere progression, fear levels, restrained narration, no power scaling audit |
| General | Minimal fallback |
Specify a genre when creating a book and matching rules activate automatically:
```bash
inkos book create --title "Devouring Emperor" --genre xuanhuan
```
View, copy, or create genre rules:
```bash
inkos genre list # List all genres
inkos genre show xuanhuan # View full xuanhuan rules
inkos genre copy xuanhuan # Copy to project for customization
inkos genre create wuxia --name Wuxia # Create a new genre from scratch
```
After copying to your project, add/remove prohibitions, adjust fatigue words, modify pacing rules, customize language rules — changes take effect on the next chapter.
Each genre has dedicated language rules (with bad → good examples), enforced by both writer and auditor:
- **Xuanhuan**: ✗ "Fire essence increased from 12 to 24 wisps" → ✓ "His arm felt stronger than before, knuckles tightening into a fist"
- **Urban**: ✗ "Quickly analyzed the current debt situation" → ✓ "Flipped through the stack of wrinkled IOUs three times"
- **Horror**: ✗ "Felt a wave of fear" → ✓ "The hairs on the back of his neck stood up one by one"
### Per-Book Rules
Each book has its own `book_rules.md`, auto-generated by the Architect agent when creating a book — also editable anytime. Rules here are injected into every chapter's prompt:
```yaml
protagonist:
name: Lin Jin
personalityLock: ["ruthlessly calm", "patient but lethal", "smart, not reckless"]
behavioralConstraints: ["no mercy, no hesitation", "warm to allies but never sentimental"]
numericalSystemOverrides:
hardCap: 840000000
resourceTypes: ["particles", "bloodline density", "spirit stones"]
prohibitions:
- protagonist goes soft at critical moments
- pointless harem romance dragging the plot
- side characters stealing the spotlight
fatigueWordsOverride: ["pupils constricted", "disbelief"] # Override genre defaults
```
Protagonist personality lock, numerical caps, custom prohibitions, fatigue word overrides — each book's rules are independent, without affecting the genre template.
### 19-Dimension Audit
Auditing is broken down into 19 dimensions, with genre-appropriate subsets auto-enabled:
OOC check, timeline, setting conflicts, foreshadowing, pacing, writing style, information leaking, vocabulary fatigue, broken interest chains, side character intelligence drops, side character tool-ification, hollow payoffs, dialogue authenticity, padding detection, knowledge base contamination, POV consistency, power scaling collapse, numerical verification, era research
Xuanhuan/Xianxia: all 19 dimensions. Urban: 17 dimensions (including era research). Horror: 15 dimensions.
### De-AI-ification
5 universal rules + genre-specific language rules to control AI marker word density and narration habits:
- AI marker word frequency limit: "as if" / "suddenly" / "unexpectedly" / "couldn't help but" — max 1 per 3,000 words
- Narrator never draws conclusions for the reader, only writes actions
- No analytical report language ("core motivation", "information gap" never appear in prose)
- Same imagery rendered no more than twice
- Methodology jargon stays out of prose
Vocabulary fatigue audit simultaneously checks marker word density — exceeding threshold triggers a warning.
### Other
- Supports OpenAI + Anthropic native + all OpenAI-compatible endpoints
- Reviser supports polish / rewrite / rework modes
- Genres without numerical systems skip resource ledger generation
- All commands support `--json` structured output for OpenClaw / external agent integration
- Auto-detect book-id when project has only one book
- `inkos update` for self-updating, `inkos init` supports current directory
- API errors include diagnostic hints, `inkos doctor` includes connectivity test
---
## Why InkOS?
Writing a novel with AI isn't just "prompt and paste." Long-form fiction breaks down fast: characters forget things, items appear from nowhere, the same adjectives repeat every paragraph, and plot threads silently die. InkOS treats these as engineering problems.
- **Canonical truth files** — track the real state of the world, not what the LLM hallucinates
- **Anti-information-leaking** — characters only know what they've actually witnessed
- **Resource decay** — supplies deplete and items break, no infinite backpacks
- **Vocabulary fatigue detection** — catches overused words before readers do
- **Auto-revision** — fixes math errors and continuity breaks before human review
## How It Works
Each chapter is produced by five agents in sequence:
| Agent | Responsibility |
|-------|---------------|
| **Radar** | Scans platform trends and reader preferences to inform story direction (pluggable, skippable) |
| **Architect** | Plans chapter structure: outline, scene beats, pacing targets |
| **Writer** | Produces prose from the plan + current world state |
| **Continuity Auditor** | Validates the draft against canonical truth files |
| **Reviser** | Fixes issues found by the auditor — auto-fixes critical problems, flags others for human review |
If the audit fails, the pipeline automatically enters a revise → re-audit loop until all critical issues are resolved.
### Canonical Truth Files
Every book maintains three files as the single source of truth:
| File | Purpose |
|------|---------|
| `current_state.md` | World state: character locations, relationships, knowledge, emotional arcs |
| `particle_ledger.md` | Resource accounting: items, money, supplies with quantities and decay tracking |
| `pending_hooks.md` | Open plot threads: foreshadowing planted, promises to readers, unresolved conflicts |
The Continuity Auditor checks every draft against these files. If a character "remembers" something they never witnessed, or pulls a weapon they lost two chapters ago, the auditor catches it.
### Writing Rule System
The Writer agent has ~25 universal writing rules (character craft, narrative technique, logical consistency, language constraints, de-AI-ification), applicable to all genres.
On top of that, each genre has dedicated rules (prohibitions, language rules, pacing, audit dimensions), and each book has its own `book_rules.md` (protagonist personality, numerical caps, custom prohibitions) and `story_bible.md` (worldbuilding), auto-generated by the Architect agent.
See [v0.3 Update](#v03-update-2026-03-13) for details.
## Three Usage Modes
InkOS provides three interaction modes, all sharing the same atomic operations:
### 1. Full Pipeline (One Command)
```bash
inkos write next my-book # Draft → audit → auto-revise, all in one
inkos write next my-book --count 5 # Write 5 chapters in sequence
```
### 2. Atomic Commands (Composable, External Agent Friendly)
```bash
inkos draft my-book --context "Focus on master-disciple conflict" --json
inkos audit my-book 31 --json
inkos revise my-book 31 --json
```
Each command performs a single operation independently. `--json` outputs structured data. Can be called by OpenClaw or other AI agents via `exec`, or used in scripts.
### 3. Natural Language Agent Mode
```bash
inkos agent "Write an urban cultivation novel with a programmer protagonist"
inkos agent "Write the next chapter, focus on master-disciple conflict"
inkos agent "Scan market trends first, then create a new book based on results"
```
9 built-in tools (write_draft, audit_chapter, revise_chapter, scan_market, create_book, get_book_status, read_truth_files, list_books, write_full_pipeline), with the LLM deciding call order via tool-use.
## Quick Start
### Install
```bash
npm i -g @actalk/inkos
```
### Configure
**Option 1: Global config (recommended, one-time setup)**
```bash
inkos config set-global \
--provider openai \
--base-url https://api.openai.com/v1 \
--api-key sk-xxx \
--model gpt-4o
```
Saved to `~/.inkos/.env`, shared by all projects. New projects just work without extra config.
**Option 2: Per-project `.env`**
```bash
inkos init my-novel # Initialize project
# Edit my-novel/.env
```
```bash
# Required
INKOS_LLM_PROVIDER=openai # openai / anthropic
INKOS_LLM_BASE_URL=https://api.openai.com/v1 # API endpoint (proxy-friendly)
INKOS_LLM_API_KEY=sk-xxx # API Key
INKOS_LLM_MODEL=gpt-4o # Model name
# Optional
# INKOS_LLM_TEMPERATURE=0.7 # Temperature
# INKOS_LLM_MAX_TOKENS=8192 # Max output tokens
# INKOS_LLM_THINKING_BUDGET=0 # Anthropic extended thinking budget
```
Project `.env` overrides global config. Skip it if no override needed.
### Usage
```bash
inkos book create --title "Devouring Emperor" --genre xuanhuan # Create a book
inkos write next my-book # Write next chapter (full pipeline)
inkos status # Check status
inkos review list my-book # Review drafts
inkos export my-book # Export full book
inkos up # Daemon mode
```
## CLI Reference
| Command | Description |
|---------|-------------|
| `inkos init [name]` | Initialize project (omit name to init current directory) |
| `inkos book create` | Create a new book (generates worldbuilding + outline + book rules) |
| `inkos book list` | List all books |
| `inkos genre list/show/copy/create` | View, copy, or create genres |
| `inkos write next [id]` | Full pipeline: write next chapter |
| `inkos write rewrite [id] ` | Rewrite chapter N (restores state snapshot, requires confirmation) |
| `inkos draft [id]` | Write draft only (no audit or revision) |
| `inkos audit [id] [n]` | Audit a specific chapter |
| `inkos revise [id] [n]` | Revise a specific chapter |
| `inkos agent ` | Natural language agent mode |
| `inkos review list [id]` | Review drafts |
| `inkos review approve-all [id]` | Batch approve |
| `inkos status [id]` | Project status |
| `inkos export [id]` | Export book to txt/md |
| `inkos radar scan` | Scan platform trends |
| `inkos config set-global` | Set global LLM config (~/.inkos/.env) |
| `inkos config show-global` | Show global config |
| `inkos config set/show` | View/update project config |
| `inkos doctor` | Diagnose setup issues (includes API connectivity test) |
| `inkos update` | Update to latest version |
| `inkos up / down` | Start/stop daemon |
`[id]` is auto-detected when the project has only one book. All commands support `--json` for structured output. `draft`/`write next`/`book create` support `--context` for writing guidance.
## Key Features
### State Snapshots + Chapter Rewrite
Every chapter automatically creates a state snapshot. Use `inkos write rewrite ` to roll back and regenerate any chapter — world state, resource ledger, and plot hooks all restore to the pre-chapter state.
### Write Lock
File-based locking prevents concurrent writes to the same book.
### Pre-Write Checklist + Post-Write Settlement
The Writer agent outputs a pre-write checklist before writing (context scope, current resources, pending hooks, conflict overview, risk scan), and a settlement table after writing (resource changes, hook changes). The Auditor cross-validates the settlement table against prose content.
### Pluggable Radar
Radar data sources are pluggable via the `RadarSource` interface. Built-in sources for Tomato Novel and Qidian. Custom data sources or skipping radar entirely are both supported.
### Daemon Mode
`inkos up` starts an autonomous background loop that writes chapters on a schedule. The pipeline runs fully unattended for non-critical issues, but pauses for human review when the auditor flags problems it cannot auto-fix.
### Notifications
Telegram, Feishu, and WeCom. In daemon mode, get notified on your phone when a chapter is done or an audit fails.
### External Agent Integration
Atomic commands + `--json` output make InkOS callable by OpenClaw and other AI agents. OpenClaw executes `inkos draft`/`audit`/`revise` via `exec`, reads JSON results, and decides next steps.
## Architecture
```
inkos/
├── packages/
│ ├── core/ # Agent runtime, pipeline, state management
│ │ ├── agents/ # architect, writer, continuity, reviser, radar
│ │ ├── pipeline/ # runner (atomic ops + full pipeline), agent (tool-use), scheduler
│ │ ├── state/ # File-based state manager
│ │ ├── llm/ # OpenAI + Anthropic dual SDK (streaming)
│ │ ├── notify/ # Telegram, Feishu, WeCom
│ │ └── models/ # Zod schema validation
│ └── cli/ # Commander.js CLI (16 commands)
│ └── commands/ # init, book, write, draft, audit, revise, agent, review, status, export...
└── (planned) studio/ # Web UI for review and editing
```
TypeScript monorepo managed with pnpm workspaces.
## Roadmap
- [x] Full pipeline (radar → architect → writer → auditor → reviser)
- [x] Canonical truth files + continuity audit
- [x] Built-in writing rule system
- [x] Full CLI (16 commands)
- [x] State snapshots + chapter rewrite
- [x] Daemon mode
- [x] Notifications (Telegram / Feishu / WeCom)
- [x] Atomic commands + JSON output (draft / audit / revise)
- [x] Natural language agent mode (tool-use orchestration)
- [x] Pluggable radar (RadarSource interface)
- [x] External agent integration (OpenClaw, etc.)
- [x] Genre customization + per-book rules (genre CLI + book_rules.md)
- [x] 19-dimension continuity audit
- [x] De-AI-ification rules
- [x] Multi-LLM provider (OpenAI + Anthropic + compatible endpoints)
- [ ] AI detection review (AIGC detection + auto-rewrite to reduce detection rate)
- [ ] `packages/studio` Web UI for review and editing
- [ ] Multi-model routing (different models for different agents)
- [ ] Custom agent plugin system
- [ ] Platform-specific export (Qidian, Tomato, etc.)
## Contributing
Contributions welcome. Open an issue or PR.
```bash
pnpm install
pnpm dev # Watch mode for all packages
pnpm test # Run tests
pnpm typecheck # Type-check without emitting
```
## License
[MIT](LICENSE)