# inkos
**Repository Path**: xiazi003_admin/inkos
## Basic Information
- **Project Name**: inkos
- **Description**: AI 写小说
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
Autonomous Novel Writing Cli AI Agent
自动化小说写作 Cli AI Agent
English | 中文
---
Agent 写小说。写、审、改，全程接管。覆盖玄幻、仙侠、都市、科幻等多种风格，支持续写、番外、同人、仿写等创作形式。
**Native English novel writing now supported！** Set `--lang en` to write in English. See [English README](README.en.md) for details.
## 快速开始
### 安装
```bash
npm i -g @actalk/inkos
```
### 通过 OpenClaw 使用 🦞
InkOS 已发布为 [OpenClaw](https://clawhub.ai) Skill，可被任何兼容 Agent（Claude Code、OpenClaw 等）直接调用：
```bash
clawhub install inkos # 从 ClawHub 安装 InkOS Skill
```
通过 npm 安装或克隆本项目时，`skills/SKILL.md` 已包含在内，🦞 可直接读取——无需额外从 ClawHub 安装。
安装后，Claw 可通过 `exec` 调用 InkOS 的所有原子命令（`draft`/`audit`/`revise`/`write next`），`--json` 输出结构化数据供 Claw 解析决策。也可以在 [ClawHub](https://clawhub.ai) 搜索 `inkos` 在线查看。
### 配置
**方式一：全局配置（推荐，只需一次）**
```bash
inkos config set-global \
--provider \
--base-url \
--api-key <你的 API Key> \
--model <模型名>
# provider: openai / anthropic / custom（兼容 OpenAI 格式的中转站选 custom）
# base-url: 你的 API 提供商地址
# api-key: 你的 API Key
# model: 你的模型名称
```
配置保存在 `~/.inkos/.env`，所有项目共享。之后新建项目不用再配。
**方式二：项目级 `.env`**
```bash
inkos init my-novel # 初始化项目
# 编辑 my-novel/.env
```
```bash
# 必填
INKOS_LLM_PROVIDER= # openai / anthropic / custom（兼容 OpenAI 接口的都选 custom）
INKOS_LLM_BASE_URL= # API 地址（支持中转站、智谱、Gemini 等）
INKOS_LLM_API_KEY= # API Key
INKOS_LLM_MODEL= # 模型名
# 可选
# INKOS_LLM_TEMPERATURE=0.7 # 温度
# INKOS_LLM_MAX_TOKENS=8192 # 最大输出 token
# INKOS_LLM_THINKING_BUDGET=0 # Anthropic 扩展思考预算
```
项目 `.env` 会覆盖全局配置。不需要覆盖时可以不写。
**方式三：多模型路由（可选）**
给不同 Agent 分配不同模型，按需平衡质量与成本：
```bash
# 给不同 agent 配不同模型/提供商
inkos config set-model writer --provider --base-url --api-key-env
inkos config set-model auditor --provider
inkos config show-models # 查看当前路由
```
未单独配置的 Agent 自动使用全局模型。
### 写第一本书
```bash
inkos book create --title "吞天魔帝" --genre xuanhuan # 创建新书
inkos write next 吞天魔帝 # 写下一章（完整管线：草稿 → 审计 → 修订）
inkos status # 查看状态
inkos review list 吞天魔帝 # 审阅草稿
inkos review approve-all 吞天魔帝 # 批量通过
inkos export 吞天魔帝 # 导出全书
inkos export 吞天魔帝 --format epub # 导出 EPUB（手机/Kindle 阅读）
```
---
## 核心特性
### 多维度审计 + 去 AI 味
连续性审计员从 33 个维度检查每一章草稿：角色记忆、物资连续性、伏笔回收、大纲偏离、叙事节奏、情感弧线等。内置 AI 痕迹检测维度，自动识别"LLM 味"表达（高频词、句式单调、过度总结），审计不通过自动进入修订循环。
去 AI 味规则内置于写手 agent 的 prompt 层——词汇疲劳词表、禁用句式、文风指纹注入，从源头减少 AI 生成痕迹。`revise --mode anti-detect` 可对已有章节做专门的反检测改写。
### 文风仿写
`inkos style analyze` 分析参考文本，提取统计指纹（句长分布、词频特征、节奏模式）和 LLM 风格指南。`inkos style import` 将指纹注入指定书籍，后续所有章节自动采用该风格，修订者也会用风格标准做审计。
### 创作简报
`inkos book create --brief my-ideas.md` 传入你的脑洞、世界观设定、人设文档。建筑师 agent 会基于简报生成故事设定（story_bible.md）和创作规则（book_rules.md），而非凭空创作。
### 续写已有作品
`inkos import chapters` 从已有小说文本导入章节，自动逆向工程 7 个真相文件（世界状态、角色矩阵、资源账本、伏笔钩子等），支持 `第X章` 和自定义分割模式、断点续导。导入后 `inkos write next` 无缝接续创作。
### 同人创作
`inkos fanfic init --from source.txt --mode canon` 从原作素材创建同人书。支持四种模式：canon（正典延续）、au（架空世界）、ooc（性格重塑）、cp（CP 向）。内置正典导入器、同人专属审计维度和信息边界管控——确保设定不矛盾。
### 多模型路由
不同 Agent 可以走不同模型和 Provider。写手用 Claude（创意强），审计用 GPT-4o（便宜快速），雷达用本地模型（零成本）。`inkos config set-model` 按 agent 粒度配置，未配置的自动回退全局模型。
### 守护进程 + 通知推送
`inkos up` 启动后台循环自动写章。管线对非关键问题全自动运行，关键问题暂停等人工审核。通知推送支持 Telegram、飞书、企业微信、Webhook（HMAC-SHA256 签名 + 事件过滤）。日志写入 `inkos.log`（JSON Lines），`-q` 静默模式。
### 本地模型兼容
支持任何 OpenAI 兼容接口（`--provider custom`）。Stream 自动降级——中转站不支持 SSE 时自动回退 sync。Fallback 解析器处理小模型不规范输出，流中断时自动恢复部分内容。
### 可靠性保障
每章自动创建状态快照，`inkos write rewrite` 可回滚任意章节。写手动笔前输出自检表（上下文、资源、伏笔、风险），写完输出结算表，审计员交叉验证。文件锁防止并发写入。写后验证器 11 条硬规则自动 spot-fix。
---
## 工作原理
每一章由五个 Agent 接力完成：
| Agent | 职责 |
|-------|------|
| **雷达 Radar** | 扫描平台趋势和读者偏好，指导故事方向（可插拔，可跳过） |
| **建筑师 Architect** | 规划章节结构：大纲、场景节拍、节奏控制 |
| **写手 Writer** | 根据大纲 + 当前世界状态生成正文（两阶段：创意写作 → 状态结算） |
| **连续性审计员 Auditor** | 对照 7 个真相文件验证草稿，33 维度检查 |
| **修订者 Reviser** | 修复审计发现的问题 — 关键问题自动修复，其他标记给人工审核 |
如果审计不通过，管线自动进入"修订 → 再审计"循环，直到所有关键问题清零。
### 长期记忆
每本书维护 7 个真相文件作为唯一事实来源：
| 文件 | 用途 |
|------|------|
| `current_state.md` | 世界状态：角色位置、关系网络、已知信息、情感弧线 |
| `particle_ledger.md` | 资源账本：物品、金钱、物资数量及衰减追踪 |
| `pending_hooks.md` | 未闭合伏笔：铺垫、对读者的承诺、未解决冲突 |
| `chapter_summaries.md` | 各章摘要：出场人物、关键事件、状态变化、伏笔动态 |
| `subplot_board.md` | 支线进度板：A/B/C 线状态、停滞检测 |
| `emotional_arcs.md` | 情感弧线：按角色追踪情绪变化和成长 |
| `character_matrix.md` | 角色交互矩阵：相遇记录、信息边界 |
连续性审计员对照这些文件检查每一章草稿。如果角色"记起"了从未亲眼见过的事，或者拿出了两章前已经丢失的武器，审计员会捕捉到。
### 创作规则体系
写手 agent 内置 ~25 条通用创作规则（人物塑造、叙事技法、逻辑自洽、语言约束、去 AI 味），适用于所有题材。
在此基础上，每个题材有专属规则（禁忌、语言约束、节奏、审计维度），每本书有独立的 `book_rules.md`（主角人设、数值上限、自定义禁令）和 `story_bible.md`（世界观设定），由建筑师 agent 创建书籍时自动生成。
## 使用模式
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` 输出结构化数据。可被外部 AI Agent 通过 `exec` 调用，也可用于脚本编排。
### 3. 自然语言 Agent 模式
```bash
inkos agent "帮我写一本都市修仙，主角是个程序员"
inkos agent "写下一章，重点写师徒矛盾"
inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
```
内置 13 个工具（write_draft、audit_chapter、revise_chapter、scan_market、create_book、get_book_status、read_truth_files、list_books、write_full_pipeline、web_fetch、import_style、import_canon、import_chapters），LLM 通过 tool-use 决定调用顺序。
## 实测数据
用 InkOS 全自动跑了一本玄幻题材的《吞天魔帝》：
| 指标 | 数据 |
|------|------|
| 已完成章节 | 31 章 |
| 总字数 | 452,191 字 |
| 平均章字数 | ~14,500 字 |
| 审计通过率 | 100% |
| 资源追踪项 | 48 个 |
| 活跃伏笔 | 20 条 |
| 已回收伏笔 | 10 条 |
## 命令参考
| 命令 | 说明 |
|------|------|
| `inkos init [name]` | 初始化项目（省略 name 在当前目录初始化） |
| `inkos book create` | 创建新书（`--genre`、`--platform`、`--chapter-words`、`--target-chapters`、`--brief ` 传入创作简报） |
| `inkos book update [id]` | 修改书设置（`--chapter-words`、`--target-chapters`、`--status`） |
| `inkos book list` | 列出所有书籍 |
| `inkos book delete ` | 删除书籍及全部数据（`--force` 跳过确认） |
| `inkos genre list/show/copy/create` | 查看、复制、创建题材 |
| `inkos write next [id]` | 完整管线写下一章（`--words` 覆盖字数，`--count` 连写，`-q` 静默模式） |
| `inkos write rewrite [id] ` | 重写第 N 章（恢复状态快照，`--force` 跳过确认，`--words` 覆盖字数） |
| `inkos draft [id]` | 只写草稿（`--words` 覆盖字数，`-q` 静默模式） |
| `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]` | 导出书籍（`--format txt/md/epub`、`--output `、`--approved-only`） |
| `inkos radar scan` | 扫描平台趋势 |
| `inkos fanfic init` | 从原作素材创建同人书（`--from`、`--mode canon/au/ooc/cp`） |
| `inkos config set-global` | 设置全局 LLM 配置（~/.inkos/.env） |
| `inkos config show-global` | 查看全局配置 |
| `inkos config set/show` | 查看/更新项目配置 |
| `inkos config set-model ` | 为指定 agent 设置模型覆盖（`--base-url`、`--provider`、`--api-key-env` 支持多 Provider 路由） |
| `inkos config remove-model ` | 移除 agent 模型覆盖（回退到默认） |
| `inkos config show-models` | 查看当前模型路由 |
| `inkos doctor` | 诊断配置问题（含 API 连通性测试 + 提供商兼容性提示） |
| `inkos detect [id] [n]` | AIGC 检测（`--all` 全部章节，`--stats` 统计） |
| `inkos style analyze ` | 分析参考文本提取文风指纹 |
| `inkos style import [id]` | 导入文风指纹到指定书 |
| `inkos import canon [id] --from ` | 导入正传正典到番外书 |
| `inkos import chapters [id] --from ` | 导入已有章节续写（`--split`、`--resume-from`） |
| `inkos analytics [id]` / `inkos stats [id]` | 书籍数据分析（审计通过率、高频问题、章节排名、token 用量） |
| `inkos update` | 更新到最新版本 |
| `inkos up / down` | 启动/停止守护进程（`-q` 静默模式，自动写入 `inkos.log`） |
`[id]` 参数在项目只有一本书时可省略，自动检测。所有命令支持 `--json` 输出结构化数据。`draft`/`write next` 支持 `--context` 传入创作指导，`--words` 覆盖每章字数。`book create` 支持 `--brief ` 传入创作简报（你的脑洞/设定文档），Architect 会基于此生成设定而非凭空创作。
## 路线图
- [ ] `packages/studio` Web UI 审阅编辑界面（Vite + React + Hono）
- [ ] 局部干预（重写半章 + 级联更新后续 truth 文件）
- [ ] 自定义 agent 插件系统
- [ ] 平台格式导出（起点、番茄等）
## 参与贡献
欢迎贡献代码。提 issue 或 PR。
```bash
pnpm install
pnpm dev # 监听模式
pnpm test # 运行测试
pnpm typecheck # 类型检查
```
## 许可证
[MIT](LICENSE)