Buttons：专为 AI Agent 设计的 CLI 工作流引擎

背景：Agent 需要什么样的自动化工具？\n\n随着 AI Agent 的快速发展，如何让 Agent 执行复杂的多步骤任务成为了一个关键问题。现有的工作流工具如 n8n、Airflow 等虽然功能强大，但往往过于重量级，且并非为 Agent 原生设计。\n\nButtons 项目提出了一个简洁的理念：每个"按钮"是一个自包含、可复用的动作。创建一次，永久执行。它将代码、API 调用和 Agent 指令封装成统一的接口，让 Agent 能够像按按钮一样触发复杂的工作流。\n\n## 项目概览：Agent 界的 n8n\n\nButtons 由 Autono 团队开发，定位为"n8n for agents"。它是一个 CLI 工作流引擎，核心特性包括：\n\n- 单一静态二进制文件 - 约 5MB，无运行时依赖\n- 多平台支持 - macOS、Linux（amd64/arm64），Windows 支持正在开发\n- 多种安装方式 - npm、curl、Docker、Go、Homebrew\n- 三种按钮类型 - 代码按钮、API 按钮、Agent 指令按钮\n- 类型化参数 - 支持 string、int、bool 三种类型\n- 结构化输出 - JSON 格式，便于 Agent 解析\n\n## 安装方式\n\n### npm 安装（推荐）\n\nbash\nnpm install -g @autono/buttons\n# 或\npnpm add -g @autono/buttons\nbun add -g @autono/buttons\n\n\n### curl 快速安装\n\nbash\ncurl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh | sh\n\n# 指定版本\ncurl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh | BUTTONS_VERSION=v0.1.0 sh\n\n# 安装到用户目录（无需 sudo）\ncurl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh | BUTTONS_INSTALL_DIR=$HOME/.local/bin sh\n\n\n### Docker 使用\n\nbash\ndocker pull ghcr.io/autonoco/buttons:latest\ndocker run --rm ghcr.io/autonoco/buttons:latest version\n\n\n### Homebrew（即将支持）\n\nbash\nbrew install autono/tap/buttons\n\n\n## 核心概念：三种按钮类型\n\nButtons 支持三种类型的按钮，每种都可通过 --prompt 参数附加 Agent 指令：\n\n### 1. 代码按钮（Code Button）\n\n代码按钮执行脚本文件，支持 Shell、Python、Node.js 三种运行时。\n\n创建示例：\n\nbash\n# Shell 按钮（默认）\nbuttons create deploy --arg env:string:required\n\n# Python 按钮\nbuttons create transform --runtime python --arg input:string:required\n\n# Node.js 按钮\nbuttons create parse --runtime node\n\n# 内联代码（无需编辑文件）\nbuttons create greet --code 'echo "Hello, $BUTTONS_ARG_NAME!"' --arg name:string:required\n\n# 导入现有脚本\nbuttons create etl --file ./scripts/etl.sh --arg source:string:required\n\n\n代码按钮的参数通过环境变量传递，格式为 BUTTONS_ARG_<NAME>。\n\n### 2. API 按钮（API Button）\n\nAPI 按钮调用 HTTP 端点，支持 URL 模板和请求体模板。\n\n创建示例：\n\n```bash\n# GET 请求\nbuttons create weather \

--url 'https://wttr.in/{{city}}?format=j1'
--arg city:string:required\n\n# POST 请求\nbuttons create notify
--url https://hooks.slack.com/services/xxx
--method POST
--header "Content-Type: application/json"
--body '{"text": "{{message}}"}'
--arg message:string:required\n\n# GraphQL 查询\nbuttons create repos
--url https://api.github.com/graphql
--method POST
--header "Authorization: Bearer {{token}}"
--header "Content-Type: application/json"
--body '{"query": "{ repository(owner: \"{{owner}}\", name: \"{{repo}}\") { stargazerCount } }"}'
--arg token:string:required --arg owner:string:required --arg repo:string:required\n\n\nURL 模板支持 `{{arg}}` 占位符，会根据上下文自动进行 URL 编码。\n\n### 3. Agent 指令按钮（Agent Button）\n\n纯指令按钮，仅包含给 Agent 的提示词，用于指导 Agent 执行特定任务。\n\nbash\nbuttons create deploy-checklist
--agent "Before deploying, verify: 1) All tests pass 2) Staging is green 3) Team notified"\n\n\n## 组合模式：代码/API + Agent 提示\n\n最强大的是组合模式，将执行动作与 Agent 解读结合：\n\nbash\n# 代码 + 提示\nbuttons create check-logs
--code 'northflank logs --service api --env production --tail 100'
--prompt "Summarize any errors or warnings from these logs"\n\n# API + 提示\nbuttons create analyze-weather
--url 'https://wttr.in/{{city}}?format=j1'
--arg city:string:required
--prompt "Extract temperature and conditions as a one-line summary"\n\n\n执行后返回的结果包含原始输出和提示词：\n\njson\n{\n "ok": true,\n "data": {\n "status": "ok",\n "stdout": "ERROR 2026-03-31 connection timeout to db-primary...",\n "prompt": "Summarize any errors or warnings from these logs",\n "button": "check-logs"\n }\n}\n\n\n## 按钮管理命令\n\n### 查看按钮\n\nbash\n# 列表视图\nbuttons\nbuttons list --json\n\n# 详情视图\nbuttons weather\n\n\n### 执行按钮\n\nbash\n# 基本执行\nbuttons press weather --arg city=Miami\n\n# JSON 输出\nbuttons press weather --arg city=Miami --json\n\n# 模拟执行（不实际运行）\nbuttons press weather --arg city=Miami --dry-run\n\n# 设置超时\nbuttons press slow-task --timeout 120\n\n\n### 历史记录\n\nbash\n# 所有按钮历史\nbuttons history\n\n# 特定按钮历史\nbuttons history weather\n\n# 最近 5 条\nbuttons history --last 5\n\n\n### 删除按钮\n\nbash\nbuttons delete deploy\nbuttons delete deploy -F # 跳过确认\nbuttons rm deploy # rm 是 delete 的别名\n\n\n## 按钮存储结构\n\n每个按钮是一个自包含的文件夹，默认存储在 `~/.buttons/buttons/<name>/`：\n\n\n~/.buttons/buttons/weather/\n├── button.json # 规格定义（参数、运行时、超时）\n├── main.sh # 代码文件（根据运行时可能是 .sh/.py/.js）\n├── AGENT.md # Agent 指令/上下文\n└── pressed/ # 执行历史\n ├── 2026-03-31T09-53-45.json\n └── ...\n```\n\n可通过 BUTTONS_HOME 环境变量覆盖存储位置。\n\n## 安全设计\n\nButtons 在安全性方面做了细致考虑：\n\n1. **执行隔离** - 每个执行使用 context.WithTimeout，默认 60 秒超时\n2. **进程管理** - 发送 SIGTERM，5 秒宽限期后发送 SIGKILL\n3. **参数安全** - 参数作为环境变量传递，不进行 shell 插值\n4. **文件权限** - 规格文件 0600，代码文件 0700\n5. **URL 编码** - {{arg}} 值根据上下文自动编码（路径、查询、JSON）\n6. **响应限制** - HTTP 响应体默认限制 10MB，可配置\n7. **网络隔离** - 默认阻止私有网络地址（localhost、10/8 等），需显式启用 --allow-private-networks\n\n## 与 n8n 的对比\n\n| 特性 | Buttons | n8n |\n|------|---------|-----|\n| 架构 | 单机 CLI | 服务端应用 |\n| 资源占用 | ~5MB 二进制 | 需要数据库、Redis |\n| 部署复杂度 | 极低 | 中等 |\n| Agent 原生 | 是 | 需适配 |\n| 可视化编辑 | 否 | 是 |\n| 适用场景 | Agent 自动化 | 企业工作流 |\n\nButtons 更适合 Agent 场景：轻量、快速、易于集成到 Agent 的工具链中。\n\n## 实际应用场景\n\n### 1. Agent 工具链集成\nAgent 可以将 Buttons 作为工具使用，通过结构化输出理解执行结果。\n\n### 2. 开发环境自动化\n创建常用的开发任务按钮：部署、日志查看、测试运行等。\n\n### 3. CI/CD 流水线\n在 CI 环境中使用 Buttons 执行特定的构建、测试、发布步骤。\n\n### 4. 运维脚本管理\n将分散的运维脚本统一封装为按钮，便于管理和审计。\n\n### 5. API 编排\n将多个 API 调用组合成可复用的按钮，简化复杂集成场景。\n\n## 项目状态与展望\n\nButtons 目前处于早期开发阶段（v0.1.0），但核心功能已经可用。根据项目路线图，未来可能包括：\n\n- Windows 原生支持\n- 更多运行时（如 Deno、Bun）\n- 按钮共享机制（类似 npm registry）\n- 更丰富的模板库\n- Web UI 管理界面\n\n## 总结\n\nButtons 是一个面向未来的工具，它敏锐地捕捉到了 AI Agent 时代的自动化需求。通过将工作流封装为"按钮"，它降低了 Agent 执行复杂任务的门槛，同时保持了足够的灵活性和安全性。\n\n对于正在构建 Agent 系统的开发者来说，Buttons 提供了一个轻量但强大的工作流编排选项。它的设计哲学——简单、可复用、Agent 原生——使其在众多自动化工具中脱颖而出。\n\n随着 AI Agent 生态的成熟，类似 Buttons 这样专为 Agent 设计的工具将会越来越多，它们将共同塑造下一代自动化基础设施。