InkOS 使用指南

1. 平台概述

InkOS 是一个面向文本与长文创作的开源 AI Agent 系统与写作工作台。它专为解决 AI 写作“长文易崩乱、上下文失控、越写越偏”等痛点设计，通过分层上下文组织、原子化指令与统一控制内核，管理长篇故事的状态、角色、世界观和剧情线。同时提供可视化 Web UI (Studio)、命令行 CLI以及与 OpenClaw/Claude Code 等外部 Agent 集成的 Agent Skill 接口。

2. 主要功能

1. 长篇小说与剧本创作：自动建立大纲、世界观、角色卡、卷纲与章节意图。内置“计划 → 构思 → 草稿 → 审稿 → 修订”治理链，保障上下文与正史逻辑不越界。
2. 剧情多线推演 (Branching)：基于当前正史推出 2-5 条彼此隔离的未来剧情分支，预览章节节拍、风险与意图匹配度，确认后才保存并切入正史。
3. InkOS Short（商业短篇与短剧）：支持一键生成独立短篇小说、短剧剧本、卖点简介、审稿记录及封面 Prompt（配置服务后可直接生成封面图）。
4. InkOS Play（互动剧情与开放世界）：允许指定世界契约、时间推进机制、角色 Agent 和物品/证据链规则，自动维护动态世界状态与选择树。
5. 专业 Skill 扩展机制：直接兼容标准 SKILL.md 格式，内置涵盖长文写作、商业短视频、剧本、分镜、长文档翻译、语义去 AI 味（Semantic De-slopping）等 15 个专业技能包。
6. 多模型灵活路由 (BYOK Multi-LLM)：支持为写作（Writer）、审稿（Auditor）等不同角色单独指定模型，最大化平衡生成质量与 API 成本。

3. 适用人群

1. 网文 / 长篇小说作家与编剧：需要维持庞大世界观、多角色关系及数十万字上下文逻辑一致性。
2. 短剧与影视策划：快速生成短剧脚本、分镜大纲及方案卖点。
3. 互动游戏与 RPG 制作人：涉及分支选择、世界状态维护及证据链驱动的互动游戏设计。
4. AI Agent 开发者：寻找可集成在 OpenClaw、Claude Code 或本地自动化流水线中的长文本创作引擎。

4. 免费与付费情况

1. 许可与价格：100% 免费且开源（开源许可为 AGPL-3.0）。项目本身不收取任何费用。
2. API 成本由用户自理 (BYOK)：采用自带密钥模式（Bring Your Own Key）。模型服务接入第三方 API（如 Google Gemini、Moonshot/Kimi、MiniMax、智谱、百炼、DeepSeek、OpenRouter 或 OpenAI 兼容格式等），产生的 API 消耗费用直接按对应平台标准结算。

5. 如何使用

5.1 安装方式

1. 全局 NPM 安装（推荐）：
2. bash

npm i -g @actalk/inkos

1. 作为 OpenClaw / Agent Skill 使用：
2. bash

clawhub install inkos

5.2 交互模式选择

1. Web UI (Studio)：在项目目录下运行 inkos studio，在浏览器打开 Visual Studio 工作台。在“模型配置”处填写 API Key 并测试连接即可开始可视化创作。
2. CLI 命令（Pipeline / Atomic）：
3. 一键管道推进：inkos write next my-book --count 3 （顺序写作 3 章，含计划 - 构思 - 写草稿 - 审稿 - 自动修订）。
4. 原子化拆解：inkos plan chapter / inkos compose chapter / inkos draft / inkos audit / inkos revise。

5.3 Natural Language Agent 模式

1. 指令式调用：inkos agent "写一部主角是治疗职业的地牢流奇幻小说"

6. 注意事项

1. 密钥安全性：在 Studio 中配置的 API Key 会保存在本地 .inkos/secrets.json 文件中，不会写入会被版本控制跟踪的 inkos.json。
2. 模型选型建议：长篇小说与复杂剧情推演极度依赖大模型的上下文遵循能力与长文本窗口，建议在全局或创作节点选用逻辑强、窗口大的模型（如 Gemini、Kimi、DeepSeek 或 MiniMax 等），简单的审稿或初稿润色节点再路由至低成本模型。
3. 正史防护：在使用分支剧情推演（Branching）时，生成的分支推演仅作为临时方案，只有显式执行确认选择后，更改才会写进“正史”与正文档案中。