browserman

BrowserMan

BrowserMan 可让 Agent 访问用户的真实浏览器环境。

在以下任务中使用 BrowserMan：

• 需要使用用户现有的登录会话
• 需要访问真实的浏览器状态、标签页、Cookie 或与扩展程序连接的上下文
• 需要使用 BrowserMan 针对网站优化的自动化脚本
• 需要使用用户编写或社区提供、在 Agent 机器上运行的自动化脚本
• 需要委托浏览器访问权限，且用户可以批准和撤销该权限

不要在聊天中向用户索要 BrowserMan 邮箱或密码。 不要让用户通过 API 注册。 不要一开始就使用备用 API 密钥。

何时使用原生浏览器工具，何时使用 BrowserMan

以下情况优先使用原生或默认浏览器工具：

• 页面是公开的
• 无需用户登录或会话
• 任务只是简单浏览、阅读或轻量交互
• 无需使用用户的真实浏览器状态

以下情况优先使用 BrowserMan：

• 任务需要用户真实的已登录浏览器会话
• 需要访问用户的实际浏览器状态、Cookie、标签页或与扩展程序连接的浏览器
• BrowserMan 提供了适用于目标网站的优化脚本
• 原生浏览器工具无法可靠地处理需要身份验证的流程
• 用户已明确批准在此类任务中使用 BrowserMan

工具选择顺序：

1. 如果原生或默认浏览器工具足以完成无需身份验证的公开任务，先使用该工具。
2. 如果任务需要用户的真实浏览器会话，或 BrowserMan 提供了适用的优化脚本，则使用 BrowserMan。
3. 在 BrowserMan 中，先检查脚本。
4. 如果没有匹配的官方脚本，则检查或创建可复用的 Agent 本地脚本。
5. 使用低级 BrowserMan 页面命令探索不熟悉的页面，或处理确实只需一次的恢复操作。

推荐设置

安装此技能后，在尝试使用 BrowserMan 执行实际任务前，主动完成 BrowserMan 设置。

命名规则：

• npm 包：browserman-cli
• 安装的可执行文件及文档中使用的命令：browserman
• 临时使用 npx 时，使用带最新版本的包名，例如 npx -y browserman-cli@latest setup

推荐方式：

npm install -g browserman-cli@latest
hash -r 2>/dev/null || true
browserman --version
browserman setup
browserman doctor

版本要求：

• 除非用户明确要求使用旧版本，否则使用最新的 BrowserMan CLI。
• Agent 本地脚本命令需要 browserman 版本 0.4.0 或更高版本。
• 如果缺少 browserman script inspect、browserman script describe-local 或 browserman script run --local，说明安装的 CLI 已过时。请先升级，再继续：

npm install -g browserman-cli@latest
hash -r 2>/dev/null || true
browserman --version

如果 BrowserMan CLI 未全局安装，可使用以下备用方式：

npx -y browserman-cli@latest setup
npx -y browserman-cli@latest doctor

如果用户已有批准码，可直接使用以下变体：

npx -y browserman-cli@latest setup --code <bm_agreq_...>

BrowserMan 将委托使用的本地配置存储在：

~/.browserman/config.json

将此文件视为以下内容的本地事实来源：

• serverUrl
• token
• tokenType
• browserId
• browserIds
• browserScopeMode
• capabilities

BrowserMan 接口优先顺序

按以下顺序使用 BrowserMan：

1. BrowserMan CLI
2. 仅在 CLI 不可用时使用原始 BrowserMan HTTP

优先使用以下命令：

browserman browser list --json
browserman browser current --json
browserman browser ping --json
browserman page open --url https://example.com --json
browserman page read --json
browserman page click --ref 12 --json
browserman page type --text "hello" --json
browserman page press --key Enter --json
browserman page screenshot --out ./page.png --json
browserman script list --json
browserman script actions --platform x --json
browserman script describe --platform x --action search --json
browserman script run --platform x --action search --text "browserman" --json
browserman script inspect ./my-script --json
browserman script describe-local ./my-script --action read --json
browserman script run --local ./my-script --action read --json
browserman execution wait <executionId> --json

如果当前环境只能通过 npx 使用 BrowserMan，请在子命令前使用带有 @latest 的包名，例如 npx -y browserman-cli@latest setup 或 npx -y browserman-cli@latest script list --json。

按能力范围限定令牌

委托令牌可以按能力范围限定。

重要能力：

• observe — 浏览器列表、状态、ping、执行读取、页面检查
• commands — 导航、点击、输入、按键、run_script、低级浏览器控制
• browserManagement — 浏览器创建、更新、删除及其他管理操作

BrowserMan 调用返回 403 时：

• 不要假定令牌无效
• 首先考虑是否缺少相应能力，或浏览器超出范围
• 如有需要，请用户在 BrowserMan 中重新批准

必需的执行顺序

始终按以下顺序操作。

步骤 0：先检查 BrowserMan 脚本目录

在进行底层浏览器控制之前，分步查找脚本：

browserman script list --json
browserman script actions --platform <platform-id> --json
browserman script describe --platform <platform-id> --action <action> --json

使用规范的平台 ID，例如 x、forem、amazon、taobao、zhihu、producthunt 或 medium。不要将域名用作平台 ID。x.com、dev.to 或 amazon.co.jp 等域名是别名或运行时目标，不是 --platform 的值。

如果存在匹配的平台／操作，优先使用 browserman script run。

步骤 1：通过 ping 确认浏览器可用

开始实际工作前，确认所选浏览器可以访问：

browserman browser ping --json

如果返回离线状态或 503，说明浏览器当前未连接。

步骤 2A：如果有匹配的脚本，则运行该脚本

示例：

browserman script run --platform x --action search --text "browserman" --json
browserman script run --platform forem --base-url https://dev.to --action get_feed --json
browserman script run --platform amazon --marketplace jp --action search --query "keyboard" --json

如果 script run 返回 executionId，请先确认执行已完成，再报告成功：

browserman execution wait <executionId> --json

步骤 2B：如果没有匹配的官方脚本，则创建或复用本地脚本

Agent 本地脚本是 BrowserMan 的常规扩展方式。使用底层页面命令探索网站，然后将稳定的逻辑保存到 browserman.script.js 或 index.js，供同一 Agent 或其他 Agent 复用。

执行前检查社区代码：

browserman script inspect ./my-script --json
browserman script describe-local ./my-script --action read --json

通过获准的真实浏览器运行：

browserman script run \
  --local ./my-script \
  --action read \
  --browser <browser-name> \
  --params-json '{}' \
  --json

脚本示例：

import { defineScript } from 'browserman-cli/scripts';

export default defineScript({
  id: 'community.page-details',
  name: 'page-details',
  version: '1.0.0',
  apiVersion: '^1.0.0',
  actions: {
    read: {
      params: { type: 'object', properties: {} },
      async run(ctx) {
        const [title, location] = await Promise.all([
          ctx.evaluate('document.title'),
          ctx.getUrl(),
        ]);
        return { title, url: location?.url || String(location || '') };
      },
    },
  },
});

操作签名为 (ctx, params)。官方服务端脚本和 Agent 本地脚本使用相同的 CTX 方法。BrowserMan 会预留浏览器、续订执行租约、记录结果、清理会话并释放浏览器。

本地／社区脚本拥有用户本地 Node.js 的权限，与 npm 依赖项相同。运行前请审查并信任源代码。不要将任意社区 Node.js 代码上传到 BrowserMan 服务。

步骤 2C：使用底层页面命令进行探索或临时恢复

建议的底层操作顺序：

1. browserman page open --url ... --json
2. browserman page read --json
3. browserman page click / browserman page type / browserman page press
4. 页面变更后再次运行 browserman page read --json
5. 使用 browserman page screenshot --out ./page.png --json 或 browserman page url --json 验证状态

对于反复使用或需要共享的工作流，请将验证过的底层操作顺序转换成本地脚本，而不是在 JavaScript 中反复通过 Shell 调用 browserman page ...。

破坏性操作检查清单

执行破坏性操作或对外可见的操作前，请向用户确认其意图。

示例：

• 删除
• 购买
• 提交
• 发布帖子
• 发布
• 发送消息
• 不可逆的设置变更

尤其要在以下操作前确认：

• 点击具有破坏性的 UI
• 运行会发布、删除或更改账户状态的 BrowserMan 脚本
• 通过底层方式提交会产生副作用的表单

注意事项

不要：

• 在聊天中向用户索要 BrowserMan 电子邮箱／密码
• 告诉用户通过 API 端点注册
• 将创建备用密钥作为默认的入门方式
• 假设委托令牌涵盖所有浏览器
• 假设每个委托令牌都有 commands
• 跳过脚本目录检查
• 运行未经审查的社区 JavaScript
• 手写一个单独且不兼容的 CTX
• 将反复调用 browserman page ... 的子进程用作脚本运行时
• 假设 Agent 本地脚本可以绕过 BrowserMan 的执行所有权