bridgic-browser

依赖项

bridgic-browser 项目需要以下软件包：

软件包	说明
bridgic-browser	浏览器自动化 CLI + Python SDK（安装其中一个即可同时安装两者）

此外，还需安装浏览器二进制文件（只需安装一次）：uv run playwright install chromium。

安装：运行安装脚本以配置所有依赖项：

bash "skills/bridgic-browser/scripts/install-deps.sh" "$PWD"

该脚本会检查 uv 是否可用，在需要时初始化 uv 项目，安装缺少的软件包，并确保 Playwright chromium 可用。

策略与指南（重要！！）

注意：

• 每次调用 bridgic-browser CLI 时，都必须使用 uv run 调用。
• 如果用户明确指定了必须遵循的确切步骤，请尝试按照这些步骤进行探索。如果探索过程中出现循环或分支，请自主决定最佳探索路径。
• 如果你认为点击进入新页面后可能需要返回原始页面，请尝试在新的浏览器标签页中打开新页面，而不要采用“点击后返回”的方式。这在原始页面已有交互状态（例如已填写的表单或已应用的筛选条件）时尤其重要；否则，返回时该状态可能会丢失。完成相关操作后，请及时关闭新标签页。
• 如果探索需要反复点击列表中的项目，无需遍历每一项（尤其是列表很长时）。
• 如果探索过程中需要登录、验证或授权，请暂停并让用户手动完成，除非用户在任务中明确提供了相关指示。
• 为避免过于频繁地访问网站，请在探索和编写代码期间保持符合人类习惯的访问间隔。你可以模拟随机等待时间，以降低被屏蔽的风险。注意：bridgic-browser wait 命令的参数单位是秒，不是毫秒；例如：bridgic-browser wait 2 或 bridgic-browser wait 3.2。
• 完成探索和代码编写后，自动运行测试/验证。
• CDP 模式下的标签页可见性：通过 --cdp 连接到用户正在运行的 Chrome 时，tabs / switch-tab / close-tab 只能看到 bridgic 自行打开的页面（初始空白标签页，以及通过 new-tab 或点击 target="_blank" 链接从该标签页打开的页面）。bridgic 无法看到用户的其他标签页，这是刻意设计的——切勿假设可以通过 switch-tab 切换到这些标签页。要操作这类标签页，请让用户通过 bridgic 导航到该标签页，或使用 new-tab <url>。

参考文件

参考文件涵盖所有用例。只加载与任务相关的文件：

场景	接口	加载
直接从终端控制浏览器	CLI	cli-guide.md
编写浏览器自动化 Python 代码	Python	sdk-guide.md
编写浏览器自动化 shell 脚本	CLI	cli-guide.md
通过 CLI 探索，然后生成 Python 代码	CLI → Python	cli-sdk-api-mapping.md + sdk-guide.md
迁移 / 比较 / 解释 CLI ↔ SDK	两者	cli-sdk-api-mapping.md
配置环境变量或登录状态持久化	两者皆可	env-vars.md
连接到现有的 Chrome（chrome://inspect、--remote-debugging-port、云浏览器、Electron）	CLI / SDK	cdp-mode.md

接口选择规则

1. 请求输出 shell 命令或脚本 → 优先使用 CLI 指南（references/cli-guide.md）。
2. 请求输出可运行的 Python 代码（async、Browser、工具构建器） → 优先使用 SDK 指南（references/sdk-guide.md）。
3. 输入是 CLI 输出或操作，但输出需要是 Python 代码 → 优先使用映射指南（references/cli-sdk-api-mapping.md），然后使用 SDK 指南生成最终代码（references/sdk-guide.md）。
4. 如果意图不明确，请根据请求的产物推断（.sh / 终端会话或 .py 脚本）。

常见用法（CLI + SDK）

• 基于 ref 的操作依赖最新快照。
• 导航或 DOM 发生重大更新后，ref 可能会过期；执行基于 ref 的操作前，请刷新快照。
• CLI 会在多次调用之间通过守护进程会话保留状态。设置 BRIDGIC_HOME 环境变量，可运行多个相互独立的守护进程实例（各自拥有独立的套接字、日志和用户数据）。
• SDK 会在 Python 进程/上下文中保留状态。默认情况下，浏览器配置文件（Cookie、会话）会持久化到 $BRIDGIC_HOME/bridgic-browser/user_data/（默认路径为 ~/.bridgic/...）；向 Browser() 传入 clear_user_data=True 可创建临时会话。
• 使用参考资料中的准确命令/方法名称；不要编造别名。

桥接工作流：CLI 操作 -> Python 代码

1. 按顺序解析 CLI 步骤。
2. 使用 references/cli-sdk-api-mapping.md 映射每个步骤。
3. 保留行为细节：ref、选项、参数、配置等。
4. 输出可运行的异步 Python 代码，并明确管理浏览器生命周期（优先使用 async with Browser(...)）。
5. 指出任何无法 1:1 表示的行为差异。

最简质量检查清单

• CLI 请求：仅返回有效的 CLI 命令/选项。
• SDK 请求：返回带有正确导入语句的可执行异步 Python 代码。
• 桥接请求：包含映射理由以及最终的 SDK 代码。