InkOS：開源 AI 小說寫作代理

1. 專案概覽

InkOS 是一套開源（AGPL-3.0）的 AI 代理系統，專為創意寫作而設計。它能協助作者規劃、起草、稽核與修訂長篇連載小說、短篇故事、劇本、同人小說與互動世界，同時在數百個章節中維持角色、情節線與世界狀態的一致性。所有內容都可透過三種介面在單一工作區中管理：網頁 Studio、終端機 TUI 與 CLI。

2. 背景與定位

創作緣起

使用單一提示詞進行長篇生成容易產生偏離：角色會改變、伏筆被遺忘、前後事實相互矛盾。InkOS 透過將寫作拆分成專門的代理，並將故事狀態儲存在結構化、可重建的記憶中（而非僅依賴模型的上下文視窗）來解決此問題。

與類似專案的差異

管線而非單一提示詞： 配備專門的 Planner、Composer、Writer、Settler、Auditor 與 Reviser 代理。
持久化記憶： 標準 JSON 狀態、人類可讀的 Markdown 投影，以及可重建的 SQLite FTS5/BM25 搜尋索引。
原子提交： 章節、狀態、鉤子與快照會一起提交，因此失敗的執行不會留下半更新的書籍。
不限於小說： 短篇故事、劇本、分鏡表、互動遊戲、同人小說、風格模仿與長文翻譯共用同一個工作區。
代理原生： 內建 19 個採用標準 SKILL.md 格式的技能，並可被其他代理（如 Claude Code 與 OpenClaw）驅動。

3. 功能分類

✍️ 長篇寫作

約 6 個協作代理（Planner、Composer、Writer、Settler、Auditor、Reviser）
範例：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（canon、AU、OOC、CP 模式）、inkos import chapters、inkos import canon
目的：模仿風格、延伸既有作品，或從既有章節繼續創作。

🔌 模型、技能與自動化

19 個內建技能；每個代理可進行多模型路由
範例：OpenAI Chat/Responses、Anthropic Messages、Gemini、DeepSeek、OpenRouter、Ollama 與 LM Studio；守護行程模式（inkos up）；透過 Telegram、Feishu、WeCom 與簽章 webhook 發送通知
目的：讓 InkOS 融入你自己的模型設定與工作流程。

4. 重點特色

多代理寫作管線： 每個階段都有單一職責，讓輸出更容易審閱與修復。
可重建記憶： 搜尋索引可從標準狀態重新產生，Markdown 投影則保持可讀且可編輯。
基於證據的稽核： Auditor 會記錄帶有證據的觀察結果；只有在你要求時才會進行修訂。
三種介面、一個工作區： 可在 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 或 pull request。

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 schema。
模型供應商： 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
Issues 與討論：https://github.com/Narcooo/inkos/issues

12. 總結

InkOS 將 AI 輔助寫作轉變為結構化、可稽核的工作流程，並具備持久化的故事記憶，讓長篇專案保持一致。它適合想要在小說、短篇故事與互動世界中進行可控長篇生成的作者、遊戲設計師與開發者，並可自由選擇自己的模型與介面。