ToolKami - 让简单智能体变得容易

ToolKami 是一个开源的【概念清晰、各部分独立】的“简单”框架（观看视频），它使你能够构建并与 AI 智能体无缝协作。该框架自带一个命令行界面和精选的工具。

命令行界面 (CLI)

toolkami CLI 是对 首席执行官 Tobias 的 try 实现 进行了修改的版本。它在原有实现的基础上增加了沙箱功能，并遵循“函数式核心，命令式外壳”的设计原则（参考文章）。

使用方法

注意：tk 是 toolkami 的别名，也可以直接使用。

常用命令：

• toolkami init [PATH]：生成 Shell 函数
• toolkami cd [QUERY]：交互式选择器
• toolkami wt [NAME]：从当前仓库创建工作树
  • merge：将工作树的更改合并回父仓库
  • drop：删除工作树及其分支
• toolkami sb：从 .toolkami/docker-compose.yml 启动 Docker 沙箱
  • build [--no-cache]：构建服务镜像（可传递 Docker Compose 标志，如 --no-cache）
  • exec [CMD...]：进入沙箱容器执行命令（默认为交互式 bash）

该 CLI 旨在支持多任务、并发的智能体工作流：

安装步骤

curl -sL https://raw.githubusercontent.com/aperoc/toolkami/refs/heads/main/toolkami.rb > ~/.local/toolkami.rb

# 将 "try" 设置为可执行文件，以便直接运行
chmod +x ~/.local/toolkami.rb

# 添加到你的 Shell 配置文件（bash/zsh）
echo >> ~/.zshrc # 添加新行
echo 'eval "$(ruby ~/.local/toolkami.rb init)"' >> ~/.zshrc

框架

ToolKami 框架能够让确定性工具和动态智能体无缝协作。它以简单、可组合性和可扩展性为核心设计理念，能够很好地适应大型语言模型能力的不断提升。

所有 MCP 服务器都可以通过 UV 脚本打包成单个二进制文件进行分发（详情请见博客）。

我在一篇博客中详细介绍了默认的文件和 Shell 工具，并探讨了如何进一步优化它们（阅读原文）。

安装步骤

# 安装 UV

## macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
## Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 启动 MCP 服务器
`./servers/__main__.py`

应用场景

Google AlphaEvolve：ToolKami 风格

基于本框架实现的一个极简版 AlphaEvolve，附有详细的说明文档（查看文档）和代码（GitHub PR）。

（图片来源：https://deepmind.google/discover/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/）

社交媒体

• 官网
• 博客
• Twitter
• toolkami@aperoc.com

ToolKami 快速上手指南

ToolKami 是一个开源的轻量级 AI Agent 框架，旨在通过概念清晰、独立的组件简化智能体的构建。它提供了命令行界面（CLI）和精选的工具集，支持确定性的工具与动态的智能体无缝协作。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS, Linux 或 Windows (WSL 推荐)。
• Ruby：用于运行 CLI 脚本（大多数类 Unix 系统默认已安装）。
• Docker & Docker Compose：用于运行沙箱环境（toolkami sb 命令依赖此项）。
• UV：Python 包管理器和运行时，用于启动 MCP 服务器。
  • 注：原文未提供国内镜像源，若下载缓慢可尝试配置国内 pip/uv 镜像或使用代理。

安装步骤

1. 安装 CLI 工具

执行以下命令下载脚本、赋予权限并配置 Shell 别名：

# 下载 toolkami.rb 到本地目录
curl -sL https://raw.githubusercontent.com/aperoc/toolkami/refs/heads/main/toolkami.rb > ~/.local/toolkami.rb

# 赋予执行权限
chmod +x ~/.local/toolkami.rb

# 将初始化命令添加到 Shell 配置文件 (~.zshrc 或 ~/.bashrc)
# 注意：如果文件不存在，请先创建或手动添加换行
echo >> ~/.zshrc 
echo 'eval "$(ruby ~/.local/toolkami.rb init)"' >> ~/.zshrc

# 使配置立即生效
source ~/.zshrc

安装完成后，您可以使用 toolkami 或其别名 tk 来调用命令。

2. 安装框架依赖 (UV)

为了运行框架层面的 MCP 服务器，需要安装 UV：

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

基本使用

初始化项目

在当前目录下生成必要的 Shell 函数配置：

toolkami init [PATH]
# 例如：toolkami init .

使用沙箱环境

ToolKami 依赖 Docker 沙箱来安全地执行代码。基于当前目录下的 .toolkami/docker-compose.yml 启动服务：

# 构建服务镜像
toolkami sb build

# 进入沙箱容器交互模式 (默认启动 bash)
toolkami sb exec

管理工作树 (Worktree)

在当前的 Git 仓库中创建独立的工作树以进行并发 Agent 工作流：

# 基于当前查询创建新的工作树
toolkami wt [NAME]

# 合并更改回主仓库
toolkami wt merge

# 删除工作树和分支
toolkami wt drop

启动 MCP 服务器

进入项目目录后，使用 UV 启动默认的 MCP 服务器（包含文件和 Shell 工具）：

./servers/__main__.py

交互式选择

使用交互式选择器快速导航或选择上下文：

toolkami cd [QUERY]