智能体 QA 调试修复

Agent QA Debug Fix

概述

根据记录的证据和相关的本地源码，修复失败的 Agent QA 运行。将分类结果视为假设，进行最小且合理的更改，并验证受影响的最小范围行为，避免为了掩盖真实缺陷而单纯重写测试。

使用场景

• Agent QA 运行失败且已完成分诊，现在需要对代码或 YAML 进行修复。

• 产出物和日志指向测试、钩子（hook）、产品、运行时或 Agent 行为缺陷。

• 提出的修复方案必须通过最小范围的 Agent QA 或单元测试重新运行来验证。

• 用户要求根据证据进行自愈或更新过时的 Agent QA 定义。

前提条件与审批边界

• 确认用户授权修改的仓库、工作区、目标环境和文件。

• 在重新运行测试前，检查其外部副作用；对于面向生产环境、破坏性或不可逆的操作，需获得明确确认。

• 保留无关的用户更改，并将补丁限制在证据显示的失败范围内。

• 不要泄露产出物和日志中的凭据或敏感应用数据。

工作流

1. 开始收集证据：
- agent_qa_get_run
- agent_qa_get_run_steps
- agent_qa_get_run_artifact
- agent_qa_get_run_logs
- agent_qa_get_run_execution_logs
2. 调用 agent_qa_classify_failure，将其分类结果视为假设而非定论。
3. 确定失败层面：测试定义、钩子、被测应用、运行时基础设施或 Agent 行为。
4. 直接检查相关的本地文件。不要仅凭产出物推断补丁。
5. 解释证据与更改之间的关联，然后应用能够解释该证据的最小代码或 YAML 更改。
6. 在执行前验证任何更改后的 Agent QA 定义。
7. 在批准的环境中重新运行受影响范围最小的 Agent QA 测试、套件、钩子或单元测试。
8. 报告根本原因、修改的文件、验证命令或 MCP 操作、结果以及剩余风险。

修复规则

• 不要虚构选择器、屏幕状态、截图、日志或源文件。

• 当产出物显示产品或运行时缺陷时，不要为了通过测试而单纯重写测试。

• 在编辑测试、套件、钩子或内存文件时，保留规范的 Agent QA ID。

• 在重新运行编辑后的 YAML 之前，优先使用 agent_qa_validate_test、agent_qa_validate_suite 和 agent_qa_validate_definition。

• 当 MCP 不可用时，使用仪表盘 REST API 或本地 .agent-qa 产出物，并注明 MCP 证据不可用。

• 当证据无法区分两种截然不同的修复方案时，停止操作并报告阻塞点。

示例

用户：修复 staging 环境中失败的结账运行，但不要触碰生产环境。
预期处理：收集失败运行的证据，对其进行分类，检查涉及的本地定义和应用代码，仅修复证据显示的诱因，验证...

```

局限性

• 需要访问相关的运行证据和本地源码；仅凭构建产物可能无法确定根本原因。

• 无法保证浏览器、设备、网络或供应商的间歇性故障在一次成功重跑后即被修复。

• 未授权在用户批准的范围之外进行生产环境变更、数据变更、依赖安装或大规模重构。

• 狭义范围内的重跑通过不能替代仓库的常规测试套件或人工审核。