ai-bug-triage

用于 Bug 分类、去重和生成工单的混合流水线。确定性指纹处理去重（这是 LLM 不擅长的）；LLM 负责解释、评估严重程度和编写工单（这些是 LLM 擅长的）。

关键认知转变： LLM 最擅长解释和分流，而不是去重。教会 Agent 设计流水线，而不是成为流水线本身。

---

探索问题

先检查 .agents/qa-project-context.md——其中包含技术栈、组件映射和已知的不稳定区域，有助于提高分类准确性。使用其中的信息，并跳过已回答的问题。然后进一步确认：

1. 故障来源是什么？

   • CI 流水线日志（GitHub Actions、GitLab CI、Jenkins、CircleCI）
   • 测试框架输出（Playwright、Jest、pytest、Vitest）
   • 生产环境错误监控（Sentry、Datadog、Bugsnag）
   • QA 或用户手动提交的 Bug 报告

2. 工单要提交到哪里？

   • Jira、Linear、GitHub Issues、Azure DevOps、Shortcut
   • 需要哪些字段？（组件、严重程度、优先级、标签）
   • 有哪些工作流？（分流看板、自动分配规则）

3. 去重范围是什么？

   • 同一次测试运行？同一个 Sprint？同一个版本？不限时间？
   • 是否已有指纹机制？当前重复率是多少？

4. 需要怎样的审批工作流？

   • 自动创建工单，由人工审核？
   • 先生成工单建议，再由人工批准后创建？
   • 自动关闭重复项？（有风险——必须经过审批）

5. 有哪些历史数据？

   • 是否有包含解决情况的历史 Bug 报告？
   • 是否有不稳定测试历史记录？已知的环境问题？
   • 是否有组件负责人映射？

---

核心原则

1. 先确定性处理，再使用 LLM。 使用稳定、可复现的指纹机制进行去重和聚类。仅在需要理解能力的任务中使用 LLM：严重程度分类、根因假设以及编写易读的工单。

2. 比较前先规范化。 原始 CI 日志中充斥着时间戳、端口号、进程 ID 和随机后缀，导致相同的故障看起来各不相同。生成指纹前应清除所有噪声。

3. 指纹应基于稳定元素。 异常类型、堆栈顶部帧、测试名称、错误消息模板和 URL 模式都很稳定。时间戳、请求 ID 和临时端口则不稳定。

4. 执行破坏性操作前须经人工批准。 将工单自动关闭为重复项或自动合并报告都必须经人工确认。错误去重比人工分流更浪费时间。

5. 分类决定分流。 分流的价值不在于标签本身，而在于由此做出的分流决策：分配给哪个团队、优先级如何、SLA 是什么。

6. 跟踪分流准确率。 衡量自动分类与人工判断的匹配频率。准确率低于 85% 时，说明流水线需要调整。

---

流水线

CI Log / Error Report
  │
  ▼
Step 1: NORMALIZE
  Strip timestamps, process IDs, ports, random suffixes, ANSI codes
  │
  ▼
Step 2: EXTRACT STABLE ANCHORS
  Exception type, top N stack frames, test name, error message template, URL pattern
  │
  ▼
Step 3: HASH CANONICAL FORM
  Deterministic fingerprint from ordered anchors
  │
  ▼
Step 4: CLUSTER NEAR-DUPLICATES
  Similarity scoring for non-identical but related failures
  │
  ▼
Step 5: LLM CLASSIFY
  Severity, component, suspected root cause, failure category
  │
  ▼
Step 6: LLM GENERATE TICKET
  Title, description, repro steps, evidence, suggested assignee
  │
  ▼
Step 7: HUMAN APPROVAL
  Review before create/close/merge

步骤 1：规范化

清除导致相同故障看起来各不相同的噪声。

规范化规则（按顺序应用）：

1. Strip ANSI color codes:        \x1b\[[0-9;]*m → ""
2. Strip timestamps:              \d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}[.\d]*Z? → "<TIMESTAMP>"
3. Strip UUIDs:                   [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} → "<UUID>"
4. Strip process IDs:             pid[=: ]\d+ → "pid=<PID>"
5. Strip port numbers:            :\d{4,5}(?=[\s/,)\]]|$) → ":<PORT>"
6. Strip temp file paths:         /tmp/[^\s]+ → "<TMPPATH>"
7. Strip memory addresses:        0x[0-9a-f]{8,16} → "<ADDR>"
8. Strip random suffixes:         [-_][a-z0-9]{6,8}(?=\.) → "<RAND>"
9. Strip request IDs:             (?:request[_-]?id|trace[_-]?id|correlation[_-]?id)[=: ]["']?[a-zA-Z0-9-]+ → "<REQ_ID>"
10. Collapse whitespace:          \s+ → " "

示例：

Before: 2025-03-22T14:32:01.456Z [pid=42891] Error: Connection refused at 127.0.0.1:54321
        request_id=abc-123-def-456
After:  <TIMESTAMP> [pid=<PID>] Error: Connection refused at 127.0.0.1:<PORT>
        <REQ_ID>

规则 5 会移除端口，但不会移除字面上的回环 IP——127.0.0.1 会保留在指纹中。对于发生在同一主机上的故障，这没有问题；但如果两个运行器绑定的主机不同（例如 127.0.0.1 和 0.0.0.0），就会生成不同的指纹。如果运行环境中的主机类型不一致，请添加一条同时规范化绑定地址的规则。

步骤 2：提取稳定锚点

从规范化日志中提取能够识别故障、且不受环境或时序影响的元素。

锚点类型（按优先级排序）：

锚点	示例	稳定性
异常类型	TypeError、AssertionError、HTTP 500	非常高
错误消息模板	Cannot read property 'X' of undefined	高
前 3 个堆栈帧	at processOrder (order.ts:142)	高
测试名称	checkout.spec.ts > completes payment	非常高
URL 模式	POST /api/orders	高
HTTP 状态码	500、429、503	非常高
退出码	exit code 1、SIGKILL	高
断言差异	Expected: 200, Received: 500	中

提取规则：

• 保留函数名称，但去掉行号（编辑后行号会变化）
• 保留 URL 路径，但去掉查询参数和路径中的 ID（/api/orders/<ID>）
• 保留错误消息结构，并将动态值替换为占位符
• 按原样保留测试文件和测试名称

步骤 3：对规范形式进行哈希处理

根据提取出的锚点创建确定性指纹。

算法：

1. Sort anchors alphabetically by type
2. Concatenate: exception_type + "|" + message_template + "|" + top_frames + "|" + test_name
3. SHA-256 hash the concatenated string
4. Take first 16 hex characters as fingerprint

指纹属性：

• 相同故障始终生成相同指纹（确定性）
• 不同故障生成不同指纹（抗碰撞）
• 日志格式的细微变化不会改变指纹（稳定）
• 指纹足够短，可用作 Jira 标签和 GitHub 标签

示例：

Anchors:
  exception_type: "TypeError"
  message_template: "Cannot read property 'vendorId' of undefined"
  top_frames: "processOrder|groupByVendor|checkout"
  test_name: "checkout.spec.ts > multi-vendor checkout"

Canonical: "TypeError|Cannot read property 'vendorId' of undefined|processOrder|groupByVendor|checkout|checkout.spec.ts > multi-vendor checkout"
Fingerprint: a3f8b2c1e9d04567

步骤 4：聚类近似重复项

通过精确的指纹匹配可捕获完全相同的故障。通过相似度评分可捕获略有差异的相关故障（根本原因相同，但表现不同）。

相似度维度：

维度	权重	匹配标准
异常类型	0.30	完全匹配
错误消息	0.25	Levenshtein 距离 < 消息长度的 20%
堆栈帧	0.25	前 5 个帧的 Jaccard 相似度 > 0.6
组件/文件	0.10	目录或模块相同
测试名称	0.10	describe 块或测试文件相同

**聚类阈值：**相似度得分 > 0.75 = 很可能是重复项，建议合并。

以下情况需要人工审核：

• 得分介于 0.60 和 0.75 之间（存在歧义）
• 新指纹首次出现时（没有历史记录可供比较）
• 已知存在间歇性问题的组件发生故障时

步骤 5：使用 LLM 分类

完成确定性指纹处理和聚类后，使用 LLM 对故障进行分类。提示词会输入异常、消息、前 5 个堆栈帧、测试名称和 CI 上下文，并要求给出以下五个字段：

1. 故障类别 — test bug | application bug | environment issue | flaky test | build failure
2. 严重性 — critical | major | minor | trivial（见下方严重性矩阵）
3. 组件 — 根据堆栈跟踪和文件路径推断
4. 疑似根本原因 — 1 至 2 句假设
5. 置信度 — high | medium | low；置信度较低时，LLM 会说明还需要哪些信息才能作出判断

将低置信度分类结果转交人工审核，而不是自动采取行动。完整提示词文本见 references/pipeline-prompts-and-integration.md；提示词应参考的错误类别、严重性和组件映射定义见 references/classification-taxonomy.md。

故障类别（详情见 references/ci-failure-analysis.md）：

类别	描述	典型操作
应用程序 Bug	应用程序出现故障	创建 Bug 工单，分配给负责团队
测试 Bug	测试有误	修复测试，无需更改应用程序
环境问题	CI 基础设施/网络/服务宕机	重试，通知基础设施团队
不稳定测试	间歇性、非确定性	隔离，调查根本原因
构建失败	编译、依赖项、配置问题	修复构建，通常会阻止后续流程

第 6 步：由 LLM 生成工单

完成分类后，使用 LLM 生成符合人工撰写质量的 Bug 工单。提示词会接收分类结果、规范化后的错误、日志摘录和相关集群指纹，并生成：

• 标题 — 简洁、便于搜索，包含组件名称（少于 80 个字符）
• 描述 — 用通俗语言说明发生了什么（绝不包含原始日志）
• 复现步骤 — 根据测试名称和日志上下文生成
• 证据 — 相关日志行、断言差异，以及可用的屏幕截图
• 建议标签 — [component, severity, failure-category, fingerprint]
• 建议指派对象 — 如果已知，则根据组件归属确定

fingerprint 应添加到工单中（标签和 Fingerprint 字段），以便将来去重时进行匹配。完整提示词和 Bug 报告模板请参见 references/pipeline-prompts-and-integration.md。

第 7 步：人工审批

未经审核不得执行自动化操作。 工作流负责提出建议，由人工决策。

审批决定：

• 创建工单 — 新故障，根本原因明确，指派给团队
• 合并到现有工单 — 已知问题的重复项，将证据添加到现有工单
• 隔离测试 — 不稳定测试，并非应用 Bug；隔离测试并安排调查
• 重试并监控 — 环境问题，重试 CI；若问题持续，则发出提醒
• 驳回 — 已知问题已在待部署版本中修复，或测试 Bug 有明显的修复方法

---

严重性/优先级矩阵

严重性衡量影响程度。优先级衡量紧迫性。它们是彼此独立的维度。

严重性定义

严重性	定义	示例
Critical	系统无法使用、数据丢失、安全漏洞，且没有变通方法	支付处理失败、用户数据泄露、应用启动时崩溃
Major	核心功能损坏、体验下降，但存在变通方法	搜索返回错误结果、结账需要重新加载页面、点击后退按钮时表单数据丢失
Minor	非核心功能受影响，或外观问题造成了功能影响	排序设置无法保留、工具提示在移动设备上被截断、次要操作失败
Trivial	仅影响外观，不影响功能	标签中有拼写错误、对齐偏差 1px、大小写不一致

优先级定义

优先级	定义	SLA（示例）
P0	立即修复，会阻碍发布或影响生产环境	当天
P1	在本迭代中修复，对用户有显著影响	本迭代
P2	在下一迭代中修复，影响中等	下一迭代
P3	方便时修复，影响较低	待办事项

严重性 x 优先级决策指南

	Critical	Major	Minor	Trivial
影响所有用户	P0	P0	P1	P2
影响部分用户（>10%）	P0	P1	P2	P3
影响少数用户（<10%）	P1	P1	P2	P3
仅影响边缘情况	P1	P2	P3	P3

---

Bug 报告模板

无论是自动生成还是人工编写，任何 Bug 报告都使用相同模板。模板包含缺陷标题、严重性/优先级/组件/环境/指纹/报告者元数据，以及描述、复现步骤、预期/实际行为、证据、发生频率、建议的根本原因和相关问题。完整的可复制粘贴 Markdown 模板请参见 references/pipeline-prompts-and-integration.md。

---

去重模式

模式	检测方式	操作
完全重复	指纹相同	合并到现有工单，并添加证据
近似重复	属于同一集群（相似度 > 0.75）	关联工单，建议合并并由人工审核
根因相同，症状不同	不同测试中的异常类型相同，且栈帧有重叠	创建父工单并关联症状工单
已修复 Bug 回归	指纹与已关闭工单匹配	重新打开工单，标记为回归，并提高优先级
间歇性复发	多次 CI 运行中间歇性出现相同指纹	标记为不稳定测试；如果发生率 > 10%，则隔离

---

CI 失败分析

完整的模式请参阅 references/ci-failure-analysis.md。关键判断：持续失败 = 测试 Bug 或应用 Bug；间歇性失败 = 不稳定测试或环境问题；同时出现多个失败 = 环境问题或共享组件问题；构建失败 = 代码或依赖项问题。

---

集成模式

流水线输出与问题跟踪器无关：步骤 6 会生成标题、描述、标签、严重性和组件，可映射到任何问题跟踪器的字段。gh issue create / 指纹去重命令、GitHub Actions 的“失败时分类”工作流，以及 Jira/Linear/Azure DevOps REST/GraphQL 集成说明，请参阅 references/pipeline-prompts-and-integration.md。

购买还是自建

在实现完整流水线之前，先确认是否已有托管平台能够完成你计划实现的工作。现在有几种工具提供 AI 驱动的测试分类功能，与步骤 4-6 的工作有直接重叠。

平台	涵盖功能	备注
Trunk Flaky Tests	指纹识别、聚类、严重性路由、原生 PR 评论 + webhook	提供专用的 Agent 分类功能；有完善文档的隔离工作流——是现成产品中最接近本技能流水线的方案
CloudBees Smart Tests	指纹识别、基于 ML 的优先级排序、测试影响分析	前身是 Launchable——查阅旧文档的 Agent 可能会看到旧名称
Datadog Test Optimization	不稳定测试管理（自动重试、提前检测不稳定测试、失败测试重放）、测试影响分析	Bits AI Dev Agent 现在会自动生成修复 PR；Flaky Test Policies 会在 30 天后自动隔离并禁用测试。如果你已经在使用 Datadog，可与 Datadog APM 搭配使用
Sealights	质量智能和测试影响门控	面向企业；在受监管行业中表现最突出

在以下情况下，使用技能内的流水线：(a) 需要本地部署或气隙部署；(b) 问题跟踪器集成方式特殊；或 (c) 为满足合规要求，需要明确记录 AI 提示词的审计轨迹。否则，购买现成方案通常比重建指纹识别 + 聚类功能更便宜。

模型选择成本说明

分类（步骤 5）使用 Sonnet 4.6 / Haiku 4.5——成本低，能力也足够。只有在集群较新颖、失败原因不明确或建议的根因置信度较低时，才升级到 Opus 4.8。每次分类都使用 Opus 会造成浪费。

---

反模式

1. 使用 LLM 去重

LLM 具有非确定性。相同的两条错误比较两次，可能会得到不同的相似度分数。去重应使用确定性指纹识别；LLM 仅用于解释和分类。

2. 未经审核就自动关闭

根据指纹匹配自动将工单关闭为“重复”，可能会合并不同的问题。关闭或合并操作务必要求人工确认。

3. 过度判定严重性

如果所有问题都是“严重”，那就没有真正严重的问题。严格遵循严重性矩阵。即使有人觉得烦人，外观上的错别字也只是轻微问题。

4. 忽略环境故障

许多失败其实是 CI 基础设施问题（Docker 内存耗尽、网络超时、磁盘已满），却把所有失败都标记为“应用 Bug”。应单独分类环境问题——它们需要不同的修复措施。

5. 没有反馈闭环

只构建一次流水线，却从不衡量准确率。跟踪：自动分类准确率、误判重复率，以及开发者对工单质量的评分。

6. 在工单中粘贴原始日志

将 500 行原始 CI 输出粘贴到缺陷工单中。应进行规范化、提取相关行，并只展示关键的 5-10 行。

7. 指纹生成前未进行规范化

对原始日志行进行哈希会生成不稳定的指纹，每次运行都会变化——同一故障每次都会得到不同的指纹，因此去重永远不会触发。规范化是必须的：指纹生成前务必先进行规范化（步骤 1），绝不要对原始日志生成指纹。

8. 没有组件归属映射

分类后不进行路由就毫无用处。维护组件到团队的映射，让已分类的缺陷能够送达正确的负责人。

---

验证

指纹生成器是关键基础，信任任何去重逻辑之前，先验证它。针对你的实现，运行 references/ci-failure-analysis.md 中的 5 项稳定性断言：

1. 相同错误，时间戳不同 → 指纹相同。
2. 相同错误，PID 和端口不同 → 指纹相同。
3. 相同错误，行号不同（代码已编辑）→ 指纹相同。
4. 错误不同（例如 TypeError 与 RangeError）→ 指纹不同。
5. 异常类型相同，message 属性不同（'name' 与 'email'）→ 指纹不同。

测试 1-3 必须合并为同一个哈希；测试 4-5 必须生成不同的哈希。此处失败意味着规范化（步骤 1）将噪声带入了哈希，或剥离了稳定锚点——应先修复该问题，再调整聚类。聚类权重（0.30 / 0.25 / 0.25 / 0.10 / 0.10）之和必须为 1.00。

---

完成标准

• failures.json 中的每个故障都具有非 null 的 severity、component 和 category 字段。
• 上述 5 项指纹稳定性断言全部通过（测试 1-3 哈希相同，测试 4-5 哈希不同）。
• 重复项已合并或关联，且每项都指向规范工单的指纹标签。
• 每个 P0/P1 工单都已指定负责人。
• 已衡量并记录自动分类准确率（目标 > 85%；参见 qa-metrics）。

---

相关技能

• qa-metrics — 跟踪分诊准确率、重复率、平均分类时间和缺陷逃逸率。
• ci-cd-integration — 配置流水线，以便在测试失败时运行分诊、并行执行和生成报告。
• test-reliability — 针对单个不稳定定位器，在运行时进行逐测试修复和隔离。分诊负责分类故障；test-reliability 负责在线修复单项测试。
• observability-driven-testing — 方向相反：将生产遥测数据转化为新的测试设计。当生产环境错误应触发测试而非工单时，使用它。
• qa-project-context — 提升分类准确率的项目上下文：组件映射、已知问题和归属关系。
• ai-test-generation — 根据分诊后的缺陷报告生成回归测试。

---

参考文件（位于 references/ 中）

• pipeline-prompts-and-integration.md — LLM 分类与工单生成提示词（步骤 5-6）、完整的缺陷报告 Markdown 模板，以及跟踪工具集成代码（GitHub Issues、CI 工作流、Jira/Linear 说明）。
• classification-taxonomy.md — 缺陷类别、严重程度定义、组件映射规则和根因类别。
• ci-failure-analysis.md — CI 日志解析模式、故障类别决策树和指纹算法详情。