Agent设计实战：从自动修Bug项目看AI Agent与工具设计原则

GitHub Copilot 的付费功能可以根据 issue 自动生成 PR，这个能力听起来很酷，但它是怎么实现的？一位 B 站 UP 主（EchoDM）通过复刻这个功能，深入探讨了 AI Agent 的设计哲学。这个项目不仅是一个技术 Demo，更是一份关于如何构建实用 Agent 系统的思考记录。

项目概览：一个插件化的自动修 Bug 机器人

这个项目的本质是一个 GitHub 插件：任何仓库安装后，用户只需提交一个 issue，插件就会自动分析需求、修改代码、运行测试，并最终创建一个 PR。UP 主演示了五个 issue，前四个是实现不同的排序算法，最后一个是将项目改造成命令行工具。每个 issue 都成功触发了 PR 的自动生成，PR 中还包含了详细的执行信息。

整个流程依托 GitHub Actions 运行。脚本将 Action 拆分为四个步骤：

1. 授权与任务解析：确认提交 issue 的用户有权限，并从 issue 描述中提取出明确的“任务”。
2. 工作分支准备：检查该 issue 是否已有对应的 PR，决定是新建分支还是在现有 PR 上继续修改。
3. Agent 修改与验证：Agent 根据任务调用工具修改代码，并通过 Docker 运行测试来验证修改是否满足要求。
4. 发布 PR：创建 PR 供仓库维护者 review。

这个架构清晰地将“任务理解”“环境准备”“代码修改”“验证反馈”和“结果交付”解耦，体现了 Agent 系统设计中的一个关键原则：让模型专注于决策，而将确定性操作交给代码。

GitHub Actions 是 GitHub 提供的持续集成与持续部署（CI/CD）服务，允许开发者在仓库中定义自动化工作流。每个工作流由事件触发（如 issue 创建、代码推送），并运行在 GitHub 提供的虚拟机或容器中。在本项目中，GitHub Actions 充当了 Agent 的运行环境：当用户提交 issue 时，Action 自动启动，执行预定义的脚本步骤。由于 Actions 原生支持 Docker 容器，项目能够方便地利用 Docker 来保证测试环境的一致性，从而可靠地验证代码修改。这种设计将 Agent 的决策逻辑与执行环境解耦，使系统更易于维护和扩展。

Agent 的核心循环：输入、调用、反馈

Agent 的运行机制可以概括为一个简单的循环：模型接收任务描述，调用工具执行操作，将工具返回的结果作为新输入，再次决策，直到模型认为任务完成。

这个循环看似基础，但其中蕴含了 Agent 设计的精髓：工具是模型与外部世界交互的桥梁。模型不需要知道代码库的全部细节，它只需要通过工具获取足够的上下文，然后决定下一步操作。这种设计让系统保持了灵活性和可扩展性。

UP 主在项目中设计了三类工具：

• 代码查找工具：帮助模型定位需要修改的代码位置。
• 代码修改工具：执行具体的代码变更。
• 代码验证工具：运行测试，检查修改是否通过。

这三类工具恰好对应了“感知—行动—验证”的闭环，构成了 Agent 完成代码修改任务的最小工具集。

在 Agent 语境中，“工具”指的是模型可以调用的外部函数或接口，用于执行具体操作（如搜索代码、修改文件、运行测试）。模型本身并不直接操作文件系统或网络，而是通过生成特定的调用指令来请求工具执行，并将返回结果作为下一步决策的输入。这种设计基于大语言模型的推理能力：模型根据任务描述和工具返回的上下文，决定何时调用哪个工具、传入什么参数。工具调用通常以结构化格式（如 JSON）表示，便于程序解析和执行。通过组合多个工具，Agent 能够完成复杂的多步任务，而无需在模型内部硬编码所有逻辑。

Agent 设计原则一：简单至上

UP 主反复强调，设计 Agent 系统最重要的原则是简单。当前 Agent 框架层出不穷，但许多场景下并不需要引入复杂的框架。相反，直接基于 AI 原生 API 封装一层或两层抽象，反而更可控、更易调试。

他将 Agent 系统拆解为三个部分：用户、模型、硬编码的规则（Harness）。模型像“变化的水”，而硬编码的规则是“水管”，规定了水流动的方向。设计 Agent 系统，就是要根据目标、场景和业务情况，为这三者设定合适的规则。

在这个项目中，规则的核心是职责划分：用户负责提出需求（issue），模型负责决策与调用工具，硬编码的 Action 脚本负责权限校验、分支管理、Docker 验证等确定性任务。这种划分让模型不必处理琐碎的环境操作，从而更专注于代码修改本身。

这种“简单”哲学还体现在调试便利性上。UP 主建议自定义关键数据的输出格式，以便在 Agent 行为异常时快速定位问题。相比依赖框架的黑盒行为，自己掌控数据流显然更可靠。

Harness（硬编码规则层）是指围绕模型构建的确定性控制逻辑，负责处理模型不擅长或不应处理的环节，例如权限校验、错误处理、资源管理、状态维护等。在 Agent 系统中，Harness 定义了模型可以做什么、不能做什么，以及如何与外部环境交互。它通常由传统代码实现，确保系统的安全性和可靠性。例如，在本项目中，Harness 包括检查用户权限、创建分支、运行 Docker 测试等步骤。通过将确定性操作交给 Harness，模型可以专注于需要推理和决策的任务，从而降低整体系统的复杂性和不确定性。

Agent 工具设计原则二：为模型而设计

工具设计的好坏直接决定了 Agent 的成败。UP 主指出，Agent 工具的设计与普通 API 设计完全不同，需要围绕“模型如何调用”来思考。

他总结了六条工具设计原则：

1. 从任务出发：工具集应围绕 Agent 要完成的任务来构建，而不是盲目堆砌功能。
2. 命名清晰且职责单一：工具名称要直白地反映其用途，让模型能轻松理解何时调用。
3. 参数与返回值透明：使用直白的变量名，明确说明用途和返回值，最好提供样例。
4. 返回有意义的上下文：工具返回的内容应是对模型决策有用的信息，而非原始数据堆砌。
5. 只返回必要信息：避免信息过载，只给模型刚好需要的内容。
6. 持续迭代优化：将工具放入真实任务中运行，观察表现，根据反馈不断调整。

这些原则的核心思想是：降低模型调用工具的认知负担。模型不是人类开发者，它无法通过阅读文档来理解工具，只能通过名称、参数和返回值来推断。因此，工具的设计必须“自解释”，让模型在少量尝试后就能正确使用。

UP 主还提到，工具的迭代过程可以交给 Agent 自己跑，无需过多人工干预。通过观察 Agent 在真实任务中的表现，开发者能快速发现工具设计的缺陷并改进。

总结与启示

这个自动修 Bug 项目虽然规模不大，但完整展示了 Agent 系统的关键设计决策。它告诉我们，构建实用的 Agent 并不需要复杂的框架，而是需要清晰的职责划分、简单的抽象层，以及为模型量身定制的工具集。

对于想要尝试 Agent 开发的开发者来说，这个项目提供了一个可复用的思路：从具体任务出发，设计最小工具集，保持系统简单可调试，让模型在循环中自主决策。正如 UP 主所说，模型是水，规则是水管——好的设计，就是让水在正确的管道中流畅运行。

（项目源码及配套学习文档可在 UP 主仓库中获取。）