85 lines
4.5 KiB
Markdown
85 lines
4.5 KiB
Markdown
# GrokBoy product notes
|
||
|
||
**North star:** a local **Grok Bot–like** agent — thin CLI core, tool-using ReAct loop, optional Playwright **DOM** browser (not screenshot-first). GrokBoy is the sole main line; LazyBoy is reference only (no fork).
|
||
|
||
## Done (P0–P6)
|
||
|
||
| Phase | What |
|
||
|-------|------|
|
||
| **P0** | Streaming chat CLI (`grokboy chat`), xAI/OpenAI-compatible API |
|
||
| **P1** | Tools + ReAct (`shell`, files), sessions under `~/.grokboy/sessions/` |
|
||
| **P2** | Completion contract (`report_done` / `report_blocked`), loop guard, context truncation |
|
||
| **P3** | Optional Playwright DOM tools: navigate / snapshot / click / type / eval (fail-closed) |
|
||
| **P4** | Human browser handoff (`browser_handoff`) for login / OTP / captcha |
|
||
| **P5** | Interactive multi-turn agent REPL (`grokboy agent`) with tools + session persist |
|
||
| **P6** | Scenario playbooks + `request_user_confirm` (confirm-before-post) |
|
||
|
||
## P5 — Interactive multi-turn agent
|
||
|
||
Gap after P4: `chat` streams but has no tools; `run` has tools but is one-shot. P5 adds **`grokboy agent`**:
|
||
|
||
1. REPL reads a user line (ignore empty; `/exit` `/quit` leave; `/session` prints id).
|
||
2. Each turn runs the **same** ReAct loop as `run` (tools + handoff inherited).
|
||
3. Prints the verdict / assistant answer; **saves** under `~/.grokboy/sessions/` after every turn.
|
||
4. `--session <id>` resumes; omitting id auto-creates and prints the session id.
|
||
5. `chat` stays streaming no-tools; `run` stays one-shot.
|
||
|
||
### Env
|
||
|
||
- `GROKBOY_BROWSER_HEADED=1` — always launch Chromium headed (recommended for `run` / `agent` when handoff is likely).
|
||
- `GROKBOY_HANDOFF_AUTO=1` — auto-resume (tests / CI); `abort` to auto-abort.
|
||
|
||
### Non-goals (this slice)
|
||
|
||
- Multi-agent orchestration
|
||
- Desktop accessibility / native UI automation
|
||
- External connectors / SaaS integrations
|
||
- Forking LazyBoy or Codex
|
||
- Turning `chat` into a tools REPL (kept simple on purpose)
|
||
|
||
### Acceptance (summary)
|
||
|
||
See `docs/ACCEPTANCE.md` section P5.
|
||
|
||
## P6 — Scenario playbooks + confirm-before-post
|
||
|
||
**Capability:** reusable **scenario playbooks** for Grok Bot–style acceptance — not a single vertical hardcode.
|
||
|
||
Pattern:
|
||
|
||
1. **Phase A** — research + draft on a source portal (**no** irreversible publish)
|
||
2. Human only for: auth `browser_handoff` + final confirm
|
||
3. **Phase B** — publish to target channel **only** after explicit approval
|
||
|
||
**Product primitive:** `request_user_confirm` (bilingual stdin gate; `GROKBOY_CONFIRM_AUTO` for tests, falls back to `GROKBOY_HANDOFF_AUTO`). AGENT_SYSTEM forbids irreversible public social posts without (a) explicit user approval this turn of the exact draft, or (b) confirm → approved. Prefer draft → confirm → act; prefer `browser_handoff` only for auth walls.
|
||
|
||
**Docs:** [`docs/scenarios/README.md`](scenarios/README.md) (可推廣 pattern), [`docs/SCENARIO-TEMPLATE.md`](SCENARIO-TEMPLATE.md), `prompts/templates/`.
|
||
|
||
**Example only (範例，非唯一路徑):** Shopee Affiliate → Threads — [`docs/scenarios/examples/shopee-threads-affiliate.md`](scenarios/examples/shopee-threads-affiliate.md) + `prompts/examples/shopee-threads-phase-*.txt`.
|
||
|
||
### Env (P6)
|
||
|
||
- `GROKBOY_CONFIRM_AUTO=1` — auto-approve confirm (tests); `abort` to deny
|
||
- Falls back to `GROKBOY_HANDOFF_AUTO` when CONFIRM_AUTO unset
|
||
- `GROKBOY_BROWSER_HEADED=1` — required for real cookie/auth scenarios
|
||
|
||
### Acceptance (summary)
|
||
|
||
See `docs/ACCEPTANCE.md` section P6.
|
||
|
||
## P7 slice — agent UX polish (chat / max-rounds / blocked recovery)
|
||
|
||
Small product UX fixes (not a full phase):
|
||
|
||
1. **Natural chat answers** — `AGENT_SYSTEM` prefers plain assistant text for greetings / small talk / no-tools; `report_done` only after a real tool workflow; `report_blocked` when stuck.
|
||
2. **Max-rounds progress summary** — hitting `GROKBOY_MAX_ROUNDS` (default 12) triggers one final no-tools completion asking for a concise progress summary (Traditional Chinese welcome); that text becomes the Blocked message (`blocked: reached max rounds (N). Progress so far:\n…`). Falls back to the bare max-rounds string if the summary call fails.
|
||
3. **Blocked recovery hint** — `run` / `agent` eprintln a Traditional Chinese tip to continue with a shorter concrete instruction (session kept; do not paste the blocked blob back).
|
||
|
||
### Env
|
||
|
||
- `GROKBOY_MAX_ROUNDS` — ReAct tool rounds (default 12; `DEFAULT_MAX_ROUNDS`).
|
||
|
||
## Roadmap hint (later)
|
||
|
||
P7+ may deepen session UX further, richer browser persistence across process restarts, or more tools — still thin core, DOM-first browser, playbook-driven acceptance.
|