browser-opt 1.0.2 → 1.0.5

package/dist/browser-core/agent.d.ts

@@ -0,0 +1,131 @@
+import { AgentOptions } from './types.js';
+export interface AgentBrowserJsonResult {
+    raw: string;
+    data: unknown | null;
+    parseError?: string;
+}
+export interface BrowserTabInfo {
+    /** 当前标签页是否处于激活状态。 */
+    active: boolean;
+    /** agent-browser 返回的稳定标签页标识，可用于后续切换。 */
+    tabId: string;
+    /** 浏览器标签页标题。 */
+    title: string;
+    /** 浏览器标签页类型，例如 `page`。 */
+    type: string;
+    /** 当前标签页地址。 */
+    url: string;
+}
+/**
+ * `agent-browser` CLI 的封装层。
+ *
+ * 每个实例都维护一个由 `sessionId` 标识的独立浏览器会话，并通过 `spawnSync`
+ * 同步执行命令，让上层无需自行处理额外的子进程异步编排。
+ */
+export declare class BrowserAgent {
+    private static autoOpenedDashboardUrls;
+    private readonly sessionId;
+    private readonly namespace;
+    private readonly sessionName;
+    private readonly timeout;
+    private readonly headed;
+    private readonly forceHeadless;
+    private readonly openLiveDashboard;
+    private readonly profile;
+    private readonly executablePath;
+    private readonly statePath;
+    private readonly reuseRunningBrowser;
+    private readonly browserArgs;
+    private liveViewportReady;
+    private browserOpened;
+    constructor(options?: AgentOptions);
+    /** 返回当前 agent 使用的 agent-browser 会话 id。 */
+    getSessionId(): string;
+    getLiveViewportUrl(): string | null;
+    /** 统一拼接 agent-browser 的全局参数，保证不同命令共享同一套会话与启动策略。 */
+    private buildGlobalArgs;
+    private resultErrorMessage;
+    /** 固定 agent-browser 使用系统标准 Chrome，防止已下载的测试浏览器被优先选中。 */
+    private createCommandEnvironment;
+    /** 底层命令执行入口，负责调用单条 agent-browser 命令并返回 stdout。 */
+    private run;
+    private runBestEffort;
+    private runSystemBestEffort;
+    private autoOpenDashboard;
+    private ensureLiveViewport;
+    detectHandoffChallenge(extraText?: string): {
+        detected: boolean;
+        categories: string[];
+        evidence: string[];
+    };
+    /** 打开指定 URL。 */
+    open(url: string): string;
+    /** 通过当前浏览器的 CDP 连接，在活动页面所在 Chrome 窗口中打开原生 DevTools。 */
+    inspect(): Promise<string>;
+    /** 等待 CDP WebSocket 建立连接，并在 agent 超时时间内给出明确失败。 */
+    private waitForWebSocketOpen;
+    /** 发送单条 CDP 指令并校验协议响应，避免实验性能力失败时仍报告成功。 */
+    private sendCdpCommand;
+    /** 刷新当前页面，用于处理 SPA 首次进入后卡在半初始化状态的场景。 */
+    reload(): string;
+    /** 通过 ref 点击元素，例如 snapshot 结果中的 e5。 */
+    click(ref: string): string;
+    /** 通过 ref 填充输入框，例如 snapshot 结果中的 e10。 */
+    fill(ref: string, value: string): string;
+    /** 通过 ref 或选择器把本地文件上传到文件选择控件。 */
+    upload(refOrSelector: string, filePaths: string[]): string;
+    /** 等待 URL 命中某个模式，例如 `/Home`。 */
+    waitForUrl(pattern: string): string;
+    /** 等待页面出现指定文本。 */
+    waitForText(text: string): string;
+    /** 按毫秒固定等待一段时间。 */
+    waitMs(ms: number): string;
+    /** 滚动页面，让当前可交互快照覆盖更大范围的长表单。 */
+    scroll(direction: 'up' | 'down' | 'left' | 'right', amount?: number): string;
+    /**
+     * 通过 `agent-browser chat` 执行自然语言指令。
+     * CLI 会解释这段指令，并完成对应的浏览器动作。
+     */
+    chat(instruction: string): string;
+    /** 在 agent-browser 支持时，以 JSON 输出执行自然语言指令。 */
+    chatJson(instruction: string): AgentBrowserJsonResult;
+    /** 获取只包含可交互元素的无障碍树快照，便于做断言。 */
+    snapshot(): string;
+    /** 获取机器可读的可交互无障碍树快照。 */
+    snapshotJson(): AgentBrowserJsonResult;
+    /** 保存当前会话的 cookies 与 storage，用于后续以干净窗口复用登录态。 */
+    stateSave(path: string): string;
+    /** 加载已保存的 cookies 与 storage，用于干净窗口复用登录态。 */
+    stateLoad(path: string): string;
+    /** 截图。 */
+    screenshot(path?: string): string;
+    /** 在页面上下文中执行 JavaScript，用于读取快照无法可靠表达的控件状态。 */
+    evaluate(script: string): string;
+    /** 获取当前页面标题。 */
+    getTitle(): string;
+    /** 获取当前页面 URL。 */
+    getUrl(): string;
+    /** 获取当前浏览器窗口中的页面标签页，供上层从意外的空白活动页恢复。 */
+    getTabs(): BrowserTabInfo[];
+    /** 切换到指定稳定标签页 id。 */
+    switchTab(tabId: string): string;
+    /**
+     * 在一次进程调用中串行执行多条命令，减少多次启动命令的开销。
+     * `commands` 中的每一项都是参数数组，例如 `['open', 'https://example.com']`。
+     */
+    batch(commands: string[][]): string;
+    /** 记录项目级人工接管状态；暂停与恢复由上层控制，不向 agent-browser 发送伪命令。 */
+    handoff(message: string): string;
+    /** 标记项目级人工接管结束；后续自动化直接复用当前浏览器 session。 */
+    resume(): string;
+    /** 关闭浏览器会话；这里吞掉异常，保证清理阶段尽量顺利完成。 */
+    close(): void;
+}
+/**
+ * 创建 {@link BrowserAgent} 的工厂函数。
+ * 这里作为首选入口，方便测试时替换实现，而不需要直接 mock ES module 类构造函数。
+ */
+export declare function createBrowserAgent(options?: AgentOptions): BrowserAgent;
+/** agent 工厂的类型别名，便于调用方约束注入的工厂签名。 */
+export type BrowserAgentFactory = typeof createBrowserAgent;
+//# sourceMappingURL=agent.d.ts.map

package/dist/browser-core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../browser-core/src/agent.ts"],"names":[],"mappings":"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"}

package/dist/browser-core/agent.js

@@ -0,0 +1,437 @@
+/**
+ * 封装 agent-browser CLI，提供两个对外产物共享的浏览器 session、截图和 handoff 能力。
+ */
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { resolveSystemChromeExecutable } from './browser-executable.js';
+import { createAgentBrowserEnvironment } from './proxy-env.js';
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_DASHBOARD_PORT = 4848;
+const DEFAULT_STREAM_PORT = 9223;
+const DEFAULT_CLEAN_BROWSER_ARGS = [
+    '--disable-session-crashed-bubble',
+    '--no-first-run',
+    '--no-default-browser-check',
+];
+const AGENT_BROWSER_INSTALL_HINT = '请先安装 agent-browser，例如：npm install -g agent-browser。';
+function parseJsonOutput(raw) {
+    try {
+        return {
+            raw,
+            data: JSON.parse(raw),
+        };
+    }
+    catch (err) {
+        return {
+            raw,
+            data: null,
+            parseError: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * `agent-browser` CLI 的封装层。
+ *
+ * 每个实例都维护一个由 `sessionId` 标识的独立浏览器会话，并通过 `spawnSync`
+ * 同步执行命令，让上层无需自行处理额外的子进程异步编排。
+ */
+export class BrowserAgent {
+    static autoOpenedDashboardUrls = new Set();
+    sessionId;
+    namespace;
+    sessionName;
+    timeout;
+    headed;
+    forceHeadless;
+    openLiveDashboard;
+    profile;
+    executablePath;
+    statePath;
+    reuseRunningBrowser;
+    browserArgs;
+    liveViewportReady;
+    browserOpened;
+    constructor(options = {}) {
+        this.sessionId = options.sessionId ?? `browser-agent-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        this.namespace = options.namespace ?? null;
+        this.sessionName = options.sessionName ?? null;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.headed = options.headed ?? options.liveViewport ?? false;
+        this.forceHeadless = options.headless ?? false;
+        this.openLiveDashboard = options.openLiveDashboard ?? true;
+        this.profile = options.profile ?? null;
+        this.executablePath = options.executablePath ?? resolveSystemChromeExecutable() ?? null;
+        this.statePath = options.statePath ?? null;
+        this.reuseRunningBrowser = options.reuseRunningBrowser ?? false;
+        this.browserArgs =
+            options.browserArgs ??
+                (!this.profile && (!this.reuseRunningBrowser || this.statePath) ? DEFAULT_CLEAN_BROWSER_ARGS : []);
+        this.liveViewportReady = false;
+        this.browserOpened = false;
+    }
+    /** 返回当前 agent 使用的 agent-browser 会话 id。 */
+    getSessionId() {
+        return this.sessionId;
+    }
+    getLiveViewportUrl() {
+        return this.headed ? `http://localhost:${DEFAULT_DASHBOARD_PORT}` : null;
+    }
+    /** 统一拼接 agent-browser 的全局参数，保证不同命令共享同一套会话与启动策略。 */
+    buildGlobalArgs(args, useHeaded, options = {}) {
+        const profile = Object.hasOwn(options, 'profile') ? options.profile ?? null : this.profile;
+        const statePath = Object.hasOwn(options, 'statePath') ? options.statePath ?? null : this.statePath;
+        const reuseRunningBrowser = options.reuseRunningBrowser ?? (this.reuseRunningBrowser && !profile && !statePath);
+        const browserArgs = options.browserArgs ?? this.browserArgs;
+        const isBrowserLaunch = args[0] === 'open' && !this.browserOpened;
+        const hasBrowserLaunch = args[0] === 'open' || this.browserOpened;
+        const useNamedSession = !profile;
+        return [
+            // profile 模式不使用 session id，后续命令必须持续携带 profile 才能命中同一浏览器会话。
+            ...(profile ? ['--profile', profile] : []),
+            ...(this.sessionName ? ['--session-name', this.sessionName] : []),
+            ...(statePath && isBrowserLaunch ? ['--state', statePath] : []),
+            ...(reuseRunningBrowser ? ['--auto-connect'] : []),
+            ...(useNamedSession ? ['--session', this.sessionId] : []),
+            ...(useHeaded ? ['--headed'] : this.forceHeadless ? ['--headed', 'false'] : []),
+            ...(hasBrowserLaunch && browserArgs.length > 0
+                ? ['--args', browserArgs.join(',')]
+                : []),
+            ...args,
+        ];
+    }
+    resultErrorMessage(result, fallback) {
+        const stderr = result.stderr?.trim() || '';
+        const stdout = result.stdout?.trim() || '';
+        return stderr || stdout || fallback;
+    }
+    /** 固定 agent-browser 使用系统标准 Chrome，防止已下载的测试浏览器被优先选中。 */
+    createCommandEnvironment() {
+        return {
+            ...createAgentBrowserEnvironment(),
+            ...(this.namespace ? { AGENT_BROWSER_NAMESPACE: this.namespace } : {}),
+            ...(this.executablePath ? { AGENT_BROWSER_EXECUTABLE_PATH: this.executablePath } : {}),
+        };
+    }
+    /** 底层命令执行入口，负责调用单条 agent-browser 命令并返回 stdout。 */
+    run(args, options = {}) {
+        const useHeaded = options.headed ?? this.headed;
+        const result = spawnSync('agent-browser', this.buildGlobalArgs(args, useHeaded, Object.hasOwn(options, 'statePath') ? { statePath: options.statePath } : {}), { encoding: 'utf-8', timeout: this.timeout, env: this.createCommandEnvironment() });
+        if (result.error) {
+            throw new Error(`无法启动 agent-browser：${result.error.message}。${AGENT_BROWSER_INSTALL_HINT}`);
+        }
+        if (result.status !== 0) {
+            throw new Error(this.resultErrorMessage(result, `agent-browser exited with code ${result.status}`));
+        }
+        if (args[0] === 'open') {
+            this.browserOpened = true;
+        }
+        else if (args[0] === 'close') {
+            this.browserOpened = false;
+        }
+        if (useHeaded && this.openLiveDashboard && args[0] === 'open') {
+            this.ensureLiveViewport();
+        }
+        return result.stdout ?? '';
+    }
+    runBestEffort(args) {
+        return spawnSync('agent-browser', args, {
+            encoding: 'utf-8',
+            timeout: this.timeout,
+            env: this.createCommandEnvironment(),
+        });
+    }
+    runSystemBestEffort(command, args) {
+        return spawnSync(command, args, {
+            encoding: 'utf-8',
+            timeout: this.timeout,
+        });
+    }
+    autoOpenDashboard(url) {
+        if (BrowserAgent.autoOpenedDashboardUrls.has(url)) {
+            return;
+        }
+        BrowserAgent.autoOpenedDashboardUrls.add(url);
+        if (process.platform === 'darwin') {
+            this.runSystemBestEffort('open', [url]);
+            return;
+        }
+        if (process.platform === 'win32') {
+            this.runSystemBestEffort('cmd', ['/c', 'start', '', url]);
+            return;
+        }
+        this.runSystemBestEffort('xdg-open', [url]);
+    }
+    ensureLiveViewport() {
+        if (this.liveViewportReady) {
+            return;
+        }
+        this.runBestEffort(['dashboard', 'start', '--port', String(DEFAULT_DASHBOARD_PORT)]);
+        const statusResult = this.runBestEffort(['--session', this.sessionId, 'stream', 'status']);
+        const statusText = `${statusResult?.stdout ?? ''}\n${statusResult?.stderr ?? ''}`;
+        if (!statusText.includes(`:${DEFAULT_STREAM_PORT}`)) {
+            if (/Streaming enabled/i.test(statusText)) {
+                this.runBestEffort(['--session', this.sessionId, 'stream', 'disable']);
+            }
+            this.runBestEffort(['--session', this.sessionId, 'stream', 'enable', '--port', String(DEFAULT_STREAM_PORT)]);
+        }
+        const dashboardUrl = this.getLiveViewportUrl();
+        if (dashboardUrl) {
+            this.autoOpenDashboard(dashboardUrl);
+        }
+        this.liveViewportReady = true;
+    }
+    detectHandoffChallenge(extraText) {
+        const evidence = [];
+        const categories = [];
+        let snapshotText = '';
+        let urlText = '';
+        try {
+            snapshotText = this.snapshot().toLowerCase();
+        }
+        catch {
+            // 这里只做尽力探测，不影响主流程。
+        }
+        try {
+            urlText = this.getUrl().toLowerCase();
+        }
+        catch {
+            // 这里只做尽力探测，不影响主流程。
+        }
+        const combined = `${snapshotText}\n${urlText}\n${extraText ?? ''}`.toLowerCase();
+        const patterns = [
+            { category: 'CAPTCHA', regex: /(recaptcha|g-recaptcha|hcaptcha|h-captcha|turnstile|cloudflare\s*challenge|verify\s*you\s*are\s*human|机器人验证|验证码)/i, hint: 'captcha/bot verification markers' },
+            { category: 'OAuth', regex: /(oauth|authorize\b|consent\b|continue\s+with|sign\s+in\s+with|登录授权|第三方登录)/i, hint: 'oauth or third-party authorization markers' },
+            { category: 'MFA', regex: /(two[ -]?factor|2fa|mfa|authenticator|one[ -]?time\s*password|otp|sms\s*code|verification\s*code|动态码|短信验证码)/i, hint: 'multi-factor verification markers' },
+        ];
+        for (const pattern of patterns) {
+            if (pattern.regex.test(combined)) {
+                categories.push(pattern.category);
+                evidence.push(pattern.hint);
+            }
+        }
+        return {
+            detected: categories.length > 0,
+            categories,
+            evidence,
+        };
+    }
+    /** 打开指定 URL。 */
+    open(url) {
+        return this.run(['open', url]);
+    }
+    /** 通过当前浏览器的 CDP 连接，在活动页面所在 Chrome 窗口中打开原生 DevTools。 */
+    async inspect() {
+        const currentUrl = this.getUrl();
+        const cdpUrl = this.run(['get', 'cdp-url']).trim();
+        const socket = new WebSocket(cdpUrl);
+        try {
+            await this.waitForWebSocketOpen(socket);
+            const targetList = await this.sendCdpCommand(socket, 1, 'Target.getTargets');
+            const target = targetList.targetInfos.find((candidate) => (candidate.type === 'page' && candidate.url === currentUrl));
+            if (!target) {
+                throw new Error(`无法在 CDP target 列表中定位当前页面：${currentUrl}`);
+            }
+            const opened = await this.sendCdpCommand(socket, 2, 'Target.openDevTools', {
+                targetId: target.targetId,
+            });
+            return `Chrome 原生 DevTools 已打开：${opened.targetId}`;
+        }
+        finally {
+            socket.close();
+        }
+    }
+    /** 等待 CDP WebSocket 建立连接，并在 agent 超时时间内给出明确失败。 */
+    waitForWebSocketOpen(socket) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error('连接 Chrome DevTools Protocol 超时')), this.timeout);
+            socket.addEventListener('open', () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+            socket.addEventListener('error', () => {
+                clearTimeout(timer);
+                reject(new Error('无法连接 Chrome DevTools Protocol'));
+            }, { once: true });
+        });
+    }
+    /** 发送单条 CDP 指令并校验协议响应，避免实验性能力失败时仍报告成功。 */
+    sendCdpCommand(socket, id, method, params) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`CDP 指令超时：${method}`)), this.timeout);
+            const handleMessage = (event) => {
+                const response = JSON.parse(String(event.data));
+                if (response.id !== id) {
+                    return;
+                }
+                clearTimeout(timer);
+                socket.removeEventListener('message', handleMessage);
+                if (response.error) {
+                    reject(new Error(`CDP ${method} 失败：${response.error.message}`));
+                    return;
+                }
+                if (!response.result) {
+                    reject(new Error(`CDP ${method} 未返回结果`));
+                    return;
+                }
+                resolve(response.result);
+            };
+            socket.addEventListener('message', handleMessage);
+            socket.send(JSON.stringify({ id, method, ...(params ? { params } : {}) }));
+        });
+    }
+    /** 刷新当前页面，用于处理 SPA 首次进入后卡在半初始化状态的场景。 */
+    reload() {
+        return this.evaluate('window.location.reload()');
+    }
+    /** 通过 ref 点击元素，例如 snapshot 结果中的 e5。 */
+    click(ref) {
+        return this.run(['click', `@${ref.replace(/^@/, '')}`]);
+    }
+    /** 通过 ref 填充输入框，例如 snapshot 结果中的 e10。 */
+    fill(ref, value) {
+        return this.run(['fill', `@${ref.replace(/^@/, '')}`, value]);
+    }
+    /** 通过 ref 或选择器把本地文件上传到文件选择控件。 */
+    upload(refOrSelector, filePaths) {
+        const target = /^@/.test(refOrSelector)
+            ? refOrSelector
+            : /^[a-z]\d+$/i.test(refOrSelector)
+                ? `@${refOrSelector}`
+                : refOrSelector;
+        return this.run(['upload', target, ...filePaths]);
+    }
+    /** 等待 URL 命中某个模式，例如 `/Home`。 */
+    waitForUrl(pattern) {
+        return this.run(['wait', '--url', pattern]);
+    }
+    /** 等待页面出现指定文本。 */
+    waitForText(text) {
+        return this.run(['wait', '--text', text]);
+    }
+    /** 按毫秒固定等待一段时间。 */
+    waitMs(ms) {
+        return this.run(['wait', String(ms)]);
+    }
+    /** 滚动页面，让当前可交互快照覆盖更大范围的长表单。 */
+    scroll(direction, amount = 600) {
+        return this.run(['scroll', direction, String(amount)]);
+    }
+    /**
+     * 通过 `agent-browser chat` 执行自然语言指令。
+     * CLI 会解释这段指令，并完成对应的浏览器动作。
+     */
+    chat(instruction) {
+        return this.run(['chat', instruction]);
+    }
+    /** 在 agent-browser 支持时，以 JSON 输出执行自然语言指令。 */
+    chatJson(instruction) {
+        return parseJsonOutput(this.run(['chat', instruction, '--json']));
+    }
+    /** 获取只包含可交互元素的无障碍树快照，便于做断言。 */
+    snapshot() {
+        return this.run(['snapshot', '-i']);
+    }
+    /** 获取机器可读的可交互无障碍树快照。 */
+    snapshotJson() {
+        return parseJsonOutput(this.run(['snapshot', '-i', '--json']));
+    }
+    /** 保存当前会话的 cookies 与 storage，用于后续以干净窗口复用登录态。 */
+    stateSave(path) {
+        return this.run(['state', 'save', path], { statePath: null });
+    }
+    /** 加载已保存的 cookies 与 storage，用于干净窗口复用登录态。 */
+    stateLoad(path) {
+        return this.run(['state', 'load', path], { statePath: null });
+    }
+    /** 截图。 */
+    screenshot(path) {
+        return this.run(path ? ['screenshot', path] : ['screenshot']);
+    }
+    /** 在页面上下文中执行 JavaScript，用于读取快照无法可靠表达的控件状态。 */
+    evaluate(script) {
+        return this.run(['eval', script]);
+    }
+    /** 获取当前页面标题。 */
+    getTitle() {
+        return this.run(['get', 'title']).trim();
+    }
+    /** 获取当前页面 URL。 */
+    getUrl() {
+        return this.run(['get', 'url']).trim();
+    }
+    /** 获取当前浏览器窗口中的页面标签页，供上层从意外的空白活动页恢复。 */
+    getTabs() {
+        const output = parseJsonOutput(this.run(['tab', 'list', '--json']));
+        if (!output.data || typeof output.data !== 'object') {
+            return [];
+        }
+        const data = output.data;
+        if (!Array.isArray(data.data?.tabs)) {
+            return [];
+        }
+        return data.data.tabs.filter((tab) => {
+            if (!tab || typeof tab !== 'object') {
+                return false;
+            }
+            const candidate = tab;
+            return typeof candidate.tabId === 'string'
+                && typeof candidate.url === 'string'
+                && typeof candidate.title === 'string'
+                && typeof candidate.type === 'string'
+                && typeof candidate.active === 'boolean';
+        });
+    }
+    /** 切换到指定稳定标签页 id。 */
+    switchTab(tabId) {
+        return this.run(['tab', tabId]);
+    }
+    /**
+     * 在一次进程调用中串行执行多条命令，减少多次启动命令的开销。
+     * `commands` 中的每一项都是参数数组，例如 `['open', 'https://example.com']`。
+     */
+    batch(commands) {
+        const result = spawnSync('agent-browser', this.buildGlobalArgs(['batch', '--json'], this.headed), {
+            input: JSON.stringify(commands),
+            encoding: 'utf-8',
+            timeout: this.timeout * commands.length,
+            env: this.createCommandEnvironment(),
+        });
+        if (result.error) {
+            throw new Error(`无法启动 agent-browser：${result.error.message}。${AGENT_BROWSER_INSTALL_HINT}`);
+        }
+        if (result.status !== 0) {
+            const stderr = result.stderr?.trim() || '';
+            throw new Error(stderr || `agent-browser batch exited with code ${result.status}`);
+        }
+        return result.stdout ?? '';
+    }
+    /** 记录项目级人工接管状态；暂停与恢复由上层控制，不向 agent-browser 发送伪命令。 */
+    handoff(message) {
+        return [
+            'HANDOFF: reusing the current browser session for manual interaction.',
+            `Session: ${this.sessionId}`,
+            `Reason: ${message}`,
+        ].join('\n');
+    }
+    /** 标记项目级人工接管结束；后续自动化直接复用当前浏览器 session。 */
+    resume() {
+        return `RESUME: continuing browser session ${this.sessionId}.`;
+    }
+    /** 关闭浏览器会话；这里吞掉异常，保证清理阶段尽量顺利完成。 */
+    close() {
+        try {
+            this.run(['close']);
+        }
+        catch {
+            // 清理阶段忽略关闭失败，常见原因是会话已经提前结束。
+        }
+    }
+}
+/**
+ * 创建 {@link BrowserAgent} 的工厂函数。
+ * 这里作为首选入口，方便测试时替换实现，而不需要直接 mock ES module 类构造函数。
+ */
+export function createBrowserAgent(options) {
+    return new BrowserAgent(options);
+}
+//# sourceMappingURL=agent.js.map

package/dist/browser-core/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../browser-core/src/agent.ts"],"names":[],"mappings":"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"}

package/dist/browser-core/browser-executable.d.ts

@@ -0,0 +1,3 @@
+/** 优先采用显式配置，否则按操作系统约定查找标准 Chrome。 */
+export declare function resolveSystemChromeExecutable(configuredPath?: string | undefined): string | undefined;
+//# sourceMappingURL=browser-executable.d.ts.map

package/dist/browser-core/browser-executable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-executable.d.ts","sourceRoot":"","sources":["../../../browser-core/src/browser-executable.ts"],"names":[],"mappings":"AAOA,qCAAqC;AACrC,wBAAgB,6BAA6B,CAAC,cAAc,qBAA4C,GAAG,MAAM,GAAG,SAAS,CAY5H"}

package/dist/browser-core/browser-executable.js

@@ -0,0 +1,49 @@
+/**
+ * 解析本机标准 Chrome 的可执行文件，供运行时和环境安装检查共用。
+ * 这里刻意不回退到 Playwright 下载的 Chrome for Testing，避免浏览器身份和用户登录态发生漂移。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** 优先采用显式配置，否则按操作系统约定查找标准 Chrome。 */
+export function resolveSystemChromeExecutable(configuredPath = process.env.AGENT_BROWSER_EXECUTABLE_PATH) {
+    const explicitPath = configuredPath?.trim();
+    if (explicitPath) {
+        return isExecutableFile(explicitPath) ? path.resolve(explicitPath) : undefined;
+    }
+    for (const candidate of systemChromeCandidates()) {
+        if (isExecutableFile(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/** 返回各平台标准 Chrome 的候选路径，不包含测试浏览器和 Playwright 缓存。 */
+function systemChromeCandidates() {
+    if (process.platform === 'darwin') {
+        return [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        ];
+    }
+    if (process.platform === 'win32') {
+        return [
+            process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe') : '',
+            'C:/Program Files/Google/Chrome/Application/chrome.exe',
+            'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+        ].filter(Boolean);
+    }
+    const executableNames = ['google-chrome', 'google-chrome-stable'];
+    return (process.env.PATH ?? '')
+        .split(path.delimiter)
+        .flatMap((directory) => executableNames.map((name) => path.join(directory, name)));
+}
+function isExecutableFile(filePath) {
+    try {
+        fs.accessSync(filePath, fs.constants.X_OK);
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=browser-executable.js.map