插件

插件让 agent-browser 能够与外部工具集成，而无需将这些工具加入核心。插件是一个本地可执行文件，它从 stdin 读取一条 JSON 请求，并向 stdout 写入一条 JSON 响应。

可将插件用于基于 vault 的登录、自定义浏览器提供方、本地启动定制，以及特定领域的命令（例如 CAPTCHA 解决）。

何时编写插件¶

当集成需要供应商 SDK、本地 CLI、凭据、付费 API，或不应成为 agent-browser 依赖的行为时，请编写插件。

适合插件处理的场景：

从外部 vault 解析登录凭据
通过托管提供方启动浏览器，并返回 CDP WebSocket URL
添加本地 Chrome 启动参数、扩展或 init 脚本
运行带命名空间的命令，例如 captcha.solve

将浏览器自动化本身保留在 agent-browser 中。插件应提供数据或启动配置，然后让 agent-browser 继续驱动浏览器。

适合构建为插件的内容¶

这些是插件作者的良好起点：

新的云浏览器提供方：托管浏览器平台是 browser.provider 的良好实现模型。为兼容性起见，现有内建提供方可保留在核心中，但新的提供方通常应以插件形式起步。
Vault 集成：密码管理器、机密存储和企业 SSO 辅助工具适合 credential.read。将本地加密的认证 vault 保留在核心中，但将特定供应商的 vault 访问放在插件中。
隐身与反检测：这些技术变化很快，在核心中支持可能带来风险。它们适合 launch.mutate 插件，用于追加启动参数、扩展、init 脚本或 user-agent 覆盖。
CAPTCHA 解决器：CAPTCHA 集成属于插件领域，因为它们涉及第三方 API、凭据、政策考量以及快速的供应商更迭。它们可以使用 command.run 或自定义能力（如 captcha.solve）。
特定供应商的认证辅助工具：针对特定应用、IdP 或企业流程的登录辅助工具应放在核心之外，除非它们成为通用的浏览器自动化原语。

添加他人构建的插件¶

使用包名或仓库名运行 plugin add：

agent-browser plugin add agent-browser-plugin-captcha
agent-browser plugin add @company/agent-browser-plugin-vault --name vault
agent-browser plugin add org/agent-browser-plugin-cloud-browser

agent-browser 根据引用形式选择来源：

引用形式	来源	示例
`name`	npm 包	`agent-browser-plugin-captcha`
`@scope/name`	作用域 npm 包	`@company/agent-browser-plugin-vault`
`owner/repo`	GitHub 仓库	`org/agent-browser-plugin-cloud-browser`

plugin add 默认写入 ~/.agent-browser/config.json。使用 --project 可改为写入 ./agent-browser.json（仅与 --config 搭配使用）。

添加过程中，agent-browser 会运行该包一次，并请求 plugin.manifest。插件清单声明插件的名称和能力。如果插件尚不支持清单，请使用插件 README 中列出的能力：

agent-browser plugin add agent-browser-plugin-captcha --capability command.run --capability captcha.solve --no-manifest

验证插件已正确配置：

agent-browser plugin list
agent-browser plugin show captcha

然后通过该能力对应的命令路径使用它：

agent-browser auth login my-app --credential-provider vault --item "My App"
agent-browser auth login my-app --credential-provider vault --item "My App" --no-navigate --url https://identity.example.com/login
agent-browser --provider cloud-browser open https://example.com
agent-browser open https://example.com
agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"abc","url":"https://example.com"}'

launch.mutate 插件会在本地启动时自动运行，例如 agent-browser open。

凭据解析、浏览器启动与清理以及启动变更相关错误会从诊断信息中省略插件响应的错误文本和不支持的协议值。清单发现和 plugin run 会保留详细错误。插件仍是受信任的本地可执行文件；此删减行为不会对它们进行沙箱隔离。

配置插件¶

plugin add 会为你创建此配置。你也可以手动编辑 plugins 数组：

{
  "plugins": [
    {
      "name": "vault",
      "command": "agent-browser-plugin-vault",
      "args": [],
      "capabilities": ["credential.read"]
    },
    {
      "name": "captcha",
      "command": "agent-browser-plugin-captcha",
      "capabilities": ["command.run", "captcha.solve"]
    }
  ]
}

检查注册表：

agent-browser plugin list
agent-browser plugin show vault

AGENT_BROWSER_PLUGINS 可以用形状相同的 JSON 数组来代替配置发现。

不要将 API 令牌、vault 令牌或密码放入插件的 args 中。请在 agent-browser 配置之外使用供应商自己的 CLI 登录、钥匙串、环境或会话机制。

协议¶

agent-browser 启动该可执行文件，将此信封写入 stdin，等待 stdout 输出，并将 stdout 解析为 JSON：

{
  "protocol": "agent-browser.plugin.v1",
  "type": "credential.resolve",
  "capability": "credential.read",
  "request": {}
}

每个成功响应都必须包含相同的协议和 success: true：

{
  "protocol": "agent-browser.plugin.v1",
  "success": true,
  "data": {}
}

仅解析 stdout。不要向 stdout 写入任何日志。对于核心集成，agent-browser 会抑制插件的 stderr，因此在开发时请使用文件或自己的调试模式。

核心集成会在面向用户的错误中抑制插件提供的错误文本，以减少机密的意外暴露。通用的 plugin run 会保留插件错误文本，因为它是一个面向开发者的命令。

插件清单¶

支持 plugin.manifest，这样用户无需手动输入能力即可添加你的插件：

{
  "protocol": "agent-browser.plugin.v1",
  "type": "plugin.manifest",
  "capability": "plugin.manifest",
  "request": {}
}

返回插件名称和能力：

{
  "protocol": "agent-browser.plugin.v1",
  "success": true,
  "manifest": {
    "name": "captcha",
    "capabilities": ["command.run", "captcha.solve"],
    "description": "Solve CAPTCHA challenges through Example CAPTCHA"
  }
}

有了清单，用户可以运行：

agent-browser plugin add agent-browser-plugin-captcha

如果没有清单，用户在添加时必须传递 --capability 标志。

能力¶

能力	请求类型	用户如何调用	响应字段
`credential.read`	`credential.resolve`	`auth login --credential-provider <name>`	`credential`
`browser.provider`	`browser.launch`, `browser.close`	`--provider <name>`	`browser`
`launch.mutate`	`launch.mutate`	任何本地启动	`launch`
`command.run`	自定义请求类型	`plugin run <name> <type>`	`data`

插件可以声明自定义能力，例如 captcha.solve。plugin run 可以调用 command.run 和自定义能力，但不能直接调用核心能力或协议请求类型。对于 credential.read、browser.provider 和 launch.mutate，请使用专用的命令路径。

最小插件¶

此插件实现了 captcha.solve 并返回一个伪造的 Token：

#!/usr/bin/env node

const chunks = [];
for await (const chunk of process.stdin) {
  chunks.push(chunk);
}

const input = JSON.parse(Buffer.concat(chunks).toString("utf8"));

function reply(body) {
  process.stdout.write(
    JSON.stringify({
      protocol: "agent-browser.plugin.v1",
      success: true,
      ...body,
    })
  );
}

if (input.protocol !== "agent-browser.plugin.v1") {
  process.stdout.write(
    JSON.stringify({
      protocol: "agent-browser.plugin.v1",
      success: false,
      error: "unsupported protocol",
    })
  );
  process.exit(0);
}

if (input.type === "plugin.manifest") {
  reply({
    manifest: {
      name: "captcha",
      capabilities: ["command.run", "captcha.solve"],
      description: "Example CAPTCHA plugin",
    },
  });
  process.exit(0);
}

if (input.type === "captcha.solve") {
  reply({
    data: {
      token: "example-token",
      siteKey: input.request.siteKey,
      url: input.request.url,
    },
  });
  process.exit(0);
}

process.stdout.write(
  JSON.stringify({
    protocol: "agent-browser.plugin.v1",
    success: false,
    error: `unsupported request type: ${input.type}`,
  })
);

使其可执行并进行配置：

chmod +x ./agent-browser-plugin-captcha

{
  "plugins": [
    {
      "name": "captcha",
      "command": "./agent-browser-plugin-captcha",
      "capabilities": ["command.run", "captcha.solve"]
    }
  ]
}

运行它：

agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"abc","url":"https://example.com"}'

凭据插件¶

凭据插件会收到：

{
  "protocol": "agent-browser.plugin.v1",
  "type": "credential.resolve",
  "capability": "credential.read",
  "request": {
    "profileName": "my-app",
    "itemRef": "My App",
    "url": "https://app.example.com/login"
  }
}

返回 credential：

{
  "protocol": "agent-browser.plugin.v1",
  "success": true,
  "credential": {
    "username": "alice@example.com",
    "password": "secret",
    "url": "https://app.example.com/login",
    "usernameSelector": "#username",
    "passwordSelector": "#password",
    "submitSelector": "input[type=submit]"
  }
}

将其用于一次登录：

agent-browser auth login my-app --credential-provider vault --item "My App"

对于需要通过有状态的页面内设置才能到达的登录表单，请添加 --no-navigate。当前活动的顶层页面必须与有效的凭据 URL 具有相同的协议、主机和有效端口。命令级别的 --url 会覆盖提供程序的 URL 元数据，并在不导航的情况下提供这个预期的源。提供程序的机密信息不会出现在生成的进程参数和常规输出中：

agent-browser auth login my-app --credential-provider vault --item "My App" --no-navigate --url https://identity.example.com/login

对于外部保险库，建议从插件中调用厂商的 CLI，并依赖其现有的本地会话。不要在 agent-browser.json 中传递保险库的 Token。

浏览器提供程序插件¶

浏览器提供程序插件会收到 browser.launch 并返回一个 CDP URL：

{
  "protocol": "agent-browser.plugin.v1",
  "success": true,
  "browser": {
    "cdpUrl": "ws://127.0.0.1:9222/devtools/browser/session",
    "directPage": false,
    "metadata": {
      "sessionId": "provider-session-id"
    },
    "cleanup": {
      "sessionId": "provider-session-id"
    }
  }
}

然后用户可以通过插件名称启动：

agent-browser --provider cloud-browser open https://example.com

如果返回了 cleanup 但连接失败，agent-browser 稍后会将其作为 browser.close 的请求体发送回去。

启动修改器插件¶

启动修改器在 Chrome 启动前接收本地启动选项，并且可以追加参数、扩展、初始化脚本或用户代理：

{
  "protocol": "agent-browser.plugin.v1",
  "success": true,
  "launch": {
    "args": ["--disable-blink-features=AutomationControlled"],
    "extensions": ["/absolute/path/to/extension"],
    "initScripts": [
      "Object.defineProperty(navigator, 'webdriver', { get: () => undefined });"
    ],
    "userAgent": "my-agent/1.0"
  }
}

使用 launch.mutate 进行配置，然后使用任意本地启动命令：

agent-browser open https://example.com

启动修改器（Launch mutators）不会作用于 CDP 连接或远程浏览器提供商，因为这些浏览器已经在本地启动路径之外运行。

策略与确认¶

插件访问以能力范围策略操作的形式暴露：

agent-browser --confirm-actions plugin:vault:credential.read auth login my-app --credential-provider vault --item "My App"
agent-browser --confirm-actions plugin:cloud-browser:browser.provider --provider cloud-browser open https://example.com
agent-browser --confirm-actions plugin:stealth:launch.mutate open https://example.com

操作字符串格式为 plugin:<名称>:<能力>。

打包指南¶

对于 npm 包，暴露一个 bin 命令，且不输出必要的标准输出日志：

{
  "name": "agent-browser-plugin-example",
  "bin": {
    "agent-browser-plugin-example": "./bin/plugin.js"
  }
}

保持插件小巧且明确：

仅声明其实际支持的能力
从标准输入精确读取一个请求
向标准输出精确写入一个 JSON 响应
将机密信息排除在命令行参数之外
让 agent-browser 处理导航、选择器、截图、状态和策略

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser