WebKitUI MCP

WebKitUI MCP

面向 Apple Silicon 的原生 WebKit 自动化，通过 MCP 提供，专为大模型而非人类设计。

此仓库是用 Swift 重写的版本。保留的 TypeScript/Playwright 文件仅供参考，并非本次扩展的实现。

现有功能

• 使用持久化系统 WebKit 数据存储的原生 WKWebView 运行时，可使用真实的已认证会话。
• MCP 2026-07-28 stdio 服务，兼容旧版初始化方式。
• 十三种范围受限的工具，包括已认证的原生下载、明确的页面/元素滚动，以及对已渲染虚拟化日志的范围受限文本提取。
• 观察作用域内的元素符号，由语义定位器方案支持，并在执行操作时重新解析。
• 五种独立的寻址计数：address_resolution_failed、address_now_ambiguous、logical_target_changed、node_replaced_but_semantic_locator_recovered 和 coordinate_invalidated_by_layout_change。
• 为每个序列化页面字符串附加来源信息。
• 观察时进行隐私最小化：在计算范围前移除未渲染的控件；敏感字段/类似令牌的字段绝不序列化其值；敏感选择框既不会发布其选项标签，也不会透露选项数量或当前选中的选项——已选标签就是该控件的值。仍会报告该控件及其角色和无障碍名称，以便交由人类处理。
• 检查点加增量的观察历史，以及最小失败集覆盖率指标。
• 可选的本地 Ollama 排序器，使用 think: false、严格预算和确定性回退机制。
• 事务账本包含前置条件、精确后置条件、幂等键、不确定结果、收据，以及不重放的对账机制。
• 每次公开的点击和开放世界导航都需要人工确认。导航默认使用服务端管理的原生 macOS 对话框，避免客户端静默拒绝往返确认；MCP 多轮导航需选择启用。
• browser_session 可设置范围受限的 320×240–3840×2160 CSS 视口，并可使用 WebKit 自带的历史记录列表前进、后退或重新加载。历史记录移动会根据 WebKit 报告的目标页面进行确认；对表单提交生成的页面重新加载会在确认前被拒绝，以防重放。
• 原生 WKUIDelegate 始终拒绝摄像头、麦克风和地理位置请求。观察结果会注明请求来源和权限，并统计重复请求，同时限制不同记录的数量；不存在可授予权限的 MCP 操作。
• 确认信息会注明提交控件的数据将发往哪个来源；该来源由服务端根据重新解析后的元素计算，而非依据其无障碍名称。如果该来源与操作者当前所在页面不同，也会明确说明。提交按钮的 formaction 会覆盖其表单的 action，因此无障碍名称看似无害的控件可能会将数据提交到其他位置。
• 确认次数按滚动的 60 秒窗口计数。从第五次起，对话框会注明已请求的确认次数；第 20 次请求会被拒绝，而不会显示对话框，因为人类连续点击 20 次的对话框已不再构成有效拦截。
• 旧版 MCP 客户端通过服务端管理的原生 macOS 确认对话框，获得相同的精确操作授权边界；模型无法提供或伪造批准值。
• 本地人工接管：handoff_start 会立即返回一个与会话绑定的不透明恢复令牌，同时将实际的 WebKit 会话显示为可见窗口。handoff_status 不会阻塞；只有经本地确认后，handoff_resume 才会使用该令牌并返回新的观察结果。人工控制期间，Agent 始终无法操作会话。 交接回复包含本地化的 return_control_button_label。归还控制权表示确认人工步骤，并不代表远程保存已完成。参数因操作而异：handoff_start 仅接受操作 ID／会话 ID；状态查询还需恢复令牌；恢复操作另外接受 compact/maximum_elements。计时参数适用于后退／前进／重新加载，而不适用于交接。对于无法安全解析条件架构的客户端，发现机制仍不依赖组合架构。
• 不改变页面控制权归属的前提下，可通过 handoff_focus 再次将当前人工控制窗口置于前台。会话状态会说明该界面当前是否正在显示；受限的身份验证状态仅公开范围受限的渲染布尔值，绝不公开页面文本、字段值、私有 URL 组成部分或网络负载。
• 打包的交接应用会安装原生“编辑”菜单，因此 Command-X/C/V/A 等标准第一响应者快捷键可在 WebKit 表单控件中使用。
• MCP 会话使用环回 SOCKS5 边界，每个配置文件一个，由其会话共享，并禁用故障转移：主机名仅解析一次，公共地址会被固定；私有／保留目的地以及非 TCP SOCKS 命令均会默认拒绝。
• 对于同一个 macOS 账户，同一时间只有一个进程可以控制浏览器：主机租约属于该进程，并在其最后一个会话结束或进程退出时释放。生产版 CLI 持有一个会话。
• 私有远程客户端可使用应用自有的代理程序和强制命令 SSH 中继；WebKit 和经过身份验证的配置文件数据仍保留在已登录的 Mac 上。
• 多个中继客户端可以并发使用同一个长期运行的代理程序，各自拥有独立会话和窗口，最多三个，并共用默认配置文件。一个会话仅属于一个客户端：其他客户端会收到 session_in_use 和 wait_only=true，无法查看、导航、操作、使地址失效或请求重复的人类控制权。拥有该会话的客户端断开连接后，或通过人工确认的 client_handoff，会话才会转移所有权。应用会逐一显示原生确认提示，每个提示都会将请求 Agent 自行报告的名称加引号显示。
• 每项独立任务都必须调用 browser_session(operation: "open")，并在所有页面操作中使用其返回的 session_id。在共享传输中，如果打开操作会返回一个已被占用的页面，已满的代理程序会拒绝该操作。不提供 ID 的状态查询会选取调用方唯一的会话；若调用方拥有多个会话，则会要求提供明确的 ID。尚有空余容量的新客户端会被引导打开自己的页面。主机租约元数据会报告代理程序剩余的会话名额。
• 当有人使用人工控制窗口时，页面打开的弹出窗口（例如 Google 或 Apple 登录窗口）是真实窗口，与页面共享配置文件、受保护的代理和 window.opener，最多四个；Agent 恢复控制权时，这些窗口都会关闭。在 Agent 控制期间，普通新窗口仍会被拒绝并报告。经明确批准的下载可以保留一个请求范围内的导出视图，使用原始配置／配置文件，且不会替换页面。该视图仅接受同源 GET 附件响应或 Blob 下载；在请求结束时关闭，且绝不会成为 Agent 可见的标签页。
• 即使 MCP 客户端重新连接，应用代理程序也会持有一个正在运行的浏览器。每次重新连接时，代理程序都会先使观察结果、待处理审批、能力和事务协调器失效，再返回保留的会话句柄。
• 原生主机会先启动 AppKit 事件循环，再处理 MCP 工作，并将正在运行的 WKWebView 固定在一个不透明窗口中。Agent 控制期间，该窗口会从屏幕上隐藏；交接给人工控制时，则会显示同一个视图，不重新挂接窗口。打包的视觉冒烟测试模式会检查 WindowServer 的实际像素。
• stdio 中继会在代理程序重启期间保持运行。它会在处理下一个尚未分派的请求前重新连接，并且绝不会静默重放重启期间结果变得未知的请求。
• 不提供会话 ID 也可查询持久的多客户端状态，且只会报告保护隐私的持有者元数据（客户端名称／版本、PID、时长、非活动时间和策略）。open(wait_timeout_ms: ...) 最多可等待 60 秒以获取本地主机租约，但不会抢占租约；失效的传输会释放其会话所有者。browser_session(operation: "client_handoff") 只能在本地人工确认且最终检查确认没有活动调用后，转移空闲会话。
• 不含密钥的 SiliconPass 填充操作可能返回 credential_not_found；随后，WebkitUIMCP 会提供原生人工交接，以便手动登录并在 SiliconPass 中添加／更新凭据。凭据值不会经过 MCP、JSON、日志或剪贴板。
• 网页内容终止时会立即使所有观察结果失效；恢复时会重新加载由主机持有的上一个 URL，不会重放操作。强制崩溃测试夹具会验证：在同一视图／数据存储生命周期内，HttpOnly 已通过身份验证的 Cookie，以及 localStorage 和 sessionStorage 均能保留。
• macOS 配套应用是带本地活动窗口的常规 Dock 应用。它只会记录列入允许列表的 MCP 工具名称、结果、时间戳、耗时和范围受限的错误类型。参数、URL、页面内容、凭据、Cookie、按键和响应正文在结构上不会被记录。仅所有者可访问的 JSONL 文件会自动轮换，也可从应用中导出或清除。

Deliberate limits

• browser_act 提供点击、原生提交控件点击、有界非敏感输入框/文本区域填充、Enter/Tab/Escape、失焦、显式输入提交，以及回答页面当前挂起的一个 JavaScript alert/confirm/prompt 对话框（dialog_accept、dialog_dismiss、dialog_accept_value）。观察结果会将待处理对话框报告为不可信网站内容；在回答之前，它会阻止所有其他操作，绝不会自动回答；如果无人回答，则会以明确的未定结果结束。beforeunload 不在支持范围内：公开的 macOS SDK 未向嵌入方提供 before-unload 面板。Native approval 还会通过 AppKit 插入来执行公开文本填充，并提供经过测量的可信 input 回执。填充操作会验证刚刚重新解析的语义目标值完全一致，且其实时验证状态不是无效。其他操作支持以下后置条件：精确 URL 或 URL 前缀、标题、标题文本、精确/包含的语义文本、选中状态、已选择状态、启用状态、语义目标不存在（target_absent，且 value="true"）、值、验证状态、字符数、有界状态属性、对话框、命名面板或所选选项。相同 URL 的 SPA 变更会返回 same_url_page_state_changed 指引，而不会暗示操作成功。UI 状态无法证明后端已提交。
• browser_download 会将经过身份验证的附件响应转换为 WKDownload，来源可以是新观察到的控件，也可以是受保护的同源 URL 回退方案。它要求精确的原生确认以及保存面板中的目标位置，绝不会覆盖现有文件；只有磁盘回执报告了 HTTP 状态、建议/最终文件名、MIME 类型、字节数、SHA-256，以及可用时解码出的配置描述文件 UUID 后，操作才算成功。Cookie、标头和本地绝对目标路径不会暴露给 MCP。
• macOS 文件输入使用 WebKit 的原生打开面板委托。所选普通文件最多 10 个，每个不超过 50 MiB；回执可以披露文件名、字节数和 SHA-256，但绝不会披露本地路径或文件内容。文件选择回执并不代表服务提供方已接受文件：操作的独立后置条件仍须验证上传预览或已保存状态。
• 请直接对刚观察到的文件输入框或打开文件选择器的标签/按钮调用 browser_upload，包括菜单中的上传按钮。若先用 browser_act 打开文件面板，会留下待处理的选择器，browser_upload 会在没有再次点击的情况下拒绝操作。请通过人工接管完成或取消该选择器，交还控制权并核对状态，然后再开始新的上传。即使单独的回执证明已选择文件，缺少手势证据仍表示结果不确定；绝不自动重放。
• 填充操作会分派常规的 input/change 事件，因此网站处理程序可能自动保存或产生服务器端效果。该操作需要人工授权（精确批准或明确记住的交互范围）；密码控件需要本地人工接管。
• approval_mode: "native" 会通过公开的 AppKit NSEvent 处理，在刚刚重新解析的 WKWebView 目标上发送已确认的点击/提交和 Enter/Tab/Escape。独立消息处理程序必须观察到匹配的 DOM 事件，且其 event.isTrusted == true，回执才会报告可信。缺少或不匹配的回执会导致未定失败；不会伪造标记。approval_mode: "mcp"、失焦和提交仍由 JavaScript 分派，并报告为不可信。公开文本填充只有在观察到匹配的 AppKit 插入回执时才会报告可信。
• 操作结果会分别公开 confirmation_mode、dispatch_mode 和 trusted_gesture_state。仅有原生确认绝不能证明事件可信。
• 导航就绪状态与渲染内容可用性相互独立。文档可以达到 readyState=complete 并且变更已静止，但页面仍然空白； 在这种情况下，导航、观察和文本读取会报告 empty_or_unusable，并明确禁止将内容缺失视为页面事实。已渲染但没有文本的画布或媒体文档仍然是 usable。
• browser_read_text 只读取当前已渲染的虚拟化行。要读取其他范围，请进行有界滚动后再次读取。
• 不提供任意 JavaScript、原始 CDP 逃生通道、坐标重试、代理集群、反机器人绕过或无头模式声明。默认情况下，每项操作都需要精确确认；用户可以明确选择启用下文所述的有界记忆权限。这只会针对用户选定的网站、配置文件和操作改变默认权限边界。
• 调整视口大小只会改变桌面 CSS 布局，不会模拟移动设备——公开的 macOS SDK 未提供 WKWebView ContentMode API——而且我们刻意不提供 set_emulated_media，因为它无助于操作用户的网站。
• 无法通过 WebKitUI MCP 授予摄像头、麦克风和地理位置访问权限。请求会被拒绝，并在下一次观察中报告，而不会让页面故障悄无声息；如果工作流需要其中某项权限，请在完整浏览器中使用人工控制。
• 不支持多个 Agent 可见的标签页。与请求绑定的导出视图仅用于受管下载；普通弹窗拒绝和由人工控制的登录窗口则分别处理。一个会话持有一个独占的主机租约，确保批准对应于明确的页面。
• 不检查子资源或 XHR 请求。虽然技术上可以实现，但我们不会提供此功能。macOS 14 起公开了 WKWebsiteDataStore.proxyConfigurations，这是 Apple DTS 自己推荐的读取 WKWebView 请求内容的方法；macOS 15.4 起也公开了带有 webRequest 权限的捆绑式 WKWebExtension。但两者都有代价：代理方案需要受信任的根证书才能查看 HTTPS 内容；扩展方案不会报告标头，也无法阻止请求。实际报告的内容则很有限——下载回执中的 HTTP 状态，以及出口代理接受、拦截、固定和超时的连接数。目前主框架导航结果不包含 HTTP 状态，代理也不会指出其允许或拒绝的主机。
• 原生 AppKit 分派并非独特功能，我们也不会声称它独特。safaridriver 会通过 [window sendEvent:] 分派 NSEvent，方式与此完全相同；WebDriver 规范要求所有符合规范的驱动程序都产生可信事件。区别在于测量方式：若缺少或不匹配可信 DOM 回执，这里的操作会以未定结果失败；而 Playwright 的命中目标拦截器会将缺少事件视为成功。
• WKFormInfo 提交门控已实现并通过单元测试，但不会触发。在这里测量的 macOS 27.0 两个构建版本 26A5416b 和 26A5419a 上，WebKit 都没有调用 webView(_:willSubmitForm:submissionHandler:)——无论是 submit()、requestSubmit()，还是原生可信手势点击都不会触发。因此，它并不是第二道生效中的门控，不应被这样理解；如果 WebKit 开始发送回调，它才会作出判断。针对会向其他网站发送数据的提交控件，当前有效的防护是在确认信息中显示目标地址。
• 已注册的跨源框架会暴露有界的已渲染语义信息，来源标记为 THIRD_PARTY_EMBED，并提供经过净化的来源地址。其几何信息明确属于框架局部坐标；即使 actionable=false 意味着没有原生指针几何信息，frameActionModes（或简写 frame_action_modes）仍会列出符合条件的尝试。已确认的 hover 或 select_option 只会作为不可信 JavaScript 在精确的子框架中运行；非敏感的 press_key 和 fill 只有在该框架返回匹配的可信 DOM 回执时，才可以使用 AppKit。由于没有公开的框架到窗口坐标变换，原生指针点击会在确认之前以 cross_origin_native_geometry_unavailable 拒绝，并提示进行实时人工接管。这种能力只提供有界控制，不代表托管结账已经完成。敏感控件和身份验证控件仍需要人工操作。无法求值的框架以及超出有界原生注册范围的框架，仍会明确标记为不可读取，而不会被视为空页面内容。
• 某些身份提供方要求完整的浏览器界面，且不会在应用内嵌入的 WKWebView 中渲染（例如缺少浏览器 passkey 权限时仅支持 WebAuthn 的步骤）。这类情况会返回 full_browser_required，并附带内部 safari_compatibility 要求。任何 HTTP(S) 页面也可以使用 compatibility_start，作为原生渲染问题的明确手动回退方案。browser_session 配合 operation: "diagnose" 会返回有界的结构性加载和错误计数，不包含控制台消息或请求 URL。脚本计数描述的是结构，不代表已证明加载停滞的原因。使用 start 或 focus 显示原生窗口；handoff 用于切换控制权。只有经过原生确认后，该操作才会在 Safari 中打开精确的私有 URL；不会仅因页面超时就自动切换，不会取代原生人工接管，不提供 Safari 观察或控制能力，也无法将 Safari 登录状态返回给此 MCP 会话。请在外部浏览器中手动完成受阻的工作流。WebKitUI 绝不会在不同后端之间复制 Cookie、passkey、AutoFill 数据或凭据。
• takeSnapshot 可能会省略 GPU 合成效果。
• 不保证对不配合的网站实现恰好一次操作或回滚。
• 有意限制并发，因为 WKWebView 没有针对单个视图的硬性内存配额。
• 受保护的网络路径是 MCP 会话注册表或 WebKitRuntime(protectedWebsiteDataStore:)；较底层的 WebKitRuntime(websiteDataStore:) 初始化器有意不受保护，用于测试固件和嵌入场景。
• 这是一种有界的网站流量控制方案，不是完整的进程出口沙箱。经过精确测试的传输方式、排除项和安全使用规则见 docs/network-boundary.md。

与 Safari MCP 服务相比

Apple 的 Safari MCP 服务内置于 safaridriver 中，并通过 safaridriver --mcp 启动；Apple 对该标志的官方帮助文本是“以使用 stdio 传输的 MCP（Model Context Protocol）服务模式运行。”它提供 17 个工具——页面内容、屏幕截图、网络请求、控制台日志、JavaScript 求值、DOM 交互、视口和媒体模拟、标签页管理。它需要在两个不同的设置面板中配置两项设置：“在 Safari > 设置 > 高级中显示网页开发者功能”，以及“在 Safari > 设置 > 开发者中允许远程自动化和外部 Agent”。Apple 要求至少使用 Safari 27 beta 或 Safari Technology Preview 247；Apple 也记录了 Safari 27 beta 可用于 macOS 26 和 macOS Sequoia，以及 macOS 27，因此它并非 macOS 27 的专属要求。

Apple 面向网页开发者设计了这项功能：它“让你的 Agent 能够了解你的代码在浏览器中的实际渲染效果”，而两份发行说明都将其列在 WebDriver > 新功能下。Apple 还表示，它“完全在本地机器上运行，不会自行发起网络请求”，并且“无法访问你在 Safari 中的个人信息（例如自动填充内容或其他浏览器活动）”。对于网站开发来说，它是更好的工具，且随 Safari 一同提供，Apple 未列出单独价格；本项目并不与它竞争。

当网站不是你自己的，而且你已登录该网站时，区别如下：

	Safari MCP 服务	WebKitUI MCP
目的	检查和调试你正在开发的网站	操作你已登录的网站
批准	文档中没有说明确认步骤，17 个工具也都不要求确认	每次执行已公开的点击和开放式导航前，都需要原生 macOS 确认
工具注解	无：每个工具仅包含 name、description 和 inputSchema，因此客户端无法区分读取页面与执行 JavaScript	每个工具都包含 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint
JavaScript 求值	作为工具提供	不提供，也没有 CDP 或坐标回退方案
会话	Apple 的 WebDriver 文档指出，自动化窗口“与普通浏览窗口、用户设置和偏好设置相互隔离”，且会话“总是从干净状态开始”	自有的 WKWebView 和持久化配置文件，这是执行已登录操作所需的
协议	报告 2024-11-05	2026-07-28，当前修订版
网络细节	完整检查请求，包括标头、正文和时序	不提供逐请求检查：仅提供下载回执中的 HTTP 状态，以及不含主机名的出口代理连接计数
验证	检查工具	每项操作都有明确的后置条件，另有独立的 confirmation_mode、dispatch_mode 和 trusted_gesture_state

上文所述的隔离措辞出自 Apple 的 WebDriver 文档，针对的是一般自动化会话。Apple 尚未发布关于 MCP 服务本身的同类说明。

两者可以同时安装，大多数开发者也都应该这样做。

关于 Apple 的服务，本项目不会声称以下两点，因为 Apple 并未这么说：它无法访问你的 Cookie 或已登录会话——Apple 的 MCP 帖子只提到了自动填充内容和“其他浏览器活动”；以及 Apple 明确表示不存在确认步骤。文档说明了相关内容的缺失，但并未作出否认。

构建和测试

该产品面向搭载 Apple silicon、运行 macOS 15 或更高版本的设备。构建可选的 WKJSHandle 探针需要 macOS 27 SDK；这些 API 仍受功能门控。

swift build -c release --arch arm64
xcrun swift-format lint --strict --recursive Sources Tests Package.swift
swift test --arch arm64
swift test -c release --arch arm64

如需对当前检出版本、已签名的本地安装及其双客户端传输进行可复现的验证：

scripts/verify-native-installed.sh

运行服务：

swift run -c release --arch arm64 webkitui-mcp

注册前，运行不涉及机密信息的本地就绪检查：

webkitui-mcp doctor

该检查会验证原生确认助手、本地所有者身份验证策略、架构、macOS 版本和本地存储的许可证状态。它不会打开网站、读取浏览器数据或凭据、验证用户身份，也不会联系许可证服务。

webkitui-mcp --help 会打印 stdio 协议约定，但不会启动服务。 同级的 webkitui-mcp-confirm 助手负责处理旧版原生对话框，避免关闭 AppKit 警告框时终止或损坏长期运行的 stdio 服务。

进程从 stdin 读取以换行符分隔的 JSON-RPC，仅向 stdout 写入协议响应，并将 stderr 专用于诊断信息。

如需运行一次性的直接进程，请安装 CLI 并按常规方式注册：

release_bin="$(swift build --show-bin-path -c release --arch arm64)/webkitui-mcp"
release_dir="$(dirname "$release_bin")"
install -m 0755 "$release_bin" "$HOME/.local/bin/webkitui-mcp"
install -m 0755 "$release_dir/webkitui-mcp-confirm" "$HOME/.local/bin/webkitui-mcp-confirm"
codex mcp add webkitui-mcp -- "$HOME/.local/bin/webkitui-mcp"
claude mcp add --scope user webkitui-mcp -- "$HOME/.local/bin/webkitui-mcp"

将两者一起安装，并让它们并排放置。显示确认框前，服务会检查其旁边的助手；它能强制执行哪些要求，取决于服务本身的签名方式：

• 经过公证的服务会固定其 Developer ID 团队和发布脚本写入的准确标识符，因此无人能在它旁边放置自己的助手；
• 从源代码构建的服务采用临时签名，没有这两项信息，因此检查只能要求助手以自身名称放在服务旁边。这不会泄露任何信息：能够在未签名服务旁边写入助手的人，也能替换该服务。

两个方向都不允许混用。如果你重新签署其中一个二进制文件，也必须使用相同身份重新签署另一个；否则确认框不会显示，所有导航都会安全失败。

确认框的键盘行为

确认框使用非激活面板：调用方仍是活动应用时，它也可以接收键盘输入，且不会在 Dock 中添加单独的助手图标。源码构建和经过公证的应用共用两项偏好设置，用于决定键盘可以执行哪些操作：

# Return cancels and Escape closes after 1 s of initial keyboard focus (default).
defaults write com.lorislab.webkitui-mcp ConfirmationKeyboardDefault cancel
# Return/Escape have no default action; click, or Tab to a button then Space.
defaults write com.lorislab.webkitui-mcp ConfirmationKeyboardDefault none
# Arming delay for Return/Escape, 0 to 5 seconds (default 1).
defaults write com.lorislab.webkitui-mcp ConfirmationArmingDelaySeconds -float 2

启用延迟从初次显示并取得键窗口后开始。排队的 Return/Escape 输入会根据其原始事件时间戳进行检查。初始时没有按钮获得焦点： 意外按下 Return/Space 不会触发操作，且在启用延迟结束前会忽略 Escape。使用 Tab 和 Space 有意选择按钮，或单击按钮，仍然有效。在 none 模式下，Escape 始终处于禁用状态。 “批准”绝不会成为键盘默认选项，也无法将其设为默认选项。本地 始终允许… 菜单允许用户选择仅允许导航，或允许导航以及点击/输入；授权范围可以是此客户端/会话，也可以针对确切的网站和浏览器配置文件记住。通过“取消”或“仅批准一次”不会记住任何内容。永久权限适用于使用该配置文件的所有 Agent，而非自报身份的客户端；隐私配置文件仅提供会话级选项。来源包含 scheme 和端口。即使网站未标明交互的影响，交互也可能发送、修改或删除数据。原生表单提交、下载/上传、对话框、身份验证和控制权转移仍需分别通过各自的审批门槛。MCP 参数不能授予权限。使用状态菜单中的撤销已记住的网站权限可清除会话级和永久授权；此操作仅影响后续操作，无法撤销已分派的操作。回执通过 authorization_source 区分已记住的授权和针对确切操作的确认；事件可信度仍需单独的回执。

对于必须在 Codex 对话重新连接后继续保持的已验证会话，请改为构建独立应用：

scripts/package-preview.sh dist
scripts/verify-package-preview.sh dist

人工控制期间，⌘F 会打开本地原生页面搜索；⌘G 和 ⇧⌘G 可在匹配项之间移动，按 Escape 可关闭搜索。搜索查询不会通过 MCP 暴露。非人工控制期间以及附加原生保存面板时，搜索会被禁用。

受管下载需要先获得批准，再选择原生保存位置：选择文件夹并点击 保存。这并不能证明传输已完成；只有经过验证的下载回执才能确认交付。取消、撤销请求或关闭源窗口都会关闭保存位置面板。不受管的手动下载仍不受支持；不要盲目重试被拒绝的受管下载。

解压 WebKitUI-MCP-0.6.42-preview.zip，将 WebKitUI MCP.app 移至 Applications 文件夹，然后打开它。在状态窗口中：

1. 启用 登录时启动。macOS 可能要求你在“系统设置”中批准。
2. 复制并运行 Codex 设置命令。该命令指向嵌入应用程序包中的中继，以及仅所有者可访问的本地 Unix 套接字。
3. 注册后，请将应用保留在 Applications 文件夹中，以确保保存的中继路径仍然有效。

应用程序包还包含固定版本的 SiliconPass 保管库 MCP 连接器，位于 Contents/Resources/CredentialBroker/siliconpass-vault-mcp。它仍是一个精简且不含密钥的客户端，连接到单独安装并解锁的 SiliconPass 凭证代理；WebKitUI 不包含保管库、其密钥或凭证导出文件。仅在安装匹配的 SiliconPass 代理管理器后配置它：

此源固定了本地验证的管理器 0.2.5 (22)、包含十个工具的保管库 MCP 0.3.0 合约、精确的连接器字节以及机器码哈希。软件包检查会列出工具并拒绝无效的密钥参数；它们不会读取或修改保管库。这是已安装版本的固定声明，并非对上游最新版本的声明。

codex mcp add siliconpass-vault -- \
  "/Applications/WebKitUI MCP.app/Contents/Resources/CredentialBroker/siliconpass-vault-mcp"

活动日志按钮会打开本地的隐私安全事件历史记录。 其文件存放在 ~/Library/Application Support/WebkitUIMCP/Activity 下，并且仅所有者可访问。轮换最多保留七个 5 MiB 归档文件，以及当前活动文件。清除会删除活动文件，但保留事务回执；导出只会写出相同的脱敏事件架构。

该应用使用 Apple 的 Service Management API，不会在 ~/Library/LaunchAgents 中安装可变的 plist。准备卸载会禁用“登录时启动”，同时保留回执和许可证数据；然后退出应用并将其移至废纸篓。预览版压缩包未签名。签名、公证、在全新 Mac 上安装以及发布均为单独的发布门槛。

每个 MCP 客户端都会在同一持久化浏览器上获得相互隔离的观察、确认、事务和能力授权。逻辑上的 browser_session close 会解除该客户端权限，但有意保留活动浏览器；退出应用则会销毁此内存中的页面会话。

请重启在注册前开启的对话：运行中的对话所使用的 MCP 工具目录是固定的，不会被追溯替换。

确认超时不能证明用户看到了面板。queue_timed_out 表示未启动任何助手；否则，除非经过验证的助手提供了有时限的原生显示回执，否则 confirmation_presented 为未知（null）。回执仅包含不透明的请求 ID、进程／窗口 ID、时间信息、AppKit 可见性／焦点／屏幕标志，以及生命周期／决策枚举，不会包含请求的操作或目标位置。 助手运行期间可获取待处理元数据；每五秒重复采样一次。 解析限制为 16 KiB 和 32 条记录，并要求请求／PID 精确匹配。 这些是诊断证据，不代表批准，也不能证明用户确实看到了内容。 人工控制窗口和确认面板会显示相同的短会话标签； owned_by_this_client 标识的是传输连接，而非单个任务。 工具发现会为无法导入 JSON Schema 交叉类型／联合类型的客户端发布不含组合类型的强类型对象架构。运行时仍会严格强制执行条件操作要求。例如，原生点击需要最新的 session_id、observation_id、element_id、idempotency_key、operation: "click"、approval_mode: "native"，以及类似 {"type":"checked_equals","value":"true"} 的后置条件。填充操作则提供 operation: "fill" 和 value，且禁止自定义后置条件：系统会自动检查精确值和 DOM。上述示例不赋予对其他任务的会话执行操作或绕过确认的权限。

SiliconPass 控制请求的传输时限为 15 秒；凭据传递为提供方的原生交互留出 330 秒（300 秒加上回复余量）。调用结束后，其回调接收端会失效：延迟到达的回调无法启动填充操作。失败信息仅显示固定的阶段／类别和审慎的恢复建议，绝不包含远程错误文本或凭据字节。传输失败并不能证明填充操作未发生：请进行检查或转交给相关人员，切勿自动重试。

MCP 流程

有关长对话框、定向列表滚动、精确定位待确认项和安全的向导后置条件，请参阅有界交互工作流。 DOM 就绪不等于业务就绪，也不能证明远程保存已完成。

1. 使用 browser_session { operation: "profiles" } 列出无密钥持久配置文件，然后使用 browser_session { operation: "open", profile_id: "default" } 打开它。
2. 默认情况下，browser_navigate 会打开一个要求确认原生精确目标地址的对话框。仅当客户端可靠支持多轮引导时，才使用 approval_mode: "mcp"。
3. 调用 browser_observe；必要时使用 element_scroll_into_view、browser_scroll 或 browser_session { operation: "set_viewport", ... }，然后再次观察。back、forward 和 reload 是需要原生确认的会话操作。
4. 将最新的 observationID 和 elementID 各使用一次。
5. 对登录表单，调用 browser_fill_siliconpass。如果返回 credential_not_found，请接受原生交接，并直接在 SiliconPass 中添加或更新凭据。
6. browser_act 会返回 input_required；请批准确切的绑定操作。
7. 使用 browser_transaction 读取、导出为规范格式 ReceiptV1，或核对回执。一个经过脱敏的规范对象会生成 JSON 和 Markdown 两种格式；仅导出幂等键的 SHA-256。导出的证据绝不授权重放操作。

无需返回过大的 MCP 结果，即可读取大型语义页面：browser_observe 支持角色／名称筛选、maximum_elements、maximum_field_characters 和 element_offset；请继续使用 nextElementOffset，直到该字段不再出现。 强制执行的限制和剩余的发布测量项见 docs/performance-budgets.md。 权限边界、攻击路径、当前控制措施和剩余发布门槛见 docs/security-threat-model.md。 本地数据保留期限和显式导出的边界见 docs/privacy-retention.md。 稳定的诊断允许列表和禁止用于支持的数据见 docs/support-diagnostics.md。 手动签名更新、回滚、支持和事件处理规则见 docs/release-maintenance-policy.md。 当用户持有人工控制窗口时，如果已安装 SiliconPass broker，窗口栏会提供 Fill with SiliconPass。由用户发起请求，而非 Agent：WebKitUI 会绑定当前使用的框架中唯一一个可见的密码表单，包括 idmsa.apple.com 等受限登录框架；SiliconPass 会根据该框架的精确主机名匹配已保存的登录信息。凭据会通过 AppKit 输入到两个字段中，因此页面会收到真实的输入事件；不会提交表单，也不会有任何内容传到 MCP、日志或 Agent。

SiliconPass 凭据释放的安全保护有意强于普通浏览器确认。用户批准精确的原生填充摘要后，macOS 会评估 deviceOwnerAuthentication；该操作不复用 Touch ID，并将可用的认证方式交由 macOS 决定。WebKitUI 不会推断特定 Mac 是否支持 Touch ID、Apple Watch、密码回退或合盖认证。如果 Mac 处于锁定状态，或无法显示认证界面，WebKitUI 只会收到 user_presence_unavailable：不会释放机密，也不会自动重试。

受保护的浏览器绝不会连接到私有地址空间。唯一的例外是所有者 Tailscale 网络上的服务：导航到仅解析为 100.64.0.0/10 的名称时，会针对该确切源和端口请求原生 Allow Tailscale Access 确认。允许后，代理只会连接该主机上的该端口，并会防止 DNS 重新绑定；其他所有私有地址，以及同一名称的其他端口，仍会被拒绝。授权会持续到应用退出。任何其他私有目标都会返回 privateNetworkDestination，而不是不透明的 WebKit 错误。

idmsa.apple.com 等受限认证源只会返回其规范源以及本地交接要求。在用户离开该源之前，观察、文本、捕获、滚动、凭据填充和操作仍会被阻止。跨源重定向不会报告为含糊的 WebKit 故障，而是返回 redirect_requires_human_approval，其中仅包含源和目标源。

当 App Store Connect 嵌入该受限 Apple Account 源时，登录会像其他受限源一样通过原生人工交接进行。它过去会返回 full_browser_required：被测为卡住的框架是已停放窗口中的隐藏页面缺陷（已于 2026-09-23 修复），而非引擎限制。

默认情况下，导航会暂停，等待精确的原生 macOS 确认，并返回正常的终止工具结果。人工交接分为两次调用：第一次将控制权交给可见窗口；完成敏感步骤后，再次调用 browser_session { operation: "handoff", ... } 并批准原生恢复对话框。MCP 2026-07-28 客户端继续使用多轮 input_required 结果。 当需要由人类控制同一个本地 WebKit 会话时，请使用 browser_session { operation: "handoff" }。拒绝恢复后，人类仍保持控制权。 如果之前的交接令牌仍然有效，但控制权已交给 Agent，status 和 handoff_start 会指向 handoff 以供恢复。必须先在本地确认，才能使旧令牌失效并开始新的人工交接。确认后进行不带令牌的恢复，也会使之前的令牌失效。其他客户端的交接仍会被排除，进行中的人工操作会报告为仅等待。 如果点击导致跨源导航但该导航遭到拒绝，操作结果和 status 会报告一个 navigation_blocker，其中仅包含源和目标源以及人工交接指令。不会自动重放点击，也不会暴露私有身份验证请求。 语义外观和目标缺失后置条件要求基线未经过滤且未截断： 否则，postcondition_baseline_incomplete 会在派发操作前拒绝执行。 请以足够多的元素和字段字符数再次观察，以确认目标不存在。 被遮挡的控件会在 coveredBy（简写形式： covered_by）中标明命中测试检测到的遮挡元素。名称筛选器会规范化常见撇号；即使可见的内联 onclick 控件没有指针光标，也会将其纳入。大小相同且没有独立状态或显式处理程序的链接包装器会被省略，优先保留其链接。 交接窗口会变成带 Dock 图标的常规前台 Mac 应用，并使用与语义观察和捕获相同的渲染视图。

Linux 无头通道

linux/ 是一个独立的临时 Playwright 工作进程，用于专用 Linux VM 上的一次性工作负载。它不会继承 Mac Cookie 或密码，也不会取代原生 WebKit。将经过身份验证的会话和人工交接安排在 Mac 上；将公开、未经身份验证的无头工作安排在 Linux 上。请参阅 linux/README.md 和 docs/architecture/linux-headless-worker.md。

证据

• 架构：docs/architecture/
• 私有远程传输与部署门槛：docs/architecture/private-remote-transport.md
• 带日期的研究与 NotebookLM 审计：docs/research/
• 同一台 Mac 上的运行时基准：Benchmarks/README.md
• 公共／私有发布边界：docs/architecture/public-private-boundary.md
• 漏洞报告与发布不变量：SECURITY.md

带日期的对抗语料测量 记录了 53 项确定性测试，涵盖 57 次具体夹具执行，涉及来源信息、 对话框真实性、目标位置和导出泄漏。它衡量的是这些产品边界， 而非人类或模型攻击的成功率。

首个实测本地通道使用相同的确定性夹具，在 2560×1600 分辨率下运行 30 次。它将 WKWebView 与由 Playwright 1.61.1 驱动的已安装 Chrome 151 进行比较。目前尚未测量完整进程树内存、可见窗口行为、经过身份验证的任务成功率或 Playwright 固定版本的 Chromium 二进制文件；因此不作更广泛的优越性主张。

许可

WebKitUI MCP 0.6.22 Developer Preview 采用 Business Source License 1.1。源代码可阅读、可审计且可修改；获准用于个人非商业用途、符合条件的组织非商业用途以及评估用途。商业生产用途则需要与许可方签订协议。此版本将于 2030-08-28 转为 Apache 2.0。有关确切范围、第三方边界以及早期修订版本的处理方式，请参阅 LICENSING.md。

安全

模型无法生成能力句柄。页面内容永远不会成为可信策略。观测结果中会省略密码值。未知分发结果为不确定状态，且绝不会自动重试。项目本身不会执行提交、推送、部署或修改外部账户。

导航行为的归因依据是操作后两秒内首次发生的主框架导航。这只是诊断证据，并非因果关系或授权的证明：自主导航或延迟更久的导航可能会被错误归因。

消失或重命名的 Save/Done 控件无法满足 enabled_equals=false：该谓词要求原始语义目标仍然存在且处于禁用状态。若控件消失，请使用 target_absent，并设置 value="true"；也可以使用页面标题或文本谓词来判断结果页面。只有完整观测才能证明目标不存在；这表示不再观测到原始语义标识，但不能证明服务器端已持久化。分发后的结果若处于不确定状态，必须进行检查或对账收据，绝不能自动重放。

人工接管后的恢复

Safari 和 WebKitUI 使用独立的登录会话；请说明转交工作流前可能需要重新登录。在可见的 WebKitUI 窗口中，完成私密步骤并选择 Done — Return Control（法语：Terminé — Rendre le contrôle）。如果该选项隐藏，请使用 handoff_focus。口头告知已完成或导航结束，都不代表授权 Agent 控制。导航只能提示检查步骤是否完成，并不能证明远程保存成功。恢复控制仍需本地批准，并会返回新的观测结果。

SiliconPass 交付失败后，不要自动重试：交付可能已经完成。请立即提供 handoff_start，让用户自行检查并私下完成操作。对于 CAPTCHA，请让用户自行解决，并协助其使用网站官方提供的无障碍选项，包括音频选项；不要转录或破解挑战。

人工操作窗口提供 CAPTCHA / accessibility 帮助，以及 Focus website，用于将键盘焦点移回页面，而不会激活或提交任何内容。帮助会说明 Tab/Shift-Tab 的使用方法，以及提供时可用的服务商官方音频/无障碍控件。已知组件的导航 URL 可能会揭示潜在挑战，并自动打开此帮助；这类元数据提示并不完整，也绝不能据此认定挑战已完成。对于无法识别或嵌入式挑战，仍可使用帮助。此辅助功能不会提取任何组件文本、图像、音频、响应令牌或答案。

隐私提取失败时归还控制权

若新观测结果超出有界隐私清单的限制，明确授权的人工归还操作仍然有效。此时恢复操作仍会返回 resumed=true、control_state=agent_controlled、status=resumed_observation_unavailable、observation_available=false，且不包含观测结果。旧目标将失效。请使用确切目的地调用 browser_navigate 并按常规进行确认，以离开当前文档；也可以请求再次进行人工接管。不会重试任何写操作，也不会推断网站已保存。

privacy_budget 仅公开固定类别（values、characters、roots 或 unknown）、其未更改的上限以及已饱和的下界计数器。它绝不会包含已扫描的值或原始异常文本。以 browser_preserved=true 关闭会释放所有权，并保留当前页面和控制状态；重新打开 reused=true 的浏览器不会重置接管状态，也不会绕过隐私过滤。人工操作窗口没有 URL 地址栏；归还控制权后，请使用经确认的 Agent 导航，或在人工控制期间使用网站自身的链接。