inkos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

InkOS - Autonomous Novel Writing Agent

InkOS - 自主小说写作Agent

InkOS is a CLI tool for autonomous fiction writing powered by LLM agents. It orchestrates a 5-agent pipeline (Radar → Architect → Writer → Auditor → Reviser) to generate, audit, and revise novel content with style consistency and quality control.

The Writer uses a two-phase architecture: Phase 1 (creative writing, temp 0.7) produces the chapter text, then Phase 2 (state settlement, temp 0.3) updates all truth files for long-term consistency.

InkOS 是一款由LLM Agent驱动的自主小说写作CLI工具。它编排了5-Agent流水线（Radar → Architect → Writer → Auditor → Reviser）来生成、审核和修订小说内容，确保风格一致性与质量管控。

Writer采用双阶段架构：第一阶段（创意写作，温度0.7）生成章节文本，第二阶段（状态定型，温度0.3）更新所有Truth Files以保持长期一致性。

When to Use InkOS

何时使用InkOS

Novel writing: Create and continue writing novels/books in Chinese web novel genres
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

小说创作：创作并续写中文网文题材的小说/书籍
批量章节生成：生成质量一致的多章节内容
导入与续写：从文本文件导入已有章节，逆向生成Truth Files并继续写作
风格模仿：分析并借鉴参考文本的写作风格
衍生内容创作：创作前传/续集/衍生作品，同时保持原作设定一致性
质量审核：检测AI生成内容并执行33维度质量检查
题材探索：探索题材趋势并创建自定义题材规则
数据分析：追踪单本书的字数、审核通过率与问题分布

Initial Setup

初始设置

First Time Setup

首次设置

bash

undefined

bash

undefined

Initialize a project directory (creates config structure)

初始化项目目录（创建配置结构）

inkos init my-writing-project

Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)

配置LLM服务商（OpenAI、Anthropic或任何兼容OpenAI的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:

对于兼容/代理端点，使用--provider custom：

inkos config set-global --provider custom --base-url https://your-proxy.com/v1 --api-key sk-xxx --model gpt-4o

undefined

undefined

Multi-Model Routing (Optional)

多模型路由（可选）

bash

undefined

bash

undefined

Assign different models to different agents — balance quality and cost

为不同Agent分配不同模型——平衡质量与成本

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.

未显式覆盖模型的Agent将使用全局模型。

View System Status

查看系统状态

bash

undefined

bash

undefined

Check installation and configuration

检查安装与配置情况

inkos doctor

View current config

查看当前配置

inkos status

undefined

inkos status

undefined

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

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

Review and approve chapters:

bash

inkos review list book-id
inkos review approve-all book-id

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

bash

inkos export book-id
inkos export book-id --format epub

初始化并创建书籍：

bash

inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000
# 或附带创意大纲（你的世界观文档/想法）：
inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md

支持题材：
```
xuanhuan
```
（玄幻）、
```
xianxia
```
（仙侠）、
```
urban
```
（都市）、
```
horror
```
（恐怖）、
```
other
```
（其他）
返回
```
book-id
```
，用于后续所有操作

生成初始章节（例如5章）：
bash
```
inkos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"
```
- ```
write next
```
  命令运行完整流水线：草稿→审核→修订
- ```
--context
```
  为Architect和Writer Agent提供创作指引
- 返回包含章节详情与质量指标的JSON

审阅并批准章节：

bash

inkos review list book-id
inkos review approve-all book-id

导出书籍（支持txt、md、epub格式）：

bash

inkos export book-id
inkos export book-id --format epub

Workflow 2: Continue Writing Existing Novel

工作流2：续写已有小说

List your books:
bash
```
inkos book list
```
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
Review and approve:
bash
```
inkos review approve-all
```

列出你的书籍：
bash
```
inkos book list
```
从最后一章开始续写：
bash
```
inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"
```
- InkOS维护7个Truth Files（世界状态、人物矩阵、情感弧线等）以保持一致性
- 如果项目中只有一本书，可省略
```
book-id
```
  自动检测
审阅并批准：
bash
```
inkos review approve-all
```

Workflow 3: Import Existing Chapters & Continue

工作流3：导入已有章节并续写

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

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+"
```
Import from a directory of separate chapter files:
bash
```
inkos import chapters book-id --from ./chapters/
```
- Reads
```
.md
```
  and
```
.txt
```
  files in sorted order

Resume interrupted import:

bash

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

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

当你已有一部小说（或部分内容），希望InkOS继续创作时使用此工作流。

从单个文本文件导入（按章节标题自动拆分）：
bash
```
inkos import chapters book-id --from novel.txt
```
- 自动按
```
第X章
```
  模式拆分
- 自定义拆分模式：
```
--split "Chapter\\s+\\d+"
```
从目录导入独立章节文件：
bash
```
inkos import chapters book-id --from ./chapters/
```
- 按顺序读取
```
.md
```
  和
```
.txt
```
  文件

恢复中断的导入：

bash

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

从导入章节开始续写：
bash
```
inkos write next book-id --count 3
```
- InkOS从导入章节逆向生成全部7个Truth Files
- 从已有文本生成风格指南
- 新章节与导入内容保持一致性

Workflow 4: Style Imitation

工作流4：风格模仿

Analyze reference text:
bash
```
inkos style analyze reference_text.txt
```
- Examines vocabulary, sentence structure, tone, pacing
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 criteria

分析参考文本：
bash
```
inkos style analyze reference_text.txt
```
- 分析词汇、句式结构、语气、节奏
将风格导入你的书籍：
bash
```
inkos style import reference_text.txt book-id --name "Author Name"
```
- 未来所有章节将采用此风格配置
- 风格规则将成为Reviser的审核标准之一

Workflow 5: Spinoff/Prequel Writing

工作流5：衍生作品/前传创作

Import parent canon:
bash
```
inkos import canon spinoff-book-id --from parent-book-id
```
- Creates links to parent book's world state, characters, and events
- Reviser enforces canon consistency

Continue spinoff:

bash

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

导入原作设定：
bash
```
inkos import canon spinoff-book-id --from parent-book-id
```
- 关联衍生作品与原作的世界状态、人物和事件
- Reviser将强制执行设定一致性

续写衍生作品：

bash

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

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

工作流6：精细化控制（草稿→审核→修订）

If you need separate control over each pipeline stage:

Generate draft only:

bash

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

Audit the chapter (33-dimension quality check):
bash
```
inkos audit book-id chapter-1 --json
```
- Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more
Revise with specific mode:
bash
```
inkos revise book-id chapter-1 --mode polish --json
```
- Modes:
```
polish
```
  (minor),
```
spot-fix
```
  (targeted),
```
rewrite
```
  (major),
```
rework
```
  (structure),
```
anti-detect
```
  (reduce AI traces)

如果你需要单独控制流水线的每个阶段：

仅生成草稿：

bash

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

审核章节（33维度质量检查）：
bash
```
inkos audit book-id chapter-1 --json
```
- 返回涵盖节奏、对话、世界观构建、大纲契合度等33个维度的指标
按特定模式修订：
bash
```
inkos revise book-id chapter-1 --mode polish --json
```
- 模式：
```
polish
```
  （润色）、
```
spot-fix
```
  （针对性修复）、
```
rewrite
```
  （重写）、
```
rework
```
  （结构调整）、
```
anti-detect
```
  （降低AI痕迹）

Workflow 7: Monitor Platform Trends

工作流7：监控平台趋势

bash

inkos radar scan

Analyzes trending genres, tropes, and reader preferences
Informs Architect recommendations for new books

bash

inkos radar scan

分析热门题材、套路与读者偏好
为Architect提供新书创作建议

Workflow 8: Detect AI-Generated Content

工作流8：检测AI生成内容

bash

undefined

bash

undefined

Detect AIGC in a specific chapter

检测特定章节中的AIGC内容

inkos detect book-id

Deep scan all chapters

深度扫描所有章节

inkos detect book-id --all

- Uses 11 deterministic rules (zero LLM cost) + optional LLM validation
- Returns detection confidence and problematic passages

inkos detect book-id --all

- 使用11条确定性规则（零LLM成本）+ 可选LLM验证
- 返回检测置信度与问题段落

Workflow 9: View Analytics

工作流9：查看分析数据

bash

inkos analytics book-id --json

bash

inkos analytics book-id --json

Shorthand alias

简写别名

inkos stats book-id --json

- Total chapters, word count, average words per chapter
- Audit pass rate and top issue categories
- Chapters with most issues, status distribution
- **Token usage stats**: total prompt/completion tokens, avg tokens per chapter, recent trend

inkos stats book-id --json

- 总章节数、字数、单章平均字数
- 审核通过率与主要问题类别
- 问题最多的章节、状态分布
- **Token使用统计**：提示词/补全Token总数、单章平均Token数、近期趋势

Advanced: Natural Language Agent Mode

进阶：自然语言Agent模式

For flexible, conversational requests:

bash

inkos agent "写一部都市题材的小说，主角是一个年轻律师，第一章三千字"

Agent interprets natural language and invokes appropriate commands
Useful for complex multi-step requests

用于灵活的对话式请求：

bash

inkos agent "写一部都市题材的小说，主角是一个年轻律师，第一章三千字"

Agent会解析自然语言并调用相应命令
适用于复杂的多步骤请求

Key Concepts

核心概念

Book ID Auto-Detection

Book ID自动检测

If your project contains only one book, most commands accept

book-id

as optional. You can omit it for brevity:

bash

undefined

如果你的项目中只有一本书，大多数命令可省略

book-id

参数：

bash

undefined

Explicit

显式指定

inkos write next book-123 --count 1

Auto-detected (if only one book exists)

自动检测（仅当只有一本书时生效）

inkos write next --count 1

undefined

inkos write next --count 1

undefined

--json Flag

--json标志

All content-generating commands support

--json

for structured output. Essential for programmatic use:

bash

inkos draft book-id --words 3000 --context "guidance" --json

所有内容生成命令均支持

--json

以输出结构化数据，适用于程序化调用：

bash

inkos draft book-id --words 3000 --context "guidance" --json

Truth Files (Long-Term Memory)

Truth Files（长期记忆）

InkOS maintains 7 files per book for coherence:

World State: Maps, locations, technology levels, magic systems
Character Matrix: Names, relationships, arcs, motivations
Resource Ledger: In-world items, money, power levels
Chapter Summaries: Events, progression, foreshadowing
Subplot Board: Active and dormant subplots, hooks
Emotional Arcs: Character emotional progression
Pending Hooks: Unresolved cliffhangers and promises to reader

All agents reference these to maintain long-term consistency. During

import chapters

, these files are reverse-engineered from existing content via the ChapterAnalyzerAgent.

InkOS为每本书维护7个文件以保证连贯性：

World State：地图、地点、科技水平、魔法体系
Character Matrix：姓名、关系、成长弧线、动机
Resource Ledger：世界观物品、货币、能力等级
Chapter Summaries：事件、剧情推进、伏笔
Subplot Board：活跃与休眠的副线、钩子
Emotional Arcs：角色情感发展
Pending Hooks：未解决的悬念与对读者的承诺

所有Agent都会参考这些文件以保持长期一致性。在

import chapters

过程中，ChapterAnalyzerAgent会从导入内容逆向生成这些文件。

Two-Phase Writer Architecture

双阶段Writer架构

The Writer agent operates in two phases:

Phase 1 (Creative): Generates the chapter text at temperature 0.7 for creative expression. Only outputs chapter title and content.
Phase 2 (Settlement): Updates all truth files at temperature 0.3 for precise state tracking. Ensures world state, character arcs, and plot hooks stay consistent.

This separation allows creative freedom in writing while maintaining rigorous continuity tracking.

Writer Agent分为两个阶段运行：

第一阶段（创意）：以温度0.7生成章节文本，侧重创意表达。仅输出章节标题与内容。
第二阶段（定型）：以温度0.3更新所有Truth Files，侧重精确状态追踪。确保世界状态、角色弧线与剧情钩子保持一致。

这种分离在保证创作自由度的同时，维持了严谨的剧情连续性。

Context Guidance

上下文指引

The

--context

parameter provides directional hints to the Writer and Architect:

bash

inkos write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"

Context is optional but highly recommended for narrative coherence
Supports both English and Chinese

--context

参数为Writer和Architect提供方向性提示：

bash

inkos write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"

上下文为可选参数，但强烈建议使用以保证叙事连贯性
支持英文与中文

Genre Management

题材管理

View Built-In Genres

查看内置题材

bash

inkos genre list
inkos genre show xuanhuan

bash

inkos genre list
inkos genre show xuanhuan

Create Custom Genre

创建自定义题材

bash

inkos genre create --name "my-genre" --rules "rule1,rule2,rule3"

bash

inkos genre create --name "my-genre" --rules "rule1,rule2,rule3"

Copy and Modify Existing Genre

复制并修改已有题材

bash

inkos genre copy xuanhuan --name "dark-xuanhuan" --rules "darker tone, more violence"

bash

inkos genre copy xuanhuan --name "dark-xuanhuan" --rules "darker tone, more violence"

Command Reference Summary

命令参考汇总

Command	Purpose	Notes
`inkos init [name]`	Initialize project	One-time setup
`inkos book create`	Create new book	Returns book-id. `--brief <file>` for creative brief
`inkos book list`	List all books	Shows IDs, statuses
`inkos write next`	Full pipeline (draft→audit→revise)	Primary workflow command
`inkos draft`	Generate draft only	No auditing/revision
`inkos audit`	33-dimension quality check	Standalone evaluation
`inkos revise`	Revise chapter	Modes: polish/spot-fix/rewrite/rework/anti-detect
`inkos agent`	Natural language interface	Flexible requests
`inkos style analyze`	Analyze reference text	Extracts style profile
`inkos style import`	Apply style to book	Makes style permanent
`inkos import canon`	Link spinoff to parent	For prequels/sequels
`inkos import chapters`	Import existing chapters	Reverse-engineers truth files for continuation
`inkos detect`	AIGC detection	Flags AI-generated passages
`inkos export`	Export finished book	Formats: txt, md, epub
`inkos analytics` / `inkos stats`	View book statistics	Word count, audit rates, token usage
`inkos radar scan`	Platform trend analysis	Informs new book ideas
`inkos config set-global`	Configure LLM provider	OpenAI/Anthropic/custom (any OpenAI-compatible)
`inkos config set-model <agent> <model>`	Set model override for a specific agent	`--provider` , `--base-url` , `--api-key-env` for multi-provider routing
`inkos config show-models`	Show current model routing	View per-agent model assignments
`inkos doctor`	Diagnose issues	Check installation
`inkos update`	Update to latest version	Self-update
`inkos up/down`	Daemon mode	Background processing. Logs to `inkos.log` (JSON Lines). `-q` for quiet mode
`inkos review list/approve-all`	Manage chapter approvals	Quality gate

命令	用途	说明
`inkos init [name]`	初始化项目	一次性设置
`inkos book create`	创建新书	返回book-id。 `--brief <file>` 用于指定创意大纲
`inkos book list`	列出所有书籍	显示ID与状态
`inkos write next`	完整流水线（草稿→审核→修订）	主要工作流命令
`inkos draft`	仅生成草稿	无审核/修订步骤
`inkos audit`	33维度质量检查	独立评估
`inkos revise`	修订章节	模式：polish/spot-fix/rewrite/rework/anti-detect
`inkos agent`	自然语言交互界面	灵活处理请求
`inkos style analyze`	分析参考文本	提取风格配置
`inkos style import`	为书籍应用风格	使风格设置永久生效
`inkos import canon`	关联衍生作品与原作	用于前传/续集创作
`inkos import chapters`	导入已有章节	逆向生成Truth Files以支持续写
`inkos detect`	AIGC检测	标记AI生成段落
`inkos export`	导出已完成书籍	格式：txt, md, epub
`inkos analytics` / `inkos stats`	查看书籍统计数据	字数、审核通过率、Token使用情况
`inkos radar scan`	平台趋势分析	为新书创作提供参考
`inkos config set-global`	配置LLM服务商	支持OpenAI/Anthropic/custom（任何兼容OpenAI的服务商）
`inkos config set-model <agent> <model>`	为特定Agent设置模型覆盖	使用 `--provider` 、 `--base-url` 、 `--api-key-env` 实现多服务商路由
`inkos config show-models`	查看当前模型路由	显示各Agent的模型分配
`inkos doctor`	诊断问题	检查安装情况
`inkos update`	更新到最新版本	自更新
`inkos up/down`	守护进程模式	后台处理。日志输出到 `inkos.log` （JSON Lines）。 `-q` 为静默模式
`inkos review list/approve-all`	管理章节批准	质量管控环节

Error Handling

错误处理

Common Issues

常见问题

"book-id not found"

Verify the ID with
```
inkos book list
```
Ensure you're in the correct project directory

"Provider not configured"

Run
```
inkos config set-global
```
with valid credentials
Check API key and base URL with
```
inkos doctor
```

"Context invalid"

Ensure
```
--context
```
is a string (wrap in quotes if multi-word)
Context can be in English or Chinese

"Audit failed"

Check chapter for encoding issues
Ensure chapter-words matches actual word count
Try
```
inkos revise
```
with
```
--mode rewrite
```

"Book already has chapters" (import)

Use
```
--resume-from <n>
```
to append to existing chapters
Or delete existing chapters first

"book-id not found"

使用
```
inkos book list
```
验证ID
确保你在正确的项目目录中

"Provider not configured"

运行
```
inkos config set-global
```
配置有效凭证
使用
```
inkos doctor
```
检查API密钥与基础URL

"Context invalid"

确保
```
--context
```
为字符串（多词时用引号包裹）
上下文支持英文与中文

"Audit failed"

检查章节编码问题
确保章节字数与设置匹配
尝试使用
```
inkos revise
```
并指定
```
--mode rewrite
```

"Book already has chapters" (import)

使用
```
--resume-from <n>
```
追加到已有章节后
或先删除已有章节

Running Daemon Mode

守护进程模式运行

For long-running operations:

bash

undefined

用于长时间运行的操作：

bash

undefined

Start background daemon

启动后台守护进程

inkos up

Stop daemon

停止守护进程

inkos down

Daemon auto-processes queued chapters

守护进程会自动处理队列中的章节

undefined

undefined

Tips for Best Results

最佳实践建议

Provide rich context: The more guidance in
```
--context
```
, the more coherent the narrative
Start with style: If imitating an author, run
```
inkos style import
```
before generation
Import first: For existing novels, use
```
inkos import chapters
```
to bootstrap truth files before continuing
Review regularly: Use
```
inkos review
```
to catch issues early
Monitor audits: Check
```
inkos audit
```
metrics to understand quality bottlenecks
Use spinoffs strategically: Import canon before writing prequels/sequels
Batch generation: Generate multiple chapters together (better continuity)
Check analytics: Use
```
inkos analytics
```
to track quality trends over time
Export frequently: Keep backups with
```
inkos export
```

提供丰富上下文：
```
--context
```
中的指引越详细，叙事连贯性越强
先设置风格：如果要模仿某位作者，在生成内容前运行
```
inkos style import
```
先导入再续写：对于已有小说，使用
```
inkos import chapters
```
生成Truth Files后再开始续写
定期审阅：使用
```
inkos review
```
尽早发现问题
监控审核结果：查看
```
inkos audit
```
指标以了解质量瓶颈
合理使用衍生作品：创作前传/续集前先导入原作设定
批量生成章节：一次性生成多章节以获得更好的连贯性
查看分析数据：使用
```
inkos analytics
```
追踪长期质量趋势
频繁导出：使用
```
inkos export
```
备份内容

Support & Resources

支持与资源

Homepage: https://github.com/Narcooo/inkos
Configuration: Stored in project root after
```
inkos init
```
Truth files: Located in
```
.inkos/
```
directory per book
Logs: Check output of
```
inkos doctor
```
for troubleshooting

主页：https://github.com/Narcooo/inkos
配置：初始化项目后存储在项目根目录
Truth Files：位于每本书的
```
.inkos/
```
目录下
日志：使用
```
inkos doctor
```
输出排查问题