opencli-adapter-author
Use when writing an OpenCLI adapter for a new site or adding a new command to an existing site. Guides end-to-end from first recon through field decoding, adapter coding, and verify. Replaces opencli-oneshot / opencli-explorer. For ad-hoc browser driving (no adapter), see opencli-browser instead; for a top-level orientation to opencli, see opencli-usage.
jackwener · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jackwener/OpenCLI --skill opencli-adapter-author技能说明
name: opencli-adapter-author description: Use when writing an OpenCLI adapter for a new site or adding a new command to an existing site. Guides end-to-end from first recon through field decoding, adapter coding, and verify. Replaces opencli-oneshot / opencli-explorer. For ad-hoc browser driving (no adapter), see opencli-browser instead; for a top-level orientation to opencli, see opencli-usage. allowed-tools: Bash(opencli:), Bash(jsluice:), Read, Edit, Write, Grep
opencli-adapter-author
你是要给一个站点写 adapter 的 agent。这份 skill 目标:简单站点争取 30 分钟内从零到通过 opencli browser verify;复杂、私有协议或写操作站点以证据完整和安全为先,不为了时限猜接口。
全程用现有工具:opencli browser * / opencli doctor / opencli browser init / opencli browser verify。没有新命令。
调试浏览器型 adapter 时,优先直接带上 --trace on --keep-tab true --window foreground。--trace on 每轮都落 trace artifact,summary.md 是失败/成功复盘入口;--keep-tab true --window foreground 让 tab lease 保留且浏览器窗口在前台,方便核对最终页面状态。
前置:看你落在哪
先拿 coverage-matrix.md 快速自测。三个问题:
- 数据在浏览器里看得到吗?(否 → 先解决鉴权)
- 数据是 HTTP/JSON/HTML 吗?(否 → 不在 skill 范围)
- 需要实时推送吗?(是 → 找同数据 HTTP 接口;没有就放弃)
三个都 yes 继续。
顶层决策树
先定 strategy,再写 adapter。 每次进入 Step 3/4 后、写代码前,必须产出一段 strategy note。没有这段 note,不要开始写 clis/<site>/<name>.js。
核心判断不是 "API 比 DOM 高级",而是 数据源有没有外部契约。实测维护成本显示:公开/官方接口最稳;UI/DOM 语义通常也有用户可见契约;站内未文档化 XHR/GraphQL/signature endpoint 最容易漂。不要为了 "API-first" 把稳定的 UI/DOM 实现盲目迁到无契约内部接口。
Strategy: PUBLIC_API | COOKIE_API | PAGE_FETCH | INTERCEPT | DOM_STATE | UI_SELECTOR
Contract: stable | visible-ui | internal-unstable
Evidence:
- observed request/state: <endpoint / state global / UI-only signal>
- auth source: <none / browser cookie / csrf from meta / localStorage / page runtime>
- replay result: <status + content-type + non-empty sample shape>
If Strategy is PAGE_FETCH or INTERCEPT:
- why PUBLIC_API / COOKIE_API are unavailable:
- why UI_SELECTOR / DOM_STATE are not safer:
- why the maintenance cost is acceptable:
Strategy classes:
| Strategy | 契约级别 | 用在什么时候 | 证据要求 |
|---|---|---|---|
PUBLIC_API | stable | 不需要登录,Node-side fetch 直接拿到目标数据 | 200 + JSON/HTML 含目标数据,不是埋点/广告 |
COOKIE_API | stable | Node-side fetch + page.getCookies() / header helper 能拿数据 | cookie/CSRF 来源清楚,replay 非空 |
UI_SELECTOR | visible-ui | publish/upload/click/表单,或页面语义比内部接口更稳 | selector 有语义锚点;错误路径是 typed error |
DOM_STATE | visible-ui | 数据在 hydration state / bootstrap JSON / SSR HTML 里 | state key / script JSON / HTML 结构明确 |
PAGE_FETCH | internal-unstable | 只能在页面上下文 fetch 才能复用 same-origin/session/runtime | opencli browser eval fetch(...) 非空;必须解释为什么避不开内部接口 |
INTERCEPT | internal-unstable | 请求签名复杂,但页面自己能自然发出请求 | 触发 UI 后能截到目标 response;必须解释为什么 UI/DOM 不够 |
选择规则:优先 PUBLIC_API / COOKIE_API。如果 UI/DOM 语义稳定,不要强行升级到 PAGE_FETCH / INTERCEPT。只有公开/官方接口不可用、UI/DOM 无法表达目标数据或操作时,才承担无契约内部接口的维护成本。
实测:PAGE_FETCH / INTERCEPT 的 fix 频率约为 PUBLIC_API 的 7-8 倍,UI_SELECTOR 跟 COOKIE_API 同档。详细 ladder 推导、api_candidates 证据怎么填、booking #1680 等反例见 references/strategy-selection.md。
边界:只复用页面自己已经合法获得的数据/能力。不教破解签名、不绕验证码/风控/访问控制;遇到不可复用签名(如必须由页面 runtime 生成且不能安全抽象)就降级到 UI_SELECTOR / DOM_STATE / INTERCEPT。
START
│
▼
┌──────────────────────────┐
│ opencli doctor 通? │── no ──→ 修桥接(doctor 输出里的提示)
└──────────────────────────┘
│ yes
▼
┌────────────────────────────────────────────────────┐
│ 读站点记忆: │
│ 1. ~/.opencli/sites/<site>/endpoints.json │
│ 2. ~/.opencli/sites/<site>/notes.md │
│ 3. references/site-memory/<site>.md │
└────────────────────────────────────────────────────┘
│ 命中 endpoint + 字段 → 直接跳到【endpoint 验证】(不跳写 adapter!memory 可能过期)
│ 没命中 → 继续
▼
┌──────────────────────────┐
│ 站点侦察(site-recon) │ → Pattern A/B/C/D/E
└──────────────────────────┘
│
▼
┌──────────────────────────┐
│ API 发现(api-discovery)│ §1 network → §2 state → §3 bundle → §4 token → §5 intercept
└──────────────────────────┘
│ 拿到候选 endpoint
▼
┌────────────────────────────────────────────┐
│ 需要 Deep Recon? │ 无文档私有 API / DOM 丢数据 / 写操作 / 证据冲突
│ → references/deep-recon.md │ intent matrix → 因果 diff → 候选账本 → contract gate
└────────────────────────────────────────────┘
│ 候选通过合同证明;不通过则记录拒绝与 lift condition
▼
┌────────────────────────────────────────────┐
│ 验证候选合同(memory 命中也要跑) │── 401/403 ──→ 回到 §4 排 token
│ safe replay;不可 replay 的 read 用自然截获 │── 空/HTML ──→ 回到 site-recon 换 Pattern
│ 数据非空、identity 对、分页/错误语义完整 │── 站点换版 ──→ 标记旧 endpoint,回 api-discovery
└────────────────────────────────────────────┘
│ OK
▼
┌───────────────────────────────────────┐
│ 字段解码(memory 里的 field-map 也要抽查)│ 自解释 → 直接 / 已知代号 → field-conventions / 未知 → decode-playbook
│ 比一条已知字段和网页肉眼值,确认没错位 │
└───────────────────────────────────────┘
│
▼
┌──────────────────────────┐
│ 设计 columns (output) │ 对照 output-design.md 的命名 / 类型 / 顺序
└──────────────────────────┘
│
▼
┌──────────────────────────┐
│ opencli browser init │ 生成 ~/.opencli/clis/<site>/<name>.js 骨架
│ 复制最像的邻居 adapter │
│ 改 name / URL / 映射三处 │
└──────────────────────────┘
│
▼
┌──────────────────────────┐
│ opencli browser verify │── 失败 ──→ autofix skill,用 --trace retain-on-failure 回对应步骤
└──────────────────────────┘
│ 成功
▼
┌──────────────────────────┐
│ 字段 vs 网页肉眼对一遍 │── 数值不对 ──→ 回字段解码
└──────────────────────────┘
│ 对得上
▼
┌──────────────────────────┐
│ 回写 ~/.opencli/sites/ │ endpoints / field-map / notes / fixtures
└──────────────────────────┘
│
▼
DONE
Runbook(一步一步勾选)
[ ] 1. opencli doctor 返回 "Everything looks good"
[ ] 2. 读站点记忆:
[ ] ~/.opencli/sites/<site>/endpoints.json 存在?里面有想要的 endpoint?
[ ] references/site-memory/<site>.md 存在?看"已知 endpoint"节
[ ] 命中后:**跳到第 5(endpoint 验证) + 第 7(字段核对)**,不能直接跳第 9 写 adapter
[ ] memory 写入超过 30 天(看 `verified_at`)→ 当作过期,按冷启动走 Step 3 → 4
[ ] 3. 侦察(site-recon.md):
[ ] **首选**:`op
阅读完整来源 ↗