KohakuTerrarium 1.0.0 發布，提供通用 Agent 框架，避免重複重建底層架構

KohakuTerrarium 1.0.0 發布，提供通用 Agent 框架，避免重複重建底層架構。

KohakuTerrarium 是專為建構 Agent 而設計的框架，而非另一個 Agent 產品，它解決 LLM/Agent 領域中每個團隊從零開始重建底層邏輯的尷尬現況，讓新 Agent 僅需設定檔和少量自訂模組即可實現。過去兩年湧現眾多 Agent 產品如 Claude Code、Codex、OpenClaw、Gemini CLI、Hermes Agent、OpenCode 等，它們雖各異其趣，卻皆從頭重現相同底層：controller 迴圈、工具調度、觸發系統、sub-agent 機制、會話持久化、多 Agent 串接，每個新 Agent 形狀都需全新 repo 重建管線。

問題診斷
當前 Agent 開發僅有兩種起點：從零撰寫一切（或輔以 Pydantic AI/LangChain），或 fork 既有完整 Agent（如 opencode、openclaw）修改。此法雖可行，但主流 Agent 差異僅在少數核心特徵，非整個執行邏輯或框架，導致浪費重複勞力。KohakuTerrarium 提供第三選擇：通用 Agent 框架，讓任何人透過設定檔和系統提示建構全新 Agent，無需修改框架。

核心抽象：Creature
Creature 是獨立 Agent，包含自身 controller、tools、sub-agents、triggers、記憶與 I/O，透過「Terrarium Layer」水平組合為更大 Agent 團隊處理複雜任務。一切皆 Python 原生，可嵌入 tools、triggers、plugins 或其他 Agent 的 outputs。Creature 分解為 6 大模組：

• Controller：推理迴圈（主 LLM），少有替換需求。
• Input：事件輸入，如 Discord 監聽、webhook、語音輸入。
• Output：結果輸出，如 Discord 發送、TTS、檔案寫入。
• Tools：動作執行，如 API 呼叫、資料庫存取、RAG 檢索。
• Triggers：自動喚醒，如計時器、排程器、頻道監視。
• Sub-agents：內部委派，如規劃、程式碼審核、研究。

5 個模組（除 controller）皆使用者可擴充，透過 config 或 Python 替換；plugins 則修改模組間連接（如提示插件、生命週期鉤子），無需 fork。

Terrarium Layer 多 Agent 架構
Terrarium 是純佈線層，管理 creature 生命週期、頻道、框架級 output wiring（自動將 creature 回合結束輸出送至指定目標），無 LLM、無決策僅運行時。Creature 不察覺身處 terrarium，仍可獨立執行。提出水平多 Agent 架構：頻道（條件/選擇性流量）、output wiring（確定性管線邊緣）、熱插拔與觀測；ROADMAP 記錄開放問題。偏好 sub-agents（垂直）處理單 creature 可分解任務，為多數「需隔離上下文」情境的簡易解。

頻道與環境
頻道為通訊基底，用於 terrarium 與單 creature 內 Agent 間互動：

• Queue：單一消費者接收每則訊息。
• Broadcast：所有訂閱者接收每則訊息。

關鍵功能

• Agent 層抽象：6 模組 creature 為一級概念，新 Agent 形狀僅需「寫 config 加少許自訂模組」，非重建運行時。
• 內建會話持久化與 resume：儲存運作狀態（非僅聊天記錄），kt resume 數小時後續接。
• 可搜尋會話歷史：每事件索引化，kt search 與 search_memory 工具供使用者/Agent 查詢過去工作。
• 非阻塞上下文壓縮：長運行 Agent 背景壓縮時持續運作。
• 全面內建 tools 與 sub-agents：檔案、shell、web、JSON、搜尋、編輯、規劃、審核、研究、terrarium 管理。
• MCP (Model Context Protocol) 支援：per-agent 或全域連 stdio/HTTP MCP 伺服器，tools 自動浮現提示。
• 套件系統：從 Git/本地安裝 creatures/terrariums/plugins/LLM presets，支援繼承組合；kt install、kt update。
• Python 原生：Agent 為非同步 Python 物件，可嵌入 tools/triggers/plugins/outputs。
• 組合代數：>> (序列)、& (平行)、| (備援)、* (重試)、.iterate (非同步迴圈) 操作符程式化串 Agent 管線。
• 多運行介面：CLI、TUI、web dashboard、桌面 app，原生支援。
• OOTB creatures：經「kt-biome」（https://github.com/Kohaku-Lab/kt-biome）提供實用 Agent/plugins，如 swe、researcher、swe_team。

生態定位

層級	產品	框架	工具/包裝器
LLM App	ChatGPT, Claude.ai	LangChain, LangGraph, Dify	DSPy
Agent	kt-biome, Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent…	KohakuTerrarium, smolagents	—
Multi-Agent	kt-biome	KohakuTerrarium	CrewAI, AutoGen

多數工具位於 Agent 層以下，或跳至多 Agent 協調（對 Agent 概念薄弱）；KohakuTerrarium 以 Agent 本身為起點。

快速啟動
60 秒示範：

pip install kohakuterrarium
kt login codex
kt install https://github.com/Kohaku-Lab/kt-biome.git
kt run @kt-biome/creatures/swe --mode cli  # 獲完整程式碼 Agent：檔案 tools、shell、web 搜尋、sub-agents、可 resume 會話；Ctrl+D 退出，kt resume --last 續接

• 單 creature：kt run @kt-biome/creatures/swe --mode cli 或 researcher。
• 多 Agent terrarium：kt terrarium run @kt-biome/terrariums/swe_team。
• Web：kt serve start。
• 桌面：kt app。
  支援 OpenRouter、OpenAI、Anthropic、Google Gemini 及 OpenAI 相容 API；kt model default gpt-5.4。

從源碼安裝（開發用，uv 為專案慣例）：

git clone https://github.com/Kohaku-Lab/KohakuTerrarium.git
cd KohakuTerrarium
uv pip install -e ".[dev]"
npm install --prefix src/kohakuterrarium-frontend && npm run build --prefix src/kohakuterrarium-frontend  # web 前端

程式化使用
Agent 為非同步 Python 值，可嵌入：

import asyncio
from kohakuterrarium.core.agent import Agent
# 多 Agent：TerrariumRuntime(load_terrarium_config("@kt-biome/terrariums/swe_team"))，shared_channels.send

組合代數示例：

# 永續 Agent 累積對話：writer >> reviewer.iterate("Write a haiku about coding")
# 平行 ensemble + 重試/備援：(fast & deep) * 2 | fast

詳見 docs/en/guides/programmatic-usage.md、composition.md、Python API。

運行介面

• CLI/TUI：cli (豐富終端)、tui (全螢幕 Textual)、plain (stdout/stdin 管線/CI)。
• Web dashboard：Vue + FastAPI，kt web (單次) 或 kt serve start (守護進程)。
• Desktop app：kt app (pywebview 包 web UI)。

會話與記憶
會話儲存運作狀態、tool calls、事件、草稿、sub-agent 狀態、頻道訊息、工作、可 resume triggers、config 元資料。

• Resume：kt resume (互動選)、--last、swe_team (名稱前綴)。
• 搜尋：kt search 工具供使用者/Agent 查詢過去工作。

套件與範例

• 安裝：kt install https://github.com/someone/cool-creatures.git 或 ./my-creatures -e (可編輯)。
• 執行：kt run @cool-creatures/creatures/my-agent。
  資源：
• kt-biome：官方展示 creatures/terrariums/plugins。
• examples/agent-apps/ (config 驅動)、code/ (Python)、terrariums/ (多 Agent)、plugins/。

適用對象
適合需新 Agent 形狀但不重建基底者、想自訂 OOTB creatures、嵌入 Python 既有程式、需求演進中者。不適合既有產品（如 Claude Code、Codex）已符穩定需求、思維模型不符 controller/tools/triggers/sub-agents/channels、需 sub-50 ms 每操作延遲者（詳見 boundaries.md）。

程式碼庫地圖

src/kohakuterrarium/
  core/              # Agent 運行時、controller、執行器、事件、環境
  bootstrap/         # Agent 初始化工廠 (LLM、tools、I/O、triggers、plugins)
  cli/               # kt 指令調度
  terrarium/         # 多 Agent 運行時、拓撲佈線、熱插拔、持久化
  builtins/          # 內建 tools、sub-agents、I/O、TUI、使用者指令、CLI UI
  builtin_skills/    # Markdown 技能清單
  session/           # 會話持久化、記憶搜尋、embeddings
  serving/           # 傳輸無關服務管理、事件串流
  api/               # FastAPI HTTP + WebSocket
  compose/           # 組合代數原語
  mcp/               # MCP 客戶端管理
  modules/           # 基協議 (tools、inputs、outputs 等)
  llm/               # LLM 提供者、設定檔、API 金鑰
  parsing/           # Tool-call 解析、串流處理
  prompt/            # 提示聚合、plugins、技能載入
  testing/           # 測試基建
src/kohakuterrarium-frontend/  # Vue 前端
kt-biome/                     # 獨立 repo OOTB 包
examples/                     # 範例
docs/                         # 文件

各子包有 README 記述檔案、依賴方向、不變式。

文件地圖
完整文件於 docs/：

• Tutorials：First Creature、Terrarium、Python Embedding、Custom Tool、Plugin。
• Guides：Getting Started、Creatures、Terrariums、Sessions、Memory、Configuration、Programmatic Usage、Composition、Custom Modules、Plugins、MCP、Packages、Serving、Examples。
• Concepts：Glossary、Why KohakuTerrarium、What is an agent、Modules、Multi-agent、Patterns、Boundaries。
• Reference：CLI、HTTP、Python API、Configuration、Builtins、Plugin hooks。

路線圖與授權
近期待辦：更可靠 terrarium 流程、豐富 CLI/TUI/web UI 輸出/互動模組、更多內建 creatures/plugins/整合、守護進程長運行/遠端工作流（ROADMAP.md）。授權 KohakuTerrarium License 1.0（基 Apache-2.0 加命名/歸屬要求）：衍生作須含「Kohaku」或「Terrarium」、提供可見連結歸屬。版權 2024-2026 Shih-Ying Yeh (KohakuBlueLeaf) 與貢獻者。