inkos

InkOS 是一个面向故事创作的 AI Agent 系统：长篇连载、独立短篇、剧本剧作、同人番外、仿写续写和开放世界互动，都可以从同一个工作台开始。支持Studio、TUI、CLI交互形式，共享创意、设定、角色、记忆、审稿、修订、封面和互动状态只智能体，让故事能持续生产、持续修改、持续玩下去。

💡 写小说，先给 Agent 接一层专业数据 —— 写小说不只缺模型，更缺素材。推荐搭配 火花数据API（huohuaapi）：按调用计费的小说 / 网文创作数据，让 Agent 动笔前先查小说正文、章节结构、人物设定、文风和创作方法等带来源素材，而不是只靠 Prompt 硬凑一份“剧情提纲”。

v1.5.0 - InkOS Play 发布，开放世界，用想象力游玩

InkOS Play 发布和 Studio 体验升级：你可以用一句自然语言创建开放世界，让角色、物品、证据、关系和时间一起推进；也可以继续写长篇、做短篇、生成封面、改设定和查状态。系统会记住世界发生了什么，并在需要时把该看的上下文带给模型。

• InkOS Play：新增开放世界与分支互动。支持自由动作、可点击选择、世界契约、非固定时间推进、角色 agent、物品 / 证据 / 关系状态、HUD 和自动配图。
• Studio UX：开始创作、我的创作、会话记录、查看世界、配图与生成物预览都重新整理，Play 可以像文字游戏一样滚动游玩，而不是藏在命令行里。
• 记忆与上下文：长篇和互动世界都开始进入“按任务取上下文”的模式。故事状态、Markdown 投影、SQLite 记忆、会话摘要和 protected / compressible 语义压缩共同工作，降低旧历史淹没当前指令的问题。
• 指令遵循：Studio Chat、TUI 和 CLI 的自然语言入口统一到 action surface。普通讨论、确认建书、短篇、封面、Play、长篇写章和重写续写不再靠散落关键词抢跑，重动作先确认，完成态来自真实工具结果。
• 创作入口：长篇、短篇、同人、番外、仿写、续写、封面制作和开放世界都成为 Studio 的一等入口。
• 模型与错误边界：弱模型格式不稳时更少直接崩溃；模型服务错误、InkOS 执行错误和图片生成错误会更清楚地区分，方便判断是配置、供应商还是系统问题。

长篇小说 — 从创作简报建书，生成世界观、角色、卷纲、章节意图，按“写作 → 审稿 → 必要修订 → 状态结算”推进。上下文按 protected / compressible 分层组织，避免长书越写越乱。

InkOS Short — Studio Chat 和 CLI 可以直接产出独立短篇：完整正文、大纲记录、审稿记录、简介卖点、封面提示词，并在配置封面服务后生成封面图。

InkOS Play — 新增开放世界与分支互动。你可以用自然语言指定世界契约、时间推进方式、角色 agent、物品 / 证据 / 关系规则和视觉风格；系统维护世界状态、可点击选择、自由动作、HUD 和自动配图。

Studio Chat — 普通聊天、建书、短篇、封面、互动世界都走同一套 action surface。重动作先确认，生成物可预览，可通过聊天修改章节、封面提示词、世界状态和持久化文本产物。

模型配置 — Studio 内置多服务配置、模型路由和封面服务配置；也支持 kkaiapi / OpenRouter 等全球主流模型聚合入口，以及自定义 OpenAI-compatible 服务。

Native English novel writing now supported！ Set --lang en to write in English. See English README for details.

欢迎交流

当前更新相对频繁，后续会持续新增功能与优化写作效果。 欢迎加群反馈问题、提出需求，也欢迎关注项目动态 — 我们的目标是做最强的基于小说的内容生态创作 AI Agent。

快速开始

安装

npm i -g @actalk/inkos

通过 OpenClaw 使用 🦞

InkOS 已发布为 OpenClaw Skill，可被任何兼容 Agent（Claude Code、OpenClaw 等）直接调用：

clawhub install inkos          # 从 ClawHub 安装 InkOS Skill

通过 npm 安装或克隆本项目时，skills/SKILL.md 已包含在内，🦞 可直接读取——无需额外从 ClawHub 安装。

安装后，Claw 应优先通过共享交互入口调用 InkOS：

inkos interact --json --message "继续当前书，但把节奏再收紧一点"

这条入口直接走和项目 TUI 相同的交互执行内核，因此 OpenClaw、TUI、Studio 共用同一套控制脑。当前 JSON 输出包含 assistant 文本回复和 interaction session 信息；真正的执行结果以工具结果和落盘文件为准，不从模型口头声明推断完成。

plan chapter / compose chapter / draft / audit / revise / write next 这些原子命令仍然保留，但更适合作为底层工具，而不是 OpenClaw 的首选入口。也可以在 ClawHub 搜索 inkos 在线查看。

配置

当前 InkOS 将 LLM 配置分成两条清晰路径：Studio 用可视化服务配置，CLI / daemon / 部署环境支持 env 覆盖。两者不会互相污染。

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

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

inkos init my-novel
cd my-novel
inkos

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

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

Studio 运行时只使用：

provider bank 默认值
→ inkos.json 里的 services / 当前 service / defaultModel
→ .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：

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

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

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

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

CLI 合成顺序：

Studio/project service 配置
→ .inkos/secrets.json service key
→ global ~/.inkos/.env
→ project .env
→ 当前进程环境变量
→ 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。

一次性指定服务或模型：

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

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

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

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

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

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

配置排查

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 默认走官方 OpenAI-compatible /v1/chat/completions，并优先使用可工作的非流式 transport，避免流式返回 usage 但无正文的问题。

LLM 配置更新

• Studio / CLI 配置隔离：Studio 固定使用服务页配置和 .inkos/secrets.json；CLI、daemon、部署环境支持 env 覆盖和一次性命令参数。
• Provider bank 能力表：内置 Google Gemini、Moonshot、MiniMax、智谱、百炼、DeepSeek、硅基流动、火山、腾讯混元、文心、讯飞星火、OpenRouter、kkaiapi、Ollama、CodingPlan 等服务的 baseUrl、协议、模型和兼容策略。
• 模型归属校验：--service google --model kimi-k2.5 这类错配会直接报错，避免把请求发到错误服务商。
• Google Gemini 兼容修复：AI Studio API Key 可直接用于 Gemini OpenAI-compatible endpoint，InkOS 会自动禁用 Google 不支持的 OpenAI store 参数。
• MiniMax transport 探测：MiniMax / MiniMax CodingPlan 使用官方 OpenAI-compatible /v1 入口，并自动使用可工作的非流式 transport，规避流式 usage 正常但正文为空的问题。
• 旧 env 兼容：老的 INKOS_LLM_BASE_URL + INKOS_LLM_MODEL + INKOS_LLM_API_KEY 仍可用于 CLI；没有 INKOS_LLM_SERVICE 时会尝试从 baseUrl 反推服务商。

当前交互入口

Studio Chat + CLI + TUI 共用同一套执行面

• Studio Chat：讨论、建书、短篇、封面、Play、编辑持久化文件都从同一个对话入口发起；重动作会先展示确认卡。
• 开始创作入口：长篇小说、短篇小说、同人创作、番外创作、仿写创作、续写创作、分支互动、开放世界都可以从 Studio 顶部入口进入。
• TUI 仪表盘：inkos tui 进入终端全屏交互，适合键盘流用户。
• 外部 Agent 入口：inkos interact --json --message "..." 仍是 OpenClaw / 其他 agent 的结构化入口。
• 原子命令保留：plan / compose / draft / audit / revise / write next 仍适合脚本和高级用户。

写第一本书

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 阅读）

写完整短篇

想直接生成一篇完整短篇，可以在 Studio 对话里说：

写一篇 12 章短篇，方向是：都市婚姻反转，女主拿到账本证据后反杀。

也可以走 CLI：

inkos short run \
  --direction "都市短篇 婚姻反转 女主证据反杀" \
  --chapters 12 \
  --chars 1000

生成物会落在 shorts/<故事名>/final/，包含 full.md、sales-package.md、cover-prompt.md，配置封面服务后还会生成 cover.png。

单独制作封面

如果只想给已有标题或简介做封面，不需要重跑短篇正文，在 Studio 对话里直接说：

给《她签下离婚协议那天，他悔疯了》生成一张短篇封面，偏现代都市、强反转。

封面工具会独立生成 covers/<标题>/cover-prompt.md 和 covers/<标题>/cover.png。如果还没有配置封面服务，先在 Studio 的模型配置里设置封面服务和 API Key。

生成后也可以继续通过 chat 改封面提示词，例如“把人物拉近一点、标题字更大、表情更冷笑”。系统会用新的 coverPrompt 重写 cover-prompt.md 并重生成封面，不需要重新写短篇。

启动开放世界 / 分支互动

在 Studio Chat 里选择「开放世界」或「分支互动」，直接用自然语言描述你想玩的世界：

做一个魔兽风格的边境哨塔开放世界。时间不是固定回合，巡逻是一小时，练功可以跨几天。装备有稀有度，但不要数值面板，用材质和光泽体现。

系统会生成世界、角色、物品、证据、关系、当前场景和可选动作。开放世界支持自由输入动作；分支互动会给出可点击选项。配置封面 / 图片服务后，角色、物品、证据、场景都可以生成图，并在对话流里滚动显示。

核心特性

Studio Chat + Action Surface

Studio Chat 不再只是问答框。它可以创建长篇、跑短篇、生成封面、启动 Play、编辑持久化文本文件，并在需要执行重动作前给出确认。普通讨论会直接回答；明确创作动作才进入工具执行。

InkOS Play：开放世界与分支互动

Play 维护一个可持续推进的世界状态：角色、地点、物品、证据、关系、时间、场景和 HUD。它不是固定 RPG 模板，你可以用自然语言定义世界契约：修仙装备可以有稀有感，恋爱本可以有心动层级，侦探本可以有