bridgic-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dependencies

依赖项

A bridgic-browser project requires the following packages:

Package	Description
`bridgic-browser`	Browser automation CLI + Python SDK (installing one installs both)

Additionally, browser binaries must be installed once:

uv run playwright install chromium

Installation: Run the install script to set up all dependencies:

bash

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

The script checks uv availability, initializes a uv project if needed, installs missing packages, and ensures Playwright chromium is available.

一个bridgic-browser项目需要以下包：

包名	描述
`bridgic-browser`	浏览器自动化CLI + Python SDK（安装其中一个即可同时获得两者）

此外，浏览器二进制文件必须安装一次：

uv run playwright install chromium

。

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

bash

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

该脚本会检查uv的可用性，必要时初始化uv项目，安装缺失的包，并确保Playwright chromium可用。

Strategies & Guidelines (Important!!)

策略与指南（重要！！）

Notes:

Whenever invoking the
```
bridgic-browser
```
CLI, you must call it using
```
uv run
```
.
If the user clearly specifies exact steps that must be followed, try to perform the exploration according to those steps. If loops or branches appear during exploration, decide the best exploration path autonomously.
If you think you may need to return to the original page after clicking into a new page, try opening the new page in a new browser tab instead of using a “click then go back” approach. This is especially important when the original page already has interaction state (such as filled forms or applied filters); otherwise, that state may be lost after navigating back. Be sure to close the new tab promptly after finishing the related actions.
If exploration involves repeatedly clicking items in a list, you do not need to traverse every item (especially when the list is large).
If login, verification, or authorization is required during exploration, pause and ask the user to complete it manually, unless the user explicitly provides instructions in the task.
To avoid operating on websites too frequently, maintain human-like access intervals during both exploration and coding. You may simulate random wait times to reduce the risk of being blocked. Note: the
```
bridgic-browser wait
```
command parameter is in seconds, not milliseconds; for example,
```
bridgic-browser wait 2
```
or
```
bridgic-browser wait 3.2
```
.
After finishing exploration and code writing, automatically run testing/validation.

注意事项：

每当调用
```
bridgic-browser
```
CLI时，必须使用
```
uv run
```
来调用。
如果用户明确指定了必须遵循的精确步骤，请尝试按照这些步骤进行探索。如果探索过程中出现循环或分支，请自主决定最佳探索路径。
如果您认为点击进入新页面后可能需要返回原页面，请尝试在新浏览器标签页中打开新页面，而不是使用“点击后返回”的方式。当原页面已存在交互状态（如已填写的表单或已应用的筛选器）时，这一点尤为重要；否则，返回后该状态可能会丢失。完成相关操作后，请务必及时关闭新标签页。
如果探索涉及重复点击列表中的项，则无需遍历每一项（尤其是当列表很大时）。
如果探索过程中需要登录、验证或授权，请暂停并要求用户手动完成，除非用户在任务中明确提供了相关说明。
为避免过于频繁地操作网站，在探索和编码过程中请保持类人的访问间隔。您可以模拟随机等待时间以降低被封禁的风险。注意：
```
bridgic-browser wait
```
命令的参数单位是秒，而非毫秒；例如，
```
bridgic-browser wait 2
```
或
```
bridgic-browser wait 3.2
```
。
完成探索和代码编写后，自动运行测试/验证。

Reference Files

参考文件

Reference files cover all use cases. Load only the one(s) relevant to the task:

Scenario	Interface	Load
Directly control browser from terminal	CLI	cli-guide.md
Write Python code about browser automation	Python	sdk-guide.md
Write shell script about browser automation	CLI	cli-guide.md
Explore via CLI, then generate Python code	CLI → Python	cli-sdk-api-mapping.md + sdk-guide.md
Migrate / compare / explain CLI ↔ SDK	Both	cli-sdk-api-mapping.md
Configure env vars or login state persistence	Either	env-vars.md

参考文件涵盖所有使用场景。仅加载与任务相关的文件：

场景	接口	加载文件
从终端直接控制浏览器	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

Interface Decision Rules

接口决策规则

Output requested as shell commands or scripts → use CLI guide first (
```
references/cli-guide.md
```
).
Output requested as runnable Python code (
```
async
```
,
```
Browser
```
, tool builder) → use SDK guide first (
```
references/sdk-guide.md
```
).
Input is CLI outputs or actions but output needs to be Python code → use mapping guide first (
```
references/cli-sdk-api-mapping.md
```
), then SDK guide for final code generation (
```
references/sdk-guide.md
```
).
If intent is ambiguous, infer from requested artifacts (
```
.sh
```
/ terminal session vs
```
.py
```
script).

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

Common Usage (CLI + SDK)

常见用法（CLI + SDK）

Ref-based actions depend on the latest snapshot.
After navigation or major DOM updates, refs can become stale; refresh snapshot before ref actions.
CLI keeps state in a daemon session across invocations.
SDK keeps state in the Python process/context. By default, browser profile (cookies, session) is persisted to
```
~/.bridgic/bridgic-browser/user_data/
```
; pass
```
clear_user_data=True
```
to
```
Browser()
```
for an ephemeral session.
Use exact command/method names from references; do not invent aliases.

基于引用的操作依赖最新快照。
导航或DOM重大更新后，引用可能会失效；执行引用操作前请刷新快照。
CLI在多次调用间将状态保存在守护进程会话中。
SDK将状态保存在Python进程/上下文里。默认情况下，浏览器配置文件（Cookie、会话）会持久化到
```
~/.bridgic/bridgic-browser/user_data/
```
；向
```
Browser()
```
传入
```
clear_user_data=True
```
可创建临时会话。
使用参考文件中的精确命令/方法名称；请勿自行创建别名。

Bridge Workflow: CLI Actions -> Python Code

桥接工作流：CLI操作 → Python代码

Parse CLI steps in order.
Map each step using
```
references/cli-sdk-api-mapping.md
```
.
Preserve behavior details: refs, options, arguments, configuration, etc.
Emit runnable async Python code with explicit browser lifecycle (
```
async with Browser(...)
```
preferred).
Call out any behavior differences that cannot be represented 1:1.

按顺序解析CLI步骤。
使用
```
references/cli-sdk-api-mapping.md
```
映射每个步骤。
保留行为细节：引用、选项、参数、配置等。
生成可运行的异步Python代码，并明确浏览器生命周期（推荐使用
```
async with Browser(...)
```
）。
指出任何无法1:1还原的行为差异。

Minimal Quality Checklist

最低质量检查清单

CLI request: return valid CLI commands/options only.
SDK request: return executable async Python with correct imports.
Bridge request: include mapping rationale plus final SDK code.

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