@agentrhq/webcmd 0.1.2 → 0.2.0

package/skills/webcmd-adapter-author/references/api-discovery.md

@@ -1,295 +1,186 @@
 # API Discovery
 
-**Layer 2：这个站的目标数据 endpoint 是什么？** 已经分完类（`site-recon.md`）再进来。
+Use this after `site-recon.md` chooses Pattern A/B/C/D/E. The output of this file is a candidate endpoint plus evidence for the strategy note.
 
-五种手段。按优先级降级用，命中即走。
+Keep `--trace on --keep-tab true --window foreground` enabled while exploring browser-backed sites.
 
----
+## Section 0 - Preflight Red Lines
 
-## §0 进入 §1 之前：先看两条红线
+Read these before endpoint verification. If you miss either one, you can spend the rest of discovery testing the wrong thing.
 
-这两条不看清楚，后面的 endpoint 验证会一直在错的前提下兜圈子。
+### 0.1 Anti-bot and WAF gates decide whether Node fetch is valid
 
-### 0.1 反爬厂商 → 决定 fetch 能不能从 Node 走
+`webcmd browser analyze <url>` reports the `anti_bot` field. You can also inspect cookies and the response body manually.
 
-`webcmd browser analyze <url>` 的 `anti_bot` 字段给答案；手查看 cookies 也行：
+| Cookie or body signal | Vendor | Bare Node fetch or curl result | Strategy |
+| --- | --- | --- | --- |
+| `acw_sc__v2`, `acw_tc`, `ssxmod_itna`; body contains `arg1 = '32-HEX'` or `/ntc_captcha/` | Aliyun WAF | Slider HTML instead of real data | Verify the endpoint in browser context first; HTML-style cookie adapters can still end with Node-side fetch plus `page.getCookies()` |
+| `__cf_bm`, `cf_clearance`, `__cfduid`; body contains `Cloudflare Ray ID` or `Checking your browser` | Cloudflare | TLS or browser fingerprint is rejected | Use a browser/session-aware probe first, then choose the adapter fetch route from `adapter-template.md` |
+| `_abck`, `bm_sz`, `bm_sv` | Akamai | Often blocked even with cookies | Use a browser/session-aware probe first |
+| Body contains `geetest` or `gt_captcha` | Geetest | Slider or puzzle challenge; no programmatic solution in this skill | Out of scope; stop or use a user-visible UI strategy |
 
-| cookie / body 信号 | 厂商 | 裸 Node fetch / curl 结果 | 策略 |
-|------------------|------|-----|-----|
-| `acw_sc__v2` / `acw_tc` / `ssxmod_itna`；body 含 `arg1 = '32-HEX'` 或 `/ntc_captcha/` | **Aliyun WAF** | 返回 slider HTML，不是真数据 | 先在浏览器上下文里验证 endpoint；HTML 型 COOKIE adapter 最终仍走 Node-side fetch + `page.getCookies()` |
-| `__cf_bm` / `cf_clearance` / `__cfduid`；body 含 `Cloudflare Ray ID` / `Checking your browser` | **Cloudflare** | TLS 指纹被标记，失败 | 同上：先 browser-context probe，最终 adapter 仍按模板选 fetch 路线 |
-| `_abck` / `bm_sz` / `bm_sv` | **Akamai** | 即使带 cookie 也常被挡 | 同上 |
-| body 含 `geetest` / `gt_captcha` | **Geetest** | 滑块/拼图，程序无解 | 超出 skill 范围，放弃或 UI 策略 |
+Rule: if any of these anti-bot or WAF signals appear, do not use bare Node fetch as endpoint verification. First prove the endpoint from the browser context or from a page on the target origin. After that, choose the final adapter strategy normally: JSON browser APIs may use `page.fetchJson()`, while HTML-style cookie adapters should keep using Node-side `fetch` with cookies read through `page.getCookies()`.
 
-**规则**：看到上面四种任一个，先不要拿**裸** Node fetch 做 endpoint 验证。先用 browser-context probe 或目标 origin 页面确认接口能通；最终 adapter 的 fetch 路线仍按 `adapter-template.md` 选，HTML 型 COOKIE adapter 继续走 Node-side fetch + `page.getCookies()`。
+### 0.2 Cross-subdomain fetch is CORS-blocked by default
 
-### 0.2 跨 subdomain = CORS 默认关
+For example, a page on `jobs.51job.com` fetching an API on `cupid.51job.com` will usually hit a CORS preflight unless the API returns `Access-Control-Allow-Origin`.
 
-`jobs.51job.com` 页面 fetch `cupid.51job.com` 的 API，默认会被浏览器 CORS 预检挡住——除非目标接口回了 `Access-Control-Allow-Origin`。
-
-判断：
-
-```bash
-webcmd browser eval "fetch('https://<target-subdomain>/api/...', {credentials:'include'}).then(r=>r.status).catch(e=>'cors:'+e.message)"
-```
-
-- 返回 status 数字 → CORS 通，继续
-- 返回 `cors:...` 或 `TypeError: Failed to fetch` → 挡住了
-
-**挡住时**：不要把 `credentials:'include'` 当万能药——这只解决"带 cookie"，不解决"跨 origin"。降级路径：
-
-1. 换同 origin 的 endpoint（同一个 subdomain 下的 API 往往更宽松）
-2. 用 `webcmd browser open https://<target-subdomain>/`，让页面在目标 subdomain 本身打开，再 fetch 相对路径
-3. 真跨域且无替代 → 走 `§5 intercept`，从页面自身发的请求里抓响应
-
----
-
-## §1 network 精读（首选，Pattern A / D 命中率最高）
-
-### 拿候选
+Probe it explicitly:
 
 ```bash
-webcmd browser network
+webcmd browser eval "fetch('https://<target-subdomain>/api/...', { credentials: 'include' }).then(r => r.status).catch(e => 'cors:' + e.message)"
 ```
 
-默认输出是 JSON，每个候选都带：
-- `key` — 稳定引用（GraphQL 的 `operationName` 或 `METHOD host+pathname`）
-- `shape` — response body 的路径→类型映射（不含原 body，省 token）
-- `status / url / method / ct / size`
-
-静态资源 / 埋点 / 追踪默认已过滤。默认会保留 JSON / XML / plain text / `text/javascript` 这类 API 响应；如果你确定浏览器 DevTools 里有目标请求但这里缺失，用 `--all` 查一遍是否被 content-type 或 URL 噪音过滤挡掉。
-
-如果是冷启动，先看 `webcmd browser analyze <url>` 里的 `api_candidates`：
-
-- `verdict: "likely_data"`：优先 replay 这条，拿 status / content-type / sample shape 填 strategy note
-- `verdict: "maybe_data"`：可以试，但必须人工核对字段是否是目标业务数据
-- `verdict: "noise"`：多半是 analytics / beacon / personalization，不要因为 XHR 数量多就判 Pattern A
-- `verdict: "blocked"`：401/403；先排 cookie / token / CSRF，别直接退到 selector
-
-`real_data_score` 是证据，不是自动 strategy。最终仍要在 strategy note 里写 replay 结果和降级理由。
+- A numeric status means CORS allows the request.
+- `cors:...` or `TypeError: Failed to fetch` means the browser blocked it.
 
-### 按 shape 初筛
+When it is blocked, `credentials: include` is not a CORS fix across subdomains. It only asks the browser to send cookies; it does not grant cross-origin permission. Use this fallback order:
 
-挑 `key` 里含业务词（`list / detail / Timeline / User / Tweets / Quote`）的优先看 `shape`：
+1. Prefer a same-origin endpoint on the current subdomain.
+2. Open a page on the target subdomain with `webcmd browser open https://<target-subdomain>/`, then fetch relative paths from that origin.
+3. If the data is truly cross-origin and there is no same-origin alternative, use Section 5 intercept and capture the response from the page's own request.
 
-- `$.data` 是 `object` 且下面出现 `array(N)` / `total` / `page` → 基本是它
-- 路径里出现 `nickname / avatar / title / price / tweets / items` → 就是它
-- shape 只有 `$: string` 或全是 HTML 噪音 → 下一条
+## Section 1 - Network Deep Read
 
-### 按期望字段反查（`--filter`）
-
-已经知道目标 body 该含哪些字段就直接让 CLI 把列表筛到只剩候选，不用自己 scroll 翻 shape：
-
-```bash
-webcmd browser network --filter author,text,likes
-```
-
-- 字段以英文逗号分隔；AND 语义，必须每个字段都作为 shape 路径的**任意一段**出现才保留（`$.data.items[0].author` 命中 `author`、`items`、`data` 都算）
-- 区分大小写（JSON key 本来就 case-sensitive）
-- 输出 envelope 新增 `filter` / `filter_dropped`，`count` 是过滤后数量
-- 0 命中不是 error，返回 `entries: []`；说明字段组合不对，换一组或去掉约束再试
-- 不要跟 `--detail` 一起用——`--detail` 按 key 取单条、`--filter` 是列表缩窄，组合会报 `invalid_args`
-- 空值 / `,,,` → `invalid_filter` 结构化错误
-- capture 依然按全量持久化，后续 `--detail <key>` 能找到被过滤掉的条目
-
-### 拉完整 body
-
-候选定了再拉完整 body（by key，不是 index — 数组顺序会随每次 capture 变）：
+Use for Pattern A and for deeper data in Pattern B.
 
 ```bash
-webcmd browser network --detail <key>
+webcmd browser open <url> --trace on --keep-tab true --window foreground
+webcmd browser wait xhr '<path-or-domain-fragment>'
+webcmd browser network --format json
 ```
 
-capture 会持久化到 `~/.webcmd/cache/browser-network/<session>.json`（默认 TTL 24h），所以 `--detail` 即使跨多条其他命令也还在。
-
-### 关键 request headers
-
-`browser network` 当前只抓响应（body + status + ct），抓不到请求头。要看请求头就在 DevTools Network 面板里点这条 request，或用 `browser eval` 手动 `fetch(url)` 复现一次观察浏览器发出去的头：
-
-| 看到 | 含义 | 对应策略 |
-|------|------|---------|
-| 只有 `Cookie` | 登录态靠 cookie | `Strategy.COOKIE` |
-| `Authorization: Bearer xxx` | token 鉴权 | 先找 token 来源（localStorage / cookie / bundle 硬编码） |
-| `X-Csrf-Token: xxx` 同时存在 cookie 里 | CSRF 防护 | `Strategy.COOKIE`，从 cookie 读 ct0 类字段拼头 |
-| `X-Workspace-Id / X-Tenant-Id` | 多租户业务头 | 先调 `/workspaces` 拿 ID，缓存下来 |
-| 啥自定义头都没有 | 匿名接口 | `Strategy.PUBLIC` |
-
-### 触发懒加载接口
-
-默认页加载完后滚动 / 点击才会出的接口不在首屏 network 里。需要：
-
-```bash
-# 滚到底（虚拟列表）
-webcmd browser eval "window.scrollTo(0, document.body.scrollHeight)"
-webcmd browser wait time 2
-webcmd browser network
-
-# 点某个按钮
-webcmd browser click <N>
-webcmd browser wait time 2
-webcmd browser network
-```
+Inspect each candidate:
 
----
+- URL and method.
+- Status code and content type.
+- Query/body params.
+- Request headers that appear auth-related.
+- Response shape and whether it includes target data.
+- Whether data is user-visible, not analytics, ads, experiments, or personalization noise.
 
-## §2 `__INITIAL_STATE__` / inline HTML（Pattern B）
+Reject candidates that only contain telemetry, unrelated recommendations, beacons, or layout metadata.
 
-首屏数据常挂在这几个全局变量上：
+Replay directly when possible:
 
 ```bash
-webcmd browser eval "Object.keys(window).filter(k=>k.startsWith('__'))"
+webcmd browser eval "await fetch('<url>', { credentials: 'include' }).then(r => r.text())"
 ```
 
-命中的常见名：
-
-| 全局 | 框架 |
-|------|-----|
-| `__NEXT_DATA__` | Next.js |
-| `__NUXT__` | Nuxt.js |
-| `__INITIAL_STATE__` | 自定义 Vue / React SSR |
-| `__PRELOADED_STATE__` | Redux SSR |
-| `__REMIX_CONTEXT__` | Remix |
+If Node-side replay works without page runtime state, prefer `PUBLIC_API` or `COOKIE_API`. If the endpoint only works in page context, document why before selecting `PAGE_FETCH`.
 
-取数据：
+## Section 2 - State Extraction
 
-```bash
-webcmd browser eval "JSON.stringify(window.__NEXT_DATA__).slice(0, 3000)"
-```
+Use for Pattern B.
 
-**关键**：inline state 只覆盖首屏的一部分（通常是 SEO 相关字段）。分页 / 评论 / 懒加载还是得回 §1 抓 API。
+Look for:
 
-把首屏 state 当作 adapter 的兜底数据源：公开访问时 state 里有 → 直接 parse；数据更新快 / 分页 → 回到 API。
+- `window.__INITIAL_STATE__`
+- `window.__NEXT_DATA__`
+- `window.__NUXT__`
+- JSON in `<script type="application/json">`
+- SSR HTML structures containing visible values
 
----
-
-## §3 JS bundle / script src 搜索（Pattern C，也是 A/D 的降级）
-
-### 扫 script src
+Commands:
 
 ```bash
-webcmd browser eval "[...document.querySelectorAll('script[src]')].map(s=>s.src).filter(s=>!/\\.(css|png|jpg|svg|woff|mp4)$/.test(s)&&!/googletagmanager|crazyegg|sentry|doubleclick|amazon-adsystem|cloudflare/.test(s))"
+webcmd browser eval "Object.keys(window).filter(k => /STATE|DATA|NUXT|APP/i.test(k))"
+webcmd browser eval "document.querySelectorAll('script[type=\"application/json\"], script:not([src])').length"
+webcmd browser eval "document.body.innerText.slice(0, 2000)"
 ```
 
-看结果里的 hostname：
-
-- 明显像 API 的域名（`api.xxx / push.xxx / data.xxx / gateway.xxx`）→ 直接去试
-- 主 bundle（`main.js / app.js / index.xxx.js`）→ 继续下一步下载 bundle 搜 baseURL
+Use `DOM_STATE` when the target data is stable in state or HTML. If only a deeper interaction loads the target data, return to section 1.
 
-### 搜 bundle 里的 baseURL
+## Section 3 - Bundle / Script Src Search
 
-```bash
-webcmd browser eval "(async()=>{const s=[...document.querySelectorAll('script[src]')].map(e=>e.src).find(s=>/main|app|index|bundle|chunk/.test(s));if(!s)return'no bundle';const t=await fetch(s).then(r=>r.text());const patterns=['baseURL','baseUrl','BASE_URL','apiHost','apiBase','API_HOST','API_BASE'];const hits=[];for(const p of patterns){let i=-1;while((i=t.indexOf(p,i+1))>-1&&hits.length<5)hits.push(t.slice(Math.max(0,i-5),i+80));}return hits})()"
-```
-
-命中 `baseURL:"https://api.foo.com"` 直接拿 host 拼 endpoint。
-
-### 直接试候选 endpoint
+Use for Pattern C.
 
-像 eastmoney 这种经验 endpoint 可以直接喂：
+Collect script sources:
 
 ```bash
-webcmd browser eval "fetch('https://push2.eastmoney.com/api/qt/clist/get?fs=m:1+t:2&pn=1&pz=5&fltt=2&fid=f3&po=1&fields=f2,f3,f12,f14').then(r=>r.json())"
+webcmd browser eval "[...document.querySelectorAll('script[src]')].map(s => s.src)"
 ```
 
-200 且数据对得上就认。
+Look for domains or paths containing:
 
-### URL 后缀探测
+- `api`
+- `data`
+- `search`
+- `graphql`
+- `query`
+- `feed`
+- `suggest`
+- `push`
 
-有些站直接在 URL 加 `.json` 就是 REST：
+For JSONP or callback-wrapped payloads, verify that stripping the wrapper yields parseable JSON:
 
-- `https://www.reddit.com/r/rust.json` — Reddit 全覆盖
-- `https://xueqiu.com/S/SH600000.json` — 雪球部分页
-
-```bash
-# 当前页加 .json 试
-webcmd browser eval "fetch(location.pathname.replace(/\\/$/,'')+'.json').then(r=>r.ok?r.json():'no')"
+```js
+const raw = await fetch(url).then((r) => r.text());
+const json = JSON.parse(raw.replace(/^[\w$.]+\((.*)\);?$/, '$1'));
 ```
 
----
-
-## §4 Token / CSRF 来源排查（Pattern D）
+If a script points to bundle code rather than data, search for base URLs, route names, and query keys. Prefer endpoints with stable names and visible data over minified private internals.
 
-已经在 network 里看到请求带自定义头，怎么拿到那个值：
+## Section 4 - Token / Header Source
 
-### Cookie 里
+Use for Pattern D.
 
-```bash
-webcmd browser eval "document.cookie.split('; ').reduce((o,x)=>{const[k,v]=x.split('=');o[k]=v;return o},{})"
-```
-
-常见 token cookie 名：`ct0`（Twitter CSRF）、`xq_a_token`（雪球）、`SESSDATA`（B 站）、`_csrf / csrfToken`（通用）。
-
-**`document.cookie` 只能看到 non-HttpOnly 的 cookie。** 上面那条命令侦察阶段够用，真写 adapter 时 auth 经常是 HttpOnly，一定要用 `page.getCookies(...)` 从 CDP cookie jar 拿——见 `adapter-template.md` 的 "COOKIE adapter 骨架"。
+Find token sources in this order:
 
-论坛 / BBS 引擎（Discuz!X / phpBB / vBulletin）还多一坑：auth cookie 设在**根域** `.example.com`（不是 `www.example.com`），且 HttpOnly。要查 `{ domain: '.<root>' }` **和** `{ domain: 'www.<root>' }` 两次，否则 adapter 在有 cookie 的前提下仍然 401。
+1. Network request headers.
+2. Cookies available through `page.getCookies()`.
+3. Meta tags or inline scripts.
+4. Global state.
+5. Same-origin bootstrap endpoint.
 
-### localStorage / sessionStorage 里
+Useful probes:
 
 ```bash
-webcmd browser eval "Object.keys(localStorage).map(k=>k+' => '+localStorage.getItem(k).slice(0,50))"
+webcmd browser eval "document.querySelector('meta[name=\"csrf-token\"]')?.content"
+webcmd browser eval "Object.keys(localStorage)"
+webcmd browser eval "Object.keys(sessionStorage)"
+webcmd browser eval "document.cookie"
 ```
 
-找 `token / auth / jwt / bearer` 关键字。
+Rules:
 
-### Bundle 硬编码
+- It is fine to reuse cookies and CSRF values the page already has.
+- Do not teach bypassing CAPTCHA, risk controls, or access controls.
+- Do not reverse engineer private signatures when the only path is static secrets or brittle bundle logic.
+- If token extraction is fragile but the user-visible page can perform the action, choose `UI_SELECTOR` or `INTERCEPT`.
 
-有些站的 Bearer 是全站一个常量（Twitter 的匿名 Bearer）。在 bundle 里搜：
-
-```bash
-webcmd browser eval "(async()=>{const s=[...document.querySelectorAll('script[src]')].map(e=>e.src).find(s=>/main|app|bundle/.test(s));const t=await fetch(s).then(r=>r.text());const m=t.match(/Bearer\\s+[\\w-]{20,}/g);return m?.slice(0,3)||'not found'})()"
-```
+## Section 5 - Store Action / Intercept Fallback
 
-### Store action 绕签名
+Use only after public API, cookie API, DOM state, and UI selector options are insufficient.
 
-Vue + Pinia / Redux / React Context 有时直接调 store method 能绕过签名逻辑（method 内部会自己拿签名再发请求）：
+For page actions:
 
 ```bash
-# Pinia
-webcmd browser eval "typeof __pinia !== 'undefined' ? Object.keys(__pinia.state.value) : 'no pinia'"
-
-# 直接调 store action（每个站点具体 action 名要查）
-webcmd browser eval "window.__pinia.state.value.someStore.someMethod({...})"
+webcmd browser trace start
+webcmd browser click '<selector>'
+webcmd browser wait xhr '<target-fragment>'
+webcmd browser network --format json
 ```
 
----
-
-## §5 installInterceptor（最后降级）
+Choose `INTERCEPT` when:
 
-所有手段都试过还拿不到请求签名时，让页面自己发请求，adapter 做 MITM 拦截响应：
-
-```javascript
-// func 里
-await page.evaluateWithArgs(installInterceptorCode, {
-  config: { domain: 'api.xxx.com', path: '/foo' },
-});
-await page.goto('https://xxx.com/trigger-page');
-// 等页面自己发那条请求
-const intercepted = await page.evaluate('window.__webcmd_intercepted');
-return intercepted.response;
-```
+- The page naturally sends the target request.
+- The response contains the target data.
+- You can trigger the request with a stable UI action.
+- You can explain why replay and DOM extraction are not enough.
 
-代价是要等页面真的触发请求，慢、不稳。只在 §1-4 都不行时用。
+Choose `UI_SELECTOR` when the operation itself is the user-visible contract, such as clicking, publishing, uploading, or filling a form.
 
----
+## Endpoint Verification Checklist
 
-## 诊断不出来怎么办
+Before writing adapter code:
 
-按这个顺序试到命中：
-
-```
-§1 network ──→ 命中？yes → 走
-      │        no
-      ↓
-§2 state  ──→ 命中？yes → 走
-      │        no
-      ↓
-§3 bundle ──→ 命中？yes → 走
-      │        no
-      ↓
-§4 token  ──→ 401 解除？yes → 走
-      │        no
-      ↓
-§5 intercept → 让页面自己发
-```
+- [ ] Candidate response is 200.
+- [ ] Candidate response contains target data.
+- [ ] Candidate is not analytics, ads, or telemetry.
+- [ ] Auth source is documented.
+- [ ] Replay method is documented.
+- [ ] Strategy note is written.
+- [ ] At least one field value is compared against the visible page.
 
-**四条都命不中的站（罕见）**：多半是视觉化渲染（canvas / webgl），数据不以 HTTP/JSON 形式存在。这种放弃或换源。
+If any item fails, return to `site-recon.md` or the earlier section of this file.

package/skills/webcmd-adapter-author/references/coverage-matrix.md

@@ -1,81 +1,47 @@
 # Coverage Matrix
 
-skill 明确承诺能搞定什么、搞不定什么。动手前先看一眼这张表，判断目标站落在哪一格。
+Use this file before writing an adapter. It decides whether the task is inside the Webcmd adapter-authoring lane.
 
-**状态标记**：
-- ✅ **已验证**：有可跑通的真实 adapter / dry-run 证据
-- 🟡 **已列招但未硬跑**：文档把方法写全了，但这一版没拿真实站点跑过；第一次遇到时按文档走，踩坑回来补 `site-memory`
-- ❌ **不支持**：skill 明确不碰，走绕开方案
+## Supported
 
----
+| Scenario | Good fit | Notes |
+| --- | --- | --- |
+| Public JSON or HTML endpoint | Yes | Prefer `PUBLIC_API` when Node-side `fetch` can replay it without auth. |
+| Cookie-backed JSON or HTML endpoint | Yes | Use `COOKIE_API` when cookies, CSRF, or headers can be sourced from the page safely. |
+| Visible UI actions | Yes | Use `UI_SELECTOR` for clicks, forms, uploads, and other user-visible workflows. |
+| SSR or hydration state | Yes | Use `DOM_STATE` when target data appears in HTML, script JSON, or bootstrap state. |
+| Page-context fetch | Conditional | Use `PAGE_FETCH` only when same-origin/session/runtime state makes Node-side replay impossible. |
+| Natural page request interception | Conditional | Use `INTERCEPT` when the page can naturally issue a signed request and UI/DOM is not enough. |
+| JSDOM fixture regression | Yes | Use when DOM extraction has already produced a silent bug or mocked evaluate is too weak. |
 
-## 支持（skill 里有对应的招）
+## Unsupported
 
-| 维度 | 支持 | 状态 | 走哪节 |
-|------|------|------|-------|
-| 页面形态 | 列表页 / 排行页 | ✅ | `adapter-template.md`（convertible.js / rank.js 类） |
-| | 详情页（单对象） | ✅ | `adapter-template.md`（stock.js / holders.js 类） |
-| | 时间序列（K 线 / 分钟线） | ✅ | `adapter-template.md`（kline.js） |
-| | 嵌套列表（列表里含列表） | 🟡 | `adapter-template.md` + `output-design.md` 打平规则 |
-| 站点类型 | SPA（React/Vue，JSON XHR） | ✅ | `site-recon.md` Pattern A + `api-discovery.md` §network |
-| | SSR（HTML with inline data） | 🟡 | `site-recon.md` Pattern B + `api-discovery.md` §state |
-| | JSONP / push/script[src] | ✅ | `site-recon.md` Pattern C + `api-discovery.md` §bundle（eastmoney / tonghuashun 已覆盖） |
-| | SPA + 独立 BFF domain | 🟡 | `api-discovery.md` §bundle §suffix |
-| Strategy（详见 `strategy-selection.md`） | 裸 `fetch()` 拿到 | ✅ | `PUBLIC_API`（一方文档化接口，最稳：fixes/adapter-year=1.18） |
-| | cookie 透传 | ✅ | `COOKIE_API`（官方 web 接口 + 用户登录态，fixes/adapter-year=2.01） |
-| | publish / upload / click / 表单 | ✅ | `UI_SELECTOR`（DOM 的 a11y / semantic 也是契约，fixes/adapter-year=1.92） |
-| | hydration state / inline JSON | 🟡 | `DOM_STATE`（fixes/adapter-year=0.91 小样本 N=11，按 UI_SELECTOR 同档） |
-| | page-context fetch（CORS / same-origin runtime） | 🟡 | `PAGE_FETCH`（无契约内部 endpoint，fixes/adapter-year=8.41，必须正向论证） |
-| | 触发 UI 拦截响应 | 🟡 | `INTERCEPT`（无契约，fixes/adapter-year=8.69，必须正向论证） |
-| 字段形态 | 自解释（`title / price / current`） | ✅ | 直接映射 |
-| | 已登记代号 | ✅ | `field-conventions.md` 查表 |
-| | 未登记代号 | 🟡 | `field-decode-playbook.md` 排序键对比法 |
-| | 嵌套路径 `data.diff[].f2` | ✅ | `field-decode-playbook.md` §3 结构差分 |
-| 分页 | `page` / `pn` / `pageNum` | ✅ | `adapter-template.md` 例子 |
-| | `cursor` / `next_cursor` | ✅ | adapter 里 while 循环，收集到 limit |
-| | `offset` / `start` | ✅ | 同上 |
-| 响应格式 | JSON | ✅ | 默认 |
-| | JSONP（`?callback=`） | ✅ | 去掉 callback 参数直接请求，返回仍是 JSON 字符串包裹 |
-| | CSV 字符串（eastmoney kline） | ✅ | `response.split(',')` 按列序解 |
-| | HTML 表格（tonghuashun） | 🟡 | `page.evaluate` 里用 `querySelectorAll` 拿 |
+| Scenario | Reason | Alternative |
+| --- | --- | --- |
+| First-time login token acquisition | Requires the user to enter real credentials | Ask the user to log in manually in the browser session, then reuse cookies. |
+| CAPTCHA or heavy anti-bot bypass | This would bypass access controls or risk systems | Stop or choose another source with the same data. |
+| Client crypto or private signing secrets | Requires reverse engineering and ongoing bundle tracking | Prefer another endpoint; if unavoidable, let the page issue the request and use `INTERCEPT`. |
+| Pure WebSocket stream | State management is too high for this skill | Look for an HTTP polling endpoint with the same data. |
+| Private binary protocol | Not HTTP/JSON/HTML | Out of scope. |
+| Canvas-only visual chart | Data is only in the render layer | Find the backing API; if none exists, stop. |
+| Strict rate limit | Adapter authoring cannot solve platform quota policy | Add adapter-level concurrency limits/backoff, but do not brute force. |
 
-🟡 的维度意思：方法在文档里，但这一版没拿真实站点跑过端到端。第一次遇到时按文档走，遇到和文档不一致的地方记到 `~/.webcmd/sites/<site>/notes.md`，下一次再打开就是 ✅。
+## Quick Self-Test
 
----
+Ask these questions before implementation:
 
-## 不支持（承认搞不定，skill 不教）
+1. **Can the data be seen in the browser?** If not because of a login wall or paywall, solve authentication first.
+2. **Is the data source HTTP, JSON, or HTML?** If the answer is binary or encrypted-only, stop.
+3. **Does the command require per-second push?** If yes, find an HTTP endpoint with the same data; if none exists, stop.
 
-| 场景 | 原因 | 绕开方案 |
-|------|------|---------|
-| 首次登录获取 token | 需要用户真实输入账密 | 让用户先在 browser session 里手动登录，adapter 拿 cookie 就行 |
-| 复杂 anti-bot（captcha） | 反爬拒流量 | 放弃，换同数据的其他站点 |
-| 加密字段（客户端 crypto） | 要破解 bundle 逆向 | 换 endpoint；实在不行发请求到 intercept 让页面自己解 |
-| WebSocket 流式数据 | 状态管理复杂 | 退回 HTTP 轮询版本（多数站都有） |
-| 私有 binary 协议 | 非 HTTP/WS | 不在 skill 范围 |
-| 视觉化图表（只有 canvas） | 数据埋在渲染层 | 找对应 API；找不到就放弃 |
-| 签名算法涉及静态密钥 | 需要长期跟踪 bundle 变更 | 走 `Strategy.INTERCEPT`，让页面自己发带签名的请求 |
-| 频控 / rate-limit 严格 | 多发几次就 429 | adapter 层控并发 + 加退避；但 skill 不解决 |
+Continue only when all three checks pass.
 
----
+## Evidence Levels
 
-## 决定用不用 skill 的快速自测
+| Level | Meaning | Required proof |
+| --- | --- | --- |
+| Green | Hard verified | `webcmd browser verify` passed and visible-page values were checked. |
+| Yellow | Plausible but not fully exercised | Pattern is documented, but this exact site has not been verified end-to-end. |
+| Red | Out of scope | The skill explicitly does not teach this path. |
 
-三个问题：
-
-1. **数据能在浏览器里看到吗？** 看不到（登录墙 / 付费墙）→ 先解决鉴权，再回来
-2. **数据来源是 HTTP/JSON/HTML 之一吗？** 不是（binary / 加密）→ 不在 skill 范围
-3. **需不需要每秒推送？** 需要 → 找同数据 HTTP 接口；没有就放弃
-
-三个都 yes 再往下走。
-
----
-
-## 本轮硬验证 / 当前证据
-
-| 类型 | 证据 adapter | 覆盖维度 |
-|------|-------------|---------|
-| PUBLIC + 自解释字段 + SPA | `~/.webcmd/clis/coingecko/top.js`（本轮 dry run） | `Strategy.PUBLIC` + REST JSON + 自解释字段 + 列表页 |
-| COOKIE + 代号字段 + JSONP | `clis/eastmoney/*.js` × 13（PR #1091 merged） | `Strategy.PUBLIC`（匿名 `ut=`）+ JSONP + f-代号 + 列表/详情/K 线 |
-| COOKIE + SPA | `clis/bilibili/*.js` × 10+（已存在） | `Strategy.COOKIE + browser:true` + wbi 签名 |
-
-**本 PR 新增的 skill 还未硬验证的维度**：🟡 行，尤其 SSR Pattern B + Bearer/CSRF + 未登记代号解码。这些放到第一批真实用户 adapter 写作中打磨，skill 文档先落，踩坑回来补 `site-memory`。合 PR 之前先拿 coingecko 跑第二轮（带着第一轮写出的 `~/.webcmd/sites/coingecko/`）验证 memory 命中 → endpoint re-verify → 字段抽查 → 写 adapter 这条回路。
+Prefer green evidence. If you proceed on yellow evidence, write the uncertainty in `~/.webcmd/sites/<site>/notes.md` after the run so the next agent starts with better context.