[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-jrswab--axe":3,"tool-jrswab--axe":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",156033,2,"2026-04-14T23:32:00",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":78,"owner_twitter":72,"owner_website":76,"owner_url":79,"languages":80,"stars":93,"forks":94,"last_commit_at":95,"license":96,"difficulty_score":32,"env_os":97,"env_gpu":98,"env_ram":98,"env_deps":99,"category_tags":108,"github_topics":109,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":117,"updated_at":118,"faqs":119,"releases":160},7608,"jrswab\u002Faxe","axe","A lightweight cli for running single-purpose AI agents. Define focused agents in TOML, trigger them from anywhere; pipes, git hooks, cron, or the terminal.","Axe 是一款轻量级命令行工具，专为运行单一功能的 AI 智能体而设计。它摒弃了传统 AI 工具倾向于构建庞大、长会话聊天机器人的模式，转而倡导“小而美”的 Unix 哲学：让每个智能体只专注做好一件事。用户只需通过简洁的 TOML 文件定义智能体的技能与提示词，即可在终端、Git 钩子、定时任务或通过管道灵活调用它们，实现像组合标准程序一样编排 AI 工作流。\n\nAxe 特别适合开发者、DevOps 工程师及希望将 AI 深度集成到现有自动化流程中的技术用户。无论是代码审查、日志分析还是数据处理，都能通过 `git diff | axe run reviewer` 这样的命令无缝衔接。其独特亮点包括支持多模型提供商（如 OpenAI、Ollama 等）、智能体间的层级委托机制、带垃圾回收的持久化记忆系统，以及严格的安全沙箱和令牌预算控制。无需守护进程或图形界面，Axe 仅凭一个二进制文件和配置文件，就能让你以声明式的方式高效管理本地或云端的 LLM 能力，真正让 AI 成为可组合、可版本控制的开发基础设施。","# Axe\n\n![axe banner](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjrswab_axe_readme_feb2eaee1535.png)\n\nA CLI tool for managing and running LLM-powered agents.\n\n## Why Axe?\n\nMost AI tooling assumes you want a chatbot. A long-running session with a massive context window doing everything at once. But that's not how good software works. Good software is small, focused, and composable.\n\nAxe treats LLM agents the same way Unix treats programs. Each agent does one thing well. You define it in a TOML file, give it a focused skill, and run it from the command line. Pipe data in, get results out. Chain agents together. Trigger them from cron, git hooks, or CI. Whatever you already use. No daemon, no GUI, no framework to buy into. Just a binary and your configs.\n\n## Overview\n\nAxe orchestrates LLM-powered agents defined via TOML configuration files. Each agent has its own system prompt, model selection, skill files, context files, working directory, persistent memory, and the ability to delegate to sub-agents.\n\nAxe is the executor, not the scheduler. It is designed to be composed with standard Unix tools — cron, git hooks, pipes, file watchers — rather than reinventing scheduling or workflow orchestration.\n\n## Features\n\n- **Multi-provider support** — Anthropic, OpenAI, Ollama (local models), OpenCode, and AWS Bedrock\n- **TOML-based agent configuration** — declarative, version-controllable agent definitions\n- **Sub-agent delegation** — agents can call other agents via LLM tool use, with depth limiting and parallel execution\n- **Persistent memory** — timestamped markdown logs that carry context across runs\n- **Memory garbage collection** — LLM-assisted pattern analysis and trimming\n- **Skill system** — reusable instruction sets that can be shared across agents\n- **Stdin piping** — pipe any output directly into an agent (`git diff | axe run reviewer`)\n- **Local agent directories** — auto-discovers agents from `\u003Ccwd>\u002Faxe\u002Fagents\u002F` before the global config, or use `--agents-dir` to point anywhere\n- **Dry-run mode** — inspect resolved context without calling the LLM\n- **JSON output** — structured output with metadata for scripting\n- **Built-in tools** — file operations (read, write, edit, list) sandboxed to working directory; shell command execution; URL fetching; web search\n- **Output allowlist** — restrict `url_fetch` and `web_search` to specific hostnames; private\u002Freserved IPs are always blocked (SSRF protection)\n- **Token budgets** — cap cumulative token usage per agent run via `[budget]` config or `--max-tokens` flag\n- **MCP tool support** — connect to external MCP servers for additional tools via SSE or streamable-HTTP transport\n- **Configurable retry** — exponential, linear, or fixed backoff for transient provider errors (429, 5xx, timeouts)\n- **Minimal dependencies** — four direct dependencies (cobra, toml, mcp-go-sdk, x\u002Fnet); all LLM calls use the standard library\n\n## Installation\n\nRequires Go 1.25+.\n\n**Pre-built binaries** (no Go required) are available for Linux, macOS, and Windows on the [GitHub Releases page](https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Freleases\u002Flatest).\n\nInstall via Go:\n\n```bash\ngo install github.com\u002Fjrswab\u002Faxe@latest\n```\n\n> If this fails with `invalid go version`, your Go toolchain is older than 1.25. Upgrade from [go.dev\u002Fdl](https:\u002F\u002Fgo.dev\u002Fdl\u002F) or download a pre-built binary instead.\n\nOr build from source:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe.git\ncd axe\ngo build .\n```\n\n## Quick Start\n\nInitialize the configuration directory:\n\n```bash\naxe config init\n```\n\nThis creates the directory structure at `$XDG_CONFIG_HOME\u002Faxe\u002F` with a sample skill and a default `config.toml` for provider credentials.\n\nScaffold a new agent:\n\n```bash\naxe agents init my-agent\n```\n\nEdit its configuration:\n\n```bash\naxe agents edit my-agent\n```\n\nRun the agent:\n\n```bash\naxe run my-agent\n```\n\nPipe input from other tools:\n\n```bash\ngit diff --cached | axe run pr-reviewer\ncat error.log | axe run log-analyzer\n```\n\n## Examples\n\nThe [`examples\u002F`](examples\u002F) directory contains ready-to-run agents you can copy into your config and use immediately. Includes a code reviewer, commit message generator, and text summarizer — each with a focused SKILL.md.\n\n```bash\n# Copy an example agent into your config\ncp examples\u002Fcode-reviewer\u002Fcode-reviewer.toml \"$(axe config path)\u002Fagents\u002F\"\ncp -r examples\u002Fcode-reviewer\u002Fskills\u002F \"$(axe config path)\u002Fskills\u002F\"\n\n# Set your API key and run\nexport ANTHROPIC_API_KEY=\"your-key-here\"\ngit diff | axe run code-reviewer\n```\n\nSee [`examples\u002FREADME.md`](examples\u002FREADME.md) for full setup instructions.\n\n## Docker\n\nAxe provides a Docker image for running agents in an isolated, hardened container.\n\n### Build the Image\n\n```bash\ndocker build -t axe .\n```\n\nMulti-architecture builds (linux\u002Famd64, linux\u002Farm64) are supported via buildx:\n\n```bash\ndocker buildx build --platform linux\u002Famd64,linux\u002Farm64 -t axe:latest .\n```\n\n### Run an Agent\n\nMount your config directory and pass API keys as environment variables:\n\n```bash\ndocker run --rm \\\n  -v .\u002Fmy-config:\u002Fhome\u002Faxe\u002F.config\u002Faxe \\\n  -e ANTHROPIC_API_KEY \\\n  axe run my-agent\n```\n\nPipe stdin with the `-i` flag:\n\n```bash\ngit diff | docker run --rm -i \\\n  -v .\u002Fmy-config:\u002Fhome\u002Faxe\u002F.config\u002Faxe \\\n  -e ANTHROPIC_API_KEY \\\n  axe run pr-reviewer\n```\n\nWithout a config volume mounted, axe exits with code 2 (config error) because no agent TOML files exist.\n\n### Running a Single Agent\n\nThe examples above mount the entire config directory. If you only need to run one agent with one skill, mount just those files to their expected XDG paths inside the container. No `config.toml` is needed when API keys are passed via environment variables.\n\n```bash\ndocker run --rm -i \\\n  -e ANTHROPIC_API_KEY \\\n  -v .\u002Fagents\u002Freviewer.toml:\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002Fagents\u002Freviewer.toml:ro \\\n  -v .\u002Fskills\u002Fcode-review\u002F:\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002Fskills\u002Fcode-review\u002F:ro \\\n  axe run reviewer\n```\n\nThe agent's `skill` field resolves automatically against the XDG config path inside the container, so no `--skill` flag is needed.\n\nTo use a **different skill** than the one declared in the agent's TOML, use the `--skill` flag to override it. In this case you only mount the replacement skill — the original skill declared in the TOML is ignored entirely:\n\n```bash\ndocker run --rm -i \\\n  -e ANTHROPIC_API_KEY \\\n  -v .\u002Fagents\u002Freviewer.toml:\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002Fagents\u002Freviewer.toml:ro \\\n  -v .\u002Falt-review.md:\u002Fhome\u002Faxe\u002Falt-review.md:ro \\\n  axe run reviewer --skill \u002Fhome\u002Faxe\u002Falt-review.md\n```\n\nIf the agent declares `sub_agents`, all referenced agent TOMLs and their skills must also be mounted.\n\n### Persistent Data\n\nAgent memory persists across runs when you mount a data volume:\n\n```bash\ndocker run --rm \\\n  -v .\u002Fmy-config:\u002Fhome\u002Faxe\u002F.config\u002Faxe \\\n  -v axe-data:\u002Fhome\u002Faxe\u002F.local\u002Fshare\u002Faxe \\\n  -e ANTHROPIC_API_KEY \\\n  axe run my-agent\n```\n\n### Docker Compose\n\nA `docker-compose.yml` is included for running axe alongside a local Ollama instance.\n\n**Cloud provider only (no Ollama):**\n\n```bash\ndocker compose run --rm axe run my-agent\n```\n\n**With Ollama sidecar:**\n\n```bash\ndocker compose --profile ollama up -d ollama\ndocker compose --profile cli run --rm axe run my-agent\n```\n\n**Pull an Ollama model:**\n\n```bash\ndocker compose --profile ollama exec ollama ollama pull llama3\n```\n\n> **Note:** The compose `axe` service declares `depends_on: ollama`. Docker Compose will attempt to start the Ollama service whenever axe is started via compose, even for cloud-only runs. For cloud-only usage without Ollama, use `docker run` directly instead of `docker compose run`.\n\n### Ollama on the Host\n\nIf Ollama runs directly on the host (not via compose), point to it with:\n\n- **Linux:** `--add-host=host.docker.internal:host-gateway -e AXE_OLLAMA_BASE_URL=http:\u002F\u002Fhost.docker.internal:11434`\n- **macOS \u002F Windows (Docker Desktop):** `-e AXE_OLLAMA_BASE_URL=http:\u002F\u002Fhost.docker.internal:11434`\n\n### Security\n\nThe container runs with the following hardening by default (via compose):\n\n- **Non-root user** — UID 10001\n- **Read-only root filesystem** — writable locations are the config mount, data mount, and `\u002Ftmp\u002Faxe` tmpfs\n- **All capabilities dropped** — `cap_drop: ALL`\n- **No privilege escalation** — `no-new-privileges:true`\n\nThese settings do not restrict outbound network access. To isolate an agent that only talks to a local Ollama instance, add `--network=none` and connect it to the shared Docker network manually.\n\n### Volume Mounts\n\n| Container Path | Purpose | Default Access |\n|---|---|---|\n| `\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002F` | Agent TOML files, skills, `config.toml` | Read-write |\n| `\u002Fhome\u002Faxe\u002F.local\u002Fshare\u002Faxe\u002F` | Persistent memory files | Read-write |\n\nConfig is read-write because `axe config init` and `axe agents init` write into it. Mount as `:ro` if you only run agents.\n\n### Environment Variables\n\n| Variable | Required | Purpose |\n|---|---|---|\n| `ANTHROPIC_API_KEY` | If using Anthropic | API authentication |\n| `OPENAI_API_KEY` | If using OpenAI | API authentication |\n| `AXE_OLLAMA_BASE_URL` | If using Ollama | Ollama endpoint (default in compose: `http:\u002F\u002Follama:11434`) |\n| `AXE_ANTHROPIC_BASE_URL` | No | Override Anthropic API endpoint |\n| `AXE_OPENAI_BASE_URL` | No | Override OpenAI API endpoint |\n| `AXE_OPENCODE_BASE_URL` | No | Override OpenCode API endpoint |\n| `TAVILY_API_KEY` | If using web_search | Tavily web search API key |\n| `AXE_WEB_SEARCH_BASE_URL` | No | Override web search endpoint |\n\n## CLI Reference\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `axe run \u003Cagent>` | Run an agent |\n| `axe agents list` | List all configured agents |\n| `axe agents show \u003Cagent>` | Display an agent's full configuration |\n| `axe agents init \u003Cagent>` | Scaffold a new agent TOML file |\n| `axe agents edit \u003Cagent>` | Open an agent TOML in `$EDITOR` |\n| `axe config path` | Print the configuration directory path |\n| `axe config init` | Initialize the config directory with defaults |\n| `axe gc \u003Cagent>` | Run memory garbage collection for an agent |\n| `axe gc --all` | Run GC on all memory-enabled agents |\n| `axe version` | Print the current version |\n\n### Run Flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `--model \u003Cprovider\u002Fmodel>` | from TOML | Override the model (e.g. `anthropic\u002Fclaude-sonnet-4-20250514`) |\n| `--skill \u003Cpath>` | from TOML | Override the skill file path |\n| `--workdir \u003Cpath>` | from TOML or cwd | Override the working directory |\n| `--timeout \u003Cseconds>` | 120 | Request timeout |\n| `--max-tokens \u003Cint>` | 0 (unlimited) | Cap cumulative token usage for the run (exit code 4 if exceeded) |\n| `--dry-run` | false | Show resolved context without calling the LLM |\n| `--verbose` \u002F `-v` | false | Print debug info (model, timing, tokens, retries) to stderr |\n| `--json` | false | Wrap output in a JSON envelope with metadata |\n| `-p` \u002F `--prompt \u003Cstring>` | (none) | Inline prompt used as the user message; takes precedence over stdin |\n| `--agents-dir \u003Cpath>` | (auto-discover) | Override agent search directory |\n\n#### User Message Precedence\n\nThe user message sent to the LLM is resolved in this order:\n\n1. **`-p` \u002F `--prompt` flag** — If provided with a non-empty, non-whitespace value, it is used as the user message.\n2. **Piped stdin** — If `-p` is absent or empty\u002Fwhitespace-only, piped stdin is used.\n3. **Built-in default** — If neither `-p` nor stdin provides content, the default message `\"Execute the task described in your instructions.\"` is used.\n\nWhen `-p` is provided alongside piped stdin, the piped stdin is silently ignored (no warning is emitted). An empty or whitespace-only `-p` value is treated as absent and falls through to stdin, then the default.\n\n**Example:**\n```bash\naxe run my-agent -p \"Summarize the README\"\n```\n\n### Exit Codes\n\n| Code | Meaning |\n|---|---|\n| 0 | Success |\n| 1 | Runtime error |\n| 2 | Configuration error |\n| 3 | Provider\u002Fnetwork error |\n| 4 | Token budget exceeded |\n\n## Agent Configuration\n\nAgents are defined as TOML files in `$XDG_CONFIG_HOME\u002Faxe\u002Fagents\u002F`.\n\n```toml\nname = \"pr-reviewer\"\ndescription = \"Reviews pull requests for issues and improvements\"\nmodel = \"anthropic\u002Fclaude-sonnet-4-20250514\"\nsystem_prompt = \"You are a senior code reviewer. Be concise and actionable.\"\nskill = \"skills\u002Fcode-review\u002FSKILL.md\"\nfiles = [\"src\u002F**\u002F*.go\", \"CONTRIBUTING.md\"]\nworkdir = \"\u002Fhome\u002Fuser\u002Fprojects\u002Fmyapp\"\ntools = [\"read_file\", \"list_directory\", \"run_command\"]\nsub_agents = [\"test-runner\", \"lint-checker\"]\nallowed_hosts = [\"api.example.com\", \"docs.example.com\"]\n\n[sub_agents_config]\nmax_depth = 3       # maximum nesting depth (hard max: 5)\nparallel = true     # run sub-agents concurrently\ntimeout = 120       # per sub-agent timeout in seconds\n\n[memory]\nenabled = true\nlast_n = 10         # load last N entries into context\nmax_entries = 100   # warn when exceeded\n\n[[mcp_servers]]\nname = \"my-tools\"\nurl = \"https:\u002F\u002Fmy-mcp-server.example.com\u002Fsse\"\ntransport = \"sse\"\nheaders = { Authorization = \"Bearer ${MY_TOKEN}\" }\n\n[params]\ntemperature = 0.3\nmax_tokens = 4096\n\n[budget]\nmax_tokens = 50000    # 0 = unlimited (default)\n\n[retry]\nmax_retries = 3           # retry up to 3 times on transient errors\nbackoff = \"exponential\"   # \"exponential\", \"linear\", or \"fixed\"\ninitial_delay_ms = 500    # base delay before first retry\nmax_delay_ms = 30000      # maximum delay cap\n\n[[mcp_servers]]\nname = \"filesystem\"\ntransport = \"stdio\"\ncommand = \"\u002Fusr\u002Flocal\u002Fbin\u002Fmcp-server-filesystem\"\nargs = [\"--root\", \"\u002Fhome\u002Fuser\u002Fprojects\"]\n```\n\nAll fields except `name` and `model` are optional.\n\n### Retry\n\nAgents can retry on transient LLM provider errors — rate limits (429), server\nerrors (5xx), and timeouts. Retry is opt-in and disabled by default.\n\n| Field | Default | Description |\n|---|---|---|\n| `max_retries` | 0 | Number of retry attempts after the initial request. 0 disables retry. |\n| `backoff` | `\"exponential\"` | Strategy: `\"exponential\"` (with jitter), `\"linear\"`, or `\"fixed\"` |\n| `initial_delay_ms` | 500 | Base delay in milliseconds before the first retry |\n| `max_delay_ms` | 30000 | Maximum delay cap in milliseconds |\n\nOnly transient errors are retried. Authentication errors (401\u002F403) and bad\nrequests (400) are never retried. When `--verbose` is enabled, each retry\nattempt is logged to stderr. The `--json` envelope includes a `retry_attempts`\nfield for observability.\n\n### Output Allowlist\n\nAgents that use `url_fetch` or `web_search` can be restricted to specific hostnames with the `allowed_hosts` field:\n\n```toml\nallowed_hosts = [\"api.example.com\", \"docs.example.com\"]\n```\n\n| Behavior | Detail |\n|---|---|\n| Empty or absent | All public hostnames allowed |\n| Non-empty list | Only exact hostname matches permitted (case-insensitive, no wildcard subdomains) |\n| Private IPs | Always blocked regardless of allowlist — loopback, link-local, RFC 1918, CGNAT, IPv6 private |\n| Redirects | Each redirect destination is re-validated against the allowlist and private IP check |\n| Sub-agents | Inherit the parent's `allowed_hosts` unless the sub-agent TOML explicitly sets its own |\n\n### Token Budget\n\nCap cumulative token usage (input + output, across all turns and sub-agent calls) for a single run:\n\n```toml\n[budget]\nmax_tokens = 50000   # 0 = unlimited (default)\n```\n\nOr override via flag:\n\n```bash\naxe run my-agent --max-tokens 10000\n```\n\nThe flag takes precedence over TOML when set to a value greater than zero.\n\nWhen the budget is exceeded, the current response is returned but no further tool calls execute. The process exits with **code 4**. Memory is not appended on a budget-exceeded run.\n\nWith `--verbose`, each turn logs cumulative usage to stderr. With `--json`, the output envelope includes `budget_max_tokens`, `budget_used_tokens`, and `budget_exceeded` fields (omitted when unlimited).\n\n## Tools\n\nAgents can use built-in tools to interact with the filesystem and run commands. When tools are enabled, the agent enters a conversation loop — the LLM can make tool calls, receive results, and continue reasoning for up to 50 turns.\n\n### Built-in Tools\n\n| Tool | Description |\n|---|---|\n| `list_directory` | List contents of a directory relative to the working directory |\n| `read_file` | Read file contents with line-numbered output and optional pagination (offset\u002Flimit) |\n| `write_file` | Create or overwrite a file, creating parent directories as needed |\n| `edit_file` | Find and replace exact text in a file, with optional replace-all mode |\n| `run_command` | Execute a shell command via `sh -c` and return combined output |\n| `url_fetch` | Fetch URL content with HTML stripping and truncation |\n| `web_search` | Search the web and return results |\n| `call_agent` | Delegate a task to a sub-agent (controlled via `sub_agents`, not `tools`) |\n\nEnable tools by adding them to the agent's `tools` field:\n\n```toml\ntools = [\"read_file\", \"list_directory\", \"run_command\"]\n```\n\nThe `call_agent` tool is not listed in `tools` — it is automatically available when `sub_agents` is configured and the depth limit has not been reached.\n\n### Path Security\n\nAll file tools (`list_directory`, `read_file`, `write_file`, `edit_file`) are sandboxed to the agent's working directory. Absolute paths, `..` traversal, and symlink escapes are rejected.\n\n### Parallel Execution\n\nWhen an LLM returns multiple tool calls in a single turn, they run concurrently by default. This applies to both built-in tools and sub-agent calls. Disable with `parallel = false` in `[sub_agents_config]`.\n\n### MCP Tools\n\nAgents can use tools from external [MCP](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\nservers. Declare servers in the agent TOML with `[[mcp_servers]]`:\n\n```toml\n[[mcp_servers]]\nname = \"my-tools\"\nurl = \"https:\u002F\u002Fmy-mcp-server.example.com\u002Fsse\"\ntransport = \"sse\"\nheaders = { Authorization = \"Bearer ${MY_TOKEN}\" }\n```\n\nAt startup, axe connects to each declared server, discovers available tools via\n`tools\u002Flist`, and makes them available to the LLM alongside built-in tools.\n\n| Field | Required | Description |\n|---|---|---|\n| `name` | Yes | Human-readable identifier for the server |\n| `url` | Yes | MCP server endpoint URL |\n| `transport` | Yes | `\"sse\"` or `\"streamable-http\"` |\n| `headers` | No | HTTP headers; values support `${ENV_VAR}` interpolation |\n\nMCP tools are controlled entirely by `[[mcp_servers]]` — they are not listed in\nthe `tools` field. If an MCP tool has the same name as an enabled built-in tool,\nthe built-in takes precedence.\n\n## Skills\n\nSkills are reusable instruction sets that provide an agent with domain-specific knowledge and workflows. They are defined as `SKILL.md` files following the community SKILL.md format.\n\n### Skill Resolution\n\nThe `skill` field in an agent TOML is resolved in order:\n\n1. **Absolute path** — used as-is (e.g. `\u002Fhome\u002Fuser\u002Fskills\u002FSKILL.md`)\n2. **Relative to config dir** — e.g. `skills\u002Fcode-review\u002FSKILL.md` resolves to `$XDG_CONFIG_HOME\u002Faxe\u002Fskills\u002Fcode-review\u002FSKILL.md`\n3. **Bare name** — e.g. `code-review` resolves to `$XDG_CONFIG_HOME\u002Faxe\u002Fskills\u002Fcode-review\u002FSKILL.md`\n\n### Script Paths\n\nSkills often reference helper scripts. Since `run_command` executes in the agent's `workdir` (not the skill directory), **script paths in SKILL.md must be absolute**. Relative paths will fail because the scripts don't exist in the agent's working directory.\n\n```\n# Correct — absolute path\n\u002Fhome\u002Fuser\u002F.config\u002Faxe\u002Fskills\u002Fmy-skill\u002Fscripts\u002Ffetch.sh \u003Cargs>\n\n# Wrong — relative path won't resolve from the agent's workdir\nscripts\u002Ffetch.sh \u003Cargs>\n```\n\n### Directory Structure\n\n```\n$XDG_CONFIG_HOME\u002Faxe\u002F\n├── config.toml\n├── agents\u002F\n│   └── my-agent.toml\n└── skills\u002F\n    └── my-skill\u002F\n        ├── SKILL.md\n        └── scripts\u002F\n            └── fetch.sh\n```\n\n## Local Agent Directories\n\nBy default, agents are loaded from `$XDG_CONFIG_HOME\u002Faxe\u002Fagents\u002F`. Axe also supports project-local agent directories for per-repo agent definitions.\n\n### Auto-Discovery\n\nIf `\u003Ccwd>\u002Faxe\u002Fagents\u002F` exists, axe searches it before the global config directory. A local agent with the same name as a global agent shadows the global one.\n\n```\nmy-project\u002F\n└── axe\u002F\n    └── agents\u002F\n        └── my-agent.toml   ← found automatically\n```\n\n### Explicit Override\n\nUse `--agents-dir` to point to any directory:\n\n```bash\naxe run my-agent --agents-dir .\u002Fcustom\u002Fagents\n```\n\nThis flag is available on all commands: `run`, `agents list`, `agents show`, `agents init`, `agents edit`, and `gc`.\n\n### Resolution Order\n\n1. `--agents-dir` (if provided)\n2. `\u003Ccwd>\u002Faxe\u002Fagents\u002F` (auto-discovered)\n3. `$XDG_CONFIG_HOME\u002Faxe\u002Fagents\u002F` (global fallback)\n\nThe first directory containing a matching `\u003Cname>.toml` wins.\n\n### Smart Scaffolding\n\n`axe agents init \u003Cname>` writes to `\u003Ccwd>\u002Faxe\u002Fagents\u002F` if that directory already exists, otherwise falls back to the global config directory.\n\n## Providers\n\n| Provider | API Key Env Var | Default Base URL |\n|---|---|---|\n| Anthropic | `ANTHROPIC_API_KEY` | `https:\u002F\u002Fapi.anthropic.com` |\n| OpenAI | `OPENAI_API_KEY` | `https:\u002F\u002Fapi.openai.com` |\n| Ollama | (none required) | `http:\u002F\u002Flocalhost:11434` |\n| OpenCode | `OPENCODE_API_KEY` | Configurable |\n| AWS Bedrock | (uses AWS credentials) | Region-based |\n\n**AWS Bedrock Configuration:**\n- Region: Set via `AWS_REGION` environment variable or `[providers.bedrock] region = \"us-east-1\"` in config.toml\n- Credentials: Uses environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) or `~\u002F.aws\u002Fcredentials` file (supports `AWS_PROFILE` and `AWS_SHARED_CREDENTIALS_FILE`)\n- Model IDs: Use full Bedrock model IDs (e.g., `bedrock\u002Fanthropic.claude-3-5-sonnet-20241022-v2:0`)\n\nBase URLs can be overridden with `AXE_\u003CPROVIDER>_BASE_URL` environment variables or in `config.toml`.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n","# 斧头\n\n![斧头横幅](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjrswab_axe_readme_feb2eaee1535.png)\n\n一个用于管理和运行基于大语言模型的智能体的命令行工具。\n\n## 为什么选择 Axe？\n\n大多数 AI 工具都假定你想要的是一个聊天机器人——一个拥有超大上下文窗口、能够一次性完成所有任务的长时间会话。但优秀的软件并非如此运作。优秀的软件应该是小巧、专注且可组合的。\n\nAxe 将 LLM 智能体视为 Unix 系统中的程序：每个智能体只做好一件事。你只需在 TOML 配置文件中定义它，赋予它特定的技能，并通过命令行运行即可。输入数据，输出结果；将多个智能体串联起来；或者通过 cron 作业、Git 钩子或 CI 来触发它们——无论你目前使用什么工具都可以无缝集成。无需守护进程、GUI 或任何框架束缚，只有二进制文件和你的配置。\n\n## 概述\n\nAxe 负责编排由 TOML 配置文件定义的 LLM 智能体。每个智能体都有自己的系统提示、模型选择、技能文件、上下文文件、工作目录、持久化内存，以及委托给子智能体的能力。\n\nAxe 是执行者，而非调度器。它的设计目标是与标准的 Unix 工具（如 cron、Git 钩子、管道、文件监视器）结合使用，而不是重新发明调度或工作流编排功能。\n\n## 特性\n\n- **多提供商支持**：Anthropic、OpenAI、Ollama（本地模型）、OpenCode 和 AWS Bedrock\n- **基于 TOML 的智能体配置**：声明式的、可版本控制的智能体定义\n- **子智能体委托**：智能体可以通过 LLM 工具调用其他智能体，支持深度限制和并行执行\n- **持久化内存**：带有时间戳的 Markdown 日志，可在多次运行之间传递上下文\n- **内存垃圾回收**：借助 LLM 进行模式分析和修剪\n- **技能系统**：可重用的指令集，可在不同智能体之间共享\n- **标准输入管道**：可将任何输出直接输入到智能体中（`git diff | axe run reviewer`）\n- **本地智能体目录**：优先从 `\u003Ccwd>\u002Faxe\u002Fagents\u002F` 自动发现智能体，然后再加载全局配置；也可使用 `--agents-dir` 指定任意路径\n- **干运行模式**：在不调用 LLM 的情况下检查解析后的上下文\n- **JSON 输出**：带元数据的结构化输出，便于脚本处理\n- **内置工具**：文件操作（读、写、编辑、列出）被沙盒化到工作目录；执行 Shell 命令；获取 URL；网络搜索\n- **输出白名单**：限制 `url_fetch` 和 `web_search` 只能访问特定主机名；始终阻止私有\u002F保留 IP 地址（防止 SSRF 攻击）\n- **令牌预算**：通过 `[budget]` 配置或 `--max-tokens` 标志，限制每个智能体运行时的累计令牌用量\n- **MCP 工具支持**：可通过 SSE 或可流式传输的 HTTP 协议连接到外部 MCP 服务器以获取更多工具\n- **可配置重试机制**：针对临时提供商错误（429、5xx、超时）提供指数、线性和固定退避策略\n- **极简依赖**：仅有四个直接依赖项（cobra、toml、mcp-go-sdk、x\u002Fnet）；所有 LLM 调用均使用标准库\n\n## 安装\n\n需要 Go 1.25 或更高版本。\n\n**预编译的二进制文件**（无需安装 Go）适用于 Linux、macOS 和 Windows，可在 [GitHub 发布页面](https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Freleases\u002Flatest) 下载。\n\n通过 Go 安装：\n\n```bash\ngo install github.com\u002Fjrswab\u002Faxe@latest\n```\n\n> 如果出现 `invalid go version` 错误，说明你的 Go 工具链版本低于 1.25。请从 [go.dev\u002Fdl](https:\u002F\u002Fgo.dev\u002Fdl\u002F) 升级，或直接下载预编译的二进制文件。\n\n或者从源码构建：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe.git\ncd axe\ngo build .\n```\n\n## 快速入门\n\n初始化配置目录：\n\n```bash\naxe config init\n```\n\n这将在 `$XDG_CONFIG_HOME\u002Faxe\u002F` 创建目录结构，并生成一个示例技能和用于提供商凭据的默认 `config.toml` 文件。\n\n搭建一个新的智能体：\n\n```bash\naxe agents init my-agent\n```\n\n编辑其配置：\n\n```bash\naxe agents edit my-agent\n```\n\n运行该智能体：\n\n```bash\naxe run my-agent\n```\n\n从其他工具中管道输入：\n\n```bash\ngit diff --cached | axe run pr-reviewer\ncat error.log | axe run log-analyzer\n```\n\n## 示例\n\n`examples\u002F` 目录包含可直接运行的智能体，你可以将其复制到自己的配置中立即使用。其中包括代码审查员、提交信息生成器和文本摘要器——每个智能体都配有专门的 SKILL.md 文件。\n\n```bash\n# 将示例智能体复制到你的配置中\ncp examples\u002Fcode-reviewer\u002Fcode-reviewer.toml \"$(axe config path)\u002Fagents\u002F\"\ncp -r examples\u002Fcode-reviewer\u002Fskills\u002F \"$(axe config path)\u002Fskills\u002F\"\n\n# 设置 API 密钥并运行\nexport ANTHROPIC_API_KEY=\"your-key-here\"\ngit diff | axe run code-reviewer\n```\n\n完整设置步骤请参阅 `examples\u002FREADME.md`。\n\n## Docker\n\nAxe 提供了一个 Docker 镜像，用于在隔离且加固的容器中运行智能体。\n\n### 构建镜像\n\n```bash\ndocker build -t axe .\n```\n\n支持多架构构建（linux\u002Famd64、linux\u002Farm64），可通过 buildx 实现：\n\n```bash\ndocker buildx build --platform linux\u002Famd64,linux\u002Farm64 -t axe:latest .\n```\n\n### 运行智能体\n\n挂载你的配置目录，并将 API 密钥作为环境变量传递：\n\n```bash\ndocker run --rm \\\n  -v .\u002Fmy-config:\u002Fhome\u002Faxe\u002F.config\u002Faxe \\\n  -e ANTHROPIC_API_KEY \\\n  axe run my-agent\n```\n\n使用 `-i` 标志传递标准输入：\n\n```bash\ngit diff | docker run --rm -i \\\n  -v .\u002Fmy-config:\u002Fhome\u002Faxe\u002F.config\u002Faxe \\\n  -e ANTHROPIC_API_KEY \\\n  axe run pr-reviewer\n```\n\n如果没有挂载配置卷，Axe 会以代码 2（配置错误）退出，因为容器内不存在任何智能体 TOML 文件。\n\n### 运行单个智能体\n\n上述示例挂载了整个配置目录。如果你只需要运行一个智能体及其一项技能，只需将这些文件挂载到容器内的预期 XDG 路径即可。当通过环境变量传递 API 密钥时，无需 `config.toml` 文件。\n\n```bash\ndocker run --rm -i \\\n  -e ANTHROPIC_API_KEY \\\n  -v .\u002Fagents\u002Freviewer.toml:\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002Fagents\u002Freviewer.toml:ro \\\n  -v .\u002Fskills\u002Fcode-review\u002F:\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002Fskills\u002Fcode-review\u002F:ro \\\n  axe run reviewer\n```\n\n智能体的 `skill` 字段会自动解析为容器内的 XDG 配置路径，因此无需使用 `--skill` 标志。\n\n如果要使用与智能体 TOML 中声明不同的技能，可以使用 `--skill` 标志进行覆盖。此时只需挂载替换的技能文件，而 TOML 中声明的原始技能将被完全忽略：\n\n```bash\ndocker run --rm -i \\\n  -e ANTHROPIC_API_KEY \\\n  -v .\u002Fagents\u002Freviewer.toml:\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002Fagents\u002Freviewer.toml:ro \\\n  -v .\u002Falt-review.md:\u002Fhome\u002Faxe\u002Falt-review.md:ro \\\n  axe run reviewer --skill \u002Fhome\u002Faxe\u002Falt-review.md\n```\n\n如果智能体声明了 `sub_agents`，则必须同时挂载所有引用的智能体 TOML 文件及其对应的技能。\n\n### 持久化数据\n\n挂载数据卷后，智能体的内存会在多次运行之间保持持久化：\n\n```bash\ndocker run --rm \\\n  -v .\u002Fmy-config:\u002Fhome\u002Faxe\u002F.config\u002Faxe \\\n  -v axe-data:\u002Fhome\u002Faxe\u002F.local\u002Fshare\u002Faxe \\\n  -e ANTHROPIC_API_KEY \\\n  axe run my-agent\n```\n\n### Docker Compose\n\n提供了一个 `docker-compose.yml` 文件，用于将 axe 与本地的 Ollama 实例一起运行。\n\n**仅云提供商（无 Ollama）：**\n\n```bash\ndocker compose run --rm axe run my-agent\n```\n\n**带有 Ollama Sidecar：**\n\n```bash\ndocker compose --profile ollama up -d ollama\ndocker compose --profile cli run --rm axe run my-agent\n```\n\n**拉取 Ollama 模型：**\n\n```bash\ndocker compose --profile ollama exec ollama ollama pull llama3\n```\n\n> **注意：** Compose 中的 `axe` 服务声明了 `depends_on: ollama`。无论是否使用 Ollama，Docker Compose 都会在启动 axe 时尝试启动 Ollama 服务。如果仅在云端使用且不需要 Ollama，请直接使用 `docker run` 而不是 `docker compose run`。\n\n### 主机上的 Ollama\n\n如果 Ollama 直接在主机上运行（而非通过 Compose），请通过以下方式指向它：\n\n- **Linux：** `--add-host=host.docker.internal:host-gateway -e AXE_OLLAMA_BASE_URL=http:\u002F\u002Fhost.docker.internal:11434`\n- **macOS \u002F Windows（Docker Desktop）：** `-e AXE_OLLAMA_BASE_URL=http:\u002F\u002Fhost.docker.internal:11434`\n\n### 安全性\n\n容器默认以以下强化配置运行（通过 Compose）：\n\n- **非 root 用户** — UID 10001\n- **只读根文件系统** — 可写位置为配置挂载点、数据挂载点和 `\u002Ftmp\u002Faxe` tmpfs\n- **丢弃所有能力** — `cap_drop: ALL`\n- **禁止权限提升** — `no-new-privileges:true`\n\n这些设置不会限制出站网络访问。若要隔离仅与本地 Ollama 实例通信的代理，可添加 `--network=none` 并手动将其连接到共享的 Docker 网络。\n\n### 卷挂载\n\n| 容器路径           | 用途                     | 默认访问权限 |\n|--------------------|--------------------------|--------------|\n| `\u002Fhome\u002Faxe\u002F.config\u002Faxe\u002F` | 代理 TOML 文件、技能、`config.toml` | 读写         |\n| `\u002Fhome\u002Faxe\u002F.local\u002Fshare\u002Faxe\u002F` | 持久化内存文件         | 读写         |\n\n配置目录设置为读写是因为 `axe config init` 和 `axe agents init` 会向其中写入内容。如果仅运行代理，则可将其挂载为只读 (`:ro`)。\n\n### 环境变量\n\n| 变量                  | 是否必需 | 用途                                       |\n|-----------------------|----------|--------------------------------------------|\n| `ANTHROPIC_API_KEY`   | 是       | 使用 Anthropic 时的 API 认证               |\n| `OPENAI_API_KEY`      | 是       | 使用 OpenAI 时的 API 认证                 |\n| `AXE_OLLAMA_BASE_URL` | 否       | 使用 Ollama 时的 Ollama 端点（Compose 默认值：`http:\u002F\u002Follama:11434`） |\n| `AXE_ANTHROPIC_BASE_URL` | 否     | 覆盖 Anthropic API 端点                   |\n| `AXE_OPENAI_BASE_URL` | 否       | 覆盖 OpenAI API 端点                       |\n| `AXE_OPENCODE_BASE_URL` | 否     | 覆盖 OpenCode API 端点                     |\n| `TAVILY_API_KEY`      | 是       | 使用 web_search 时的 Tavily Web 搜索 API 密钥 |\n| `AXE_WEB_SEARCH_BASE_URL` | 否   | 覆盖 Web 搜索端点                         |\n\n## CLI 参考\n\n### 命令\n\n| 命令            | 描述                           |\n|-----------------|--------------------------------|\n| `axe run \u003Cagent>` | 运行一个代理                   |\n| `axe agents list` | 列出所有已配置的代理           |\n| `axe agents show \u003Cagent>` | 显示代理的完整配置         |\n| `axe agents init \u003Cagent>` | 构建一个新的代理 TOML 文件 |\n| `axe agents edit \u003Cagent>` | 在 `$EDITOR` 中打开代理 TOML |\n| `axe config path` | 打印配置目录路径               |\n| `axe config init` | 使用默认值初始化配置目录       |\n| `axe gc \u003Cagent>`  | 为某个代理运行内存垃圾回收     |\n| `axe gc --all`    | 对所有启用内存的代理运行 GC    |\n| `axe version`     | 打印当前版本                 |\n\n### 运行标志\n\n| 标志              | 默认值          | 描述                                   |\n|-------------------|-----------------|----------------------------------------|\n| `--model \u003Cprovider\u002Fmodel>` | 来自 TOML | 覆盖模型（例如 `anthropic\u002Fclaude-sonnet-4-20250514`） |\n| `--skill \u003Cpath>`  | 来自 TOML       | 覆盖技能文件路径                       |\n| `--workdir \u003Cpath>` | 来自 TOML 或当前目录 | 覆盖工作目录                         |\n| `--timeout \u003Cseconds>` | 120        | 请求超时时间                           |\n| `--max-tokens \u003Cint>` | 0（无限制） | 限制本次运行的累计 token 使用量（超出则退出码为 4） |\n| `--dry-run`       | false           | 显示解析后的上下文，但不调用 LLM       |\n| `--verbose` \u002F `-v` | false           | 将调试信息（模型、时间、token、重试次数等）输出到 stderr |\n| `--json`          | false           | 将输出包裹在包含元数据的 JSON 框架中   |\n| `-p` \u002F `--prompt \u003Cstring>` | （无） | 内联提示作为用户消息；优先级高于标准输入 |\n| `--agents-dir \u003Cpath>` | （自动发现） | 超越代理搜索目录                       |\n\n#### 用户消息优先级\n\n发送给 LLM 的用户消息按以下顺序解析：\n\n1. **`-p` \u002F `--prompt` 标志** — 如果提供了非空且非空白的值，则将其用作用户消息。\n2. **管道输入** — 如果 `-p` 不存在或为空\u002F仅包含空白字符，则使用管道输入。\n3. **内置默认值** — 如果既没有 `-p` 也没有管道输入，则使用默认消息 `\"执行您指令中描述的任务。\"`。\n\n当同时提供 `-p` 和管道输入时，管道输入会被静默忽略（不会发出警告）。空值或仅包含空白字符的 `-p` 值被视为不存在，流程会继续到管道输入，最后才是默认值。\n\n**示例：**\n```bash\naxe run my-agent -p \"总结 README\"\n```\n\n### 退出码\n\n| 代码 | 含义             |\n|------|------------------|\n| 0    | 成功             |\n| 1    | 运行时错误       |\n| 2    | 配置错误         |\n| 3    | 提供商\u002F网络错误  |\n| 4    | Token 预算超限   |\n\n## 代理配置\n\n代理以 TOML 文件的形式定义，位于 `$XDG_CONFIG_HOME\u002Faxe\u002Fagents\u002F` 目录下。\n\n```toml\nname = \"pr-reviewer\"\ndescription = \"评审拉取请求中的问题和改进建议\"\nmodel = \"anthropic\u002Fclaude-sonnet-4-20250514\"\nsystem_prompt = \"你是一位资深代码评审员。请言简意赅、切中要点。\"\nskill = \"skills\u002Fcode-review\u002FSKILL.md\"\nfiles = [\"src\u002F**\u002F*.go\", \"CONTRIBUTING.md\"]\nworkdir = \"\u002Fhome\u002Fuser\u002Fprojects\u002Fmyapp\"\ntools = [\"read_file\", \"list_directory\", \"run_command\"]\nsub_agents = [\"test-runner\", \"lint-checker\"]\nallowed_hosts = [\"api.example.com\", \"docs.example.com\"]\n\n[sub_agents_config]\nmax_depth = 3       # 最大嵌套深度（硬上限：5）\nparallel = true     # 并发运行子代理\ntimeout = 120       # 每个子代理的超时时间（秒）\n\n[memory]\nenabled = true\nlast_n = 10         # 加载最近 N 条记录到上下文中\nmax_entries = 100   # 超过此值时发出警告\n\n[[mcp_servers]]\nname = \"my-tools\"\nurl = \"https:\u002F\u002Fmy-mcp-server.example.com\u002Fsse\"\ntransport = \"sse\"\nheaders = { Authorization = \"Bearer ${MY_TOKEN}\" }\n\n[params]\ntemperature = 0.3\nmax_tokens = 4096\n\n[budget]\nmax_tokens = 50000    # 0 表示无限制（默认值）\nretry:\n  max_retries = 3           # 在出现瞬时错误时最多重试 3 次\n  backoff = \"exponential\"   # \"指数\"、\"线性\" 或 \"固定\"\n  initial_delay_ms = 500    # 第一次重试前的基础延迟\n  max_delay_ms = 30000      # 最大延迟上限\n\n[[mcp_servers]]\nname = \"filesystem\"\ntransport = \"stdio\"\ncommand = \"\u002Fusr\u002Flocal\u002Fbin\u002Fmcp-server-filesystem\"\nargs = [\"--root\", \"\u002Fhome\u002Fuser\u002Fprojects\"]\n```\n\n除 `name` 和 `model` 外，其他字段均为可选。\n\n### 重试\n\n代理可以在出现暂时性 LLM 提供商错误时进行重试，包括速率限制（429）、服务器错误（5xx）和超时。重试功能为可选，默认情况下是禁用的。\n\n| 字段 | 默认值 | 描述 |\n|---|---|---|\n| `max_retries` | 0 | 初始请求后的重试次数。设置为 0 表示禁用重试。 |\n| `backoff` | `\"exponential\"` | 重试策略：`\"exponential\"`（带抖动）、`\"linear\"` 或 `\"fixed\"` |\n| `initial_delay_ms` | 500 | 第一次重试前的基础延迟时间，单位为毫秒。 |\n| `max_delay_ms` | 30000 | 最大延迟时间上限，单位为毫秒。 |\n\n仅对暂时性错误进行重试。认证错误（401\u002F403）和无效请求（400）绝不会被重试。当启用 `--verbose` 时，每次重试尝试都会记录到标准错误输出中。`--json` 输出包络中会包含一个 `retry_attempts` 字段，用于可观ability 监控。\n\n### 输出白名单\n\n使用 `url_fetch` 或 `web_search` 的代理可以通过 `allowed_hosts` 字段限制为特定的主机名：\n\n```toml\nallowed_hosts = [\"api.example.com\", \"docs.example.com\"]\n```\n\n| 行为 | 详情 |\n|---|---|\n| 空或未指定 | 允许所有公共主机名。 |\n| 非空列表 | 仅允许完全匹配的主机名（不区分大小写，不支持通配符子域名）。 |\n| 私有 IP 地址 | 无论白名单如何，私有 IP 地址始终会被阻止——包括回环地址、链路本地地址、RFC 1918 私有地址、CGNAT 和 IPv6 私有地址。 |\n| 重定向 | 每次重定向的目标都会重新验证是否在白名单内，并检查是否为私有 IP 地址。 |\n| 子代理 | 继承父代理的 `allowed_hosts` 设置，除非子代理的 TOML 文件明确设置了自身的白名单。 |\n\n### Token 预算\n\n可以为单次运行限制累计的 token 使用量（输入 + 输出，跨所有回合及子代理调用）：\n\n```toml\n[budget]\nmax_tokens = 50000   # 0 表示无限制（默认）\n```\n\n也可以通过命令行参数覆盖：\n\n```bash\naxe run my-agent --max-tokens 10000\n```\n\n当命令行参数设置为大于零的值时，该参数优先于 TOML 配置。\n\n当超出预算时，当前响应会被返回，但不会再执行任何工具调用。程序将以 **代码 4** 退出。超出预算的运行不会追加内存。\n\n启用 `--verbose` 时，每一轮都会将累计使用情况记录到标准错误输出中。启用 `--json` 时，输出包络中会包含 `budget_max_tokens`、`budget_used_tokens` 和 `budget_exceeded` 字段（如果未设置限制则省略）。\n\n## 工具\n\n代理可以使用内置工具与文件系统交互并执行命令。启用工具后，代理会进入对话循环——LLM 可以调用工具、接收结果并继续推理，最多可达 50 轮。\n\n### 内置工具\n\n| 工具 | 描述 |\n|---|---|\n| `list_directory` | 列出工作目录相对路径下的目录内容。 |\n| `read_file` | 读取文件内容，显示行号，并可选择分页（偏移\u002F限制）。 |\n| `write_file` | 创建或覆盖文件，必要时会自动创建父目录。 |\n| `edit_file` | 在文件中查找并替换精确文本，可选择全部替换模式。 |\n| `run_command` | 通过 `sh -c` 执行 shell 命令并返回合并的输出。 |\n| `url_fetch` | 获取 URL 内容，去除 HTML 并进行截断。 |\n| `web_search` | 在网络上搜索并返回结果。 |\n| `call_agent` | 将任务委托给子代理（通过 `sub_agents` 控制，而非 `tools`）。 |\n\n通过将工具添加到代理的 `tools` 字段来启用：\n\n```toml\ntools = [\"read_file\", \"list_directory\", \"run_command\"]\n```\n\n`call_agent` 工具并未列在 `tools` 中——它会在配置了 `sub_agents` 且未达到深度限制时自动可用。\n\n### 路径安全\n\n所有文件相关工具（`list_directory`、`read_file`、`write_file`、`edit_file`）都被沙盒化到代理的工作目录中。绝对路径、`..` 跳转以及符号链接逃逸均会被拒绝。\n\n### 并行执行\n\n当 LLM 在同一轮中返回多个工具调用时，默认会并发执行。这适用于内置工具和子代理调用。可通过在 `[sub_agents_config]` 中设置 `parallel = false` 来禁用并行执行。\n\n### MCP 工具\n\n代理可以使用来自外部 [MCP](https:\u002F\u002Fmodelcontextprotocol.io\u002F) 服务器的工具。在代理的 TOML 文件中使用 `[[mcp_servers]]` 声明服务器：\n\n```toml\n[[mcp_servers]]\nname = \"my-tools\"\nurl = \"https:\u002F\u002Fmy-mcp-server.example.com\u002Fsse\"\ntransport = \"sse\"\nheaders = { Authorization = \"Bearer ${MY_TOKEN}\" }\n```\n\n启动时，axe 会连接到每个声明的服务器，通过 `tools\u002Flist` 发现可用工具，并将其与内置工具一起提供给 LLM 使用。\n\n| 字段 | 必需 | 描述 |\n|---|---|---|\n| `name` | 是 | 服务器的人类可读标识符。 |\n| `url` | 是 | MCP 服务器的端点 URL。 |\n| `transport` | 是 | `\"sse\"` 或 `\"streamable-http\"`。 |\n| `headers` | 否 | HTTP 头部；值支持 `${ENV_VAR}` 插值。 |\n\nMCP 工具完全由 `[[mcp_servers]]` 控制——它们不会列在 `tools` 字段中。如果某个 MCP 工具与已启用的内置工具同名，则内置工具优先。\n\n## 技能\n\n技能是一组可重用的指令集，为代理提供特定领域的知识和工作流程。它们以社区 SKILL.md 格式定义的 `SKILL.md` 文件形式存在。\n\n### 技能解析\n\n代理 TOML 文件中的 `skill` 字段按以下顺序解析：\n\n1. **绝对路径**——直接使用（例如 `\u002Fhome\u002Fuser\u002Fskills\u002FSKILL.md`）。 |\n2. **相对于配置目录**——例如 `skills\u002Fcode-review\u002FSKILL.md` 解析为 `$XDG_CONFIG_HOME\u002Faxe\u002Fskills\u002Fcode-review\u002FSKILL.md`。 |\n3. **纯名称**——例如 `code-review` 解析为 `$XDG_CONFIG_HOME\u002Faxe\u002Fskills\u002Fcode-review\u002FSKILL.md`。 |\n\n### 脚本路径\n\n技能通常会引用辅助脚本。由于 `run_command` 是在代理的工作目录中执行的（而非技能目录），因此 **SKILL.md 中的脚本路径必须是绝对路径**。相对路径会导致失败，因为这些脚本不存在于代理的工作目录中。\n\n```\n# 正确——绝对路径\n\u002Fhome\u002Fuser\u002F.config\u002Faxe\u002Fskills\u002Fmy-skill\u002Fscripts\u002Ffetch.sh \u003Cargs>\n\n# 错误——相对路径无法从代理的工作目录解析\nscripts\u002Ffetch.sh \u003Cargs>\n```\n\n### 目录结构\n\n```\n$XDG_CONFIG_HOME\u002Faxe\u002F\n├── config.toml\n├── agents\u002F\n│   └── my-agent.toml\n└── skills\u002F\n    └── my-skill\u002F\n        ├── SKILL.md\n        └── scripts\u002F\n            └── fetch.sh\n```\n\n## 本地代理目录\n\n默认情况下，代理会从 `$XDG_CONFIG_HOME\u002Faxe\u002Fagents\u002F` 加载。Axe 还支持项目本地代理目录，用于每个仓库的代理定义。\n\n### 自动发现\n\n如果 `\u003Ccwd>\u002Faxe\u002Fagents\u002F` 存在，Axe 会优先搜索该项目目录，然后再搜索全局配置目录。与全局代理同名的本地代理会覆盖全局代理。\n\n```\nmy-project\u002F\n└── axe\u002F\n    └── agents\u002F\n        └── my-agent.toml   ← 自动找到\n```\n\n### 显式覆盖\n\n使用 `--agents-dir` 可以指向任意目录：\n\n```bash\naxe run my-agent --agents-dir .\u002Fcustom\u002Fagents\n```\n\n此标志适用于所有命令：`run`、`agents list`、`agents show`、`agents init`、`agents edit` 和 `gc`。\n\n### 解析顺序\n\n1. `--agents-dir`（如果提供了）\n2. `\u003Ccwd>\u002Faxe\u002Fagents\u002F`（自动发现）\n3. `$XDG_CONFIG_HOME\u002Faxe\u002Fagents\u002F`（全局回退）\n\n第一个包含匹配的 `\u003Cname>.toml` 文件的目录将被优先使用。\n\n### 智能脚手架\n\n`axe agents init \u003Cname>` 会写入 `\u003Ccwd>\u002Faxe\u002Fagents\u002F` 目录，如果该目录已存在；否则将回退到全局配置目录。\n\n## 提供者\n\n| 提供者 | API 密钥环境变量 | 默认基础 URL |\n|---|---|---|\n| Anthropic | `ANTHROPIC_API_KEY` | `https:\u002F\u002Fapi.anthropic.com` |\n| OpenAI | `OPENAI_API_KEY` | `https:\u002F\u002Fapi.openai.com` |\n| Ollama | （无需） | `http:\u002F\u002Flocalhost:11434` |\n| OpenCode | `OPENCODE_API_KEY` | 可配置 |\n| AWS Bedrock | （使用 AWS 凭证） | 基于区域 |\n\n**AWS Bedrock 配置：**\n- 区域：可通过 `AWS_REGION` 环境变量或在 `config.toml` 中设置 `[providers.bedrock] region = \"us-east-1\"` 来指定。\n- 凭证：使用环境变量（`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_SESSION_TOKEN`）或 `~\u002F.aws\u002Fcredentials` 文件（支持 `AWS_PROFILE` 和 `AWS_SHARED_CREDENTIALS_FILE`）。\n- 模型 ID：需使用完整的 Bedrock 模型 ID（例如：`bedrock\u002Fanthropic.claude-3-5-sonnet-20241022-v2:0`）。\n\n基础 URL 可通过 `AXE_\u003CPROVIDER>_BASE_URL` 环境变量或在 `config.toml` 中进行覆盖。\n\n## 许可证\n\nApache-2.0。详情请参阅 [LICENSE](LICENSE)。","# Axe 快速上手指南\n\nAxe 是一个命令行工具，用于管理和运行由大语言模型（LLM）驱动的智能体（Agents）。它遵循 Unix 哲学，将每个智能体设计为专注单一任务的可组合程序，支持通过管道、Cron 或 Git Hooks 集成到现有工作流中。\n\n## 环境准备\n\n*   **操作系统**：Linux, macOS, Windows\n*   **Go 版本**：若需从源码构建，要求 Go 1.25+。\n*   **API 密钥**：根据使用的模型提供商（如 Anthropic, OpenAI, Ollama 等），需提前准备好相应的 API Key。\n\n## 安装步骤\n\n您可以选择下载预编译二进制文件或通过 Go 安装。\n\n### 方式一：下载预编译二进制文件（推荐）\n访问 [GitHub Releases 页面](https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Freleases\u002Flatest) 下载对应系统的最新版本，无需安装 Go 环境。\n\n### 方式二：通过 Go 安装\n确保已安装 Go 1.25 或更高版本，运行以下命令：\n\n```bash\ngo install github.com\u002Fjrswab\u002Faxe@latest\n```\n\n> **注意**：如果提示 `invalid go version`，请升级您的 Go 工具链或改用预编译二进制文件。\n\n### 方式三：从源码构建\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe.git\ncd axe\ngo build .\n```\n\n## 基本使用\n\n### 1. 初始化配置\n首次使用前，初始化配置目录。这将在 `$XDG_CONFIG_HOME\u002Faxe\u002F` 下创建必要的文件夹结构、示例技能文件和默认的 provider 配置文件。\n\n```bash\naxe config init\n```\n\n### 2. 创建智能体\n创建一个名为 `my-agent` 的新智能体骨架：\n\n```bash\naxe agents init my-agent\n```\n\n使用默认编辑器编辑其 TOML 配置文件（定义模型、系统提示词、技能文件等）：\n\n```bash\naxe agents edit my-agent\n```\n\n### 3. 运行智能体\n直接运行配置好的智能体：\n\n```bash\naxe run my-agent\n```\n\n### 4. 管道输入（核心用法）\nAxe  Designed to be composed with standard Unix tools. 您可以将其他命令的输出直接管道传递给智能体：\n\n```bash\n# 审查暂存的代码变更\ngit diff --cached | axe run pr-reviewer\n\n# 分析日志文件\ncat error.log | axe run log-analyzer\n```\n\n### 5. 设置 API 密钥\n在运行前，请通过环境变量设置您的 API 密钥：\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-key-here\"\n# 或\nexport OPENAI_API_KEY=\"your-key-here\"\n```\n\n### 进阶提示\n*   **查看可用命令**：使用 `axe agents list` 查看所有已配置的智能体。\n*   **调试模式**：添加 `--dry-run` 标志可在不调用 LLM 的情况下检查解析后的上下文；添加 `-v` 查看详细调试信息。\n*   **示例参考**：项目自带的 `examples\u002F` 目录包含代码审查员、提交信息生成器等现成配置，可直接复制使用。","某后端开发团队在日常迭代中，需要频繁对代码提交进行安全扫描、日志异常分析及文档同步更新。\n\n### 没有 axe 时\n- **流程割裂且手动**：开发者需分别打开聊天窗口粘贴代码、切换终端查看日志、再手动编写文档，上下文频繁切换导致效率低下。\n- **难以自动化集成**：现有的 AI 助手多为长会话聊天机器人，无法直接嵌入 Git Hooks 或 Cron 定时任务，难以实现“提交即审查”的无人值守流程。\n- **上下文污染严重**：通用大模型会话缺乏隔离，历史对话干扰当前任务，且无法针对特定任务（如仅检查 SQL 注入）定义专注的系统提示词。\n- **结果非结构化**：AI 返回的自然语言描述难以被脚本解析，无法直接触发后续的自动修复或报警动作。\n\n### 使用 axe 后\n- **流水线式自动化**：通过 `git diff | axe run security-scan` 将代码审查直接嵌入提交钩子，或利用 Cron 定时运行日志分析代理，实现全流程无人干预。\n- **专注且可组合的代理**：在 TOML 文件中定义仅负责\"SQL 注入检测”或\"Nginx 错误归类”的轻量级代理，像 Unix 管道一样串联使用，各司其职。\n- **持久化记忆与隔离**：每个代理拥有独立的 Markdown 记忆日志，跨运行保留关键上下文，同时通过工作目录沙箱确保文件操作安全。\n- **结构化输出对接**：利用 JSON 输出模式，让 axe 的分析结果直接作为下游脚本的输入参数，自动创建 Jira 工单或发送钉钉警报。\n\naxe 将庞大的 AI 能力拆解为可编排、可集成的命令行原子工具，让智能体真正融入现代软件工程的标准工作流。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjrswab_axe_feb2eaee.png","jrswab","Jaron Swab","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fjrswab_7414f8d2.jpg","Husband, Father & Coffee Enthusiast | Col 3:17",null,"USA","jr@jrswab.com","https:\u002F\u002Fgithub.com\u002Fjrswab",[81,85,89],{"name":82,"color":83,"percentage":84},"Go","#00ADD8",99.9,{"name":86,"color":87,"percentage":88},"Dockerfile","#384d54",0.1,{"name":90,"color":91,"percentage":92},"Makefile","#427819",0,793,24,"2026-04-14T09:02:21","Apache-2.0","Linux, macOS, Windows","未说明",{"notes":100,"python":101,"dependencies":102},"该工具是基于 Go 语言开发的命令行工具，无需 Python 环境。支持通过预编译二进制文件直接运行，或通过 Go 源码编译安装。支持 Docker 容器化部署（提供多架构镜像）。运行时需要配置对应 LLM 提供商（如 Anthropic, OpenAI, Ollama 等）的 API 密钥。","不需要",[103,104,105,106,107],"Go 1.25+","cobra","toml","mcp-go-sdk","x\u002Fnet",[13,14,52,35],[110,111,112,113,114,115,116],"cli","golang","ai-agents","automation","command-line","developer-tools","llm","2026-03-27T02:49:30.150509","2026-04-15T08:10:21.210320",[120,125,130,135,140,145,150,155],{"id":121,"question_zh":122,"answer_zh":123,"source_url":124},34071,"如何直接向代理传递提示词（Prompt），而不使用管道输入？","可以使用 `-p` 标志直接传递提示词。命令格式为：`axe run my-agent -p \"MY_PROMPT\"`。这替代了之前必须使用 `echo MY_PROMPT | axe run my-agent` 的管道方式，也支持交互式输入模式。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F43",{"id":126,"question_zh":127,"answer_zh":128,"source_url":129},34072,"在 Debian 上使用 `go install` 安装时遇到 'invalid go version' 错误怎么办？","这是因为项目需要 Go 1.25 版本，而 Debian 默认源提供的 Go 版本（如 1.23）过低。解决方法是访问 Go 官方网站下载并安装最新的 Go 1.25 版本，而不是使用 `apt` 安装的旧版本。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F48",{"id":131,"question_zh":132,"answer_zh":133,"source_url":134},34073,"使用 OpenAI o-series 模型或 gpt-5-nano 时报错 'max_tokens is not supported' 如何解决？","OpenAI 已弃用这些模型的 `max_tokens` 参数，改用 `max_completion_tokens`。该问题已在代码中修复，将 JSON 标签从 `max_tokens` 更新为 `max_completion_tokens`。请确保升级到最新版本以获取此修复。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F34",{"id":136,"question_zh":137,"answer_zh":138,"source_url":139},34074,"是否支持配置出站连接的允许列表（Allowlist）以增强安全性？","是的，已支持该功能。可以在代理的 TOML 配置文件中设置 `allowed_hosts` 列表（例如 `allowed_hosts = [\"api.example.com\"]`）。代理将被限制只能访问列表中指定的域名，未列出的主机请求会被阻止并记录日志。目前暂不支持 CIDR 格式的 IP 范围。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F24",{"id":141,"question_zh":142,"answer_zh":143,"source_url":144},34075,"如何处理 LLM 提供商的间歇性故障（如速率限制或服务器错误）？","系统已内置重试逻辑。您可以在代理的 TOML 配置或全局配置中设置重试参数，例如：\n```toml\n[retry]\nmax_retries = 3\nbackoff = \"exponential\"\ninitial_delay_ms = 500\n```\n该机制会自动重试速率限制 (429)、服务器错误 (500\u002F503) 和网络超时，但不会重试认证错误或无效请求。此功能已在 v1.4.0 版本中发布。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F29",{"id":146,"question_zh":147,"answer_zh":148,"source_url":149},34076,"链式代理之间如何共享状态或上下文，而不仅仅依靠管道传输文本？","官方不建议引入复杂的内存状态存储。推荐的解决方案是利用文件系统：让所有代理在同一个工作目录（working directory）下运行，代理 A 可以将结果写入该目录下的文件，代理 C 随后读取该文件即可实现状态共享。这是一种轻量且有效的替代方案。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F30",{"id":151,"question_zh":152,"answer_zh":153,"source_url":154},34077,"是否有预构建的 Docker 镜像可用？","维护者已计划提供 Docker 镜像。虽然早期曾因工作流问题延迟，但目前已支持通过 GitHub Container Registry (ghcr) 或 Docker Hub 获取预构建镜像，用户无需每次都是从源码构建或使用 `go install` 安装。请检查项目的 Packages 页面获取最新镜像地址。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F26",{"id":156,"question_zh":157,"answer_zh":158,"source_url":159},34078,"是否支持 Anthropic 和 OpenAI 兼容 API 的流式输出？","是的，流式输出功能已被添加。这使得交互式用例更加流畅，用户可以实时看到生成的回复内容，而不是等待全部生成完毕。该功能已通过相关 Pull Request 合并。","https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fissues\u002F59",[161,166,171,176,181,186,191,196,201,206,211,216],{"id":162,"version":163,"summary_zh":164,"released_at":165},263981,"v1.7.1","## 更改记录\n### 修复\n- 在命令路径验证中屏蔽 URL (#70)\n\n### 变更\n- 在 v1.7.0 文档中添加 streaming、timeout 和 tool_call_details 字段 (#69)\n\n## Docker\n```bash\ndocker pull ghcr.io\u002Fjrswab\u002Faxe:1.7.1\n```\n\n有关所有可用标签，请参阅 [GHCR 软件包页面](https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fpkgs\u002Fcontainer\u002Faxe)。","2026-04-06T17:24:36",{"id":167,"version":168,"summary_zh":169,"released_at":170},263982,"v1.7.0","### 新增\n- 响应流式传输支持 (#68)\n- 烟囱测试 CI 工作流 (#55)\n- 代理 TOML 文件的顶级超时设置 (#63)\n\n### 变更\n- 在 --json 输出中的 tool_call_details 中添加 turn 和 duration_ms 字段 (#64)\n\n## Docker\n```bash\ndocker pull ghcr.io\u002Fjrswab\u002Faxe:1.7.0\n```\n\n请参阅 [GHCR 软件包页面](https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fpkgs\u002Fcontainer\u002Faxe) 以获取所有可用标签。","2026-04-01T19:10:40",{"id":172,"version":173,"summary_zh":174,"released_at":175},263983,"v1.6.1","### 已修复\n- 将相对工件目录解析为代理工作目录，而非进程的当前工作目录\n\n## Docker\n\n```bash\ndocker pull ghcr.io\u002Fjrswab\u002Faxe:1.6.1\n```\n\n请参阅 [GHCR 软件包页面](https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fpkgs\u002Fcontainer\u002Faxe) 以获取所有可用标签。\n","2026-03-27T02:33:41",{"id":177,"version":178,"summary_zh":179,"released_at":180},263984,"v1.6.0","### 新增\n- 工件管理系统 (#47)\n- `axe run` 的内联提示标志 (#46)\n- mdBook 文档站点及部署工作流 (#50)\n\n### 变更\n- 扩展了发布流程，增加了版本号更新、README 文件更新以及 GHCR 步骤\n\n### Docker\n```bash\ndocker pull ghcr.io\u002Fjrswab\u002Faxe:1.6.0\n```","2026-03-24T15:36:13",{"id":182,"version":183,"summary_zh":184,"released_at":185},263985,"v1.5.0","### 新增\n- 出站连接的输出白名单 (#45)\n- 本地代理目录支持 (#41)\n- 每次代理运行的 Token 预算限制 (#37)\n\n### 变更\n- 整合 Docker 发布工作流 (#44)\n- 将 github.com\u002Fmodelcontextprotocol\u002Fgo-sdk 从 1.4.0 升级至 1.4.1 (#39)\n\n### Docker 镜像\n- https:\u002F\u002Fgithub.com\u002Fjrswab\u002Faxe\u002Fpkgs\u002Fcontainer\u002Faxe\u002F748712095?tag=1.5.0","2026-03-20T18:24:35",{"id":187,"version":188,"summary_zh":189,"released_at":190},263986,"v1.4.0","GHCR：[ghcr.io\u002Fjrswab\u002Faxe](https:\u002F\u002Fghcr.io\u002Fjrswab\u002Faxe)","2026-03-18T02:43:41",{"id":192,"version":193,"summary_zh":194,"released_at":195},263987,"v1.3.0","\n","2026-03-16T02:43:10",{"id":197,"version":198,"summary_zh":199,"released_at":200},263988,"v1.2.0","### 新增\n- OpenCode 提供者支持\n- `url_fetch` 工具的 HTTP 请求超时（每请求 15 秒）\n- 对 `url_fetch` 响应进行 HTML 标签剥离\n","2026-03-10T17:08:17",{"id":202,"version":203,"summary_zh":204,"released_at":205},263989,"v1.1.1","### 修复\n- 移除 OpenAI 提供者 URL 路径中的硬编码 `\u002Fv1`","2026-03-06T23:46:48",{"id":207,"version":208,"summary_zh":209,"released_at":210},263990,"v1.1.0","### 新增\n- MCP 工具支持\n- 使用 Tavily Search API 的内置工具 `web_search`\n- 内置工具 `url_fetch`\n- 运行输出中的 JSON 格式 `tool_call_details`\n- JSON 输出中的拒绝检测功能\n- 可执行示例\n\n### 变更\n- 支持通过选择性挂载运行单个代理的 Docker 文档","2026-03-06T15:00:43",{"id":212,"version":213,"summary_zh":214,"released_at":215},263991,"v1.0.0","### 新增\n- 核心 CLI，包含 `run`、`agents list`、`agents show`、`agents init`、`agents edit`、`gc` 和 `config init` 命令\n- 基于 TOML 的代理配置，支持 SKILL.md 上下文\n- 多提供商大模型支持：Anthropic、OpenAI 和 Ollama\n- 工具调用系统，提供 `read_file`、`write_file`、`edit_file`、`list_directory` 和 `run_command` 等工具\n- 子代理编排功能，通过 `call_agent` 工具实现，并支持深度限制的执行\n- 代理内存系统，采用 XDG 兼容的数据存储方式，并具备垃圾回收机制\n- 路径安全：对用户提供的路径支持 `~` 和 `$VAR` 展开\n- 支持标准输入管道，可与 Unix 工具组合使用\n- 模拟运行模式及按工具粒度的详细日志记录\n- Docker 容器化支持\n- CI 工作流：代码风格检查、测试、构建以及 GoReleaser 打包\n\n### 修复\n- 参数验证用户体验及技能路径解析问题\n- staticcheck\u002Ferrcheck 静态分析工具发现的问题\n- 重复错误抑制、Glob 路径匹配验证以及针对 `nil ExitError` 的防护措施\n","2026-03-02T23:33:33",{"id":217,"version":218,"summary_zh":219,"released_at":220},263992,"v0.1.0","## Changelog\n* d26db06ad86de569a050f48436fae3893c6d47cd Add 'Why Axe?' section to README\n* 506dfecb8da4d45bfd3840911c028dfa3aace334 Add AGENTS.md for LLM coding agent context\n* 811706f876c3643f6700093b83dda1e7e07e96ae Add CHANGELOG.md for v0.1.0 release\n* d95c0de219e9f2ebb6e1656d6fcd4dcc31a20092 Add CI workflows and GoReleaser config for axe\n* 5df01495f6812d844ac7685740d484e7222be8f7 Add CLI smoke tests and golden file tests (Phases 3-4)\n* 075c8b341fe1a515280469c02e14b5d0fcb26d70 Add Docker containerization and README documentation\n* a93c0c764f39542580f21799255a2ec2cc72423f Add M4 multi-provider support spec, implementation checklist, and resolve fixes\n* 9e047c0b6db9d2d842ec44abe8bc340da0182711 Add M8 integration & polish: dry-run tools display, per-tool verbose logging, golden tests, integration tests\n* 4f5db3be43b630fe7f95887c9cd2b0b8bdd48359 Add Phase 5-6 tests and mark implementation plan complete\n* 87d38271b574df1dedd89750865e7a31cfea7cce Add Stdin, BuildSystemPrompt, and axe run command with tests (M3 Phases 9-11)\n* fb57ff173cbb2259d185c7780ced0be629c67e16 Add agent config structs, Load, List, Validate, and Scaffold with tests (M2 Phases 1-6)\n* 4cae3af1449071917171453f6c9493bb8a3f1988 Add agents CLI commands: list, show, init, edit with tests (M2 Phases 7-12)\n* eb57a6b7a66ebe1eeb98471eee19a7abcbbe69dd Add banner image to README\n* d4e20002124a5c150f0cbb35f29efe9694023323 Add context resolution: Workdir, Files, and Skill with tests (M3 Phases 6-8)\n* a155bcc8505f790cea47608e089df2bbebe1b740 Add edit_file tool with find-and-replace and path security (M6)\n* 9bdbcc550afe8cfb50ff6c02b326962b821147ab Add golangci-lint config, Makefile lint target, and fix all errcheck\u002Fstaticcheck errors\n* 4cbdea4b2981e7abf809bb4b6169fbeb4ec73406 Add i9n milestones plan\n* 0f4b3826b1ba920d16f1403ff2a0ac8ee00aa1cd Add integration test infrastructure (Phase 1)\n* 4991877908fd028c5f7e3c4a82bc1bd465db6328 Add list_directory tool, validatePath, and RegisterAll (M3 phases 1-3)\n* af17d2e9fca092072aeea41d0779aa428401c455 Add manual testing plan, list_directory spec, and mark M8 milestones complete\n* e899bf4bdf5dc5e4aea58d498fad4dec626cfaa1 Add mock provider integration tests (Phase 2, parts 10-18)\n* b284632d70640fbc00eea74e360149ea41378055 Add project documentation and update .gitignore\n* f8c6ae389a7c3f61c0c7d6a54d45aee2797cb657 Add provider types, Anthropic provider, and ExitError for M3 (Phases 1-5)\n* fe1a247dd355a66a32db9dc7e96907d034d71609 Add read_file tool with line-numbered output and pagination (M4)\n* 8b6000bf07462fe53232ad617f0ed50aea8b0677 Add reusable mock LLM server and response helpers (Phase 2, parts 1-9)\n* f83ea65bb92f1ad76054590b3007d9287788a4da Add skeleton CLI with version, config path, and config init commands\n* 51193bb1b0b5c50a045edfdaf96b51e46ce10f20 Add tool call documentation to README\n* 2ab0ac5f3d20c310bc8c724a50d363ef50873acc Add tool registry for centralized tool dispatch (M2)\n* 9f5fc2f7bc5c2d8b1a4a34da4010c0fc7b3a2238 Add tools config field to AgentConfig (M1)\n* e623673dfe8deaefdf8276e789c7c43c1836bbbb Add write_file tool with path security and parent dir creation (M5)\n* 92dfd3ec63232667b57deadd78b53e6f1f6e29c7 Add ~ and $VAR expansion for user-supplied paths\n* 46ecd3b185efbfe9f2bb7d798b2b0856aca1590b Bump version to 1.0.0\n* 755b8146d1947c4b50bd41e05654a6e96f4b47db Fix M4 review issues: reorder API key check, eliminate goroutine test races, add missing tests\n* 89ad8f2102232da15a3d31be17ff26367db56b54 Fix arg validation UX and skill path resolution\n* 4b4aff012122eaf1a79aa63bbcb2bfd83f155ac0 Fix review issues: silence duplicate errors, validate ** globs, guard nil ExitError (M3 Phase 12)\n* 50de7a577d29065b214adad9ac4399afa88c2fd8 Fix staticcheck QF1012: use fmt.Fprintf instead of WriteString(fmt.Sprintf(...))\n* 54ada3996a80cee42e94e2711307dcdb896f6780 Implement M4: Multi-provider support (OpenAI, Ollama, provider factory, global config)\n* f41eda22c31366c4dba329069ee3369b2d9dd378 Initial commit\n* 8da5ac994c90482d14683e5b60d38a6ecd4cc739 M5 Phase 1-2: Add tool-calling types and Anthropic provider tool support\n* b321c90eca0fbdc89d72acfba278e3f48088e3cd M5 Phase 3: Add OpenAI provider tool-calling support\n* 013c49d33d8aaf5cd0aa527cfa977eb823359c43 M5 Phase 4: Add Ollama provider tool-calling support\n* 1e3a8b9dc470d6fc9940480db30e7ac3ca2d5946 M5 Phase 5-7: Add SubAgentsConfig, call_agent tool definition, and ExecuteCallAgent\n* 95235549a6862081462c1e4fd74fd304c565a7bf M5 Phase 8: Add conversation loop, tool injection, parallel execution, and output extensions\n* 3383a23bf51e0e3145fd80c5e0956f9c646ad171 M5 Phase 9-10: Add depth-limit tool stripping test and complete final verification\n* 96adbacd8ae5773efcc2d1b5db3ac19f8b3070e7 M6 Phase 4: Add top-level run memory integration (load, append, dry-run, verbose, warnings)\n* 46c8bb80c6bbf51a4db5e1cf25429ed0c579687a M6 Phases 1-3: Add XDG data dir, memory config fields, and memory package core\n* 833a33502bfe2e7a99ef307871c3a4ada6541de8 M6 Phases 5-6: Add sub-agent memory integ","2026-03-16T02:42:50"]