安装#

方式一：Studio 服务配置（推荐）#

适合本地写作、Web 工作台和可视化管理。

1
inkos init my-novel
2
cd my-novel
3
inkos

打开 Studio 后进入「模型配置」：

1. 选择服务商，例如 Google Gemini、Moonshot、MiniMax、智谱、百炼或自定义端点。
2. 粘贴 API Key，点击「测试连接」。
3. 选择可用模型，保存配置。
4. 回到书籍页面开始写作。

Studio 运行时只使用：

1
provider bank 默认值
2
→ inkos.json 里的 services / 当前 service / defaultModel
3
→ .inkos/secrets.json 里的 service API Key

即使检测到 ~/.inkos/.env 或项目 .env，Studio 也只会展示提示，不会用 env 覆盖 service、model、baseUrl 或 API Key。API Key 存在项目内的 .inkos/secrets.json，不会写进 inkos.json。

方式二：CLI / daemon / 部署环境的 env 配置#

适合终端批处理、服务器部署、CI、Docker、守护进程和一次性切模型。

全局 env：

1
inkos config set-global \
2
  --provider <openai|anthropic|custom> \
3
  --base-url <API 地址> \
4
  --api-key <你的 API Key> \
5
  --model <模型名>

也可以手动写 ~/.inkos/.env 或项目 .env：

1
INKOS_LLM_PROVIDER=custom
2
INKOS_LLM_BASE_URL=https://api.moonshot.cn/v1
3
INKOS_LLM_API_KEY=sk-...
4
INKOS_LLM_MODEL=kimi-k2.5
5

6
# 可选
7
INKOS_LLM_SERVICE=moonshot                         # 推荐写；不写时会尽量从 baseUrl 自动识别
8
INKOS_LLM_TEMPERATURE=0.7
9
INKOS_LLM_THINKING_BUDGET=0
10
INKOS_DEFAULT_LANGUAGE=zh
11
INKOS_LLM_EXTRA_top_p=0.9

CLI 合成顺序：

1
Studio/project service 配置
2
→ .inkos/secrets.json service key
3
→ global ~/.inkos/.env
4
→ project .env
5
→ 当前进程环境变量
6
→ CLI 参数

也就是说，CLI 默认可以复用 Studio 配好的服务和密钥；如果 env 里声明了 INKOS_LLM_SERVICE、INKOS_LLM_MODEL、INKOS_LLM_BASE_URL 或 INKOS_LLM_API_KEY，则作为覆盖层生效。旧 env 只写 baseUrl + model + apiKey 也能继续用，InkOS 会尽量从 baseUrl 反推 service。

一次性指定服务或模型：

1
inkos write next --service google --model gemini-2.5-flash
2
inkos write next --service moonshot --model kimi-k2.5 --no-stream
3
inkos agent "继续写下一章" --api-key-env MOONSHOT_API_KEY
4
inkos doctor --service minimaxCodingPlan --model MiniMax-M2.7

--service 会从 provider bank 自动推导 baseUrl、协议和兼容策略；--model 必须属于最终 service，否则会直接报错，避免把 Kimi 模型发到 Gemini 这类错配问题。

方式三：多模型路由（可选）#

给不同 Agent 分配不同模型，按需平衡质量与成本：

1
# 给不同 agent 配不同模型/提供商
2
inkos config set-model writer <model> --provider <provider> --base-url <url> --api-key-env <ENV_VAR>
3
inkos config set-model auditor <model> --provider <provider>
4
inkos config show-models        # 查看当前路由

未单独配置的 Agent 自动使用全局模型。

配置排查#

1
inkos doctor

doctor 会显示当前 effective config mode、service/model/API Key 来源，并尝试 API 连通性。常见模式：

如果服务测试失败，优先检查服务商、模型和协议是否匹配。Google Gemini 的 AI Studio API Key 可用于 Gemini OpenAI-compatible endpoint；InkOS 会自动禁用 Google 不支持的 OpenAI store 参数。MiniMax / MiniMax CodingPlan 会优先使用可工作的非流式 transport，避免流式返回 usage 但无正文的问题。

多维度审计 + 去 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），而非凭空创作；同时把简报落盘到 story/author_intent.md，让这本书的长期创作意图不会只在建书时生效一次。

输入治理控制面#

每本书现在都有两份长期可编辑的 Markdown 控制文档：

• story/author_intent.md：这本书长期想成为什么
• story/current_focus.md：最近 1-3 章要把注意力拉回哪里

写作前可以先跑：

1
inkos plan chapter 吞天魔帝 --context "本章先把注意力拉回师徒矛盾"
2
inkos compose chapter 吞天魔帝

这会生成 story/runtime/chapter-XXXX.intent.md、context.json、rule-stack.yaml、trace.json。其中 intent.md 给人看，其他文件给系统执行和调试。plan / compose 只编译本地文档和状态，不依赖在线 LLM，可在没配好 API Key 前先验证控制输入。

字数治理#

draft、write next、revise 现在共享同一套保守型字数治理：

• --words 指定的是目标字数，系统会自动推导一个允许区间，不承诺逐字精确命中
• 中文默认按 zh_chars 计数，英文默认按 en_words 计数
• 如果正文超出允许区间，InkOS 最多只会追加 1 次纠偏归一化（压缩或补足），不会直接硬截断正文
• 如果 1 次纠偏后仍然超出 hard range，章节照常保存，但会在结果和 chapter index 里留下长度 warning / telemetry

续写已有作品#

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 兼容接口（Studio 里新增自定义服务，或 CLI 使用 --provider custom / INKOS_LLM_PROVIDER=custom）。服务测试会尝试不同协议和流式开关组合，并保存或提示可用 transport。Fallback 解析器处理小模型不规范输出，流中断时自动恢复部分内容。

可靠性保障#

每章自动创建状态快照，inkos write rewrite 可回滚任意章节。写手动笔前输出自检表（上下文、资源、伏笔、风险），写完输出结算表，审计员交叉验证。文件锁防止并发写入。写后验证器含跨章重复检测和 11 条硬规则自动 spot-fix。

伏笔系统使用 Zod schema 校验——lastAdvancedChapter 必须是整数，status 只能是 open/progressing/deferred/resolved。LLM 输出的 JSON delta 在写入前经过 applyRuntimeStateDelta 做 immutable 更新 + validateRuntimeState 结构校验。坏数据直接拒绝，不会滚雪球。

模型输出上限由 provider bank 的模型卡管理；llm.extra / INKOS_LLM_EXTRA_* 中的保留键（max_tokens、temperature、model、messages、stream 等）会被自动过滤，防止意外覆盖核心请求参数。

长期记忆#

每本书维护 7 个真相文件作为唯一事实来源：

连续性审计员对照这些文件检查每一章草稿。如果角色”记起”了从未亲眼见过的事，或者拿出了两章前已经丢失的武器，审计员会捕捉到。

从 0.6.0 起，真相文件的权威来源从 markdown 迁移到 story/state/*.json（Zod schema 校验）。Settler 不再输出完整 markdown 文件，而是输出 JSON delta，由代码层做 immutable apply + 结构校验后写入。markdown 文件仍然保留作为人类可读的投影。旧书首次运行时自动从 markdown 迁移到结构化 JSON，零人工操作。

Node 22+ 环境下自动启用 SQLite 时序记忆数据库（story/memory.db），支持按相关性检索历史事实、伏笔和章节摘要，避免全量注入导致的上下文膨胀。

控制面与运行时产物#

除了 7 个真相文件，InkOS 还把“护栏”和“自定义”拆成可审阅的控制层：