1  # AI Workflow
 2  
 3  OpenCLI is designed for AI agents writing adapters. The workflow is built on a small set of browser primitives plus a skill that teaches the end-to-end loop.
 4  
 5  ## The Loop
 6  
 7  From a new site URL to a passing `opencli browser verify` — one skill, one set of primitives:
 8  
 9  ```bash
10  # 1. Pick up the skill (Claude Code)
11  #    skills/opencli-adapter-author/SKILL.md
12  
13  # 2. Reconnaissance
14  opencli browser open https://example.com
15  opencli browser wait time 3
16  opencli browser network        # inspect XHR / fetch calls
17  opencli browser state          # extract __INITIAL_STATE__ / __NEXT_DATA__
18  
19  # 3. Scaffold + verify
20  opencli browser init <site>/<name>
21  opencli browser verify <site>/<name>
22  ```
23  
24  The skill `opencli-adapter-author` walks through: coverage self-test → site recon → API discovery → field decoding → output design → adapter coding → verify → write-back to site memory.
25  
26  See [skills/opencli-adapter-author/SKILL.md](https://github.com/jackwener/opencli/blob/main/skills/opencli-adapter-author/SKILL.md).
27  
28  ## Primitives
29  
30  | Command | Purpose |
31  |---------|---------|
32  | `opencli doctor` | Sanity check: bridge, Chrome, signals |
33  | `opencli browser open <url>` | Open a tab in the Chrome session |
34  | `opencli browser network` | List recent XHR / fetch calls |
35  | `opencli browser state` | Page state: URL, title, interactive elements |
36  | `opencli browser eval '<expr>'` | Evaluate JS in the page context (cookies + origin honored) |
37  | `opencli browser init <site>/<name>` | Scaffold `~/.opencli/clis/<site>/<name>.js` |
38  | `opencli browser verify <site>/<name>` | Run the adapter and print first rows |
39  
40  No `explore` / `synthesize` / `generate` / `cascade` command. The skill drives the loop — the primitives are small and composable.
41  
42  ## Site Memory
43  
44  Every site accumulates knowledge at `~/.opencli/sites/<site>/` (endpoints, field decode map, notes, response fixtures). The adapter-author skill reads memory on Step 2 and writes back on Step 12 — see `skills/opencli-adapter-author/references/site-memory.md` for the schema.
45  
46  In-repo seeds for well-known sites live at `skills/opencli-adapter-author/references/site-memory/<site>.md` (eastmoney / xueqiu / bilibili / tonghuashun already covered).
47  
48  ## Authentication Strategies
49  
50  Adapters declare one of:
51  
52  1. **PUBLIC** — direct fetch, no credentials
53  2. **COOKIE** — reuse Chrome session cookies (`browser: true` + `credentials: 'include'`)
54  3. **HEADER** — inject a custom header (bearer / csrf / signed token)
55  4. **INTERCEPT** — let the page make the request; capture the response
56  
57  Pick per the `coverage-matrix.md` and `api-discovery.md` references inside the skill.
58  
59  ## When Something Breaks
60  
61  - Verify failure → run `opencli doctor`, then consult `skills/opencli-autofix/SKILL.md`
62  - Field values wrong → jump back to `skills/opencli-adapter-author/references/field-decode-playbook.md`
63  - Endpoint returns 401/403 → `api-discovery.md` §4 (token) / §5 (intercept)