publishport-opencli 1.8.4-pp.1

package/skills/opencli-adapter-author/references/site-memory/tonghuashun.md

@@ -0,0 +1,51 @@
+# tonghuashun（同花顺 / ths）
+
+## 域名
+
+| 用途 | 域名 |
+|------|------|
+| 行情页 / 热榜 | `q.10jqka.com.cn` |
+| 数据中心（多维筛选） | `data.10jqka.com.cn` |
+| 行情推送 | `d.10jqka.com.cn` / `dq.10jqka.com.cn` |
+| 基本面 / F10 | `basic.10jqka.com.cn` |
+| 资讯 / 新闻 | `news.10jqka.com.cn` |
+
+## 默认鉴权
+
+- `Strategy.COOKIE + browser: true`（多数接口有 cookie 风控）
+- `Referer: http://q.10jqka.com.cn/` 是关键 header，很多接口缺它直接返回空
+- 有些 JSONP 接口没 cookie 要求，但 Referer 还是要带
+- 不支持登录态扩展（加密/签名客户端逻辑复杂）
+
+## 已知 endpoint
+
+- `GET d.10jqka.com.cn/v6/line/hs_<code>/01/last1200.js` — K 线（JSONP，返回 `quotebridge_v6_line_...({...})`）
+- `GET q.10jqka.com.cn/thsq/quote/v6/<code>` — 实时行情快照（页面内 XHR）
+- `GET q.10jqka.com.cn/stock/attention/` — 热度榜（HTML，抽表）
+- `GET data.10jqka.com.cn/funds/ggzjl/field/zdf/order/desc/page/1/ajax/1/` — 资金流排行（HTML 表格 + JSONP 混合）
+- `GET news.10jqka.com.cn/tapp/news/push/stock/?tag=&page=1&limit=20` — 快讯
+- `GET data.10jqka.com.cn/ifinance/hotNews/` — 热点新闻
+
+## 字段
+
+见 `../field-conventions.md` 的 tonghuashun 节（`openPrice / closePrice / zdf / hsl / zf` 等）。
+
+数值字段多数是字符串（带百分号或"万"单位），解析时 `parseFloat` 并处理单位。
+
+## 坑 / 陷阱
+
+1. **`Referer` 必须带**，否则 302 到错误页
+2. **多数 JSONP 接口回调名固定**：`quotebridge_v6_...`，adapter 里直接 `.replace(/^[\w_]+\((.*)\)$/, '$1')` 剥壳再 JSON.parse
+3. **HTML 表格接口**（如资金流）：`page.evaluate` 里 `document.querySelectorAll('table tr')` 抽，每列顺序在同类 adapter 之间复用
+4. **`<code>` 格式 `hs_600000`**：hs 是上海，sz 是深圳；港美股前缀不同
+5. **数据中心接口有日期快照切换**：`date=YYYYMMDD` 参数默认当天，历史日期要显式传
+6. **限频特别严**：连续 10 次会跳风控页，adapter 层 1s 间隔起
+7. **响应 gzip 强制**：某些接口不带 Accept-Encoding 会 406，`fetch` 默认 OK，node 原生 http 要显式加
+
+## 可参考的 adapter
+
+| 模板类型 | 参考文件 |
+|---------|---------|
+| 热度榜 | `clis/ths/hot-rank.js`（目前唯一一个，其他待补） |
+
+ths 覆盖度低，新写 adapter 参考 eastmoney 同类型 adapter 的结构，把 URL / 解析逻辑换成 ths 版本。

package/skills/opencli-adapter-author/references/site-memory/xueqiu.md

@@ -0,0 +1,58 @@
+# xueqiu（雪球）
+
+## 域名
+
+| 用途 | 域名 |
+|------|------|
+| 行情 / 搜索 / 关注列表 | `stock.xueqiu.com` / `xueqiu.com` |
+| 动态 / 评论 / 热帖 | `xueqiu.com` |
+| 基金（蛋卷） | `danjuanfunds.com` |
+
+## 默认鉴权
+
+- `Strategy.COOKIE + browser: true`
+- 核心 cookie：`xq_a_token`（匿名也有，登录后含用户身份）
+- `page.evaluate` 里 `fetch(url, { credentials: 'include' })` 带 cookie
+- 浏览器先访问一次 `xueqiu.com` 触发 cookie 下发，再去调接口（否则 `xq_a_token` 不存在 → 400）
+
+## 已知 endpoint
+
+- `GET stock.xueqiu.com/v5/stock/quote.json?symbol=SH600000` — 单股详情
+- `GET stock.xueqiu.com/v5/stock/batch/quote.json?symbol=SH600000,SZ000001` — 批量报价
+- `GET stock.xueqiu.com/v5/stock/chart/kline.json?symbol=SH600000&begin=<ts>&period=day&type=before&count=-100` — K 线
+- `GET stock.xueqiu.com/v5/stock/screener/quote/list.json?market=CN&type=sh_sz` — 排行
+  - 可选：`order_by=percent`（涨幅）/ `volume`（成交量）/ `amount`（成交额）/ `market_capital`
+- `GET stock.xueqiu.com/v5/stock/search.json?keyword=<q>` — 搜索
+- `GET xueqiu.com/statuses/hot/list.json?since_id=-1&max_id=-1&size=20&type=stock` — 热门帖
+- `GET xueqiu.com/statuses/search.json?source=all&q=<q>` — 动态搜索
+- `GET xueqiu.com/service/v5/stock/portfolio/list.json` — 关注组合（需登录）
+- `GET xueqiu.com/v4/statuses/user_timeline.json?user_id=<uid>` — 用户动态
+
+## 字段
+
+字段基本人类可读（`symbol / name / current / chg / percent / volume / amount / market_capital / pe_ttm / pb`），详见 `../field-conventions.md` 的 xueqiu 节。
+
+## 坑 / 陷阱
+
+1. **必须先访问首页**：冷启动直接调 API 会 400 `cookie is invalid`，先 `page.goto('https://xueqiu.com/')` 再 fetch
+2. **`symbol` 前缀硬编码**：SH/SZ/HK/US —— 港股 `00700` 是 `'HK00700'`，美股 `AAPL` 是 `'AAPL'`（无前缀）
+3. **kline 的 `begin` 是毫秒 unix**，不是秒
+4. **screener 的 `type`**：`sh_sz / hk / us` 必传，漏了拿空数组
+5. **评论接口 `comments.json` 要传 `statusId`**，不是 `status_id`
+6. **限频明显**：同 symbol 短时间反复调会 403，adapter 层建议加 300ms 间隔
+7. **蛋卷基金（`danjuanfunds.com`）是独立子品牌**：cookie 域不同，要单独获取
+
+## 可参考的 adapter
+
+| 模板类型 | 参考文件 |
+|---------|---------|
+| 单股 / 批量报价 | `clis/xueqiu/stock.js` |
+| K 线 | `clis/xueqiu/kline.js` |
+| 排行 | `clis/xueqiu/hot-stock.js` |
+| 热帖 / feed | `clis/xueqiu/hot.js` / `feed.js` |
+| 关注 | `clis/xueqiu/watchlist.js` |
+| 搜索 | `clis/xueqiu/search.js` |
+| 评论 | `clis/xueqiu/comments.js` |
+| 基金持仓（蛋卷） | `clis/xueqiu/fund-holdings.js` |
+
+工具：`clis/xueqiu/utils.js` 有 `fetchWithRetry` + symbol normalize，直接用别重写。

package/skills/opencli-adapter-author/references/site-memory.md

@@ -0,0 +1,231 @@
+# Site Memory
+
+站点记忆分两层：**in-repo 种子**（skill 自带的已知站点公共知识）+ **本地工作目录**（每台机器跑过的站点累积产物）。
+
+---
+
+## 两层结构
+
+```
+skills/opencli-adapter-author/references/site-memory/<site>.md
+    — 公共种子。手写 + PR 审核进入。多 agent 共享的第一批起点。
+    — 已铺：eastmoney / xueqiu / bilibili / tonghuashun
+
+~/.opencli/sites/<site>/
+    — 本地累积。agent 跑 adapter 过程里自动写入，跨 session 复用。
+    — 不进 git，不进 PR。
+```
+
+用法：开头先读本地，命中 **不跳写 adapter**，仍要跑 Step 5 endpoint 验证 + Step 7 字段抽查（memory 可能过期或站点换版）；没命中读 in-repo；都没有走完整 recon。
+
+---
+
+## Layer 1 — In-repo 种子（`references/site-memory/<site>.md`）
+
+每个覆盖站点一个 `.md`，结构固定：
+
+```markdown
+# <site>
+
+## 域名
+主 API / 备 API / 登录 / 静态资源
+
+## 默认鉴权
+`Strategy.XXX` + 必需 cookie/header + 获取方式
+
+## 已知 endpoint（选最常用的 5-10 条）
+- `GET <url>` — 返回 X，分页参数 Y
+- ...
+
+## 字段（指向 `field-conventions.md` 的某一节）
+
+## 坑 / 陷阱
+- fltt=2 必传
+- 单位是"万"不是"元"
+- ...
+
+## 可参考的 adapter
+`clis/<site>/<name>.js` × N
+```
+
+审核门槛高，里面写的东西必须是"多数人都会踩到"的共识。一次性试错、站点局部怪癖放 Layer 2。
+
+---
+
+## Layer 2 — 本地工作目录（`~/.opencli/sites/<site>/`）
+
+agent 每跑一次相关 adapter 就可以自动写/读：
+
+```
+~/.opencli/sites/<site>/
+  notes.md               — 累积笔记（时间戳 + 写入人 + 发现）
+  endpoints.json         — 已验证的 endpoint 目录
+  field-map.json         — 字段代号 → 含义（key 为字段代号，value 为 {meaning, verified_at, source}）
+  verify/                — `opencli browser verify` 期望值（值级校验锚点，每个 adapter 一份）
+    <cmd>.json
+  fixtures/              — 完整响应样本（给字段对比 / 离线 replay；**调试时的原始 dump 也只能落在这里或 /tmp/**）
+    <cmd>-<ts>.json
+  last-probe.log         — 最近一次侦察输出（下次接着用）
+```
+
+`verify/` vs `fixtures/` 别混：
+- `verify/<cmd>.json` 是**结构期望**（rowCount / columns / types / patterns / notEmpty），每 adapter 一份、会被 verify 读。
+- `fixtures/<cmd>-<ts>.json` 是**原始响应样本**，给人 / 下一个 agent 做字段比对用，verify 不会读。
+
+### `endpoints.json` 格式（schema 锁死）
+
+key = endpoint 的短名（`clist` / `kline` / `search` 等），不要用全 URL 当 key。
+
+```json
+{
+  "clist": {
+    "url": "https://push2.eastmoney.com/api/qt/clist/get",
+    "method": "GET",
+    "params": {
+      "required": ["fs", "fields"],
+      "optional": ["pn", "pz", "fid", "po", "fltt"]
+    },
+    "response": "data.diff[] 数组",
+    "verified_at": "2026-04-20",
+    "notes": "fltt=2 必传"
+  }
+}
+```
+
+字段说明：
+
+- `url` / `method`：原样存，query string 不入 `url`，都归 `params`
+- `params.required` / `params.optional`：参数名列表。**不存具体值**（值会变，记例子放 `notes`）
+- `response`：一句话写清响应形状入口（`data.diff[] 数组` / `result.data.items` / `纯数组`），而不是把整个响应贴进来
+- `verified_at`：`YYYY-MM-DD`。超过 30 天下次读到当作过期重验
+- `notes`：一两句关键坑（`fltt=2 必传` / `ms 单位 begin` 之类），不要写长文
+
+### `field-map.json` 格式（schema 锁死）
+
+key = 字段代号（`f237` / `f152`），value 三件套：
+
+```json
+{
+  "f237": {
+    "meaning": "convertible premium rate (%)",
+    "verified_at": "2026-04-20",
+    "source": "field-decode-playbook sort-key comparison vs page"
+  }
+}
+```
+
+- `meaning`：人话 + 单位/精度（`%` / `元` / `万元` / `× 10^f152` 等）
+- `verified_at`：`YYYY-MM-DD`
+- `source`：怎么推出来的，让下次能复查（`field-decode-playbook sort-key` / `网页标签对照` / `bundle 搜索 var pricePct =`）
+- **已存在的 key 不要默默覆盖**。有冲突时先用 `fixtures/` 里的真实样本 + 网页肉眼值再确认一遍
+
+### `verify/<cmd>.json` 格式（schema 锁死）
+
+每个 adapter 一份，`opencli browser verify <site>/<cmd>` 会自动读。**没有这份 = verify 只能证"能跑"，证不出数据对**——所以是必填产物。
+
+```json
+{
+  "args": { "limit": 3 },
+  "expect": {
+    "rowCount": { "min": 1, "max": 3 },
+    "columns": ["rank", "tid", "title", "url"],
+    "types": {
+      "rank": "number",
+      "tid": "string|number",
+      "title": "string",
+      "url": "string"
+    },
+    "patterns": {
+      "url": "^https://www\\.1point3acres\\.com/bbs/thread-"
+    },
+    "notEmpty": ["title", "url"]
+  }
+}
+```
+
+字段说明：
+
+- `args`：verify 调 adapter 时要带的参数。支持两种形态：
+  - **对象**：`{ "limit": 3 }` → 展开成 `--limit 3`，用于标准 named flag 适配器
+  - **数组**：`["123", "--limit", "3"]` → **原样**追加到命令后，用于 positional 主语型适配器（`<tid>` / `<url>` / `<query>`）。repo 约定"主语优先 positional"，所以这类适配器只能用数组形态
+- `expect.rowCount.{min,max}`：包含边界。稳定列表接口收紧到 `[min, max]`，动态接口给一个宽区间
+- `expect.columns`：每行必须都有这些 key（严格要求——漏了就 fail）
+- `expect.types`：支持 `|` union（`string|null`）和 `any` 通配。写多少列类型看列的稳定性；波动大的列直接 `any` 比频繁改 fixture 好
+- `expect.patterns`：正则表达式 **字符串**（注意 `\\` 转义）。`null` / `undefined` 会被跳过，不要用正则校验可空字段
+- `expect.notEmpty`：trim 后不能为空的列。这是"adapter 没吃掉核心业务字段"的最后一道保险
+- `expect.mustNotContain`：`Record<col, string[]>`。列值里不允许出现这些子串。用来挡"字段内容污染"——比如 `description` 里混进了 `address:` / `category:` 的邻居节点文字、`title` 前面粘了面包屑前缀。`notEmpty` 挡不住这种软污染
+- `expect.mustBeTruthy`：列数组。列值必须是 JS truthy。用来挡"silent `|| 0` / `|| false` 兜底"——数值列返回 0 / 空字符串 / false 都会被 `notEmpty` 放过，但业务上通常是"没抓到"
+
+### 什么时候手写 vs `--write-fixture` 自动生成
+
+- `--write-fixture` 只是种子：生成 `rowCount.min=1` / `columns` / `types`，**没有** `patterns` / `notEmpty` / `mustNotContain` / `mustBeTruthy`——纯类型 fixture 挡不住数值错位 / 字段污染 / silent fallback。
+- 拿到种子后**必须手改**，四件套一起上：
+  - `patterns`：URL / 日期 / ID 等格式列
+  - `notEmpty`：核心业务字段
+  - `mustNotContain`：描述类文本列容易被兄弟节点污染时，把禁词（`address:` / `category:` 等）列出来
+  - `mustBeTruthy`：数值 / 布尔业务列，挡 `|| 0` / `|| false`
+- adapter 是 positional 主语型（`<tid>` / `<url>` / `<query>`）时，`--write-fixture` 的 `args` 要手写成数组形态。工具不会替你决定形态。
+- 站点换版导致 fixture 过时：`--update-fixture` 覆盖。改之前**先用肉眼核对一次网页值**，别闭着眼把错的响应固化下来。
+- **规避反模式：不要为了让 verify 通过去放松 pattern**。失败的 pattern 说明 adapter 输出有问题，要收紧 adapter，不是收紧 fixture。放松 fixture 等于默认把错数据接受下来。
+
+### `notes.md` 格式
+
+```markdown
+## 2026-04-20 by opencli-user
+写 `convertible.js` 时遇到：
+- f237 推断是溢价率（排序对比法，页面对照）
+- `fltt=2` 不加的话价格是整数 × 10^f152
+- `fs=b:MK0354` 过滤可转债
+```
+
+顶部追加新段落，老的不删。每段有日期 + 写入人。
+
+### `fixtures/<cmd>-<YYYYMMDDHHMM>.json` 格式
+
+一份该 endpoint 的**完整**响应样本。用途：
+
+- 未来字段代号再变时，拿样本和 `field-map.json` 做 regression 对比
+- 站点换版时，新响应和旧 fixture 做 diff 看哪个字段结构变了
+
+**存之前脱敏**：去掉 cookie / token / 登录态相关 header、去掉用户自己的 uid / 用户名 / 手机号 / 邮箱。
+
+---
+
+## runbook 里的读/写时机
+
+```
+Step 2 开始前 → 读  ~/.opencli/sites/<site>/
+                → 读  references/site-memory/<site>.md
+                命中后 → 不跳写 adapter，仍要跑 Step 5 (endpoint 验证) + Step 7 (字段抽查)
+                        verified_at 超 30 天 → 当作过期，按冷启动走 Step 3 → 4
+
+Step 10 verify 首轮通过后 → 写 ~/.opencli/sites/<site>/verify/<cmd>.json
+                            - 先 `--write-fixture` 拿种子，再手改 patterns / notEmpty / rowCount
+                            - 没这份后续 verify 挡不住数据错位，**必填**
+
+Step 11 肉眼对比通过后 → 写 ~/.opencli/sites/<site>/
+                        - endpoints.json：按 schema 追加或更新 verified_at
+                        - field-map.json：只追加新 key，已有的不默默覆盖
+                        - notes.md：顶部追加一段
+                        - fixtures/：脱敏后存一份完整响应样本（区别于 verify/）
+```
+
+**回写是 commit，不是 stash**：不过 Step 10 verify + Step 11 肉眼对比不写，防止把错的映射喂给下一轮。
+
+---
+
+## 不要写进 `~/.opencli/sites/` 的东西
+
+- 真实账户 cookie / token — 不要保存任何鉴权凭据
+- 用户私有数据（返回体里有个人敏感字段的 → 脱敏再存 fixtures）
+- 过期超过 30 天的 last-probe.log（自动清）
+
+## 不要写进 **repo / adapter 目录** 的东西
+
+调试过程里的临时 dump（`.dbg-*.html` / `raw-*.json` / `sample-*` / `trace-*.txt`）**只能**落在 `~/.opencli/sites/<site>/fixtures/` 或系统 `/tmp/`。PR diff 会把 repo 根目录和 `clis/<site>/` 下的文件一起带走——别人 review 时看到一堆调试副产物会很烦。
+
+---
+
+## 没有 site-memory 时
+
+新站点没对应 `.md`，也没本地目录 → 完整走 recon + discovery，跑完直接写 `~/.opencli/sites/<site>/`，后面就有了。

package/skills/opencli-adapter-author/references/site-recon.md

@@ -0,0 +1,134 @@
+# Site Recon
+
+**Layer 1：这是哪种站？** 分类完直接进 `api-discovery.md` 找 endpoint。
+
+本文件**只做分类**，不讲 endpoint 怎么找。
+
+---
+
+## 一步诊断（推荐）
+
+```bash
+opencli browser analyze <url>
+```
+
+返回一份 JSON：
+
+```json
+{
+  "pattern": { "pattern": "A", "reason": "3 JSON XHR responses observed", "json_responses": 3, "auth_failures": 0 },
+  "anti_bot": { "detected": false, "vendor": null, "evidence": [], "implication": "No known anti-bot signatures. Node-side fetch may work; try COOKIE first, fall back to browser-context fetch if blocked." },
+  "initial_state": { "__INITIAL_STATE__": false, "__NUXT__": false, "__NEXT_DATA__": false, "__APOLLO_STATE__": false },
+  "nearest_adapter": { "site": "xueqiu", "example_commands": ["xueqiu search", "xueqiu hot"], "reason": "2 existing adapters target this site — reuse strategy/cookie config" },
+  "recommended_next_step": "Pick the most specific JSON endpoint from `opencli browser network` and try a bare Node fetch with cookies; escalate to browser-context fetch only if blocked."
+}
+```
+
+`analyze` 一步把 Pattern 分类 / 反爬厂商识别 / 最近 adapter 匹配 / 下一步建议给完。直接按 `recommended_next_step` 走，多数情况不用手跑三步诊断。
+
+## 手动三步诊断（analyze 给不出明确结论时）
+
+```bash
+opencli browser open <url>
+opencli browser wait time 2
+opencli browser network
+```
+
+看 `network` 输出判：
+
+| `network` 看到什么 | 站点类型 | 特征 |
+|------------------|---------|------|
+| 大量 `/api/...` JSON 请求，包含目标数据 | **A. SPA / JSON XHR** | React/Vue，数据走 fetch |
+| 有请求但都是广告 / 埋点，无目标数据 | **B. SSR / inline data** | 首屏在 HTML 里，深层再走 API |
+| 完全空 / 只有静态资源 | **C. JSONP / `<script src>` 驱动** | 老金融行情站常见 |
+| 有 API 但 401/403/签名错 | **D. Token / CSRF 鉴权型** | 在 A 基础上加鉴权 |
+| `Content-Type: text/event-stream` / WebSocket 握手 | **E. 流式** | 行情 tick / chat |
+
+分不清时参考下面五节的其他信号。
+
+**数据是 SPA / 异步加载时，`wait time 2` 可能不够**。改用 `opencli browser wait xhr '/api/path-fragment'` 直接等具体接口到场，比盲 `wait time 5` 更稳。
+
+---
+
+## Pattern A — SPA / JSON XHR
+
+**代表**：xueqiu、linear、notion、大多数现代 SaaS
+
+**信号**：
+- URL 一访问就是 `/`，后续数据都在 network tab
+- `document.querySelector('main').childElementCount` 一开始为 0，后被 JS 填充
+- `window.React / window.Vue / window.__REACT_DEVTOOLS_GLOBAL_HOOK__` 存在
+
+**下一步**：`api-discovery.md` §1（network 精读）
+
+**注意 — Pattern A 命中不等于 strategy 选 `PAGE_FETCH`**：
+- 先看 `opencli browser analyze` 输出的 `api_candidates[]`：`verdict=likely_data` 的条目才是真候选；`verdict=noise`（analytics / beacon / personalization）不能算 API 信号
+- booking #1680 反例：17 个 JSON XHR 看起来像 Pattern A，但全是 analytics side-channel，最终走 `DOM_STATE` / `UI_SELECTOR`
+- replay 候选 endpoint 后，按 `strategy-selection.md` 的契约模型选 strategy；`PUBLIC_API` / `COOKIE_API` 都不通才考虑 `PAGE_FETCH`
+
+---
+
+## Pattern B — SSR / inline data
+
+**代表**：bilibili 个人主页、小红书、微博、部分 Next.js / Nuxt 页
+
+**信号**：
+- 第一个请求（`document`）返回的 HTML 里已经含目标数据（`curl <url> | grep <某数字>`）
+- `window.__INITIAL_STATE__` / `window.__NEXT_DATA__` / `window.__NUXT__` 存在
+- 关 JS 仍能看到首屏数据
+
+**下一步**：`api-discovery.md` §2（state 抽取） + §1（深层数据回到 network）
+
+---
+
+## Pattern C — JSONP / `<script src>` 驱动
+
+**代表**：eastmoney、tonghuashun、老一代金融站
+
+**信号**：
+- `network` 空或只有 css/font
+- 页面上肯定有数据（价格、成交量等）
+- `document.querySelectorAll('script[src]')` 里有指向 `push / api / data` 域名的 src
+- 响应是 `jQuery123({...})` 这种回调包裹（JSONP）
+
+**下一步**：`api-discovery.md` §3（bundle / script src 搜索）
+
+---
+
+## Pattern D — Token / CSRF / Bearer
+
+**代表**：Twitter/X、部分企业 SaaS
+
+**信号**：
+- 已经是 Pattern A，但 `fetch(url, {credentials:'include'})` 返回 401/403
+- network 里请求头有 `X-Csrf-Token / Authorization: Bearer / X-Client-Id / X-Workspace-Id` 等自定义字段
+- 401 响应体带 `{"code":"AUTH_REQUIRED","csrf":"..."}` 类提示
+
+**下一步**：`api-discovery.md` §4（token 来源排查） + §5（store action / intercept 降级）
+
+---
+
+## Pattern E — 流式
+
+**代表**：行情 tick、LLM chat
+
+**信号**：
+- `network` 里有 `101 Switching Protocols`（WebSocket 握手）
+- Response headers 含 `Content-Type: text/event-stream`
+- 请求一直 pending 不结束
+
+**下一步**：先找**同数据的 HTTP 轮询接口**（90% 概率有）。真没有再走 intercept 收 N 条。
+
+---
+
+## 识别失败怎么办
+
+诊断信号互相矛盾（比如 network 非空但目标数据不在里面），按优先级硬走：
+
+1. 先当 A，试 `api-discovery.md` §1
+2. 不行当 B，试 §2
+3. 还不行当 C，试 §3
+4. 401 出现了切 D，试 §4
+5. 所有手段都试过，启动 intercept（§5）
+
+不要纠结分类。分类是帮忙定第一步，没命中就按顺序降级。

package/skills/opencli-adapter-author/references/strategy-selection.md

@@ -0,0 +1,169 @@
+# Strategy Selection
+
+SKILL.md 顶层已给出 strategy gate 的 enum、表格和必填字段。本文件展开**为什么**这套 ladder 是按"契约"而不是"接口高度"组织的，以及具体怎么用 `opencli browser analyze` 的 `api_candidates` 证据填 strategy note。
+
+进入条件：你已经按 `site-recon.md` 跑过 `opencli browser analyze`、按 `api-discovery.md` 抓过候选 endpoint。本文件是写 note 之前的最后一站。
+
+---
+
+## 1. 核心模型：契约 vs 无契约
+
+普遍假设 "API > DOM" — **数据不支持**。
+
+837 个内置 adapter 在 30 天观察窗（2026-04-20 → 2026-05-20）按 6 档 strategy 分类后的实测 fix 频率：
+
+| Strategy | 契约级别 | fixes/adapter-year | 解读 |
+|---|---|---|---|
+| `PUBLIC_API` | stable | **1.18** | 一方文档化 API，最稳 |
+| `COOKIE_API` | stable | 2.01 | 官方 web 接口 + 用户 cookie |
+| `UI_SELECTOR` | visible-ui | 1.92 | DOM 的 a11y / semantic 约定也是契约 |
+| `DOM_STATE` | visible-ui | 0.91 (N=11, 小样本) | hydration JSON 半契约 |
+| `PAGE_FETCH` | **internal-unstable** | **8.41** | 站内未文档化 endpoint，最易漂 |
+| `INTERCEPT` | **internal-unstable** | **8.69** | 拦截内部 XHR，签名/字段 silent drift |
+
+含义：
+
+- 选 `PAGE_FETCH` / `INTERCEPT` 的 adapter 平均维护成本是 `PUBLIC_API` 的 **~7-8 倍**
+- `UI_SELECTOR` 在 1.92/year，跟 `COOKIE_API` 同档 — 不是"漂得最快"
+- `DOM_STATE` 在 0.91/year 但 N=11 小样本，按 `UI_SELECTOR` 的近邻处理
+
+**Selection bias caveat**：`PAGE_FETCH` / `INTERCEPT` 高 fix 率部分来自 selection bias — 用这俩的本身就是难站（Twitter GraphQL、xhs signed URL）。但这不改变 practical implication：能用契约层就用契约层，别把稳定的 UI/DOM 实现盲目迁到无契约 endpoint。
+
+数据观察窗局限：30 天窗口是近似不是长尾；`PAGE_FETCH`/`INTERCEPT`/`DOM_STATE` 样本量小（N=32/9/11），二期数据足时会单独评估 `DOM_STATE`。
+
+---
+
+## 2. Ladder 心智模型
+
+```
+契约层（首选，互相平级，按 surface 适配）：
+  PUBLIC_API ─┬─ COOKIE_API ─┬─ UI_SELECTOR ≈ DOM_STATE
+              (read)           (write/click/upload)
+              
+无契约层（被迫才用，必须正向论证 8x 维护成本）：
+  PAGE_FETCH ──── INTERCEPT
+```
+
+注意：**ladder 不是从上往下降级**。`UI_SELECTOR` 不是 `PUBLIC_API` 失败后的"惩罚选项"。如果数据/操作本来就是 UI 表面的事（publish、click、upload、表单），`UI_SELECTOR` 是首选，不需要为"为什么不是 API"过度辩护。
+
+---
+
+## 3. 怎么把 `api_candidates` 转化为 strategy note 证据
+
+`opencli browser analyze <url>` 的输出里 `api_candidates[]` 字段，每条带：
+
+```json
+{
+  "url": "https://example.com/api/list",
+  "status": 200,
+  "contentType": "application/json",
+  "real_data_score": 0.82,
+  "verdict": "likely_data",
+  "reasons": ["json content-type", "non-empty top-level array", "3 business-like keys"],
+  "sample_paths": ["$.data.items:array(20)", "$.data.items[0].title:string"]
+}
+```
+
+按 `verdict` 决策：
+
+| Verdict | 含义 | strategy 信号 |
+|---|---|---|
+| `likely_data` (score ≥ 0.65) | 看起来是业务数据 | 优先 replay 这条做 `PUBLIC_API` / `COOKIE_API` 候选 |
+| `maybe_data` (score 0.35-0.65) | 可能业务数据但有 telemetry / 空字段嫌疑 | replay 必须人工核对字段是不是目标数据 |
+| `noise` | analytics / beacon / personalization | 不是 API 候选；Pattern A 不能基于这类条目成立 |
+| `blocked` (401/403) | auth-gated | 先排 cookie / token / CSRF，**不要**直接退到 `UI_SELECTOR` |
+
+**关键**：`real_data_score` 是证据，不是 strategy。你最终在 strategy note 里仍要写 replay 出来的 status / content-type / sample shape，不是把 score 直接当结论。
+
+### 反例：booking #1680
+
+```
+Site: booking.com (酒店搜索)
+analyze 输出：17 个 JSON XHR，原 Pattern A
+但 api_candidates 全部 verdict=noise（analytics + personalization + experiment）
+```
+
+按 1.0.17 前的旧判定，agent 会按 Pattern A 写 `PAGE_FETCH` adapter，replay 拿到 noise data → adapter silent-fail。**新判定**：`real_data_candidates = 0` → Pattern 落到 C → 提示 SSR HTML scrape → 正确的 strategy 是 `DOM_STATE` / `UI_SELECTOR`。
+
+`browser analyze` 的 `recommended_next_step` 也已更新为 "Inspect api_candidates, then replay the best endpoint" — 不再按 XHR count 推 API。
+
+---
+
+## 4. Strategy note 的关键字段填法
+
+### `Contract` 字段
+
+不是直接从 strategy enum 抄，而是反映"这个 source 有多稳"：
+
+- `stable`：一方文档化 API、官方 web 接口（PUBLIC_API、COOKIE_API）
+- `visible-ui`：用户可见的 DOM、a11y / semantic 标记（UI_SELECTOR、DOM_STATE）
+- `internal-unstable`：站内未文档化 endpoint、签名 / queryId 漂移、字段 silent rename（PAGE_FETCH、INTERCEPT）
+
+### `Evidence` 三行
+
+每行都是事实，不是猜测：
+
+```md
+- observed request/state: GET /api/v2/list (sample_paths: $.data.items:array(20), $.data.items[0].title:string)
+- auth source: browser cookie (sessionid)，无 CSRF
+- replay result: 200 / application/json / 20 items / 非空
+```
+
+`observed request/state` 在 `DOM_STATE` 时写 state global key（`window.__INITIAL_STATE__.feed.items`）；在 `UI_SELECTOR` 时写 selector path 或 a11y locator（`role=list[name="Trending"] > listitem`）。
+
+### `If PAGE_FETCH or INTERCEPT` 三行论证
+
+```md
+Why PUBLIC_API / COOKIE_API are unavailable: <因为 a_bogus signature 必须 page runtime 生成 / 公开 API 缺少 since 字段 / 接口仅在登录态曝露但 cookie 透传会触发 anti-bot>
+Why UI_SELECTOR / DOM_STATE are not safer: <因为数据是无限滚动 + 增量加载，DOM 一次只能拿 1 屏 / 因为目标是 write action，UI 无对应操作>
+Why the maintenance cost is acceptable: <因为业务需求要 raw timeline cursor / 因为已经接受漂时 autofix 流程兜底>
+```
+
+**反模式**：
+
+- ❌ "因为 API 比 DOM 高级" — 不是论证，是假设
+- ❌ "因为 selector 不可靠" — 数据不支持（UI_SELECTOR 跟 COOKIE_API 同档）
+- ❌ "因为我看到 17 XHR" — 不是论证，是 booking #1680 反例
+
+正确论证须基于：endpoint 的**真实**不可达 / 操作语义本质 / 维护成本承担方有明确接收方。
+
+### `If UI_SELECTOR / DOM_STATE`
+
+```md
+- semantic anchor: <a11y role / data-testid / framework-stable class>
+- typed error path: <selector 失配时抛 EmptyResultError / CommandExecutionError>
+```
+
+不需要"why not API"过度辩护。如果你能简短说一句"目标是 publish，没有公开 write API"或"数据在 SSR HTML 直接 inline 了"就够了。
+
+---
+
+## 5. 与其他 reference 的关系
+
+| 文件 | 关系 |
+|---|---|
+| [`api-discovery.md`](./api-discovery.md) | §1-5 是 endpoint 发现的具体方法。本文件指它，但本文件管"用 endpoint 证据填 strategy note"，那边管"怎么先找到 endpoint" |
+| [`site-recon.md`](./site-recon.md) | Pattern A-E 是 site classification。Pattern A 命中 ≠ `PAGE_FETCH` 必然合适 — 还要看 `api_candidates` 是不是 `likely_data` |
+| [`coverage-matrix.md`](./coverage-matrix.md) | 鉴权列已对齐 6 档 strategy enum |
+| [`adapter-template.md`](./adapter-template.md) | 写代码模板。strategy note 应该在打开 template 之前已经定好 |
+| [`success-rate-pitfalls.md`](./success-rate-pitfalls.md) | 11 种 silent failure 模式 — 多数发生在 strategy 选错时（比如把 noise endpoint 当业务数据） |
+
+---
+
+## 6. 反例案例库
+
+### booking #1680 — Pattern A 误判
+
+旧判定按 XHR count 推 Pattern A，实际 17 XHR 全是 analytics / personalization side channel。新 `verdict` 系统能识别为 `noise`，落到 Pattern C → SSR HTML scrape。
+
+### Twitter GraphQL — PAGE_FETCH 高维护成本的典型
+
+`queryId` 每隔 1-2 月漂一次，字段名 silent rename（`legacy.user_screen_name` → `core.user.screen_name`）。30 天 9 个 fix PR。`Why the maintenance cost is acceptable` 的合理论证：业务需要 raw timeline cursor、autofix 流程已接住、fixed 时间窗口可控。
+
+### xiaohongshu signed URL — INTERCEPT 必要场景
+
+`a_bogus` signature 由 page runtime 即时生成，无法在 Node 端复现也不能拷贝 cookie 跨 origin replay。合理 strategy 是 `INTERCEPT`：触发 UI 让页面自己发请求，从 response 取数据。
+
+### weread-official — PUBLIC_API 首选
+
+WeRead 官方 Agent Gateway 有 Bearer auth + 文档化 schema。一方契约 + 不依赖 cookie / 不依赖浏览器 — 最理想的 strategy。维护成本最低。