Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠
站点适配器 —— 如何编写
站点适配器是最受欢迎的贡献类型第一名(参见 CONTRIBUTING.md)。它们在代理首次在已知站点上操作时,将简短、人工精选的指导注入到代理的首条消息中。目标不是编码每个选择器(那些腐烂得很快),而是捕捉那些非显而易见的怪癖——这些怪癖会让 LLM 花费数次徒劳的工具调用来自行发现。
工作原理
文件
src/chrome/src/agent/adapters.js(以及 src/firefox/src/agent/adapters.js——两个构建共享相同的文件内容,修改需同步到两者)。
匹配
getActiveAdapter(url) 遍历 ADAPTERS 数组,返回第一个 matches(url) 返回 true 的适配器:
export function getActiveAdapter(url) {
if (!url) return null;
for (const a of ADAPTERS) {
try {
if (a.matches(url)) return a;
} catch (e) { /* 跳过格式错误的匹配器 */ }
}
return null;
}
一次只有一个适配器触发,因此无论适配器总数多少,提示词成本都是固定的。
对于 Mastodon 等联邦平台,请保持通用 URL 形状保守。
裸的 /@user 和 /users/user 路径出现在许多非 Mastodon 的站点上,
而当前的适配器匹配器只看到 URL 字符串。未来的工作可能会集成
instances.social 作为基于技能的查找
或维护的已知实例列表,以便在更广泛地注入 Mastodon 指导之前验证候选主机。
注入时机
- 首轮:适配器的
notes在_enrichUserMessageWithCurrentPage()中被追加到第一条用户消息。 - 对话中导航:如果用户导航到匹配不同适配器的 URL,代理会注入一条
[Site context changed → now on <name>]消息。由_maybeReinjectAdapter()控制。
通用前言
UNIVERSAL_PREAMBLE 在启用 useSiteAdapters 时随每条系统提示一起注入。它涵盖 cookie/同意横幅和付费墙——这两种模式出现在公共网络上,会导致 LLM 做出错误的假设。
适配器格式
{
name: 'my-site', // 唯一短标识符
category: 'general', // 'general' | 'finance'
matches: (url) => /^https?:\/\/(www\.)?example\.com\//.test(url),
notes: `
- 要点 1:可操作的建议。
- 要点 2:另一个建议。
- 保持简短(最多 4–8 条要点)。每个适配器在每轮首轮对话中都会消耗令牌。
`,
}
字段
| 字段 | 类型 | 描述 |
|---|---|---|
name |
string | 适配器的唯一标识符。用于系统提示的标题。 |
category |
'general' 或 'finance' |
'finance' 会在标题中添加 [FINANCE / HIGH-STAKES] 横幅,并在系统提示中触发额外的安全指导。 |
matches |
(url) => boolean |
当适配器应为该 URL 触发时返回 true。推荐使用正则表达式——保持足够具体以避免错误匹配。 |
notes |
string | 注入到第一条用户消息中的要点式指导。最多保持 4–8 行。 参见下面的风格指南。 |
排序
适配器在 ADAPTERS 数组中按分类/站点排序。金融适配器必须放在 finance-generic 之前,因为 finance-generic 使用宽泛的正则表达式会遮蔽特定的适配器。当前顺序:Stripe → Coinbase → Robinhood → TradingView → finance-generic。
编写有效的 Notes
应该做的
- 描述页面的结构而不是文字选择器。选择器会腐烂;页面布局模式更稳定。
// 好 notes: `- 编辑器是一个 contenteditable div,而不是 textarea。` // 差 notes: `- 点击 div[contenteditable="true"] 来编辑。` - 指明要优先使用的工具:引导使用 AX 工具(
click_ax、set_field)而非旧工具(click({text})、type_text)。 - 标记破坏性的细微之处:"账单页面上的'取消'按钮会立即停止服务——请阅读确认弹窗。"
- 标记 SPA 导航陷阱:"设置更改会自动保存;通过浏览器后退导航会丢弃未保存的编辑。"
- 标记粘性覆盖层:"Cookie 横幅每 24 小时重新出现。不要将其文本描述为页面内容。"
- 标记虚拟化容器:"时间线是虚拟化的——滚动以加载更多内容。"
- 每条要点保持一个可操作的建议。模型的上下文有限,会快速浏览。
不应该做的
- 不要编码 CSS 选择器——它们在每次站点重新设计时都会变化。
- 不要写超过 8 条要点——令牌成本会在每次对话中累积。
- 不要包含模型通过阅读页面就能弄清楚的明显建议(例如,"提交按钮提交表单")。
- 不要重复通用前言(cookie/付费墙指导)。
- 不要添加字母表或参考适配器——每个适配器必须提供真正的指导,能为模型节省至少 2–3 次试错工具调用。
示例:好的适配器
{
name: 'twitter',
category: 'general',
matches: (url) => /^https?:\/\/(www\.)?(twitter\.com|x\.com)\//.test(url),
notes: `
- 编辑器是一个 contenteditable,而不是 textarea。字符数由客户端强制限制。
- 时间线是虚拟化的——推文会滚动出 DOM。使用搜索而不是滚动来查找推文。
- "回复"、"转推"、"喜欢"图标位于每条推文下方。
- 引用推文 vs 转发:转推图标会打开一个包含两个选项的菜单。
`,
}
示例:金融适配器
{
name: 'stripe',
category: 'finance',
matches: (url) => /^https?:\/\/(dashboard\.)?stripe\.com\//.test(url),
notes: `
- LIVE 与 TEST 模式切换在右上角。始终确认当前模式。
- 退款默认为部分退款——请仔细检查金额。
- 删除客户是不可逆的。
- 订阅:按比例计算的提示("立即收取按比例计算的金额" vs "在下一张发票上")。
`,
}
测试适配器
- 添加适配器到
src/chrome/src/agent/adapters.js和src/firefox/src/agent/adapters.js。 - 验证匹配:在加载了扩展的浏览器中导航到目标 URL。打开服务工作线程/后台页面的 DevTools 控制台并运行:
import { getActiveAdapter, listAdapters } from './agent/adapters.js'; console.log(getActiveAdapter('https://example.com/some-page')); - 验证 notes 出现:在 Ask、Act 或 Dev 模式下,输入一个简单的指令(例如,"这个页面上有什么?")。打开侧面板的详细模式,确认第一条用户消息包含带有你的 notes 的
[Site guidance for <name>]。 - 验证只有一个适配器触发:导航到一个可能匹配多个匹配器的 URL。检查第一个匹配是否胜出且没有其他匹配泄漏。
- 测试导航重新注入:在一个非适配站点上开始对话,然后导航到你的适配站点。确认出现
[Site context changed]消息。
手动测试 URL
打开每个适配站点并验证:
- 适配器在页面 1 上加载(不是在 SPA 路由变化时)
- notes 有用(不会误导模型)
- 模型不会遵循过时的指令
添加新适配器的检查清单
- 将适配器对象添加到
src/chrome/src/agent/adapters.js的ADAPTERS数组中 - 将完全相同的更改同步到
src/firefox/src/agent/adapters.js - 确保
matches()正则表达式具体且不会遮蔽相邻的适配器 - 如果
category: 'finance',将其放在数组中finance-generic之前 - 验证 notes 是 4–8 条简洁的要点
- 使用
getActiveAdapter(url)测试匹配 - 在加载了扩展的情况下测试端到端
- 如果适配器针对非英语市场,添加本地化标签提示(参见 WordPress 适配器了解如何注释非英语 UI 标签的示例)