abundantbeing/hermes-browser-extension

# Hermes 浏览器扩展 用于 [Hermes Agent](https://hermes-agent.nousresearch.com/docs) 的浏览器原生侧边栏 — 将活动 Web 上下文连接到您的本地或远程 Hermes runtime。

公开 Alpha 版 v0.1.10 · 加载已解压的扩展程序 · 本地/远程 Hermes API · 完整的 Hermes runtime 工具
尚未上架 Chrome Web Store。

## 简介 Hermes 浏览器扩展不是一款浏览器聊天机器人。它是用于真正的 Hermes Agent runtime 的 Chrome/Edge/Chromium 侧边栏。它与您的 Hermes Gateway/API 服务器通信（默认为本地，当您配置了可访问的 URL 时为远程），因此它可以使用已在 Hermes 中配置的模型、工具、技能、会话、记忆和 MCP 服务器。 此代码库专门用于 **Hermes 浏览器扩展**：Hermes Agent 的 Chrome/Edge/Chromium 侧边栏集成。 ## 视觉导览 | 侧边栏 | 主题设置 | 本地 agents | | --- | --- | --- | | | | | | 浏览器行为 | 仅页面上下文 | Hermes 兼容性 | | | | | ## 核心亮点 - Chrome/Edge/Chromium MV3 侧边栏，由 Side Panel API 提供支持。 - 连接到可配置的本地或远程 Hermes API 服务器。默认地址：`http://127.0.0.1:8642`。 - 当您拥有已登录的远程 Hermes dashboard 标签页且没有 API key 时，支持 dashboard WebSocket 模式。 - 自动同步已连接的 Hermes 提供商/模型、配置文件、技能、会话和功能。 - 保持 runtime 插件在同一个 Hermes 会话中可用。例如，连接的社交媒体或消息插件可以添加帐户、帖子和趋势上下文，而扩展提供浏览器页面上下文。 - 显示 Hermes 兼容性面板，以便旧版 gateway 可以优雅降级为明确的 fallback/手动模式，而不是出现损坏的路由错误。 - 为 v0.1.10 支持报告添加了**复制诊断信息**功能：浏览器系列、版本/构建号、扩展源、gateway 源、capability flags、上下文模式、选定的 model/provider，以及已去除 tokens/页面内容的最后可见错误。 - 添加了一个可选的 **Hermes Browser Companion Plugin**，它被动地为 Hermes 工具/hooks 缓存经过净化的 Browser Context Protocol 元数据，而无需浏览器控制、网络调用或 API 服务器路由。 - 添加了 `/meta` / `/metadata` / `/head` 用于真实捕获的页面元数据分析：它仅报告 Browser 上下文实际包含的内容，并明确指出未捕获的元数据类别。 - 添加了用于浏览器工作的会话控制：创建/切换会话、复制会话 ID、重命名会话、智能首条消息标题，以及紧凑且符合品牌风格的会话操作。 - 添加了浏览器范围的模型控制：浏览器模型选择和每会话绑定保留在扩展内，不会更改 Hermes 的全局默认设置。 - 将活动标签页/浏览器上下文发送到持久化的 Hermes 会话中，或者在您不希望附加浏览器上下文时切换为仅聊天模式。 - 添加了用于“仅聊天”、“跟随活动标签页”、“固定特定标签页”以及选择哪些打开的标签页出现在 prompt 中的编辑器头部上下文菜单。 - 默认情况下作为标签页附加的侧边栏打开，并提供使侧边栏在所有标签页中全局生效的设置。 - 使用键盘快捷键打开（默认为 `Alt+H`，可在 `chrome://extensions/shortcuts` 中自定义）。 - 通过每标签页的本地历史记录和 Hermes 会话绑定，保持固定标签页对话的隔离性。 - 添加了用于常见浏览器上下文工作的快速命令，包括 `/summarize`、`/explain`、`/rewrite`、`/tabs` 和 `/action-items`。 - 在每次发送轮次后添加一个可折叠的“Hermes 所见内容”回执，以实现透明的上下文/调试。 - 在 Hermes 流式传输期间显示实时的 Tool Activity Strip（工具活动条），因此工具调用将显示为结构化的 runtime 活动，而不是附加到答案中的原始 `[tool]` markdown。 - 当 gateway 可访问时，将上游 Hermes runtime/工具异常分类为带有警告的连接诊断，包括已知的 Python `NoneType`/`int()` traceback 类别。 - 捕获活动标签页的标题/URL、打开的标签页、选中的文本、可读的页面文本、元数据、标题、表单、链接和按钮（如果可用）。 - 当可用时，通过 Hermes 音频转录支持语音听写；当连接的 runtime 未暴露 STT 时，回退为浏览器语音识别。 - 在将网页文本发送到 Hermes 之前，将其包装为不受信任的上下文。 - 流式传输 Hermes 响应，并在需要时回退到非流式聊天。 - 包含桌面版的外观设置：浅色/深色/系统模式，以及 Nous、Midnight、Ember、Mono、Cyberpunk 和 Slate 主题。 - 包含一个 localhost agent 选择器，用于在受信任的本地 Hermes API gateway 端口之间切换。 - v0.1 版本中没有 `debugger`、`nativeMessaging`、点击/输入/表单提交、cookies、历史记录、书签、下载或浏览器控制权限。 ## 环境要求 - 已安装并正常运行的 Hermes Agent。 - 在本地或可访问的远程机器上启用 Hermes Gateway/API 服务器。 - Node.js 20+。 - Chrome、Edge、Brave、Comet 或其他支持 Side Panel API 的 Chromium 浏览器（Chrome 114+ 基线）。 ## v0.1.10 兼容性矩阵 | 界面 | v0.1.10 是否支持 | Fallback / 备注 | | --- | --- | --- | | Chrome / Edge / Chromium 114+ 侧边栏 | 是 | 公开支持的主要目标。 | | Brave / Comet / Chromium 分支 | 尽力而为 | 必须暴露 Chromium Side Panel API 和扩展剪贴板权限才能使用复制诊断功能。 | | Firefox / Safari | 仅限预览 | 诊断信息现在会报告浏览器系列，但尚未提供完整的跨浏览器支持。 | | 本地 Hermes API 服务器 | 是 | 默认路径：`http://127.0.0.1:8642`。 | | 远程 API 服务器 | 是，仅限显式 URL/token | 使用受信任的 LAN/Tailscale/VPN 或 HTTPS 反向代理；不要将 Hermes 直接暴露在互联网上。 | | 远程 dashboard WebSocket | 尽力而为 | 仅限聊天/会话/模型路径；仅限 REST 的 profile/skills/图片上传界面仍然不可用。 | | Browser Context Protocol | 是 | 扩展会发出 `hermes.browser.context.v1` payload 并保留嵌入 prompt 的 fallback。 | | Companion 插件 | 可选的功能性上下文缓存 | `companion-plugin/` 为净化的 Browser 上下文提供只读工具/hooks；正常使用扩展不需要此插件。 | | 浏览器控制 / Runs UI / debugger / nativeMessaging | 否 | 推迟到具备可支持性、操作策略、批准和日志功能之后。 | ## 快速开始 ### 1. 克隆并构建 ``` git clone https://github.com/abundantbeing/hermes-browser-extension.git cd hermes-browser-extension npm install npm run build ``` 可加载的扩展程序生成于： ``` dist/ ``` ### 2. 在 Chrome/Edge 中加载已解压的扩展程序 1. 打开 `chrome://extensions` 或 `edge://extensions`。 2. 启用**开发者模式**。 3. 点击**加载已解压的扩展程序**。 4. 选择此代码库的 `dist/` 文件夹 — 而不是代码库根目录，也不是 `extension/`。 5. 固定/点击 Hermes 扩展图标以打开侧边栏。 代码更新后，再次运行 `npm run build`，并在浏览器扩展页面的 Hermes Browser Extension 卡片上点击**重新加载**。 ## 连接到 Hermes ### 本地 API 服务器 仅本地连接是最安全的默认设置。在运行 Hermes 的机器上，将以下内容放入 `~/.hermes/.env` 中： ``` API_SERVER_ENABLED=true API_SERVER_HOST=127.0.0.1 API_SERVER_PORT=8642 API_SERVER_KEY= API_SERVER_CORS_ORIGINS=chrome-extension:// ``` 启动或重启 gateway： ``` hermes gateway run ``` 验证 API 服务器： ``` HERMES_GATEWAY_URL=http://127.0.0.1:8642 HERMES_API_TOKEN='' curl "$HERMES_GATEWAY_URL/health" curl -H "Authorization: Bearer $HERMES_API_TOKEN" "$HERMES_GATEWAY_URL/v1/models" ``` 然后在扩展侧边栏中： 1. 点击**连接到 Hermes**，如果您的 Hermes Desktop/gateway 支持审批流程，请在本地批准。 2. 如果尚不可用审批，请点击**手动设置**。 3. 选择**本地 gateway**。 4. 使用 Gateway URL `http://127.0.0.1:8642`。 5. 粘贴您的限定范围浏览器 token 或 `API_SERVER_KEY`。 6. 点击**测试连接**，然后点击**保存设置**。 7. 打开一个普通的 `https://` 页面并提问：`用一句话总结这个页面。` ### 远程 API 服务器 对于远程 Hermes 机器，将 API 服务器绑定到可访问的受信任接口，并保持 CORS 范围尽可能小： ``` API_SERVER_ENABLED=true API_SERVER_HOST=0.0.0.0 API_SERVER_PORT=8642 API_SERVER_KEY= API_SERVER_CORS_ORIGINS=chrome-extension:// ``` 使用具有 HTTP 访问权限的私有同 LAN/Tailscale/VPN 主机，或者将 API 服务器置于受信任的 HTTPS 反向代理之后以进行公开/代理访问。**不要**将 Hermes API 服务器直接暴露在公共互联网上。Hermes API 服务器可以访问真实的 Hermes runtime 和工具。 示例： ``` http://192.168.1.50:8642 http://hermes-desktop.local:8642 https://hermes.example.com ``` 在扩展侧边栏中： 1. 选择**远程 gateway**。 2. 粘贴远程 API URL，包括 `http://` 或 `https://`。 3. 粘贴 API key/浏览器 token。 4. 点击**测试连接**。 存在 key 的情况下，Remote 指的是**远程 API 服务器**，并且不强制要求 HTTPS。在 key 为空的情况下，Remote 指的是**远程 dashboard WebSocket**，并且需要 `https://` dashboard URL。 ### 远程 dashboard 模式，无 API 服务器 如果您在其他地方运行 Hermes 并且仅暴露受 OAuth 保护的 dashboard，请选择**Remote**，输入 dashboard 的 `https://` URL，并将 API key 留空。在没有 key 的情况下，扩展将通过 dashboard 的 `/api/ws` socket 而不是 REST API 服务器进行连接。 身份验证使用从已登录的 dashboard 标签页生成的单次性 WebSocket ticket： - 在普通的浏览器标签页中打开 dashboard URL 并登录，并保持该标签页打开。 - 扩展会从该标签页直接生成 ticket，然后打开 socket。 - **测试连接**会打开 socket 并加载模型，这将确认整个路径。 此模式的限制：图片附件只能为内联方式，并且 skills/profiles 列表不可用，因为这些仅限 REST，并且 dashboard 的 REST 接口无法进行跨域访问。 ## 连接后会同步什么 连接后，侧边栏会从连接的 Hermes gateway 加载： - `/v1/models` — Hermes 可以枚举的所有 providers/models，包括 provider 限定的 ID。 - `/api/sessions` — 按来源分组的近期 Hermes 会话。 - `/v1/skills` — 编辑器中的斜杠命令技能建议。 - `/v1/profiles` — 当 gateway 暴露 profile 元数据时显示的 profile 选择器。 - `/v1/capabilities` — 功能 flags，如音频转录和浏览器上传支持。 在普通的可读页面上，DOM/上下文芯片应显示非零的页面上下文计数。诸如 `chrome://extensions` 之类的浏览器内部页面受到有意限制。 ## 通过 Hermes / Computer Use 安装 您可以请求 Hermes 协助安装： ``` Install Hermes Browser Extension from https://github.com/abundantbeing/hermes-browser-extension. Clone it, run npm install, run npm run build, then use computer use to open chrome://extensions, enable Developer mode, load the dist folder unpacked, and help me connect it to my local or remote Hermes Gateway API server. Do not reveal, print, screenshot, or commit my API key. ``` ## 安全模型 Hermes 浏览器扩展在 v0.1 中有意采取保守策略： - 默认使用本地 API 服务器；远程 API 服务器支持需要显式的 URL、token 和 CORS 允许列表。 - API 访问需要强 bearer/API key。 - 页面内容在到达 Hermes 之前会被包装为不受信任的上下文。 - 只读的浏览器上下文捕获：没有点击、输入表单提交、结帐、下载或浏览器控制行为。 - 无 `debugger`、`nativeMessaging`、`cookies`、`history`、`downloads` 或 `bookmarks` 权限。 - 受限页面包括浏览器内部页面、扩展页面以及明显的银行/加密货币/密码/支付/健康/政府税务类别。 详情请参阅 [`SECURITY.md`](SECURITY.md)、[`PERMISSIONS.md`](PERMISSIONS.md)、[`DATA-FLOW.md`](DATA-FLOW.md) 和 [`PRIVACY.md`](PRIVACY.md)。 ## 故障排除 ### 我加载了扩展但没有任何反应 确保您加载的是 `dist/`，而不是代码库根目录。所选文件夹必须直接包含 `manifest.json`。 ### 更新后 Chrome 仍显示旧版本 浏览器仍在使用旧的已解压文件夹，或者未重新加载的已解压扩展卡片。对于 v0.1.10，源 manifest、构建的 `dist/` manifest 和发布归档文件都应包含 `0.1.10` 版本的 `manifest.json`。 修复方法： 1. 解压/下载 v0.1.10 发行版，或在本地运行 `npm run build`。 2. 打开 `chrome://extensions` 或 `edge://extensions`。 3. 在 Hermes Browser Extension 卡片上，点击**重新加载**。 4. 如果仍显示旧版本，请点击**移除**，然后再次点击**加载已解压的扩展程序**并选择最新的 v0.1.10 `dist/` 文件夹。 5. 点击 **service worker** / **Inspect views** 仅用于调试；它不是版本来源。 ### 提交支持 issue 打开 Settings → **Support diagnostics** → **Copy Diagnostics**，并将报告粘贴到 GitHub issue 或支持主题中。 复制的代码块包含版本/构建号、浏览器系列、gateway 源、连接状态、runtime capability flags、选定的 model/provider、上下文模式、提取器模式以及最后可见的错误。它故意排除了 API key、bearer token、cookies、页面文本、选中的文本、标签页标题和完整的标签页 URL。 ### 侧边栏显示无法连接 检查 Hermes Gateway/API 服务器是否正在运行并且可以从浏览器访问： ``` curl http://127.0.0.1:8642/health # 或者，用于 remote 模式： curl http://:8642/health ``` 如果 `/v1/models` 失败，请检查 `API_SERVER_KEY`、扩展存储的 API key/浏览器 token 以及 `API_SERVER_CORS_ORIGINS`。对于远程模式，必须在 Hermes 机器上将浏览器扩展源（`chrome-extension://`）添加到允许列表中。 ### 侧边栏显示 runtime 警告，但仍显示已连接 v0.1.10 将 gateway 可达性与上游 Hermes runtime/工具故障区分开来。如果 `/health` 正常，但 Hermes 引发了 runtime traceback，浏览器将保持连接并显示警告，而不是使整个连接变红。 对于像 `int() argument must be a string, a bytes-like object or a real number, not 'NoneType'` 这样的 traceback，请在运行 gateway 的机器上检查 Hermes Agent 日志。如果 traceback 提到 `computer_use` 或 `cua-driver`，请运行： ``` hermes computer-use doctor ``` 该诊断信息属于 Hermes runtime/工具层，而不是浏览器扩展打包或 Chrome 权限问题。 ### Hermes 原生 computer use 不起作用 Hermes 浏览器扩展不请求浏览器控制权限，也不自行驱动页面。原生桌面控制来自 Hermes Agent 通过 `cua-driver` 实现的 `computer_use` 工具集。 在运行 Hermes 的机器上，直接验证 computer use： ``` hermes tools list hermes computer-use status hermes computer-use doctor ``` 如果 `doctor` 提示缺少 driver： ``` hermes computer-use install ``` 然后启动一个启用了该工具集的新 Hermes 会话： ``` hermes -t computer_use chat ``` Hermes 文档中指出的常见阻碍： - 通过 SSH 运行的 Windows 处于 Session 0 中，无法看到交互式桌面；请使用控制台/RDP 会话或 cua-driver Windows 自动启动模式。 - 提权/管理员窗口无法由正常完整性的 Hermes 进程在 Windows 上驱动。 - macOS 需要“辅助功能”+“屏幕录制”权限。 - Linux 需要可访问的 X11/Wayland 显示器和 AT-SPI。 ### DOM 芯片显示 `0 chars` 打开一个普通的 `https://` 页面并刷新上下文。浏览器内部页面（`chrome://`、`edge://`、扩展页面、devtools 等）受到设计限制。 ### 麦克风显示被阻止或语音听写未启动 Chromium 侧边栏可能会抑制麦克风权限提示。Hermes 浏览器扩展通过基于能力限制的语音模式处理此问题： - 当连接的 Hermes runtime 提供音频转录时，启用 **Hermes STT**。 - 当 Hermes STT 不可用且 Chromium 暴露了 Web Speech 时，启用**浏览器语音 fallback**。 - 当侧边栏无法直接捕获麦克风时，显示可见的 **Hermes 语音听写** 标签页。 建议的流程： 1. 点击侧边栏中的麦克风按钮。 2. 如果侧边栏无法捕获麦克风，将打开一个 **Hermes 语音听写** 标签页。 3. 在该标签页中，点击**开始听写**。此点击是 Chromium 期望的权限手势。 4. 说话，然后根据活动模式点击**停止 + 转录**或**停止语音**。 5. 转录文本将自动发送回侧边栏编辑器。 如果 Chromium 仍提示麦克风被阻止，请点击语音标签页中的**打开麦克风设置**，并将 `chrome-extension:///` 的麦克风设置为**允许**，然后返回语音标签页重试。 ### 首次运行连接流程不可用 使用带有您的本地/远程 Gateway URL 和 API key 的**手动设置**。原生的 Desktop 审批流程在 alpha 阶段仍在不断完善中。 ## GitHub PR/Issue 自动审查 此代码库包含两个 Hermes 审查运行器： - `npm run review:watch` — 用于开放 PR/issue 的本地轮询器。它现在可以从能够访问 Hermes 并通过了 `gh` 身份验证的机器上运行。 - `npm run review:event` — 用于将来进行 GitHub Actions/webhook 连接的 GitHub 事件运行器。它需要 `GITHUB_EVENT_NAME`、`GITHUB_EVENT_PATH` 和 `GITHUB_REPOSITORY`。 本地轮询器会检查开放的 PR 和 issue，根据 PR head SHA 或 issue 标题/正文计算稳定签名，并且仅审查更改的目标。它使用稳定的标记为每个 PR/issue 插入或更新一条机器人评论。PR diff 和 issue 正文被视为不受信任的输入。 本地设置： ``` # 使用 gh auth token，来自 ~/.hermes/.env 的本地 API_SERVER_KEY， # 并且默认使用 http://127.0.0.1:8642。 npm run review:watch ``` 可选覆盖： ``` HERMES_REVIEW_REPO=abundantbeing/hermes-browser-extension HERMES_REVIEW_GATEWAY_URL=http://127.0.0.1:8642 HERMES_REVIEW_API_KEY= HERMES_REVIEW_MAX_TARGETS=3 HERMES_REVIEW_STATE_FILE=~/.hermes/hermes-browser-review-state.json ``` 对于稍后的 GitHub 托管 Actions runner，`HERMES_REVIEW_GATEWAY_URL` 必须可从 GitHub 访问。Runner 无法访问您个人机器上的 `http://127.0.0.1:8642`；请使用位于 Tailscale/VPN/HTTPS 之后的远程 Hermes API 服务器，或者位于同一网络中的自托管 GitHub runner。推送 `.github/workflows/*` 还需要具有 `workflow` 权限范围的 GitHub token。 试运行： ``` npm run review:watch:dry-run GITHUB_EVENT_NAME=pull_request_target \ GITHUB_EVENT_PATH=./event.json \ GITHUB_REPOSITORY=abundantbeing/hermes-browser-extension \ GITHUB_TOKEN= \ npm run review:event:dry-run ``` ## 开发 ``` npm test npm run check:js npm run check:manifest npm run verify npm run build npm run package ``` 项目结构： ``` extension/ manifest.json MV3 extension manifest background.js side panel behavior content.js page context collector sidepanel.html side panel UI sidepanel.css side panel styling sidepanel.js Hermes API client + UI state voice-dictation.* visible extension voice recorder fallback for blocked side-panel mic capture request-permissions.* visible extension mic-permission helper page sidepanel-preview.html static visual QA preview assets/ local Hermes fonts, icons, and imagery lib/browser-context-protocol.mjs versioned read-only browser context protocol helpers lib/runtime-events.mjs stable runtime/tool event names for Browser UI normalization lib/support-diagnostics.mjs redacted Copy Diagnostics support report helpers lib/common.mjs shared prompt/context/security utilities companion-plugin/ optional fail-soft Browser companion plugin with read-only context cache tools/hooks scripts/ build.mjs copies extension/ to dist/ check-manifest.mjs validates required manifest assets/permissions hermes-review-github-event.mjs PR/issue event runner for GitHub Actions/webhooks hermes-review-watch.mjs local PR/issue review poller package.mjs creates artifacts/hermes-browser-extension.tar.gz tests/ common.test.mjs utility behavior tests ``` ## 与 Hermes Agent 的关系 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 是由 Nous Research 开发的开源项目。Hermes 浏览器扩展是由 Jon Komet 开发的社区扩展，可连接到本地或远程 Hermes API 服务器。它旨在处于生态系统边缘，而不增加核心 tool-schema 占用空间。 有用的链接： - Hermes 文档： - Hermes API 服务器文档： - Hermes 上游代码库： ## Star 历史 ## 作者 由 **Jon Komet** (`@abundantbeing`) 构建。 ## 许可证 MIT。详见 [`LICENSE`](LICENSE)。

标签：AI智能体, Hermes, MITM代理, SOC Prime, Web上下文, 上下文集成, 开发工具, 数据可视化, 浏览器扩展, 自定义脚本