opencli-adapter-author

You are an agent tasked with writing an adapter for a site. This skill's goal: complete end-to-end closure from zero to passing opencli browser verify within 30 minutes.

Use only existing tools throughout: opencli browser * / opencli doctor / opencli browser init / opencli browser verify. No new commands.

When debugging browser-type adapters, prioritize running with --trace on --keep-tab true --window foreground. --trace on drops a trace artifact each round; summary.md is the entry point for failure/success review. --keep-tab true --window foreground keeps the tab lease and browser window in the foreground, making it easy to verify the final page state.

---

Prerequisites: Determine Your Starting Point

First, do a quick self-test using coverage-matrix.md. Three questions:

1. Can you see the data in the browser? (No → solve auth first)
2. Is the data HTTP/JSON/HTML? (No → outside this skill's scope)
3. Does it require real-time push? (Yes → find a synchronous HTTP polling interface for the same data; if none exists, give up)

If all three are yes, proceed.

---

Top-Level Decision Tree

START
  │
  ▼
┌──────────────────────────┐
│ opencli doctor passes?   │── no ──→ Fix bridge (hints in doctor output)
└──────────────────────────┘
  │ yes
  ▼
┌────────────────────────────────────────────────────┐
│ Read site memory:                                   │
│   1. ~/.opencli/sites/<site>/endpoints.json         │
│   2. ~/.opencli/sites/<site>/notes.md               │
│   3. references/site-memory/<site>.md               │
└────────────────────────────────────────────────────┘
  │ Hit endpoint + fields → Jump to【endpoint verify】(don't skip to adapter! memory may be stale)
  │ No hit → continue
  ▼
┌──────────────────────────┐
│ Site recon (site-recon)  │  → Pattern A/B/C/D/E
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ API discovery            │  §1 network → §2 state → §3 bundle → §4 token → §5 intercept
└──────────────────────────┘
  │ Get candidate endpoint
  ▼
┌────────────────────────────────────────────┐
│ Direct fetch to verify endpoint             │── 401/403 ──→ Back to §4 for token
│ (also run even if memory hit)               │── empty/HTML ──→ Back to site-recon, switch Pattern
│ Non-empty data + 200                        │── site version change ──→ Mark old endpoint, back to api-discovery
│ Is memory value still alive?                │
└────────────────────────────────────────────┘
  │ OK
  ▼
┌───────────────────────────────────────┐
│ Field decoding                         │  Self-explanatory → direct use / known code → field-conventions
│ (also spot-check field-map in memory) │  / unknown → decode-playbook
│ Compare one known field with web value│
│ to confirm no offset errors            │
└───────────────────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ Design columns (output)  │  Per output-design.md: naming / type / order
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ opencli browser init     │  Generate ~/.opencli/clis/<site>/<name>.js skeleton
│ Copy most similar        │
│ neighbor adapter         │
│ Edit name / URL / 3 maps │
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ opencli browser verify   │── fail ──→ autofix skill, use --trace retain-on-failure back to corresponding step
└──────────────────────────┘
  │ success
  ▼
┌──────────────────────────┐
│ Compare field values vs  │── values mismatch ──→ Back to field decoding
│ website visually once    │
└──────────────────────────┘
  │ matches
  ▼
┌──────────────────────────┐
│ Write back ~/.opencli/   │  endpoints / field-map / notes / fixtures
│ sites/                   │
└──────────────────────────┘
  │
  ▼
DONE

---

Runbook (Check Off Step by Step)

[ ] 1. opencli doctor returns "Everything looks good"
[ ] 2. Read site memory:
       [ ] ~/.opencli/sites/<site>/endpoints.json exists? Contains desired endpoint?
       [ ] references/site-memory/<site>.md exists? Check "Known endpoints" section
       [ ] If hit: **Jump to Step 5 (endpoint verify) + Step 7 (field check)**, cannot skip directly to Step 9 for adapter
       [ ] memory verified_at > 30 days ago → treat as stale, cold-start via Step 3 → 4
[ ] 3. Recon (site-recon.md):
       [ ] **Preferred**: `opencli browser analyze <url>` gets pattern + anti-scrape + recent adapters + next step in one go
       [ ] When `analyze` is unclear, manual run: `open` → `wait time 2` (or `wait xhr <regex>`) → `network`
       [ ] Determine Pattern (A / B / C / D / E)
[ ] 4. API discovery (api-discovery.md) by Pattern:
       [ ] Pattern A → §1 network deep read
       [ ] Pattern B → §2 state extraction + §1 deeper data
       [ ] Pattern C → §3 bundle / script src search
       [ ] Pattern D → §4 token source + fallback §5
       [ ] Pattern E → find HTTP polling interface; if not found, §5
[ ] 5. Direct fetch candidate endpoint to verify:
       [ ] Returns 200
       [ ] Response contains target data (not HTML / ads)
[ ] 6. Define auth strategy: bare fetch works → PUBLIC; needs cookie / token / csrf → COOKIE; can't get signature → INTERCEPT; can only click UI → UI
[ ] 7. Field decoding:
       [ ] Self-explanatory → use key directly
       [ ] Known code → check field-conventions.md
       [ ] Unknown code → field-decode-playbook.md (sort key comparison / structure diff / constant audit)
[ ] 8. Design columns (output-design.md):
       [ ] Name in camelCase aligned with neighbor adapters
       [ ] Type / unit / percentage format clear
       [ ] Order: identifier → business numbers → metadata
[ ] 9. Write adapter (adapter-template.md):
       [ ] opencli browser init <site>/<name>
       [ ] Find most similar adapter (same site or type), copy it
       [ ] Edit name / URL / field mappings
[ ] 10. opencli browser verify <site>/<name>
        [ ] On first pass, immediately `--write-fixture` to generate `~/.opencli/sites/<site>/verify/<cmd>.json` seed
        [ ] Hand-edit seed: add `patterns` (URL / date / ID formats) + `notEmpty` (core fields) + tighten `rowCount`
        [ ] Run `opencli browser verify <site>/<name>` again, confirm ✓ matches fixture
[ ] 11. Compare field values vs website visually (don't just check "Adapter works!")
[ ] 12. Write back site memory (**after verify passes + visual comparison confirms**, schema see `references/site-memory.md`):
        [ ] `endpoints.json`: keyed by endpoint short name, value = `{url, method, params.{required,optional}, response, verified_at: YYYY-MM-DD, notes}`
        [ ] `field-map.json`: append new codes only. key = field code, value = `{meaning, verified_at: YYYY-MM-DD, source}`; **don't overwrite existing keys**, align with web visual if conflict exists
        [ ] `notes.md`: append one section `## YYYY-MM-DD by <agent/user>` at top, document new pitfalls / conclusions from this adapter session
        [ ] `verify/<cmd>.json`: **required.** Expected values for `opencli browser verify` (args / rowCount / columns / types / patterns / notEmpty); Step 10 already generated it, just checklist here
        [ ] `fixtures/<cmd>-<YYYYMMDDHHMM>.json`: store complete response sample from endpoint (strip cookies / tokens / user-private fields), for later field comparison / offline replay
        [ ] If you dumped temp files during debugging (`.dbg-*.html` / `raw-*.json` / etc) in repo / adapter dir, **clean them before commit**—they belong in `~/.opencli/sites/<site>/fixtures/` or `/tmp/`

---

Degradation Paths (If Stuck at Step X, Jump To)

Stuck at	Symptom	Jump to
Step 4 API discovery	network empty, __INITIAL_STATE__ also empty	§3 bundle search for baseURL
	bundle can't find baseURL	§5 intercept
Step 5 endpoint verify	401 / 403	§4 token audit
	200 but response is HTML	back to Step 3, switch Pattern judgment
	200 but data: [] empty	wrong params / endpoint version change, back to §1 check real request headers in network
Step 7 field decoding	sort key comparison doesn't yield result	field-decode-playbook.md §3 structure diff
	still doesn't yield	output raw first, iterate after adapter runs
Step 10 verify fails	fltt missing / field mapping wrong	autofix skill; repeat with --trace retain-on-failure
	column always null	field path wrong, back to Step 7
Step 10 verify fixture mismatch	[pattern] row[i] error	first compare web values visually; if value matches → fixture pattern too strict, relax; if value wrong → field mapping wrong
	[column] missing column "X"	actual response lacks this column (site version change or args affect it); re-run --update-fixture or fix adapter
	[type] actual null / undefined	field extraction failed, back to Step 7 re-extract; temp fallback to union type string|null only if semantic allows null
Step 11 values wrong	off by 10000x	unit mismatch ("万" vs "元")
	percentage 100x too small	response already 0.025, don't × 100

---

Reference Files

File	When to read
references/coverage-matrix.md	Before starting: is this in scope?
references/site-recon.md	Step 3: determine site type
references/api-discovery.md	Step 4: find endpoint
references/field-conventions.md	Step 7: look up known field codes
references/field-decode-playbook.md	Step 7: field not in dictionary
references/output-design.md	Step 8: naming / type / order
references/adapter-template.md	Step 9: file structure + live example convertible.js
references/site-memory.md	Overview: in-repo seed + local ~/.opencli/sites/ two-layer structure
references/site-memory/<site>.md	Step 2: read site public knowledge (eastmoney / xueqiu / bilibili / tonghuashun pre-populated)
references/success-rate-pitfalls.md	Step 7 / 11: read before hitting gotchas—11 types of "verify passes but data wrong" silent failures (incl aria-label locale-dependence)
references/jsdom-fixture-pattern.md	When adapter uses page.evaluate with DOM extraction + mocked-evaluate unit test misses silent bug—freeze HTML into clis/<site>/__fixtures__/ and run with JSDOM (incl mandatory awk 'NF>0' tight whitespace + reverse-validate discipline)
references/typed-errors.md	Read before writing func body: 5-class typed error landing table (ArgumentError / EmptyResultError / CommandExecutionError / AuthRequiredError / TimeoutError) + three major silent anti-patterns (silent-clamp / sentinel-row / generic CliError) with counter-examples

---

Key Conventions

• adapter only imports @jackwener/opencli/registry + @jackwener/opencli/errors, no third-party
• columns array and func return object keys must align perfectly (including order)
• Intermediate parse object keys cannot overlap with any columns item (else silent-column-drop audit misfire, PR #1329 R1 actually hit this; use dedicated naming + push row with destructure aliasing)
• browser: field determines func signature: browser:false → (args), browser:true → (page, args). If reversed, args actually becomes debug flag, all external params silent-fallback to default (PR #1329 upstream: 8 non-browser adapters all hit this before)
• Throw typed errors per references/typed-errors.md 5-classification for known failures; don't silent return [], don't silent return [{sentinel}], don't Math.max/min silent-clamp external params
• Private adapters go in ~/.opencli/clis/<site>/<name>.js (skip build); only copy to clis/<site>/<name>.js when submitting PR
• site memory rewrites each round: no memory → use skill → produce memory → next time 5 minutes
• Raw dumps / packet captures / HTML samples from debug sessions go only in ~/.opencli/sites/<site>/fixtures/ or /tmp/. Strictly forbidden: .dbg-*.html / raw-*.json / sample.* temp files in repo root, clis/<site>/, or CWD (PR diff picks them up, review noise)
• JSDOM unit-test fixtures (clis/<site>/__fixtures__/<command>.html) are the exception to above—they are intentionally commit artifacts for review, not temp dumps. Higher quality bar: follow references/jsdom-fixture-pattern.md all 5 steps (incl mandatory awk 'NF>0' whitespace tighten), reverse-validate to prove regression guard actually fires.

---

Stuck?

• Diagnosis: opencli doctor → check notes.md → search autofix skill
• Field decoding: complete all three sections in field-decode-playbook.md → output raw first, iterate
• Endpoint not found: api-discovery §5 intercept fallback

Don't guess. Wrong guess passes verify but data is corrupted; users see gibberish before finding out.