mirror of
https://github.com/jackwener/OpenCLI.git
synced 2026-09-14 18:25:42 +08:00
jakevin
afa5e6046c
* refactor: consolidate 6 skills into 3, remove mechanical commands Replaces opencli-oneshot / opencli-explorer / opencli-browser / opencli-usage with a single opencli-adapter-author skill that takes the AI agent end-to-end: site recon, API discovery, field decoding, adapter coding, and `opencli browser verify`. Removes the mechanical commands (`explore`, `synthesize`, `generate`, `cascade`, `record`) and their src/tests — they were codegen scaffolding meant for agents, which the new skill handles more flexibly via `opencli browser` primitives. Skill highlights: - Top-level decision tree + 12-step runbook - 5 site patterns (SPA / SSR / JSONP / Token / Streaming) - 5-layer API discovery (network → initial state → bundle → token → interceptor) - Field decode playbook (self-explanatory → codes → sort-key comparison) - Output design guide (columns, types, order, ≤15 per adapter) - Two-layer site memory: in-repo seeds for eastmoney/xueqiu/bilibili/tonghuashun plus local `~/.opencli/sites/<site>/` runtime workspace Kept skills: opencli-autofix (now points to adapter-author for rewrites), smart-search. Kept primitives: `browser *`, `doctor`, `list`, `validate`, `verify`, `<site> <cmd>`, `plugin *`, `completion`. No backward compatibility shims. Full test suite (1605 tests) passes. * review fixes: honest coverage, hard memory-hit path, typo, stale docs - site-memory hit path no longer jumps to writing adapter; forces Step 5 endpoint re-verification + Step 7 field check, and 30-day expiry - site-memory.md now specifies exact schemas for endpoints.json / field-map.json / notes.md / fixtures + write-back timing rules - coverage-matrix.md marks unverified patterns as 🟡 with an evidence section citing coingecko dry run + PR #1091 eastmoney + bilibili - eastmoney seed typo: resolveSecids -> resolveSecid (and splitSymbols) - docs/developer/ai-workflow.md rewritten to teach the adapter-author skill + opencli browser * primitives (dropped generate/synthesize/ cascade/explore references) - ts-adapter.md, getting-started.md, CHANGELOG.md:87 updated to point at opencli-adapter-author * fix(ci): resync package-lock + drop stale built-in list reference - Regenerate package-lock.json to restore @emnapi/core + @emnapi/runtime entries that got dropped during the rebase — `npm ci` was failing on all CI jobs (build / audit / docs-build / bun-test / unit-test) - docs/guide/getting-started.md: built-in list dropped `explore`, now reads (list, validate, verify, browser, doctor, plugin...) * fix(ci): restore package-lock.json from main (unrelated lockfile churn)
64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# AI Workflow
|
|
|
|
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.
|
|
|
|
## The Loop
|
|
|
|
From a new site URL to a passing `opencli browser verify` — one skill, one set of primitives:
|
|
|
|
```bash
|
|
# 1. Pick up the skill (Claude Code)
|
|
# skills/opencli-adapter-author/SKILL.md
|
|
|
|
# 2. Reconnaissance
|
|
opencli browser open https://example.com
|
|
opencli browser wait time 3
|
|
opencli browser network # inspect XHR / fetch calls
|
|
opencli browser state # extract __INITIAL_STATE__ / __NEXT_DATA__
|
|
|
|
# 3. Scaffold + verify
|
|
opencli browser init <site>/<name>
|
|
opencli browser verify <site>/<name>
|
|
```
|
|
|
|
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.
|
|
|
|
See [skills/opencli-adapter-author/SKILL.md](https://github.com/jackwener/opencli/blob/main/skills/opencli-adapter-author/SKILL.md).
|
|
|
|
## Primitives
|
|
|
|
| Command | Purpose |
|
|
|---------|---------|
|
|
| `opencli doctor` | Sanity check: bridge, Chrome, signals |
|
|
| `opencli browser open <url>` | Open a tab in the Chrome session |
|
|
| `opencli browser network` | List recent XHR / fetch calls |
|
|
| `opencli browser state` | Page state: URL, title, interactive elements |
|
|
| `opencli browser eval '<expr>'` | Evaluate JS in the page context (cookies + origin honored) |
|
|
| `opencli browser init <site>/<name>` | Scaffold `~/.opencli/clis/<site>/<name>.js` |
|
|
| `opencli browser verify <site>/<name>` | Run the adapter and print first rows |
|
|
|
|
No `explore` / `synthesize` / `generate` / `cascade` command. The skill drives the loop — the primitives are small and composable.
|
|
|
|
## Site Memory
|
|
|
|
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.
|
|
|
|
In-repo seeds for well-known sites live at `skills/opencli-adapter-author/references/site-memory/<site>.md` (eastmoney / xueqiu / bilibili / tonghuashun already covered).
|
|
|
|
## Authentication Strategies
|
|
|
|
Adapters declare one of:
|
|
|
|
1. **PUBLIC** — direct fetch, no credentials
|
|
2. **COOKIE** — reuse Chrome session cookies (`browser: true` + `credentials: 'include'`)
|
|
3. **HEADER** — inject a custom header (bearer / csrf / signed token)
|
|
4. **INTERCEPT** — let the page make the request; capture the response
|
|
|
|
Pick per the `coverage-matrix.md` and `api-discovery.md` references inside the skill.
|
|
|
|
## When Something Breaks
|
|
|
|
- Verify failure → run `opencli doctor`, then consult `skills/opencli-autofix/SKILL.md`
|
|
- Field values wrong → jump back to `skills/opencli-adapter-author/references/field-decode-playbook.md`
|
|
- Endpoint returns 401/403 → `api-discovery.md` §4 (token) / §5 (intercept)
|