Agent QA 失败结果分类（Triage）：基于证据的 Agent QA 运行故障研判指南-开发者社区

Agent QA 失败结果分类（Triage）：基于证据的 Agent QA 运行故障研判指南

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills

在 Agentic Awesome Skills（AAS）仓库的 testing 类技能体系中，agent-qa-result-triage是连接「证据采集」与「定位修复」的关键一环：它解决的是「一次失败的 Agent QA 运行到底应该归因到哪一类问题、该由谁负责、下一步做什么」。本文基于 plugins/agentic-awesome-skills-claude/skills/agent-qa-result-triage/SKILL.md 及配套分类参考 references/triage-categories.md 展开，并结合仓库中相邻的 authoring / debug-fix 技能与数据目录中的元数据，给出可直接落地的研判流程。读完本文，你将掌握：如何从运行记录（run）、制品（artifacts）、步骤结果与日志中提取证据，如何从八个固定分类中「只选一个」给出结论，如何声明置信度、所有权归属与下一步行动，以及何时移交到修复阶段。

技能定位：用证据代替猜测

agent-qa-result-triage的核心主张非常明确：对一次失败的 Agent QA 运行进行分类，必须基于其记录的证据，而不是靠直觉猜测。技能的元描述（frontmatter 中的description）将其概括为：通过 MCP 证据、制品、日志、固定的失败分类、置信度与可执行的下一步行动，对失败的 Agent QA 运行进行分流（Triage）。在 data/catalog.json 的技能目录条目中，该技能被标记为category: testing、risk: safe，触发词（triggers）覆盖testing、qa、triage、mcp、failed runs、evidence、artifacts、logs等，说明它面向的是 QA 运行失败后的第一道研判工序，且属于不修改任何代码/配置的低风险操作。

它适用的场景包括四类典型情况：

正在调查一次失败或中断的 Agent QA 运行；
需要检查运行制品、步骤结果或执行日志；
需要对比近期相关运行，识别反复出现的失败模式；
需要决策一次失败究竟属于test（测试）、product（产品）、hook（钩子）、browser/mobile runtime（浏览器/移动端运行时）还是 infrastructure（基础设施）的所有者。

证据优先的六步工作流

技能给出了严格按证据采集顺序推进的研判流程，任何一步的省略都会降低结论的可信度：

从运行入口开始：调用agent_qa_get_run，获取运行状态、套件子上下文（suite child context）、步骤与重试次数（attempts）。
先采集证据再下结论，至少从以下四个 MCP 工具中获取证据：
- agent_qa_get_run_artifact—— 读取运行制品（截图、DOM/无障碍上下文、设备日志等）；
- agent_qa_get_run_steps—— 读取逐步执行结果；
- agent_qa_get_run_logs—— 读取常规运行日志；
- agent_qa_get_run_execution_logs—— 读取执行层日志（含 stderr、运行时错误）。
调用分类器并以此为默认结论：调用agent_qa_classify_failure，将其输出的类别作为默认分类，除非有更强的证据与之矛盾。
横向对比近期运行：当分类器输出中带有近期相关运行记录时，进行对比，识别复发模式。
输出精简的分流结论：包含类别（category）、置信度（confidence）、证据（evidence）、可能的修复面（likely fix area）、下一步行动（next action）五个要素。
交接修复阶段：如果需要修改代码，在分流完成后切换到 agent-qa-debug-fix。

从该技能与 agent-qa-debug-fix/SKILL.md 的分工可以看到完整闭环：agent-qa-result-triage的职责止步于「证据化分类与移交」，而agent-qa-debug-fix负责「把分类器当作假设（hypothesis）而非判决，检查相关本地源码，做最小改动并验证」。因此分流阶段严禁越过边界直接改测试或产品代码。

八大失败分类及其判定依据

技能明确要求：只从references/triage-categories.md中选取恰好一个分类。八个分类并非平行罗列，而是按照「先运行时、后应用层、再环境层」的思路组织的证据判据。下表为分类参考文件的完整内容，附上每类的首选检查点（First Checks）：

分类	适用情形（Use When）	首选检查点（First Checks）
`timeout`	运行或某步骤超过超时时间	运行失败摘要、步骤耗时、日志
`appium_startup`	Appium 启动失败或未能获取移动端会话	失败摘要、执行日志、制品中的运行时错误
`browser_disconnect`	浏览器、页面或上下文意外关闭	包含`browser closed`或`target closed`的错误日志
`element_not_found`	定位器、元素、选择器或 UI 描述不可用	失败步骤错误、观察记录、截图、DOM/无障碍上下文
`assertion_failure`	应用可达，但期望的内容或状态不匹配	失败的断言/验证步骤、观察记录、截图
`hook_failure`	设置（setup）、清理（teardown）或钩子执行阻塞了运行	钩子日志、钩子制品区段、钩子注册表错误
`infrastructure`	网络、Docker、farm、设备、文件系统或服务依赖失败	执行日志、stderr、制品中的运行时错误
`unknown_failure`	证据不足以支持更强的分类	缺失的区段与下一步需要采集的证据

这个分类体系的价值在于可操作性：每个分类都对应明确的证据来源。例如browser_disconnect不应仅凭「页面打不开」就下结论，而必须看到含browser closed/target closed的日志；element_not_found则需要失败步骤错误、观察记录、截图或 DOM/无障碍上下文中的至少一项；infrastructure则需要执行日志、stderr 或制品运行时错误中的环境层证据。当证据不足以支撑任何更强分类时，如实选择unknown_failure，并在结论中明确「缺失了哪些证据区段、下一步应采集什么」。

注意：分类标识的是最可能的失败面（failure surface），而非已证明的根因（root cause）。这在技能 Limitations 中被明确强调。

证据规则：可引用的边界与脱敏义务

为了让分类结论可复核、可追溯，技能对证据的使用划定了硬性边界：

引用或概括真实证据：必须引用或概括具体的制品、日志或步骤证据，而不是空泛描述；
诚实声明证据缺口：当制品区段缺失、影响置信度时，必须在结论中点名；
禁止虚构证据：不得编造 MCP 未返回的截图、视频、日志或记忆上下文；
回退路径：当 MCP 不可用时，允许改用仪表盘 REST API 或 Agent QA CLI 输出作为回退，并明确声明哪些证据不可用；
脱敏义务：必须从报告中移除凭据、会话令牌、个人数据以及与主题无关的应用内容。

这条规则与该技能risk: safe的定位一致——它只读取和研判，不产生变更，因此证据的「可采信度」完全取决于上述纪律。相比之下，下游的agent-qa-debug-fix因涉及修改代码与重跑测试，在目录中被标记为risk: critical，其证据纪律更严格：不得仅凭制品推断补丁、必须直接检查相关本地文件、修复前优先调用agent_qa_validate_test/agent_qa_validate_suite/agent_qa_validate_definition验证 YAML。

输出示例：一次`element_not_found`的标准分流

技能提供了一个 JSON 形式的分流结果模板，用于保证输出结构的稳定与可机器解析：

{ "category": "element_not_found", "confidence": "high", "evidence": ["Step 4 could not resolve the described checkout button"], "likely_fix_area": "test definition or changed product UI", "next_action": "Inspect the captured UI context, then compare the current checkout screen" }

拆解这个示例可以看到分流的产出标准：

category：恰好一个分类（此处为element_not_found）；
confidence：显式声明置信度等级（high/medium/low等）——当截图、DOM/无障碍上下文、设备日志或历史运行缺失时，必须下调置信度；
evidence：指向具体可复核的制品证据（此处为第 4 步的失败事实）；
likely_fix_area：指出最可能的修复归属面，如「测试定义或产品 UI 变更」；
next_action：给出证据支撑的下一步行动，例如「检查捕获的 UI 上下文，再对比当前结账页面」。

局限性：置信度与边界的诚实声明

技能明确列出四类限制，这些限制也是使用者判断结论可靠性的标尺：

结论上限取决于证据留存：分类的可靠性不会超过保留下的运行制品与日志；
类别≠根因：失败类别只锁定最可能的失败面，不能证明根因；
证据缺失必须降级：截图、DOM/无障碍上下文、设备日志或历史运行的缺失，都必须降低置信度；
只读边界：本技能不修改测试或应用代码；授权修复需切换到agent-qa-debug-fix。

在技能体系中的衔接：从作者到分流到修复

要正确使用该技能，需要理解它在 AAS testing 类技能中的位置。以 agent-qa-authoring/SKILL.md 为代表的「上游」负责创建合法的测试/套件/钩子定义，其配套契约文件 agent-qa-contracts.json 定义了 ID 生成规则（t_/s_/h_/r_/obs_前缀 + 10 个 id-agent 词）以及测试/套件/钩子的必填与可选键——这保证了失败运行中的 run ID、test ID 都是可校验的规范标识；agent-qa-result-triage位于「中游」，消费这些 ID 对应的证据并产出分类；agent-qa-debug-fix位于「下游」，仅在授权范围内对likely_fix_area指向的本地定义或代码做最小修复并重跑最窄范围的验证。

从仓库文件结构看，三个技能在同一skills/目录下以独立技能包形式组织（各含SKILL.md与可选的references/目录），共享同一套 MCP 工具命名（agent_qa_get_run、agent_qa_classify_failure、agent_qa_validate_*等）与分类假设传递语义：triage 把分类器输出当作默认结论，debug-fix 则把它当作待验证的假设。理解这一差异，是避免「分类即定案」误用的关键。

落地建议：把分流做成可审计的环节

综合技能文档与仓库元数据，在实际 Agent QA 工作流中落地该技能时建议：

固化证据采集顺序：先agent_qa_get_run拿到运行骨架，再按 artifact → steps → logs → execution_logs 的顺序补齐证据，最后才允许agent_qa_classify_failure参与结论；
强制单分类输出：遵循triage-categories.md的「恰好一个分类」约束，避免「既是超时又是元素未找到」这类无法执行的模糊结论；
把置信度与证据缺口绑定：在分流报告中显式列出缺失的证据区段（无截图、无 DOM 上下文、无历史运行等），并在这些情况下主动下调置信度；
明确交接触发条件：结论中likely_fix_area指向代码或 YAML 时，按流程移交 agent-qa-debug-fix；只有unknown_failure时，下一步行动应为「补充证据采集」而非「盲目修复」；
全程遵守只读与脱敏：该技能只读不改，报告中不留凭据与敏感应用数据，这一边界是它被标记为risk: safe的前提，也是分流环节可以放心自动化执行的基础。