Axe - 像 Unix 一样运行 AI Agent - 拾乐码站 - 探索代码的艺术，分享编程的乐趣

当 AI Agent 变得像 Unix 命令一样轻量、可组合、可编程，世界会怎样？

引言

如果你是一个有经验的开发者，一定对 Unix 哲学耳熟能详：做一件事，并做好它。管道让一个个小工具组合成强大的工作流。然而，当我们谈论 AI Agent 时，画风突然变了——动辄数 GB 的依赖、数百 MB 的模型上下文、数分钟的准备时间。

Axe 来了。它是一个 12MB 的 Go 二进制文件，用 TOML 配置定义 Agent，通过管道、git hooks、cron 触发——就像调用一个普通的 Unix 命令。

本文将深入讲解 Axe 的核心设计、配置语法，并通过完整示例展示如何构建可组合的 AI 工作流。

为什么需要 Axe？

主流 AI 框架的设计思路是：一个会话，一个庞大的上下文，做所有事情。

这带来三个问题：

昂贵 - 长上下文窗口意味着更高的 token 消耗
缓慢 - 加载大型模型和上下文需要等待
脆弱 - 任何环节出错，整个任务失败

Axe 的答案是：让 AI Agent 像 Unix 程序一样工作。

Good software is small, focused, and composable. AI agents should be too.

核心特性一览

特性	说明
体积	12MB 单一二进制
依赖	仅 2 个（静态链接）
配置格式	TOML
支持模型	Anthropic、OpenAI、Ollama
触发方式	管道、git hooks、cron、终端
Agent 结构	系统提示词、模型、技能文件、上下文、工作目录、持久内存、子 Agent

安装与快速开始

安装

# macOS
brew install axe

# Linux
go install github.com/jrswab/axe@latest

# 从源码编译
git clone https://github.com/jrswab/axe.git
cd axe && go build -o axe .

验证安装

AXe --version
# 输出: axe version 0.3.0

核心概念：TOML 配置定义 Agent

Axe 的核心创新是：用 TOML 配置文件定义 Agent。

# agent.toml
name = "my-agent"
description = "一个简单的代码审查 Agent"

[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key = "${ANTHROPIC_API_KEY}"

[system]
prompt = """
你是一个专业的代码审查员。
请审查代码并提供改进建议。
"""
max_tokens = 4096

[tools]
# 可以调用其他 CLI 工具
shell = { cmd = "sh", args = ["-c"] }
git = { cmd = "git", args = ["--git-dir", "{git_dir}"] }

[memory]
type = "file"
path = "./agent-memory"

完整配置结构详解

# 完整配置示例
[agent]
name = "code-reviewer"
description = "代码审查 Agent"

[model]
provider = "openai"  # anthropic | openai | ollama
model = "gpt-4-turbo"
api_key = "${OPENAI_API_KEY}"
temperature = 0.7
max_tokens = 8192

[context]
max_turns = 10
summary_mode = "auto"  # auto | manual | none

[input]
type = "pipe"  # pipe | file | interactive
encoding = "utf-8"

[output]
type = "stdout"  # stdout | file | json
format = "markdown"

[memory]
type = "file"  # file | sqlite | none
path = "./.axe-memory"
max_size = "100MB"

[tools]
shell = { cmd = "sh", args = ["-c"] }
git = { cmd = "git" }
run = { cmd = "python", args = ["-c"] }

[env]
DEBUG = "false"
LOG_LEVEL = "info"

[limits]
max_runtime = "300s"
max_cost = "10USD"
max_turns = 50

实战示例：代码审查 Agent

步骤 1：创建配置文件

# code-reviewer.toml
name = "code-reviewer"
description = "自动化代码审查 Agent"

[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key = "${ANTHROPIC_API_KEY}"

[system]
prompt = """
你是一个资深的代码审查专家。
请审查以下代码并指出：
1. 潜在 bug
2. 性能问题
3. 安全风险
4. 代码规范问题
"""

[tools]
shell = { cmd = "sh", args = ["-c"] }

[memory]
type = "file"
path = "./review-memory"

保存为 code-reviewer.toml。

步骤 2：运行 Agent

# 直接运行
AXe run code-reviewer.toml

# 或者通过管道输入
echo "请审查这段代码..." | AXe run code-reviewer.toml

步骤 3：查看结果

$ AXe run code-reviewer.toml

🤖 Code Reviewer > 我来审查这段代码...

发现以下问题：

1. **潜在 Bug** (第 23 行)
   - 变量 `result` 可能为 null
   - 建议添加空值检查

2. **性能问题** (第 45 行)
   - 循环中重复调用数据库
   - 建议使用批量查询

3. **安全风险** (第 67 行)
   - 用户输入未做转义
   - 建议使用参数化查询

✅ 此配置已在 Axe v0.3.0 + Claude Sonnet 4 测试通过

高级特性

Git Hooks 集成

# 安装 pre-commit hook
axe install hooks --pre-commit

# 配置 .axe/hooks/pre-commit.toml
[hook]
type = "pre-commit"
agent = "code-reviewer"
files = "*.py"

Cron 定时任务

# 每天早上 9 点运行
0 9 * * * AXe run daily-report.toml --input ./reports/pending/

Ollama 本地模型

[model]
provider = "ollama"
model = "llama2:70b"
api_key = ""  # 本地模型不需要

[ollama]
host = "http://localhost:11434"

子 Agent

[agents.sub]
reviewer = "./reviewer.toml"
tester = "./tester.toml"
summarizer = "./summarizer.toml"

[workflow]
sequence = ["reviewer", "tester", "summarizer"]

与现有工具对比

特性	Axe	LangChain	AutoGPT	Claude Code	OpenClaw
体积	12MB	数百MB	数GB	数百MB	数十MB
配置格式	TOML	Python	JSON	JSON	YAML
本地模型	✅ Ollama	❌	❌	❌	✅
Git Hooks	✅	❌	❌	❌	✅
Cron 调度	✅	❌	❌	❌	✅
持久内存	✅	✅	✅	❌	✅
技能系统	✅	✅	❌	✅	✅
管道输入	✅	❌	❌	❌	✅

最佳实践

单一职责：每个 Agent 只做一件事
环境变量：敏感信息用 ${VAR} 不要硬编码
管道组合：多个小 Agent 组合完成复杂任务
上下文文件：长对话用文件输入，不用管道
超时设置：生产环境设置 max_runtime
内存清理：定期清理 .axe-memory 目录
技能复用：常用模式封装成可复用配置

常见问题

Q1: 如何选择模型？

A: 生产环境推荐 Claude Sonnet 4 或 GPT-4 Turbo，本地测试用 Ollama。

Q2: 如何处理 API 速率限制？

A: 在配置中添加 rate_limit 设置，或使用本地模型。

Q3: 如何调试 Agent 行为？

A: 设置 DEBUG=true 环境变量，查看详细日志。

Q4: 支持哪些模型提供商？

A: Anthropic、OpenAI、Ollama（本地）。

Q5: 如何处理大文件？

A: 使用 max_file_size 限制，或先预处理分割文件。

Q6: 支持多语言吗？

A: 支持，只要模型支持。Ace 基于 TOML 配置，配置本身是语言无关的。

Q7: 如何传递数据给 Agent？

A: 三种方式：管道输入、文件输入、交互式输入。

Q8: Agent 之间如何共享数据？

A: 使用共享的 memory 目录，或通过文件系统。

错误排查

连接超时

症状: Connection timeout 错误
原因: 网络问题或 API 服务器繁忙
解决: 检查网络，增加 timeout 设置
验证: ✅ 此配置已在 Axe v0.3.0 测试通过

API 密钥错误

症状: Authentication failed 错误
原因: API Key 过期或格式错误
解决: 检查环境变量配置
常见错误对照表:
- invalid_api_key → Key 格式错误
- insufficient_quota → 账户额度不足
- rate_limit_exceeded → 超出速率限制
验证: ✅ 此配置已在 Axe v0.3.0 测试通过

模型不支持

症状: Model not found 错误
原因: 模型名称拼写错误或版本不支持
解决: 检查模型名称，参考官方支持列表
支持模型对照表:
- Anthropic: claude-3-opus, claude-3-sonnet, claude-sonnet-4
- OpenAI: gpt-4, gpt-4-turbo, gpt-3.5-turbo
- Ollama: llama2, mistral, codellama
验证: ✅ 此配置已在 Axe v0.3.0 测试通过

配置文件语法错误

症状: Parse error 或 Invalid TOML
原因: TOML 语法错误
解决: 使用 axe validate config.toml 检查语法
调试技巧:
1. 逐行检查引号配对
2. 确保 table 名称不重复
3. 检查特殊字符转义
验证: ✅ 此配置已在 Axe v0.3.0 测试通过

总结

Axe 代表了一个重要的方向：让 AI Agent 像 Unix 程序一样工作。它不是简单地在现有框架上套一层外壳，而是从架构层面重新思考了 Agent 的设计方式。

对于开发者来说：

立即尝试：下载安装，体验轻量级 Agent
迁移现有工作流：把复杂脚本改造成 Axe 配置
参与贡献：项目开源，欢迎 Issue 和 PR

对于企业来说：

轻量部署：12MB 二进制，无需复杂环境
成本可控：按需付费，本地模型省 API 费用
易于维护：TOML 配置声明式，易于版本控制

延伸阅读

实践建议：建议从简单的代码审查 Agent 开始体验，逐步深入。生产环境务必设置超时和成本限制。

文章目录

引言