unblock-pr

解除 PR 阻塞

一句话概述：调查 PR CI 流水线失败——将每项失败归类为不稳定、基础设施问题或回归，并提出有针对性的处理措施。

需要：dd-pup 技能（已安装并完成身份验证的 pup CLI）、triage-flaky-test 技能（用于深入调查不稳定失败）。

---

后端

检测——每次调用开始时，在采取任何操作前，确定要使用的后端：

1. 如果用户在任何位置传入了 --backend pup → 立即使用 pup 模式。跳过步骤 2–4。
2. 检查可用工具中是否包含 search_datadog_ci_pipeline_events。
3. 如果包含 → 全程使用 MCP 模式。严格按照此技能工作流各部分中的工具名称调用工具。
4. 如果不包含 → 检查 pup 是否可执行：通过 Bash 运行 pup --version。如果命令成功退出（退出代码为 0），则 pup 可用。
5. 如果 pup 有响应 → 全程使用 pup 模式。使用此文件底部的工具参考附录转换每个工具调用。
6. 如果两者都不可用 → 停止并告知用户：

   "Datadog MCP 服务和 pup CLI 均不可用。请连接 MCP 服务或安装 pup（brew install datadog-labs/pack/pup）。"

pup 调用规则：

• 通过 Bash 调用。pup 始终输出 JSON——直接解析。
• 传给 pup 的仓库 ID 必须全为小写（API 不接受大小写混用）：github.com/datadog/my-repo，而非 github.com/DataDog/my-repo。
• 如果 pup 返回 401/403，告知用户运行 pup auth refresh 或 pup auth login。

---

输入

参数	说明
PR 分支	正在调查的分支（例如 my-feature-branch）
仓库	不含 schema 的小写 URL（例如 github.com/org/repo）。如果未提供，则通过 git remote get-url origin 获取。

---

工作流

步骤 0 — 解析输入

如果未提供仓库 ID 和默认分支，则从 git 获取：

# Repository ID: fully lowercase, no-schema URL (the API rejects mixed-case)
git remote get-url origin
# Strip protocol and trailing .git, then lowercase the result
# e.g. https://github.com/DataDog/my-repo.git → github.com/datadog/my-repo

# Default branch
git symbolic-ref refs/remotes/origin/HEAD
# Strip refs/remotes/origin/ prefix — fall back to main if unset

步骤 1 — 获取 PR CI 摘要（并行运行）

流水线失败：

Tool: search_datadog_ci_pipeline_events
query: @ci.status:error @git.branch:<branch> @git.repository.id_v2:"<repo>"
ci_level: job
from: now-24h

测试失败（仅当流水线结果包含测试运行器任务时）：

Tool: search_datadog_test_events
query: @test.status:fail @git.branch:<branch> @git.repository.id_v2:"<repo>"
from: now-24h
test_level: test

并行运行两项检查。收集测试事件结果中所有不同的 @test.service 值。如果发现多个不同的服务，则在分类摘要中分别注明；不要将其合并为单个服务筛选条件。如果流水线结果仅包含基础设施任务类型（build、lint、deploy），且没有测试运行器输出，则丢弃测试结果并跳至步骤 3。

步骤 1.5 — 获取 PR 健康状况（与步骤 1 并行运行）

此步骤始终运行——无论 CI 是红还是绿，PR 健康状况信息都很有价值。

代码覆盖率（两种模式均适用）：

Tool: get_datadog_code_coverage_branch_summary
repository_id: <repo>
branch: <branch>

解析 PR 编号（仅限 MCP 模式——如果输入中已提供 PR 编号，则跳过）：

Tool: get_prs_by_head_branch
repo_url: https://<repo>
head_branch: <branch>

使用返回的第一个未关闭 PR。如果没有找到未关闭的 PR，则跳过质量/安全信息获取，并将质量和安全状态报告为“无可用数据”。

代码质量和安全（仅限 MCP 模式——仅在有 PR 编号时执行）：

Tool: search_pr_insights
repo_url: https://<repo>
pr_number: <pr_number>

仅从 products_status 中提取 code_quality 和 code_security。忽略 failed_tests、flaky_tests 和 failed_jobs——CI 数据来自步骤 1–3。

pup 模式说明： pup 不支持 PR 编号解析和 search_pr_insights。在 pup 模式下，质量和安全状态始终显示“无可用数据”。

步骤 2 — 对每个失败任务执行归因检查

首先检查步骤 1 中任务事件的 @error_classification.domain / @error_classification.type 是否存在——如果已填充，则将其作为主要分类信号。

对于仍需分类的每个失败任务，并行运行以下两项检查：

默认分支检查——此任务在此 PR 之前是否已经失败？

Tool: aggregate_datadog_ci_pipeline_events
query: @ci.status:error @ci.job.name:"<job>" @git.branch:<default-branch> @git.repository.id_v2:"<repo>"
ci_level: job
aggregation: count
from: now-24h

影响范围检查——此任务在其他分支上也失败吗？

Tool: aggregate_datadog_ci_pipeline_events
query: @ci.status:error @ci.job.name:"<job>" @git.repository.id_v2:"<repo>"
ci_level: job
aggregation: count
group_by: ["@git.branch"]
from: now-24h

性能回退方案：如果影响范围查询耗时过长或超时，则跳过此项，仅依据默认分支检查。

第 3 步 — 对每项失败进行分类

优先级顺序：

1. 如果存在 @error_classification.domain / @error_classification.type → 将其作为主要信号
2. 如果测试失败，且该测试在 get_datadog_flaky_tests 中的 flaky_test_state:active → flaky
3. 使用 blame 守卫结果：

默认分支上是否失败？	是否在 ≥3 个其他分支上失败？	分类
是	是	infra（已有问题，影响广泛）
是	否	infra（默认分支上已有问题）
否	否	regression（由此 PR 引入）
否	是	flaky（间歇性问题，跨分支出现）
数据不足	—	unknown

第 4 步 — 生成问题分诊简报

每个失败的作业占一项：

PR CI Triage Brief
==================
Branch:   <branch>
Repo:     <repo>

Job: <job-name>
  Classification:  <flaky | infra | regression | unknown>
  Evidence:        <1 key data point — error message, pipeline count, or test result>
  Confidence:      <high | medium | low>
  Recommended:     <action>

[repeat for each failing job]

Overall: <N> failures — <e.g. "1 regression, 1 flaky, 1 infra">

PR Health
=========
Coverage:   <X>% on <branch> | No data available
Quality:    <N violations (X high, Y medium)> | No violations | No data available
Security:   <N violations> | No violations | No data available

始终显示全部三行。工具未返回数据或不可用时（Quality/Security 的 pup 模式），使用“No data available”。

第 5 步 — 提出后续操作

regression → 提示用户检查其代码更改。没有可用的写入操作。

flaky → 加载 triage-flaky-test 技能进行深入调查。对于每个被分类为 flaky 的不同失败测试名称，调用一次该技能，并将 STEP 1 结果中的测试名称（来自 @test.name）和推导出的仓库作为输入。该技能将：

• 尝试结合 flaky_category + 堆栈跟踪进行 Agent 原生修复
• 如果无法快速修复，则通过 update_datadog_flaky_test_states 提议隔离测试

infra → 提议重试前，先评估失败是否为暂时性：

• 检查 @error_classification.type 和错误消息中是否存在 timeout、runner unavailable、network error、quota exceeded 等信号——这类暂时性失败通常可通过重试解决
• 如果错误具有确定性（构建配置错误、缺少密钥、明确的测试断言失败），重试不太可能有帮助——建议调查根本原因
• 如果默认分支上已有该失败，告知用户——重试很可能再次失败；应等待上游修复

如果是暂时性失败：

MCP 模式 — GitHub Actions： 使用 retry_datadog_ci_job。从失败的作业事件中收集：

• @ci.provider.name → ci_provider（"github"）
• @git.repository.id_v2 → repository_id
• @ci.job.id → job_id
• 事件的 id 字段 → event_uuid（可选）

对于 pipeline_id：如果 @ci.pipeline.id 匹配 ^\d+-[1-9]\d*$（例如 26027867390-1），则直接使用。如果它是纯数字运行 ID，则将其与同一事件中的 @github.run_attempt 组合："{@ci.pipeline.id}-{@github.run_attempt}"。备用方法：解析 @ci.pipeline.url——从 runs/{run_id}/attempts/{attempt} 中提取 {run_id} 和 {attempt}。

重试返回后，通过 search_datadog_ci_pipeline_events（query: @ci.job.name:"<job>" @git.branch:<branch>，from: now-5m）确认是否出现新运行。

备用模式 / pup 模式 — GitHub Actions： 从 @ci.pipeline.url 中提取运行 ID：

gh run rerun <run_id> --failed

GitLab / 其他提供商（两种模式）：分享 @ci.pipeline.url，并引导用户前往提供商 UI。

unknown → 建议通过 CI 提供商 UI 或流水线事件中的 @ci.pipeline.url 查看原始作业日志。

工具参考

本附录仅适用于 pup 模式。在 MCP 模式下，请直接使用工作流部分中的工具名称。

MCP 工具	pup 命令
search_datadog_ci_pipeline_events (ci_level: job)	pup cicd events search --query "..." --level job --from 24h --limit 50
aggregate_datadog_ci_pipeline_events (count, group_by branch)	pup cicd events aggregate --query "..." --compute count --group-by "@git.branch" --from 24h
aggregate_datadog_ci_pipeline_events (count, no group_by)	pup cicd events aggregate --query "..." --compute count --from 24h
search_datadog_test_events	pup cicd tests search --query "..." --from 24h --limit 50
get_datadog_flaky_tests	pup cicd flaky-tests search --query "flaky_test_state:active ..."
update_datadog_flaky_test_states	将请求正文写入 /tmp/flaky-update.json，然后运行 pup test-optimization flaky-tests update --file /tmp/flaky-update.json
get_datadog_code_coverage_branch_summary	repo_lower=$(echo "<repo>" | tr '[:upper:]' '[:lower:]') && pup code-coverage branch-summary --repo "$repo_lower" --branch "<branch>"
get_prs_by_head_branch	pup 中不可用 — 跳过；针对质量/安全报告“No data available”
search_pr_insights	pup 中不可用 — 跳过；针对质量/安全报告“No data available”
retry_datadog_ci_job	pup 中不可用 — 改用 gh run rerun <run_id> --failed