@agentrhq/webcmd 0.1.2 → 0.2.0

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

@@ -1,169 +1,125 @@
 # Strategy Selection
 
-SKILL.md 顶层已给出 strategy gate 的 enum、表格和必填字段。本文件展开**为什么**这套 ladder 是按"契约"而不是"接口高度"组织的，以及具体怎么用 `webcmd browser analyze` 的 `api_candidates` 证据填 strategy note。
+Choose the strategy before writing adapter code. The right strategy is the lowest-maintenance source that has enough evidence.
 
-进入条件：你已经按 `site-recon.md` 跑过 `webcmd browser analyze`、按 `api-discovery.md` 抓过候选 endpoint。本文件是写 note 之前的最后一站。
+## Contract Ladder
 
----
+| Rank | Strategy | Contract | Maintenance risk |
+| --- | --- | --- | --- |
+| 1 | `PUBLIC_API` | stable external contract | lowest |
+| 2 | `COOKIE_API` | stable endpoint plus page-sourced auth | low |
+| 3 | `UI_SELECTOR` | visible UI contract | low to medium |
+| 4 | `DOM_STATE` | visible page state / SSR contract | medium |
+| 5 | `PAGE_FETCH` | internal page-runtime endpoint | high |
+| 6 | `INTERCEPT` | internal request naturally issued by page | high |
 
-## 1. 核心模型：契约 vs 无契约
+Use the first strategy in the ladder that can satisfy the command honestly.
 
-普遍假设 "API > DOM" — **数据不支持**。
+## Strategy Definitions
 
-837 个内置 adapter 在 30 天观察窗（2026-04-20 → 2026-05-20）按 6 档 strategy 分类后的实测 fix 频率：
+### `PUBLIC_API`
 
-| 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 |
+Use when Node-side `fetch` can retrieve the target data without login or page state.
 
-含义：
+Required evidence:
 
-- 选 `PAGE_FETCH` / `INTERCEPT` 的 adapter 平均维护成本是 `PUBLIC_API` 的 **~7-8 倍**
-- `UI_SELECTOR` 在 1.92/year，跟 `COOKIE_API` 同档 — 不是"漂得最快"
-- `DOM_STATE` 在 0.91/year 但 N=11 小样本，按 `UI_SELECTOR` 的近邻处理
+- URL, method, params.
+- 200 response.
+- JSON or HTML contains target data.
+- Response is not analytics, ads, recommendations, or layout-only data.
 
-**Selection bias caveat**：`PAGE_FETCH` / `INTERCEPT` 高 fix 率部分来自 selection bias — 用这俩的本身就是难站（Twitter GraphQL、xhs signed URL）。但这不改变 practical implication：能用契约层就用契约层，别把稳定的 UI/DOM 实现盲目迁到无契约 endpoint。
+### `COOKIE_API`
 
-数据观察窗局限：30 天窗口是近似不是长尾；`PAGE_FETCH`/`INTERCEPT`/`DOM_STATE` 样本量小（N=32/9/11），二期数据足时会单独评估 `DOM_STATE`。
+Use when Node-side `fetch` works after sourcing cookies or headers from the page.
 
----
+Required evidence:
 
-## 2. Ladder 心智模型
+- Cookie/header/CSRF source is documented.
+- Replay returns non-empty target data.
+- Auth values are obtained from the user's existing browser session.
 
-```
-契约层（首选，互相平级，按 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"过度辩护。
+### `UI_SELECTOR`
 
----
+Use when the user-visible UI is the stable contract: click, publish, upload, form, navigation, or page semantics.
 
-## 3. 怎么把 `api_candidates` 转化为 strategy note 证据
+Required evidence:
 
-`webcmd browser analyze <url>` 的输出里 `api_candidates[]` 字段，每条带：
+- Stable semantic selector or accessibility anchor.
+- Typed error path for missing UI, auth, timeout, and empty result.
+- Visible-page assertion after the action when possible.
 
-```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"]
-}
-```
+### `DOM_STATE`
 
-按 `verdict` 决策：
+Use when target data is in SSR HTML, hydration state, or bootstrap JSON.
 
-| 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` |
+Required evidence:
 
-**关键**：`real_data_score` 是证据，不是 strategy。你最终在 strategy note 里仍要写 replay 出来的 status / content-type / sample shape，不是把 score 直接当结论。
+- State key, script JSON, or HTML structure is clear.
+- At least one extracted value matches the visible page.
+- Parser failure produces a typed error, not an empty success.
 
-### 反例：booking #1680
+### `PAGE_FETCH`
 
-```
-Site: booking.com (酒店搜索)
-analyze 输出：17 个 JSON XHR，原 Pattern A
-但 api_candidates 全部 verdict=noise（analytics + personalization + experiment）
-```
+Use when only page-context `fetch` can reuse same-origin/session/runtime state.
 
-按 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`。
+Required evidence:
 
-`browser analyze` 的 `recommended_next_step` 也已更新为 "Inspect api_candidates, then replay the best endpoint" — 不再按 XHR count 推 API。
+- `webcmd browser eval fetch(...)` returns non-empty target data.
+- Simpler strategies are ruled out in the strategy note.
+- Internal endpoint drift risk is accepted and documented.
 
----
+### `INTERCEPT`
 
-## 4. Strategy note 的关键字段填法
+Use when request signing or runtime state is too complex, but the page can naturally issue the target request.
 
-### `Contract` 字段
+Required evidence:
 
-不是直接从 strategy enum 抄，而是反映"这个 source 有多稳"：
+- Stable user action triggers the request.
+- Captured response contains target data.
+- UI/DOM cannot provide the target data or operation.
 
-- `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）
+## `api_candidates` Evidence
 
-### `Evidence` 三行
+`webcmd browser analyze` may output `api_candidates[]`.
 
-每行都是事实，不是猜测：
+Treat a candidate as usable only when:
 
-```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 / 非空
-```
+- `verdict` is `likely_data`.
+- Response sample includes target fields.
+- URL and params are related to the user-visible result.
+- Replay succeeds or the failure clearly points to auth/token handling.
 
-`observed request/state` 在 `DOM_STATE` 时写 state global key（`window.__INITIAL_STATE__.feed.items`）；在 `UI_SELECTOR` 时写 selector path 或 a11y locator（`role=list[name="Trending"] > listitem`）。
+Ignore candidates when:
 
-### `If PAGE_FETCH or INTERCEPT` 三行论证
+- `verdict` is `noise`.
+- The response is analytics, beacon, ads, personalization, or experiment config.
+- It contains only layout metadata.
+- It cannot be tied to visible page data.
 
-```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 流程兜底>
-```
+## Counterexample: API-Looking Noise
 
-**反模式**：
+A booking-site case had many JSON XHR requests. They looked like Pattern A, but the useful visible data was not in those requests; the requests were analytics side-channels. The correct outcome was `DOM_STATE` / `UI_SELECTOR`, not `PAGE_FETCH`.
 
-- ❌ "因为 API 比 DOM 高级" — 不是论证，是假设
-- ❌ "因为 selector 不可靠" — 数据不支持（UI_SELECTOR 跟 COOKIE_API 同档）
-- ❌ "因为我看到 17 XHR" — 不是论证，是 booking #1680 反例
+Lesson: "has JSON XHR" is not the same as "has a usable API." Verify target data and external contract before choosing strategy.
 
-正确论证须基于：endpoint 的**真实**不可达 / 操作语义本质 / 维护成本承担方有明确接收方。
+## Required Strategy Note
 
-### `If UI_SELECTOR / DOM_STATE`
+Write this before adapter code:
 
 ```md
-- semantic anchor: <a11y role / data-testid / framework-stable class>
-- typed error path: <selector 失配时抛 EmptyResultError / CommandExecutionError>
+Strategy: PUBLIC_API | COOKIE_API | UI_SELECTOR | DOM_STATE | PAGE_FETCH | INTERCEPT
+Contract: stable | visible-ui | internal-unstable
+Evidence:
+- observed request/state:
+- auth source:
+- replay result:
+Why not simpler:
+- PUBLIC_API:
+- COOKIE_API:
+- UI_SELECTOR/DOM_STATE:
+Risk:
+- drift risk:
+- verification fixture:
 ```
 
-不需要"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。维护成本最低。
+If the selected strategy is `PAGE_FETCH` or `INTERCEPT`, the "Why not simpler" section is mandatory. If the selected strategy is `UI_SELECTOR` or `DOM_STATE`, do not over-defend why it is not an API; focus on semantic anchors and typed errors.

package/skills/webcmd-adapter-author/references/success-rate-pitfalls.md

@@ -1,162 +1,137 @@
 # Success-Rate Pitfalls
 
-11 个**静默失败**（adapter 看起来能跑、verify 能过，但数据是错的）的坑。每条给：现象 → 根因 → 防御手段。
+These are silent failures where `webcmd browser verify` can pass while the data is wrong. Check this file during field decoding and visible-page comparison.
 
-不是风格建议。每条都对应过一次真实翻车。
+## 1. Wrong Unit Scale
 
----
+Symptoms:
 
-## 1. fixture pattern 被放松以过 verify
+- Value is 100x, 1,000x, or 10,000x off.
+- Percentage appears as `0.025` in source but output claims `0.025%` instead of `2.5%`.
 
-**现象**：`verify` 报 `pattern "url" does not match /^https?:\/\/.*\.com\/bbs\/thread-/`。agent 的"修法"是把 fixture 里的 pattern 改宽（`^https?://`），verify 一下就通过了。
+Fix:
 
-**根因**：adapter 丢了 URL 前缀 / 拼错了路径 / 吃到了相对路径。pattern 失败不是 fixture 太严，是 adapter 输出真的破了。
+- Decide the output scale.
+- Document it.
+- Compare with a visible page value.
 
-**防御**：
-- `autofix` skill 现有纪律：**verify pattern 失败 = 收紧 adapter，不是收紧 fixture**（`webcmd-autofix` SKILL.md §Rules for Patching 第 6 条）
-- 要改 fixture 的唯一合法理由：**站点本身换了格式**（例如 URL 规范迁移）。这种情况下在 `~/.webcmd/sites/<site>/notes.md` 顶部写一段说明
+## 2. Seconds Versus Milliseconds
 
----
+Symptoms:
 
-## 2. 字段内容污染但 `notEmpty` / `columns` 都过
+- Dates land in 1970 or far future.
+- Time sorting looks wrong.
 
-**现象**：`description` 字段不为空，`verify` 通过。肉眼看输出发现描述里混了 `"address: 上海 category: IT"` 之类明显不属于描述的片段——兄弟 DOM 节点或父节点文字被一起 `textContent` 了。
+Fix:
 
-**根因**：`.container` 的 `textContent` 包括所有后代文字。调 `innerText` 仅好一点；用 `querySelector('.desc').textContent` 时，如果 `.desc` 里嵌套了 `.tag.address`，一样吃进去。
+- Inspect timestamp length.
+- Convert seconds with `* 1000`; leave milliseconds as-is.
+- Keep timezone clear.
 
-**防御**：
-- fixture 用 `mustNotContain`：`{ "description": ["address:", "category:", "工作年限:"] }` 把已踩过的污染词列出来
-- adapter 侧：定位更精确的 selector，或抓到后 `.replace(/address:[^\n]*/g, '').trim()`
-- 别信 `textContent.trim()` 就完事
+## 3. Page-Level Selector In Repeated Cards
 
----
+Symptoms:
 
-## 3. 字段语义分歧（两个字段看起来都对）
+- Every row has the same author, count, button state, or URL.
 
-**现象**：51job 列表有 `updatedate` 和 `publishDate`，eastmoney 债券有 `f10`（发行日）和 `f26`（上市日）。adapter 随便选一个，verify 通过，用户一对照发现时间错位 1 个月。
+Fix:
 
-**根因**：两个字段都是合法日期，format 也对，只是含义不同。`notEmpty` / `types` 都挡不住。
+- Scope selectors to the row/card root.
+- Add a JSDOM fixture for repeated-card parsing.
 
-**防御**：
-- Step 7 字段解码**必须和网页肉眼对至少一条已知记录**（"这条债券首页写的上市日是 2025-02-14"，看 adapter 输出对不对得上）
-- 字段写进 `field-map.json` 时 `meaning` 要精确到"上市日"而不是"日期"
+## 4. Hidden Template Content
 
----
+Symptoms:
 
-## 4. 字段单位混淆（数值量级错）
+- Output includes rows not visible on the page.
+- Text contains modal, template, or navigation labels.
 
-**现象**：eastmoney 返回 `totalMarketCap: 128`（单位：亿元），adapter 直接写进 `marketCap`，用户对照 K 线页看是 128 元。常见错位：
+Fix:
 
-| 接口返回 | 网页显示 | 实际单位 | 错误写法 |
-|---------|---------|----------|---------|
-| `0.025` | `2.5%` | 小数 | adapter 再 × 100 → 显示 250% |
-| `12800` | `1.28 万` | 元 | adapter 不除 10000 → 显示 12800 万 |
-| `f152 = 2` | `9.27` | 价格 = 原值 ÷ 10^f152 | adapter 忽略 f152 → 显示 927 |
+- Filter hidden elements.
+- Prefer semantic row roots over broad text extraction.
 
-**防御**：
-- fixture 加 `mustBeTruthy` 挡 `|| 0` / `|| false` silent fallback（数值列应该有值，不是 0）
-- `field-map.json` 的 `meaning` 写单位：`"premium pct (0-1 fraction, NOT already × 100)"`
-- Step 11 肉眼比对不能只比"有没有数字"，要比数量级
+## 5. Locale-Dependent Labels
 
----
+Symptoms:
 
-## 5. JSON-in-attribute vs 渲染后 innerText
+- Parser works in one locale and fails in another.
+- `aria-label` or button text changes.
 
-**现象**：51job 把完整 JSON 塞在 `<div data-sensorsdata='{"job_title":"..."}'>` 里，用 innerText 取的是渲染后的截断显示文字（"Lead... ↩ 上海..."），字段边界丢了。
+Fix:
 
-**根因**：现代站点常把结构化数据放在 `data-*` 属性里，渲染层只挑部分显示。取 innerText 相当于丢掉了结构。
+- Prefer stable attributes or structure.
+- If text is unavoidable, support known variants and fixture them.
 
-**防御**：
-- 看到 `data-sensorsdata` / `data-ng-state` / `data-page-props` / `data-track` 类属性先读属性，不读 innerText
-- 先在 `browser eval` 里检查：`document.querySelector('.item').dataset` 看有没有 JSON 串
-- 搜 bundle 时也搜 `JSON.parse(el.dataset.*)` 模式看 vendor 把数据塞哪了
+## 6. Analytics Or Recommendation APIs
 
----
+Symptoms:
 
-## 6. cookie 域 / origin 不一致的隐式假设
+- JSON endpoint exists but rows do not match visible results.
+- API returns personalized or experiment data.
 
-**现象**：在 `jobs.51job.com` 页面调 `cupid.51job.com` 的接口，headless 里带了 cookie 也跨不过去——`credentials:'include'` 只管带 cookie，不管 CORS。
+Fix:
 
-**根因**：浏览器 CORS 预检默认关闭跨 subdomain 请求。`credentials:'include'` 不是万能药。
+- Verify target data against the visible page.
+- Reject `api_candidates` marked `noise`.
 
-**防御**：参见 `api-discovery.md §0.2`。判断：`fetch(target).catch(e=>'cors:'+e.message)` 看是不是 TypeError。降级路径：改用 same-origin endpoint / 改在目标 subdomain 上打开页面 / 走 `§5 intercept`。
+## 7. Empty Success
 
----
+Symptoms:
 
-## 7. 等不够就抓导致空 DOM / 空 network
+- Adapter returns `[]` when selectors changed, auth expired, or endpoint returned HTML.
 
-**现象**：`open url && wait time 2 && network` 看到 0 条业务 API。agent 以为是 Pattern C（静态），去 bundle 里找 baseURL，找不到就卡住。真相：SPA 3.5 秒才发出第一个 API。
+Fix:
 
-**根因**：`wait time N` 是盲等。不同站点 JS 执行速度差很多。
+- Throw `EmptyResultError` only when the site truly reports no results.
+- Throw typed errors for auth, timeout, parse, or shape failures.
 
-**防御**：
-- 数据是异步加载时**不用 `wait time`**，用 `webcmd browser wait xhr '/api/path-fragment'`，等具体 XHR 到场再 `network`
-- 不确定 endpoint 路径时：先 `wait time 2 && network`，看到候选路径再转 `wait xhr` 确认
-- 首诊断用 `webcmd browser analyze <url>` 一步拿 `json_responses` 数量——=0 时才真的是 Pattern C
+## 8. Silent Clamp
 
----
+Symptoms:
 
-## 8. adapter 里的 falsy `|| 0` 兜底静默
+- Invalid `limit`, page number, or date silently changes to a default.
 
-**现象**：`likes: data.likes || 0`。接口偶尔返回 `likes: null`（可能因字段名改了、权限问题等），adapter 写成 0，verify `types: {likes: 'number'}` 通过，用户看到的是"所有帖子 0 赞"。
+Fix:
 
-**根因**：`||` 兜底把"没抓到"变成"是 0"。`notEmpty` 挡不住 0，`types` 也不挡。
+- Throw `ArgumentError` for invalid external args.
+- Clamp only when the command explicitly documents clamping.
 
-**防御**：
-- fixture 用 `mustBeTruthy: ["likes", "count", ...]`——业务数值列必须 truthy
-- adapter 侧 prefer `?.` 而不是 `||`；真的想兜底就兜 `undefined`，让 verify 能看见
-- 全部 `|| 0` 要过一遍眼：这个 0 是合法值还是漏抓 fallback
+## 9. Column Drift
 
----
+Symptoms:
 
-## 9. 跨 session cookie 污染 / 登录态漂移
+- `columns` contains a field that rows do not return.
+- Row contains extra fields not documented in `columns`.
 
-**现象**：本地开发时用自己的登录态验 endpoint 能通，PR 一合 verify fixture 跑在 CI 环境里立刻 401——顺手把样本数据也固化进了 fixture，看起来"一切正常"。
+Fix:
 
-**根因**：fixture 样本是带登录态跑出来的。存 `~/.webcmd/sites/<site>/fixtures/*.json` 没脱敏，把 cookie / token / 自己的 uid / 昵称存了进去。
+- Keep `columns` and row keys exactly aligned.
+- Add fixture checks for columns and types.
 
-**防御**：
-- `site-memory.md` 的脱敏规则：存 fixtures 前去掉 cookie / token / 用户私有字段（手机号 / 邮箱 / 昵称 / uid）
-- 需要登录态的接口：adapter 用 `Strategy.COOKIE`，adapter 代码里**不写任何具体 cookie 值**，只声明"我需要 domain X 的 cookie"
-- verify 样本里看到 `Bearer ...` 或 32 位 hex token → 先删再存
+## 10. Auth State Misread
 
----
+Symptoms:
 
-## 10. adapter 默认 timeout 不统一
+- Logged-out page returns marketing content but parser treats it as data.
+- Endpoint returns login HTML with status 200.
 
-**现象**：同一个站两个 adapter，一个默认 15s timeout，另一个默认 60s。慢接口在一个命令里 ok，在另一个一样的慢接口却 timeout 了。
+Fix:
 
-**根因**：模板没统一 timeout；agent 依赖"最像的邻居"复制，复制到的邻居选了短 timeout。
+- Detect login walls.
+- Throw `AuthRequiredError`.
+- Check response content type and expected shape.
 
-**防御**：
-- 邻居 adapter 的 `requestTimeoutMs` / `browser.wait` 配置**不能盲抄**。每个 adapter 应该结合自己的接口特性设一个
-- 真实接口延迟：Step 5 endpoint 验证时用 `time curl`（或 `performance.now()` 包 fetch）量一下 p50 / p95，timeout 设 p95 × 2 比较安全
-- 出现偶发 timeout 别 retry 掩盖；记到 `notes.md`，下次就知道这接口 p95 偏高
+## 11. Fixture Too Loose
 
----
+Symptoms:
 
-## 11. `aria-label` / `placeholder` / `title` 是 locale-dependent 文本
+- Verify passes even after a parser regression.
+- Patterns only check that some string exists.
 
-**现象**：你本地英文 Chrome 测 `button[aria-label="Submit"]` 一切正常，verify fixture 也是英文环境抓的。用户把 `chrome://settings/languages` 切中文，同一个按钮变 `aria-label="提交"`，adapter silent 0 匹配——退化成 `notEmpty` / `types` 都没法 fire 的"adapter 跑完返 0 行"。
+Fix:
 
-**根因**：`aria-label` / `title` / `placeholder` / `alt` / `textContent` 都是页面的**用户可见文本**，被站点 i18n 框架翻译。用它们当 selector anchor 等于 "select by visible text"，locale 一动整个选择器就废。
-
-**防御**：
-- 优先用 locale-stable 标识：`data-testid` / `data-*` / 稳定 `id` / `class`。先确认不是 hash / A-B test 产物
-- `role` 不按 locale 翻译，但通常不唯一；只能当 semantic / scope filter，不能用裸 `[role="button"]` 当 primary
-- 站点只暴露 `aria-label`（典型如 ChatGPT web 某些 control）时，写 fallback list，至少 en + zh-CN：`'[aria-label="Send"], [aria-label="发送"]'`
-- commit 前 grep `aria-label=` / `placeholder=` / `title=` 的硬编码字符串，确认每条都有兜底 locale
-- 找不到 control 要 typed fail-fast（例如 `CommandExecutionError` / send-failed），不要把 selector miss 变成空 rows 或假成功
-- 详细 framework + 活例见 `adapter-template.md §Selector 稳定性`
-
-不要去给 framework 加 `--i18n` flag 自动展开——多一层 indirection 还要维护翻译字典，纯 over-engineering。
-
----
-
-## 总结：静默失败的共同特征
-
-1. **verify 绿 ≠ 数据对**。verify 只能证"结构没坏"，证不出"值对不对"。Step 11 肉眼比对是必须的。
-2. **"字段有值"是个比"字段为空"更危险的失败态**。空你会去查，有值你会 fallthrough。
-3. **fixture 四件套一起上**：`patterns` + `notEmpty` + `mustNotContain` + `mustBeTruthy`——每件挡一类问题，缺一个就漏。
-
-回写 `notes.md` 时把你踩的新坑写进去。下次就有第 12 条了。
+- Add `notEmpty` for core fields.
+- Add URL/date/ID patterns.
+- Tighten `rowCount`.
+- Reverse-validate important parser tests.