AgentSkillsCN

buildbuddy-invocation-compare

比较两个 BuildBuddy 调用 URL 或 ID，以排查一致性/可重复性问题以及缓存失效情况。当被要求对比标准 Bazel 标志、查找首次出现的共享操作缓存缺失、检查 Action/ActionResult 的差异（输入/命令/环境/平台/输出），或使用 `bb explain` 分析紧凑的执行日志时，可使用此技能。

SKILL.md
--- frontmatter
name: buildbuddy-invocation-compare
description: Compare two BuildBuddy invocation URLs or IDs to troubleshoot hermeticity/reproducibility and cache invalidation. Use when asked to diff canonical Bazel flags, find the first shared action-cache misses, inspect Action/ActionResult differences (inputs/command/env/platform/outputs), or analyze compact execution logs with `bb explain`.
metadata:
  short-description: Compare two BuildBuddy invocations and pinpoint cache/action differences.

BuildBuddy Invocation Compare

Overview

Compare two invocations end-to-end to isolate the earliest shared action-cache miss and pinpoint why actions are rebuilt or produce divergent outputs.

Workflow

0) Preflight: auth + inputs

  • •Extract invocation IDs from the URLs.
  • •Confirm API base URL and API key presence without printing the key.
  • •Create a temp working directory and cache API responses there.
  • •Use the request templates in references/requests.md.

1) Diff canonical flags

  • •Call GetInvocation for both IDs.
  • •Extract the canonical command line (structuredCommandLine.commandLineLabel matching canonical).
  • •Sort flags and diff; highlight any differences in startup or command options.
  • •If canonical is missing, fall back to the only structured command line and note the limitation.
  • •Some entries may have commandLineLabel=null; filter them out to avoid jq errors.

2) Find the first shared AC miss

  • •Call GetCacheScoreCard for both invocations filtered to:
    • •cache_type=AC, request_type=READ, response_type=NOT_FOUND
    • •ordered by start_time ascending
  • •Use scripts/find_first_shared_ac_miss.py to identify the earliest shared {target, mnemonic} with AC misses on both sides.
  • •Record target_id, action_mnemonic, and action_id from each side for the next step.

3) Locate the rerun action(s)

  • •Call GetExecution with inline_execute_response=true for each invocation.
  • •Filter executions by target label, mnemonic, and primary output path (if known) to disambiguate actions.
  • •Capture:
    • •action_digest (Action proto in CAS)
    • •action_result_digest or execute_response.result (ActionResult)
    • •execute_response.result (stdout/stderr/output digests)
    • •primary_output_path to ensure you are comparing the correct action

4) Diff Action and ActionResult

Fetch protos via bazel run //tools/cas and compare with diff -u or jq.

Focus on these common divergence points:

  • •Input root tree: Compare Action.input_root_digest; if it differs, fetch both trees and identify differing file paths/digests. If only a few files differ, download and diff them.
  • •Command args / outputs: Compare Command.arguments, Command.output_files, and Command.output_directories. Expect platform or toolchain mismatches to surface here.
  • •Env / platform properties: Compare Command.environment_variables and Action.platform.properties. Treat differences as evidence of non-strict env or platform drift.
  • •Output digests: Compare ActionResult.output_files and output_directories; if digests differ with identical inputs/commands, suspect non-determinism.

Prefer bb explain when input roots differ and compact execution logs are available to pinpoint exact input changes.

5) Compact execution logs (optional)

  • •If execution_log.binpb.zst appears in the build tool logs, download both logs and diff with bb explain.
  • •Alternatively, pass invocation IDs directly to bb explain when the logs are available in BES.

Response requirements

  • •Summarize the root cause clearly and tie it to the earliest shared AC miss.
  • •Call out which of the divergence categories applies (inputs, command/outputs, env/platform, output digest).
  • •Include a pointer to the compare UI sources: app/compare/compare_actions.tsx or app/compare/compare_invocations.tsx for deeper inspection.

Resources

  • •references/requests.md for API + jq templates.
  • •scripts/find_first_shared_ac_miss.py to identify the earliest shared AC miss.