Browser automation

Browser automation 表示真实浏览器不是测试工具，而是产品/运维工作流的一部分。仓库需要直接处理浏览器身份、challenge、邮箱验证、代理环境、headless/headed 切换和运行诊断，因此浏览器本身就是 runtime contract。

这个 Topic 和 Playwright e2e 不同。后者是质量门禁，Browser automation 则是在生产性自动化里把浏览器当执行引擎使用。它通常会和 Developer utility、SQLite 一起出现，但不替代这些 Topic：Browser automation 解释浏览器执行面，其他 Topic 解释工具定位或运行记录（projects/tavreg-hikari.md）。

当 README、workflow 文档、CLI 入口或 project snapshot 明确表明系统依赖真实浏览器完成注册、登录、验证、challenge 处理或 provider 交互时使用。若浏览器只用于本地测试或 CI e2e，不应命中。

如果一个改动会影响浏览器启动方式、指纹/代理预检查、邮箱/验证码流程、headless/headed 调试路径、或运行结果如何落盘和复盘，就应该命中 Browser automation。若改动只在普通 Web UI 或测试脚本内，则应回到相邻 Topic。

• Split the system into orchestration plus replaceable subsystems (browser launch, proxy control, mailbox/provider integration, persistence), so failures can be retried without rewriting the whole run loop (projects/tavreg-hikari.md)
• Run environment and identity prechecks before irreversible actions; IP, WebRTC, fingerprint, or similar signals should be validated up front instead of being debugged after a bad run (projects/tavreg-hikari.md)
• Persist structured artifacts for each run (result payloads, diagnostics, per-run folders, or ledgers) so automation remains auditable and batch runs can be triaged after the fact (projects/tavreg-hikari.md)
• Keep debugging modes explicit at the CLI/env layer (headed vs headless, browser engine, inspect-only paths) so operators can switch from unattended execution to diagnosis without patching the code (projects/tavreg-hikari.md)
• 浏览器层与业务编排层应分开。浏览器启动、代理控制、邮箱/provider 集成和 ledger 若缠在一起，失败后很难局部重试。
• 不可逆动作前必须做环境预检查。IP、WebRTC、指纹、cookie/profile、邮件可达性等都应先验证，否则坏 run 的代价很高。
• 运行产物必须可复盘。批量自动化如果没有 per-run 结果、诊断和 ledger，很快就会退化成“跑了但不知道发生了什么”。
• 调试开关要显式暴露在 CLI/env 层，避免为了看一次浏览器过程就去改代码。
• 回答此 Topic 时，应先说明浏览器在工作流里承担什么角色，再说明用了什么库。否则很容易把关键问题从“身份/挑战/诊断”错误降级成“Playwright API 怎么写”。

• projects/tavreg-hikari.md：直接样本。它把注册、邮箱验证、代理检查、ledger 和 CLI 调试路径都放进同一自动化工作流里，适合说明真实浏览器如何从“测试工具”升级成“生产性执行面”。

• 把测试用浏览器脚本误写成 Browser automation，会让 Topic 边界虚化。
• 把 Browser automation 当成整个仓库的总括标签，忽略 Developer utility、SQLite 等相邻 Topic，会让后续 Agent 无法判断真正该看的是浏览器执行面、工具定位还是记录持久层。
• 没有 precheck 和可复盘产物时，自动化一旦失败就很难定位是在浏览器、代理、邮箱还是 provider 上坏掉。
• 没有 headed/inspect 路径，也会让真实浏览器问题变成只能盲调的黑箱。

• projects/tavreg-hikari.md
• skills/style-playbook/references/data/topics/browser-automation.json