argos-pr-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Argos PR Review

Argos PR评审

Argos is a visual testing platform: each CI build captures screenshots and compares them to a baseline, producing per-snapshot diffs. A build with

changes-detected

is waiting for a human (or you) to decide whether each change is intentional, a regression, or a flaky capture.

Treat the Argos build as one input to the PR review, never the sole source of truth. Infer the intended UI change from the PR title, description, linked issue, and code diff first, then use Argos to confirm the rendered result matches.

Argos 是一个视觉测试平台：每次CI构建都会捕获截图，并将其与基线版本对比，生成每个快照的差异（diffs）。标记为

changes-detected

的构建需要人工（或你）判断每个变化是有意修改、回归问题，还是不稳定的捕获结果。

请将Argos构建作为PR评审的参考依据之一，而非唯一判断标准。首先从PR标题、描述、关联的问题以及代码差异中推断预期的UI变更，再通过Argos确认渲染结果是否符合预期。

Tooling & auth

工具与认证

Drive Argos through the

argos

CLI — load the argos-cli skill for the token model and flags. In short:

build get

build snapshots

need a project token (

ARGOS_TOKEN

--token

); submitting a review or comment needs a personal access token (

--token

argos login

). Always use

--json

when parsing, and never print token values. If no PAT is available, give the user your conclusion and evidence instead of posting — the CLI can't submit the review.

通过

argos

CLI操作Argos —— 加载argos-cli技能以获取令牌模型和参数。简而言之：

build get

build snapshots

需要项目令牌（

ARGOS_TOKEN

--token

）；提交评审或评论需要个人访问令牌（personal access token，PAT）（

--token

argos login

）。解析时务必使用

--json

参数，且绝不要打印令牌值。如果没有可用的PAT，请向用户提供你的结论和证据，而非尝试提交 —— CLI无法在无PAT的情况下提交评审。

Workflow

工作流程

Inspect the build —

argos build get <ref> --json

. Decide from status:

Status	Meaning / next step
`accepted` / `no-changes`	Already approved / no visual diff — no review needed
`pending` / `progress`	Not ready — stop and report it can't be reviewed yet
`changes-detected`	Needs a decision — fetch snapshots
`rejected` / `error` / `aborted` / `expired`	Don't approve until the cause is understood

Fetch what changed —
```
argos build snapshots <ref> --needs-review --json
```
. For each diff inspect
```
url
```
(diff mask),
```
base.url
```
(before),
```
head.url
```
(after), and
```
head.metadata
```
, plus the flakiness signals
```
test.metrics
```
and, on a change,
```
change.occurrences
```
/
```
change.ignored
```
(used in step 3).
Judge each diff against the inferred intent:
- Intentional — matches the code change and renders cleanly.
- Regression — broken layout/overlap, clipping, wrong state/theme/route, missing content, or a removed snapshot with no matching test removal.
- Flaky — weigh two independent signals; when they agree, call it flaky with confidence:
  - Test history —
```
test.metrics.flakiness
```
    (0 stable → 1 flaky) and
```
change.occurrences
```
    (how many times this exact diff has recurred over the metrics period). A high flakiness score or a recurring change is strong evidence the diff is environmental noise, not this PR's work;
```
stability
```
    (builds without a change),
```
consistency
```
    (do changes repeat identically), and
```
uniqueChanges
```
    explain why it scores that way.
```
change.ignored: true
```
    is already known-flaky and auto-approved — never read it as a regression.
  - This capture — a spinner/skeleton, async content not yet loaded, mid-animation, drifting dynamic values,
```
head.metadata.test.retry > 0
```
    , or identical
```
score
```
    /
```
head.url
```
    across browsers (both captured the same transient state).
```
retries
```
    (the configured budget) is not itself a signal.
  Conversely, a stable test (
```
flakiness
```
  →0, high
```
stability
```
  , a first-time change) that changed is more likely intentional or a real regression — don't dismiss it as flaky on the visuals alone. Tune the window with
```
build snapshots --metrics-period <24h|3d|7d|30d|90d>
```
  (default
```
7d
```
  ).
Comment on specific diffs — the highest-value output of an agent review. A binary approve/reject is cheap; specific, anchored feedback is what makes an agent review worth reading. For each problem diff, post a comment that names what's wrong and how to fix it, anchored to that snapshot:
bash
```
argos comment create <ref> --token <pat> --diff <screenshotDiffId> \
  --body "Loader still visible — capture runs before data loads. Wait for settled content (or mark the loader aria-busy)."
```
- ```
<screenshotDiffId>
```
  is the diff
```
id
```
  from
```
build snapshots --json
```
  .
- Pin to a region with
```
--anchor-lines <from,to>
```
  or
```
--anchor-point <x,y>
```
  (normalized 0–1); reply in a thread with
```
--reply-to <commentId>
```
  .
- Use
```
--draft
```
  to bundle comments into your pending review, then submit them together in the next step.
Submit the review (or report if no PAT is available):
- Approve:
```
argos review create <ref> --token <pat> --event approve
```
- Request changes:
```
argos review create <ref> --token <pat> --event reject --body "<summary>"
```
- Neutral note only:
```
--event comment --body "<summary>"
```
- Add
```
--project owner/project
```
  for build-number refs (not URLs).
- Silence a confirmed recurring flake so it stops blocking future builds:
```
argos change ignore <change.id> --token <pat> --project owner/project
```
  (reverse with
```
change unignore
```
  ). Only ignore flakes the metrics confirm — never to bypass a real diff; prefer a code fix (references/flaky-fixes.md) when one exists.
- Lead with the inferred intent, the snapshots reviewed, and the evidence. In the PR, cite the build URL and affected snapshot names; for flakes, name the signal and recommend a fix.

检查构建状态 —— 执行

argos build get <ref> --json

。根据状态决定下一步：

状态	含义 / 下一步操作
`accepted` / `no-changes`	已批准 / 无视觉差异 —— 无需评审
`pending` / `progress`	未就绪 —— 停止操作并告知当前无法评审
`changes-detected`	需要决策 —— 获取快照
`rejected` / `error` / `aborted` / `expired`	在明确原因前不要批准

获取变更内容 —— 执行
```
argos build snapshots <ref> --needs-review --json
```
。针对每个差异，检查
```
url
```
（差异遮罩）、
```
base.url
```
（变更前）、
```
head.url
```
（变更后）和
```
head.metadata
```
，以及不稳定信号
```
test.metrics
```
，若存在变更则还需查看
```
change.occurrences
```
/
```
change.ignored
```
（用于步骤3）。
根据推断的预期判断每个差异：
- 有意修改 —— 与代码变更一致，且渲染正常。
- 回归问题 —— 布局错乱/重叠、内容被裁剪、状态/主题/路由错误、内容缺失，或是快照被移除但未对应删除测试用例。
- 不稳定（Flaky） —— 参考两个独立信号；若信号一致，则可确定为不稳定：
  - 测试历史 ——
```
test.metrics.flakiness
```
    （0表示稳定 → 1表示不稳定）和
```
change.occurrences
```
    （在统计周期内该完全相同的差异出现的次数）。高不稳定分数或重复出现的差异是强有力的证据，表明该差异是环境干扰而非本次PR的问题；
```
stability
```
    （无变更的构建次数）、
```
consistency
```
    （差异是否重复出现）和
```
uniqueChanges
```
    解释了分数产生的原因。
```
change.ignored: true
```
    表示该差异已被标记为已知不稳定且自动批准 —— 绝不要将其视为回归问题。
  - 本次捕获 —— 加载动画/骨架屏、异步内容未加载完成、动画进行中、动态值偏移、
```
head.metadata.test.retry > 0
```
    ，或是不同浏览器的
```
score
```
    /
```
head.url
```
    完全相同（均捕获了同一瞬时状态）。
```
retries
```
    （配置的重试次数）本身并非判断信号。
  相反，稳定的测试（
```
flakiness
```
  趋近于0，
```
stability
```
  值高，首次出现变更）更可能是有意修改或真实的回归问题 —— 不要仅根据视觉效果就将其归为不稳定。可通过
```
build snapshots --metrics-period <24h|3d|7d|30d|90d>
```
  调整统计窗口（默认7天）。
针对特定差异发表评论 —— 这是Agent评审的最高价值输出。简单的批准/拒绝毫无意义；具体、锚定的反馈才是Agent评审的价值所在。针对每个有问题的差异，发布评论说明问题所在及修复方法，并锚定到对应快照：
bash
```
argos comment create <ref> --token <pat> --diff <screenshotDiffId> \
  --body "Loader still visible — capture runs before data loads. Wait for settled content (or mark the loader aria-busy)."
```
- ```
<screenshotDiffId>
```
  是
```
build snapshots --json
```
  返回的差异
```
id
```
  。
- 使用
```
--anchor-lines <from,to>
```
  或
```
--anchor-point <x,y>
```
  （归一化0–1）锚定到特定区域；使用
```
--reply-to <commentId>
```
  在评论线程中回复。
- 使用
```
--draft
```
  将评论打包为待提交的评审，然后在下一步中一起提交。
提交评审（若无PAT则仅报告结果）：
- 批准：
```
argos review create <ref> --token <pat> --event approve
```
- 请求修改：
```
argos review create <ref> --token <pat> --event reject --body "<summary>"
```
- 仅发表中立备注：
```
--event comment --body "<summary>"
```
- 对于构建编号引用（非URL），添加
```
--project owner/project
```
  参数。
- 若确认是重复出现的不稳定差异，可将其忽略以避免阻塞后续构建：
```
argos change ignore <change.id> --token <pat> --project owner/project
```
  （使用
```
change unignore
```
  撤销忽略）。仅忽略经统计数据确认的不稳定差异 —— 绝不要以此绕过真实的差异；若存在代码修复方案，优先选择代码修复（references/flaky-fixes.md）。
- 报告时先说明推断的预期、已评审的快照以及证据。在PR中引用构建URL和受影响的快照名称；对于不稳定差异，说明判断信号并推荐修复方案。

References

参考资料

references/baseline.md — baseline selection and orphan-build semantics (load when the review depends on which baseline was used).
references/flaky-fixes.md — concrete code fixes for flaky captures (
```
aria-busy
```
,
```
data-visual-test
```
, animation stabilization).

references/baseline.md —— 基线版本选择和孤立构建的语义（当评审依赖于所使用的基线版本时加载此文档）。
references/flaky-fixes.md —— 针对不稳定捕获的具体代码修复方案（
```
aria-busy
```
、
```
data-visual-test
```
、动画稳定化）。