136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# GrokBoy
|
||
|
||
Minimal local **GrokBot-like** CLI agent. Phase **P6**: scenario playbooks + confirm-before-post. **P7 UX**: natural chat, max-round summary, blocked recovery. **P8**: auto-continue chunks like Grok Bot (progress beats, total ceiling).
|
||
|
||
## 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 |
|
||
| P5 interactive agent REPL | done |
|
||
| P6 scenario playbooks + confirm | done |
|
||
| P7 agent UX polish | done (slice) |
|
||
| P8 auto-continue chunks | 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_MAX_ROUNDS=12 # rounds per chunk
|
||
# export GROKBOY_MAX_ROUNDS_TOTAL=48 # absolute ceiling across auto-continues
|
||
# export GROKBOY_PROGRESS=0 # silence 〔續跑〕 progress beats
|
||
# export GROKBOY_BROWSER_HEADED=1 # visible Chromium (recommended for handoff / agent)
|
||
|
||
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 "打開需要登入的頁面並完成任務"
|
||
# or interactive:
|
||
cargo run -p grokboy -- agent
|
||
```
|
||
|
||
Tests / CI: `GROKBOY_HANDOFF_AUTO=1` auto-resumes (no interactive Enter).
|
||
|
||
|
||
### Scenario playbooks (P6)
|
||
|
||
Reusable acceptance pattern: **Phase A** research+draft (no publish) → auth `browser_handoff` + **`request_user_confirm`** → **Phase B** publish only after approve.
|
||
|
||
- Pattern: [`docs/scenarios/README.md`](docs/scenarios/README.md)
|
||
- Template: [`docs/SCENARIO-TEMPLATE.md`](docs/SCENARIO-TEMPLATE.md) · prompts in `prompts/templates/`
|
||
- Example only: Shopee Affiliate → Threads — [`docs/scenarios/examples/shopee-threads-affiliate.md`](docs/scenarios/examples/shopee-threads-affiliate.md)
|
||
|
||
```bash
|
||
export GROKBOY_BROWSER_HEADED=1
|
||
cargo run -p grokboy -- agent
|
||
# paste prompts/examples/shopee-threads-phase-a.txt (or your filled template)
|
||
# review draft → paste phase-b or say「核准，請發佈…」
|
||
```
|
||
|
||
Tests: `GROKBOY_CONFIRM_AUTO=1` auto-approves; `abort` denies.
|
||
|
||
## 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 (one shot)
|
||
- `grokboy agent` — **interactive multi-turn** agent REPL with tools (auto session)
|
||
- `grokboy agent --session <id>` — resume an agent session
|
||
- `grokboy smoke` — offline checks (no API key / no interactive handoff)
|
||
- `grokboy help`
|
||
|
||
In `agent` REPL: `/exit` or `/quit` leave; `/session` show id; empty line ignored.
|
||
|
||
Tools: `shell`, `list_dir`, `read_file`, `write_file`, `report_done`, `report_blocked`,
|
||
`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_eval`,
|
||
`browser_handoff`, `request_user_confirm`.
|
||
|
||
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.
|
||
Long tasks **auto-continue** across chunks (`GROKBOY_MAX_ROUNDS` per beat, up to `GROKBOY_MAX_ROUNDS_TOTAL`) with `〔續跑〕` progress on stderr — like Grok Bot — instead of hard-stopping for a user re-prompt after every chunk.
|
||
|
||
## Traditional Chinese
|
||
|
||
本機終端機 coding assistant。P6 支援可推廣的情境劇本（Phase A 草稿 → confirm → Phase B 發佈）與 `request_user_confirm`。P5 `grokboy agent`；P4 `browser_handoff`（登入牆）。範例：蝦皮→Threads，見 `docs/scenarios/`。
|
||
|
||
```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 -- agent
|
||
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
|
||
docs/scenarios/ # playbook pattern + examples
|
||
prompts/templates/ # Phase A/B placeholders
|
||
prompts/examples/ # filled example prompts
|
||
```
|