Flutter analyze-github-flake 技能详解从 GitHub Flaky 工单到 LUCI 构建日志的自动化归因【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter本文基于 Flutter 仓库中的 Agent 技能文档 .agents/skills/analyze-github-flake/SKILL.md完整讲解analyze-github-flake技能的工作流程如何用gh命令识别并解析 fluttergithubbot 自动创建的 flaky 工单如何从工单正文与评论中提取 LUCI 构建地址如何通过 Buildbucket prpc API 拉取失败构建的日志元数据并将多次失败归类为不同失败类型输出高层摘要。读完后你可以独立复现这一整套 CI 抖动flake分析流程并理解它与 docs/infra/Reducing-Test-Flakiness.md 中描述的 flaky 治理机制之间的衔接关系。1. 背景一个 Flaky 工单在 Flutter 仓库中的生命周期要理解这个技能为什么长这样先看它在整条 flaky 治理链路中的位置。根据 docs/infra/Reducing-Test-Flakiness.md每周Cocoon 中的自动化脚本会扫描过去 15 天的测试执行统计识别抖动最严重的测试当某个测试 builder 的Flaky Ratio ≥ 2%时脚本会若不存在自动创建跟踪工单默认指派给对应子团队 TL并打上P0标签如果该测试不是分片shard测试脚本还会更新 .ci.yaml 中对应条目标记为 flaky——具体做法是在bringup: true行上方加一行# TODO(username): github issue url。当前仓库的 .ci.yaml 共约 7800 行其中存在多处bringup: true条目如 L703、L739、L2707 等对应的就是正在 staging 环境观察或被标记的测试工单关闭后有 15 天宽限期若抖动持续会再次开单修复后的测试需连续 50 次运行无抖动才能从 .ci.yaml 中移除bringup: true重新启用。而自动创建的 flaky 工单由机器人fluttergithubbot提交会包含三类关键信息同一 commit 上近期 flake 的示例及其 LUCI 构建页链接、完整的 Flaky builds: 构建列表、以及 Flutter dashboard 上 Recent test runs 的过滤链接。analyze-github-flake技能的工作对象正是这类工单——它把工单 → 构建日志 → 失败归类摘要这一段高度重复的人工操作固化为可被 Agent 执行的标准化流程。该技能存放在 .agents/skills/analyze-github-flake/SKILL.md。Flutter 仓库对共享技能有统一规范见 .agents/skills/README.md技能作者拥有所有权、需遵循严格的结构化规则、One Skill Per CLI Tool每个 CLI 工具一个专用技能、以及在合适时指示 Agent 以只读模式访问真实数据以防意外变更——analyze-github-flake正是只读分析这一推荐实践的典型落地。2. 运行前提与三条硬规则SKILL.md 开头的宿主假设Host assumptions声明了执行环境要求已安装且在PATH中可用dart、git、ghGitHub CLIgh已完成认证配置。文档随后给出三条必须遵守的规则界定了这个技能做什么、不做什么不得修改任何文件——只针对某个具体 check 为什么 flaking 提供分析输出是分析报告而非代码改动只查看 issue 正文以及包含更多构建链接的评论不尝试解决 flake也不去 flutter/ 代码内部定位根因——只提供正在发生什么的高层摘要并把失败分桶bucket为若干不同类型。第 3 条尤其值得注意该技能的定位是分诊的第一公里收集证据、建立分类而非根因修复。这与 docs/infra/Reducing-Test-Flakiness.md 的分工一致——归类之后由 TL 接手 triage、重派与修复。3. 步骤一用 gh 拉取并验证 IssueGitHub issue 链接形如https://github.com/flutter/flutter/issues/issue-number其中issue-number是纯数字。技能要求从链接中取出编号执行SKILL.md L26gh issue view issue-number --repo flutter/flutter \ --jsonauthor,body,id,labels,number,state,title,url文档给出的实例是 issue174116gh issue view 174116 --repo flutter/flutter \ --jsonauthor,body,id,labels,number,state,title,url--json指定的字段覆盖了后续判断所需的全部元数据author判断是否机器人提交、body提取 flaky 构建列表、labels/title判断是否为 flaky 工单、state等。拿到数据后技能定义了一个短路short circuit条件只有同时满足以下两点才属于要分析的类型——Issue 由fluttergithubbot提交标题形如ci.yaml target is X% flaky例如标题中的 target 名对应 .ci.yaml 中定义的 check 目标。不满足时如果用户是直接点名要求调用该技能就告知用户这个 issue 不是 flake bot 开的否则技能是作为通用流程的一部分被触发的直接回到先前的工作不做分析。这里有个可以佐证的细节标题中的ci.yaml target就是 LUCI builder 所对应的 check 目标名。在当前仓库的 .ci.yaml 中确实定义了以Windows plugin_test为前缀的一族目标例如Windows plugin_test_android_variants约 L6674、Windows plugin_test_android_standard约 L6695等其task_name与目标名一一对应。技能示例里 URL 的 check_name 为Windows%20plugin_test即 URL 编码后的 Windows plugin_test正对应这一命名体系。4. 步骤二解析 Flaky builds: 并收集全部构建 URL对于通过验证的 flaky 工单信息分布在两处都要采集Issue 正文body标题包含 flaking check 的名称正文中紧跟Flaky builds:头之后每一行一个URL列出该 check 失败或抖动的所有构建实例评论comments找出所有login: fluttergithubbot的评论格式与正文相同——顶部是一个示例 flake 的链接其下紧跟 Flaky builds: 头与完整列表——同样提取其中的 URL。这意味着一个持续抖动的工单通常会有多轮机器人评论每一轮对应一批新的 flaky 构建技能要求把所有轮次的构建 URL 都收集进来才能形成完整的失败样本集。每条构建链接的格式为SKILL.md L38https://ci.chromium.org/ui/p/flutter/builders/bucket/check_name/buildNumber/overview以文档示例为例https://ci.chromium.org/ui/p/flutter/builders/prod/Windows%20plugin_test/16247/overview其中prod是bucketLUCI 构建桶与 .ci.yaml 中 staging/prod 双环境对应Windows%20plugin_test是check_nameURL 编码的空格即 check 目标名16247是buildNumber下一步拉取日志的关键参数。5. 步骤三调用 Buildbucket prpc API 拉取构建日志元数据对每个构建 URL取出其中的buildNumber执行如下 curl 请求SKILL.md L45-L63 原文命令将bucket、check_name、buildNumber替换为实际值curl https://cr-buildbucket.appspot.com/prpc/buildbucket.v2.Builds/GetBuild \ -H accept: application/json \ -H accept-language: en-US,en;q0.9,es;q0.8 \ -H cache-control: no-cache \ -H content-type: application/json \ -H origin: https://ci.chromium.org \ -H pragma: no-cache \ -H priority: u1, i \ -H referer: https://ci.chromium.org/ \ -H sec-ch-ua: Chromium;v146, Not-A.Brand;v24, Google Chrome;v146 \ -H sec-ch-ua-mobile: ?0 \ -H sec-ch-ua-platform: macOS \ -H sec-fetch-dest: empty \ -H sec-fetch-mode: cors \ -H sec-fetch-site: cross-site \ -H user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36 \ -H x-return-encrypted-headers: all \ --data-raw {builder:{project:flutter,bucket:bucket,builder:check_name},buildNumber:buildNumber,mask:{fields:id,builder,builderInfo,number,canceledBy,createdBy,createTime,startTime,endTime,cancelTime,status,statusDetails,summaryMarkdown,output,steps,tags,schedulingTimeout,executionTimeout,gracePeriod,ancestorIds,retriable}}命令结构要点请求目标是 Buildbucket 的buildbucket.v2.Builds/GetBuildprpc 端点即 LUCI 构建系统的构建查询接口builder对象由project: flutter、上一步解析出的bucket与builder即 check_name三个字段确定buildNumber是数字mask.fields显式声明了要返回的字段集其中最关键的是status/statusDetails构建终态与状态详情、summaryMarkdown构建摘要、output、steps各执行步骤含日志引用是判断失败发生位置的核心、tags构建标签、canceledBy/cancelTime是否被取消、executionTimeout执行超时信息等。这些字段恰好覆盖了区分测试失败、构建取消、超时等失败类型的判断所需请求头中的origin/referer/sec-fetch-*/user-agent组合是模拟浏览器端 ci.chromium.org 页面调用该接口时携带的上下文直接照抄即可复用。响应解析注意事项SKILL.md L65Buildbucket 的 prpc 响应开头会带一段)]}前缀这是防止 XSSI/JSONP 劫持的常见做法处理时应忽略这几个字符把剩余部分当作 JSON 解析。6. 步骤四逐条检查日志、按失败类型分桶、输出高层摘要技能的最后一步SKILL.md L67-L69检查日志内容以判定失败原因对 issue 中列出的每一个 URL 都执行上述拉取与检查收集每一次具体失败的日志然后按失败类型归类categorize形成一份高层摘要。结合技能的三条硬规则这一阶段的输出形态是一组互斥的失败类型桶例如某类断言失败、某类设备/环境问题、超时/取消等具体类别取决于实际日志每桶下挂对应的 flaky 构建清单外加一段正在发生什么的高层叙述——而不是修改flutter/内代码的修复方案。当归类摘要完成后后续的人工 triage 可以按 docs/infra/Reducing-Test-Flakiness.md 的建议继续深入这些建议与该技能的分类结果直接衔接区分基础设施问题与测试问题设备类问题如设备未找到、测试中途设备掉线、Xcode 缓存污染、瞬时网络问题往往从 stdout 难以判断应查看 LUCI 构建页失败步骤的execution details在日志底部找非零退出码定位失败的测试在test_stdout中搜ERROR:注意带冒号其上方会有RUNNING:Dart/Flutter 测试关注Failed assertion:shard 单测抖动则搜[E]标记找规律利用工单中 dashboard 的 Recent test runs 过滤链接验证部分而非全部失败是否同型、回找第一个红色构建及其 commit、对比成功运行检查测试顺序依赖、每日首次构建与 bot 每日重新置备的关系、是否集中在同一台 bot/设备上以判断硬件问题。7. 技能的校验与维护按 .agents/skills/README.md 的规范.agents/skills下的共享技能入库前必须满足作者实际使用过、明确面向 Flutter 贡献者、PR 中附带提示词与产出示例、命名符合规范、遵循开放技能标准。技能作者对其拥有所有权并负责审批修改。对analyze-github-flake这类技能的自动化校验可在dev/tools目录下执行# 检查技能尾随空白、绝对路径、相对路径有效性 dart run dart_skills_lint:cli --skills-directory ../../.agents/skills \ --check-trailing-whitespace --check-absolute-paths --check-relative-paths # 自动校验测试 dart test test/validate_skills_test.dart另有--fix预览可修复项dry run与--fix-apply自动应用可修复规则两个作者辅助参数。从源码结构看仓库内还配套有dev/tools/skills_lint.yaml等配置支撑这套 lint 流程。8. 流程速查步骤动作关键产物0环境自检dart、git、gh在 PATH 且gh已认证1gh issue view n --repo flutter/flutter --json...拉取元数据author/body/labels 等字段2校验fluttergithubbot 标题target is X% flaky否则短路确认是 flaky 工单3从 body 与各轮 bot 评论的 Flaky builds: 列表提取全部 URL构建 URL 集合4解析ci.chromium.orgURL 的bucket/check_name/buildNumber三元组参数5curl 调用GetBuildprpc忽略)]}前缀解析 JSON状态、steps、summaryMarkdown 等6逐条检查日志按失败类型分桶输出高层摘要分类报告只读不改代码整条链路完全只读从工单解析到日志归类技能不触碰仓库任何文件其产出为后续按 docs/infra/Reducing-Test-Flakiness.md 流程修复并更新 .ci.yaml 提供了证据基础。9. 延伸阅读仓库内路径技能本体.agents/skills/analyze-github-flake/SKILL.md技能体系规范与 lint 校验.agents/skills/README.mdFlaky 治理完整工作流预防、检测、triage、修复docs/infra/Reducing-Test-Flakiness.mdCI 目标与bringup: true标记定义.ci.yaml其他相关技能如失败日志解析.agents/skills/dart-log-failure-parser/SKILL.md【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考