【Agent工坊】Axe 实战：用 12MB 二进制文件替代 AI 框架，搭建你的专属 Agent 工具箱

227 points 登上 HN 首页，832 stars 的开源项目 Axe 把 Unix 哲学带进了 AI Agent 世界。每个 Agent 只做一件事，做好一件事，组合起来就是你的自动化军团。

▲

一、为什么会有人需要 Axe

这个问题值得先聊清楚。当下 AI 工具的主流思路是给你一个大而全的对话界面。Claude Code 是一个持续运行的会话，你在里面写代码、调试、部署。Cursor 是一个 AI 增强的编辑器。Hermes Agent 是一个完整的 Agent 运行时，带 memory、skill、cron、多模型切换。

它们都很好。但它们都假设了一个前提：你需要一个长期运行、功能齐全的 AI 工作环境。

Axe 的创作者显然不这么想。他的设计理念写在 README 第一段里：好的软件是小而专注、可组合的。把这句话翻译到 AI Agent 世界——每个 Agent 只做一件事，定义在 TOML 文件里，从命令行运行。用管道传数据进去，拿到结果出来。链式调用。用 cron 触发、git hooks 触发、CI 触发。

没有守护进程，没有 GUI，没有框架绑定。只有一个 12MB 的二进制文件加上你的配置文件。这就是 Axe 的全部。

我第一眼看到这个项目时想到的是 Ken Thompson 的名言：那些不起眼的小程序组合在一起，能完成惊人的工作。四十年后，这个原则依然成立，只是程序变成了 AI Agent。

核心特性一览：

  • 多 Provider 支持：Anthropic、OpenAI、Ollama、OpenCode、AWS Bedrock
  • TOML 声明式配置：Agent 定义即代码，可版本管理
  • 子 Agent 委托：Agent 可调用其他 Agent，支持深度限制和并行执行
  • 持久化记忆：时间戳 Markdown 日志，跨运行携带上下文
  • Skill 系统：可复用的指令集，跨 Agent 共享
  • Stdin 管道：git diff 直接传给 axe run reviewer
  • Token 预算：按运行限制累计 Token 用量，超预算自动熔断
  • MCP 工具支持：通过 SSE 或 streamable-HTTP 接入外部 MCP 服务
  • Docker 一键部署：非 root 用户、只读文件系统、全部 capabilities 已丢弃

Axe 用 Go 1.25+ 编写，提供预编译二进制文件，支持 Linux、macOS、Windows。

方式一：Go 安装，推荐

go install github.com/jrswab/axe@latest

如果你的 Go 工具链低于 1.25，这条命令会直接报错：invalid go version。解决方案有两种：从 go.dev/dl 下载新版 Go，或者直接用预编译二进制，完全不需要 Go 环境。

方式二：下载预编译二进制

从 GitHub Releases 页面下载对应平台的二进制文件，解压后放到 PATH 目录里即可。

验证安装成功：

axe version

输出应该是：axe version 1.10.0

Windows 用户特别提醒：Axe 的二进制会安装到 GOPATH 下的 bin 目录。如果你用的是 scoop 或 choco 安装的 Go，这个路径可能是 C 盘某个深处。运行 axe 报 command not found 的话，用 go env GOPATH 找到实际路径，然后加到系统 PATH 环境变量里。

三、第一个 Agent：代码审查员

Axe 的核心工作流只有三步：定义 Agent 配置、写 Skill 指令、运行。

3.1 初始化配置目录

axe config init

这条命令会在 $XDG_CONFIG_HOME/axe/ 下创建完整的目录结构，同时生成一份示例 Skill 和默认 config.toml。目录长这样：

~/.config/axe/

├── config.toml # Provider 凭证配置

├── agents/ # Agent TOML 文件存放处

└── skills/ # Skill 定义存放处

3.2 创建代码审查 Agent

第一步，脚手架生成：

axe agents init code-reviewer

这会自动创建一个名为 code-reviewer.toml 的配置文件骨架。第二步，编辑它：

axe agents edit code-reviewer

这个命令会用 $EDITOR 环境变量指定的编辑器打开文件。如果你用的是 VS Code，提前 export EDITOR=code。如果是 vim 用户，什么都不用做。

填入以下完整配置：

name = "code-reviewer"

description = "审查代码变更，发现潜在问题和改进机会"

model = "anthropic/claude-sonnet-4-20250514"

system_prompt = "你是一位资深代码审查员。审查代码变更并给出简洁可执行的反馈。"

skill = "skills/code-review/SKILL.md"

tools = ["read_file", "list_directory"]

workdir = "."

几个关键字段解释一下：model 的格式是 provider/model-id，用斜杠分隔。目前支持的 provider 前缀有 anthropic、openai、ollama、opencode、bedrock。tools 数组控制 Agent 可以调用哪些内置工具，这里开了 read_file 和 list_directory，因为审查时需要查看完整文件上下文。workdir 设成点号表示当前工作目录，Agent 的文件操作都会限制在这个目录下。

与其他框架的对比值得一提。LangChain 让你写 Python 代码来编排 Agent，CrewAI 让你定义角色和任务，它们本质上都是框架——你必须在它们的抽象层里工作。Axe 不提供框架，只提供运行环境和工具集。Agent 的定义是纯配置加 Markdown，不需要写任何代码来调用 LLM。这意味着你能用版本管理追踪 Agent 的演变，用任何编辑器修改 Skill，用管道组合多个 Agent。

3.3 编写 Skill 文件，这是质量的分水岭

Skill 是 Axe 里最重要的概念。它决定了 Agent 的专业水平。一个草草写就的 Skill 产出的结果质量和你手动调用 API 差不多。一个精心打磨的 Skill 能让你得到接近高级工程师水平的输出。

创建 ~/.config/axe/skills/code-review/SKILL.md，写入以下内容：

# Code Review Skill

## 审查维度

1. 逻辑正确性：边界条件是否处理？空值是否有检查？错误路径是否完整？

2. 安全性：有没有注入风险？会不会泄露敏感信息？权限校验够不够？

3. 性能：有没有不必要的循环？有没有 N+1 查询？内存分配是否合理？

4. 可读性：命名是否清晰？注释是否充分？函数长度是否可控？

5. 测试覆盖：变更的代码是否有对应的测试用例？

## 输出格式

按严重程度分为三级：

致命：会导致生产事故的问题，比如空指针、死循环、数据丢失风险

严重：可能导致数据不一致或安全漏洞，比如缺少权限校验、SQL 注入

建议：代码质量和可维护性改进，比如命名不规范、函数过长

每条问题必须包含三个要素：代码位置（文件+行号）、问题描述、具体的修复建议。

踩坑提醒：Skill 里引用的脚本路径必须是绝对路径。因为 run_command 在 Agent 的 workdir 下执行，而不是 Skill 目录下。如果你在 Skill 里写了 scripts/fetch.sh，Agent 会在当前工作目录下找这个文件，肯定找不到。正确写法是 /home/user/.config/axe/skills/my-skill/scripts/fetch.sh。

3.4 运行，看看效果

先设置 API Key：

export ANTHROPIC_API_KEY="sk-ant-xxx"

然后管道传代码变更：

git diff | axe run code-reviewer

这时候你会看到 Agent 开始工作。它先读取 diff 中的文件列表，然后逐文件调用 read_file 获取完整上下文，最后按 Skill 里定义的五维度逐条审查。典型输出如下：

## 代码审查结果

### 致命问题

无

### 严重问题

- handlers/user.go:45 - user.ID 未做空值检查

  如果 user 为 nil 或 ID 为空字符串，第 45 行的查询会导致空指针 panic

  修复建议：在查询前添加 if user == nil || user.ID == "" { return ErrInvalidUser }

### 建议

- handlers/user.go:12 - fetchUserData 函数超过 80 行

  建议拆分为 fetchUserProfile 和 fetchUserPreferences 两个函数

- utils/format.go:8 - 魔法数字 86400 缺少语义

  建议提取为常量 const SecondsPerDay = 86400

字段越多越好的误区：很多新手以为 tools 开得越多 Agent 越强。事实正相反。只给 Agent 真正需要的工具，它能更专注地完成当前任务。code-reviewer 只需要 read_file 和 list_directory，给它 run_command 反而可能引入安全风险。

四、管道的力量：把 Agent 嵌入现有工作流

这是 Axe 最与众不同的地方。它不提供调度器、不提供 Web 界面、不提供消息队列。它只做一件事：运行 Agent。剩下的交给 Unix。

▲

4.1 git hooks：提交前自动审查

在 .git/hooks/pre-commit 里写入：

#!/bin/sh

result=$(git diff --cached | axe run code-reviewer)

if echo "$result" | grep -q "致命"; then

    echo "$result"

    echo ""

    echo "检测到致命问题，提交已阻止。请修复后重试。"

    exit 1

fi

echo "$result"

保存后 chmod +x .git/hooks/pre-commit。现在每次 git commit 之前，Axe 会自动审查你的代码变更。发现致命问题直接阻止提交。整个过程不需要启动任何服务，不需要登录任何平台。

4.2 cron 定时任务

每天早上 9 点分析昨夜错误日志，结果推送到 Slack：

0 9 * * * cat /var/log/app/error.log | axe run log-analyzer --json | curl -X POST -d @- YOUR_SLACK_WEBHOOK

这里用了 --json 标志，输出会包裹成 JSON 格式，包含 metadata（模型、Token 用量、耗时），方便下游解析。

4.3 链式 Agent：多条流水线并行运转

Axe 的子 Agent 委托机制让流水线编排变得简单。创建一个调度 Agent：

name = "pr-review-pipeline"

description = "完整 PR 审查流水线：代码质量 + 测试覆盖 + 安全检查"

model = "anthropic/claude-sonnet-4-20250514"

system_prompt = "你是 PR 审查调度员。将审查任务分发给子 Agent 并汇总结果。"

sub_agents = ["code-reviewer", "test-coverage-checker", "security-scanner"]

[sub_agents_config]

max_depth = 2

parallel = true

timeout = 120

parallel = true 是关键。三个子 Agent 并发执行，整体审查时间约等于最慢的那个子 Agent 的耗时。如果不设置 parallel，三个 Agent 会串行执行，时间累加。

深度限制的坑：max_depth 硬上限是 5。深度怎么算？pr-review-pipeline 调用 code-reviewer 是深度 1。如果 code-reviewer 又调用了另一个 Agent，深度就到 2。超过 5 层的调用会被直接拒绝，不会执行。

五、持久化记忆让 Agent 不再金鱼脑

默认情况下，每次运行 Agent 都是一个全新的上下文。Agent 不知道你上次审查了什么代码，不知道之前的错误模式出现过几次。

启用记忆很简单，在 TOML 里加三行：

[memory]

enabled = true

last_n = 10

max_entries = 100

记忆存在 $XDG_DATA_HOME/axe/ 下，是纯 Markdown 文件。每条记忆记录包含时间戳、用户输入、Agent 输出摘要、Token 使用量。

last_n = 10 表示每次运行加载最近 10 条记忆，注入到 system prompt 之后。Agent 就能看到之前发生的事——比如上次代码审查里高频出现的错误模式，这次会特别留意。

max_entries = 100 是警告阈值。超过 100 条记忆时每次运行都会打印警告，提醒你该做垃圾回收了。

记忆垃圾回收：

axe gc my-agent # 清理单个 Agent

axe gc --all # 清理所有启用了记忆的 Agent

GC 不是简单删旧留新。它用 LLM 辅助做模式分析，会识别哪些记忆是重复的、哪些是关键决策点、哪些已经失去时效性。保留高价值信息，删除冗余内容。这个设计很巧妙——不是简单的 FIFO 或 LRU，而是语义级别的去重和保留。

六、Token 预算：真正在意的成本控制

作为 AI 创业者，每一分 API 费用都要算清楚。Axe 的 Token 预算机制让你精确控制单次运行的成本上限。

在 TOML 里配置：

[budget]

max_tokens = 50000

也可以在命令行动态覆盖：

axe run my-agent --max-tokens 10000

命令行参数优先级高于 TOML 配置。当 max-tokens 设为大于 0 的值时生效，设为 0 表示不限制。

超预算时的行为很克制：

  • 当前这一轮的响应正常返回，不会截断
  • 后续的工具调用请求全部拒绝
  • 进程退出码为 4，方便上游脚本判断
  • 不会追加新的记忆记录

在 --verbose 模式下可以实时看到用量：

axe run my-agent --max-tokens 10000 --verbose

输出：

Turn 1: 1247 input + 856 output = 2103 / 10000

Turn 2: 1892 input + 1024 output = 5019 / 10000

Turn 3: 2456 input + 1532 output = 9007 / 10000

Turn 4: budget exceeded - response returned, no further tool calls

并行子 Agent 的 Token 计入规则：如果设置了 parallel = true 的多个子 Agent，每个子 Agent 消耗的 Token 都计入父 Agent 的总预算。比如父 Agent 自己用了 5000 Token，三个子 Agent 各用了 5000 Token，总消耗就是 20000。建议先用 --dry-run 摸底再设预算。

--dry-run 标志也很实用：它会解析所有配置、加载 Skill、拼接上下文，但不实际调用 LLM。你可以用它检查 Agent 的配置是否完整、上下文是否正确组装。

七、输出安全与 Provider 灵活切换

7.1 输出白名单

url_fetch 和 web_search 是 Axe 提供的两个外部访问工具，默认可以访问任意公共 hostname。如果想让 Agent 只能访问特定域名，用白名单：

allowed_hosts = ["api.example.com", "docs.example.com"]

白名单规则很严格：

  • 空列表或不设置：允许所有公共 hostname
  • 非空列表：只精确匹配，大小写不敏感，不支持通配符子域名
  • 私有 IP 地址永远被阻止：loopback、link-local、RFC 1918、CGNAT、IPv6 私有地址一律拦截
  • 每次重定向目标都会重新校验

这个设计有效防御了 SSRF 攻击。Agent 无法探测内网服务，无法访问 localhost，无法绕过白名单通过重定向跳转。

▲

7.2 Provider 切换：一行配置的事

Axe 的多 Provider 支持让它完全不锁定任何一家厂商。想从 Anthropic 切到 OpenAI：

# 之前

model = "anthropic/claude-sonnet-4-20250514"

# 之后

model = "openai/gpt-5.5"

想用本地 Ollama 模型：

model = "ollama/qwen3:14b"

OpenAI 兼容的第三方 API 也能用，通过环境变量覆盖 Base URL：

export AXE_OPENAI_BASE_URL="YOUR_OPENAI_COMPATIBLE_ENDPOINT"

Provider 切换不影响 Agent 的定义。同一个 code-reviewer Agent，换模型就是改一行 model 字段。这在做成本对比时特别方便——同样的 Skill、同样的输入，跑一遍 Anthropic 再跑一遍 OpenAI，对比输出质量和 Token 消耗。

八、实战组合：一人公司的内容质量流水线

让我们把前面所有的知识点串起来。假设你运营一个技术博客，每天产出 2-3 篇文章，需要自动化的质量检查：

第一步：语法检查 Agent

name = "grammar-checker"

model = "anthropic/claude-sonnet-4-20250514"

system_prompt = "检查中文文本的语法错误、错别字、标点使用问题。只列出具体错误行和修改建议，不要改写全文。"

skill = "skills/grammar/SKILL.md"

第二步：事实核查 Agent

name = "fact-checker"

model = "anthropic/claude-sonnet-4-20250514"

system_prompt = "核查文章中的技术声明是否准确。对每条可验证的声明标注来源 URL。无法验证的声明标注为待人工确认。"

tools = ["web_search"]

allowed_hosts = ["en.wikipedia.org", "github.com", "docs.rs"]

[budget]

max_tokens = 30000

第三步：调度 Agent

name = "article-qa"

model = "anthropic/claude-sonnet-4-20250514"

system_prompt = "你是文章质量审核调度员。将文章分发给子 Agent 审查，并汇总为最终报告。按问题严重程度排序。"

sub_agents = ["grammar-checker", "fact-checker"]

[sub_agents_config]

max_depth = 2

parallel = true

timeout = 120

运行：

cat article.md | axe run article-qa --verbose

输出示例：

## 文章质量审核报告

### 语法检查（grammar-checker）

- 第 3 段：逗号缺失，建议在然而后加逗号

- 第 7 段：的得地混用，应修改为做得很好

### 事实核查（fact-checker）

- Axe 最新版本 1.10.0 已确认 来源 github.com/jrswab/axe

- Go 最低版本要求 1.25+ 已确认 来源 github.com/jrswab/axe 的 go.mod

- 第 5 段引用的 LangChain 价格信息已过时，当前版本定价与文中描述不一致

### 综合评分：良好，建议修改以上 4 处后发布

从写完文章到拿到审核报告，全过程不到 60 秒。而且语法检查和事实核查是并行的，不是串行等待。

九、高阶技巧与排障

9.1 重试策略

网络抖动、API 限流——生产环境中不可避免。Axe 提供了可配置的重试：

[retry]

max_retries = 3

backoff = "exponential"

initial_delay_ms = 500

max_delay_ms = 30000

三种退避策略：exponential 带随机抖动，适合应对限流；linear 均匀间隔，适合网络抖动；fixed 固定延迟，适合已知恢复时间的场景。

只有瞬时错误会重试：429 限流、5xx 服务端错误、超时。认证错误 401/403 和请求错误 400 永不重试，直接报错退出。

9.2 JSON 输出模式

--json 标志让输出结构化：

git diff | axe run code-reviewer --json

输出变成一个 JSON 对象，包含 model、duration_ms、input_tokens、output_tokens、retry_attempts 和 content 字段。方便你用 jq 过滤、写脚本解析、接入监控系统。举个例子，想只提取 Token 消耗量来判断成本：axe run reviewer --json | jq .input_tokens,.output_tokens 就能一行拿到数据。

9.3 本地 Agent 目录

项目级的 Agent 定义可以直接放在项目目录里：

my-project/

└── axe/

    └── agents/

        └── my-agent.toml # 自动发现

如果当前工作目录下存在 axe/agents/，Axe 会优先从这里加载，而不是全局配置目录。这意味着你可以给每个项目配专属的 Agent，其他人 clone 代码后立即可用，不需要额外配置。

十、为什么 Axe 值得放进工具箱

做个总结。Axe 不是要取代 Claude Code 或 Hermes Agent。它们解决的是不同层面的问题。Claude Code 是交互式编程环境，Hermes 是完整的 Agent 运行时。Axe 是命令行工具——给那些已经被 git、cron、CI 包围的开发者一个无需额外学习成本的 AI Agent 入口。

它的极简依赖令人印象深刻——只有 4 个外部 Go 包：cobra 做 CLI、toml 做配置解析、mcp-go-sdk 接 MCP、x/net 处理网络。所有 LLM API 调用全部用 Go 标准库实现。对比一下 LangChain 的数百个依赖和 CrewAI 的 Python 重量级生态，Axe 的轻量级设计让它在 CI 环境、容器化部署和边缘设备上都表现出色。编译出来就是单个二进制，拷贝即运行。

Unix 血脉——管道、组合、小而美——这些存在了半个世纪的设计原则，在 AI Agent 时代依然熠熠生辉。用 git diff 传输入，用退出码判断状态，用 cron 调度执行，用 jq 解析 JSON 输出。你不需要学任何新概念，用你已经会的一切就能驱动 AI。

风险提示：Axe 当前版本 1.10.0，项目仍在活跃开发中。生产环境使用前请充分测试 Token 预算、子 Agent 深度限制和重试策略的实际行为。另外 Go 1.25+ 的要求意味着如果你用的是 Ubuntu 20.04 等旧系统的默认 Go 版本，需要手动升级。

行动建议

按难度递进：

  1. 装好 Axe，跑通 code-reviewer 示例 约 10 分钟
  2. 把你的日常重复性审查改造成 Agent 约 30 分钟
  3. 接入 git hooks 或 cron 实现自动触发 约 20 分钟
  4. 组合 2-3 个 Agent 搭建完整流水线 约 1 小时
  5. 接入 Docker 安全运行环境 约 15 分钟

五个步骤走完，你就有了一套可复用的、版本管理的、按需触发的 AI Agent 工具链。不需要付费订阅任何平台。不需要迁移到任何新框架。

参考来源：

  • Axe GitHub 仓库：github.com/jrswab/axe
  • Axe 官方文档：axe.jrswab.com
  • HN 讨论帖：news.ycombinator.com/item?id=47350516

#AI创业 #Agent工坊 #Axe #AI工具 #一人公司

本文由AI辅助创作，经人工审核编辑发布

更多一人公司案例与工具，微信搜索「AI创业内参」关注我们