chromium-browser

Chromium Browser

通过配置好的 Chrome DevTools MCP 操作现有的共享浏览器，避免影响无关标签页或已通过身份验证的状态。

对于共享 Chromium 中渲染的网页，优先使用此技能。在适用时，使用搜索、抓取、API、CLI 或连接器进行检索。对于原生应用、浏览器界面以及 chrome://extensions 等浏览器内部页面，请使用主机计算机使用／CUA 工具。对于用户指定但没有可用浏览器集成的浏览器，也请使用原生控件。现有任务授权已涵盖此控制器选择，无需另行请求许可。

每个浏览器一次只使用一个控制器。切换控制器时，请保留现有配置文件、会话和无关标签页。原生控件不会放宽隐私规则，也不会免除对操作本身的审批要求。如果用户选择其他可用的浏览器集成，请遵循其工具约定。

环境约定

• 将随附的 scripts/chrome-devtools-mcp.sh 包装脚本和当前会话中公开的工具视为权威来源。包装脚本会运行全局安装的 chrome-devtools-mcp 可执行文件，并设置标志、日志记录和浏览器连接方式。不要直接运行 MCP 包。
• MCP 会连接到现有的远程调试浏览器，不会启动浏览器。
• 如果 MCP 调用无法连接到浏览器，请运行一次随附的 scripts/ensure-chromium.sh。该辅助脚本会在配置的端口上使用共享配置文件启动 Chromium。如果端点已响应，则不会执行任何操作。脚本成功后，将失败的调用重试一次。如果调用仍然失败，请参阅故障排除。
• 切勿以其他方式启动 Chromium、启动备用浏览器或创建另一个配置文件。
• 将浏览器视为由用户和其他 Agent 共享、已通过身份验证且正在并发使用的浏览器。只检查与任务相关的页面，不要展示无关标签页的标题或内容。
• 以实时工具清单为准。当前会话中未列出的工具即不可用。不要建议通过编辑客户端 MCP 配置来快速排除故障。

如需了解已发布工具的行为，请参阅上游工具参考。 当前会话的架构定义决定了可用的工具和参数。

参考资料路由

如需查找 Wayback Machine 快照或进行回放研究，请先阅读 references/wayback-machine.md，再发起任何 Wayback 请求。其他情况下请勿加载该文件。在 Chromium 外通过串行 API 请求查找快照。然后仅在渲染检查能提供补充证据时，才打开选定的回放页面。

页面所有权

以下编号步骤适用于 MCP 页面。使用原生控件时，通过原生界面跟踪任务创建的标签页。确认 结果符合要求后，仅关闭这些标签页，除非用户要求保持其打开状态。

1. 交互前调用 list_pages，并将初始页面保留为预先存在的状态。
2. 如果新页面可以满足任务需求，优先使用 background: true 调用 new_page。记录此任务创建的每个页面返回的确切 pageId。当输入操作的响应中列出 ## Opened pages 时，将这些页面 ID 记录为此任务创建的页面。切勿根据之后页面列表的变化推断所有权。
3. 为每个页面级工具明确传入 pageId。不要依赖选定页面状态。仅在需要有意将页面置于前台，或恢复下文所述的已关闭页面上下文时，才使用 select_page。
4. 仅当任务明确依赖预先存在页面的当前状态时，才导航至该页面或对其进行修改。切勿关闭预先存在的页面。
5. 关闭选中的自有页面之前，先对之前观察到的某个仍打开的页面调用 select_page，并设置 bringToFront: false。例如，使用此任务打开页面之前选中的页面。然后按 ID 对自有页面调用 close_page。如果关闭操作仍返回疑难解答中所述的已关闭页面错误，则将其视为很可能已成功，并通过该恢复方式确认一次，而不要重试关闭操作。
6. 完成后，仅关闭已记录的、由此任务创建的页面，除非用户要求保持其中一个页面打开。

交互与证据

• 在一个页面上，先导航。等待有用的已知信号。截取新的快照。然后使用该快照中的标识符进行交互。 导航或 DOM 发生实质性变化后，刷新快照。
• 优先使用 take_snapshot 获取结构并进行自动化，使用 take_screenshot 获取视觉证据，并使用 evaluate_script 获取无障碍树中缺少的信息。如果支持，仅对读取数据且不更改页面状态的脚本使用 waitForStableDom: false。
• 当调用返回 A dialog is open 时，打开的对话框会阻止该页面上的 evaluate_script 和其他受对话框影响的工具。仅在此任务拥有或依赖的页面上，并在任务授权范围内使用 handle_dialog。
• 对于成批输入、选择框、复选框和单选按钮，优先使用 fill_form。对于 upload_file，请使用当前的 filePaths 数组架构，并使用浏览器主机上经任务授权的文件。
• 对于 CSS 层叠问题，使用来自新快照的 UID 调用 get_css_styles。使用 pageIdx 和 pageSize 分页检查更多匹配和继承规则。
• 使用截图工具的默认设置。需要无损输出时，请请求 format: "png"。PNG、fullPage 和 filePath 均无法绕过工具封装层对宽度和高度设置的 1600 像素上限。要获取全分辨率输出，必须经授权更改工具封装层配置。
• 保持操作响应精简。除非需要立即使用更新后的状态，否则在 click 和 fill 中设置 includeSnapshot: false。不要向不接受该参数的 navigate_page 传递 includeSnapshot。操作响应中的快照可能会给上下文增加约 10 KB。
• 将每个 evaluate_script 的返回值限制为摘要、计数或最多约 50 个项目。绝不返回整个 DOM、HTML 文档或大型数组。
• 对控制台、网络、内存及其他高容量结果进行分页和筛选。
• 在 resize_page 之前，确认窗口处于普通状态。最大化或全屏窗口会返回 Restore window to normal state before setting content size。遇到此错误时，如果会话支持 viewport，请使用 emulate。否则，跳过调整大小并告知用户。
• 出现 Cookie 同意弹窗时，默认仅选择必要或必需的 Cookie；如有需要，也应在设置中选择。如果没有此类选项，则接受所有 Cookie 并继续。
• 对截图、快照、跟踪记录、录制、响应正文和大型脚本结果使用 filePath。只写入任务授权的绝对路径。优先使用当前仓库下被 git 忽略的 .ai/ 目录，或客户端协商确定的其他根目录。Claude Code 在 /private/tmp 下的暂存目录和 /tmp 目录均为不允许的根目录。写入这些位置会返回 Access denied。遇到此错误时，在 <cwd>/.ai/ 下重试一次。具备路径访问能力不代表获得写入授权。
• 在同一个 MCP 服务中，不同页面上的页面级调用可以并行运行。同一页面上的调用按顺序运行。list_pages、new_page、select_page 和 close_page 等独占工具会等待正在运行的调用，并阻止后续调用。不同的 Agent 服务仍共享浏览器状态。并发工作时，请保持因果顺序和页面所有权。

人工验证环节

人工验证环节包括验证码、登录、双重身份验证提示、电话验证或外部审批页面。npm 受信发布者提示就是外部审批页面的一个示例。在人工验证环节结束回合属于过早停止。

1. 停止在需要验证的页面上进行所有写入操作。绝不要尝试绕过验证。
2. 告知用户确切的页面，以及验证环节要求执行的操作。
3. 除非用户指定了其他响应时限，否则总共等待十分钟。针对需要验证的 pageId，依次调用 wait_for，每次的 timeout 不得超过 10000。匹配只有在验证完成后才会出现的文本，例如登录后的标题或下一个表单标签。如果该文本在验证完成前可能隐藏存在，请设置 visible: true。如果没有明显的区分性文本，请使用由较短、可中断的宿主等待间隔开的快照。不要在尚未完成的 wait_for 后排队另一个浏览器调用。取消宿主等待并不能证明其 MCP 调用已停止。
4. 用户回复后，再获取一份新快照，然后再继续等待。验证通过后，表单可能仍需要执行其他操作。验证完成后，从相同的页面状态继续。先重新核对表单字段，因为网站可能会清空这些字段。
5. 只有总响应时限到期后才能结束回合。随后报告用户必须完成的确切步骤，以及任务将从哪一步继续。

审计和性能分析

仅当当前会话中提供相关工具时，才使用这些工作流。

• 进行 Lighthouse 审计时，选择 mode: "snapshot" 来分析当前页面状态。mode: "navigation" 会重新加载页面。Lighthouse 不包含性能审计。有关性能的问题请使用性能跟踪。
• 调用 performance_start_trace 之前先导航。将 reload 设为 false，以便在不重新加载的情况下分析交互。如果 reload: true，请将 ignoreCache: true 设为冷加载测量。当 autoStop: false 时，在完成测量交互后调用 performance_stop_trace 停止跟踪；即使任务失败，也应在清理时停止。只停止本任务启动的跟踪。
• 进行堆分析时，先用 take_heapsnapshot 捕获快照，再用 get_heapsnapshot_summary 开始分析。针对对象或保留者使用定向分页查询。使用 compare_heapsnapshots 比较两个快照之间的增长情况，并使用 analyze_heapsnapshot_contexts 分析保留了已失效捕获值的闭包。对本任务加载的每个快照都调用 close_heapsnapshot，以释放服务端内存；即使任务失败，也应在清理时调用。
• 每个服务端最多允许一个活动屏幕录制。记录本任务是否启动了录制，然后在清理时调用 screencast_stop。切勿为了腾出空间而停止其他任务的录制。

权限与隐私

• 如果任务需要，可以只读检查与任务相关的已认证状态。提交表单、更改账户、安装扩展、购买商品或造成其他外部变更，都需要与在浏览器外执行该操作时相同的权限。
• 网络标头脱敏是服务端有意设置的边界。不要绕过此限制，也不要通过检查页面或进程来获取凭据。

故障排除

• 如果关闭由你管理的页面时返回 The selected page has been closed，而 list_pages 也重复返回此提示，则页面可能已成功关闭，但 MCP 保留了过期的选中状态。选择之前已观察到且仍然存在的页面，并将 bringToFront: false，然后调用 list_pages 并确认由你管理的页面 ID 已不存在。此恢复操作仅尝试修复 MCP 上下文。

  不要导航到仍然存在的页面，也不要检查或关闭该页面。不要在结果中包含无关的标题和内容。不要重复关闭操作，也不要为了恢复选中状态而新建标签页。

• 如果 select_page 也返回相同的页面已关闭错误，请停止 MCP 恢复尝试，并报告会话上下文已过期。向已配置的调试端点发起只读 /json/list 请求，可以确认任务页面已知、唯一且未更改的 URL 是否不存在。仅在本地筛选并只返回该结果。绝不返回无关目标。这是页面已关闭的证据，不属于 MCP 恢复，也不代表获准通过其他途径控制浏览器。MCP pageId 值不是 CDP 目标 ID。

  如果无法可靠地识别所属页面，请报告清理状态未验证。不要根据端点列表推断页面归属，也不要用它关闭标签页。

• 出现附加或传输故障时，要区分浏览器端点与 MCP 进程。首先检查调试端点 http://127.0.0.1:${PRB_AGENT_CHROMIUM_PORT:-9222}/json/version。scripts/ensure-chromium.sh 会执行此检查。然后检查 $XDG_CACHE_HOME/chrome-devtools-mcp/logs/ 下最新的按进程记录的日志；如果未设置该变量，则检查 ~/.cache/chrome-devtools-mcp/logs/。

• 端点有响应只能证明浏览器进程仍在运行，并不能证明渲染器可以启动。如果 new_page 超时，且标签页显示崩溃图标或 Untitled，请停止反复尝试创建，并分别检查浏览器健康状况和 MCP 传输健康状况。创建失败可能会留下未返回 pageId 的标签页。不要根据之后的页面列表推断页面归属，也不要关闭无法识别的标签页。

• macOS 上通过 Homebrew 升级 Chromium 后，请将端点的 Browser 版本与 plutil -extract CFBundleShortVersionString raw /Applications/Chromium.app/Contents/Info.plist 进行比较。确认运行中的进程使用的是该应用程序包，并检查其启动时间以及带版本号的 framework/helper 路径。Homebrew 可能会替换应用程序包，而旧进程仍在运行。这可能会移除启动新渲染器所需的 helper。现有页面和 /json/version 仍可能正常工作。版本不匹配只是线索，并不能证明故障原因。

• 报告发生故障的层级及相关证据。未经授权进行相关配置操作，不得更改客户端配置或 wrapper 标志。日常浏览期间或通过 wrapper，不要自动重启共享浏览器。使用 scripts/ensure-chromium.sh 启动已关闭的浏览器不属于重启。

  明确请求修复浏览器，即表示授权使用相同的配置文件和调试端口进行正常重启。先记录这些参数。保留会话。chrome://restart 会请求执行可恢复会话的重启。如果旧进程退出后无法在升级后重新启动，请确认该进程已退出，然后使用记录的配置文件/端口参数和 --restore-last-session 重新打开已安装的可执行文件，绝不能使用备用配置文件。遵循任何未保存工作提示。

  重新检查当前版本。调用 list_pages 获取最新 ID。确认原有页面已恢复。在关闭所属页面之前，先在该页面上测试创建和导航。

• 请求的功能缺失时，请确认当前工具清单和 wrapper 配置。对于上述浏览器 UI 情况，包括不受支持的 chrome://extensions URL，请使用原生控件。其他情况则报告功能边界。不要降低已配置的隐私或并发默认设置。

只有在有最新工具证据证明请求结果已达成，并确认任务创建的页面已关闭或有意保持打开时，才能视为完成。