1. 项目概述
InkOS 是一个开源（AGPL-3.0）的 AI 代理系统，专为创意写作而设计。它帮助作者规划、起草、审查和修订长篇连载小说、短篇小说、剧本、同人小说和互动世界，同时确保数百章内容中的人物、情节线索和世界状态保持一致。所有内容均可通过三种界面在同一个工作区中管理：网页 Studio、终端 TUI 和 CLI。
2. 背景与定位
创建初衷
使用单一提示词进行长篇生成往往会出现偏差：人物性格改变、伏笔被遗忘、前后事实相互矛盾。InkOS 通过将写作拆分为专门的代理，并将故事状态存储在结构化、可重建的记忆中（而非仅依赖模型的上下文窗口）来解决这一问题。
与同类项目的区别
- 流水线而非单一提示词： 设有专门的规划器、编排器、写作者、设定器、审计器和修订器代理。
- 持久化记忆： 规范的 JSON 状态、人类可读的 Markdown 投影以及可重建的 SQLite FTS5/BM25 搜索索引。
- 原子提交： 章节、状态、钩子和快照一起提交，因此失败的运行不会留下半更新的书籍。
- 适用范围超越小说： 短篇小说、剧本、故事板、互动剧本、同人小说、风格模仿和长文本翻译共享同一个工作区。
- 代理原生： 内置 19 项标准
SKILL.md格式的技能，并可被 Claude Code 和 OpenClaw 等其他代理驱动。
3. 功能分类
✍️ 长篇写作
- 约 6 个协作代理（规划器、编排器、写作者、设定器、审计器、修订器）
- 示例：
inkos write next、使用--count进行批量写作、inkos write rewrite、inkos review、inkos revise - 目的：生成情节和人物一致的分章内容。
🧠 记忆与控制
- 示例：规范的 JSON 状态、Markdown 投影、SQLite FTS5/BM25 索引、
author_intent.md和current_focus.md、每章上下文追踪 - 目的：保持长篇故事连贯，并让作者掌控方向。
📖 短篇小说与封面
- 示例：
inkos short run、inkos short revise、大纲、审查记录、销售文案、封面提示词和可选的封面图片 - 目的：生成完整的短篇作品及其配套素材。
🎮 互动剧本
- 示例：开放世界模式、分支故事、可点击选项、自由操作、HUD、自动插图
- 目的：将故事世界转化为可玩的体验。
🎨 风格、同人与导入
- 示例：
inkos style analyze、inkos fanfic init（正典、AU、OOC、CP 模式）、inkos import chapters、inkos import canon - 目的：模仿某种风格、扩展现有作品或从已有章节继续创作。
🔌 模型、技能与自动化
- 19 项内置技能；每个代理支持多模型路由
- 示例：OpenAI Chat/Responses、Anthropic Messages、Gemini、DeepSeek、OpenRouter、Ollama 和 LM Studio；守护进程模式（
inkos up）；通过 Telegram、飞书、企业微信和签名 webhook 发送通知 - 目的：让 InkOS 适配你自己的模型设置和工作流程。
4. 核心亮点
- 多代理写作流水线： 每个阶段职责单一，使输出更易于审查和修复。
- 可重建记忆： 搜索索引可从规范状态重新生成，Markdown 投影保持可读和可编辑。
- 基于证据的审计： 审计器记录带有证据的观察结果；只有在你要求时才会进行修订。
- 三种界面，一个工作区： 无需切换项目即可在 Studio、TUI 和 CLI 之间自由切换。
- 灵活的模型支持： 可混合使用不同提供商，并将不同代理路由到不同模型（包括本地模型）。
- 可扩展技能： 支持项目级、用户级和环境指定的技能目录，
@skill-id可强制某一轮使用指定技能。
5. 按角色划分的使用场景
- 普通开发者： 使用 CLI 编写书籍创建和导出脚本（许多命令支持
--json输出），或通过技能将 InkOS 嵌入代理工作流。 - 作者与创作者： 以一致的世界状态起草连载小说、短篇小说和同人小说。
- 游戏与互动媒体设计师： 原型化分支叙事和开放世界场景。
- DevOps/SRE： 运行守护进程（
inkos up/inkos down），并通过使用 HMAC-SHA256 签名的 webhook 接收通知。 - 研究人员： 研究多代理长上下文生成和结构化记忆设计。
6. 快速上手
查找所需内容
inkos --help
inkos doctor
浏览仓库中的 docs/ 文件夹和 skills/ 目录。
安装与集成
需要 Node.js 22.16 或更高版本。
npm i -g @actalk/inkos
inkos init my-novel
cd my-novel
inkos
在 Studio 设置中或通过 CLI 配置模型：
inkos config set-global --provider <provider> --base-url <url> --api-key <key> --model <model>
典型 CLI 流程：
inkos book create --title "My Novel" --genre xuanhuan
inkos write next "My Novel" --count 5
inkos export "My Novel" --format epub
在 OpenClaw 中将其用作技能：
clawhub install inkos
参与贡献
pnpm install
pnpm dev
pnpm test
pnpm typecheck
阅读 CONTRIBUTING.md，然后提交 issue 或拉取请求。
7. 项目结构
inkos/
├── packages/ # 工作区包（core、CLI、Studio）
├── skills/ # 内置技能（SKILL.md 格式）
├── docs/ # 文档
├── spec/ # 规范
├── scripts/ # 维护脚本
├── test-project/ # 用于测试的示例项目
├── assets/ # 图片和静态资源
├── README.md # 中文 README
├── README.en.md # 英文 README
├── CONTRIBUTING.md
├── CHANGELOG.md
└── pnpm-workspace.yaml
8. 相关生态
- pi agent runtime（
@mariozechner/pi-ai、@mariozechner/pi-agent-core）：InkOS 2.0 所基于的框架。 - Studio 技术栈： Vite、React 和 Hono。
- 存储与验证： SQLite FTS5/BM25 和 Zod 模式。
- 模型提供商： OpenAI 兼容、Anthropic、Google Gemini、DeepSeek、OpenRouter、Ollama、LM Studio 等。
- 代理平台： 通过技能支持 Claude Code 和 OpenClaw/ClawHub。
9. 许可证
InkOS 以 AGPL-3.0 许可证发布。
- ✅ 允许使用、修改和分发本软件，包括商业用途。
- ✅ 允许为个人写作项目私下运行。
- ❌ 禁止分发修改版本而不以相同许可证提供相应源代码。
- ℹ️ 如果你将修改版本作为网络服务提供，AGPL-3.0 要求你向用户提供其源代码。
- ℹ️ 请查阅
LICENSE并就商业集成咨询法律顾问。
10. 常见问题
问：我需要哪个 Node.js 版本？
答：Node.js 22.16 或更高版本。使用 npm i -g @actalk/inkos 安装 CLI。
问：InkOS 支持英文吗？
答：中文是主要语言，英文可通过 --lang en 标志支持。参见 README.en.md。
问：如何检查我的模型设置是否正常？
答：运行 inkos doctor。在 Studio 中配置的 API 密钥存储在 .inkos/secrets.json 中。
问：我可以从 InkOS 1.x 迁移项目吗？
答：可以。先用 inkos work migrate --json 预览，再用 inkos work migrate --apply 应用。
问：我可以使用本地模型吗？
答：可以。支持 Ollama 和 LM Studio，以及自定义端点。
11. 快速链接
- 仓库：https://github.com/Narcooo/inkos
- 文档：https://github.com/Narcooo/inkos/tree/master/docs
- 英文 README：https://github.com/Narcooo/inkos/blob/master/README.en.md
- 贡献指南：https://github.com/Narcooo/inkos/blob/master/CONTRIBUTING.md
- npm 包：https://www.npmjs.com/package/@actalk/inkos
- Issue 与讨论：https://github.com/Narcooo/inkos/issues
12. 总结
InkOS 将 AI 辅助写作转变为一种结构化、可审计的工作流，并带有持久的故事记忆，从而确保长篇项目保持一致。它适合希望获得可控长篇生成能力（涵盖小说、短篇小说和互动世界）的作者、游戏设计师和开发者，并允许自由选择自己的模型和界面。