# @cogitator-ai/browser 中文文档

规范地址：https://npmcn.com/package/%40cogitator-ai/browser/

版本：0\.4\.66
npm 元数据更新时间：2026-10-29T00:49:43.555Z
中文译文更新时间：2026-11-10T10:15:37.344Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cogitator-ai/browser
原文对照：https://npmcn.com/package/%40cogitator-ai/browser/?lang=original
源码仓库：https://github.com/cogitator-ai/Cogitator-AI

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

- 包体积（解压后）：258 kB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：4 个
- 首次发布：2026-03-03T15:41:48.012Z
- 最新版本发布：2026-10-29T00:49:43.383Z
- 近 30 天下载量：9459（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

Cogitator AI 代理器的浏览器自动化工具

## 安装

```sh
npm install @cogitator-ai/browser
```

也可以使用：`pnpm add @cogitator-ai/browser`、`yarn add @cogitator-ai/browser`、`bun add @cogitator-ai/browser`

## README

# @cogitator-ai/浏览器

Cogitator AI代理的浏览器自动化工具. 基于Playwright的有33个工具,跨越了5个模块,视觉模式,隐形系统,结构化的数据提取,以及网络控制.

## 特征

-   **33 浏览器工具** 跨越5个模块(导航、互动、提取、愿景、网络)
-   **浏览器会议** -- 有标签( 包括弹出) 、 饼干、 代理、 持久性配置文件以及标签限制的浏览器生命周期管理
-   **隐形模式** - 偷取指纹、类似人的打字/打mouse、无人机旋转
-   **愿景模式** -- 截图 + 视觉LLM 导航无障碍树
-   **智能提取** -- 表格、结构数据、链接、干净文本
-   **网络控制** - 请求拦截、HAR捕获、资源封锁、API监测
-   **游戏机驱动** - Chromium、Firefox、WebKit支持

## 安装

```bash
pnpm add @cogitator-ai/browser playwright
npx playwright install chromium   # or firefox / webkit
```

`playwright` 是软件包的依赖性; 浏览器二进制与 `playwright install`。网站文件: [浏览器](https://cogitator.app/docs/browser), (中文(简体) ), [会议](https://cogitator.app/docs/browser/session), (中文(简体) ), [工具](https://cogitator.app/docs/browser/tools), (中文(简体) ), [隐形](https://cogitator.app/docs/browser/stealth), (中文(简体) ), [愿景](https://cogitator.app/docs/browser/vision), (中文(简体) ), [网络](https://cogitator.app/docs/browser/network)。 。 。 .

## 快速启动

```typescript
import { BrowserSession, browserTools } from '@cogitator-ai/browser';
import { Agent, Cogitator } from '@cogitator-ai/core';

const session = new BrowserSession({ headless: true });
await session.start();

const agent = new Agent({
  name: 'web-researcher',
  model: 'openai/gpt-6.1-sol',
  instructions: 'You browse the web and extract information.',
  tools: browserTools(session),
});

const cog = new Cogitator({
  llm: { providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } } },
});
const result = await cog.run(agent, {
  input: 'Go to https://news.ycombinator.com and get the top 5 story titles',
});

console.log(result.output);
await session.close();
```

## 工具模块

### 导航(7个工具)

| 工具 | 说明 |
| --- | --- |
| `browser_navigate` | 导航到 URL。 返回最后的 URL、 标题和 HTTP 状态 |
| `browser_go_back` | 返回浏览器历史 |
| `browser_go_forward` | 在浏览器历史中前进 |
| `browser_reload` | 重新装入当前页面 |
| `browser_wait_for_navigation` | 等待导航到匹配图案的 URL |
| `browser_get_current_url` | 获取当前页面 URL 和标题 |
| `browser_wait_for_selector` | 在页面上等待 CSS 选择器 |

### 互动(9个工具)

| 工具 | 说明 |
| --- | --- |
| `browser_click` | 通过 CSS 选择器单击一个元素 。 支持按钮、 单击“ 选择” 、 位置 |
| `browser_type` | 将文本输入输入。 隐形模式用类似人类的密钥替换值 |
| `browser_select_option` | 从 a 中选择 `<select>` 按数值、标签或索引分列的元素 |
| `browser_hover` | 绕过元素 |
| `browser_scroll` | 向任何方向滚动页面或特定元素 |
| `browser_press_key` | 按带有可选修改键的键盘键 |
| `browser_drag_and_drop` | 将元素拖入另一个元素 |
| `browser_fill_form` | 智能表单填充器 - 按名称、占位符、 aria- 标签或标签文本查找输入 |
| `browser_upload_file` | 上传文件到文件输入元素 |

### 采掘(7个工具)

| 工具 | 说明 |
| --- | --- |
| `browser_get_text` | 从页面或第一个匹配元素中提取文本 |
| `browser_get_html` | 获取页面或元素的内部或外部 HTML |
| `browser_get_attribute` | 获取 DOM 属性的值 |
| `browser_get_links` | 提取与文本、href和标题的所有链接 |
| `browser_query_selector_all` | 查询所有匹配元素的标签、文本、属性、能见度 |
| `browser_extract_table` | 从表格中取出标题+行( 或其中的第一个表格) |
| `browser_extract_structured` | 提取已解析的文本, 无脚本/ 样式/ 隐藏元素 |

### 愿景(4个工具)

| 工具 | 说明 |
| --- | --- |
| `browser_screenshot` | 屏幕截取页面或元素 。 回归基数64 PNG/JPEG `mimeType` 层面 |
| `browser_screenshot_element` | 屏幕拍摄带有边框坐标的特定元素 |
| `browser_find_by_description` | 使用无障碍树用自然语言查找元素 |
| `browser_click_by_description` | 按自然语言描述单击一个元素( tries 角色、文本、标签、占位符) |

### 网络(6个工具)

| 工具 | 说明 |
| --- | --- |
| `browser_intercept_request` | 块、 修改或继续请求与 glob 或 `/regex/flags` 在所有标签中 |
| `browser_remove_interceptor` | 以 ID 或全部删除一个拦截器 |
| `browser_wait_for_response` | 等待 URL 包含子字符串或匹配的响应 `/regex/flags` |
| `browser_block_resources` | 在所有标签中块资源类型(图像、样式表、字体、媒体、脚本) |
| `browser_capture_har` | 开始/ 停止所有标签的流量捕捉; 在停止返回条目时可以写入 HAR 1.2 |
| `browser_get_api_calls` | 自会话开始以来,通过URL或方法过滤的XHR/fatch呼叫记录; `clear` 删除返回的呼叫 |

## 隐形模式

隐形模式使得浏览器更难被检测为自动化. 它在上下文创作上应用了逃避脚本,并可以进行人相类的输入模拟.

```typescript
const session = new BrowserSession({
  stealth: true, // enable all defaults
});

// or configure individually
const session = new BrowserSession({
  stealth: {
    humanLikeTyping: true, // random delays between keystrokes (50-150ms)
    humanLikeMouse: true, // bezier curve mouse movement
    fingerprintRandomization: true, // canvas/WebGL/plugin spoofing
    blockWebDriver: true, // navigator.webdriver = false
    evasionScripts: [], // custom init scripts to inject
  },
});
```

您省略的选项返回到上面的默认值( 所有) `true`),这样 `stealth: { humanLikeMouse: false }` 保留其他特性.

隐形模式会做什么 :

-   设定 `navigator.webdriver` 改为 `false` (签名) `Navigator.prototype`,而不是作为自己的财产)
-   鼠标 `navigator.plugins` 带有现实的 Chrome 插件
-   设定 `navigator.languages` 从 `locale` (例如:. `de-DE` - > (中文) `['de-DE', 'de']`默认值 `['en-US', 'en']`(中文(简体) )
-   对齐 `navigator.platform` 财务报告和审定财务报表 `navigator.userAgentData.platform` 使用中的用户代理
-   随机化画布指纹 (1- 位像素噪声)
-   Spoofs WebGL 供应商/供应商(英特尔·伊里斯)
-   喷出 `window.chrome` 运行时间根
-   覆盖 `Permissions.query` 通知通知
-   每个浏览器类型旋转桌面用户代理字符串
-   添加类似人类的打字延迟( 每字符50-150ms)
-   将鼠标沿比齐尔曲线移动 `browser_click`, (中文(简体) ), `browser_click_by_description`, (中文(简体) ), `browser_hover`,在小步中为 `browser_scroll`

## 愿景模式

视觉工具允许代理使用自然语言而不是CSS选择器与页面交互:

```typescript
import { BrowserSession, browserTools } from '@cogitator-ai/browser';

const session = new BrowserSession();
await session.start();

const tools = browserTools(session, { modules: ['navigation', 'vision'] });

// Agent can now use:
// browser_screenshot -- take a screenshot for visual analysis
// browser_find_by_description -- "find the login button"
// browser_click_by_description -- "click the Submit button"
```

`browser_find_by_description` 将无障碍树行走,并按角色和名称与描述相匹配. `browser_click_by_description` 尝试多种策略:角色按钮,角色链接,文本内容,标签,和占位符.

## 网络控制

```typescript
import { BrowserSession, createNavigationTools, createNetworkTools } from '@cogitator-ai/browser';

const session = new BrowserSession();
await session.start();

const tools = [...createNavigationTools(session), ...createNetworkTools(session)];

// Agent can intercept requests (glob or /regex/flags), in every tab:
// browser_intercept_request({ urlPattern: "**/ads/**", action: "block" })
// browser_intercept_request({ urlPattern: "/\\.(png|jpe?g)$/i", action: "block" })
// browser_remove_interceptor({ interceptorId: "interceptor_1" })

// Block resource types to speed up loading:
// browser_block_resources({ types: ["image", "font", "stylesheet"] })

// Monitor API calls made by the page since the session started.
// clear removes only the calls returned here; calls the filters exclude are kept:
// browser_get_api_calls({ urlPattern: "/api/", method: "POST", clear: true })

// Capture traffic and save a HAR 1.2 file (path must be inside the working directory):
// browser_capture_har({ action: "start" })
// ... navigate and interact ...
// browser_capture_har({ action: "stop", path: "./traffic.har" })
```

截取器被注册在浏览器上下文上,因此它们也适用于后期打开的分页. `continue` 财务报告和审定财务报表 `modify` 将请求交给下一个匹配的截取器(`route.fallback`)),因此阻塞规则在多个拦截器重叠时继续工作. `modify.headers` 合并为原请求头。 API调用历史保持了最新的1000个调用;HAR捕捉保存了多达5000个条目并存储了仅用于文本响应到1 MB的机体.

## 浏览器会议API

### 构造器

```typescript
import { BrowserSession } from '@cogitator-ai/browser';
import type { BrowserSessionConfig } from '@cogitator-ai/types';

const config: BrowserSessionConfig = { headless: true }; // every field is optional
const session = new BrowserSession(config);
```

### 浏览器SessionConfig

```typescript
interface BrowserSessionConfig {
  headless?: boolean; // default: true
  browser?: 'chromium' | 'firefox' | 'webkit'; // default: 'chromium'
  stealth?: boolean | StealthConfig; // enable stealth mode
  proxy?: string | ProxyConfig; // proxy server
  viewport?: { width: number; height: number }; // default: 1280x720
  userAgent?: string; // custom UA (stealth rotates automatically)
  locale?: string; // browser locale (e.g., 'en-US')
  timezone?: string; // timezone ID (e.g., 'America/New_York')
  geolocation?: { latitude: number; longitude: number };
  persistentContext?: string; // user data dir; profile (cookies, storage) survives restarts
  cookies?: BrowserCookie[]; // pre-load cookies (domain cookies default to path '/')
  timeout?: number; // navigation timeout, default: 30000ms
  actionTimeout?: number; // action timeout, default: 10000ms
  pool?: { maxPages: number }; // maximum number of open tabs for newTab()
  robots?: RobotsChecker; // block navigations a site's robots.txt disallows
}
```

与 `robots` (例如 `new RobotsPolicy({ userAgent })` 从 `@cogitator-ai/core`),每页导航,打入,点击,重定向或在一个框中,都会被与站点的机器人.txt对照检查并被屏蔽. `browser_navigate` 财务报告和审定财务报表 `newTab(url)` 掷出 `robots.txt does not allow visiting <url>` 所以经纪人才知道为什么.

### 生命周期

```typescript
await session.start(); // launch browser, create context and first page
await session.ensureStarted(); // start once; concurrent callers share one launch
await session.close(); // close browser and cleanup

const unsubscribe = session.onStart((context) => {
  // runs after every successful start (immediately if already started)
});
```

如果浏览器或上下文意外关闭,会话会重新排列自己和下一个 `ensureStarted()` (被来自 `browserTools`重新发起。 一个失败的开始会关闭它所发射的任何东西.

### 属性

```typescript
session.page; // active Playwright Page
session.tabs; // all open Page[] (includes popups and target=_blank pages)
session.activeTabIndex; // index of the active tab
session.started; // whether a context is running
session.browser; // Playwright Browser instance
session.context; // Playwright BrowserContext
session.config; // current config
session.stealthEnabled; // whether stealth is on
session.stealthConfig; // resolved StealthConfig or null
```

### 标签管理

```typescript
const page = await session.newTab('https://example.com'); // open new tab (respects pool.maxPages)
session.switchTab(1); // switch to tab by index
await session.closeTab(0); // close tab by index
```

### Cookie 管理器

```typescript
const cookies = await session.getCookies();
await session.setCookies([{ name: 'token', value: 'abc', domain: '.example.com' }]);
await session.saveCookies('./cookies.json');
await session.loadCookies('./cookies.json');
```

## 模块选择

只装入您需要的工具模块 :

```typescript
// all 33 tools
const tools = browserTools(session);

// only navigation + extraction (14 tools)
const tools = browserTools(session, {
  modules: ['navigation', 'extraction'],
});

// or use individual factory functions
import {
  createNavigationTools,
  createExtractionTools,
  createScreenshotTool,
} from '@cogitator-ai/browser';

const tools = [
  ...createNavigationTools(session),
  ...createExtractionTools(session),
  createScreenshotTool(session),
];
```

可用模块 : `navigation`, (中文(简体) ), `interaction`, (中文(简体) ), `extraction`, (中文(简体) ), `vision`, (中文(简体) ), `network`。 。 。 .

模块工厂`createNavigationTools`, (中文(简体) ), `createInteractionTools`, (中文(简体) ), `createExtractionTools`, (中文(简体) ), `createVisionTools`, (中文(简体) ), `createNetworkTools`)返回打入的tuple,所以一个已解结构的工具保留了自己的参数类型:

```typescript
const [navigate] = createNavigationTools(session);
await navigate.execute({ url: 'https://example.com' }, ctx); // params typed as NavigateInput
```

工具来自 `browserTools()` 调用 `session.ensureStarted()` 在每次呼叫之前, 浏览器会按要求启动( 或重新启动) ; 来自单个工厂的工具会期望一个开始的会话 .

## 辅助工具

用于高级用途的独立助手 :

```typescript
import {
  smartSelect,
  findFormField,
  getReadableText,
  getAccessibilityTree,
  elementToInfo,
} from '@cogitator-ai/browser';

// smartSelect tries CSS, XPath, then text matching
const locator = await smartSelect(page, 'Submit');

// findFormField tries name, placeholder, aria-label, label text
const input = await findFormField(page, 'Email');

// getReadableText returns rendered text (no scripts, styles, or hidden elements)
const text = await getReadableText(page);

// getAccessibilityTree returns simplified a11y tree
const tree = await getAccessibilityTree(page);
```

## 隐形独立函数

在浏览器会议之外直接使用隐形原始:

```typescript
import {
  humanLikeType,
  humanLikeClick,
  humanLikeHover,
  humanLikeScroll,
  getRandomUserAgent,
  getAllUserAgents,
  getEvasionScripts,
  applyStealthToContext,
  getStealthLaunchOptions,
} from '@cogitator-ai/browser';

// human-like input on any Playwright page
await humanLikeType(page, '#search', 'cogitator ai');
await humanLikeClick(page, '.submit-btn'); // selector or Locator
await humanLikeClick(page, page.getByRole('button', { name: 'Buy' }), { clickCount: 2 });
await humanLikeHover(page, '#menu');
await humanLikeScroll(page, 'down', 500); // up | down | left | right

// get a random desktop UA for a browser type
const ua = getRandomUserAgent('chromium');

// evasion scripts consistent with that user agent and locale
const scripts = getEvasionScripts({ userAgent: ua, locale: 'de-DE' });
await applyStealthToContext(context, { blockWebDriver: true }, { userAgent: ua, locale: 'de-DE' });
```

## 许可证

麻省理工学院

## 常见问题

### @cogitator-ai/browser 是什么？

Cogitator AI 代理器的浏览器自动化工具

### 如何安装 @cogitator-ai/browser？

在项目目录运行 npm install @cogitator-ai/browser，或使用 pnpm add / yarn add / bun add。

### @cogitator-ai/browser 支持 TypeScript 吗？

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

### @cogitator-ai/browser 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cogitator-ai/browser 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cogitator-ai/browser 可以商用吗？

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

### @cogitator-ai/browser 的下载量有多少？

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

### @cogitator-ai/browser 还在维护吗？

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