browser-max-automation

Browser Max Automation

通过 Playwright MCP、已有浏览器 CDP 以及直接 CDP 辅助工具实现浏览器自动化。

适用场景

• 浏览器自动化、UI 确认、表单操作、截图获取
• 想先用 MCP 确立步骤，再用 Python 批量执行时
• 想通过 CDP 使用已有浏览器的登录状态时
• Playwright MCP / connect_over_cdp() 不稳定，想切换到 raw CDP WebSocket 时
• 处理模态框或 file chooser 等普通点击容易失效的 UI 时

不适合的场景

• 优先考虑 API / CLI：如果通过官方 API（YouTube Data API、Microsoft Graph、GitHub API 等）或 CLI 就能完成 read/write，则优先使用它们；出现 UI 脆弱的迹象（native file chooser / shadow DOM / 多步向导 / 会阻塞渲染器的 modal）时不要执着，应及时切换（例：YouTube Studio UI → captions.insert）
• URL 的存活确认用 HTTP client 进行，但仅 dead 判定升级到浏览器。确凿的消失证据只有 HTTP 404 / 410。403 是 bot 拦截，timeout 是一过性的，SSL 的 unable to get local issuer certificate 发生在不返回中间 CA 的服务器上（浏览器和 .NET/schannel 会通过 AIA 自动补全，但 Python ssl 不会）。请用 Invoke-WebRequest -Uri <url> -Method Get 或浏览器核实后再下结论
• PowerPoint / Loop / Dynamics 365 的 expense entry 画面等有专用 skill 的 UI，优先遵循该 skill 的操作规则
• 不要在聊天中接收认证信息、机密信息、MFA 响应。必要的输入请让用户在浏览器上处理。用户操作后，不要读取可能显示恢复代码、token、password 的画面正文，只通过 URL（/json/list）确认状态。即使用户申报「已完成」，也可能残留确认前的机密显示画面
• 例外：如果目标网站支持 passkey / FIDO2 / WebAuthn，则可通过 CDP 虚拟认证器实现完全无人化。优先级为 passkey (虚拟认证器) > 邮件 OTP > SMS > 物理密钥 / 生物识别。详情请参阅 references/instructions/webauthn-virtual-authenticator.md

先选择模式

• 默认使用可见的、带标题栏的浏览器。仅在明确要求时使用无头模式，绝不能将其作为自动恢复路径。尽可能复用已验证的认证会话和自有工作标签页；新建配置文件并不意味着认证可复用。当专用启动已被授权时，若会话缺失，应进行自有启动，而非判定为不可用。
• 保留操作系统前台窗口和用户选中的标签页。不要例行调用 bring_to_front、Page.bringToFront、Target.activateTarget 或原生聚焦/按键辅助工具。这适用于浏览器启动、标签页创建、导航、捕获和恢复，而不仅仅是点击操作。
• 如果某项必要操作无法避免激活，请先说明原因以及需要哪个有界步骤，然后再继续。之后不要强制将焦点切回：用户可能在此期间已切换到其他应用。凭据和 MFA 仍由用户输入。将步骤交给用户时，请提供窗口标题并确认窗口位于主显示器上（多显示器配置下否则会被隐藏）。
• 确定工作标签页、目标和已授权的副作用。浏览器访问权限或草拟权限并不授权发送消息、购买、交易、取消或合同变更；应将审批绑定到目标位置和确切内容/操作。只读辅助工具不得提交或选择设置选项；允许展开菜单，但选择某项可能会自动保存。报告尝试的写入操作，包括被阻止的写入。在用户编辑、目标漂移或所有权丢失时暂停；查看标签页并不允许丢弃它。
• 对于受支持的数据操作，优先使用 API/CLI 辅助工具，但当目标是演示、UI 验证或观察浏览器工作流时，保留 UI 执行。

模式	适用场景	边界
现有有头浏览器 + MCP/CDP	认证或交互式探索较为重要	验证配置文件、自有目标和非激活行为
Playwright CLI 或已保存的 Playwright 脚本	稳定工作流将重复执行	复用会话；新启动时明确请求有头模式
直接 CDP WebSocket	需要已验证的更低层路径	固定目标 ID；不要绕过所有权或恢复限制

既存ブラウザ CDP の起動、profile 確認、port drift、認証 URL encode、スクリーンショット取得は references/instructions/cdp-existing-browser.md を参照する。 直接 WebSocket CDP の起動フラグ、websocket-client 接続、SPA hash navigation、virtual scroll 操作は references/instructions/cdp-direct-websocket.instructions.md を参照する。

核心循环

1. Reuse a suitable script or establish the flow on an owned, verified work tab.
2. Resolve the target and expected postcondition with a scoped snapshot or query.
3. Perform the action once; wait for the expected state with a deadline.
4. Read back the durable result before retrying or moving to the next item.

保持一条可用的控制路径，而不是反复切换 MCP/CLI/CDP。批量执行相互独立的读取并返回紧凑结果；在具有意义的视觉检查点使用完整快照或截图，而不是每次读取后都使用。

对于下载，在上下文/运行器清理之前保存一份持久的、带扩展名的副本，并验证其字节/内容，而不是其浏览器历史记录中的名称或图标；参见下载处理。

等待必需的控件或明确的空状态。标题、路由或标签页点击成功既不能证明已认证，也不能证明所选视图与渲染的行匹配。区分解析失败与空数据：保留原始文本，仅在提取副本中规范化观察到的不可见标签字符，并通过收集器测试显式零值、缺失字段和 ID 不匹配的情况。绝不注入预期的 ID 来通过验证。就绪截止时间结束时处于未验证状态，而非推断出的登出状态。

UI 验证时，在操作前确定预期的 state 和确认方法。不要仅凭成功 toast 或按钮按下就判定成功，而要通过 DOM、URL、持久化的列表行、API 的读取结果，或 screenshot / trace 等证据来确认。 对于设置回读，在选择定位器之前先定位语义区块/分组并检查实际角色：标签可能从单选按钮变为下拉菜单，相似的控件可能管辖不相关的范围。从 checked、aria-checked 或显示的值中读取选中状态。当前选中项或文档化默认值并不能确立创建时的值；需要历史且未变更状态的证据，否则报告为未验证。 对于回复/消息，将编辑器和列表预览排除在成功检查之外。在可用时捕获 POST 状态和回复/消息 ID；否则在全新读取/重新加载后验证已批准的内容和发送者一次出现在预期会话中。在重新加载前保留草稿，绝不丢弃他人的输入，并将不可用的网络证据报告为未观察到。陈旧的计数或提交后保留的草稿不构成重新发送的理由。

API 与 DOM 的状态有时会暂时不一致。即使 API 返回 stale / capture failure，如果画面上的 cell / row 的 aria-label 或 status text 显示状态已推进，也应将 DOM 视为正本候选。不要仅凭 API 就断定“未完成”。

决策模式

情形	操作
流程或选择器仍未知	交互式使用 MCP
稳定的多步流程第二次重复出现	当重复次数超过维护成本时，复用或将已保存的脚本参数化；对于已知的批量工作，先校验一项，然后首次运行时就将其余项脚本化
快照返回 ref	使用普通的 click/type
元素可见但没有 ref	目视确认后，使用 evaluate 或相关的 UI 回退方案
元素不可见	等待有边界的就绪条件；保留有未保存内容的表单，不要强制交互
只读表格数据提取	保留导航证据，然后从 DOM 求值返回紧凑的 JSON

仅靠 CLI 命令并不能消除逐操作的推理。保存已验证的序列，包含稳定的定位器、输入/目标参数、回读、重复写入保护和可逐项恢复的结果。将任务专属脚本与其项目一起存储，将通用辅助脚本与所属 skill 一起存储；记录用途和调用方式以便发现。不要持久化保存密钥或临时快照 ref。参见 可重复工作流。

虚拟化信息流 / 逐项变更及处理器数量诊断：参见 UI 回退方案。

不要破坏未保存的编辑器 / 草稿标签页

保持有未保存内容的编辑器标签页原样不动；使用单独的干净工作标签页，而不要导航或重新加载它们。绝不要自动接受 Leave 或丢弃更改。 CDP 报告 No dialog is showing 并不排除浏览器 chrome 提示。仅当所属浏览器进程、所选标签页地址、确切的离开站点警告及已启用的按钮唯一匹配时，原生自动化才可调用 Cancel/Stay only；否则停止。绝不要以这种方式处理凭证、权限或任意对话框。 在关闭后，验证同一目标有所响应；保留的表单值并不能证明设置已保存。参见 未保存表单安全 和 原生恢复。

iframe、force click、file chooser、hidden input、evaluate+fetch 参见 UI 回退方案。force: true 应作为确认元素存在且可见之后的最终手段。

安全规则

在向外部平台重复／批量发送技术、安全内容之前的 content-filter preflight，参见 UI 回退方案。

失败预算

• 写入之前，选择其持久成功信号和一次有界恢复。对于 UI、CLI、CDP、脚本和替换标签页路径中的每个逻辑操作，允许初次尝试加上至多一次恢复尝试；切换路径不会重置预算。
• 超时并不证明失败。重新读取权威状态；仅当确认未应用或幂等机制可防止重复时才重试。如果结果仍然不明确，停止而不重放写入。
• 两次失败尝试后停止，并报告目标、尝试次数、最后状态和重启条件。等待正常的异步进展不算另一次尝试：使用截止时间和窄范围状态检查，而不是固定休眠或重复的整页快照。
• UI click から DOM mutation、keyboard、private frontend internals へ連続的に fallback しない。公開されていない ViewModel や upload 実装の操作は、明示承認のある単発 incident 以外では使わない
• Session ended、login redirect、別 context を検出したら stale DOM を操作しない。再認証後は永続 state を再取得し、未完了操作だけを再開する

CDP 排他控制

• 每个工作目标使用一个控制器。如果另一个会话拥有浏览器且协调未经验证，使用一个空闲端口和一个单独的未使用 user-data-dir。仅更换端口或 profile 目录并不能隔离 Chromium 进程；不要附加、重启它或复制其凭据以绕过所有权。
• 固定已验证的 profile/context 和拥有的目标 ID；在每个写入批次之前重新检查 URL、route、query 和 item ID。绑定工作目标后，绝不要再次选择第一个域匹配项。
• 在必要的交接之前，停止拥有的 runner 并验证当前工具的 detach/close 语义。不要将 browser_close 用作通用的断开连接：它可能会销毁标签页或浏览器。保留脏标签页；如果无法安全分离，保留工作路径或停止。
• 仅在结果验证后关闭明确拥有且不再需要的目标。绝不要关闭共享浏览器的最后一个标签页或停止另一个会话的 runner 作为清理。当 Playwright MCP 通过 CDP 附加时，browser_close 可能仅分离并保留拥有的标签页打开；重新列出目标并按 ID（/json/close/<id>）关闭拥有的那个。

使用 raw WebSocket 时，按 CDP command id 过滤响应，并先启用 Runtime.enable / Page.enable 等必要的 domain。详情请参阅 references/instructions/cdp-direct-websocket.instructions.md。

Playwright MCP 的 file: 拒绝（通过 http.server 提供）以及容易出问题的场景列表，请参阅 CDP Recovery and Context。

参考对照表

需求	参考文档
现有浏览器 CDP、配置文件、端口漂移、截图捕获	references/instructions/cdp-existing-browser.md
原始 CDP WebSocket	references/instructions/cdp-direct-websocket.instructions.md
从已认证浏览器提交 CWS，无需 CDP	references/instructions/cws-store-submission.instructions.md
WebAuthn 虚拟认证器 / passkey	references/instructions/webauthn-virtual-authenticator.md
CDP 恢复、上下文选择、无 CDP 的 Windows UI Automation	references/instructions/cdp-recovery-and-context.md
Azure Portal iframe / OOPIF	references/instructions/azure-portal.md
Angular Material 表单	references/instructions/angular-material.md
隐藏上传、VS Code Web、evaluate+fetch、UI 回退	references/instructions/ui-fallbacks.md
未保存的编辑器 / 草稿标签页安全	references/instructions/unsaved-form-tabs.md
Windows 子进程稳定性（PIPE 死锁、SIGINT、进程树终止）	references/instructions/windows-subprocess-cdp.md

完成标准

• 验证实际控制路径在操作期间保持操作系统前台和用户标签页选择，而不仅仅是在操作前后保持；区分已测量结果与未验证行为。检查保存的捕获是否存在渲染不完整。
• 报告工作目标和持久结果；对于重复运行，报告脚本复用情况并比较耗时、工具调用和重试次数，不得省略验证。参见验收场景。
• 成功判定を toast だけに頼らず、DOM / URL / API read / screenshot / status artifact のいずれかで確認している
• 失敗時は modal / file chooser / iframe / CDP context のどこで詰まったかを報告している
• Playwright MCP が作業 repo 直下へ書く .playwright-mcp/（console log / snapshot）が .gitignore 済みで、自分が作った未追跡分は git clean -n で確認して削除している。追跡済みなら git rm -r --cached -- .playwright-mcp（ファイルは残る）