通过 Firefox WebDriver BiDi 端口接管已启动的浏览器，不新建进程、不导航页面，MCP 退出或 bridge 超时时保留外部浏览器。

在 ruyipage 指纹浏览器中打开新标签页并导航到目标 URL。支持配置代理、指纹伪装、无头模式、隐私模式。首次调用自动启动 Firefox 浏览器。

导航已有标签页到新 URL，或执行刷新/前进/后退。

关闭指定标签页。不能关闭主标签页（pageIdx=0）。

切换活跃标签页。

列出所有打开的标签页。

列出当前页面中的所有 iframe/frame（包括嵌套子 frame）。返回每个 frame 的 contextId、url、isCrossOrigin 信息。

选择指定的 iframe/frame。contextId（从 ruyi_list_frames 获取）最稳定；也可传 selector，由 ruyiPage 1.2.54 通过 iframe.contentWindow 精确映射 srcdoc 或同 URL frame。选择后的 frame 可在后续 evaluate_script 中通过 frameContextId 参数操作。

列出页面中加载的所有 JavaScript 脚本 URL。支持 URL 筛选。

获取指定 URL 脚本的源码片段。支持行号范围或字符偏移。

保存脚本完整源码到本地文件。JSON 结果用 .json 扩展名，其他用 .js。

在页面已加载的 JS 源码中搜索字符串或正则表达式。

在浏览器页面中执行 JavaScript 函数并返回结果。可用于运行时采样、Hook 注入、读取页面状态。函数必须返回 JSON-safe 值。支持接收本地文件作为参数。

读取浏览器控制台日志消息。支持按类型筛选。

对当前页面应用指纹伪装。可独立设置地理位置、时区、语言、UserAgent、viewport、outer window、screen 与 CSP 绕过。ruyipage 支持 22 维硬件指纹随机化（需在 ruyi_new_page 时通过 fingerprint 参数配置）。

模拟浏览器地理位置（经纬度）。

模拟浏览器时区。

模拟浏览器语言/区域。

自动处理 Cloudflare Turnstile 验证（5s 盾）。通过 BiDi 查找 CF iframe 并在内部触发点击，绕过 closed shadow root 限制。

模拟浏览器 UserAgent 字符串。覆盖 navigator.userAgent。

⚠ 代理必须在 ruyi_new_page 时通过 proxy 参数设置。浏览器启动后无法切换代理。此工具仅返回说明和当前代理状态。如需切换代理，请先 ruyi_browser_quit，再用新代理调用 ruyi_new_page。

在页面中定位 DOM 元素。支持 CSS 选择器、XPath、标签名、文本内容等多种定位方式。格式: "#id" / "css:.class" / "xpath://div" / "tag:input" / "text:登录"

读取 DOM 元素的文本内容、HTML、表单值和指定属性。

向 DOM 元素输入文本或上传文件。支持普通文本输入和文件路径上传。

点击 DOM 元素。

导出当前浏览器会话状态（Cookie、localStorage、sessionStorage、UserAgent、URL）。可保存到 JSON 文件供 js-reverse-mcp、ruyitrace 或其他工具复用。这是跨工具 session 桥接的核心工具。

获取当前页面的所有 cookies。

设置 cookies。传入 cookie 对象数组，每个对象需包含 name 和 value。可选字段：domain, path, secure, httpOnly, sameSite, expiry。

删除 cookies。不传 name 则清除所有 cookies。

列出最近的网络请求。基于 performance API 获取资源加载信息。需要更详细信息时，使用 ruyi_capture_start 主动抓包。

开始被动抓包。按 URL 模式匹配请求，后续用 ruyi_capture_wait 获取。

停止被动抓包。会先清空尚未消费的队列/历史，避免 ruyiPage stop 隐式补读全部 body；需要结果时应先调用 ruyi_capture_wait。

等待并获取抓包结果。在调用 ruyi_capture_start 后使用。默认返回完整 request/response body；内部按单包 RPC 排空，避免大批量补读拖垮 bridge。

注入 fetch/XHR Proxy 以捕获后续 JS 请求的调用栈。注入后通过 ruyi_list_network_requests 可看到带 initiator 的请求。⚠ 只能捕获注入后发起的 JS 请求；调用栈为 Error().stack 字符串格式。

开始拦截 HTTP 请求（beforeRequestSent 阶段）。支持 URL 模式过滤。拦截的请求用 ruyi_intercept_wait 消费。可修改/拦截/模拟请求（未来版本）。

开始拦截 HTTP 响应（responseStarted 阶段）。支持 URL 模式过滤。拦截的响应用 ruyi_intercept_wait 消费。

等待并消费一个拦截到的请求/响应。队列模式：每次调用返回一个。超时返回 timedOut=true。返回 url、method、headers、body、responseStatus 等。

停止所有网络拦截。

设置软断点（通过 preload script 注入 debugger 或 Proxy 包装）。支持 XHR/Fetch URL 断点和函数名匹配。⚠ 当前 BiDi 不支持完整的 CDP 式断点调试，此工具注入 debugger; 语句作为替代。

在 XHR/Fetch 请求 URL 匹配时触发断点（注入 debugger）。等价于 ruyi_set_breakpoint_on_text with XHR wrapper.

列出当前所有活跃的软断点。

移除指定软断点。

列出所有已注入的 preload 脚本。每个脚本有 scriptId 和内容摘要。

模拟人类鼠标移动到目标元素。支持 bezier 曲线和 windmouse 算法。需要反检测场景下的鼠标操作，这是 js-reverse-mcp 不具备的能力。

执行原子的拟人鼠标拖拽：move → hold → wait → human_move → wait → release。ruyiPage 1.2.54 会把按下到释放合并为单次 BiDi input.performActions，适合滑块、排序和 drag-and-drop 场景。source/target 可用选择器或 viewport 坐标。

使用 Firefox 原生 wheel action 做单方向、小步、随机间隔滚动。不会定位元素或自动回滚，适合阅读式下滑和翻页按钮渐进进入视口。

模拟人类鼠标点击。使用 windmouse/bezier 算法生成自然轨迹。

模拟人类逐字输入文本（带延迟）。避免被检测为自动化输入。

从当前时刻开始记录结构化 BiDi trace；首次在运行中的浏览器上启动时，会清空旧缓冲区并建立新的 trace 段。浏览器启动时已开启或重复调用时会保留现有缓冲区。浏览器启动后调用也会真实启用记录，但不包含此前的启动事件。如需覆盖启动阶段，请在 ruyi_new_page 时设置 traceEnabled:true。该工具记录 BiDi 协议级事件，不等同于 Firefox 内核 DOMTrace。

停止 BiDi 追踪并返回结果摘要和数据。

获取当前的追踪结果（不停止追踪）。返回最近的 BiDi 事件条目。

为所有后续请求附加额外的 HTTP Headers。用于注入认证 token、自定义 UA 等。

控制浏览器缓存行为。可选：default（默认）、bypass（跳过缓存）、force_cache（强制缓存）。

注入 WebSocket Proxy 以捕获后续 WebSocket 连接的消息。注入后，新创建的 WebSocket 连接的 send/receive 消息会记录到 window.__ruyi_ws_messages。⚠ 只能捕获注入后创建的 WebSocket 连接。binary 帧以 "[binary]" 标记。

获取已注入 Proxy 后收集的 WebSocket 消息。返回每连接的 url、sent、received 消息列表及时间戳。设置 clear=true 可在读取后清空缓冲区。

对当前页面截图。可保存到文件或返回 base64 编码（PNG）。

清除当前页面的浏览器状态：Cookie、localStorage、sessionStorage。

获取浏览器当前状态：是否存活、当前 URL、页面数量、断点数、preload 脚本数。

关闭由 MCP 启动的浏览器并清理状态；端口接管的外部浏览器只断开连接，不关闭进程。