创建日期：2026-09-06 ｜ 最近更新：2026-09-14 内容以本地仓库 InkOS v1.8.0（Narcooo/inkos，2026-09 拉取）为准

InkOS 入门：从装好到写出第一本书

InkOS 是一个面向故事创作与多语言翻译的 AI Agent 系统：长篇连载、独立短篇、剧本剧作、同人番外、仿写续写、互动影游、开放世界和长文翻译，都能从同一个工作台开始。它不只是"套 Prompt 的写作工具"，底层是一套完整的 Agent 工程实现（基于 pi-agent harness）——这也是本文档把它单独开一个栏目的原因：既能当写作助手用，又是一份绝佳的 agent 架构学习样本，正好接上"深度体验 → 拆解 → 提升自己的 agent 开发能力"这条学习线。

本文定位

本文是 InkOS 系列的第 0 篇（入门），目标是让一个完全没用过的人，在 30 分钟内装好、配好、写出第一本书，并且能在磁盘上说出"我的书到底存成了什么"。之后的学习路径大致是：

篇	主题	状态
0	入门：装好 / 配好 / 写出第一本书（本文）	✅
1	深度体验：命令地图、单章流水线手动跑、批量/守护、模型路由与审阅闸门、调参与坑	✅
2	架构拆解：agent 分几类、状态机、FTS5 检索、37 维审计、原子提交	✅
3	为什么不用 LangGraph：零依赖事实、四件套对照（reducer/图/checkpointer/interrupt）、五条「拿回控制权」的收益与版本 scope 坑	✅

1. InkOS 到底是什么

一句话：一个把"写长篇小说"工程化的 AI Agent 系统——它用一个统一的生产 harness 串起创作全流程，把设定、角色、记忆、伏笔、审稿、修订、状态这些"写长篇最容易翻车的东西"交给代码层管理，而不是全赌模型记性。

先看它给自己的定位（v1.8.0 引言，值得逐字读两遍）：

InkOS 1.8.0 把"Chat Agent 调工具"和"各类作品管线"收敛成一套围绕 pi-agent 的生产 harness。模型负责理解、提议和调用能力；InkOS 负责确认、上下文、状态、原子落盘和产物真实性。

它能创作什么

形态	说明
长篇小说	从创作简报建书，生成世界观/角色/卷纲/章节意图，按"写作→审稿→修订→状态结算"推进
InkOS Short（短篇）	一句方向描述直接产出一整套短篇包（正文、大纲记录、审稿记录、简介卖点、封面提示词、可选封面图）
剧本 / 分镜 / 互动影游	各自独立 Skill 与状态模型，可导出
InkOS Play（互动）	开放世界 / 分支互动：自然语言定义世界契约，系统维护世界状态、角色、物品/证据/关系、可点选项与自由动作
翻译	长文 / EPUB / TXT / Markdown 多语言本地化（v1.7+）
文风仿写 / 续写 / 同人	`style import` 文风指纹、`import chapters` 导入正文续写、`fanfic init` 同人四模式

语言上：中文默认；--lang en 切英文（含 LitRPG / Progression Fantasy / Isekai 等 10 套英文题材档案）。

三种交互面，一个内核

Studio：Web 工作台（Vite + React + Hono），聊天 + 建书 + 短篇 + 封面 + Play 全在一个页面；
TUI：终端全屏界面，斜杠命令操作；
CLI：命令与脚本、守护进程、外部 Agent 调用。

三者共用同一套"执行面"，这也是它和"聊天玩具"的分水岭。

先建立四个心智模型（重要）

动手之前，先把这四条刻进脑子，后面所有操作都好理解：

模型提议，宿主执行。 你说话 → Agent 理解并"提议"一个结构化 action（写章、审计、改封面提示词…）→ InkOS 确认（重动作弹确认卡）后，用确定性工具执行。模型不是嘴上答应，而是调用工具。
完成以文件和工具结果为准。 Agent 说"写完了"不算数，正文落盘、工具返回成功才算。所以你可以放心让它跑整条流水线。
设定/伏笔/角色是状态机，不是上下文。 书的记忆由 schema 校验的 JSON 维护（伏笔状态只能是 open/progressing/deferred/resolved，lastAdvancedChapter 必须是整数…），写入走 immutable + 原子落盘。坏数据直接拒绝，不会滚雪球。
SKILL.md 只是"说明书"，不给权限。 InkOS 用标准 SKILL.md 扩展专业能力，但它只提供指令和静态参考资料，不会因此获得新的文件/网络/写权限——创建、写文件、生成图仍由 InkOS 工具与确认闸门控制。这条对理解"Skill 安全模型"极关键。

对比一下：普通 ChatGPT = "你帮我写，全靠我上下文里那点设定"；InkOS = "设定、状态、审稿、修订全部是代码管理的流水线，我只负责调模型做其中'创造'的部分"。这也正是写长书不崩、可回滚、可续写的原因。

2. 安装与环境

环境要求

Node.js ≥ 22（源码里 .nvmrc/.node-version 写死 22；记忆库/若干新特性依赖 22+）
源码跑需要 pnpm ≥ 9；npm 全局装则不需要

方式 A：npm 全局安装（推荐，开箱即用）

npm i -g @actalk/inkos

npm 包名是 @actalk/inkos（不是 inkos），装完后得到 inkos 命令（bin 指向 CLI 的 dist/index.js）。
包里自带 skills/SKILL.md，如果你在搞 agent，可直接把它当 Skill 喂给 Claude Code / OpenClaw。

验证：

inkos --version
inkos --help

方式 B：跑源码（适合后续拆解）

git clone https://github.com/Narcooo/inkos
cd inkos
pnpm install        # monorepo：packages/cli + core + studio
pnpm build          # 依次构建 core → cli / studio

仓库结构（先认个脸，拆解篇会细讲）：

目录	角色
`packages/cli`	`@actalk/inkos`：命令入口、TUI（基于 ink/react）
`packages/core`	`@actalk/inkos-core`：核心 harness，agent 逻辑、状态、检索、各创作管线，依赖 `@mariozechner/pi-ai` / `pi-agent-core`（Mario Zechner 的 pi）、zod、typebox
`packages/studio`	`@actalk/inkos-studio`：Web 工作台（前端 Vite/React + 后端 Hono），依赖 `@xyflow/react`（流程图）、zustand、shiki 等
`skills/SKILL.md`	一个 47KB 的 Agent Skill 说明（OpenClaw 元数据 + 使用契约）
`test-project/`	样例项目配置（`inkos.json`）

另外有官方网页版（README 里的 huohuaapi.com/apps），但本系列重点在本地——能看文件、能拆源码。

3. 第一次配置：连上大模型（最容易卡的一步）

InkOS 把 LLM 配置切成两条互不污染的路径，新手先认清再动手，能避开 90% 的配置坑。

	方式一：Studio 服务配置	方式二：CLI / env 配置
适合	本地写作、Web 工作台、可视化	终端批处理、服务器/CI/Docker/守护进程
存哪	项目内 `.inkos/secrets.json`（API Key）+ `inkos.json`（service/model）	`~/.inkos/.env`（全局）或项目 `.env`（覆盖）
谁来读	Studio 只认这一套，无视 env	CLI/daemon 以 Studio 配置为底，再叠加 env + 参数

路线 A（新手推荐）：Studio 里点几下

inkos init my-novel     # 初始化一个项目目录
cd my-novel
inkos                   # 等价 inkos studio，启动 Web 工作台

浏览器打开 http://localhost:4567（-p 可换端口），进「模型配置」：

选服务商：Google Gemini、Moonshot/Kimi、MiniMax、智谱、百炼、DeepSeek、硅基流动、火山、腾讯混元、讯飞、OpenRouter…或自定义 OpenAI 兼容端点；
粘贴 API Key → 点「测试连接」；
选可用模型 → 保存；
回到书籍页开始写作。

Studio 只读这一串（从高到低）：provider bank 默认值 → inkos.json 的 services / service / defaultModel → .inkos/secrets.json 的 service Key。就算你写了 ~/.inkos/.env 或项目 .env，Studio 也只用提示、不覆盖——Key 永远不会被写进 inkos.json。

路线 B：纯命令行（一条龙）

# 一次性设全局 env（写入 ~/.inkos/.env）
inkos config set-global \
  --provider custom \
  --base-url https://api.moonshot.cn/v1 \
  --api-key sk-xxxx \
  --model kimi-k2.5

或手写 ~/.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_DEFAULT_LANGUAGE=zh

常用变量一览：

变量	作用
`INKOS_LLM_PROVIDER`	`openai` / `anthropic` / `custom`
`INKOS_LLM_BASE_URL`	OpenAI 兼容端点
`INKOS_LLM_API_KEY`	API Key
`INKOS_LLM_MODEL`	模型名
`INKOS_LLM_SERVICE`	显式服务名（moonshot/google/minimax…），避免反推歧义
`INKOS_LLM_TEMPERATURE` / `INKOS_LLM_THINKING_BUDGET`	采样 / thinking 预算
`INKOS_LLM_DEFAULT_LANGUAGE`	默认 `zh`，`en` 切英文
`INKOS_LLM_EXTRA_*`	额外透传参数（`max_tokens`/`temperature` 等保留键会被自动过滤，防覆盖核心请求）
`TAVILY_API_KEY`	可选：网页检索（`.env` 模板里提示）

CLI 的配置合成顺序（从底到顶，后者覆盖前者）：

Studio/project service 配置
→ .inkos/secrets.json service key
→ 全局 ~/.inkos/.env
→ 项目 .env
→ 当前进程环境变量
→ CLI 参数（如 --service/--model）

也就是说 CLI 默认能直接复用 Studio 配好的服务；env 里声明了对应项才会覆盖。老项目只写 baseUrl + model + apiKey（不写 service）也能用，会尝试从 baseUrl 反推服务。

排错：`inkos doctor`

任何连不上、配不对，先跑它：

inkos doctor

它会显示当前的 effective config mode、service/model/Key 各来自哪一层，并做真实 API 连通性测试。三种模式：

模式	含义
`studio-project`	Studio 运行时，只用 Studio/project 配置 + secrets
`cli-project`	CLI 运行时，Studio 配置 + env/参数覆盖
`legacy-env`	老项目纯 `.env` 兼容

新手常见坑

service 与 model 错配：--service google --model kimi-k2.5 会直接报错——InkOS 内置"模型归属校验"，避免把模型发错服务商；
Studio 配了半天没生效：Studio 不吃 env，去「模型配置」页或 .inkos/secrets.json 检查；
Gemini：AI Studio 的 Key 可直接用于 Gemini 的 OpenAI 兼容端点（InkOS 会自动禁用 Google 不支持的 store 参数）；
MiniMax：默认走官方 /v1 OpenAI 兼容入口，并自动用非流式 transport，规避"流式返回 usage 正常但正文为空"的问题；
Node 版本：< 22 会导致部分特性（SQLite 记忆库等）不可用。

4. 写出第一本书（CLI 主线）

初始化并建一本玄幻书：

inkos init my-novel
cd my-novel

inkos book create --title "吞天魔帝" --genre xuanhuan   # 建书
inkos write next 吞天魔帝                                 # 写下一章（草稿→审计→按配置修订）
inkos status                                             # 看状态
inkos review list 吞天魔帝                                # 审阅草稿
inkos review approve-all 吞天魔帝                         # 批量通过
inkos export 吞天魔帝                                     # 导出全书（默认 txt/md）
inkos export 吞天魔帝 --format epub                       # 导出 EPUB（手机/Kindle 阅读）

项目里只有一本书时，[id]（书名/ID）可以省略，自动检测。

这条链背后发生了什么

write next 默认走 plan → compose → write 的输入治理链路，正文部分 = draft（草稿）→ audit（审计）→ revise（修订）→ 状态结算。审计不通过时默认最多自动修订 1 次，仍解决不了的问题会留在结果里交给你（想更自动：inkos config set writing.reviewRetries 3）。

把它拆成原子命令（划重点）

同样的能力可以手动分步，每步独立、可出 JSON、可被外部 Agent / 脚本调用——这是拆解它时要重点看的结构：

inkos plan chapter 吞天魔帝 --context "本章先写师徒矛盾"   # ① 生成章节意图 intent.md（调 LLM）
inkos compose chapter 吞天魔帝                            # ② 只编译本地文档+状态（不调 LLM，可离线验证输入）
inkos draft 吞天魔帝 --context "..."                      # ③ 只写草稿
inkos audit 吞天魔帝 31                                   # ④ 审计第 31 章
inkos revise 吞天魔帝 31                                  # ⑤ 修订第 31 章

所有命令支持 --json 出结构化数据；draft / write next 支持 --words 覆盖每章目标字数（--words 是目标值，系统推导允许区间，不承诺逐字命中；超区间只做 1 次纠偏，不硬截断）。

直接写一篇短篇也很快：

inkos short run \
  --direction "都市婚姻反转，女主拿到账本证据后反杀" \
  --chapters 12 \
  --chars 1000

5. 在 Studio / TUI 里再走一遍

Studio Chat：一句话触发重动作

Studio 里建书、写短篇、做封面、开 Play、改正文都是同一个对话入口，重动作先弹确认卡，生成物可预览。试试直接说：

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

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

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

短篇产物落在 shorts/<故事名>/final/：full.md + sales-package.md（简介卖点）+ cover-prompt.md（封面提示词），配置封面服务后还会生成 cover.png；
封面可独立生成到 covers/<标题>/，且之后能在 chat 里改提示词并重新生成（改 coverPrompt 重写 + 重生成，不用重跑正文）；
Play 会生成世界状态、角色、物品/证据/关系、当前场景和可选动作，每回合状态写回本地。

TUI：终端全屏

inkos tui 进入全屏界面，斜杠命令走结构化入口：/new（建书）、/short、/play、/cover、/write、/confirm、/cancel，会话级 /model <模型名> 切模型；普通自由文本仍交给 Agent 理解。

6. 你的书在磁盘上长什么样（重要认知）

inkos init 会生成（已对照源码确认）：

my-novel/
├─ inkos.json          # 项目配置：llm 服务/model、notify 通知、daemon 计划等
├─ .env                # 项目级 LLM 覆盖模板（默认全注释）
├─ .gitignore          # 自动补 .env / node_modules / .DS_Store
├─ .nvmrc  .node-version   # node 22
├─ books/              # 每本书一个子目录
├─ radar/              # 平台趋势扫描缓存（雷达 Radar 用）
├─ shorts/…/final/     # 短篇产物（full/sales-package/cover-prompt/cover.png）
└─ covers/<标题>/…      # 封面产物

一本书内部（README 里的 story/... 相对路径，实际都在 books/<bookId>/story/）：

路径	是什么	给谁看
`story/state/*.json`	权威结构化状态：当前状态、伏笔、章节摘要（Zod 校验）	机器
`story/memory.db`	SQLite 时序记忆库（Node 22+），相关性检索历史事实/伏笔/摘要	机器
`story/author_intent.md`	这本书长期想成为什么（可编辑控制面）	人
`story/current_focus.md`	最近 1-3 章注意力拉回哪里（可编辑控制面）	人
`story/current_state.md` `pending_hooks.md` `chapter_summaries.md` `character_matrix.md` 等	结构化状态的 Markdown 投影	人
`story/runtime/chapter-XXXX.intent.md / context.json / rule-stack.yaml / trace.json`	每章的运行产物：意图、实际选入的上下文、规则栈、输入编译轨迹	意图给人，其余给系统调/排错
`story/bible.md` `book_rules.md`	世界观设定、本书创作规则（建书时生成）	人
`.inkos/secrets.json`、`.inkos/backups/`	服务 Key、整书备份	机器

核心认知：Markdown 是给人看的投影，JSON 才是权威真相。 早期版本要求模型直接输出完整 markdown 来"改状态"，现在改由 Reflector（反射器）输出 JSON delta → 代码层做 immutable 更新 + Zod 校验后再落盘 → 再生成给人看的 markdown 投影。旧书首次运行会自动从 legacy Markdown 迁移到结构化 JSON。这正是"状态可信、可回滚"的根本原因，也是后续拆解重点。

7. 为什么它敢写长书：质量机制速览

写几十章不出戏，靠的是下面这套工程，而不是模型运气。

控制面 + 输入治理

写每一章前不是把所有材料塞进上下文，而是先编译：

Planner 读作者意图 + 当前焦点 + 记忆检索，产出"本章意图"（must-keep / must-avoid）；
Composer 按任务选上下文，编译出 context.json + 规则栈；
Writer 基于精简上下文写正文。

创作规则分三层叠加：写手内置 ~25 条通用规则 → 题材专属规则 → 每本书的 book_rules.md（主角人设、数值上限、自定义禁令）。brief、卷纲、书级规则、当前任务不再混成一坨 prompt。

分工：一组角色 Agent

Agent	职责
雷达 Radar	扫描平台趋势 / 读者偏好，指导方向（可插拔）
规划师 Planner	产出本章意图
编排师 Composer	选上下文、编译规则栈与运行产物
建筑师 Architect	建书/导入时生成基础设定（世界观、规则、角色）
写手 Writer	基于精简上下文生成正文（字数治理 + 对话引导）
观察者 Observer	从正文提取 9 类事实（角色/位置/资源/关系/情感/信息/伏笔/时间/物理状态）
反射器 Reflector	输出 JSON delta（非全量 markdown），代码层校验后写入
归一化器 Normalizer	正文明显偏离字数范围时才单 pass 压缩/扩展
连续性审计员 Auditor	对照状态/控制文档验证草稿，37 个维度
修订者 Reviser	修审计发现的关键问题（默认最多 1 轮）

每章链路：

长期记忆三层 + 审计

权威状态：story/state/*.json（校验过）；
人类投影：*.md；
SQLite 时序库 memory.db：按相关性检索历史事实/伏笔/摘要，避免全量注入把上下文撑爆。

连续性审计员对照这些状态查每一章——角色"想起"从没见过的事、拿出两章前已丢的武器，都会被捉到。37 维覆盖角色记忆、物资连续性、伏笔回收、大纲偏离、叙事节奏、情感弧线，还内置 AI 痕迹检测（高频词、句式单调、过度总结等"LLM 味"）。

去 AI 味 & 文风仿写

去 AI 味规则内置于写手 prompt 层（疲劳词表、禁用句式、文风指纹注入），从源头减痕迹；inkos revise --mode anti-detect 可对已有章节做反检测改写，inkos detect 可做 AIGC 检测；
inkos style analyze <file> 提取文风指纹（句长分布、词频、节奏），inkos style import 注入指定书——之后每章自动采用该风格，修订者也用它做审计。

可靠性兜底

每章自动状态快照，inkos write rewrite <id> <n> 可回滚任意章节；
正文/状态/伏笔先在章节工作区校验再原子提交——不会出现"状态已推进、正文没落盘"；
写手落笔前输出自检表（上下文/资源/伏笔/风险），写完输出结算表；文件锁防并发写；
模型输出上限由 provider bank 的模型卡管，extra/INKOS_LLM_EXTRA_* 里的保留键自动过滤，防止意外覆盖核心请求参数。

8. 进阶玩法 & 接进你自己的 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 自动回退全局模型。（写手 Claude / 审计 GPT / 雷达本地模型是官方建议姿势。）

后台守护 + 通知

inkos up    # 后台按 daemon 计划自动写章（写进 inkos.log，-q 静默）
inkos down

通知支持 Telegram / 飞书 / 企业微信 / Webhook（HMAC-SHA256 签名 + 事件过滤）——长书挂机写，完事叫你。

续写 / 同人 / 推演

inkos import chapters 吞天魔帝 --from 已有正文.txt   # 导入旧文续写，重建状态
inkos fanfic init --from source.txt --mode canon     # 同人：canon/au/ooc/cp 四模式
inkos forecast create 吞天魔帝                        # 非正史剧情分支推演（不污染正史）

接入 Claude Code / OpenClaw（跟本栏目最相关的玩法）

InkOS 是标准的 Agent Skill：

# 方式一：从 ClawHub 装
clawhub install inkos

# 方式二：装 npm 包或 clone 本仓库，自带 skills/SKILL.md，Agent 直接读

装好后，Agent 应优先走共享交互入口：

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

这个入口与 TUI / Studio 共用同一执行内核，结构化输出包含 assistant 文本 + session 信息；真正的执行结果以工具结果和落盘文件为准；
对话里可用 @skill-id 强制启用某 Skill（如 @detective-play 做一个证据链驱动的开放世界）；
外部 Skill 只提供说明与静态资料，不会绕过 InkOS 的工具权限与确认闸门。

想在自己的 Claude Code 里直接用，可以把 skills/SKILL.md 放进项目 .claude/skills/ 或用户 ~/.agents/skills/，或用 INKOS_SKILL_DIRS 指向它。注意它 metadata.openclaw.requires.env 写的是 OPENAI_API_KEY，但实际支持 INKOS_LLM_* 或 Studio 服务配置，按第 3 节配即可。

9. 命令速查（精选）

命令	作用
`inkos init [name]`	初始化项目
`inkos` / `inkos studio`	启动 Web 工作台（默认 4567）
`inkos tui`	终端全屏 TUI
`inkos book create --title X --genre Y [--brief file]`	建书（`--brief` 传创作简报脑洞）
`inkos write next [id]`	完整管线写下一章（`--count` 连写、`--words` 改字数）
`inkos plan/compose/draft/audit/revise`	分步原子命令（`--json`）
`inkos review list / approve-all [id]`	审阅 / 批量通过
`inkos status [id]` / `inkos export [id] --format txt/md/epub`	状态 / 导出
`inkos short run`	产出独立短篇包
`inkos config set-global / set-model / show-models`	配置 / 多模型路由
`inkos doctor`	配置诊断（连不上先跑它）
`inkos up / down`	守护进程启停
`inkos interact --json --message "…"`	外部 Agent 结构化入口

完整命令见官方 README「命令参考」表。

10. 从"入门"到"拆解"：给后续的路线图

想成为"资深使用者"，先做这串实验

用 --brief 建一本带完整设定的书，翻 story/bible.md 与 book_rules.md，看 Architect 怎么把你的脑洞"编译"成规则；
手动跑 plan → compose，读 story/runtime/chapter-*.intent.md / context.json / rule-stack.yaml / trace.json——理解"上下文是被编排的，不是硬塞的"；
故意在第 31 章引入一个伏笔矛盾，跑 audit，看 Auditor 是否捉到、37 维从哪几路检出；
调 writing.reviewRetries、--words 区间，观察字数治理的"目标值 vs 硬范围"行为；
用 style analyze/import 仿写一篇你喜欢的文风，对比前后章节；
用 import chapters 导入一部老书续写，看它如何"逆向重建"状态；
给 writer/auditor 配不同模型（多模型路由），量化 token 与质量差；
把 skills/SKILL.md 接进 Claude Code，体验 interact --json 的工具调用协议。

拆解时值得盯的观察点（为第 2 篇预留）

harness 循环：模型"提议结构化 action → 宿主执行 → 以真实 tool result 判定完成"这个循环在代码里怎么落；
确认闸门：哪些动作要人确认、重动作清单在哪定义；
状态模型：state/*.json 的 Zod schema、Reflector 的 JSON delta + immutable 写入 + 原子提交（安全章节工作区）；
检索内核：SQLite FTS5 / BM25 的投影与"来源可溯源"设计；
上下文分层：protected / compressible 与"选上下文而非全量注入"；
输入治理 v2：Planner/Composer 的编译产物与"控制文档优先于卷纲"；
模型健壮性：provider bank、模型卡、流式/非流式 transport 探测、fallback 解析器、LLM 输出保留键过滤。

一句话收尾：InkOS = "把模型当有想法的执行者，把创作当有状态、有校验、可回滚的工程"。 先照着本文写出第一本书，再去第 1、2 篇里把它拆开。

参考

项目主页 / 源码：github.com/Narcooo/inkos（README 含多语言版，命令参考以它为准）
npm：www.npmjs.com/package/@actalk/inkos
ClawHub Skill：clawhub.ai/narcooo/inkos
底层运行时：pi（@mariozechner/pi-ai、@mariozechner/pi-agent-core）
许可：AGPL-3.0
本文事实基于本地 Narcooo/inkos master（v1.8.0，commit 09104838）核对；版本演进后部分命令可能变化，以 README 与 inkos --help 为准。

本文定位​

1. InkOS 到底是什么​

它能创作什么​

三种交互面，一个内核​

先建立四个心智模型（重要）​

2. 安装与环境​

环境要求​

方式 A：npm 全局安装（推荐，开箱即用）​

方式 B：跑源码（适合后续拆解）​

3. 第一次配置：连上大模型（最容易卡的一步）​

路线 A（新手推荐）：Studio 里点几下​

路线 B：纯命令行（一条龙）​

排错：inkos doctor​

新手常见坑​

4. 写出第一本书（CLI 主线）​

这条链背后发生了什么​

把它拆成原子命令（划重点）​

5. 在 Studio / TUI 里再走一遍​

Studio Chat：一句话触发重动作​

TUI：终端全屏​

6. 你的书在磁盘上长什么样（重要认知）​

7. 为什么它敢写长书：质量机制速览​

控制面 + 输入治理​

分工：一组角色 Agent​

长期记忆三层 + 审计​

去 AI 味 & 文风仿写​

可靠性兜底​

8. 进阶玩法 & 接进你自己的 Agent​

多模型路由​

后台守护 + 通知​

续写 / 同人 / 推演​

接入 Claude Code / OpenClaw（跟本栏目最相关的玩法）​

9. 命令速查（精选）​

10. 从"入门"到"拆解"：给后续的路线图​

想成为"资深使用者"，先做这串实验​

拆解时值得盯的观察点（为第 2 篇预留）​

参考​