用途：agent-browser 通过 CLI 驱动一个持久的真实浏览器会话，用于验证只有运行中的应用才能证明的状态，如路由、认证、实时数据和完整浏览器外壳。相较之下，隔离的 React、Ink 或终端可执行状态用 astroshot，可复用的多用例浏览器冒烟测试用 browser-ui-harness。
主要能力：打开页面、查看无障碍树、通过 ref 或选择器执行操作、调试，以及截图与诊断。CLI 自带与版本匹配的命令指南，应加载它而非依赖复制来的命令参考： agent-browser --version agent-browser skills get core --full
安装：仅在缺失时安装 CLI： npm install -g agent-browser agent-browser install
使用方式：为仓库创建唯一会话名，例如： REPO="$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")" SESSION="browse-${REPO}-$$" 然后打开页面并等待： agent-browser --session "$SESSION" open "https://example.com/app" agent-browser --session "$SESSION" wait --load networkidle agent-browser --session "$SESSION" snapshot -i 之后循环：用 snapshot -i 或局部快照检查，通过当前 @eN ref 或稳定的语义选择器操作，等待产品级就绪条件，再次快照并断言结果，仅捕获有意义的状态。不要点击过期 ref 或猜测选择器；find 会执行操作且默认点击，需显式命名动作： agent-browser --session "$SESSION" find role button click --name "Submit" agent-browser --session "$SESSION" find label "Email" fill "user@example.com" 只读检查命令包括 snapshot -s 'main'、is visible、get count、get url。networkidle 只是传输层稳定，不代表产品状态就绪，应等待特征文本、选择器、URL 或 JavaScript 条件后再断言或捕获。
捕获与诊断：可设置视口并截图，例如 set viewport 1280 900、screenshot ./page.png、screenshot --full、以及对特定元素截图；用 errors、console、network requests --filter 排查。局部裁剪用于排除无关界面。切勿捕获加载骨架、凭据、令牌或客户数据。
与 Astroshots 配合：页面达到目标状态后，可读取 astroshots-review 技能并用其辅助命令，通过 --from-agent-browser "$SESSION" 流式传输帧。Astroshots 是可选的审查传输，不替代产品断言，也不代表人工批准。连续旅程影片应使用 astroshot movie --source browser，而非桌面录制 Chrome；agent-browser 仍负责语义操作与断言，影片只是证据。
本地应用与清理：从目标仓库配置或文档发现基础 URL，先做健康检查再打开会话，不要臆造端口。若旅程会改动数据，优先使用回环目标与运行唯一值。除非人工要求保留调试，否则关闭会话：agent-browser --session "$SESSION" close。报告产品结果、异常 URL 或诊断、捕获路径、使用的 Astroshots feature，以及浏览器会话是否仍打开。