创建日期：2026-09-14 ｜ 最近更新：2026-09-14 事实以本地仓库 Narcooo/inkos v1.8.0-4-g6e9979b4（2026-09-07） 与本机实测的 CLI 帮助为准：下文命令、参数、子命令均为 npx @actalk/inkos@1.8.0 <cmd> --help 的真实输出。未实际调用模型生成内容（本机模型端点受限），涉及产物效果的部分只描述机制，不编造结果。

InkOS 深度体验：把 CLI 从「会用」用到「用得顺」

第 0 篇带你写出第一本书；这篇是进阶使用手册——把命令体系摸全、把单章流水线拆开手动跑、把批量与守护用起来、把模型路由和审阅闸门配好。目标是：遇到任何需求，你知道该敲哪条命令、参数在哪。

1. 全局开关：一次调用临时换模型/端点

inkos --help 的 GLOBAL OPTIONS 里有一组只对本次调用生效的覆盖项（不改配置文件）：

--service <service>      覆盖本次 LLM 服务
--model <model>          覆盖本次模型
--api-key-env <envVar>   从指定环境变量读 key
--base-url <url>         覆盖 base URL
--api-format <chat|responses>   覆盖 API 格式
--stream / --no-stream   强制流式 / 非流式

典型用法：某次审计想临时上更强的模型，或临时切到另一个网关——

inkos --model kimi-k2.5 --api-format chat audit 吞天魔帝 31

这一组是「临时试验」的正确姿势；长期配置走 config（第 5 节），别把临时值写死。

2. 命令地图（真实 `--help` 整理）

分组	命令	一句话
立项	`init` `book` `chapter` `import` `fanfic`	建项目/建书/章节管理/导入/同人
写作	`write` `draft` `plan` `compose`	完整管线 / 只出草稿 / 只做意图 / 只编译上下文
质量	`audit` `revise` `review` `detect` `eval` `style`	审计 / 修订 / 审阅闸门 / AIGC 检测 / 质量评估 / 文风指纹
批量	`auto` `up` `down`	追到指定章 / 守护进程启停
多形态	`short` `forecast` `translate` `play`（工具层）	短篇 / 推演 / 翻译 / 互动
编排	`agent` `interact` `tui` `studio`	自然语言编排 / 交互入口 / 终端界面 / Web 工作台
工程	`config` `doctor` `status` `export` `analytics` `consolidate` `genre` `update`	配置 / 体检 / 状态 / 导出 / 统计 / 卷级摘要 / 题材 / 升级

3. 把「一章」拆开手动跑（最有价值的调试方式）

第 0 篇提过 plan → compose → draft → audit → revise，这里给真实参数（来自 --help）：

# ① 生成「本章意图」（调 LLM）
inkos plan chapter 吞天魔帝 --context "本章先写师徒矛盾"

# ② 只编译本地文档 + 状态，产出 context/rule-stack/trace（不调 LLM）
inkos compose chapter 吞天魔帝

# ③ 只写草稿（不做审计/修订）
inkos draft 吞天魔帝 --words 3000 --context "冲突要更硬"

# ④ 审计（默认章节号取最新）
inkos audit 吞天魔帝 31

# ⑤ 按审计问题修订
inkos revise 吞天魔帝 31 --mode auto --brief "只修连续性问题"

revise --mode 有五档（真实取值）：spot-fix / polish / rewrite / rework / anti-detect（默认 auto）。想只动连续性用 spot-fix，想去 AI 味用 anti-detect，别一上来就 rewrite（会把已认可的文风也搅乱）。

为什么值得手动拆：write next 是「一把梭」，出问题你只能看整体结果；拆开跑能定位到底是意图不对（plan）、上下文没选对（compose）、写歪了（draft）还是审计/修订策略不对（audit/revise）。

4. `write` 的四个子命令（修数据的好帮手）

write next         写下一章（完整管线）
write rewrite      重新生成指定章节
write sync         按“最新编辑过的正文”重建 truth 文件与 SQLite 索引
write repair-state 章节状态退化时，只重建 truth 文件、不重写正文

sync vs repair-state 常被问：

你手工改了正文（比如自己润色了一段）→ 用 sync，让它按新正文回填状态与索引；
状态文件坏了但正文没问题 → 用 repair-state，只修状态、不动正文。

5. 多模型路由：不同 Agent 用不同模型

inkos config set-model writer <model> --provider <provider> --base-url <url> --api-key-env <ENV>
inkos config set-model auditor <model> --provider <provider>
inkos config show-models            # 看各 Agent 当前路由
inkos config remove-model writer    # 撤销，回落默认
inkos config list-models <service>  # 看某服务可用模型（含 maxOutput/contextWindow/abilities）

其它配置命令（真实）：config set <key> <value>、config set-global（写 ~/.inkos/.env，跨项目共享）、config show-global、config show。

实践建议（官方也这么推荐）：写手用强模型、审计用另一个模型、雷达用便宜模型——list-models 先看 contextWindow / maxOutput，别给长章节配上小输出的模型。

6. 审阅闸门：人说了算

inkos review list 吞天魔帝            # 待审章节
inkos review approve 吞天魔帝 31      # 通过并提交状态
inkos review approve-all 吞天魔帝     # 批量通过
inkos review reject 吞天魔帝 31       # 驳回并回滚状态

注意两个词的区别：approve 会「提交状态」，reject 会「回滚状态」——这不是单纯的「标记」，而是和状态机联动的闸门（架构层怎么落，见第 2 篇）。

7. 批量与守护：挂机写长书

inkos auto 吞天魔帝 50 --words 3000 --notify   # 一直写到第 50 章
inkos up                                        # 守护进程（按 daemon 计划自动写）
inkos down
inkos auto ... --json -q                        # 脚本/CI 友好

--notify 是命令级的通知开关，写到目标章后按配置的通道推送——通知实现支持 Telegram / 飞书 / 企业微信 / Webhook（源码 core/src/notify/ 下对应 telegram/feishu/wechat-work/webhook + dispatcher，Webhook 走 HMAC 签名）。

8. 两个「自然语言入口」：`agent` 与 `interact`

# agent：LLM 用 tool-use 编排（可绑书、可复用会话、可带上下文文件）
inkos agent "把《吞天魔帝》第 20 章的伏笔挑出来，列个表" --book <bookId> --session s1 --json

# interact：对当前项目做一次自然语言交互
inkos interact --json --message "继续写，但节奏收紧一点"

agent 的关键参数（真实）：--book（绑定书）、--session（复用会话 id）、--context / --context-file（补充上下文）、--json / --quiet（输出控制）。--session 是可复用的——同一个会话里，模型记得上一轮（它把完整对话（含工具调用）留在内存，见第 2 篇对 agent-session 的拆解）。

9. 质量与统计：别只看「写得快」

命令	用途
`inkos detect [book] [chapter]`	AIGC 检测（反检测效果的验证）
`inkos style analyze/import`	文风指纹分析 / 注入到某本书
`inkos eval [book]`	输出结构化质量报告
`inkos analytics\|stats [book]`	token 消耗与统计分析（成本意识）
`inkos consolidate [book]`	把章节摘要合并成卷级摘要，压缩长书上下文
`inkos status --chapters`	逐章状态与问题（排查「卡在哪一章」）

长书成本控制的关键是 consolidate：章节越写越多，如果每次都把全部摘要塞进上下文，token 会炸；卷级摘要 + 检索（第 2 篇的 FTS5/BM25）才是正解。

10. 排错与维护

inkos doctor                     # 环境/项目体检（配错先跑它）
inkos doctor --repair-node-runtime   # 写 .nvmrc / .node-version 锁 Node 22
inkos status --chapters          # 每章状态与问题
inkos export 吞天魔帝 --format epub --approved-only --output out.epub
inkos update                     # 升级 InkOS

--approved-only 只导出已通过审阅的章节——投稿/发布前用得上。

11. 踩坑清单（结合命令语义与第 0 篇）

两套配置体系别混：Studio 只认项目内配置与 .inkos/secrets.json，CLI 是「Studio 配置为底 + env + 参数」——doctor 会告诉你当前生效的是哪层；
service 与 model 错配会直接报错（内置模型归属校验），别硬凑；
临时改模型用全局开关，长期用 config set-model，别把试验值写进项目配置；
手动改正文后要 write sync，否则状态/索引和你看到的正文不一致；
reject 不只是标记，它会回滚状态——想保留请走 approve；
Node 版本：部分能力（SQLite 记忆库等）依赖 Node 22+，跨机器时先 doctor。

关联

前置：InkOS 入门（装好、写出第一本书）
下一篇：InkOS 架构拆解——这些命令背后的 agent、状态机、检索与审计是怎么实现的
底层运行时：pi-agent 系列（InkOS 的会话/工具循环建在它上面）

自测

临时给某次调用换模型，用哪组全局开关？
plan 和 compose 的区别是什么？后者会调 LLM 吗？
sync 与 repair-state 分别修什么？
approve 与 reject 对状态做了什么？
长书 token 成本为什么要靠 consolidate？

1. 全局开关：一次调用临时换模型/端点​

2. 命令地图（真实 --help 整理）​

3. 把「一章」拆开手动跑（最有价值的调试方式）​

4. write 的四个子命令（修数据的好帮手）​

5. 多模型路由：不同 Agent 用不同模型​

6. 审阅闸门：人说了算​

7. 批量与守护：挂机写长书​

8. 两个「自然语言入口」：agent 与 interact​

9. 质量与统计：别只看「写得快」​

10. 排错与维护​

11. 踩坑清单（结合命令语义与第 0 篇）​

关联​

自测​