agent-browser-relay

Agent Browser Relay

使用此技能，通过本地中继网关操作明确附加的浏览器标签页；读取前先验证是否就绪，并确保并发标签页工作流限定在各自的租约范围内，而不是退回使用直接浏览器控制工具。

Chrome 是文档中指定的主要目标。能够加载此扩展的基于 Chromium 的浏览器也可能适用。一个中继端口可同时保持多个浏览器／配置文件扩展客户端处于连接状态；中继状态会显示每个浏览器 ID 及已附加的 tabRef 值。

快速开始

全新机器规则：

• skills add 保证已安装的技能位于 ~/.agents/skills/agent-browser-relay
• 执行 skills add 后，保证可供 Chrome 加载的路径为 ~/.agents/skills/agent-browser-relay/extension
• ~/agent-browser-relay/extension 只是由 npm run extension:install 创建的可选便捷副本，方便直接查看
• npm run extension:path、npm run relay:start 和 npm run relay:global:install 会输出要加载的主目录
• npm run extension:path 还会输出 read-active-tab.js 和 preflight.sh 的稳定绝对路径，让 Agent 无需依赖当前工作目录即可调用
• 中继启动后打开一次扩展弹出窗口，即可唤醒扩展；随后 npm run extension:status 会确认 Chrome 是否已实际加载该扩展
• 在新机器上，必须先由用户在 chrome://extensions 中加载主路径，然后才能执行附加／读取步骤。不要将缺少可见便捷副本视为沙盒或套接字权限问题。

默认值在代码中设置：

• 主机：127.0.0.1
• 端口：18793
• 附加超时：120000 ms 需要时，可通过 --host、--port 和 --attach-timeout-ms 按命令覆盖。

1. 安装依赖并启动中继

   这会输出要在 Chrome 中加载的 Chrome 扩展主路径，并在可能时刷新可选的可见便捷副本。

   npm run relay:start -- --status-timeout-ms 3000
   

   或显式指定主机／端口：

   npm run relay:start -- --host "127.0.0.1" --port "18793" --status-timeout-ms 3000
   

   relay:start 会持续运行，直到你停止它或进程重启。若要限制会话时长，请显式传入 --auto-stop-ms：

   node scripts/relay-manager.js start --auto-stop-ms 10800000
   

2. 在 Chrome 中加载扩展

   • chrome://extensions
   • 启用开发者模式
   • 执行 skills add 后，从 ~/.agents/skills/agent-browser-relay/extension 加载未打包的扩展
   • 如果命令输出了扩展路径，请以该路径为准
   • 无论何时，只要想再次查看准确路径，都可以在已安装的技能目录中运行 npm run extension:path
   • ~/agent-browser-relay/extension 是可选的；如果想要一个可见快捷方式，可通过 npm run extension:install 创建

3. 确认 Chrome 已加载扩展

   中继运行后，打开一次工具栏弹出窗口。窗口应显示 Relay connected on <port>。

   Agent 要求：在新机器上执行任何附加步骤之前，先请用户打开一次弹出窗口，然后确认：

   npm run extension:status -- --port "18793" --wait-for-connected --connected-timeout-ms 120000
   

   此命令会报告连接到该中继端口的每个浏览器主机／配置文件 ID。

4. 将扩展附加到目标标签页（打开工具栏弹出窗口并点击附加）

   正常使用时，让每个浏览器都使用默认中继端口，并在每个浏览器中附加目标标签页。中继会使用 tabRef（browserId:tabId）为标签页划分命名空间。 若要让 Agent 自行创建首个后台标签页，请在弹出窗口中启用 允许 Agent 创建新的后台标签页。

   Agent 要求：extension:status 确认 Chrome 已加载扩展后，暂停并请用户执行此附加步骤，然后等待确认再继续。

   如果 git fetch 或拉取后，你的 .agents 技能文件夹中缺少 extension/，请从仓库修复：

   cd ~/.agents/skills/agent-browser-relay 2>/dev/null || cd ~/.agents/skills/private/agent-browser-relay
   git sparse-checkout disable
   git config --unset-all core.sparseCheckout || true
   git config --unset-all core.sparseCheckoutCone || true
   git checkout -- .
   

5. 检查就绪状态和附加状态

   npm run relay:doctor -- --port "18793" --tab-id "<TAB_ID>" --json
   

   先从状态中解析 <TAB_ID> 或 <TAB_REF>（npm run relay:status -- --all --status-timeout-ms 3000）。 对于所有 Agent 运行，请使用指定的标签页 ID 或标签页引用：

   npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-id "<TAB_ID>" --json
   

   npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-ref "<TAB_REF>" --json
   

   只有在此命令成功返回后才能继续。

多浏览器行为

• 一个中继端口支持连接多个浏览器／配置文件扩展客户端。
• 附加的标签页包含浏览器范围内的 tabRef，格式为 browserId:tabId。
• 如果只有一个附加标签页具有该 ID，请使用 --tab-id；如果多个浏览器可能存在相同的数字标签页 ID，请使用 --tab-ref。
• 如果多个浏览器都启用了 Target.createTarget，请传入 --browser-id 选择浏览器。

高级的逐标签页中继端口行为

• 多个中继端口仍可用于调试或特殊路由。
• 未保存中继端口映射的标签页使用全局默认中继端口（18793）。
• 成功附加后，扩展会保存该标签页映射的中继端口，并自动重复使用。
• 关闭的标签页会自动移除其映射。

Agent 的强制行为

• 使用此仓库中的固定命令。不要尝试“发现”其他脚本名称。
• 仅限网关规则：始终通过本地中继网关进行通信（/status 和 node scripts/read-active-tab.js）。
• 此工作流中切勿使用直接浏览器控制工具（例如 Playwright、Puppeteer、Selenium、agent-browser 或临时编写的 Chrome 控制脚本）。
• 切勿控制随机的 Chrome 窗口或配置文件。只能操作通过 --tab-id 或 --tab-ref 租用的明确附加目标标签页。
• 在新机器上，任何附加或读取尝试之前，都要明确告知用户先通过 npm run extension:path 加载主扩展路径。运行 skills add 后，该路径通常为 ~/.agents/skills/agent-browser-relay/extension。
• 规范命令：
  • npm run extension:path
  • npm run extension:status
  • npm run relay:start
  • npm run relay:status
  • npm run relay:doctor
  • npm run relay:stop
  • node scripts/read-active-tab.js
• 检查中继健康状态时，始终使用显式超时以避免挂起：
  • npm run relay:status -- --status-timeout-ms 3000
  • curl --max-time 3 -sS "http://127.0.0.1:18793/status"
  • npm run relay:status -- --all --status-timeout-ms 3000
• 执行 relay:start 后暂停，并请用户打开一次弹出窗口，以便 npm run extension:status -- --port "18793" --wait-for-connected --connected-timeout-ms 120000 确认 Chrome 已实际加载扩展。
• 只有在 extension:status 成功后，才能请用户附加目标标签页再进行读取，或在创建首个标签页的工作流开始前，确认已启用 Allow agent to create new background tabs。
• 读取前运行 npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-id "<TAB_ID>" --json 或 npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-ref "<TAB_REF>" --json；仅在命令成功后继续。
• 如果工作流将通过 Target.createTarget 打开标签页，运行 npm run relay:doctor -- --host "127.0.0.1" --port "18793" --require-target-create --json；仅在命令成功后继续。
• 对所有 Agent 运行（单 Agent 和并发运行），检查或读取命令始终传入 --tab-id <tabId> 或 --tab-ref <browserId:tabId>，确保每次操作都受租约约束。
• 并发运行时，附加的标签页是共享的中继状态，但一个附加标签页同一时间只能有一个有效租约。检查 npm run relay:status -- --all --status-timeout-ms 3000，选择下一个 --tab-id / --tab-ref 时，优先参考 leaseSummary.availableAttachedTabIds、attachedTabs[].tabRef 或 attachedTabs[].leasedSessionId。
• 如果 doctor 返回 TAB_LEASED_BY_OTHER_SESSION，不要尝试接管。等待该会话结束，或改用另一个没有有效租约的附加标签页重试。
• 启用 Target.createTarget 后，扩展可以为会话创建并自动附加首个由 Agent 控制的标签页，无需用户先附加种子标签页。
• 除非用户提出要求或确实需要恢复，否则任务期间不要停止或重启中继。
• 不要仅因本地代码更新就重启中继；更新会在用户下一次明确批准重启后生效。
• 如果请求的 tabId 未出现在中继状态的 attachedTabs 中，请停止并让用户在弹出窗口中重新附加目标标签页后再继续。
• 如果 relay:start 超时，请报告实际的中继日志或错误。除非命令输出明确显示权限错误，否则不要猜测沙盒限制。
• 如果页面出现人工验证关卡（例如“Are you human?” 或 CAPTCHA），请立即停止，通过 $attention-please 提醒用户，并等待用户明确确认后再继续。

5. 读取结构化标签页载荷

   node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id "<TAB_ID>"
   

6. 可选：单命令冒烟测试

   ./scripts/preflight.sh
   

   这是一个本地冒烟测试包装脚本。对于 Agent 工作流，规范的预检命令仍然是：针对已附加的标签页，运行 npm run relay:doctor -- --port "18793" --tab-id "<TAB_ID>" --json；针对创建首个标签页的工作流，运行 npm run relay:doctor -- --port "18793" --require-target-create --json。

如果当前工作目录不是已安装的技能根目录，请使用 npm run extension:path 输出的绝对 Stable read CLI path，而不是相对路径 node scripts/read-active-tab.js。

功能

read-active-tab.js 会在每个成功的载荷中通过以下字段返回功能元数据：

source.capabilities

版本兼容性检查也会通过 source.extension 返回：

• installedVersion
• sourceVersion
• relayVersion
• observedExtensionVersion
• versionMismatch

如果检测到版本不匹配，该命令每次运行时也会向 stderr 输出易于理解的更新提示。

• scripts/read-active-tab.js 的默认提取内容：url、title、text、links、metaDescription。
• 中继会话租约（--tab-id、--tab-ref），用于隔离同一中继端口上各标签页的并发 Agent。
• 使用 --expression、--expression-file 或 --expression-stdin 的 Runtime.evaluate 表达式模式。
• 通过 --screenshot 截取屏幕截图（可选使用 --screenshot-full-page、--screenshot-path）。
• WhatsApp 和通用聊天审计的预设提取，支持正则表达式筛选。
• 使用 --check --wait-for-attach 轮询附加状态。

并发工作流注意事项

• 为并发运行选择标签页前，请先检查 npm run relay:status -- --all --status-timeout-ms 3000。
• 使用 attachedTabs 与 leasedSessionId / tabLeases，了解当前哪些已附加的标签页可用。
• 如果 doctor 返回 TAB_LEASED_BY_OTHER_SESSION，请勿强行接管。等待该会话释放标签页，或选择另一个已附加的 tabId。
• 租约隔离会按已附加的标签页限定中继命令路由。这不代表使用了单独的浏览器配置文件，也不代表浏览器进程隔离级别更高。

预设和筛选器

• --preset 的值：default、whatsapp、wa、whatsapp-messages、chat-audit、chat。
• 正则表达式筛选器：--text-regex、--exclude-text-regex、--link-text-regex、--link-href-regex。
• WhatsApp/聊天筛选器：--message-regex、--exclude-message-regex、--sender-regex、--exclude-sender-regex。

常见命令示例

在 Agent 工作流中，请使用 --tab-id 或 --tab-ref 变体。无作用域的命令仅用于手动/本地调试。 对于较复杂的 JavaScript，优先使用 --expression-file 或 --expression-stdin，而不是内联 --expression。

node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --pretty false
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --pretty false
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-ref chrome-profile:123 --pretty false
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --check --wait-for-attach --require-target-create --attach-timeout-ms 120000
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --expression "document.documentElement.outerHTML"
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --expression-file "./tmp/expression.js"
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --expression-stdin < ./tmp/expression.js
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --screenshot --screenshot-full-page --screenshot-path "./tmp/page.png"
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --preset whatsapp-messages --max-messages 200 --selector "#main"
node scripts/read-active-tab.js --preset chat-audit --selector "body" --message-regex ".*"

所有成功的命令都会返回一个 source 对象，其中包含 relayHost、relayPort、relayStatusUrl 和 relayWebSocketUrl。

与 Agent 配合的推荐流程

在自动化流程中获取数据之前，先运行一次轻量级预检，确保中继和已附加的标签页均已就绪。

对于在一个中继上运行的多个 Agent：

• 从中继状态中解析标签页 ID（npm run relay:status -- --all --status-timeout-ms 3000）。
• 为每个 Agent 分配一个标签页 ID。
• 该 Agent 的每次 read-active-tab.js 调用都使用 --tab-id 或 --tab-ref。
• 将扩展实例视为共享实例：租约可防止两个控制器会话同时操作同一个已附加标签页，但不会创建独立的 Chrome 配置文件或独立的扩展进程。
• 如果 relay:doctor 报告 TAB_LEASED_BY_OTHER_SESSION，请检查 attachedTabs、tabLeases 和阻止项 detail，然后选择另一个已附加的标签页，或等待占用会话释放该标签页。