Kohaku-Lab/KohakuTerrarium

它解决的问题

许多现有的代理产品（如 Claude Code、Codex 等）都各自重新实现了相同的底层机制：控制器循环、工具分发、触发器、子代理、会话、持久化和多代理连接。KohakuTerrarium 将这一共享基础放在一个地方，因此创建新的代理形态只需一个配置文件和一些自定义模块，而不是一个全新的代码库。

工作原理

KohakuTerrarium 是一个 Python 框架。核心抽象是“生物”——一个独立的代理，拥有自己的控制器（推理循环）、工具、触发器、子代理、记忆和输入/输出。生物由“Terrarium”引擎托管，该引擎管理生物图、通道、生命周期和会话记账。在其之上，“Studio”层处理管理、身份和面向用户的界面（Web 仪表板、桌面应用、HTTP API）。可选地，“Laboratory”层通过 WebSocket 将主机和引擎分离到不同机器上。代理是异步 Python 对象，具有类型化结果，因此您可以直接将它们嵌入到自己的程序中。您可以通过 CLI、TUI、Web 或桌面运行代理，并使用运算符（如 >>（顺序）、&（并行）、|（回退）和 *（重试））将它们组合成管道。

适用对象

这适用于想要构建自定义 AI 代理而无需重新发明轮子的开发人员——无论您需要单个代理、多代理团队，还是嵌入到更大 Python 应用程序（如批处理作业、机器人或管道）中的代理。它也适用于那些想要开箱即用且可定制的强大代理的人。如果您已经有一个稳定的代理产品满足您的需求，或者您需要每次操作低于 50 毫秒的延迟，这可能不适合您。

亮点

• 代理级抽象：通过编写配置和自定义模块来定义新代理，而不是重建运行时。
• 真正的 Python API：类型化的 TurnResult 轮次，超时实际取消，流式类型化事件，@kt.tool 将任何函数转换为代理工具，以及严格的错误处理。
• 内置会话持久化和恢复：会话自动保存；稍后使用 kt resume 或 Terrarium.resume 恢复。SessionReader 可离线重放任何已完成的运行。
• 可搜索的会话历史：每个事件都被索引；kt search 和 search_memory 工具让您（和代理）查找过去的工作。
• 非阻塞上下文压缩：长时间运行的代理在后台压缩上下文时继续工作。
• 全面的内置工具和子代理：文件、shell、Web、JSON、笔记本、搜索、编辑，以及用于特权节点的图编辑器工具。
• 上下文感知的侧边对话：可选的 fork 助手让您在隔离的快照中提出侧边问题，而不影响主任务。
• MCP 支持：按代理或全局连接 MCP 服务器（stdio 或 streamable-HTTP）；四个元工具即使在许多服务器下也能保持提示词简洁。
• 包系统和市场：kt install @name 通过 TerrariumMarket 解析；提供幂等的脚本端原语。
• 组合代数：>>、&、|、* 和 .iterate 运算符用于构建代理管道。
• 多种运行时界面：开箱即用包含 CLI、TUI、Web 仪表板和原生桌面应用。
• 可选的四层身份验证（主机令牌、管理员密码、多用户账户）——按层选择加入，默认关闭。