CI 失败日志自动去重与分类：用确定性指纹聚类、LLM…

当需要把 CI 日志、测试框架输出或错误监控中的失败自动归一化、去重、分类并生成缺陷工单时使用。

适用场景

解决思路

1. 先检查 `.agents/qa-project-context.md`，复用其中已有的技术栈、组件映射和已知 flaky 区域，跳过已回答的问题；再澄清失败来源（CI 日志 / 测试框架输出 / 生产错误监控 / 人工报告）、工单目的地（Jira、Linear、GitHub Issues、Azure DevOps、Shortcut）及必填字段、去重范围（同一次运行 / 同一 sprint / 同一发布 / 全时段）、审批流程（自动创建+人工复核 / 建议后人工批准 / 自动关闭重复）、以及可用的历史数据（历史缺陷与解决记录、flaky 历史、组件归属映射）。
2. 遵循核心原则：确定性优先、LLM 其次；比较前先归一化；指纹锚定稳定元素；破坏性操作前需人工批准；分类用于驱动路由；持续跟踪分类准确率（低于 85% 需调优）。
3. 按 7 步流水线执行：1) 归一化 → 2) 提取稳定锚点 → 3) 对规范形式做哈希 → 4) 聚类近似重复 → 5) LLM 分类 → 6) LLM 生成工单 → 7) 人工审批。
4. Step 1 归一化：按顺序应用规则——去除 ANSI 颜色码 `\x1b\[[0-9;]*m`；时间戳替换为 `<TIMESTAMP>`；UUID 替换为 `<UUID>`；进程 ID 替换为 `pid=<PID>`；端口号替换为 `:<PORT>`；临时路径替换为 `<TMPPATH>`；内存地址替换为 `<ADDR>`；随机后缀替换为 `<RAND>`；request/trace/correlation ID 替换为 `<REQ_ID>`；折叠空白为单个空格。若运行在异构主机上，额外归一化绑定地址（如 `127.0.0.1` 与 `0.0.0.0`）。
5. Step 2 提取稳定锚点（按优先级）：异常类型、错误消息模板、前 3 个栈帧、测试名、URL 模式、HTTP 状态码、退出码、断言差异。提取时保留函数名但去掉行号；保留 URL 路径但去掉查询参数和路径中的 ID（如 `/api/orders/<ID>`）；保留错误消息结构但把动态值替换为占位符；测试文件和测试名保持原样。
6. Step 3 生成指纹：按类型字母序排序锚点；拼接 `exception_type + "|" + message_template + "|" + top_frames + "|" + test_name`；做 SHA-256 哈希；取前 16 个十六进制字符作为指纹。
7. Step 4 聚类近似重复：按维度加权打分——异常类型 0.30（精确匹配）、错误消息 0.25（Levenshtein 距离 < 消息长度 20%）、栈帧 0.25（前 5 帧 Jaccard 相似度 > 0.6）、组件/文件 0.10（同目录或模块）、测试名 0.10（同 describe 块或测试文件）。相似度 > 0.75 视为可能重复并建议合并；0.60–0.75 之间、新指纹首次出现、或已知间歇性问题的组件必须人工复核。
8. Step 5 LLM 分类：把异常、消息、前 5 个栈帧、测试名和 CI 上下文喂给 LLM，输出五个字段——失败类别（`test bug | application bug | environment issue | flaky test | build failure`）、严重级别（`critical | major | minor | trivial`）、组件（从栈和文件路径推断）、疑似根因（1–2 句假设）、置信度（`high | medium | low`，低置信度时说明还需哪些信息）。低置信度结果转人工复核。
9. Step 6 LLM 生成工单：基于分类结果、归一化错误、日志摘录和相关聚类指纹，生成标题（简洁可搜索、含组件名、< 80 字符）、描述（用平实语言说明发生了什么，不要贴原始日志）、复现步骤（从测试名和日志上下文推导）、证据（相关日志行、断言差异、截图）、建议标签 `[component, severity, failure-category, fingerprint]`、建议负责人（基于组件归属）。指纹必须写入工单的标签和 Fingerprint 字段，供后续去重匹配。
10. Step 7 人工审批：流水线只建议、人做决定。审批选项包括——创建工单（新失败、根因清晰、指派团队）、合并到已有工单（重复，补充证据）、隔离测试（flaky，非应用缺陷，安排调查）、重试并监控（环境问题，重试 CI，持续则告警）、驳回（已知问题已在待发布中修复，或测试缺陷有明显修复）。
11. 按严重级别/优先级矩阵决策：严重级别衡量影响（Critical=系统不可用/数据丢失/安全泄露/无绕过；Major=核心功能损坏/体验下降/有绕过；Minor=非核心功能受影响/有功能影响的视觉问题；Trivial=纯视觉）。优先级衡量紧迫度（P0=立即修复/阻塞发布或生产；P1=本 sprint；P2=下个 sprint；P3=待办）。按影响范围交叉映射：影响所有用户 → Critical/Major 为 P0、Minor 为 P1、Trivial 为 P2；影响 >10% 用户 → P0/P1/P2/P3；影响 <10% 用户 → P1/P1/P2/P3；仅边界情况 → P1/P2/P3/P3。
12. 使用统一的缺陷报告模板（自动或人工编写均适用）：包含缺陷标题、severity/priority/component/environment/fingerprint/reporter 元数据，以及 Description、Steps to Reproduce、Expected/Actual Behavior、Evidence、Frequency、Suggested Root Cause、Related Issues。
13. 按去重模式处理：精确重复（同指纹）→ 合并到已有工单并补充证据；近似重复（同聚类，相似度 > 0.75）→ 关联工单并建议人工复核合并；同根因不同症状（同异常类型 + 不同测试中重叠栈帧）→ 创建父工单关联各症状工单；已修复缺陷回归（指纹匹配已关闭工单）→ 重开工单、标记回归、提升优先级；flaky 复发（同指纹在多次 CI run 中间歇出现）→ 标记 flaky，出现率 > 10% 则隔离。
14. CI 失败分析关键判断：持续失败 = 测试缺陷或应用缺陷；间歇失败 = flaky 测试或环境问题；同时多处失败 = 环境或共享组件；构建失败 = 代码或依赖问题。
15. 集成时保持 tracker 无关：Step 6 产出的标题、描述、标签、严重级别、组件可映射到任意 tracker 字段；参考 `references/pipeline-prompts-and-integration.md` 中的 `gh issue create` / 指纹去重命令、GitHub Actions「失败即分诊」工作流，以及 Jira/Linear/Azure DevOps 的 REST/GraphQL 集成说明。
16. 实现前先评估买 vs 自建：Trunk Flaky Tests（指纹、聚类、严重级别路由、原生 PR 评论 + webhook、Agents 分诊、隔离工作流）、CloudBees Smart Tests（原 Launchable，指纹、ML 优先级、测试影响分析）、Datadog Test Optimization（Flaky Test Management、Auto Retries、Early Flake Detection、Failed Test Replay、测试影响分析，Bits AI Dev Agent 可自动生成修复 PR，Flaky Test Policies 30 天后自动隔离再禁用）、Sealights（质量智能与测试影响门禁，面向受监管行业）。仅在需要本地/气隙部署、tracker 集成特殊、或需要合规的 AI 提示审计轨迹时自建。
17. 模型选择控制成本：Step 5 分类用 Sonnet 4.6 / Haiku 4.5 即可；仅当聚类新颖、失败模糊或根因置信度低时才升级到 Opus 4.8。
18. 避免反模式：不要用 LLM 做去重（非确定性）；不要未经复核自动关闭工单；不要过度定级（什么都 critical 等于没有 critical）；不要把环境失败都标为应用缺陷；不要没有反馈闭环（跟踪自动分类准确率、误判重复率、开发者对工单质量的评分）；不要在工单里贴原始日志（归一化后只保留 5–10 行关键行）；不要不做归一化就指纹化（原始日志哈希每次运行都变，去重永不触发）；不要缺少组件归属映射（分类不路由等于无用）。
19. 验证指纹器（承重部件）：跑 5 条稳定性断言——1) 同错误不同时间戳 → 同指纹；2) 同错误不同 PID 和端口 → 同指纹；3) 同错误不同行号（代码已改）→ 同指纹；4) 不同错误（如 `TypeError` vs `RangeError`）→ 不同指纹；5) 同异常类型不同消息属性（`'name'` vs `'email'`）→ 不同指纹。测试 1–3 必须收敛为同一哈希，测试 4–5 必须产生不同哈希；失败说明 Step 1 归一化泄漏噪声或剥掉了稳定锚点，先修这个再调聚类。聚类权重 0.30/0.25/0.25/0.10/0.10 必须和为 1.00。
20. 完成标准：`failures.json` 中每个失败的 `severity`、`component`、`category` 字段均非空；5 条指纹稳定性断言通过；重复项已合并或关联，且都指向规范工单的指纹标签；每个 P0/P1 工单都有负责人；自动分类准确率已测量并记录（目标 > 85%）。

适用边界 · 注意事项

• 不适用于单个 flaky locator 的运行时自愈——那属于 test-reliability。
• 不适用于从生产遥测设计新测试——那属于 observability-driven-testing。
• 不适用于需要本地/气隙部署、特殊 tracker 集成或合规 AI 提示审计轨迹之外的场景——这些情况下通常买现成平台比自建更便宜。