KohakuTerrarium（琥珀生態瓶）深度研究報告

一句話定位

KohakuTerrarium 是 Python 原生的通用 Agent 框架，核心使命是：把過去兩年每個 Agent 產品（Claude Code、Codex、OpenClaw 等）都從零重寫一遍的「底盤」——控制器循環、工具調度、觸發系統、子智能體機制、會話持久化、多智能體接線——統一收攏到一個地方，讓下一種 Agent 形態只需要一個配置文件 + 幾個自定義模塊，而不是一個新倉庫。

生態位圖譜

KohakuTerrarium 的獨特位置：從 Agent 本身開始，而不是從底層鏈條或直接跳到多智能體編排。多數工具要么低於 Agent 層（如 LangChain），要么對「什麼是 Agent」只有很薄的概念就跳到多智能體（如 CrewAI）。

核心抽象：三層架構

1. Creature（智能體單元）

獨立 Agent，由六個模塊組成：

Creature 就是一個文件夾：配置文件 + 提示詞 + 可選自定義模塊。可以獨立運行（kt run path/to/creature），可以繼承其他 Creature，可以打包複用——且無需知道自己是在單獨運行還是在團隊中。

2. Terrarium（運行引擎）

託管 Creature 圖的運行時引擎：

• 無 LLM，無推理循環
• 擁有結構決策：連通分量、頻道註冊、熱插拔、輸出接線、會話合併/拆分記賬
• 純粹的「接線層」，負責 Creature 之間的水平協作

3. Studio（管理框架）

Web Dashboard、Desktop App、HTTP API 使用的管理層：

• 目錄視圖、身份/設置、活動會話、持久化、附加/恢復、編輯器、實時追踪
• 不推理，只管理

組合代數：Agent 即 Python 對象

from kohakuterrarium.compose import agent

async with await agent("@kt-biome/creatures/writer") as writer, \
           await agent("@kt-biome/creatures/critic") as critic:
    
    pipeline = writer >> critic  # writer 的輸出 → critic
    async for verdict in pipeline.iterate("Write a haiku about coding."):
        print(verdict)
        if "APPROVED" in verdict:
            break

運算符：

• >> 序列：運行 a，輸出傳給 b
• & 並行：同時運行，返回元組
• | 備選：故障轉移
• * 重試：最多重試 N 次
• .iterate() 迭代循環

這意味著 Agent 是可組合的值——可以嵌入工具、觸發器、插件、或其他 Agent 的輸出中。

kt-biome：官方 OOTB 生態包

安裝即用的一組實用 Agent 和插件：

Creatures（單體 Agent）

Terrariums（多智能體團隊）

插件系統

低摩擦升級：

• context_files：自動發現並注入 AGENTS.md、.cursorrules 等上下文文件
• family_guidance：針對 OpenAI/Codex、Gemini 等模型家族的特定引導

會話控制：

• cost_tracker：追蹤 token/成本，預算耗盡時可投票停止
• seamless_memory：在模型調用前後運行內部讀寫 Agent 對會話記憶進行操作

安全與防護：

• checkpoint：破壞性工具前自動 git stash
• circuit_breaker：重複失敗後開啟斷路器
• injection_scanner：掃描工具輸出中的提示注入模式
• pev_verifier：獨立驗證器檢查完成度，失敗時重新注入問題

關鍵技術特性

1. MCP（Model Context Protocol）支持

連接 stdio、streamable HTTP 或傳統 SSE/HTTP MCP 服務器：

kt mcp connect stdio ./my-mcp-server

工具自動出現在提示詞中，通過 mcp_call、mcp_list 等內置工具調用。

2. 會話持久化與恢復

kt resume --last      # 恢復最近會話
kt resume swe_team    # 按名稱前綴恢復

.kohakutr 文件存儲：對話、工具調用、事件、草稿本、子智能體狀態、頻道消息、作業、可恢復觸發器、配置元數據。

3. 可搜索的會話歷史

kt embedding <session>               # 構建 FTS + 向量索引
kt search <session> "auth bug fix"    # 混合/語義/全文搜索

Agent 可通過 search_memory 工具搜索自己的歷史。

4. 非阻塞上下文壓縮

長期運行的 Agent 在後台壓縮上下文的同時繼續工作。

5. 包管理系統

kt install https://github.com/someone/cool-creatures.git
kt run @cool-creatures/creatures/my-agent
kt update --all

支持 Git URL、本地路徑、可編輯安裝（.link 指針）。

6. 多運行時表面

與 OpenClaw 的對比

這是步子哥（用戶）最可能關心的問題，因為他本人就是 OpenClaw 用戶。

關鍵差異解讀

1. 框架 vs 應用

KohakuTerrarium 明確說自己是「framework for building agents — not another agent」。OpenClaw 則更接近「ready-to-deploy AI assistant application」——你不需要寫代碼，部署、配置、連接訊息平台就能用。

2. Agent 所有權

KohakuTerrarium 的 Creature 是「自包含」的——帶自己的控制器、工具、記憶、I/O，打包後可複用。OpenClaw 的 Agent 更多是在會話中動態加載技能，Agent 本身不像 Creature 那樣是一個獨立封裝的單元。

3. 多智能體機制

KohakuTerrarium 的 Terrarium 是專門為多智能體設計的「純接線層」：頻道、輸出接線、熱插拔、圖拓撲管理。OpenClaw 的多智能體更多通過會話委派和子代理實現，沒有專門的「圖運行時」概念。

4. 組合代數

KohakuTerrarium 提供了 >>、&、|、*.iterate 等運算符，讓 Agent 像 Python 對象一樣組合。這在 OpenClaw 中沒有直接對應——OpenClaw 的組合更多通過技能加載和會話管理實現。

適用人群

適合使用 KohakuTerrarium 的人：

1. 需要新 Agent 形態，不想從零重寫底盤 —— 已有 Claude Code/Codex/OpenClaw 等 Agent 產品，但它們的「形狀」不完全符合需求
2. 想要 OOTB Creature 且能自定義 —— kt-biome 提供了 swe、researcher 等即開即用 Agent
3. 想在現有 Python 項目中嵌入 Agent 行為 —— 因為一切都是 Python，Agent 可以嵌入工具、觸發器、插件、或其他 Agent 的輸出
4. 需求仍在演進 —— 需要快速迭代 Agent 形態，而不是被某個產品的固定形狀綁死

不適合的人：

1. 已有穩定需求的 Agent 產品用戶 —— Claude Code、Codex、OpenClaw 已經夠用
2. 無法映射到 controller/tools/triggers/channels 心智模型的人
3. 需要 sub-50ms 每操作延遲的場景 —— 這是 LLM Agent 的固有延遲，不是框架能解決的

技術架構亮點

輸出接線（Output Wiring）

解決了多智能體流水線的可靠性問題：

# terrarium.yaml creature block
- name: coder
  base_config: "@kt-biome/creatures/swe"
  output_wiring:
    - runner                              # 簡寫形式
    - { to: root, with_content: false }   # 生命週期 ping

框架級別自動交付：每輪結束時，creature 的輸出文本自動進入目標 Agent 的事件隊列。不依賴 LLM 記得調用 send_message。

頻道（Channels）適合條件性/可選性/群聊流量；輸出接線適合確定性流水線邊緣。

Agent-in-Plugin 智能防護

生命週期插件鉤住 pre_tool_execute，運行一個嵌套 Agent 審查擬議工具調用，返回 allow/deny/rewrite。插件可以調用 Agent，就像調用任何異步函數一樣。

非阻塞壓縮

長期運行 Agent 的上下文壓縮在後台進行，不阻塞推理循環。

路線圖與未來方向

根據 ROADMAP.md：

近期（1.1.x）：

• CLI 細節改進
• 新配置系統 UI/UX/後端精煉
• Bug 修復

中期（1.x）：

• TUI 重做（類似 CLI 的重設計）
• CLI 設置面板
• 更多內置 Creature、插件、集成

探索中：

• 反應式 Agent 模型：連續事件流處理，分層注意力（用於監控/警報 Agent）
• Agent 協議：能力、內容提示的諮詢合約，用於安全組合和發現
• 無縫記憶：自適應記憶檢索作為插件內 Agent（主動上下文注入，無需顯式搜索）
• 桌面應用改進：研究 pytauri 以獲得更豐富的原生集成

社區與生態

• GitHub: https://github.com/Kohaku-Lab/KohakuTerrarium
• QQ 群: 1097666427
• Discord: https://discord.gg/xWYrkyvJ2s
• Forum: https://linux.do/
• PyPI: pip install kohakuterrarium
• kt-biome: https://github.com/Kohaku-Lab/kt-biome

已知衍生項目：

• XinYu: 基於 KohakuTerrarium 的長期運行型個人 AI 伴隨系統，支持記憶、學習、原生 QQ gateway 與受控主動性

核心判斷

KohakuTerrarium 不是又一個 Agent 產品，它是 Agent 基礎設施的「提煉」。

過去兩年，每個 Agent 產品（Claude Code、Codex、OpenClaw、Gemini CLI、Hermes Agent……）都從零實現了同一套底盤。KohakuTerrarium 的價值在於：把這套底盤做一次，做好，讓下一個 Agent 形態只需要寫配置而不是寫框架。

這與當年 Web 框架的演進類似：

• 早期：每個網站從零寫 HTTP 服務器
• 後來：Django/Rails/Express 提供底盤，開發者寫業務邏輯

KohakuTerrarium 想成為 Agent 時代的「Express」——不是給終端用戶的現成產品，而是給 Agent 開發者的底盤。

對步子哥的意義：

• 如果他想構建自己的 Agent 形態（比如一個專門做論文分析的 Agent），KohakuTerrarium 比 OpenClaw 更適合——它提供了更細粒度的控制、可繼承的 Creature 配置、可打包複用的生態
• 如果他只是想使用 Agent 完成日常任務，OpenClaw 更成熟、平台集成更豐富
• kt-biome 中的 researcher、deep_research terrarium 可能與他的論文分析工作流天然契合

參考資料

1. KohakuTerrarium GitHub: https://github.com/Kohaku-Lab/KohakuTerrarium
2. kt-biome GitHub: https://github.com/Kohaku-Lab/kt-biome
3. ROADMAP.md: https://github.com/Kohaku-Lab/KohakuTerrarium/blob/main/ROADMAP.md
4. AGENTS.md: https://github.com/Kohaku-Lab/KohakuTerrarium/blob/main/AGENTS.md
5. 掘金發佈文: https://juejin.cn/post/7631138406543114286

#KohakuTerrarium #琥珀生態瓶 #Agent框架 #OpenClaw #深度研究 #小凯