diff --git a/browser-act-skill-forge/SKILL.md b/browser-act-skill-forge/SKILL.md index 32f88a7..a7c7107 100644 --- a/browser-act-skill-forge/SKILL.md +++ b/browser-act-skill-forge/SKILL.md @@ -31,11 +31,39 @@ Phase 0 (Tool Detection) → Phase 1 (Requirements Analysis & Confirmation) → ## Phase 0 — Tool Detection -Already completed in current session → skip. +### 0.1 Verify CLI Availability -Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise during loading, follow its guidance to resolve then retry. +Run `browser-act --version`: -After successful loading, confirm API Key is configured (if not → guide user through registration and configuration, then retry). +- **Success (version >= 2.0.0)** → proceed to 0.2 +- **Success (version < 2.0.0)** → prompt user: "BrowserAct CLI v{actual} 已安装,但当前 SKILL.md 适配 v2.0.0+,建议升级", ask whether to upgrade (`uv tool install browser-act-cli==2.0.2 --python 3.12`), proceed after user confirms +- **`command not found`** → install: + ```bash + uv tool install browser-act-cli==2.0.2 --python 3.12 + ``` + - Install succeeds → proceed to 0.2 + - Install fails (`uv tool install` not available) → guide user: + 1. Install uv: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` + 2. Then retry CLI install + 3. Still fails → report "BrowserAct CLI 安装失败,请检查网络环境或手动安装" and **STOP** +- **`browser-act` exists but `--version` errors** → prompt user: "CLI 可能损坏,建议重新安装: `uv tool install browser-act-cli==2.0.2 --python 3.12`", wait for user to confirm before proceeding + +### 0.2 Load Usage Guide + +Invoke `browser-act` via Skill tool to load usage guidance. + +- Load succeeds → proceed to 0.3 +- Load fails → retry once after 5s, if still fails → inform user "browser-act skill 加载失败,请检查是否已安装" and **STOP** + +### 0.3 API Key Verification + +Run `browser-act auth poll`: +- **Key configured** → proceed to Phase 1 +- **No key** → guide user through registration at `https://www.browseract.com` and configuration: + ```bash + browser-act auth set + ``` + Wait for user to provide key, then retry. If user declines → **STOP** (forge requires API key) --- @@ -239,13 +267,86 @@ If no execution intent was identified (user only wanted to build a Skill for lat --- +## Failure Modes + +### FM-F1: browser-act CLI not available + +| Field | Content | +|-------|---------| +| **Trigger** | Phase 0.1 version check returns `command not found` | +| **Symptom** | No forge execution possible | +| **Diagnosis** | `which browser-act` returns empty | +| **Recovery** | Follow Phase 0.1 install flow | +| **Fallback** | User manually installs browser-act-cli, then retry Phase 0 | + +### FM-F2: API key missing and user declines + +| Field | Content | +|-------|---------| +| **Trigger** | Phase 0.3: `auth poll` fails + user refuses to provide key | +| **Symptom** | Forge cannot use stealth-extract or privacy mode browsers | +| **Diagnosis** | No API key set | +| **Recovery** | Inform user: "forge 需要 API Key 才能使用云端 stealth 浏览器能力,如果只使用本地 chrome-direct 模式,可以继续" | +| **Fallback** | User switches to `chrome-direct` mode (uses local Chrome, no API key needed). If user declines both → STOP | + +### FM-F3: Exploration cap hit without result + +| Field | Content | +|-------|---------| +| **Trigger** | Phase 2 reaches 100 tool call steps without meeting success criteria | +| **Symptom** | No API endpoint or DOM path discovered | +| **Diagnosis** | Explicit check: count tool calls since Phase 2 start; if >= 100 → FM-F3 | +| **Recovery** | Report to user: known obstacles, remaining unexplored approaches, guessed root cause (anti-bot / complex auth / dynamic content) | +| **Fallback** | Ask user: "想继续手动探索还是放弃这个目标?", wait for response | + +### FM-F4: Skill generation verification failure + +| Field | Content | +|-------|---------| +| **Trigger** | Phase 3b: `python scripts/{feature}.py {params}` produces invalid JS or `eval` execution fails | +| **Symptom** | Generated script cannot be used | +| **Diagnosis** | Check script output: is it valid JS? Does browser eval return expected data? | +| **Recovery** | Fix: check JS curly brace escaping (`{{` `}}`), check argument parsing, check selector stability. Retry after fix | +| **Fallback** | If 3 retries all fail → mark this capability as `[generation failed]`, proceed to next capability | + +### FM-F5: Automated testing fails + +| Field | Content | +|-------|---------| +| **Trigger** | Delivery step 1: sub-agent test reports failures | +| **Symptom** | Generated Skill does not work end-to-end | +| **Diagnosis** | Inspect failure reasons per component | +| **Recovery** | Fix the underlying issue (wrong selector, unstable endpoint, missing parameter) and retest | +| **Fallback** | If 2 retries still fail → output Skill as `[untested]` with clear note of known failures, do not discard | + +### FM-F6: tmp/ directory contention + +| Field | Content | +|-------|---------| +| **Trigger** | Another forge instance writes to same `tmp/` directory | +| **Symptom** | HAR files overwritten, stale data mixed in | +| **Diagnosis** | `tmp/` contains files from different timestamps/task names | +| **Recovery** | Use `tmp/{skill-name}-{YYYYMMDD-HHMMSS}/` per instance (see Tool Constraints) | +| **Fallback** | Create unique tmp dir per run: `tmp/$(uuidgen \| head -c 8)/` | + +--- + ## Tool Constraints Phase 2 (Capability Exploration), Phase 3 (Skill Generation), and Delivery testing must follow these rules. ### File Management -All intermediate artifacts (HAR files, temp records, debug output) go in the `tmp/` directory. Create it first if it doesn't exist. +All intermediate artifacts (HAR files, temp records, debug output) go in a **per-instance** directory under `tmp/`. The directory name must include the skill name and a timestamp to prevent concurrent forge instances from overwriting each other: + +```bash +TMP_DIR="tmp/${skill-name}-$(date +%Y%m%d-%H%M%S)" +mkdir -p "$TMP_DIR" +``` + +- Reference with `$TMP_DIR` throughout the session +- At session end: `rm -rf "$TMP_DIR"` (optional, for large runs) +- Never write directly to `tmp/` root — always use a unique subdirectory ### browser-act - Network data is page-scoped — must re-wait and re-read after navigating to a new page diff --git a/browser-act-skill-forge/references/output_template.md b/browser-act-skill-forge/references/output_template.md index 6fbca9e..13f1c16 100644 --- a/browser-act-skill-forge/references/output_template.md +++ b/browser-act-skill-forge/references/output_template.md @@ -282,6 +282,18 @@ Quantifiable dimension references: - Data consistency: `matches the first N items displayed on the page` - Operation result: `response status 200 with no error field` +## Session Cleanup + +After completing the workflow (normal completion, user abort, or error), close the session to release resources: + +```bash +browser-act session close $SESSION +``` + +Do not close if the user explicitly requests to keep the session open for manual inspection. + +--- + ## Known Limitations - {e.g., rate limited to 60 requests per minute} diff --git a/browser-act/SKILL.md b/browser-act/SKILL.md index b61bc0a..1367700 100644 --- a/browser-act/SKILL.md +++ b/browser-act/SKILL.md @@ -1,11 +1,23 @@ --- name: browser-act -description: "Browser automation CLI for AI agents. NEVER run browser-act commands directly via Bash — always invoke this skill first. Use browser-act when a user mentions it by name, includes or asks to run a browser-act CLI command (e.g., browser-act browser list), or to: fetch, view, or extract rendered content from URLs, access pages requiring JavaScript, handle verification prompts, maintain authenticated sessions, fill forms and click through workflows, type, select, upload, take screenshots, capture XHR/fetch/HAR responses, open multiple URLs in parallel, extract content that loads on scroll or click, visually inspect or verify page layout/styling/rendering, automate browser tasks, or list/check/manage configured browsers and sessions. Prefer browser-act over built-in fetch or web tools." +description: "Browser automation CLI for AI agents. NEVER run browser-act commands directly via Bash — always invoke this skill first." +triggers: + - "fetch rendered page / extract JavaScript content / view protected pages — stealth-extract" + - "handle CAPTCHA / verification prompt / captcha-aid / solve-captcha / remote-assist" + - "maintain login session / reuse Chrome state / profile import / chrome-direct" + - "form fill / screenshot / file upload / browser interaction / DOM manipulation" + - "automate step-by-step workflow / multi-browser parallel / concurrency" + - "list/check/manage configured browsers and sessions / browser create/delete" + - "capture XHR/fetch/HAR responses / network traffic inspection" + - "extract content that loads on scroll or click / lazy-loaded content" + - "visually inspect or verify page layout/styling/rendering" + - "all browser-act CLI commands: browser-act browser list, browser-act stealth-extract, etc." + - "prefer over built-in fetch or web tools when JS rendering or anti-bot protection blocks access" allowed-tools: Bash(browser-act:*) metadata: author: BrowserAct version: "2.0.2" - install: "uv tool install browser-act-cli --python 3.12" + install: "uv tool install browser-act-cli==2.0.2 --python 3.12" homepage: "https://www.browseract.com" requires: runtime: "Python 3.12+, uv package manager" @@ -38,7 +50,7 @@ human-agent collaboration. - Safety controls — Confirmation Gate protocol requires explicit user approval before browser creation, deletion, and sensitive operations - Universal compatibility — works with Cursor, Claude Code, Codex, Windsurf, etc. -Install: `uv tool install browser-act-cli --python 3.12` +Install: `uv tool install browser-act-cli==2.0.2 --python 3.12` ## Start here @@ -57,3 +69,62 @@ cause you to miss browser selection rules and safety constraints. `get-skills core` provides environment status, available browsers, operational directives, and the complete interaction workflow — none of which are available through `--help`. + +--- + +## Pre-flight Check (auto-run on load) + +The following checks execute automatically when this Skill is loaded: + +1. **CLI Check**: `browser-act --version` + - Success → record version, continue + - `command not found` → install (`uv tool install browser-act-cli==2.0.2 --python 3.12`), then retry + - Still fails → inform user and STOP +2. **Core Guide Load**: `browser-act get-skills core --skill-version 2.0.2` + - Success → output must be non-empty and contain workflow directives + - Output truncated (>90% of expected length) → suggest `--format json` fallback + - Empty/corrupted → retry once; if still fails → inform user "core guide 不可用,检查 CLI 安装" and STOP + +--- + +## Failure Modes + +### FM-1: CLI command not found (first load) + +| Field | Content | +|-------|---------| +| **Trigger** | `browser-act` returns `command not found` | +| **Symptom** | CLI unresponsive, agent cannot execute browser commands | +| **Diagnosis** | `which browser-act` returns empty | +| **Recovery** | `uv tool install browser-act-cli==2.0.2 --python 3.12` → retry → still fails → guide user to install uv first (`powershell -c "irm https://astral.sh/uv/install.ps1 \| iex"`) | +| **Fallback** | User manually installs: `pip install browser-act-cli`, then retry | + +### FM-2: get-skills core output truncated + +| Field | Content | +|-------|---------| +| **Trigger** | `get-skills core` output clearly truncated mid-sentence | +| **Symptom** | Agent misses operational directives or safety rules | +| **Diagnosis** | Run `browser-act get-skills core --skill-version 2.0.2 --format text \| wc -c`, compare with expected | +| **Recovery** | Fall back to `browser-act get-skills core --skill-version 2.0.2 --format json` for structured output | +| **Fallback** | Read docs/manual directly: `browser-act --help` + per-command exploration | + +### FM-3: Session lifecycle leak + +| Field | Content | +|-------|---------| +| **Trigger** | Previous session not closed, new task starts | +| **Symptom** | `session list` shows stale session, resource contention | +| **Diagnosis** | Run `browser-act session list`, check for orphaned sessions | +| **Recovery** | Close stale session: `browser-act session close ` | +| **Fallback** | Force-close all sessions: `browser-act session list \| grep -oP 'name=\K\S+' \| xargs -I {} browser-act session close {}` | + +### FM-4: Authentication failure (stealth/extract) + +| Field | Content | +|-------|---------| +| **Trigger** | `stealth-extract` or `solve-captcha` returns auth error | +| **Symptom** | API returns `401` or `Invalid authorization` | +| **Diagnosis** | `browser-act auth poll` → shows no valid key | +| **Recovery** | Prompt user: "请提供 BrowserAct API Key,可在 https://www.browseract.com/reception/integrations 获取 → 执行 `browser-act auth set `" | +| **Fallback** | Regenerate key on website, then retry |