Skill: tielei/bridgic-browser (version 0.0.5)

--- name: bridgic-browser description: | Use for any task requiring a real browser: viewing web pages, accessing login-gated sites, operating web UIs, scraping social media (Xiaohongshu/Weibo/Twitter/X, etc.), reading JS-rendered or dynamic pages, bypassing bot detection, form filling, e2e checks, and general web automation. Prefer this over WebFetch whenever the page needs JS execution, authenticated session, interaction, or stealth. Invoke via terminal CLI (`bridgic-browser ...`) or Python SDK (`from bridgic.browser.session import Browser`, `from bridgic.browser.tools import BrowserToolSetBuilder`). Also covers accessibility snapshot refs, CLI-SDK mapping/migration, and generating SDK code from CLI action steps. --- ## 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. ## 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. - **CDP mode tab visibility**: when attached via `--cdp` to a user's running Chrome, `tabs` / `switch-tab` / `close-tab` only see pages bridgic itself opened (the initial blank tab plus anything spawned from it via `new-tab` or a click on a `target="_blank"` link). The user's other tabs are deliberately invisible to bridgic — never assume you can `switch-tab` into them. To work with such a tab, ask the user to navigate to it through bridgic, or use `new-tab <url>`. ## 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](references/cli-guide.md) | | Write Python code about browser automation | Python | [sdk-guide.md](references/sdk-guide.md) | | Write shell script about browser automation | CLI | [cli-guide.md](references/cli-guide.md) | | Explore via CLI, then generate Python code | CLI → Python | [cli-sdk-api-mapping.md](references/cli-sdk-api-mapping.md) + [sdk-guide.md](references/sdk-guide.md) | | Migrate / compare / explain CLI ↔ SDK | Both | [cli-sdk-api-mapping.md](references/cli-sdk-api-mapping.md) | | Configure env vars or login state persistence | Either | [env-vars.md](references/env-vars.md) | | Connect to an existing Chrome (chrome://inspect, `--remote-debugging-port`, cloud browser, Electron) | CLI / SDK | [cdp-mode.md](references/cdp-mode.md) | ## Interface Decision Rules 1. Output requested as shell commands or scripts → use CLI guide first (`references/cli-guide.md`). 2. Output requested as runnable Python code (`async`, `Browser`, tool builder) → use SDK guide first (`references/sdk-guide.md`). 3. 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``). 4. If intent is ambiguous, infer from requested artifacts (`.sh` / terminal session vs `.py` script). ## Common Usage (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. Set `BRIDGIC_HOME` env var to run multiple independent daemon instances (each with its own socket, logs, and user data). - SDK keeps state in the Python process/context. By default, browser profile (cookies, session) is persisted to `$BRIDGIC_HOME/bridgic-browser/user_data/` (default `~/.bridgic/...`); pass `clear_user_data=True` to `Browser()` for an ephemeral session. - Use exact command/method names from references; do not invent aliases. ## Bridge Workflow: CLI Actions -> Python Code 1. Parse CLI steps in order. 2. Map each step using `references/cli-sdk-api-mapping.md`. 3. Preserve behavior details: refs, options, arguments, configuration, etc. 4. Emit runnable async Python code with explicit browser lifecycle (`async with Browser(...)` preferred). 5. Call out any behavior differences that cannot be represented 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.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (CRITICAL)