leeguooooo
ea2e93dbba
- 将 CreepJS like headless 指标优化到 0%（headless/stealth 维持 0%） - 新增 ActiveText 与 prefers-color-scheme 探针修复 - 版本号采用 <upstream>-fork.<fork> 格式并在 --version 输出 upstream/fork - 更新 README、SKILL 与 docs 中的版本体系说明
144 lines
3.5 KiB
Plaintext
144 lines
3.5 KiB
Plaintext
import { pageMetadata } from "@/lib/page-metadata"
|
|
|
|
export const metadata = pageMetadata("installation")
|
|
|
|
# Installation
|
|
|
|
## Global installation (recommended)
|
|
|
|
Installs the native Rust binary for maximum performance:
|
|
|
|
```bash
|
|
npm install -g agent-browser-stealth
|
|
agent-browser install # Download Chromium
|
|
```
|
|
|
|
This is the fastest option -- commands run through the native Rust CLI directly with sub-millisecond parsing overhead.
|
|
|
|
## Quick start (no install)
|
|
|
|
Run directly with `npx` if you want to try it without installing globally:
|
|
|
|
```bash
|
|
npx agent-browser-stealth install # Download Chromium (first time only)
|
|
npx agent-browser-stealth open example.com
|
|
```
|
|
|
|
> **Note:** `npx` routes through Node.js before reaching the Rust CLI, so it is noticeably slower than a global install. For regular use, install globally.
|
|
|
|
## Project installation (local dependency)
|
|
|
|
For projects that want to pin the version in `package.json`:
|
|
|
|
```bash
|
|
npm install agent-browser-stealth
|
|
npx agent-browser-stealth install
|
|
```
|
|
|
|
Then use via `npx` or `package.json` scripts:
|
|
|
|
```bash
|
|
npx agent-browser-stealth open example.com
|
|
```
|
|
|
|
## Homebrew (macOS)
|
|
|
|
```bash
|
|
brew install agent-browser
|
|
agent-browser install # Download Chromium
|
|
```
|
|
|
|
## From source
|
|
|
|
```bash
|
|
git clone https://github.com/leeguooooo/agent-browser
|
|
cd agent-browser
|
|
pnpm install
|
|
pnpm build
|
|
pnpm build:native
|
|
./bin/agent-browser install
|
|
pnpm link --global
|
|
```
|
|
|
|
## Fork versioning
|
|
|
|
Fork releases use a dual-version format:
|
|
|
|
- `<upstream>-fork.<fork>`
|
|
- Example: `0.14.0-fork.1`
|
|
|
|
`agent-browser --version` prints the full version and also shows upstream and fork parts for fork builds.
|
|
|
|
## Linux dependencies
|
|
|
|
On Linux, install system dependencies:
|
|
|
|
```bash
|
|
agent-browser install --with-deps
|
|
# or manually: npx playwright install-deps chromium
|
|
```
|
|
|
|
## Custom browser
|
|
|
|
Use a custom browser executable instead of bundled Chromium:
|
|
|
|
- **Serverless** - Use `@sparticuz/chromium` (~50MB vs ~684MB)
|
|
- **System browser** - Use existing Chrome installation
|
|
- **Custom builds** - Use modified browser builds
|
|
|
|
```bash
|
|
# Via flag
|
|
agent-browser --executable-path /path/to/chromium open example.com
|
|
|
|
# Via environment variable
|
|
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com
|
|
```
|
|
|
|
### Serverless example
|
|
|
|
```typescript
|
|
import chromium from '@sparticuz/chromium';
|
|
import { BrowserManager } from 'agent-browser-stealth';
|
|
|
|
export async function handler() {
|
|
const browser = new BrowserManager();
|
|
await browser.launch({
|
|
executablePath: await chromium.executablePath(),
|
|
headless: true,
|
|
});
|
|
// ... use browser
|
|
}
|
|
```
|
|
|
|
## AI agent setup
|
|
|
|
agent-browser works with any AI agent out of the box. For richer context:
|
|
|
|
### AI coding assistants (recommended)
|
|
|
|
Install the skill for your AI coding assistant:
|
|
|
|
```bash
|
|
npx skills add leeguooooo/agent-browser
|
|
```
|
|
|
|
This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository and stays up to date automatically.
|
|
|
|
> **Do not** copy `SKILL.md` from `node_modules` -- it will become stale as new features are added. Always use `npx skills add` or reference the repository version.
|
|
|
|
### AGENTS.md / CLAUDE.md
|
|
|
|
Add to your instructions file:
|
|
|
|
```markdown
|
|
## Browser Automation
|
|
|
|
Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.
|
|
|
|
Core workflow:
|
|
1. `agent-browser open <url>` - Navigate to page
|
|
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
|
|
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
|
|
4. Re-snapshot after page changes
|
|
```
|