跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

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 快速自测。三个问题:

  1. 数据在浏览器里看得到吗?(否 → 先解决鉴权)
  2. 数据是 HTTP/JSON/HTML 吗?(否 → 不在 skill 范围)
  3. 需要实时推送吗?(是 → 找同数据 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_APIstable不需要登录,Node-side fetch 直接拿到目标数据200 + JSON/HTML 含目标数据,不是埋点/广告
COOKIE_APIstableNode-side fetch + page.getCookies() / header helper 能拿数据cookie/CSRF 来源清楚,replay 非空
UI_SELECTORvisible-uipublish/upload/click/表单,或页面语义比内部接口更稳selector 有语义锚点;错误路径是 typed error
DOM_STATEvisible-ui数据在 hydration state / bootstrap JSON / SSR HTML 里state key / script JSON / HTML 结构明确
PAGE_FETCHinternal-unstable只能在页面上下文 fetch 才能复用 same-origin/session/runtimeopencli browser eval fetch(...) 非空;必须解释为什么避不开内部接口
INTERCEPTinternal-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
阅读完整来源 ↗