返回博客
官小西

InkOS 深度解析:把长篇小说创作做成状态机的 Agent 系统

让模型写长篇小说的人都会撞上同一堵墙:写到第三十章,主角顺手掏出了两章前就已经丢掉的武器;三章前埋下的伏笔,模型已经彻底忘了它存在。InkOS 的 README 里就举了这两个例子——这不是模型智力问题,是状态问题。上下文窗口从 8K 拉到 1M 也没解决它,因为缺的从来不是窗口,是一份模型之外的、可校验的事实账本。

InkOS 的回答不是"换更大的模型",而是把整本书变成一台状态机。先把它的体量摆出来(截至 2026-09-14,数据来自 GitHub API 与 npm API):GitHub 9,754 stars、1,796 forks、233 个 open issues;2026-03-12 建仓,五个月累计 1,541+ 次 commit、6 位贡献者;npm 包 @actalk/inkos 过去一个月(2026-08-13 至 2026-09-11)下载 4,381 次;AGPL-3.0 许可证,当前版本 v1.8.0。还有一个数字后面会用到:最近一次提交停在 2026-08-25,距今已三周。

InkOS 是什么:不是写作玩具,是垂直生产线

InkOS 把自己定位为"Story Creation AI Agent"——面向长短篇小说、剧本、分镜、互动影游、同人创作和多语言翻译的创作智能体系统。覆盖的形态多到有点吓人:长篇连载、独立短篇(直接产出正文 + 卖点简介 + 封面提示词的商业短篇包)、开放世界与分支互动(可自定义"世界契约":修仙装备的稀有感、恋爱本的心动层级、侦探本的证据生命周期)、四种同人模式(canon / au / ooc / cp)、EPUB 导出、守护进程自动写章加 Telegram / 飞书 / 企微推送。

这些形态共享同一个执行内核,通过四个入口触达:Studio Web 工作台(Vite + React + Hono,本地 4567 端口)、终端 TUI、CLI 原子命令,以及给外部 agent 用的 inkos interact --json 结构化入口。技术栈是 TypeScript + Node 22+,pnpm monorepo,三个包:cli、core、studio。值得注意的一个工程决策:它的 agent 运行时不是自研的,构建在 Mario Zechner 的 pi 框架(@mariozechner/pi-ai / pi-agent-core)之上。作者把这写在致谢里——把模型调用循环这种轮子交给专业底座,自己的精力花在领域状态上,这个取舍本身就很"状态机思维"。

商业模式也值得一看:它是 Kimi(Moonshot)首批开源合作伙伴,拿了火山引擎的赞助,README 里挂着 huohuaapi 数据 API 的 affiliate 链接,还有一个托管网页版。赞助 + 联盟营销 + 托管版,这是中文开源 AI 工具目前最常见的三条变现路径,后面评可持续性时再回到这点。

我的判断:InkOS 不是"能写小说的 chat 套壳",而是给网文产业做的垂直生产线——它认真对待的问题是工业问题(一致性、吞吐、可恢复),不是演示问题(单次生成的惊艳程度)。

统一 Harness 与十角色流水线

v1.8.0 的架构收敛用一句话概括:模型负责理解、提议和调用能力;InkOS 负责确认、上下文、状态、原子落盘和产物真实性。README 原话——"真正的执行结果以工具结果和落盘文件为准,不从模型口头声明推断完成"。这句话值得每个做 agent 系统的人贴在显示器上,它和我之前在大厂 Agent Harness 开源之战里看到的趋势是同一件事:智能体可靠性的来源正在从模型层转移到 harness 层。

InkOS 章节生产管线

每一章默认按"规划 → 编排 → 写作 → 审计 → 必要修订 → 状态结算"运行,十角色分工:

角色 职责
Radar 雷达 扫平台趋势与读者偏好,指导方向(可插拔、可跳过)
Planner 规划师 读控制面文档 + 记忆检索结果,产出本章意图(must-keep / must-avoid)
Composer 编排师 从状态和投影中选上下文、编译规则栈,不要求在线 LLM
Architect 建筑师 建书时生成故事框架、规则、角色与长期控制文件
Writer 写手 基于编排后的精简上下文生成正文,内置字数治理与去 AI 味规则
Observer 观察者 从正文提取 9 类事实:角色、位置、资源、关系、情感、信息、伏笔、时间、物理状态
Reflector 反射器 输出 JSON delta(而非全量 markdown),由代码层校验后写入
Normalizer 归一化器 仅在正文明显偏离字数区间时单 pass 压缩或补足,不做硬截断
Auditor 审计员 37 维连续性检查:角色记忆、物资连续性、伏笔回收、大纲偏离、节奏、情感弧线,含 AI 痕迹检测
Reviser 修订者 修复审计发现的关键问题,默认最多自动修订 1 轮

两个设计细节比角色清单本身更有信息量。

第一,修订是有界的。审计不通过,管线只做一次"修订 → 再审计";仍未解决的问题保留在状态里,标记给人工或后续命令处理。想加大自动化力度可以调 writing.reviewRetries,但默认值是 1。这是对"多轮自动修复越修越烂"这一 agent 系统通病的正面回答:自动化有边界,边界之外交还给人。

第二,多 agent 在这里不是表演,是上下文分工。十个角色不是把同一个大 prompt 复读十遍,而是每个角色的输入都是被 Composer 编排过的窄上下文——审计员不需要读写作提示词,写手不需要读审计维度。这和 Anthropic 多 agent 模式里"orchestrator 给每个 sub-agent 定制任务描述"是同一个原则:上下文是按角色预算分配的稀缺资源。

三层记忆与输入治理:整仓最值得抄的部分

长篇创作里上下文工程的敌人有两个:全量注入(把整本书塞进 prompt,直到撑爆)和口头记忆(让模型自己"记住"设定,然后看着它漂移)。InkOS 对这两个问题的解法,是我在同类公开方案里见过最完整的一套。

InkOS 三层记忆与输入治理

三层记忆,每层职责单一:

层 形态 职责
权威层 story/state/*.json 单一事实来源:状态、伏笔、章节摘要,Zod schema 校验
投影层 story/*.md 人类可读副本:current_state.md、pending_hooks.md、character_matrix.md 等
检索层 story/memory.db SQLite 时序记忆,FTS5 / BM25 按相关性检索,避免全量注入

这个分层和我在给三个 AI Agent 装同一份大脑里讨论过的"知识层与记忆层分离"思路同源,但 InkOS 落得更彻底:权威数据只有一份,投影由状态生成,索引可以随时从原始文件重建——"原始文件仍是权威来源,索引可重建,检索结果保留来源与位置"。

输入治理:护栏先编译,再写作。每本书有两份长期可编辑的控制文档(author_intent.md:这本书长期想成为什么;current_focus.md:最近几章聚焦什么),写作前先编译成每章的运行时产物:

inkos plan chapter 吞天魔帝 --context "本章先把注意力拉回师徒矛盾"
inkos compose chapter 吞天魔帝
# 产出 story/runtime/chapter-XXXX.intent.md      给人看
#      story/runtime/chapter-XXXX.context.json   本章实际选入的上下文
#      story/runtime/chapter-XXXX.rule-stack.yaml 规则优先级与覆盖关系
#      story/runtime/chapter-XXXX.trace.json     输入编译轨迹,可调试

brief、卷纲、书级规则、当前任务不再混成一坨 prompt,而是先编译、可审阅、可调试。尤其聪明的一点:compose 不要求在线 LLM,你可以在没配 API Key 之前先验证输入治理的结果——把"控制输入对不对"从"生成结果好不好"里剥离出来单独测试。

去 AI 味也在这一层。写手 prompt 内置词汇疲劳词表、禁用句式、文风指纹注入(inkos style analyze 提取参考文本的句长分布、词频特征、节奏模式,style import 注入指定书籍);审计维度里专门有 AI 痕迹检测(高频词、句式单调、过度总结);还有独立的 revise --mode anti-detect 反检测改写。对一个产出物是要过平台 AIGC 检测的内容生产线,这不是锦上添花,是刚需。

写入时校验:可靠性的分水岭

前面三层是"怎么组织上下文",这一节是 InkOS 真正拉开差距的地方:坏数据在写入前被拒绝,而不是在失败后被人发现。

机制拆开看:Reflector 不再要求模型输出完整的 markdown 状态文件,而是输出 JSON delta;代码层用 applyRuntimeStateDelta 做 immutable 更新,再过 validateRuntimeState 做 Zod 结构校验——伏笔的 lastAdvancedChapter 必须是整数,status 只能是 open / progressing / deferred / resolved,不符合直接拒绝,不滚雪球。正文、状态、伏笔和运行快照先在"章节工作区"内校验,再原子提交,所以不可能出现"状态已推进、正文未落盘"的半完成态。

同一哲学贯穿所有角落:

  • 每章状态快照 + 回滚:inkos write rewrite 可回滚任意章节,文件锁防并发写;
  • 保留键过滤:env 里的 INKOS_LLM_EXTRA_* 无法覆盖 max_tokens、temperature、model、messages、stream 这些核心请求参数;
  • 模型归属校验:--service google --model kimi-k2.5 这类错配直接报错,请求根本不发出去;
  • 配置双轨隔离:Studio 只用服务页配置和 .inkos/secrets.json,CLI / daemon / 部署环境才叠加 env 覆盖,两条路径不互相污染——API Key 不落进 inkos.json;
  • 诚实的字数治理:--words 是目标而非承诺,系统推导允许区间,最多追加 1 次纠偏归一化,绝不硬截断;纠偏后仍超区间,章节照常保存但留下 warning 和 telemetry,不假装达标。

校验时机对比

这张图的右半边不是假想敌,是本站 guancyxx.cn 自己的亲身事故,下一节展开。

放进坐标系:和谁比,比什么

先说明维度选择的依据:在长篇创作里,失败成本随篇幅复利——写到 200 章时的一次设定崩坏,代价远高于单次生成的质量瑕疵。所以一致性、上下文组织、可恢复性比"单点智力"更重要,对比也围绕这三者展开。

通用 Chat 直写 通用 Agent 框架 编码 harness(Codex 类) InkOS
状态一致性 靠上下文窗口,随篇幅衰减 需自行拼装 文件系统即状态 Zod 状态机,delta 原子写入
上下文组织 全量粘贴 自行设计 仓库检索 + 规则 编译式(context.json + rule-stack)
失败恢复 从头再来 自行设计 git 每章快照 + 回滚 + 原子提交
领域纵深 无 无 编码特化 网文 / 剧本 / 互动叙事特化
上手成本 零 高 中 中(npm 一装,Node 22+)

我的立场:如果你的产出物是"章"——需要跨章一致、连载数月、随时回滚——InkOS 是四者中唯一为这个失败模式设计过的;如果你的产出物是"一次回答",它的复杂度就是纯负担,别碰。

多维度评分

维度 评分 理由
架构设计 9/10 四入口一内核,流水线降级为可调用的确定性能力;agent 循环交给 pi 底座而非自研,精力花在领域状态上
可靠性工程 9/10 写入时校验 / 原子提交 / 快照回滚 / 保留键过滤,成体系且互相咬合,是同类开源项目的最高水位
上下文工程 8.5/10 三层记忆 + 输入治理是公开方案里最完整的;扣分在没有公开的量化效果评测
产品成熟度 7/10 doctor 诊断 / EPUB / 守护进程 / 多端入口齐全;扣分在 233 个 open issues 和陡的配置面——provider bank 兼容表本身就是负担的证明
生态与商业化 6.5/10 npm + ClawHub 分发 + Kimi 首批合作是正资产;README 里赞助与 affiliate 的密度已经压过工程叙事
可持续性 6/10 6 位贡献者的 bus factor;截至 2026-09-14 已三周无提交,对一个被生产依赖的系统是明确的观察信号

对照 guancyxx.cn:四条建议与一条警告

本站是一个 Next.js 14 静态生成的双语博客:内容是 content/blog/<lang>/<category>/<YYYY-MM>/<slug>.md,frontmatter 手写,git push 之后服务器每 2 小时拉取并重建容器。和 InkOS 完全不同量级的系统,但作为"内容管道"它是同构的——都有权威数据(frontmatter vs story state)、都有校验时机问题、都有质量审计环节。两个系统先摆在一起:

维度 InkOS guancyxx.cn 内容管道
权威数据 story/state/*.json + Zod 校验 手写 YAML frontmatter
校验时机 写入时(delta 校验后原子提交) 部署时(next build),甚至不失败
检索/记忆 SQLite FTS5 / BM25 无,内部链接靠人工翻目录
质量审计 37 维 + 有界修订 写作规范清单(人和 agent 执行)
回滚 每章快照 git(已足够)

建议一:把 frontmatter 校验从部署时前移到提交时(收益最大,先做)

就在昨天的真实事故:2026-09-13 的 zh 版早报缺 frontmatter,加上根目录冒出重复的早报文件,服务器构建被阻塞,由 2026-09-14 的 commit 4614207 修复。错误是在"服务器 build 失败"时才被发现的——那是整个链路里最贵的发现时刻。

更隐蔽的是读取端的宽容降级。看 src/lib/blog.ts 的实际代码:normalizeKeywords 对任何非法输入都安静地返回 [];normalizeImage 对 SVG 路径静默返回 null(退回默认卡片图);无效 date 不报错而是"沉到列表底部";getBlogPostsMeta 的 catch 块直接返回 []——整篇文章消失也不抛错。每一处宽容单看都合理,合起来的效果是把错误推迟到最贵、最难定位的时刻。InkOS 的对照原则就一句话:坏数据在写入前被拒绝。落到本站是一个零依赖的 pre-push 脚本,大约 40 行:

// scripts/validate-posts.ts(示意)
const REQUIRED = ['title', 'date', 'category', 'keywords', 'excerpt', 'author'];
for (const file of allPostFiles()) {
  const { data } = matter(read(file));
  const missing = REQUIRED.filter(k => !data[k]);
  if (missing.length) fail(file, `缺少字段: ${missing.join(', ')}`);
  if (isNaN(new Date(data.date).getTime())) fail(file, 'date 不可解析');
  if (!['ai', 'tech', 'business', 'news'].includes(data.category)) fail(file, 'category 越界');
  if (/\.svg$/i.test(data.image ?? '')) fail(file, 'image 指向 SVG,卡片会退默认图');
  // zh/en slug 成对检查:content/blog/zh/**/foo.md 必须有 en 兄弟
}

建议二:加一层结构化索引,别让内部链接靠人脑

内部链接是本站 SEO 唯一有复利效应的动作,但现在靠作者记得哪篇文章写过什么。InkOS 的原则"原始文件是权威来源,索引可重建"直接可用:构建时生成一份内容索引(slug / title / date / category / keywords / 摘要),写作时按关键词重合度给出内链候选,归档页和将来的站内搜索也吃这份数据。注意规模判断:全站 174 篇 × 2 语言,JSON + 词重合就够,不需要 SQLite——抄原则,不抄实现规模。

建议三:确定性审计先行,LLM 判断后行

本站的写作规范清单里,近一半条目是确定性可判的:套话开头("本文将 / 随着…的发展")、无时间戳的量化数字、结尾缺 ## 参考资料 节、零内部链接、author 字段错误、image 指向 SVG。这些应该从"提醒人注意"升级成"脚本拒绝提交"——它们不需要智力,只需要执行。InkOS 的 37 维审计同样是这个思路的产物:能代码化的先代码化,需要品味的(叙事节奏、情感弧线)才留给模型和人类。把确定性检查交给脚本,还有个副作用红利:脚本不会幻觉,也不会累。

建议四:自动化要有界,向"审计 → 一轮修订 → 人工"看齐

本站早报已经全自动(定时任务生成、提交、部署),博客链路是"agent 起草 → 检查清单 → 人工过目后 push"。这和 InkOS 的"审计 → 最多 1 轮修订 → 人工"天然同构,方向是对的,缺的只是建议三里那道确定性闸门。同时要明确不学什么:十角色流水线和 SQLite 检索对本站是负资产——我们的瓶颈是质量和判断力,不是吞吐。有界自动化不是偷懒,是对"无限自动修复越修越糟"的防御。

一条警告,和一个有意思的趋同

警告:InkOS 是 AGPL-3.0。本地装来写小说没有任何问题,AGPL 义务不会传染你的作品;但想把它的校验代码搬进任何对外提供网络服务的项目,先咨询律师。抄模式,不抄代码。

趋同:InkOS 在 v1.8.0 放弃了私有 Skill 协议,直接采用标准 SKILL.md 作为专业能力扩展——Skill 只提供指令和参考资料,不增加执行权限,创建、写入、生成图片仍由工具和确认闸门控制。而本站的内容生产恰好也运行在一套 SKILL.md 写成的工作流上。两套完全独立演化的系统收敛到同一个答案:用 Markdown 控制文档 + 确定性闸门 + 人工确认,去管理不可靠的模型输出。这比任何单一功能都更能说明 Agent Skills 格式正在成为事实标准。

风险与局限

  • 维护负载:233 个 open issues 对 6 位贡献者;截至 2026-09-14 距最后一次提交(2026-08-25)已三周。对一个被生产环境依赖的系统,这是需要持续观察的信号。赞助收入(Kimi、火山引擎)是可持续性的正项,但 README 里 affiliate 链接的密度也提示商业化压力不轻。
  • Token 成本:一章过十个角色,每个角色至少一次完整调用。多模型路由(写手用 Claude、审计用便宜模型、雷达用本地模型)的存在本身就是成本真实的证明。长篇按章付费的用户应该先算账。
  • 数字无法独立验证:"37 维审计""15 个内置 Skills""~25 条通用创作规则"都是 README 的自我声明,效果没有公开的量化评测。本文基于 v1.8.0 README、仓库结构与 GitHub / npm API 数据的静态分析写成,未进行长跑实测——这是分析边界,先说清楚。
  • harness 保证下限,不保证上限:写入时校验保证状态"不越来越糟",但每一章的文笔上限仍由底座模型决定。状态机治漂移,不治平庸。

结论

InkOS 是"垂直 agent harness"的教科书样本:它不赌模型会变可靠,而是把不可靠的输出关进"提议 → 校验 → 原子落盘 → 审计 → 有界修订"的笼子,把长篇创作里最致命的状态漂移变成了可回滚的工程问题。

给三类读者的明确建议:写作者(尤其长篇续写、导入已有作品接着写)值得装来试,npm i -g @actalk/inkos,Node 22+ 起步;工程师把它当 harness 设计教材读,重点抄三件事——写入时校验、编译式上下文、确定性审计先行;想商用集成的,先过 AGPL 这一关。对本站,四条建议按收益排序:frontmatter 校验脚本最先做(一次事故的学费已经交过),内容索引其次,prose-lint 第三,有界自动化原则融入日常。本周就把那 40 行写掉。

参考资料

  1. Narcooo — InkOS GitHub 仓库(AGPL-3.0;截至 2026-09-14:9,754 stars / 1,796 forks / 233 open issues / 1,541+ commits / 6 contributors)
  2. Narcooo — InkOS README(中文,v1.8.0)(2026-08-17 最后整理)
  3. @actalk/inkos — npm(2026-08-13 至 2026-09-11 月下载 4,381 次)
  4. Mario Zechner — pi-mono:InkOS 的 agent 运行时底座
  5. 官小西 — 大厂 Agent Harness 开源之战:Codex、DeepSeek dsh、Grok Build 与它们的野心(2026-08-22)
  6. 官小西 — 给三个 AI Agent 装同一份大脑:TencentDB Agent Memory 知识层搭建实录(2026-08-25)
  7. 官小西 — Google 下场做 Agent Skills:一个正在赢得事实标准之争的格式(2026-08-10)
  8. guancyxx.cn commit 4614207 — "fix: remove root-level duplicate briefings, add missing frontmatter to 09-13 zh"(2026-09-14)