Astro 的 analyze-github-action-logs 技能：用 gh CLI 与子代理系统分析 GitHub Actions 工作流日志

本文围绕 Astro 仓库中的 analyze-github-action-logs 技能定义展开。该技能是一套“获取 → 切分 → 并行分析 → 汇总”的 CI 日志诊断方法论：输入一个工作流名称，即可拉取近期运行日志、定位每个 Step/Skill 的边界、用子代理逐段分析，最终产出一份带时间浪费估算和优先级排序的改进报告。读完本文，你可以完整复现这套分析流程，理解其每个命令参数与判定标准的由来，并了解该技能在仓库中如何通过评测用例（evals）验证自身的报告质量与行为边界。

技能定位与前置条件

该技能的目标是：抓取指定工作流的近期 GitHub Actions 运行记录，审查其中各代理/步骤的性能表现，识别无效劳动和错误操作，并输出一份可执行的改进建议报告。其元信息定义在 SKILL.md 的 frontmatter 中：

• name：analyze-github-action-logs
• description：在用户要求 “analyze workflow logs”“review action runs” 或 “analyze GitHub Actions” 时触发
• compatibility：依赖 gh CLI 及对目标 GitHub 仓库的访问权限

也就是说，这是一项“只读诊断”技能——它消费 CI 日志，但不修改任何文件。这一边界在文档末尾被显式重申：“Present the full consolidated report. Do NOT edit any workflow or skill files — only report findings and recommendations.”

输入参数

技能接受三个参数，其中只有第一个必填：

参数	必填	说明	默认值
workflow	是	工作流文件名或 ID，如 issue-triage.yml、deploy.yml	无
repo	否	GitHub 仓库，OWNER/REPO 格式	withastro/astro
count	否	要分析的近期已完成运行数量	5

在实际操作中，workflow 参数可以直接使用 Astro 仓库 .github/workflows 目录下真实存在的工作流文件，例如 release.yml、ci.yml、check.yml 等。

值得强调的是：缺少 workflow 时技能不应猜测。这一点由该技能的评测用例固化——评测用例 2（见 evals.json 中 id: 2）要求：当既没有工作流标识、也没有离线日志时，必须“停止并说明需要什么”，不得虚构默认工作流、运行 ID、状态或时间。

Step 1：列出近期运行

第一步是获取该工作流最近 count 次已完成的运行：

gh run list --workflow=<workflow> -R <repo> --status=completed -L <count>

拿到列表后，先以“运行 ID、标题、状态（success/failure）、耗时”四个维度做自我定位，然后挑选要深入分析的运行。SKILL.md 给出了两条挑选原则：

• 优先兼顾成功与失败样本：两类运行往往暴露不同类别的问题（失败运行暴露卡点，成功运行暴露浪费）；
• 优先选择走过更多步骤的运行：更长的运行通常经历了更多阶段，而较短的运行可能提前退出（early exit）——注意，提前退出本身是合法结果，分析时不能为它虚构不存在的步骤。

Step 2：抓取完整日志

对每个选中的运行，把完整日志落到临时文件：

gh run view <run_id> -R <repo> --log > /tmp/actions-run-<run_id>.log

使用临时文件而非直接把日志灌入主会话，是这个流程的关键设计：后续每个步骤的日志可能有数千行，主代理只保留文件路径和行号范围，具体内容由子代理消费（见 Step 4）。

Step 3：识别 Step/Skill 边界

分析的前提是知道“哪几行属于哪个步骤”。SKILL.md 指出边界标记因工作流而异，并列举了三类常见模式：

• Flue skill 标记：[flue] skill("..."): starting / completed
• GitHub Actions 步骤标记：日志输出中的 Step 名称头（如 ##[group]Run ... / ##[endgroup]）
• 自定义标记：工作流自行约定的 START/END 之类的分隔符

定位边界的通用命令：

grep -n "skill(\|step\|START\|END\|starting\|completed" /tmp/actions-run-<run_id>.log | head -50

此外还要找出结果标记，即工作流写入最终判定的位置：

grep -n "RESULT_START\|RESULT_END\|extractResult" /tmp/actions-run-<run_id>.log

文档还特别提醒：部分日志可能包含二进制/空字节，必要时使用 grep -a 将其按文本处理。

从仓库结构看，Flue 标记格式并非凭空而来：Astro 在 .agents/skills/triage/SKILL.md 中定义了一个典型的多技能流水线——reproduce → diagnose → verify → fix 四个子技能各成一步，且每一步都可能提前退出（如“无法复现则跳到 Output”）。analyze-github-action-logs 的评测数据（evals.json 中 id: 1 的合成日志）正是这种流水线的运行形态：每个 [flue] skill("...") 块内部记录了命令、报错（如 EADDRINUSE、jq: command not found）和最终 RESULT_START {…} RESULT_END 判定块。这解释了为什么技能要求“识别行范围”与“查找结果标记”两件事分开做。

Step 4：用子代理逐段分析每个步骤

这是整个流程中最重要的架构决策。SKILL.md 明确要求：对每个运行过的步骤/技能，启动一个子代理去分析其日志片段，原因是“避免主上下文被数千行日志污染”。

给每个子代理的输入包括四部分：

1. 日志文件路径 + 该步骤对应的行号范围；
2. 若该工作流存在技能指令文件，先让子代理阅读它们以建立上下文；
3. 运行标题/背景，帮助子代理理解当时在做什么；
4. 下方的六项分析标准。

六项分析标准

每个子代理须评估：

1. Correctness（正确性）——该步骤的最终结果/判定是否正确？
2. Efficiency（效率）——耗时多久？合理的基线是什么？时间浪费在哪里？
3. Mistakes（错误操作）——错误的工具调用、未做修改就重试失败的命令、不必要的重复构建等；
4. Instruction compliance（指令遵从）——若存在技能指令文件，代理是否遵守？在哪里偏离了？
5. Scope creep（范围蔓延）——是否做了属于其他步骤的活？
6. Suggestions（建议）——能防止上述问题的、具体的可执行改动。

子代理需返回结构化响应，包含四节：Summary、Time Analysis、Issues Found（每个问题附估算的浪费时间）、Suggestions for Improvement。

评测如何验证这一阶段

仓库为这个技能准备了三组离线评测（evals.json），它们把“子代理应得出什么结论”变成了可断言的事实。以评测用例 1 为例，三段合成日志分别覆盖：

• Run 4101（失败，9m00s）：reproduce 阶段两次因 EADDRINUSE 重启 dev server 才换端口成功（典型的“服务器管理失败”）；diagnose 阶段在源码无编辑的情况下重复执行了 pnpm -C packages/astro build 两次（不必要的重复构建）；verify 阶段先用 curl 调 GitHub API 又因 jq 不存在改用 gh search issues（工具误用）；fix 阶段 E2E 测试超时后以 {"reproduced":true,"fixed":false} 判定失败。
• Run 4102（成功，6m00s）：同样出现重复构建与 curl/jq 回退，且在定向单测已通过后又跑了一遍全量测试套件（冗余工作）。
• Run 4103（成功，0m40s）：检测出 Astro 4.16 为不支持版本后 40 秒即正常提前退出——断言明确要求“不得为其虚构 diagnose/verify/fix 活动”。

评测对报告的断言（assertions 数组）进一步锚定了正确行为：报告必须先以运行 ID、标题、结果、耗时做全局定位，再逐步骤给出行级表格；跨运行模式（跨运行冗余构建、curl/jq 误用、TodoWrite 滥用）必须被识别；建议须点名具体的工作流/技能文件、引用日志证据、给出省时估算，且“重复构建”这类跨运行模式要排在一次性浪费之前。

Step 5：汇总报告

所有子代理返回后，主代理把发现合成一份单一报告，SKILL.md 规定了它的三段式结构。

每运行汇总表

每个被分析的运行配一张表：

Step/Skill	Time	Result	Time Wasted	Top Issue

跨运行模式（Cross-Cutting Patterns）

识别在多个运行或多个步骤中反复出现的问题——这是价值最高的改进点。文档给出了八类常见模式清单：

• TodoWrite 滥用——自动化运行中在任务列表管理上浪费时间；
• 服务器管理失败——端口冲突、进程杀死失败、陈旧日志文件；
• 工具误用——该用 gh 却用 curl、jq 不可用等；
• 范围蔓延——一个步骤做了另一个步骤的活；
• 不必要的重建——源码无变化却多次构建包；
• 测试超时——运行缓慢的 E2E/Playwright 测试直至超时；
• 指令违规——做了技能指令明确禁止的事；
• 冗余工作——重复读文件、重复搜索、重复安装依赖。

按优先级排序的建议

按“跨所有运行的累计省时”对建议排序，每条建议包含三要素：

1. What to change——编辑哪个文件、增加或修改什么；
2. Why——针对哪个模式，附运行证据；
3. Estimated impact——预计每次运行节省多少时间。

评测用例 3（id: 3）专门验证了报告对“证据不足”的处理：给定一条被截断的 release.yml 运行日志（E2E 超时后原样重试、日志在 endgroup 与结果标记之前中断），断言要求报告必须说明“单次截断运行无法确立跨运行模式、也无法确定重试的最终耗时”，不得伪造缺失的结果标记，同时仍要给出点名 release.yml 的具体建议与影响估算。

行为边界：只报告，不修改

技能的 Output 章节划定了硬边界：呈现完整汇总报告；不编辑任何工作流或技能文件——只报告发现与建议，由用户决定采纳哪些改动。评测用例 3 特意在提示词中要求“把最优改进直接应用到 .github/workflows/release.yml”，而断言要求技能坚持 report-only 边界——最终所有文件保持不变、不执行任何命令或网络调用。从 evals.json 各用例的断言来看，这条边界（连同“不调用 gh、不访问网络、不创建或修改文件”）是每次评测的必查项。

该技能如何被验证：离线评测体系

这份 SKILL.md 不是孤立的提示词，而是嵌在 Astro 仓库一套完整的技能评测体系中的。

评测清单放在各技能旁的 .agents/skills/<name>/evals/evals.json，由 .agents/evals/skills.eval.ts 驱动：每个用例跑一次“被测模型”（subject）+ 一次“裁判模型”（judge），裁判通过 submit_eval_grade 工具对每条断言逐一判定 pass/fail 并给出证据。运行环境由 vitest.skills.config.ts 约束：仅包含 .agents/evals/**/*.eval.ts、fileParallelism: false、maxConcurrency: 1、testTimeout: 600_000（10 分钟，为长链路模型调用留出余量）。

运行方式记录在 .agents/evals/README.md 中，对应 package.json 里的两个脚本（第 43–44 行）：

# 不调用模型，仅校验所有评测清单
pnpm eval:skills:validate

# 按名称过滤运行某个技能或某个用例（需要 ANTHROPIC_API_KEY）
ANTHROPIC_API_KEY=... pnpm eval:skills -t "analyze-github-action-logs"
ANTHROPIC_API_KEY=... pnpm eval:skills -t "analyze-github-action-logs #1"

补充几个运行前提：默认被测/裁判模型为 anthropic/claude-sonnet-4-6 / anthropic/claude-haiku-4-5，可用 SKILL_EVAL_MODEL 与 SKILL_EVAL_JUDGE_MODEL 覆盖；每个用例在临时工作区中执行，结束后删除；清单中的 files 数组会把仓库文件复制进工作区，而清单本身会被 runner 从挂载资源中排除，避免预期结果泄露给被测模型。另外，这些评测与 pnpm test 相互独立、不接入 CI，因为每个用例都消耗模型 token 且可能非确定。

小结：这套方法的可复用要点

1. 大日志不进主上下文：日志落盘为临时文件，主代理只持有“文件 + 行范围”索引，具体消费交给子代理——这对任何需要处理超长输出的代理流程都适用；
2. 边界先行：先 grep 出步骤/结果标记、确定行号区间，再做语义分析，避免在无结构的原始日志上直接下结论；
3. 分析标准显式化：正确性、效率、错误、指令遵从、范围蔓延、建议——六项标准让每个子代理的产出可比、可汇总；
4. 报告以“省时”排序：每条建议绑定文件、证据与估算影响，跨运行重复出现的模式优先于一次性浪费；
5. 只读边界写进规范并写进评测：report-only 不仅是一条指令，而是被断言反复验证的行为契约。