LLM Wiki for Chrome

公开、无内容执行基底，用于针对性的 llm-wiki 适配器。它提供一个 Chrome 扩展、一个允许列表中的原生消息主机、一个私有 Unix 域套接字中继，以及一个带版本的类型化作业契约。

扩展和本地连接器源代码是公开的。浏览器权限、页面数据、凭据、私有结果槽和运行时套接字保留在本地，从未成为仓库内容。公开源代码可用性不代表 Chrome 网上应用商店发布或允许发布用户数据。

这不是一个自主的自然语言浏览器代理。它暴露一个小的结构化代理工具表面——共享标签页、无障碍快照、视口截图、语义点击、私有文本插入、按键组合和滚动——并将每个调用编译为相同的精确目标类型化协议。它不接受任意 JavaScript、原始 CDP 方法、下载的代码、环境浏览器访问或页面编写的操作。特定于提供商的适配器仍然拥有更强的路由、认证、日志、恢复、幂等性以及关键工作流的最终回读验证。

安装、协作、安全和故障排除指南 →

点击协作流程

扩展不需要持久的站点访问或每页 Chrome 主机注册。用户打开一个 HTTPS 页面并点击扩展操作。它在 Chrome 中的名称是 LLM Wiki for Chrome；浏览器执行器术语仅用于内部协议和实现。 该 Chrome 用户手势创建一个新的临时协作授权，绑定到确切的标签页、URL 和来源。点击其他标签页构建一个最多 16 个授权的显式工作区；执行器从不枚举不相关的标签页。同源导航会轮换确切的授权 ID 和 URL，因此过时的程序会安全失败。当标签页离开其来源、关闭，或用户在侧面板中停止该标签页或整个工作区时，授权被撤销。

一个活跃的授权在页面上显示为固定的绿色轮廓和“LLM WIKI • CONTROLLED”标签，以及一个“ON”操作徽章。该标记是打包的、非交互式的、对内容无感知，仅在扩展点击后注入；当授权被撤销时被移除，并且从不接收页面或作业内容。 操作监听器接收 Chrome 的 activeTab 授权，并同步打开该确切标签页的侧面板。面板加载确认操作创建的授权；中继的面板消息从不尝试打开面板或制造用户手势。其连接按钮是一个状态/重试控件，不能替代创建 activeTab 权限的工具栏手势。已连接状态意味着授权已通过实时本地连接器发布，因此代理可以使用 browser_status 检测就绪状态，而无需用户检查扩展内部。

本地代理和针对性适配器通过原生套接字检索私有工作区。直接代理必须首先列出确切点击的授权，并在每个工具调用中命名一个协作 ID。然后服务器编译一个固定的类型化程序，如果授权或页面已更改则安全失败。点击授权对该确切标签页进行有界读取和结构化交互；它从不授予环境浏览器访问权限。关键性提供商工作流仍然使用针对性适配器以获得更强的先决条件和独立验证。

适配器代码仍然需要安装并信任一次。协作授权仅替换每个资源的注册和提供商 OAuth，仅限于那些可以通过浏览器 UI 检查和验证的工作流。针对性适配器可能会保留第一方 API 作为可选更强的验证路径。

变异程序可以绑定提供商拥有的修订指纹与 assert_ax_private_sha256。执行器在受控变异边界之前，立即在确切暴露的标签页上重新计算有界无障碍投影，并在漂移时安全失败。预期的哈希仍然是私有值；它和投影的页面内容都不会显示在侧面板中。

提供商适配器直接使用捆绑的客户端：

from browser_executor.client import BrowserExecutorClient

executor = BrowserExecutorClient()
collaboration = executor.collaboration_for_url(expected_url)
if collaboration is None:
    raise RuntimeError("click the extension on the target page")

# Bind collaboration_id, url, and origin into the signed typed program.
result = executor.run(program, private_values=private_values)

Codex 和其他 MCP 客户端使用提供商中立的直接协作表面，而不是自行构建程序：

.venv/bin/python adapter.py mcp-server

MCP 服务器发布一个固定的结构化工具清单，涵盖显式标签页生命周期、确切同源导航、等待、无障碍快照、视口/区域/全页截图、元素几何、点击/悬停/输入/选择/拖拽/按键/滚动、有界诊断、注册根文件传输、密码管理器 UI 激活以及内存中工作流起草。它没有任意程序、CSS 选择器、脚本、自然语言执行工具或不相关标签页查询。页面内容仅返回给调用中的本地代理，不会由此仓库持久化或显示在侧面板中。

Related MCP server: browser-mcp

开发状态

当前开发分支扩展了 0.0.1 基础，包含第一个有界执行切片：

• 严格的程序哈希和验证；

• Python 客户端和 MV3 验证器的跨语言策略决策测试；

• 确切的 HTTPS 目标和有界动作声明；

• 点击创建的 active-tab 授权，无持久主机权限；

• 有界多标签页协作工作区，带私有确切 URL 查找；

• 每个 Chrome 实例的原生套接字由本地客户端聚合，因此多个 Chrome 配置文件或进程不会覆盖彼此的共享标签页；

• 固定的页面轮廓/标签和工具栏徽章，显示哪些标签页被控制；

• 绿色 LLM Wiki 标签组，仅包含显式授权；

• 同源打开/导航/历史/重新加载、确切标签页聚焦/关闭、语义等待、悬停、选项选择、拖放和滚动到元素原语；

• 扁平化、有界无障碍集合，跨越附加的子帧目标，包含会话绑定的几何和交互；语义 AX 发现也覆盖开放的影子树，而不启用任意 DOM 遍历；

• 区域和尺寸限制的全页截图、语义元素几何和有界性能指标；

• 机器本地上传/下载根目录，带真实路径检查、完成下载验证、危险状态强制执行、流式哈希，且无隐式文件系统权限；

• 手动、批准计划和自动有界授权模式，受保护操作始终回退到本地确认和无内容会话决策计数器；

• 无内容完成/注意力通知；

• 可取消的内存中只读快照计划，其私有结果被检索一次，权限随 MCP 进程或标签页授权过期；

• 内存中记录已输入的代理操作，形成哈希绑定、需要审查、故意不可重放的提供商驱动草稿；

• 密码管理器 UI 激活，从不接收凭据值；以及

• 提供商驱动 SDK，将针对性适配器绑定到确切授权、批准计划哈希、一个变异回调和适配器拥有的后置条件验证；

• 操作监听器标签页授权、侧面板状态/重试控制和无内容代理就绪工具；

• 无内容侧面板工作区、进度条、每个标签页的撤销和取消；

• 分离的读取和变异能力；

• Python 客户端中的一个受控变异回调；

• 稳定的扩展身份和确切原生主机来源；

• 私有本地状态、短套接字路径、消息限制和一个活跃作业；

• 确切标签页激活和审查的同源导航；

• 直接本地 MCP 代理表面，使扩展点击立即可发现并可由代理控制，无需提供商 OAuth 授权；

• 允许列表中的 DOM 和无障碍树读取、等待和私有提取；

• 字节限制的私有视口 JPEG 捕获，执行器端不持久化；

• 有界视口滚动、去重长列表收集和私有 AX 链接/描述提取；

• 通过私有结果槽的有界确切标签页浏览器日志捕获；

• 有界确切标签页请求元数据捕获，去除查询字符串并忽略头部、主体、cookie、发起者和安全细节；

• 有界确切标签页控制台 API 捕获，仅保留标量参数，从不评估或解引用远程对象；

• 类型化点击、聚焦、按键组合和私有文本插入动作；

• 取消、目标焦点漂移检测、结果大小限制和尽力调试器清理（取消在下一个有界动作处停止，不能回滚已开始的变异）；

• 提供商效果前的一次性预变异授权；以及

• 无路由的 llm-wiki 自测试清单；以及

• 无内容扩展状态面板，包含已连接、运行中、授权和失败状态。

此分支不是发布版或已安装的提供商替代品。针对性适配器影子运行、提供商拥有的验证、升级/回滚测试以及显式发布批准在合并的 0.1.0 之前仍然是必需的。

仓库边界

允许跟踪的材料：

• 可执行代码和扩展资产；

• 协议模式和安全文档；以及

• 合成夹具和确定性测试。

绝不提交真实资源 URL 或标识符、页面文本、截图、捕获、计划、收据、提取结果、cookie、凭据、浏览器存储或提供商语料库。运行时输入和输出保留在针对性适配器的独立受控数据平面中，并应尽可能保留在内存中。

架构

local agent through fixed MCP tools OR a targeted provider adapter
  -> select one exact user-created click grant from the private collaboration workspace
  -> deterministic typed program + exact approved plan hash
  -> BrowserExecutorClient over a private Unix socket
  -> allowlisted Native Messaging host
  -> shared MV3 extension on the exact user-exposed tab
  -> one-shot before-mutation challenge when required
  -> private result slots returned only to the targeted adapter

llm-wiki 可能会看到此仓库的无路由 self-test 适配器清单，但它从不直接将外部编辑或研究请求路由到执行器。

打包和安装

可安装产品在 Chrome 的安全边界处拆分：

• llm-wiki-chrome 原生伴侣： Python 客户端、固定 MCP 服务器、原生消息主机、安装程序、诊断工具和打包的扩展资产；

• LLM Wiki for Chrome： 公开源代码的 MV3 扩展 ZIP。Chrome 网上应用商店发布仍然是需要显式批准的单独发布步骤；加载未打包路径仍然是开发工作流。

仅用于开发的 Homebrew 配方可从 nvk/tap 获得，作为 HEAD 构建。它故意不是稳定发布版：

brew install --HEAD nvk/tap/llm-wiki-chrome
llm-wiki-chrome install
llm-wiki-chrome doctor

install 写入确切来源的原生消息注册。它不安装守护进程：Chrome 按需启动主机，并通过标准输入/输出与之通信。每个 Chrome 主机在确定性路径 /tmp/llm-wiki-chrome-<uid>/ 下创建一个私有的每进程套接字。CLI、MCP 服务器和针对性适配器自动发现这些套接字。没有正常的套接字参数、端口、配对码或环境变量。现有的环境覆盖仅用于特殊的沙盒或开发设置。

对于未打包的开发安装，向包询问确切路径：

llm-wiki-chrome extension-path

从 chrome://extensions 加载该目录，并运行 llm-wiki-chrome doctor。healthy: true 确认包和原生消息注册；connected: true 在 Chrome 打开扩展的原生端口时出现。仅卸载原生伴侣注册：

llm-wiki-chrome uninstall

文件传输默认禁用。仅在 ~/.config/llm-wiki/browser-executor.json 中启用明确的机器本地根目录：

{
  "upload_roots": ["/absolute/private/staging/uploads"],
  "download_roots": ["/absolute/private/staging/downloads"]
}

每个路径拒绝最终符号链接，解析其父目录链，并且必须保持在注册根目录内。上传值仅在私有槽中传输。下载必须完整、被 Chrome 接受为安全、位于注册根目录内，并且在返回给调用方之前由本地伴侣进行哈希处理。

侧面板提供 Manual、Approved plan 和 Automatic bounded jobs。 默认选项为 Approved plan。文件上传、对话处理以及凭据代理激活仍然是受保护的操作，始终需要本地手动确认。授权历史记录是一个无内容的会话计数器，而非页面内容日志。

工作流录制仅捕获已通过固定 MCP 界面请求的键入操作。browser_record_stop 返回一个内存中、哈希绑定、需审查的草稿。通用执行器不会重放该草稿；必须由目标适配器审查、编译、授权、记录并独立验证版本化的提供者工作流。直接界面只允许在精确授权和 MCP 进程仍然活跃时，对只读快照进行内存中的有界调度。持久化或周期性调度、变更、恢复和日志记录保留在目标适配器或外部调度器中，绝不在扩展的意图层中。

目标适配器可以通过 browser_executor.driver.ProviderDriverSession 集中执行边界，该会话拒绝计划哈希或精确授权漂移，并要求适配器拥有 status: verified 后置条件。

构建一个确定性、无内容的 Chrome Web Store ZIP 包，无需发布：

python3 scripts/package_extension.py

这些构建命令不会执行任何发布、标签、商店上传或已安装升级。

开发

python3 -m venv .venv
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q adapter.py browser_executor tests
node --check extension/service-worker.js
node --check extension/protocol.mjs
node --check extension/executor.mjs
node --check extension/sidepanel.js

确定性套件由一个独立的真实浏览器冒烟测试补充。它需要匹配的 Chrome for Testing 和 ChromeDriver 对，以及运行时提供的精确批准的读取目标；它不会触及正常的 Chrome 配置文件，也不会打印、持久化或返回捕获的视口：

LLM_WIKI_BROWSER_E2E_TARGET_URL='<exact approved HTTPS target>' \
  .venv/bin/python tests/chrome/run_extension_e2e.py \
    --chrome '/path/to/Google Chrome for Testing' \
    --chromedriver '/path/to/chromedriver'

测试框架将解压后的扩展复制到临时目录，添加一个仅测试的扩展页面，在无头 Chrome 中运行已签名的读取程序，并仅返回无内容计数器。Chrome 二进制文件不会由仓库下载或安装。

自测是无内容的：

.venv/bin/python adapter.py describe
.venv/bin/python adapter.py execute --request /private/request.json \
  --response /private/response.json

安装源码签出的本地主机一次，并注册其 MCP 命令：

.venv/bin/python adapter.py install

codex mcp add llm-wiki-browser \
  -- .venv/bin/python adapter.py mcp-server

注册后重启代理会话，即可使用固定的工具清单。Chrome 在用户于特定 HTTPS 标签页上点击扩展之前仍然不暴露任何内容，停止协作将撤销授权。如果运行时无法访问私有的默认 /tmp 目录，则可以对两个命令一致地设置 LLM_WIKI_BROWSER_EXECUTOR_NATIVE_SOCKET，但这不属于打包用户流程的一部分。

browser-install 写入一个精确来源的 Native Messaging 清单和启动器。仅在显式安装或迁移任务期间使用它。加载解压后的扩展、更改正常的 Chrome 配置文件以及升级已安装的副本不属于测试套件的一部分，需要明确的用户指示。

安全模型

执行器在 Python 和扩展中独立验证规范程序哈希、计划哈希、活跃协作 ID、固定驱动身份/版本、精确目标、能力、限制、动作词汇、私有槽位和结果允许列表。不存在持久化主机权限、<all_urls> 访问或内容脚本；Chrome 的 activeTab 授权仅通过用户的扩展点击创建。解释器具有固定的 CDP 方法允许列表，不接受 Runtime.evaluate、原始方法、脚本或页面生成的操作。

固定的 CDP 允许列表还包括配对的 Log.enable/Log.disable 和 Network.enable/Network.disable 窗口。后者仅保留有界的私有请求方法、来源/路径、资源类型、状态、MIME、缓存和失败标量；它会剥离查询字符串，从不保留标头、主体、Cookie、发起者、安全详情或请求 ID。这两种能力都不会暴露原始诊断方法或请求拦截。一个单独的配对 Runtime.enable/Runtime.disable 窗口仅保留有界的私有 Runtime.consoleAPICalled 类型、时间戳和标量参数。它忽略上下文、堆栈、描述、预览和对象 ID，绝不允许评估、编译、函数调用、脚本执行或属性访问。每个 Chrome 本地主机进程在配置的基础路径下绑定一个唯一的私有套接字。客户端仅发现这些严格命名的套接字，聚合它们的显式协作工作空间，并将作业路由到拥有其精确授权的单个主机。这可以防止多个 Chrome 配置文件相互替换中继，同时保持每个作业一个精确标签页。

执行器是受信任的本地代码，而不是操作系统沙箱。目标适配器仍需负责授权每个重要的提供者效果，并独立证明提供者的最终状态。直接变更工具会跨越一个内部一次性边界，但故意不声称提供者事务性保证。请参阅 SECURITY.md。