用途
Antithesis agent-browser 是一个辅助技能，用于在 snouty API 无法可靠提供所需信息时，从需要认证的 Antithesis 网页中读取数据。其他技能（antithesis-triage、antithesis-debug、antithesis-query-logs）在需要已认证的浏览器会话时会委托到这里。
主要能力
- 以最小干扰处理与用户 Antithesis 租户的交互式认证。
- 加载 Antithesis 网页（报告、日志、运行、因果报告），并通过注入的运行时从中提取数据。
- 从运行页面发现运行记录。
- 从分诊报告读取属性。
- 从无法与 snouty runs list 匹配的分诊报告 URL 中查找 run_id（run_id 渲染在主报告页面底部，report_id → run_id 目前不由 API 暴露）。
- 从失败运行的报告页面下载错误日志。
- 读取因果报告（主要信号是日志中通向 bug 时刻的 bug 概率轨迹）。
使用方式
前置条件
- 必须已安装 agent-browser，否则不要继续。安装选项见 https://raw.githubusercontent.com/vercel-labs/agent-browser/refs/heads/main/README.md。
- agent-browser 版本不得低于 v0.23.4，可用
agent-browser upgrade升级。 - 必须已安装 jq，安装选项见 https://jqlang.org/download/。
- 本技能的 references/ 目录包含特定任务的详细指南。不要预先全部读取，只在被指示时读取对应参考文件。
会话管理
agent-browser 有两个会话变量：
--session：唯一、隔离的浏览器实例名称。--session-name：按名称自动保存/恢复 cookie。
每次调用都必须使用唯一的 --session 值。生成一次并在本技能引用 $SESSION 时复用：
SESSION=antithesis-ab-$(date +%s)-$$
在引用新 $SESSION 的第一个 agent-browser 命令中使用 --session-name antithesis，这会创建会话并恢复已保存的 cookie。同一 $SESSION 的后续命令不需要 --session-name，因为会话已存在。完成后关闭活动会话：
agent-browser --session $SESSION close
认证
不要为了检查认证而导航到首页。应使用会话创建命令直接导航到目标 URL（报告、运行页面等）：
agent-browser --session "$SESSION" --session-name antithesis open "$TARGET_URL"
agent-browser --session "$SESSION" wait --load networkidle
agent-browser --session "$SESSION" get url
如果 URL 以 https://$TENANT.antithesis.com 开头，则已认证。如果重定向到登录页，则需要认证——阅读 references/setup-auth.md，其中会在用户确认后启动交互式有头登录。
运行时注入
本技能附带一个运行时（assets/antithesis-agent-browser.js），在 window.__antithesisAgentBrowser 上暴露用于读取 Antithesis 页面数据的辅助方法。在导航完成后注入：
cat assets/antithesis-agent-browser.js \
| agent-browser --session "$SESSION" eval --stdin
用 agent-browser eval 调用其方法：
agent-browser --session "$SESSION" eval \
"window.__antithesisAgentBrowser.report.getRunMetadata()"
agent-browser eval 会自动等待 Promise，因此异步和同步方法使用相同的调用模式。
错误处理：运行时方法出错时会抛出异常，导致 agent-browser eval 返回非零退出码。检查退出码即可检测失败，无需解析输出。错误消息会描述出错原因（例如页面错误、元素未找到、超时）。
如果 window.__antithesisAgentBrowser 缺失，重新注入 assets/antithesis-agent-browser.js 并重试。
切勿并行运行 agent-browser 调用。它们是有状态且带副作用的调用，并行调用可能出错或返回混乱结果。
导航与加载
每个 Antithesis 页面都会异步加载内容。导航到任何 Antithesis 页面后，遵循以下模式：
- 先等待 networkidle：
agent-browser --session "$SESSION" wait --load networkidle
- 然后检查 url，看是否被重定向到认证页面：
agent-browser --session "$SESSION" get url
如果遇到认证页面，停止并重新认证后再继续。
- 然后注入运行时：
cat assets/antithesis-agent-browser.js \
| agent-browser --session "$SESSION" eval --stdin
- 最后，eval 页面特定的等待函数，等待所有异步块加载完成：
- 报告页面：
window.__antithesisAgentBrowser.report.waitForReady() - 日志页面：
window.__antithesisAgentBrowser.logs.waitForReady() - 运行页面：
window.__antithesisAgentBrowser.runs.waitForReady()
每个等待方法默认轮询最多 60 秒。成功时返回 { attempts, waitedMs }。超时时方法抛出异常，导致 agent-browser eval 返回非零退出码。
需要一次性探测时，使用较低层的布尔检查：
- 报告页面：
window.__antithesisAgentBrowser.report.loadingFinished() - 日志页面：
window.__antithesisAgentBrowser.logs.loadingFinished() - 运行页面：
window.__antithesisAgentBrowser.runs.loadingFinished()
如果页面仍未就绪，检查状态：
- 报告页面：
window.__antithesisAgentBrowser.report.loadingStatus() - 日志页面：
window.__antithesisAgentBrowser.logs.loadingStatus() - 运行页面：
window.__antithesisAgentBrowser.runs.loadingStatus()
处理错误报告
每次调用报告 waitForReady() 后，检查 result.error。如果存在，阅读 references/error-reports.md 了解错误报告工作流。
通用指导
- 始终确保先完成认证。
- 使用一次性会话。每次调用本技能都生成唯一的 SESSION。
- 在导航后注入运行时。每次 open 后、点击可能改变页面的链接后，以及从 finding 路由重新打开报告后，都要等待 networkidle，注入 assets/antithesis-agent-browser.js，然后使用匹配的
*.waitForReady()方法再继续。 - 切勿并行运行 agent-browser 调用。它们是有状态且带副作用的。
- 通过重新注入重试缺失运行时错误。如果命令因
window.__antithesisAgentBrowser未定义或缺失而失败，注入运行时并重跑同一方法。 - 将报告 eval 保持在主报告视图上。如果不小心点击进入其他页面，在使用报告查询前重新打开原始报告 URL。
适用场景
- 当另一个技能需要 snouty 无法可靠提供的 Antithesis 页面信息时。
- 当用户或另一个技能需要直接与 Antithesis 网页交互时。
限制
- 必须已安装 agent-browser 且版本不低于 v0.23.4，否则不要继续。
- 必须已安装 jq，否则不要继续。
- 不要为了检查认证而导航到首页。
- 不要并行运行 agent-browser 调用。
- 不要预先读取所有参考文件，只在被指示时读取对应文件。
- 优先使用 snouty API（如
snouty runs list、snouty runs --json properties），仅在 API 不可用或未暴露所需内容时才回退到 UI。 - 因果报告需要用户提供 URL。
- 本技能版本为 2026-09-23 a8fe900。