argos-pr-review

Argos PR 审查

Argos 是一个视觉测试平台：每次 CI 构建都会捕获截图并与基线进行比较，为每张快照生成 差异。状态为 changes-detected 的构建正在等待人工（或你）判断每项变更是有意的、回归问题，还是不稳定的捕获结果。

将 Argos 构建视为 PR 审查的一个输入，而非唯一依据。_先_根据 PR 标题、描述、关联的问题和代码差异推断预期的 UI 变更，再用 Argos 确认渲染结果是否符合预期。

工具与身份验证

通过 argos CLI 操作 Argos——加载 argos-cli skill，了解令牌模型和标志。简而言之：build get / build snapshots 需要项目令牌（ARGOS_TOKEN/--token）；提交审查或评论则需要个人访问令牌（--token / argos login）。解析时始终使用 --json，绝不打印令牌值。如果没有 PAT，请向用户提供你的结论和证据，而不要发布内容——CLI 无法提交审查。

工作流

1. 检查构建 — argos build get <ref> --json。根据状态判断：

   状态	含义 / 下一步
   accepted / no-changes	已批准 / 没有视觉差异——无需审查
   pending / progress	尚未就绪——停止并报告目前还无法审查
   changes-detected	需要判断——获取快照
   rejected / error / aborted/ expired	在了解原因前不要批准

2. 获取变更内容 — argos build snapshots <ref> --needs-review --json。 检查每个差异的 url（差异蒙版）、base.url（变更前）、head.url （变更后）和 head.metadata，以及不稳定性信号 test.metrics；如果有变更，还要检查 change.occurrences / change.ignored（步骤 3 会用到）。

3. 根据推断出的意图判断每项差异：

   • 有意变更 — 符合代码变更，且渲染正常。

   • 回归问题 — 布局损坏/重叠、内容裁切、状态/主题/路由错误、内容缺失，或快照被移除但没有相应的测试移除。

   • 不稳定结果 — 综合两项独立信号；当两者一致时，有把握地判定为不稳定：

     • 测试历史 — 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> 调整统计窗口（默认值为 7d）。

4. 针对具体差异发表评论——这是 Agent 审查最有价值的产出。 简单的批准/拒绝没有多少价值；具体且有明确定位的反馈，才让 Agent 审查值得阅读。针对每项问题差异，发布一条评论，指出问题所在和修复方法，并关联到相应快照：

   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 将评论加入待提交的审查，然后在下一步中一并提交。

5. 提交审查（如果没有 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/baseline.md — 基线选择和孤立构建语义（当审查取决于所用基线时加载）。
• references/flaky-fixes.md — 修复捕获不稳定问题的具体代码方案（aria-busy、data-visual-test、动画稳定）。