100 lines
3.2 KiB
Markdown
100 lines
3.2 KiB
Markdown
# GrokBoy
|
||
|
||
Minimal local **GrokBot-like** CLI agent. Phase **P4**: human browser handoff (login/OTP/captcha).
|
||
|
||
## Status
|
||
|
||
| Phase | Status |
|
||
|-------|--------|
|
||
| P0 streaming chat | done |
|
||
| P1 shell / files + ReAct | done |
|
||
| P2 completion / loop guard / truncation | done |
|
||
| P3 browser (Playwright DOM) | done (optional) |
|
||
| P4 human handoff | done |
|
||
|
||
No Docker desktop, no Codex/LazyBoy fork. Product notes: [`docs/PRODUCT.md`](docs/PRODUCT.md).
|
||
|
||
## Setup (macOS)
|
||
|
||
```bash
|
||
export GROKBOY_API_KEY=your_key # or XAI_API_KEY
|
||
# optional:
|
||
# export GROKBOY_BASE_URL=https://api.x.ai/v1
|
||
# export GROKBOY_MODEL=grok-4.6
|
||
# export GROKBOY_CONTEXT_CHARS=100000
|
||
# export GROKBOY_BROWSER_HEADED=1 # visible Chromium (recommended for handoff)
|
||
|
||
cd ~/GrokBoy
|
||
cargo run -p grokboy -- chat
|
||
```
|
||
|
||
### Optional: Playwright browser tools
|
||
|
||
Browser tools are always registered but **fail closed** until you install the helper:
|
||
|
||
```bash
|
||
cd ~/GrokBoy/tools/playwright
|
||
npm install
|
||
npx playwright install chromium
|
||
```
|
||
|
||
Then the agent can use `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_eval`, and **`browser_handoff`** (DOM/selector/role — not screenshot-first).
|
||
|
||
### Human handoff (P4)
|
||
|
||
When the agent hits a login / OTP / captcha wall it calls `browser_handoff`:
|
||
|
||
1. Chromium opens **headed** (visible) — or relaunches headed if it was headless.
|
||
2. Terminal prints why it paused (ZH-TW + English) and what to do.
|
||
3. You complete the wall in the browser, then press **Enter** in that terminal (or type `abort`).
|
||
4. Agent resumes with a fresh **DOM snapshot**.
|
||
|
||
```bash
|
||
# Prefer headed for runs that may need handoff:
|
||
export GROKBOY_BROWSER_HEADED=1
|
||
cargo run -p grokboy -- run "打開需要登入的頁面並完成任務"
|
||
```
|
||
|
||
Tests / CI: `GROKBOY_HANDOFF_AUTO=1` auto-resumes (no interactive Enter).
|
||
|
||
## Commands
|
||
|
||
- `grokboy chat` — interactive streaming chat (no tools)
|
||
- `grokboy run "<prompt>"` — one-shot agent with tools
|
||
- `grokboy run --session <id> "<prompt>"` — continue a saved session
|
||
- `grokboy smoke` — offline checks (no API key / no interactive handoff)
|
||
- `grokboy help`
|
||
|
||
Tools: `shell`, `list_dir`, `read_file`, `write_file`, `report_done`, `report_blocked`,
|
||
`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_eval`,
|
||
`browser_handoff`.
|
||
|
||
Sessions are stored under `~/.grokboy/sessions/<id>.json` (may include `last_browser_url`).
|
||
|
||
The agent stops on `report_done` / `report_blocked`, blocks identical tool rounds (×3), and truncates old context when over budget.
|
||
|
||
## Traditional Chinese
|
||
|
||
本機終端機 coding assistant。P4 支援瀏覽器人工接手（登入／OTP／驗證碼）：代理暫停 → 你在可見 Chromium 完成 → 終端機按 Enter 繼續。
|
||
|
||
```bash
|
||
export GROKBOY_API_KEY=你的金鑰
|
||
export GROKBOY_BROWSER_HEADED=1
|
||
cd ~/GrokBoy
|
||
cargo run -p grokboy -- smoke
|
||
# 可選瀏覽器：
|
||
cd tools/playwright && npm install && npx playwright install chromium
|
||
cargo run -p grokboy -- run "打開 example.com 並 snapshot"
|
||
cargo run -p grokboy -- chat
|
||
```
|
||
|
||
## Layout
|
||
|
||
```
|
||
crates/grokboy-core/ # config, model, tools, browser, agent, session
|
||
crates/grokboy/ # CLI binary
|
||
tools/playwright/ # optional Node Playwright helper (JSONL)
|
||
docs/PRODUCT.md
|
||
docs/ACCEPTANCE.md
|
||
```
|