Bug Investigator（故障调查技能）

AI 会写代码，但它真的会调查 Bug 吗？随着 AI 编程工具的发展，越来越多的软件开发任务开始交给 Agent 完成。从生成代码、实现功能，到运行测试、修复错误，AI 正在逐渐融入软件开发的各个环节。 但在实际开发过程中，我们发现了一个值得关注的问题：

当 AI 遇到 Bug 时，它往往急于修改代码，却未必真正理解故障发生的原因。

例如，一个桌面应用启动失败，AI 可能立即修改启动脚本；一个 API 返回 HTTP 500，AI 可能直接重写接口逻辑。这些操作有时能够解决问题，但也可能只是暂时绕过症状，甚至引入新的问题。 因此，我们开发了 Bug Investigator（故障调查技能）。它的目标不是让 AI 修改更多代码，而是让 AI 在修改代码之前，先学会调查问题。

01｜为什么需要 Bug Investigator？

传统软件工程中，故障调查与代码修复是两个相互关联但并不相同的过程。当程序出现异常时，开发者通常需要回答几个问题：

• 故障究竟发生在哪里？

• 当前看到的是故障症状，还是根本原因？

• 哪些信息已经得到证实？

• 哪些判断仍然只是猜测？

• 如何通过最小范围的验证排除错误解释？

对于 AI Agent 来说，这些问题同样重要。然而，如果缺少明确的调查规范，Agent 可能在看到错误信息后立即尝试修复。例如：

发现错误
   ↓
猜测原因
   ↓
修改代码
   ↓
重新运行
   ↓
继续猜测

这种方式容易产生重复修改、无效尝试以及不必要的工程风险。Bug Investigator 希望建立另一种工作模式：

发现故障
   ↓
定义问题
   ↓
收集证据
   ↓
定位故障边界
   ↓
建立候选原因
   ↓
验证与排除
   ↓
形成根因判断
   ↓
提出修复建议

02｜它究竟能够做什么？

Bug Investigator 是一个面向软件工程场景的 Agent Skill。它不是独立运行的调试软件，而是为具备相应工具访问能力的 AI Agent 提供故障调查规范。目前主要覆盖以下场景。 程序启动与运行异常 包括应用无法启动、Runtime 异常退出、端口冲突以及环境配置问题。 API 与服务故障 包括 HTTP 4xx/5xx 错误、前后端通信失败、服务调用异常等。 依赖与构建问题 包括依赖版本冲突、运行环境不兼容、构建失败及部署异常。 数据库与系统配置问题 包括数据库连接失败、配置加载异常、环境变量不一致等。 复杂故障链路分析 针对涉及多个组件的系统，追踪故障从底层原因到用户可见症状的传播过程。 这些能力并不是简单地为错误信息匹配解决方案，而是帮助 Agent 根据实际项目证据建立诊断结论。

03｜从症状出发，追踪真正的根因

假设一个桌面应用启动后显示：

服务器不可用

如果只根据界面提示判断，很容易认为是前端通信异常。但真正的故障链可能是：

8766 端口已被占用
        ↓
Backend 尝试绑定端口
        ↓
端口绑定失败
        ↓
Backend 启动失败
        ↓
Gateway 无法连接 Backend
        ↓
UI 显示服务器不可用

在这个示例中： 用户看到的症状是服务器不可用。 直接故障是 Backend 无法启动。 而真正需要调查的原因是目标端口为什么无法正常绑定。 Bug Investigator 会引导 Agent 沿着执行链路逐步检查，并寻找能够支持判断的实际证据。例如：

lsof -nP -iTCP:8766 -sTCP:LISTEN

通过检查端口监听状态、进程身份和应用启动配置，逐步判断是否存在端口冲突。需要强调的是，发现端口被占用，并不意味着应该立即终止对应进程。该进程可能属于系统服务、其他项目，甚至是当前应用的正常实例。调查的目标是理解问题，而不是通过破坏现有运行状态来尝试修复。

04｜不是所有根因都能立即确认

Bug Investigator 的一个重要设计，是明确区分不同程度的诊断结论。当前版本采用四级根因状态模型。

为什么要这样设计？因为 AI 生成一个看起来合理的解释，并不意味着这个解释已经得到证实。例如：

假设：
数据库连接失败是因为密码错误。

这个判断可能合理，但如果没有查看实际错误日志、连接配置或认证结果，就不能将它作为已确认根因。Bug Investigator 要求 Agent 尽可能寻找支持证据与反证。如果证据不足，就应该明确说明：

根因状态：未知

已确认：
数据库连接失败。

尚未确认：
是否由认证信息错误导致。

下一步：
检查实际连接错误与运行配置。

能够承认未知，也是可靠工程诊断的重要能力。

05｜默认只读，减少不必要的修改

在软件开发过程中，某些诊断操作本身就可能影响系统状态。例如，删除缓存、终止进程、升级依赖或者修改数据库。因此，Bug Investigator 默认采用只读优先的调查策略。允许 Agent 根据实际权限读取代码、检查日志、查看配置、分析依赖、检查进程以及执行低副作用的诊断操作。但默认不主动修改源代码、删除文件、终止未知进程或调整生产环境配置。当用户明确要求：

只分析原因，不要修改代码。

这一要求会成为调查过程中的强约束。这让故障调查与实际修复之间形成更加清晰的边界。对于复杂项目、生产环境以及需要保留现场证据的问题，这种设计尤其重要。

06｜让不同 Agent Skill 各司其职

Bug Investigator 并不试图承担整个软件开发过程。在我们的 Agent 软件工程技能体系中，不同技能具有不同职责。例如： Project Analyst 负责理解陌生项目，包括技术栈、架构、依赖关系和运行流程。 Bug Investigator 负责调查具体故障，建立证据链并判断根因。 Coding Agent 根据已经确认的问题实施代码修复。 Tests 通过测试验证修复结果是否符合预期。 它们可以组成一条完整的软件工程工作流：

Project Analyst
        ↓
理解项目

Bug Investigator
        ↓
调查故障

Coding Agent
        ↓
实施修复

Tests
        ↓
验证结果

这种设计的价值，在于让 Agent 不必依靠单一的通用指令处理所有任务，而是通过不同技能形成更明确的执行边界。 Bug Investigator 负责回答：为什么会发生这个问题？而不是直接承担所有代码修改工作。