你是要给一个站点写 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 快速自测。三个问题：
三个都 yes 继续。
\n先定 strategy，再写 adapter。 每次进入 Step 3/4 后、写代码前，必须产出一段 strategy note。没有这段 note，不要开始写 clis/<site>/<name>.js。
核心判断不是 \"API 比 DOM 高级\"，而是 数据源有没有外部契约。实测维护成本显示：公开/官方接口最稳；UI/DOM 语义通常也有用户可见契约；站内未文档化 XHR/GraphQL/signature endpoint 最容易漂。不要为了 \"API-first\" 把稳定的 UI/DOM 实现盲目迁到无契约内部接口。
\nStrategy: PUBLIC_API | COOKIE_API | PAGE_FETCH | INTERCEPT | DOM_STATE | UI_SELECTOR\nContract: stable | visible-ui | internal-unstable\nEvidence:\n- observed request/state: <endpoint / state global / UI-only signal>\n- auth source: <none / browser cookie / csrf from meta / localStorage / page runtime>\n- replay result: <status + content-type + non-empty sample shape>\n\nIf Strategy is PAGE_FETCH or INTERCEPT:\n- why PUBLIC_API / COOKIE_API are unavailable:\n- why UI_SELECTOR / DOM_STATE are not safer:\n- why the maintenance cost is acceptable:\nStrategy classes:
\n| Strategy | \n契约级别 | \n用在什么时候 | \n证据要求 | \n
|---|---|---|---|
PUBLIC_API | \nstable | \n不需要登录，Node-side fetch 直接拿到目标数据 | \n200 + JSON/HTML 含目标数据，不是埋点/广告 | \n
COOKIE_API | \nstable | \nNode-side fetch + page.getCookies() / header helper 能拿数据 | \ncookie/CSRF 来源清楚，replay 非空 | \n
UI_SELECTOR | \nvisible-ui | \npublish/upload/click/表单，或页面语义比内部接口更稳 | \nselector 有语义锚点；错误路径是 typed error | \n
DOM_STATE | \nvisible-ui | \n数据在 hydration state / bootstrap JSON / SSR HTML 里 | \nstate key / script JSON / HTML 结构明确 | \n
PAGE_FETCH | \ninternal-unstable | \n只能在页面上下文 fetch 才能复用 same-origin/session/runtime | \nopencli browser eval fetch(...) 非空；必须解释为什么避不开内部接口 | \n
INTERCEPT | \ninternal-unstable | \n请求签名复杂，但页面自己能自然发出请求 | \n触发 UI 后能截到目标 response；必须解释为什么 UI/DOM 不够 | \n
选择规则：优先 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\n │\n ▼\n┌──────────────────────────┐\n│ opencli doctor 通？ │── no ──→ 修桥接（doctor 输出里的提示）\n└──────────────────────────┘\n │ yes\n ▼\n┌────────────────────────────────────────────────────┐\n│ 读站点记忆： │\n│ 1. ~/.opencli/sites/<site>/endpoints.json │\n│ 2. ~/.opencli/sites/<site>/notes.md │\n│ 3. references/site-memory/<site>.md │\n└────────────────────────────────────────────────────┘\n │ 命中 endpoint + 字段 → 直接跳到【endpoint 验证】（不跳写 adapter！memory 可能过期）\n │ 没命中 → 继续\n ▼\n┌──────────────────────────┐\n│ 站点侦察（site-recon） │ → Pattern A/B/C/D/E\n└──────────────────────────┘\n │\n ▼\n┌──────────────────────────┐\n│ API 发现（api-discovery）│ §1 network → §2 state → §3 bundle → §4 token → §5 intercept\n└──────────────────────────┘\n │ 拿到候选 endpoint\n ▼\n┌────────────────────────────────────────────┐\n│ 需要 Deep Recon？ │ 无文档私有 API / DOM 丢数据 / 写操作 / 证据冲突\n│ → references/deep-recon.md │ intent matrix → 因果 diff → 候选账本 → contract gate\n└────────────────────────────────────────────┘\n │ 候选通过合同证明；不通过则记录拒绝与 lift condition\n ▼\n┌────────────────────────────────────────────┐\n│ 验证候选合同（memory 命中也要跑） │── 401/403 ──→ 回到 §4 排 token\n│ safe replay；不可 replay 的 read 用自然截获 │── 空/HTML ──→ 回到 site-recon 换 Pattern\n│ 数据非空、identity 对、分页/错误语义完整 │── 站点换版 ──→ 标记旧 endpoint，回 api-discovery\n└────────────────────────────────────────────┘\n │ OK\n ▼\n┌───────────────────────────────────────┐\n│ 字段解码（memory 里的 field-map 也要抽查）│ 自解释 → 直接 / 已知代号 → field-conventions / 未知 → decode-playbook\n│ 比一条已知字段和网页肉眼值，确认没错位 │\n└───────────────────────────────────────┘\n │\n ▼\n┌──────────────────────────┐\n│ 设计 columns (output) │ 对照 output-design.md 的命名 / 类型 / 顺序\n└──────────────────────────┘\n │\n ▼\n┌──────────────────────────┐\n│ opencli browser init │ 生成 ~/.opencli/clis/<site>/<name>.js 骨架\n│ 复制最像的邻居 adapter │\n│ 改 name / URL / 映射三处 │\n└──────────────────────────┘\n │\n ▼\n┌──────────────────────────┐\n│ opencli browser verify │── 失败 ──→ autofix skill，用 --trace retain-on-failure 回对应步骤\n└──────────────────────────┘\n │ 成功\n ▼\n┌──────────────────────────┐\n│ 字段 vs 网页肉眼对一遍 │── 数值不对 ──→ 回字段解码\n└──────────────────────────┘\n │ 对得上\n ▼\n┌──────────────────────────┐\n│ 回写 ~/.opencli/sites/ │ endpoints / field-map / notes / fixtures\n└──────────────────────────┘\n │\n ▼\nDONE\n[ ] 1. opencli doctor 返回 \"Everything looks good\"\n[ ] 2. 读站点记忆：\n [ ] ~/.opencli/sites/<site>/endpoints.json 存在？里面有想要的 endpoint？\n [ ] references/site-memory/<site>.md 存在？看\"已知 endpoint\"节\n [ ] 命中后：**跳到第 5（endpoint 验证） + 第 7（字段核对）**，不能直接跳第 9 写 adapter\n [ ] memory 写入超过 30 天（看 `verified_at`）→ 当作过期，按冷启动走 Step 3 → 4\n[ ] 3. 侦察（site-recon.md）：\n [ ] **首选**：`opencli browser analyze <url>` 一步拿 pattern + 反爬 + 最近 adapter + next step\n [ ] `analyze` 结论模糊时再手跑：`open` → `wait time 2` (或 `wait xhr <regex>`) → `network`\n [ ] 定 Pattern（A / B / C / D / E）\n[ ] 4. API 发现（api-discovery.md）按 Pattern 选 §：\n [ ] Pattern A → §1 network 精读\n [ ] Pattern B → §2 state 抽取 + §1 深层数据\n [ ] Pattern C → §3 bundle / script src 搜索\n [ ] Pattern D → §4 token 来源 + 降级 §5\n [ ] Pattern E → 找 HTTP 轮询接口；找不到才 §5\n [ ] 无文档 API / DOM 丢数据 / 写操作 / bundle 与 network 冲突 → `deep-recon.md`\n [ ] 写 intent matrix 和明确的 mutation boundary\n [ ] baseline → 单一动作 → 新请求 diff；至少一组 changed-input 对照\n [ ] jsluice 只扩大候选面；候选必须进入 evidence ledger\n [ ] read 候选过 occurrence/replay/completeness/auth/pagination/failure gate\n [ ] write 候选有明确授权、目标绑定、幂等/不确定性与不可自动重试语义\n[ ] 5. 候选合同验证（memory 命中也要重跑）：\n [ ] `PUBLIC_API / COOKIE_API / PAGE_FETCH`：safe replay 跨两个输入返回成功\n [ ] `INTERCEPT`：两次自然页面动作都截到属于目标 identity 的完整响应\n [ ] 响应含目标数据（不是 HTML / 广告 / 推荐侧栏），字段与网页对得上\n [ ] 分页达到 exact limit 或证明 upstream exhaustion；失败不返回 partial\n [ ] write 不自动 replay，必须过 `deep-recon.md` 的额外合同门禁\n[ ] 6. 写 strategy note（写代码前的强制产物）：\n [ ] 从 `PUBLIC_API / COOKIE_API / PAGE_FETCH / INTERCEPT / DOM_STATE / UI_SELECTOR` 选一个\n [ ] 填 Contract：`stable / visible-ui / internal-unstable`\n [ ] 填 Evidence：observed request/state、auth source、replay result\n [ ] 如果选 `PAGE_FETCH` / `INTERCEPT`，必须解释为什么 `PUBLIC_API` / `COOKIE_API` / `UI_SELECTOR` / `DOM_STATE` 都不适合\n [ ] 如果选 `UI_SELECTOR` / `DOM_STATE`，不需要为 \"为什么不是 API\" 过度辩护；只要说明语义锚点和 typed error 路径\n[ ] 7. 字段解码：\n [ ] 自解释 → 直接用 key\n [ ] 已知代号 → field-conventions.md 查表\n [ ] 未知代号 → field-decode-playbook.md（排序键对比 / 结构差分 / 常量排查）\n[ ] 8. 设计 columns（output-design.md）：\n [ ] 命名 camelCase 且对齐邻居 adapter\n [ ] 类型 / 单位 / 百分比格式清楚\n [ ] 顺序：识别列 → 业务数字 → metadata\n[ ] 9. 写 adapter（adapter-template.md）：\n [ ] opencli browser init <site>/<name>\n [ ] 找同站点或同类型最像的 adapter，cp 过来\n [ ] 改 name / URL / 字段映射\n[ ] 10. opencli browser verify <site>/<name>\n [ ] 首轮通过后立刻 `--write-fixture` 生成 `~/.opencli/sites/<site>/verify/<cmd>.json` 种子\n [ ] 手改种子：加 `patterns`（URL / 日期 / ID 格式）+ `notEmpty`（核心字段）+ 收紧 `rowCount`\n [ ] 再跑一次 `opencli browser verify <site>/<name>`，确认 ✓ matches fixture\n[ ] 11. 字段值 vs 网页肉眼比对（别只看 \"Adapter works!\"）\n[ ] 12. 回写站点记忆（**verify 通过 + 肉眼比对对得上之后**，schema 见 `references/site-memory.md`）：\n [ ] `endpoints.json`：以 endpoint 的短名为 key，value = `{url, method, params.{required,optional}, response, verified_at: YYYY-MM-DD, notes}`\n [ ] `field-map.json`：只追加新代号。key = 字段代号，value = `{meaning, verified_at: YYYY-MM-DD, source}`；**已存在的 key 不要覆盖**，有冲突先和网页肉眼值对齐再写\n [ ] `notes.md`：顶部追加一段 `## YYYY-MM-DD by <agent/user>`，写本次写 adapter 时遇到的新坑 / 新结论\n [ ] `verify/<cmd>.json`：**必填。** `opencli browser verify` 的期望值（args / rowCount / columns / types / patterns / notEmpty），Step 10 已经让你生成了，这里只是 checklist\n [ ] `fixtures/<cmd>-<YYYYMMDDHHMM>.json`：仅保存公开数据或可证明完成脱敏的样本；私人邮箱/消息/账号等高敏响应改用合成 fixture，不落盘\n [ ] 原始 dump/capture 只短暂落 `/tmp/` 或受控 cache；安全分级后的长期样本才进 `fixtures/`，任务结束清理原始文件\n[ ] 13. repo 贡献收口（私人 adapter 可跳过）：\n [ ] production-path tests，不只测 parser/helper\n [ ] `npm run typecheck` + focused/site tests + `npm run build`\n [ ] `node dist/src/main.js validate <site>`\n [ ] `npm run check:typed-error-lint` + `npm run check:silent-column-drop`\n [ ] adapter 文档；若 sitemap/site memory 有稳定新知识则同步\n [ ] `git diff --check` + 敏感数据扫描 + 删除 raw capture/cache + 释放 browser session\n [ ] 写操作或私有协议请独立 review exact head 后再合入\n| 卡在 | \n现象 | \n跳去 | \n
|---|---|---|
| Step 4 API 发现 | \nnetwork 空，__INITIAL_STATE__ 也空 | \n§3 bundle 搜 baseURL | \n
| \n | bundle 搜不到 baseURL | \n§5 intercept | \n
| Step 5 endpoint 验证 | \n401 / 403 | \n§4 token 排查 | \n
| \n | 200 但响应是 HTML | \n回 Step 3 换 Pattern 判断 | \n
| \n | 200 但 data: [] 空 | \n参数传错 / 接口换版，回 §1 看 network 里真实请求头 | \n
| Step 7 字段解码 | \n排序键对比推不出 | \nfield-decode-playbook.md §3 结构差分 | \n
| \n | 还推不出 | \n先输出 raw，adapter 跑起来再迭代 | \n
| Step 10 verify 失败 | \nfltt 漏了 / 字段映射错 | \nautofix skill；复现命令加 --trace retain-on-failure | \n
| \n | 某列永远是 null | \n字段路径错了，回 Step 7 | \n
| Step 10 verify fixture mismatch | \n[pattern] row[i] 报错 | \n先肉眼比对网页值；值对 → 是 fixture pattern 太严，放宽；值不对 → 字段映射错 | \n
| \n | [column] missing column \"X\" | \n实际 response 没这列（站点改版 or args 影响）；重新 --update-fixture 或修 adapter | \n
| \n | [type] actual null / undefined | \n字段提取失败，回 Step 7 重抽；临时 fallback 用 union type string\\|null 只有在语义真的可空时用 | \n
| Step 11 数值不对 | \n差 10000 倍 | \n单位不统一（\"万\" vs \"元\"） | \n
| \n | 百分比小 100 倍 | \n响应已是 0.025，不要 × 100 | \n
| 文件 | \n什么时候翻 | \n
|---|---|
references/coverage-matrix.md | \n动手前做\"是否在范围内\"自测 | \n
references/site-recon.md | \nStep 3 定站点类型 | \n
references/api-discovery.md | \nStep 4 找 endpoint | \n
references/deep-recon.md | \n复杂无文档站：动作归因、jsluice 候选扩展、合同证明、读写安全与交付净账 | \n
references/strategy-selection.md | \nStep 6 填 strategy note 之前：契约模型 + 实测 fix 频率 + api_candidates 证据用法 + 反例 | \n
references/field-conventions.md | \nStep 7 查已知字段代号 | \n
references/field-decode-playbook.md | \nStep 7 字段不在词典时 | \n
references/output-design.md | \nStep 8 命名 / 类型 / 顺序 | \n
references/adapter-template.md | \nStep 9 文件结构 + 活例子 convertible.js | \n
references/site-memory.md | \n总览：in-repo 种子 + 本地 ~/.opencli/sites/ 的两层结构 | \n
references/site-memory/<site>.md | \nStep 2 读站点公共知识（eastmoney / xueqiu / bilibili / tonghuashun 已铺） | \n
references/success-rate-pitfalls.md | \nStep 7 / 11 踩坑前翻：11 种\"verify 能过但数据是错的\"静默失败（含 aria-label locale-dependence） | \n
references/jsdom-fixture-pattern.md | \n当 adapter 走 page.evaluate 内 DOM 抽取、且 mocked-evaluate 单测漏 silent bug 时——把 HTML 冻进 clis/<site>/__fixtures__/ 用 JSDOM 跑（含 fixture 创建 mandatory awk 'NF>0' 收紧 + reverse-validate 纪律） | \n
references/typed-errors.md | \n写 func 主体之前必读：5 类 typed error 落点表（ArgumentError / EmptyResultError / CommandExecutionError / AuthRequiredError / TimeoutError）+ 三大 silent anti-pattern（silent-clamp / sentinel-row / generic CliError）的反例修法 | \n
@jackwener/opencli/registry + @jackwener/opencli/errors，不用第三方columns 数组和 func 返回对象 keys 完全对齐（含顺序）columns 任一项重叠（否则 silent-column-drop audit 误判，PR #1329 R1 真踩过；改成专属命名 + push row 时 destructure aliasing）browser: field 决定 func 签名：browser:false → (args)，browser:true → (page, args)。搞反时 args 实际是 debug flag，所有外部参数 silent fallback 到 default（PR #1329 upstream 之前 8 个 non-browser adapter 全踩过这个）references/typed-errors.md 5-classification 抛对应 typed error；不要 silent return []，不要 silent return [{sentinel}]，不要 Math.max/min silent clamp 外部参数~/.opencli/clis/<site>/<name>.js（免 build）；要提 PR 才 copy 到 clis/<site>/<name>.jsdeep-recon.md 的 contract gate；过不了就记录 blocker/lift condition，不生成伪 API 命令。/tmp/ 或受控 cache，任务结束删除。只有通过 site-memory.md 数据分级、准备长期保留的公开/合成/已脱敏样本才进入 ~/.opencli/sites/<site>/fixtures/。严禁在 repo 根目录、clis/<site>/ 或当前工作目录留 .dbg-*.html / raw-*.json / sample.*。clis/<site>/__fixtures__/<command>.html）是上面那条的例外——它是有意 commit 进 repo 的 review artifact，不是临时 dump。但因此 quality bar 要更高：必须按 references/jsdom-fixture-pattern.md 的 5 步做完（含 mandatory awk 'NF>0' 空白行收紧），并 reverse-validate 一道证明 regression guard 真能挂。opencli doctor → 看 notes.md → 搜 autofix skillfield-decode-playbook.md 全三节走完 → 先输出 raw 迭代不要猜。猜错了 verify 能通过但数据是错的，用户看到乱码才发现。
\n","files":[{"path":"references/adapter-template.md","sizeBytes":21668,"isText":true},{"path":"references/api-discovery.md","sizeBytes":15995,"isText":true},{"path":"references/coverage-matrix.md","sizeBytes":5600,"isText":true},{"path":"references/deep-recon.md","sizeBytes":10593,"isText":true},{"path":"references/field-conventions.md","sizeBytes":5308,"isText":true},{"path":"references/field-decode-playbook.md","sizeBytes":7135,"isText":true},{"path":"references/jsdom-fixture-pattern.md","sizeBytes":8011,"isText":true},{"path":"references/output-design.md","sizeBytes":4816,"isText":true},{"path":"references/site-memory/bilibili.md","sizeBytes":3714,"isText":true},{"path":"references/site-memory/eastmoney.md","sizeBytes":3896,"isText":true},{"path":"references/site-memory/gmail.md","sizeBytes":2901,"isText":true},{"path":"references/site-memory.md","sizeBytes":10992,"isText":true},{"path":"references/site-memory/tonghuashun.md","sizeBytes":2492,"isText":true},{"path":"references/site-memory/xueqiu.md","sizeBytes":2875,"isText":true},{"path":"references/site-recon.md","sizeBytes":5383,"isText":true},{"path":"references/strategy-selection.md","sizeBytes":8894,"isText":true},{"path":"references/success-rate-pitfalls.md","sizeBytes":9651,"isText":true},{"path":"references/typed-errors.md","sizeBytes":12910,"isText":true},{"path":"SKILL.md","sizeBytes":20657,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-20T08:08:10.64988Z","sha256":"BBB326F54887486B323738BC649EBFDC04AC22C924B4F170249B66317246DAE4","sizeBytes":84819},"review":null,"source":{"repositoryUrl":"https://github.com/mxyhi/ok-skills","path":"opencli/opencli-adapter-author","license":"Apache-2.0","commit":"7de464066579c539f0ec0342abef83e8a1e994c2","subtreeSha":"15BE45BD0CC545201767B610B14FA4AE83F4D9ACD213FCD5EFE38B49491DCD4A","lastSyncedAt":"2026-09-27T20:55:58.668939Z"},"reviewedAt":"2026-09-20T08:22:30.148948Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/mxyhi/ok-skills/tree/main/opencli/opencli-adapter-author"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mxyhi-ok-skills@llmmart"},{"target":"git","command":"git clone https://github.com/mxyhi/ok-skills.git"}]}