浏览器扩展

连续工作、浏览器控制中心与实验性本机桥接。

herdr-mcp 浏览器扩展是已经可用的 MCP Connector 之上的可选浏览器层，不是第二个 Agent runtime，也不是第一次连接工作站的前置条件。

它只负责三类浏览器侧问题：

ChatGPT composer 旁的“排队”属于浏览器交互：它等待当前回复结束，再把明确的下一轮用户意图发出去，不会中断正在生成的回复。

数据处理与权限用途见 浏览器扩展隐私政策。

安装身份：STORE / STANDALONE / DEV#

扩展身份与 Runtime DEV/PROD 是两套独立通道：

当前 runtime 支持 STORE / STANDALONE / DEV 三种 Native Host ownership。STANDALONE 使用固定的非 Store 身份；不要用路径派生 DEV build 冒充 standalone。更老的 runtime 可能只暴露部分通道，切换 ownership 前先检查已安装 runtime。

默认安装 Herdr Chrome Web Store 官方扩展。只有 Store 不适用且 runtime 明确支持时才选 STANDALONE；DEV 只用于源码开发。

当前 runtime 可直接从 GitHub 仓库生成本机可 Load unpacked 的 STANDALONE 副本，不需要 clone 源码仓库：

复制herdr-mcp extension standalone install
herdr-mcp native-host use standalone

正式 runtime 默认使用编译时记录的不可变 source commit；开发构建无法证明 build commit 时才回退 main。需要明确追踪仓库最新源码时可执行 herdr-mcp extension standalone install --ref main。

支持 --path 的 runtime 可以显式指定 Chrome “加载已解压的扩展程序”看到的路径：

复制herdr-mcp extension standalone install --ref <release-tag-or-commit> --path ~/Documents/herdr-mcp/extension

--path 可省略，默认用户可见路径为 ~/Documents/herdr-mcp/extension。自定义路径必须解析到用户 HOME 目录以内。真实受管副本始终保留在 ~/.config/herdr-mcp/extensions/standalone/current，指定路径只是指向受管副本的稳定软链，因此改变 --path 不会改变 standalone 扩展身份。用户显式指定的路径若已被占用，命令直接失败而不是覆盖；默认路径冲突则保持原内容不动，并回退到受管路径。自动化需要确定 chrome://extensions → Developer mode → Load unpacked 应选择哪个目录时，运行 herdr-mcp extension standalone status 并读取 chrome.load_unpacked_path；后续更新继续复用同一路径。该值是上次安装记录的 Chrome 可见路径，读取自 ~/.config state，因此即使 macOS 权限不允许读取 ~/Documents 也保持稳定；此时 user_visible_path.status 会显示 unverified，但不会改变 chrome.load_unpacked_path。

下载器先把 ref 解析为不可变 commit SHA，再只下载该 commit 下 Git 跟踪的 extension/ 文件。除 manifest.json 为固定 STANDALONE ID 注入公开 key 外，其余文件必须与该 commit 的 extension/ 字节一致；repo/worktree 中的 DEV extension/manifest.json 不会被修改。可用 herdr-mcp extension standalone status 查看已安装 commit、版本、ID 和路径。

扩展打包 workflow（.github/workflows/extension-store.yml）在 Store ZIP 之外还会生成手工安装包。herdr-mcp-extension-X.Y.Z.zip 是 Chrome Web Store 上传包；herdr-mcp-extension-standalone-X.Y.Z.zip 及其 .sha256 用于手工 Load unpacked。只有 standalone ZIP 注入公开固定 manifest key，用于保持 Native Messaging 要求的 STANDALONE Chromium ID，因此不要把 Store ZIP 当作手工包加载。先执行 shasum -a 256 -c herdr-mcp-extension-standalone-X.Y.Z.zip.sha256 校验，再解压到新的干净目录，不要覆盖旧版本目录。

macOS 安装或更新 STANDALONE 后还应执行一次 herdr-mcp doctor。standalone status 说明受管目录里的文件状态；doctor 会额外只读取 Google Chrome profile preferences 中 Herdr 这个固定 extension ID 的精确条目，并把 Chrome 当前 Load unpacked 的实际路径与上面的受管路径比较。它同时接受受管 ~/.config/herdr-mcp/extensions/standalone/current 目录和上次安装记录的 Chrome 可见路径。该记录读取自 ~/.config state 并按稳定字符串比较，因此改变 --path、或 macOS 拒绝读取 ~/Documents，都不会误报 drift。若出现 WARN standalone-extension-load state=drift，说明相同固定 ID 仍从另一目录加载，常见于旧的 Downloads/开发副本仍留在 Chrome。打开 chrome://extensions，找到 Herdr 扩展，按 doctor 给出的 expected 路径重新 Load unpacked/Reload。不要仅为修复路径漂移而切换 Native Host channel、删除扩展数据或复制凭据。该检查只诊断，不会重写 Chrome 配置，也不会刷新标签页。

选择通道后验证：

复制herdr-mcp native-host status

要求 active channel、extension identity、Native Host 和当前 runtime generation 一致。STORE 由商店更新；STANDALONE 由正式独立 package 更新；DEV 由开发者显式 Reload。旧网页仍运行旧 content script 时，刷新页面即可。

当前 1.1 开发版在安装或加载扩展时申请必需的 <all_urls> host access，使 Generic Web BrowserPage 在访问新网站时不再逐站弹出权限请求。从旧版较窄的 host permission 升级时，Chrome 可能要求用户一次确认新增权限；确认后 Herdr 运行时不会再逐站申请 host permission。

入口与状态对象#

这些状态为什么必须分开、如何恢复和接力，由 浏览器连续工作 与 浏览器控制中心 分别作为 SSOT 说明，本页不再重复实现细节。

本机安全边界#

扩展不会把 Herdr bearer 放进网页脚本、service worker 或浏览器存储：

复制网页内容脚本 / Side Panel
          ↓
Chrome Extension Service Worker
          ↓ Native Messaging
本机 Host
          ↓ Unix socket (0600)
herdr-mcp Rust runtime

浏览器负责页面交互和可视化；Native Host 是受信任本机桥；runtime 继续负责工具 schema、managed-root、权限和 mutation 边界。公网 OAuth/MCP 与本机 Native Messaging 是两个独立信任边界。

第一次使用#

1. 先确认 runtime + ChatGPT Connector 已经工作；
2. 选择 STORE / STANDALONE / DEV，并验证 herdr-mcp native-host status；
3. 打开受支持网页和 Side Panel；
4. 完成 workspace binding；
5. 保持 Auto 关闭，先核对状态、Pinned Target 与人工操作；
6. 只有需要长时间无人值守时再按作用域开启 Continuity 自动化。

设置页只把常用项放在首屏：语言、ChatGPT Project Auto 能力开关和已支持 WebChat 的站点访问。实验性站点、Page Assist、本机连接、连续工作模板和时间参数默认折叠，需要时再展开。workspace binding 继续留在 Side Panel / HUD，便于核对当前页面上下文；已注册的 WebChat endpoint 默认可控，不再提供单独的 WebChat Control 开关。

语义 Auto 不在浏览器扩展里配置 Provider 凭证或 endpoint。扩展只调用本机 Herdr Runtime；Runtime 的 Provider 配置只有两层：单机使用 mode-0600 的 config.json，全局使用已认证 Cloudflare Worker 的共享 route pool，同一 typed/chat 能力有本机 route 时优先本机。两层都使用统一的 name / protocol / url / model / api_key route JSON 对象；decision 与 decision-vercel 自动归为 typed evaluation，openai-chat 自动归为 chat；shell/process environment 不承担 Provider 配置。普通 Auto 固定按 typed evaluation route（Jev）-> chat route（LLM）-> 有界脚本兜底；Goal 模式可把 Jev 作为现有 LLM Goal Supervisor 的 advisory semantic prior。route 的配置顺序就是优先级：第一个健康 route 为 primary，后续 route 只在失败或 cooldown 后有界接替；Jev 与 LLM route 的单次 timeout 与整个 pool 的总 deadline 分开。旧 config.toml 首次读取时会迁移为 JSON。没有语义 Provider 时脚本兜底仍提供基础 Auto；Work Memory/TODO evidence 与确定性安全门继续保持权威。

1.0 的浏览器支持覆盖 ChatGPT、Claude 与 Grok。三者的已注册 WebChat endpoint 默认可控；Project / Project 对话另外提供 workspace binding，全局新聊天 / 首页在没有 Project 或 conversation 作用域时不显示 workspace binding。ChatGPT 另外支持会话 create、archive 与 self-handoff；Claude 与 Grok 支持已登录会话的 dispatch、settled result 与 reload recovery。Gemini 保持可选实验状态，不进入 1.0 验收边界。

z.ai / DeepSeek 的 JSON → MCP 属于实验性集成，默认关闭，需要在 Herdr 设置的实验性功能中显式开启。

发布与维护边界#

STORE / STANDALONE / DEV 可以作为不同扩展身份共存，但受管 Native Messaging manifest 只有一个 active owner。Store 身份以 contracts/browser-extension-store.json 为机器可读 SSOT；Standalone 身份以 contracts/browser-extension-standalone.json 为 SSOT；DEV 继续使用路径派生身份。

切换 native-host use store / use standalone / use dev 后刷新已经打开的受支持页面。扩展版本生命周期独立于 Rust runtime；只有新增 Native Host identity/channel contract 时才要求相应 runtime 能力。

维护者的详细发布流程见 docs/_wip/browser-extension-development-and-store-release.md 和 AGENTS.md。