InkOS
自动化小说写作 CLI Agent
中文 | English
---
Agent 写小说。写、审、改，全程接管。
## v0.3 更新 (2026-03-13)
创作规则三层分离：基础护栏 → 题材特性 → 用户自定义规则。
### 题材自定义
内置 5 个题材，每个题材带一套完整的创作规则：章节类型、禁忌清单、疲劳词、语言铁律、审计维度。
| 题材 | 自带规则 |
|------|----------|
| 玄幻 | 数值系统、战力体系、同质吞噬衰减公式、打脸/升级/收益兑现节奏 |
| 仙侠 | 修炼/悟道节奏、法宝体系、天道规则 |
| 都市 | 年代考据、商战/社交驱动、法律术语年代匹配、无数值系统 |
| 恐怖 | 氛围递进、恐惧层级、克制叙事、无战力审计 |
| 通用 | 最小化兜底 |
创建书时指定题材，对应规则自动生效：
```bash
inkos book create --title "吞天魔帝" --genre xuanhuan
```
题材规则可以查看、复制到项目中修改、或从零创建：
```bash
inkos genre list # 查看所有题材
inkos genre show xuanhuan # 查看玄幻的完整规则
inkos genre copy xuanhuan # 复制到项目中，随意改
inkos genre create wuxia --name 武侠 # 从零创建新题材
```
复制到项目后，增删禁忌、调整疲劳词、修改节奏规则、自定义语言铁律——改完下次写章自动生效。
每个题材有专属语言铁律（带 ✗→✓ 示例），写手和审计员同时执行：
- **玄幻**：✗ "火元从12缕增加到24缕" → ✓ "手臂比先前有力了，握拳时指骨发紧"
- **都市**：✗ "迅速分析了当前的债务状况" → ✓ "把那叠皱巴巴的白条翻了三遍"
- **恐怖**：✗ "感到一阵恐惧" → ✓ "后颈的汗毛一根根立起来"
### 单本书规则
每本书有独立的 `book_rules.md`，建筑师 agent 创建书时自动生成，也可以随时手改。写在这里的规则注入每一章的 prompt：
```yaml
protagonist:
name: 林烬
personalityLock: ["强势冷静", "能忍能杀", "有脑子不是疯狗"]
behavioralConstraints: ["不圣母不留手", "对盟友有温度但不煽情"]
numericalSystemOverrides:
hardCap: 840000000
resourceTypes: ["微粒", "血脉浓度", "灵石"]
prohibitions:
- 主角关键时刻心软
- 无意义后宫暧昧拖剧情
- 配角戏份喧宾夺主
fatigueWordsOverride: ["瞳孔骤缩", "不可置信"] # 覆盖题材默认
```
主角人设锁定、数值上限、自定义禁令、疲劳词覆盖——每本书的规则独立调整，不影响题材模板。
### 19 维度审计
审计细化为 19 个维度，按题材自动启用对应的子集：
OOC检查、时间线、设定冲突、伏笔、节奏、文风、信息越界、词汇疲劳、利益链断裂、配角降智、配角工具人化、爽点虚化、台词失真、流水账、知识库污染、视角一致性、战力崩坏、数值检查、年代考据
玄幻/仙侠全 19 维度，都市 17 维度（含年代考据），恐怖 15 维度。
### 去 AI 味
5 条通用规则 + 每个题材的专属语言规则，控制 AI 标记词密度和叙述习惯：
- AI 标记词限频：仿佛/忽然/竟然/不禁/宛如/猛地，每 3000 字 ≤ 1 次
- 叙述者不替读者下结论，只写动作
- 禁止分析报告式语言（"核心动机""信息落差"不入正文）
- 同一意象渲染不超过两轮
- 方法论术语不入正文
词汇疲劳审计同时检测标记词密度，超标即 warning。
### 其他
- 支持 OpenAI + Anthropic 原生 + 所有 OpenAI 兼容接口
- 修订者支持 polish / rewrite / rework 三种模式
- 无数值系统的题材不生成资源账本
- 所有命令支持 `--json` 结构化输出，OpenClaw / 外部 Agent 可直接解析
- book-id 自动检测：项目只有一本书时省略 book-id
- `inkos update` 一键更新、`inkos init` 支持当前目录初始化
- API 错误附带中文诊断提示，`inkos doctor` 含 API 连通性测试
---
## 为什么需要 InkOS？
用 AI 写小说不是简单的"提示词 + 复制粘贴"。长篇小说很快就会崩：角色记忆混乱、物品凭空出现、同样的形容词每段都在重复、伏笔悄无声息地断掉。InkOS 把这些当工程问题来解决。
- **长期记忆** — 追踪世界的真实状态，而非 LLM 的幻觉
- **反信息泄漏** — 确保角色只知道他们亲眼见证过的事
- **资源衰减** — 物资会消耗、物品会损坏，没有无限背包
- **词汇疲劳检测** — 在读者发现之前就捕捉过度使用的词语
- **自动修订** — 在人工审核之前修复数值错误和连续性断裂
## 工作原理
每一章由五个 Agent 接力完成：
| Agent | 职责 |
|-------|------|
| **雷达 Radar** | 扫描平台趋势和读者偏好，指导故事方向（可插拔，可跳过） |
| **建筑师 Architect** | 规划章节结构：大纲、场景节拍、节奏控制 |
| **写手 Writer** | 根据大纲 + 当前世界状态生成正文 |
| **连续性审计员 Auditor** | 对照长期记忆验证草稿 |
| **修订者 Reviser** | 修复审计发现的问题 — 关键问题自动修复，其他标记给人工审核 |
如果审计不通过，管线自动进入"修订 → 再审计"循环，直到所有关键问题清零。
### 长期记忆
每本书维护三个文件作为唯一事实来源：
| 文件 | 用途 |
|------|------|
| `current_state.md` | 世界状态：角色位置、关系网络、已知信息、情感弧线 |
| `particle_ledger.md` | 资源账本：物品、金钱、物资数量及衰减追踪 |
| `pending_hooks.md` | 未闭合伏笔：铺垫、对读者的承诺、未解决冲突 |
连续性审计员对照这三个文件检查每一章草稿。如果角色"记起"了从未亲眼见过的事，或者拿出了两章前已经丢失的武器，审计员会捕捉到。
### 创作规则体系
写手 agent 内置 ~25 条通用创作规则（人物塑造、叙事技法、逻辑自洽、语言约束、去 AI 味），适用于所有题材。
在此基础上，每个题材有专属规则（禁忌、语言铁律、节奏、审计维度），每本书有独立的 `book_rules.md`（主角人设、数值上限、自定义禁令）和 `story_bible.md`（世界观设定），由建筑师 agent 创建书籍时自动生成。
详见 [v0.3 更新](#v03-更新-2026-03-13)。
## 三种使用模式
InkOS 提供三种交互方式，底层共享同一组原子操作：
### 1. 完整管线（一键式）
```bash
inkos write next 吞天魔帝 # 写草稿 → 审计 → 自动修订，一步到位
inkos write next 吞天魔帝 --count 5 # 连续写 5 章
```
### 2. 原子命令（可组合，适合外部 Agent 调用）
```bash
inkos draft 吞天魔帝 --context "本章重点写师徒矛盾" --json
inkos audit 吞天魔帝 31 --json
inkos revise 吞天魔帝 31 --json
```
每个命令独立执行单一操作，`--json` 输出结构化数据。可被 OpenClaw 等 AI Agent 通过 `exec` 调用，也可用于脚本编排。
### 3. 自然语言 Agent 模式
```bash
inkos agent "帮我写一本都市修仙，主角是个程序员"
inkos agent "写下一章，重点写师徒矛盾"
inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
```
内置 9 个工具（write_draft、audit_chapter、revise_chapter、scan_market、create_book、get_book_status、read_truth_files、list_books、write_full_pipeline），LLM 通过 tool-use 决定调用顺序。
## 快速开始
### 安装
```bash
npm i -g @actalk/inkos
```
### 配置
**方式一：全局配置（推荐，只需一次）**
```bash
inkos config set-global \
--provider openai \
--base-url https://api.openai.com/v1 \
--api-key sk-xxx \
--model gpt-4o
```
配置保存在 `~/.inkos/.env`，所有项目共享。之后新建项目不用再配。
**方式二：项目级 `.env`**
```bash
inkos init my-novel # 初始化项目
# 编辑 my-novel/.env
```
```bash
# 必填
INKOS_LLM_PROVIDER=openai # openai / anthropic
INKOS_LLM_BASE_URL=https://api.openai.com/v1 # API 地址（支持中转站）
INKOS_LLM_API_KEY=sk-xxx # API Key
INKOS_LLM_MODEL=gpt-4o # 模型名
# 可选
# INKOS_LLM_TEMPERATURE=0.7 # 温度
# INKOS_LLM_MAX_TOKENS=8192 # 最大输出 token
# INKOS_LLM_THINKING_BUDGET=0 # Anthropic 扩展思考预算
```
项目 `.env` 会覆盖全局配置。不需要覆盖时可以不写。
### 使用
```bash
inkos book create --title "吞天魔帝" --genre xuanhuan # 创建新书
inkos write next 吞天魔帝 # 写下一章（完整管线）
inkos status # 查看状态
inkos review list 吞天魔帝 # 审阅草稿
inkos export 吞天魔帝 # 导出全书
inkos up # 守护进程模式
```
## 命令参考
| 命令 | 说明 |
|------|------|
| `inkos init [name]` | 初始化项目（省略 name 在当前目录初始化） |
| `inkos book create` | 创建新书（生成世界观 + 卷纲 + 本书规则） |
| `inkos book list` | 列出所有书籍 |
| `inkos genre list/show/copy/create` | 查看、复制、创建题材 |
| `inkos write next [id]` | 完整管线写下一章 |
| `inkos write rewrite [id] ` | 重写第 N 章（恢复状态快照，需确认） |
| `inkos draft [id]` | 只写草稿（不审不改） |
| `inkos audit [id] [n]` | 审计指定章节 |
| `inkos revise [id] [n]` | 修订指定章节 |
| `inkos agent ` | 自然语言 Agent 模式 |
| `inkos review list [id]` | 审阅草稿 |
| `inkos review approve-all [id]` | 批量通过 |
| `inkos status [id]` | 项目状态 |
| `inkos export [id]` | 导出书籍为 txt/md |
| `inkos radar scan` | 扫描平台趋势 |
| `inkos config set-global` | 设置全局 LLM 配置（~/.inkos/.env） |
| `inkos config show-global` | 查看全局配置 |
| `inkos config set/show` | 查看/更新项目配置 |
| `inkos doctor` | 诊断配置问题（含 API 连通性测试） |
| `inkos update` | 更新到最新版本 |
| `inkos up / down` | 启动/停止守护进程 |
`[id]` 参数在项目只有一本书时可省略，自动检测。所有命令支持 `--json` 输出结构化数据，`draft`/`write next`/`book create` 支持 `--context` 传入创作指导。
## 实测数据
用 InkOS 全自动跑了一本玄幻题材的《吞天魔帝》：
| 指标 | 数据 |
|------|------|
| 已完成章节 | 31 章 |
| 总字数 | 452,191 字 |
| 平均章字数 | ~14,500 字 |
| 审计通过率 | 100% |
| 资源追踪项 | 48 个 |
| 活跃伏笔 | 20 条 |
| 已回收伏笔 | 10 条 |
## 核心特性
### 状态快照 + 章节重写
每章自动创建状态快照。使用 `inkos write rewrite ` 可以回滚并重新生成任意章节 — 世界状态、资源账本、伏笔钩子全部恢复到该章写入前的状态。
### 写入锁
基于文件的锁机制防止对同一本书的并发写入。
### 写前自检 + 写后结算
写手 agent 在动笔前必须输出自检表（上下文范围、当前资源、待回收伏笔、冲突概述、风险扫描），写完后输出结算表（资源变动、伏笔变动）。审计员对照结算表和正文内容做交叉验证。
### 可插拔雷达
雷达数据源通过 `RadarSource` 接口实现可插拔。内置番茄小说和起点中文网两个数据源，也可以传入自定义数据源或直接跳过雷达。用户自己提供题材时，agent 模式会自动跳过市场扫描。
### 守护进程模式
`inkos up` 启动后台循环，按计划写章。管线对非关键问题全自动运行，当审计员标记无法自动修复的问题时暂停等待人工审核。
### 通知推送
支持 Telegram、飞书、企业微信。守护进程模式下，写完一章或审计不通过都会推通知到手机。
### 外部 Agent 集成
原子命令 + `--json` 输出让 InkOS 可以被 OpenClaw 等 AI Agent 调用。OpenClaw 通过 `exec` 工具执行 `inkos draft`/`audit`/`revise`，读取 JSON 结果决定下一步操作。
## 项目结构
```
inkos/
├── packages/
│ ├── core/ # Agent 运行时、管线、状态管理
│ │ ├── agents/ # architect, writer, continuity, reviser, radar
│ │ ├── pipeline/ # runner (原子操作 + 完整管线), agent (tool-use 编排), scheduler
│ │ ├── state/ # 基于文件的状态管理器
│ │ ├── llm/ # OpenAI + Anthropic 双 SDK 接口 (流式)
│ │ ├── notify/ # Telegram, 飞书, 企业微信
│ │ └── models/ # Zod schema 校验
│ └── cli/ # Commander.js 命令行 (16 条命令)
│ └── commands/ # init, book, write, draft, audit, revise, agent, review, status, export...
└── (规划中) studio/ # 网页审阅编辑界面
```
TypeScript 单仓库，pnpm workspaces 管理。
## 路线图
- [x] 完整管线（雷达 → 建筑师 → 写手 → 审计 → 修订）
- [x] 长期记忆 + 连续性审计
- [x] 内置创作规则体系
- [x] CLI 全套命令（15 条）
- [x] 状态快照 + 章节重写
- [x] 守护进程模式
- [x] 通知推送（Telegram / 飞书 / 企微）
- [x] 原子命令 + JSON 输出（draft / audit / revise）
- [x] 自然语言 Agent 模式（tool-use 编排）
- [x] 可插拔雷达（RadarSource 接口）
- [x] 外部 Agent 集成（OpenClaw 等）
- [x] 题材自定义 + 单本书规则（genre CLI + book_rules.md）
- [x] 19 维度连续性审计
- [x] 去 AI 味铁律
- [x] 多 LLM provider（OpenAI + Anthropic + 兼容接口）
- [ ] AI 检测复核（AIGC 检测 + 自动改写降率）
- [ ] `packages/studio` Web UI 审阅编辑界面
- [ ] 多模型路由（不同 agent 用不同模型）
- [ ] 自定义 agent 插件系统
- [ ] 平台格式导出（起点、番茄等）
## 参与贡献
欢迎贡献代码。提 issue 或 PR。
```bash
pnpm install
pnpm dev # 监听模式
pnpm test # 运行测试
pnpm typecheck # 类型检查
```
## 许可证
[MIT](LICENSE)