@cogitator-ai/浏览器

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

特征

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

安装

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

playwright 是软件包的依赖性; 浏览器二进制与 playwright install。网站文件: 浏览器, (中文(简体) ), 会议, (中文(简体) ), 工具, (中文(简体) ), 隐形, (中文(简体) ), 愿景, (中文(简体) ), 网络。 。 。 .

快速启动

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个工具)

互动(9个工具)

采掘(7个工具)

愿景(4个工具)

网络(6个工具)

隐形模式

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

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选择器与页面交互:

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 尝试多种策略:角色按钮,角色链接,文本内容,标签,和占位符.

网络控制

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

构造器

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

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> 所以经纪人才知道为什么.

生命周期

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重新发起。 一个失败的开始会关闭它所发射的任何东西.

属性

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

标签管理

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 管理器

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');

模块选择

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

// 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,所以一个已解结构的工具保留了自己的参数类型:

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

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

辅助工具

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

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);

隐形独立函数

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

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' });

许可证

麻省理工学院