# @centralinc/browseragent 中文文档

规范地址：https://npmcn.com/package/%40centralinc/browseragent/

版本：1\.9\.6
npm 元数据更新时间：2026-01-07T17:25:57.102Z
中文译文更新时间：2026-11-09T07:50:05.170Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40centralinc/browseragent
原文对照：https://npmcn.com/package/%40centralinc/browseragent/?lang=original
项目主页：https://github.com/centralinc/browseragent#readme
源码仓库：https://github.com/centralinc/browseragent

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：226 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：@playwright/test ^1\.40\.0，playwright ^1\.40\.0，zod ^3\.25\.0，zod-to-json-schema ^3\.23\.0
- 首次发布：2025-08-28T19:50:55.920Z
- 最新版本发布：2026-01-07T17:25:56.700Z
- 近 30 天下载量：13689（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 8 个）

## 中文简介

使用 Playwright 计算机使用的浏览器自动化代理

## 安装

```sh
npm install @centralinc/browseragent
```

也可以使用：`pnpm add @centralinc/browseragent`、`yarn add @centralinc/browseragent`、`bun add @centralinc/browseragent`

## README

# @ centroinc/ 浏览器

使用计算机使用 Playwright 的浏览器自动化代理. 这个TypeScript SDK将Anthropic的计算机使用能力与Playwright相结合,为使用克洛德的计算机使用能力实现浏览器交互自动化提供清洁,类型安全的接口.

这个叉子是 **为高容量的RPA情景设计**——思考大型保险后台,政府形式填报门户等数据繁多的工作流程.  
它运行 **在临时工作流程中无缝**: 代理商为本地人 `pause` 编号 : `resume` 编号 : `cancel` **信号** 可被浮出水面 **临时信号**,让你的管弦乐层协调长期的工作,而操作员则在需要时跳入(人与Temperal本身之间没有紧密的接合).  
我们的目标是揭露一个 **高可塑性、精致的制剂**——分拨为生速或分拨为下拨为像素完美,人相精准.

## 此分叉中的其他特性

> **亮度特征矩阵**
> 
> | \* 能力 | 它会做什么 | 怎么会这样 |
> | --- | --- | --- |
> | **工具登记** | 任何工具通用能力系统 | 用Slack,Discord,数据库等扩展代理. |
> | **智能滚动** | 90%的取景口卷轴+即时文本导航 | Turbo 页面翻转 **财务报告和审定财务报表** 零废物倒放控制 |
> | **打字模式** | 填充、快速特征、人类特征 | 匹配 CAPTCHA 相容性或通过输入燃烧 |
> | **信号总线** | 暂停/ 恢复/ 取消任何步骤 | 在生产中增加人质检检查站 |
> | **URL 提取器** | 通过可见文本查找链接 | 需要零 CSS 选择器 |
> | **速度调整** | 屏幕截图 + 延迟优化 | 截断多步流从分到秒 |
> | **浏览器上下文** | 为自定义工具创建Page( ) | 子代理、 孤立任务、 共享会话 |

以下是分叉中运出的主要改进:

### URL 提取工具

从任何可见元素提取 URL - 不需要 CSS 选择器 ! 这个特性是 **此叉子独有**。 。 。 .

#### 如何运作

代理在您通过可见文本请求 URL 时自动使用 URL 提取工具 :

```typescript
// Simple URL extraction - just ask naturally!
const url = await agent.execute('Extract the URL from the "Learn More" link');

// Extract from article titles
const articleUrl = await agent.execute(
  'Get the URL from the article titled "Introduction to AI"',
);

// Extract multiple URLs with structured output
const urls = await agent.execute(
  "Extract URLs from the top 3 navigation links",
  z.array(
    z.object({
      linkText: z.string(),
      url: z.string(),
    }),
  ),
);
```

#### 高级能力

**智能搜索策略** (按顺序排列):

1.  **准确的文本匹配** - 查找包含准确可见文本的元素
2.  **部分文本匹配** - 在更大的内容块内匹配文本
3.  **锁定标记检测** - 地点 `<a>` 包含文本的标签
4.  **CSS 选择器倒置** - 如果文本是有效的选择器,则直接选择元素
5.  **可点击元素搜索** - 找到与文本互动的元素
6.  **URL 模式提取** - 检测直接在文本内容中的 URL

**技术特征**数字 :

-   **计算机使用优化** - 与克洛德的视觉感知无缝工作
-   **多个 HTML 结构** - 处理复杂的嵌入元素和动态内容
-   **自动 URL 正常化** - 相对于绝对 URL 转换
-   **智能错误处理** - 在元素找不到时提供有益的反馈
-   **日志和调试** - 内置控制台记录故障

**最佳做法**数字 :

-   使用页面上可见的文本
-   对于按钮或链接,请使用其标签文本(例如"Download","Read More","View Details")
-   对于文章或故事,请使用其标题文本
-   该工具将自动处理查找关联的 URL

* * *

### 工具登记系统

扩展您的代理 **任何外部工具** 使用我们灵活的能力系统 不只是Playwright!

#### 如何运作

工具注册提供了一种简单、安全的方式,为您的代理人添加能力:

```typescript
import { registerPlaywrightCapability } from "@centralinc/browseragent";

// Add a custom Playwright capability
registerPlaywrightCapability({
  method: "check_all",
  displayName: "Check All Checkboxes",
  description: "Check all checkboxes matching a pattern",
  usage: "Check multiple checkboxes at once by pattern",
  schema: z.tuple([z.string()]),
  handler: async (page, args) => {
    const [pattern] = args;
    await page.locator(`input[type="checkbox"]${pattern}`).check();
    return { output: `Checked all checkboxes matching ${pattern}` };
  },
});

// Use it naturally in prompts
await agent.execute('Check all the "Accept Terms" checkboxes on this form');
```

#### 扩展超越播放机

登记册支持 **任何工具类型**。这里有一个Slack整合的例子:

```typescript
// Create a Slack tool
class SlackTool implements ComputerUseTool {
  name: "slack" = "slack";
  // ... implementation
}

// Use it with the agent
const agent = new ComputerUseAgent({
  apiKey: ANTHROPIC_API_KEY,
  page,
  additionalTools: [new SlackTool(SLACK_TOKEN)],
});

// Natural language Slack operations
await agent.execute(
  "Send a message to #general saying the deployment is complete",
);
await agent.execute(
  "Navigate to the metrics dashboard and share a screenshot in #analytics",
);
```

**支持的工具类型**数字 :

-   📧 **通讯**: Slack, Discord, Teams, 电子邮件
-   🗄️ **数据**: 数据库、 API、 文件系统
-   🔧 **公用事业**: AWS, GitHub, 吉拉语
-   🤖 **自定义**:任何你能想象的工具!

**关键特性**数字 :

-   带有 Zod 计划的类型安全
-   自动生成的文档
-   自然语言提示
-   不需要复杂的遗产

见 [工具注册设计文档](https://npmcn.com/package/%40centralinc/browseragent/design-docs/tool-registry.md) 用于完整的例子.

* * *

### QQ 即时文本导航

直接跳转到下拉、列表或可滚动容器中的任何文本 - 不需要多次滚动尝试 !

#### 如何运作

探员可以使用 `scroll_to_text` 立即导航特定文本的剧作家方法 :

```typescript
// The agent sees a state dropdown and needs Wyoming
await agent.execute(`
  Use the playwright scroll_to_text method to find "Wyoming" in the state picker
`);

// Behind the scenes, the agent calls:
// {"name": "playwright", "input": {"method": "scroll_to_text", "args": ["Wyoming"]}}
```

**智能特性**数字 :

-   在取景口自动检测可滚动容器
-   首先搜索可见的容器, 然后搜索整页
-   找不到精确匹配的大小写后退
-   如果找不到文本, 则光彩地返回正则滚动
-   不需要 CSS 选择器 - 只是可见的文本!

**当代理使用时**数字 :

-   在降水中寻找具体选项(国家、国家等)
-   浏览长列表中的产品
-   跳转到边栏中的特定项目
-   任何确切文本已知的情景

**示例**:取而代之的是取出"怀俄明"的"10+"小卷轴",而现在却成了单一的即时跳出!

* * *

### 智能滚动( 90% Viewport)

在小的UI元素中保留精确控制的同时通过长页速度.

-   **默认行为**  ^ 卷起~90%的取景口与~10%相重叠,达到最大吞吐量.
-   **精细控制**  →  `scroll_amount` 介于 **5-20 (中文(简体) )** 做细小的卷轴 完全适合倒地 列表 侧面板.
-   **可配置**  • 接受任何 `scroll_amount` 1 -100 和优雅地贬低.

> **为什么这很重要**:Form-havy门户网站(例如保险索赔系统)往往需要快速的页平面滚动,由所选部件内部的像素-完美调整来取出. 此功能会自动处理两个案件.

* * *

### 速度优化

现在抓取屏幕截图 **~5× 更快 ~** 行动后等待时间缩短:

| 行动 | 旧的延迟 | 新建延迟 |
| --- | --- | --- |
| 屏幕截图等待 | 2个s | 0.3 s (中文(简体) ) |
| 后打字等待 | 0.5 s (单位:千美元) | 0.1 s (中文(简体) ) |
| 滚动后等待 | 0.5 s (单位:千美元) | 0.1 s (中文(简体) ) |
| 鼠标移动暂停 | 0.1 s (中文(简体) ) | 0.02 s (中文(简体) ) |

这些切口 **1-2秒** 从每个多步交互.

> ⚠️ **备注:** 一些站点依靠人相距来进行反机器人检查. 如果您遇到 Captchas 或 缺失的状态, 请通过新的构造参数增加延迟 :
> 
> ```ts
> const fastComputer = new ComputerTool(
>   page,
>   "20250124",
>   /* screenshotDelay */ 0.5,
> );
> // or adjust post-action waits inside ComputerTool if needed
> ```

* * *

### \* 代理信号(暂停/恢复/取消)

带上 **人员控制** 到长期运行的自动化工作流程.

-   **暂停** 活动 `agent.execute()` 运行以检查或修正页面
-   **继续** 从你离开的确切一步
-   **取消** 优雅而又不破坏过程
-   实时活动: `onPause`, (中文(简体) ), `onResume`, (中文(简体) ), `onCancel`, (中文(简体) ), `onError`

```typescript
const agent = new ComputerUseAgent({ apiKey, page });

// Subscribe to events
agent.controller.on("onPause", ({ step }) => console.log("Paused at", step));
```

* * *

### \===================================================================================================================================================================================

这个分叉包括一个强大的配置系统,允许您自定义代理如何执行浏览器自动化任务. 您可以控制打字速度、 截图时间、 滚动策略、 鼠标行为以及其他自动化设置以优化原始速度 **或者说** 人性互动.

#### 可用的配置选项

```typescript
import type { ExecutionConfig } from "@centralinc/browseragent";

const executionConfig: ExecutionConfig = {
  typing: {
    mode: "fill" | "character-by-character",
    characterDelay: 12, // milliseconds between characters (character-by-character mode)
    completionDelay: 100, // milliseconds to wait after typing completes
  },
  screenshot: {
    delay: 0.3, // seconds to wait before taking screenshots
    quality: "low" | "medium" | "high",
  },
  mouse: {
    moveSpeed: "instant" | "fast" | "normal" | "slow",
    clickDelay: 50, // milliseconds to wait after clicks
  },
  scrolling: {
    /**
     * When no scroll_amount is provided the agent will use this mode
     * with ~90 % viewport coverage for page-level scrolling.
     */
    mode: "percentage", // (future-proofed for pixel or element-based modes)
    /** Default percentage of the viewport to scroll. */
    percentage: 90,
    /** Overlap percentage to keep for context during large scrolls. */
    overlap: 10,
  },
};
```

#### 打字模式配置

最有影响的配置是打字行为. 您可以选择两种模式:

**QQ 填充模式( Fasters)** - 直接填补全部绕过键盘事件的输入字段:

```typescript
const fastAgent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  page,
  executionConfig: {
    typing: { mode: "fill", completionDelay: 50 },
  },
});
```

**++ 字符逐字模式( 类似人)** - 在可配置的延迟情况下,一次输入文本一个字符:

```typescript
const humanLikeAgent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  page,
  executionConfig: {
    typing: {
      mode: "character-by-character",
      characterDelay: 100, // 100ms between each character
      completionDelay: 200,
    },
  },
});
```

**QQ 快字符模式 (Balanced)** - 最好的两个世界 - 可见的打字,但非常快:

```typescript
const balancedAgent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  page,
  executionConfig: {
    typing: {
      mode: "character-by-character",
      characterDelay: 5, // Very fast character typing
      completionDelay: 75,
    },
  },
});
```

**性能比较 :**

| 模式 | 速度 | 可见度 | 使用大小写 |
| --- | --- | --- | --- |
| **填充** | ⚡⚡⚡最快 | \* 即时 | 生产、速度关键任务 |
| **快速字符** | {\\fn华文楷体\\fs16\\1cHE0E0E0}非常快 {\\fn华文楷体\\fs16\\1cHE0E0E0}非常快 | \* 可见 | 开发、调试 |
| **慢字符** | 像人类一样 | \* \* \* 十分明显 | 人型自动化软件 |

#### 尝试示例

运行包含的示例以查看性能差异 :

```bash
# Run the typing configuration example (set ANTHROPIC_API_KEY first)
npx ts-node examples/example-typing-config.ts
agent.controller.on('onResume', () => console.log('Resumed'));

// Trigger a pause after 5 s
setTimeout(() => agent.controller.signal('pause'), 5_000);

// Start a task (the controller is available immediately)
await agent.execute('Get the titles of the top 10 stories');
```

用于调试、监视超时和手动操作.

* * *

### QQ 自定义工具的上下文访问

自定义工具现在可以生成新页面甚至 **将任务委托给子代理人** ,同时共享同一浏览器会话(cookies,代理,反检测).

#### 如何运作

这个 `ToolExecutionContext` 现规定:

-   **`createPage()`** - 创建一个有防检测脚本的新页面
-   **`browserContext`** - 直接进入 Playwright `BrowserContext`

```typescript
import type { ComputerUseTool, ToolResult, ToolExecutionContext } from "@centralinc/browseragent";

class ActivationLinkTool implements ComputerUseTool {
  name = "click_activation_link";

  async call(params: Record<string, unknown>, ctx?: ToolExecutionContext): Promise<ToolResult> {
    if (!ctx?.createPage) {
      return { error: "Browser context not available" };
    }

    const { url } = params as { url: string };
    const page = await ctx.createPage();

    try {
      await page.goto(url, { waitUntil: "domcontentloaded" });
      return { output: `Navigated to ${page.url()}` };
    } finally {
      await page.close();
    }
  }
}
```

#### 副代理代表团模式

真正的权力是 **产出子剂** 用于执行孤立任务的新页面:

```typescript
import { ComputerUseAgent } from "@centralinc/browseragent";
import { z } from "zod";

class DelegatedTaskTool implements ComputerUseTool {
  name = "delegated_task";

  async call(params: Record<string, unknown>, ctx?: ToolExecutionContext): Promise<ToolResult> {
    if (!ctx?.createPage) {
      return { error: "Browser context not available" };
    }

    const { task, url } = params as { task: string; url: string };
    const page = await ctx.createPage();

    try {
      await page.goto(url);

      // Create a sub-agent on the new page
      const subAgent = new ComputerUseAgent({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        page,
      });

      // Execute task and get structured result
      const result = await subAgent.execute(
        task,
        z.object({ data: z.string(), success: z.boolean() })
      );

      return { output: JSON.stringify(result) };
    } finally {
      await page.close();
    }
  }
}
```

**使用大小写 :**

-   📧 **电子邮件验证** - 导航激活链接, 返回成功状态
-   🔐 **OA 流量** - 在单独的一页中处理 OAuth, 返回符号
-   📊 **数据刮取** - 与外界隔绝,返回结构化数据
-   🔄 **多站工作流程** - A探员触发B副探员获取数据
-   ⚡ **平行行动** - 不同页面上的多个子代理人同时使用

#### 共享输入脚本

在您的初始页面中应用相同的反检测脚本 :

```typescript
import { applyInitScripts, ComputerUseAgent } from "@centralinc/browseragent";

const page = await context.newPage();
await applyInitScripts(page); // Same scripts used by createPage()
await page.goto("https://example.com");

const agent = new ComputerUseAgent({ apiKey, page });
```

**主要惠益:**

-   页面共享 cookie, 存储和会话状态
-   自动继承代理配置
-   一致适用反侦查脚本
-   管理好的页面被清理出错误

* * *

## 特征

-   🤖 **简单 API**单人 `ComputerUseAgent` 所有计算机使用任务的类
-   🔄 **双重反应类型**:支持案文和结构化(JSON)对策
-   🛡️ **类型安全**: 用 Zod schema 验证的完整类型脚本支持
-   ⚡ **优化**: 清除错误处理和强大的 JSON 解析
-   🎯 **重点**: 具有合理默认的清洁 API 表面

## 安装

```bash
npm install @centralinc/browseragent playwright @playwright/test
# or
yarn add @centralinc/browseragent playwright @playwright/test
# or
pnpm add @centralinc/browseragent playwright @playwright/test
```

## 快速启动

```typescript
import { chromium } from "playwright";
import { ComputerUseAgent } from "@centralinc/browseragent";

const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();

// Navigate to Hacker News manually first
await page.goto("https://news.ycombinator.com/");

const agent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  page,
});

// Simple text response
const answer = await agent.execute("Tell me the title of the top story");
console.log(answer);

await browser.close();
```

## API 参考

### `ComputerUseAgent`

计算机使用自动化主课.

#### 构造器

```typescript
new ComputerUseAgent(options: {
  apiKey: string;
  page: Page;
  model?: string;
})
```

**参数:**

-   `apiKey` 你的Anthropic API密钥。 从一个 [自动控制台](https://console.anthropic.com/)
-   `page` (页):用于控制的 Playwright 页面实例
-   `model` (弦,可选): 使用Anthropic模型. 默认为 `'claude-sonnet-4-20250514'`

**支持的模式 :** 见 [Anthropic 的计算机使用文档](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool#model-compatibility) 用于最新的模型兼容性.

#### `execute()` 方法

```typescript
async execute<T = string>(
  query: string,
  schema?: z.ZodSchema<T>,
  options?: {
    systemPromptSuffix?: string;
    thinkingBudget?: number;
  }
): Promise<T>
```

**参数:**

-   **`query`** (字符串):克劳德要执行的任务描述
-   **`schema`** (ZodSchema,可选): Zod schema 用于结构化响应. 提供后,将对照这一计划验证答复
-   **`options`** (对象,可选):
    -   **`systemPromptSuffix`** (字符串):系统上附加的补充指令提示
    -   **`thinkingBudget`** (数字):克劳德内部推理过程的托肯预算. 默认 : `1024`。见 [扩展思维文档](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) 详情

**回返情况:**

-   `Promise<T>`: 当 `schema` 提供了类型已验证的返回数据 `T`
-   `Promise<string>`: 当无 `schema` 返回文本响应

## 用法实例

### 文本回应

```typescript
import { ComputerUseAgent } from "@centralinc/browseragent";

// Navigate to the target page first
await page.goto("https://news.ycombinator.com/");

const agent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  page,
});

const result = await agent.execute(
  "Tell me the title of the top story on this page",
);
console.log(result); // "Title of the top story"
```

### 与Zod的结构性反应

```typescript
import { z } from "zod";
import { ComputerUseAgent } from "@centralinc/browseragent";

const agent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  page,
});

const HackerNewsStory = z.object({
  title: z.string(),
  points: z.number(),
  author: z.string(),
  comments: z.number(),
  url: z.string().optional(),
});

const stories = await agent.execute(
  "Get the top 5 Hacker News stories with their details",
  z.array(HackerNewsStory).max(5),
);

console.log(stories);
// [
//   {
//     title: "Example Story",
//     points: 150,
//     author: "user123",
//     comments: 42,
//     url: "https://example.com"
//   },
//   ...
// ]
```

### 高级选项

```typescript
const result = await agent.execute(
  "Complex task requiring more thinking",
  undefined, // No schema for text response
  {
    systemPromptSuffix: "Be extra careful with form submissions.",
    thinkingBudget: 4096, // More thinking tokens for complex tasks
  },
);
```

### 重试配置

SDK包括处理连接错误和瞬间故障的内置重试逻辑:

```typescript
import { ComputerUseAgent, type RetryConfig } from "@centralinc/browseragent";

const retryConfig: RetryConfig = {
  maxRetries: 5,             // Maximum retry attempts (default: 3)
  initialDelayMs: 2000,      // Initial delay between retries (default: 1000ms)
  maxDelayMs: 60000,         // Maximum delay between retries (default: 30000ms)
  backoffMultiplier: 2.5,    // Exponential backoff multiplier (default: 2)
  preferIPv4: true,          // Prefer IPv4 DNS resolution (helpful with VPNs like Tailscale)
  retryableErrors: [         // Errors that trigger retries
    "Connection error",
    "ECONNREFUSED",
    "ETIMEDOUT",
    "ECONNRESET",
    "socket hang up",
  ],
};

const agent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  page,
  retryConfig, // Custom retry configuration
});
```

复试机制使用与焦躁相伴的指数回放来避免打雷群出问题. 连接出错和网络超时会随着越来越多的延迟而自动重审.

**VPN/ Tailscale 用户的说明 :** 如果你正在经历 `ENETUNREACH` iPv6 地址出错, 设置 `preferIPv4: true` 在您重试配置中将 DNS 解析为 IPv4 地址.

### 工具注册 API

SDK输出功能用于扩展能力:

```typescript
import {
  registerPlaywrightCapability,
  getToolRegistry,
  defineCapability,
} from "@centralinc/browseragent";

// Register a new Playwright capability
registerPlaywrightCapability({
  method: "custom_action",
  displayName: "Custom Action",
  description: "Performs a custom browser action",
  usage: "Detailed usage instructions",
  schema: z.object({ selector: z.string() }),
  handler: async (page, args) => {
    // Implementation
    return { output: "Success" };
  },
});

// Register capabilities for other tools
const registry = getToolRegistry();
registry.register(
  defineCapability("slack", "send_message", {
    displayName: "Send Message",
    description: "Send a Slack message",
    usage: "Send message to channel",
    schema: z.tuple([z.string(), z.string()]),
  }),
);
```

## 环境设置

1.  **Anthropic API 密钥**: 将您的 API 密钥设置为环境变量 :
    
    ```bash
    export ANTHROPIC_API_KEY=your_api_key_here
    ```
    
2.  **剧作家**: 安装 Playwright 和浏览器依赖性 :
    
    ```bash
    npx playwright install
    ```
    

## 计算机使用参数

这个SDK利用了Anthropic的"计算机使用API",其关键参数如下:

### 模式选择

-   **Claude 3.5 索内**:大多数任务的速度和能力的最佳平衡
-   **克洛德4型号**: 增强思维能力
-   **克洛德·3.7 索内**: 思维透明的高级推理

### 思考预算

这个 `thinkingBudget` 参数控制克洛德的内部推理过程:

-   **1024个纪念品** (默认):适合简单的任务
-   **4096+ 纪念品**: 更适合复杂的推理任务
-   **16k+ 符号**建议采取高度复杂的多步骤行动

见 [Anthropic 扩展思维指南](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#working-with-thinking-budgets) 用于优化提示.

## 处理错误

SDK包括内置错误处理:

```typescript
try {
  const result = await agent.execute("Your task here");
  console.log(result);
} catch (error) {
  if (error.message.includes("No response received")) {
    console.log("Agent did not receive a response from Claude");
  } else {
    console.log("Other error:", error.message);
  }
}
```

## 最佳做法

1.  **使用具体、明确的指令**:"点击红色"屈服"按钮对"点击提交"
    
2.  **对于复杂的任务,拆开**: 在查询中使用分步指示
    
3.  **优化思维预算**: 从默认开始( 1024) 为复杂任务增加
    
4.  **处理错误优雅**: 为生产用途实施适当的错误处理
    
5.  **使用结构化响应**: 当您需要特定的数据格式时, 请使用 Zod schemas
    
6.  **无头测试:虚假**: 在开发过程中, 使用可见浏览器来调试
    

## 安全考虑

⚠️ **重要**:计算机的使用可以与任何可见的应用程序相互作用. 总是:

-   在孤立的环境中运行(容器/VMs),用于生产
-   避免提供访问敏感账户或数据的机会
-   在部署生产前审查克洛德在日志中的行动
-   可能时使用允许列表域

见 [Anthropic 计算机使用安全指南](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool#security-considerations) 详细安保建议.

## 所需资源

-   节点.js 18+
-   类型脚本 5+
-   剧作家 1.52+
-   Anthropic API 键

## 相关资源

-   [Athropic 计算机使用文档](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool)
-   [扩展思维指南](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)
-   [剧作家文档](https://playwright.dev/)
-   [Zod 文档](https://zod.dev/)

## 许可证

见 [许可证](https://npmcn.com/package/%40centralinc/browseragent/LICENSE)

## 常见问题

### @centralinc/browseragent 是什么？

使用 Playwright 计算机使用的浏览器自动化代理

### 如何安装 @centralinc/browseragent？

在项目目录运行 npm install @centralinc/browseragent，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@playwright/test（^1\.40\.0）、playwright（^1\.40\.0）、zod（^3\.25\.0）、zod-to-json-schema（^3\.23\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @centralinc/browseragent 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @centralinc/browseragent 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @centralinc/browseragent 可以商用吗？

@centralinc/browseragent 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @centralinc/browseragent 的下载量有多少？

根据 npm 官方下载统计，@centralinc/browseragent 在 2026/10/10 – 2026/11/08 这 30 天内被下载 13,689 次，日均约 456 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @centralinc/browseragent 还在维护吗？

最新版本 1\.9\.6 发布于 2026/01/08（10 个月前）；至今共发布 20 个版本，其中过去 12 个月发布了 8 个；首次发布于 2025/08/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。