publishport-opencli 1.8.4-pp.1

package/skills/opencli-adapter-author/references/field-decode-playbook.md

@@ -0,0 +1,181 @@
+# Field Decode Playbook
+
+响应里出现 `f237 / zdf / oc5 / x4` 这种看不懂的代号时走这套流程。目标：10 分钟内搞定一条未知字段，不靠猜。
+
+适用于 `field-conventions.md` 没收录的站点、没收录的代号、或者收录了但怀疑对不上的情况。
+
+---
+
+## 决策树
+
+```
+拿到一条响应，有字段看不懂？
+├── 字段值是字符串 / 时间 / URL → 走 §1 「肉眼对网页」
+├── 字段值是数字 → 走 §2 「排序键对比法」
+├── 字段值是数组 / 对象 → 走 §3 「结构差分法」
+└── 改参数响应不动 → 走 §4 「常量 / 精度位排查」
+```
+
+---
+
+## §1 肉眼对网页（字符串/时间/URL 类）
+
+最快。打开对应网页，响应的这条记录在哪行，把响应值跟页面上的文字一一对照。
+
+```bash
+# 举例：eastmoney convertible，响应里有 f243=20231215，页面上这支债写着"上市日期 2023-12-15"
+# 直接判断 f243 是上市日期（YYYYMMDD int）
+```
+
+**时间字段的判别**：
+
+| 观察到的形态 | 大概率是 |
+|-------------|---------|
+| 10 位整数 `1712345678` | unix 秒 |
+| 13 位整数 `1712345678000` | unix 毫秒 |
+| 8 位整数 `20240101` | YYYYMMDD int |
+| 6 位整数 `240101` | YYMMDD int |
+| 字符串 `2024-01-01` / `2024/01/01` | ISO 日期 |
+| 字符串 `01/01/2024` | 美式日期，小心月日顺序 |
+
+**URL 字段的判别**：
+
+```bash
+# 如果是相对路径，拼 domain 回浏览器验证
+opencli browser eval "window.location.origin + '/<path>'"
+```
+
+---
+
+## §2 排序键对比法（数字类核心手段）
+
+数字字段是最容易踩坑的一类——看起来都是小数，但可能是涨跌幅、换手率、振幅、溢价率、市盈率……单位和量级也可能带陷阱。
+
+### 流程
+
+1. **找到一个能改变排序的参数**
+
+   | 站点 | 排序参数 | 值域 |
+   |------|---------|------|
+   | eastmoney (push2 clist) | `fid` + `po` | `fid` 是字段代号，`po` 是 `0=asc / 1=desc` |
+   | xueqiu | `order_by` | `percent / volume / amount / ...` |
+   | bilibili | `order` | `pubdate / click / stow / ...` |
+   | tonghuashun | `sort` | 数字代号 |
+   | 通用 | 页面点击表头切排序，抓包看新参数 | — |
+
+2. **用两个已知含义的值各抓一份响应**
+
+   比如 eastmoney，`fid=f2`（最新价）和 `fid=f3`（涨跌幅）：
+
+   ```bash
+   opencli browser eval "fetch('<url>&fid=f2&po=1').then(r=>r.json()).then(d=>d.data.diff.slice(0,3))"
+   opencli browser eval "fetch('<url>&fid=f3&po=1').then(r=>r.json()).then(d=>d.data.diff.slice(0,3))"
+   ```
+
+3. **对比两组数据**：
+
+   - 第一条记录的 `symbol/name` 变了吗？没变说明这个参数无效或者白名单窄
+   - 新的第一条里，哪个字段数量级 / 正负号 / 小数位数变化最大？那个字段就是和 `fid` 对应的业务语义
+   - 单调性：按 `desc` 取前 3 条，看新旧两组里目标字段是不是都单调下降
+
+4. **用第三个参数交叉验证**
+
+   ```bash
+   opencli browser eval "fetch('<url>&fid=f6&po=1').then(r=>r.json()).then(d=>d.data.diff.slice(0,3))"  # 成交额
+   ```
+
+   对照网页上"成交额排行"的前三名。对得上就认。
+
+### 实例：推 f237（可转债溢价率）
+
+```bash
+# 按价格排，拿一条观察
+opencli browser eval "fetch('https://push2.eastmoney.com/api/qt/clist/get?fs=b:MK0354&pn=1&pz=1&fid=f2&po=1&fltt=2&fields=f12,f14,f2,f3,f236,f237,f239').then(r=>r.json()).then(d=>d.data.diff[0])"
+# 返回 {f12:'123456', f14:'XX转债', f2:180.5, f3:2.1, f236:98.5, f237:83.2, f239:-4.1}
+
+# 按 f237 排
+opencli browser eval "fetch('...&fid=f237&po=1...').then(...)"
+# 第一条变了，f237 值变成 400+
+
+# 打开 eastmoney 可转债页，切"溢价率"排序，第一条的溢价率确实是 400+ —— f237 就是溢价率 %
+```
+
+---
+
+## §3 结构差分法（数组 / 嵌套对象类）
+
+响应顶层是 `{data: {diff: [...]}}` 还是 `{list: [{...}, {...}]}` 还是 `{rows: [{k:v}, ...]}`，不同接口差别大。
+
+### 流程
+
+1. **先数一次嵌套路径**
+
+   ```bash
+   opencli browser eval "fetch('<url>').then(r=>r.json()).then(j=>({keys:Object.keys(j), type:Array.isArray(j)?'array':'object'}))"
+   ```
+
+2. **一层一层剥**
+
+   ```bash
+   opencli browser eval "fetch('<url>').then(r=>r.json()).then(j=>{const d=j.data; return {keys:Object.keys(d), sample: d[Object.keys(d)[0]]}})"
+   ```
+
+3. **数数组长度对照 pz / pageSize**
+
+   如果请求 `pz=20` 拿回的数组正好 20，那就是结果数组；如果是 1 那可能是 pagination meta。
+
+4. **同一字段在不同条目间是否变化**
+
+   ```bash
+   # 取前三条的 keys，看哪些 key 的值在变（业务数据），哪些不变（常量/配置）
+   opencli browser eval "fetch('<url>').then(r=>r.json()).then(d=>d.data.diff.slice(0,3).map(x=>({f2:x.f2,f3:x.f3,f152:x.f152})))"
+   ```
+
+---
+
+## §4 常量 / 精度位排查
+
+有的字段每条都一样，是精度指示器或类型标记。
+
+| 典型现象 | 通常含义 | 处理 |
+|---------|---------|------|
+| 每条值都是 `2` 或 `3` | 精度位数（小数几位） | 除以 `10^n` 还原浮点 |
+| 每条值都是 `0` 或 `1` | 涨跌方向 / 停牌标记 | 枚举，查同类 adapter |
+| 每条值都是 `6` / `8` / `80` | 市场代号 / 分类 ID | 查 `field-conventions.md` 市场表 |
+| 每条值都是空字符串 | 接口不返回但字段有占位 | 请求里去掉 / 用别的字段 |
+
+**eastmoney 精度坑**：不传 `fltt=2` 时，价格字段是 `int * 10^f152`。所以一律加 `fltt=2`，避免所有除法问题。
+
+---
+
+## §5 写完要做的事
+
+推出一个新代号后：
+
+1. **补进 `references/field-conventions.md`**：找到对应站点的表格加一行。下次直接查。
+2. **在 adapter 代码里留一条注释**：如果是实测推出来的不常见代号，写一行 `// f237 = convertible premium rate (verified 2026-04-20 against page)` 方便复核。
+3. **通过 `opencli browser verify` 验一次**：字段值能对上网页上眼见的数字。
+
+---
+
+## §6 通用坑
+
+| 坑 | 症状 | 解 |
+|----|------|-----|
+| 单位"万"当"元"用 | 成交额少 4 个零 | eastmoney `f6` 是元、`f62 / f64` 等净流入是万，核对每条接口 |
+| 百分比没 × 100 | 涨跌幅显示 0.0XX | 响应已经乘过 100 或者站点用小数 —— 看一眼网页 |
+| 股票代码被截 | `600000` 变 `60000` | 某些接口返回 int，前导 0 掉了。永远用 `String(code).padStart(6, '0')` 处理 A 股代码 |
+| 时间区无前导 0 | `2024-1-1` 排序坏 | parse 后用 ISO 回写 |
+| JSON 里数字是字符串 | 无法 `.toFixed()` | `Number(x)` 显式转 |
+
+---
+
+## §7 真推不出来
+
+三条兜底：
+
+1. **找同站点已有的 adapter** — `ls clis/<site>/` 翻文件，别站点邻居的 adapter 通常共享字段命名
+2. **找开源实现** — GitHub 搜 `<域名> fields` 或 `<域名> api`，往往有 Python / Go 库已经解码过
+3. **灰度**：把这条字段先输出成 raw，命令仍可用，下一版再语义化
+
+不要猜。猜错了后面验证不到、线上跑出来用户看到乱码也会误导决策。

package/skills/opencli-adapter-author/references/jsdom-fixture-pattern.md

@@ -0,0 +1,196 @@
+# JSDOM-against-frozen-fixture pattern (for in-browser DOM extractors)
+
+## When this pattern applies
+
+You're writing an adapter where the data extraction happens **inside the
+live browser** via `page.evaluate(...)` — not in Node-side post-processing.
+Typical signal: the adapter has a function literal stringified into
+`page.evaluate('(' + fn.toString() + ')()')`, walking `document.querySelector`
+and other DOM APIs.
+
+These extractors are invisible to mocked `page.evaluate` unit tests — those
+tests feed pre-baked results to the func, so the real DOM walk never runs.
+PR #1312 found two such silent in-browser bugs in dianping that only
+surfaced on live verify:
+
+1. shop title fallback split on ASCII `[]` while the page renders
+   full-width `【】`, so `name` was always empty.
+2. `headText.replace(/\s+/g, ' ')` collapsed rating "4.8" with reviews
+   "21241条", and a head-wide `/\d+条/` regex captured `4.821241` → 5.
+
+If either category looks plausible for your site, freeze a representative
+HTML snapshot and replay it through JSDOM in a unit test.
+
+## File layout
+
+- Test file: `clis/<site>/<site>.test.js` (alongside the adapter file)
+- Fixture file: `clis/<site>/__fixtures__/<command>.html`
+
+Reference implementation: `clis/dianping/__fixtures__/{shop,search}.html`
+(see PR #1313 for the original test + PR #1318 for the whitespace-strip
+follow-up that this doc grew out of).
+
+## Creating the HTML fixture
+
+The whole point is to commit a **representative snapshot of the live
+page's DOM** — so the JSDOM unit test exercises the real selector paths
+the live extractor walks.
+
+### Mandatory steps (in order)
+
+1. **Capture** the page's HTML from a live verify run:
+   ```bash
+   opencli browser open https://www.example.com/<page>
+   # In another shell, dump page.content():
+   opencli browser eval 'document.documentElement.outerHTML' \
+     > /tmp/raw-<command>.html
+   ```
+
+2. **Strip noise blocks** that JSDOM doesn't need and that change every
+   page load (so committed fixtures wouldn't survive a re-capture diff
+   anyway):
+   - All `<script>...</script>` content
+   - All `<style>...</style>` content
+   - All `<iframe>...</iframe>` content
+   - All `<!-- ... -->` HTML comments
+   - All `<link rel="preload" ...>` / tracking pixels
+
+3. **Replace `<img src="...">`** with a placeholder
+   (`src="placeholder.png"`) — real CDN URLs leak account-scoped tokens
+   and are noise.
+
+4. **Trim to the minimum subtree** that exercises the extractor and
+   triggers the bug you're guarding against. For dianping shop, that
+   was `.shop-head` + `.desc-info` + `.review-title`; for search,
+   3 of 15 result `<li>` cards (rank 1, 2, 3).
+
+5. **MANDATORY whitespace normalization step** — strip all
+   whitespace-only lines:
+   ```bash
+   awk 'NF>0' /tmp/raw-<command>.html > clis/<site>/__fixtures__/<command>.html
+   ```
+   JSDOM's HTML parser is whitespace-tolerant; blank lines have zero
+   semantic effect on the test, but they bloat the committed diff and
+   obscure the meaningful DOM subtree from reviewers.
+   **Skipping this step is the most common silent quality regression
+   in fixture creation.** PR #1318 cleaned 239 leftover blank lines
+   from dianping's two fixtures (84.6% / 54.8% of file content) and
+   the JSDOM tests still passed unchanged.
+
+6. **Commit** at `clis/<site>/__fixtures__/<command>.html`.
+
+### Anti-patterns to avoid
+
+- ❌ "Strip script/style content" but leave the surrounding newlines.
+  Removing inline script body without collapsing the now-blank line is
+  the source of the noise — Step 5 exists specifically to clean this up.
+- ❌ Trim to minimum subtree, skip Step 5. The fixture works for the
+  test but reviewers see hundreds of blank lines.
+- ❌ Pretty-print the **mega-line** (e.g. `<div>...</div>` collapsed
+  onto one giant line by the source page). Some bugs depend on
+  text-node adjacency without intervening whitespace (e.g. `4.8` and
+  `21241条` immediately adjacent → `headText` fusion bug). Pretty-print
+  inserts whitespace that masks the very condition you're testing for.
+  Step 5 only deletes empty lines — never re-flow content.
+- ❌ Re-capture from live and overwrite the committed fixture without
+  re-running Steps 2-5. The fixture is a **frozen** snapshot; if the
+  page layout changes, that's a separate decision (update test
+  expectations + re-trim + re-strip).
+
+## Writing the JSDOM unit test
+
+```js
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { JSDOM } from 'jsdom';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { extractShopFields } from './shop.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SHOP_FIXTURE = readFileSync(join(__dirname, '__fixtures__/shop.html'), 'utf8');
+
+describe('shop adapter — extractor against frozen HTML fixture', () => {
+    let originalDocument;
+    let originalLocation;
+
+    beforeEach(() => {
+        originalDocument = globalThis.document;
+        originalLocation = globalThis.location;
+    });
+
+    afterEach(() => {
+        globalThis.document = originalDocument;
+        globalThis.location = originalLocation;
+    });
+
+    function loadFixture(html, url) {
+        const dom = new JSDOM(html, { url });
+        globalThis.document = dom.window.document;
+        globalThis.location = dom.window.location;
+        return dom;
+    }
+
+    it('extracts the canonical fields and avoids known silent bugs', () => {
+        loadFixture(SHOP_FIXTURE, 'https://www.example.com/shop/123');
+
+        const data = extractShopFields();
+
+        expect(data.ok).toBe(true);
+        expect(data.name).toBe('...');
+        // Add explicit regression guards for each known silent bug.
+        expect(data.reviewsRaw).toBe('...');  // not the fused "<rating><reviews>" form
+    });
+});
+```
+
+For this to work, the adapter's extractor must be a **top-level
+function** that uses bare `document` / `location` (not `window.document`),
+so the same code is exercised by:
+
+- live browser: injected via `${extractFn.toString()}` into
+  `page.evaluate`
+- JSDOM unit test: with `globalThis.document` swapped
+
+If your adapter currently has the extractor as an IIFE inside a
+template literal, refactor to a top-level `export function` first.
+Reference: `clis/dianping/{shop,search}.js` extracts `extractShopFields()`
+and `extractSearchRows()` with bare `document`/`location`.
+
+## Reverse-validation (mandatory before claiming the test catches the bug)
+
+A test that "passes 18/18" doesn't prove it would have caught the original
+bug — only that it agrees with the current implementation. Before
+trusting a regression guard:
+
+1. Make a backup of the adapter source.
+2. Reintroduce the buggy variant of the relevant extractor.
+3. Run the test. It MUST fail with an assertion that points at the
+   silent bug.
+4. Restore from backup.
+
+For dianping bug #2 (rating/reviews fusion):
+```js
+// BUGGY VARIANT — replaces the .reviews selector path
+const buggyMatch = headText.match(/(\d+)条/);
+let reviewsRaw = buggyMatch ? buggyMatch[0] : '';
+```
+
+If after Step 5 of fixture creation the test still fails on this buggy
+variant with `expected '21241条' to be '21241条'` actually receiving
+`'821241条'` (the fused digits), the regression guard is intact. If the
+test still passes with the buggy variant, the fixture is too stripped /
+normalization went too far / the assertion is too loose — go back and
+tighten.
+
+This is the same discipline as `--write-fixture` Step 10 in the main
+runbook (verify fixture catches what it should), applied to the JSDOM
+HTML fixture instead of the response JSON fixture.
+
+## See also
+
+- `references/adapter-template.md` — basic adapter file structure
+- `references/output-design.md` — column naming for the post-extract mapping
+- `references/success-rate-pitfalls.md` — broader "verify can pass while
+  data is silently wrong" catalog; the mocked-page.evaluate gap that
+  motivates this whole pattern is one entry there

package/skills/opencli-adapter-author/references/output-design.md

@@ -0,0 +1,149 @@
+# Output Design
+
+adapter 的 `columns` 不是随便列。要让下游（用户、其他 adapter 合并、agent 后续分析）都能直接读。
+
+---
+
+## 核心约定
+
+### 1. 命名
+
+**camelCase，全英文**：
+
+| 好 | 差 |
+|----|---|
+| `marketCap` | `market_cap` / `市值` / `MarketCap` |
+| `change24hPct` | `change_percentage_24h` / `涨跌幅24h` / `changePct_24h` |
+| `bondCode` | `bond_code` / `BOND_CODE` |
+| `pubTime` | `publish_time` / `pubdate` |
+
+原则：
+- 缩写：`pct`（百分比）/ `pe`（市盈率）/ `pb`（市净率）/ `ytm`（到期收益率）/ `id`
+- 时间后缀：`Time`（具体时刻）/ `Date`（日期）/ `Ts`（unix 秒）
+- 百分比一律 `Pct` 结尾，数值是"已乘 100"形式（`2.5` 表示 2.5%，不是 `0.025`）
+- 数量后缀：`Count`（整数计数）/ `Total`（累计值）
+
+### 2. 类型
+
+| 字段类 | JS 类型 | 格式 |
+|--------|---------|------|
+| 价格 / 金额 | `number` | 原始小数，别除 1000 别取整 |
+| 百分比 | `number` | 已 × 100（`2.5` = 2.5%） |
+| 计数 / rank | `number` | 正整数 |
+| 代码 / id / symbol | `string` | 股票代码 `'600000'` 保留前导 0 |
+| 名称 / 标题 | `string` | 去首尾空白 |
+| 时间 | `string` ISO（`'2024-01-15T10:30:00Z'`）或 `number` unix 秒 | 不要本地字符串 `'2024/1/15'` |
+| 布尔 | `boolean` | 不用 `0/1` |
+| URL | `string` | 绝对路径，相对路径要拼 host |
+
+**特殊**：
+- 缺失用 `null`，不用 `0` / `''`（0 和空字符串有业务含义，别混）
+- 枚举 → string，不要 int 代号（`'listed'` 比 `0` 清楚）
+
+### 3. 顺序
+
+固定三段：
+
+```
+[识别列 ...] [业务数字 ...] [metadata ...]
+```
+
+**识别列**（前 1-3 列）：`rank / symbol / code / bondCode / name / title / id`
+
+**业务数字**（中间）：价格、涨跌幅、成交量、市值等业务语义
+
+**metadata**（最后 1-3 列）：`pubTime / updateTime / source / url`
+
+### 4. 必有列（按类型）
+
+| adapter 类型 | 必须包含 |
+|-------------|---------|
+| 排行 / 列表 | `rank` + 识别列 + 业务数字 |
+| 时序 / K 线 | `date`（或 `ts`）+ 数值 |
+| 详情（单对象） | 识别列 + 业务字段 |
+| 新闻 / 公告 | `title` + `pubTime` + `url` |
+
+### 5. 控量
+
+**单条 ≤ 15 列**。超了就得考虑：
+- 拆成多个 adapter（列表版 + 详情版）
+- 次要字段合进 `extras: {...}` 对象
+- 只有少数用户关心的字段默认隐藏（靠参数开关）
+
+---
+
+## 对齐邻居 adapter
+
+写新 adapter 前先看同站点现有 adapter 怎么命名：
+
+```bash
+grep -h "columns:" clis/<site>/*.js
+```
+
+复用同类列名。比如 `clis/eastmoney/convertible.js` 用 `bondCode / bondName / stockCode / stockName`，新写 eastmoney 某个涉及股票代码的 adapter 就沿用 `stockCode / stockName`，不要发明 `securityId / securityName`。
+
+---
+
+## 常见错误
+
+| 错 | 对 |
+|----|---|
+| `columns: ['id', 'name', 'data.price']`（点路径） | 把 `data.price` 在 func 里打平成 `price` |
+| `{date: '2024-01-15 10:30'}`（空格 + 非 ISO） | `'2024-01-15T10:30:00Z'` 或 `Date.toISOString()` |
+| `{pct: '2.5%'}`（字符串 + 单位） | `{changePct: 2.5}` 纯数字 |
+| `{volume: '1.2万'}` | `{volume: 12000}` |
+| `{code: 600000}`（整数丢前导 0） | `{code: '600000'}` string，或 `String(code).padStart(6, '0')` |
+| columns 和 func 返回的 keys 对不上 | 列出的每个 key 必须在返回对象里，顺序也一致 |
+
+---
+
+## description 字段
+
+adapter `description` 是用户第一眼看到的，写清楚：
+
+1. **数据是什么**：`"A 股涨幅排行"` vs `"大盘指数分时"`
+2. **默认行为**：`"默认按涨幅排序，前 20 条"`
+3. **重要参数**：`"支持 market 参数切换沪深/北证"`
+
+不要：
+- `"get data"` — 废话
+- `"查询 xxx 数据"` — 也是废话
+- 塞完整 URL / 字段代号列表 — 留给 help
+
+一行 30 字左右够了。
+
+---
+
+## args 命名
+
+- `limit` 而不是 `count / num / n / size`
+- `sort` 而不是 `sort_by / order_by / sortKey`
+- `market` 而不是 `exchange / platform / type`
+- `symbol` / `code` / `query` 根据业务选，保持和邻居 adapter 一致
+- 布尔参数用 `enableX / includeX`，默认 false 免得用户改变认知负担
+
+`help` 文案给**所有合法值**，别让用户猜：
+
+```javascript
+{ name: 'sort', type: 'string', default: 'turnover', help: '排序：turnover / change / drop / price / premium' }
+```
+
+---
+
+## 示例对比
+
+**差的**：
+
+```javascript
+columns: ['股票代码', 'name', 'PRICE', 'change%', 'vol', 'time']
+```
+
+问题：中英混、大小写乱、百分号字符串、缩写不统一。
+
+**好的**：
+
+```javascript
+columns: ['rank', 'stockCode', 'stockName', 'price', 'changePct', 'volume', 'updateTime']
+```
+
+识别列在前，metadata 在后，命名统一 camelCase。

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

@@ -0,0 +1,70 @@
+# bilibili（B 站）
+
+## 域名
+
+| 用途 | 域名 |
+|------|------|
+| 主 API | `api.bilibili.com` |
+| 个人主页 / 空间 | `space.bilibili.com` |
+| 登录 / 鉴权 | `passport.bilibili.com` |
+| 动态 | `t.bilibili.com` / `api.vc.bilibili.com` |
+| 直播 | `api.live.bilibili.com` |
+
+## 默认鉴权
+
+- `Strategy.COOKIE + browser: true`
+- 核心 cookie：`SESSDATA`（登录态）、`bili_jct`（CSRF token，部分写接口要带到 header `Referer + csrf`）
+- **未登录也能调多数读接口**，但有 wbi 签名要求
+
+## 关键：wbi 签名
+
+- 凡 URL 含 `/wbi/` 的接口都要 `w_rid + wts` 签名
+- 签名算法依赖每日轮换的 `img_key / sub_key`，从 `api.bilibili.com/x/web-interface/nav` 的 `wbi_img` 字段拿
+- **不要自己重新实现**：`clis/bilibili/utils.js` 里的 `apiGet(page, path, { signed: true, params })` 已经封装好
+- 普通 cookie JSON 接口优先用 `page.fetchJson(url)`；站点级签名逻辑仍复用 `utils.js`
+
+## 已知 endpoint
+
+- `GET api.bilibili.com/x/web-interface/nav` — 登录态 + 拿 wbi key
+- `GET api.bilibili.com/x/space/wbi/arc/search?mid=<uid>` — 用户视频（需 wbi 签）
+- `GET api.bilibili.com/x/space/acc/info?mid=<uid>` — 用户资料
+- `GET api.bilibili.com/x/web-interface/view?bvid=BV...` — 视频详情
+- `GET api.bilibili.com/x/web-interface/popular?ps=20&pn=1` — 热门
+- `GET api.bilibili.com/x/web-interface/ranking/v2?rid=0` — 排行
+- `GET api.bilibili.com/x/v2/reply/wbi/main?type=1&oid=<aid>&mode=3` — 评论（需 wbi）
+- `GET api.bilibili.com/x/web-interface/search/all/v2?keyword=<q>` — 综合搜索
+- `GET api.vc.bilibili.com/dynamic_svr/v1/dynamic_svr/space_history?host_uid=<uid>` — 用户动态（新版走 `api.bilibili.com/x/polymer/web-dynamic/v1/feed/space`）
+- `GET api.bilibili.com/x/v2/history/cursor` — 观看历史（需登录）
+- `GET api.bilibili.com/x/v3/fav/folder/created/list-all` — 收藏夹列表（需登录）
+
+## 字段
+
+字段基本人类可读，见 `../field-conventions.md` 的 bilibili 节（`mid / aid / bvid / cid / view / danmaku / reply / favorite / coin / share / like / pubdate / ctime`）。
+
+## 坑 / 陷阱
+
+1. **wbi 签名缓存 `img_key / sub_key`**：24 小时内有效，每次请求都重新 fetch `nav` 会被限频。utils.js 内部做了缓存
+2. **`mid` 和 `uid` 一回事**：接口不统一，`mid=` 居多，个别接口要 `host_mid=`
+3. **视频 ID 两种**：`aid`（老数字）和 `bvid`（BV1xxx），视频详情要用 `bvid`
+4. **`ps=` 最大 50**（popular/ranking），超过了多发几页拼
+5. **动态接口换版**：老的 `dynamic_svr` 已经废，新的走 `x/polymer/web-dynamic/v1/feed/space`，写新 adapter 直接用新接口
+6. **评论分页靠 `next` 游标**，不是页号
+7. **B 站限频 `-352 风控`**：短时间高频调会拦截，adapter 层加 500ms 间隔
+8. **搜索要先 "cold start"**：空 cookie 的 session 第一次搜会 412，先访问首页拿 `buvid3` cookie
+9. **直播接口在 `api.live.bilibili.com`**，不是主域名
+
+## 可参考的 adapter
+
+| 模板类型 | 参考文件 |
+|---------|---------|
+| 用户资料 / 视频列表 | `clis/bilibili/user-videos.js` / `me.js` |
+| 视频详情 / 字幕 | `clis/bilibili/download.js` / `subtitle.js` |
+| 评论 | `clis/bilibili/comments.js` |
+| 搜索 | `clis/bilibili/search.js` |
+| 热门 / 排行 | `clis/bilibili/hot.js` / `ranking.js` |
+| 动态 | `clis/bilibili/dynamic.js` |
+| 关注 | `clis/bilibili/following.js` |
+| 收藏 | `clis/bilibili/favorite.js` |
+| 观看历史 | `clis/bilibili/history.js` |
+
+通用工具：`clis/bilibili/utils.js`。新 adapter 先 `import { apiGet, fetchJson } from './utils.js'`，不要重写。

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

@@ -0,0 +1,70 @@
+# eastmoney（东方财富）
+
+## 域名
+
+| 用途 | 域名 |
+|------|------|
+| 行情列表 / 批量报价 | `push2.eastmoney.com` |
+| K 线历史 | `push2his.eastmoney.com` |
+| 报表类（龙虎榜 / 十大股东） | `datacenter-web.eastmoney.com` |
+| 7x24 快讯 | `np-listapi.eastmoney.com` |
+| 公司公告 | `np-anotice-stock.eastmoney.com` |
+| 静态页（网页端入口） | `quote.eastmoney.com` / `data.eastmoney.com` |
+
+## 默认鉴权
+
+- `Strategy.PUBLIC + browser: false`
+- 统一带 `ut=bd1d9ddb04089700cf9c27f6f7426281`（push2 系列的公共 token）
+- User-Agent 随意给个 `Mozilla/5.0` 就行，不加会偶发被拦
+
+## 已知 endpoint
+
+- `GET push2.eastmoney.com/api/qt/clist/get` — 列表 / 排行
+  - 必需：`fs`（市场/板块过滤码）、`fields`（字段清单）
+  - 可选：`pn`（页码，1-based）、`pz`（每页数量）、`fid`（排序字段）、`po`（0=asc / 1=desc）、`fltt`（2=浮点格式化）、`invt`（2=固定）、`np`（1=固定）
+  - 返回：`data.diff[]` 数组
+- `GET push2.eastmoney.com/api/qt/ulist.np/get` — 批量报价（给定 secids）
+  - 必需：`secids`（逗号拼接的 `<market>.<code>`）、`fields`
+  - 返回：`data.diff[]` 数组
+- `GET push2.eastmoney.com/api/qt/stock/get` — 单只详情
+  - 必需：`secid`、`fields`
+- `GET push2his.eastmoney.com/api/qt/stock/kline/get` — K 线历史
+  - 必需：`secid`、`klt`（周期：1 分 / 5 / 15 / 30 / 60 / 101 日 / 102 周 / 103 月）、`fqt`（0=不复权 / 1=前复权 / 2=后复权）、`fields1`、`fields2`
+  - 返回：`data.klines[]` — CSV 字符串数组
+- `GET datacenter-web.eastmoney.com/api/data/v1/get` — 报表类
+  - 必需：`reportName`（如 `RPT_DAILYBILLBOARD_DETAILS`）、`columns`、`pageSize`、`pageNumber`、`sortColumns`、`sortTypes`
+  - 返回：`result.data[]`
+- `GET np-listapi.eastmoney.com/nlist/api/list/get` — 7x24 快讯
+  - 必需：`client=web`、`column_id`、`limit`、`last_time`
+- `GET np-anotice-stock.eastmoney.com/api/security/ann` — 公司公告
+  - 必需：`sr=-1`、`page_size`、`page_index`、`ann_type`、`stock_list`
+
+## 字段
+
+字段代号词典见 `../field-conventions.md` 的 eastmoney 节（`f2 / f3 / f12 / f14 / f62 / f229-f243` 等全集）。
+
+市场前缀、fs 过滤码、secid 格式也都在那里。
+
+## 坑 / 陷阱
+
+1. **`fltt=2` 必传**：否则价格字段是 `int × 10^f152` 的整数表示，要自己除
+2. **资金流单位混乱**：`f6` 成交额是元，但 `f62 / f66 / f72 / f78 / f84` 等净流入大部分接口返回"万元"，核对单条接口后再乘
+3. **secid vs code**：`0.000001 / 1.600000` 是 secid（market + code），只有纯 code 时要先判断所属市场前缀再拼。用 `clis/eastmoney/_secid.js` 导出的 `resolveSecid(input)`（单股）或 `splitSymbols(s)`（批量参数拆分），不要自己硬拼前缀
+4. **港股代码 `00700.HK` 不是 secid**：只有前缀属于 `{0, 1, 105, 106, 107, 116, 100, 90}` 才当 secid
+5. **kline CSV 列序**：`fields2=f51,f52,f53,f54,f55,f56,f57,f58,f59,f60,f61` 对应 `date,open,close,high,low,volume,turnover,amplitude,changePct,changeAmt,turnoverRate`
+6. **datacenter-web 字段名大写**：`SECURITY_CODE` 不是 `security_code`
+
+## 可参考的 adapter
+
+| 模板类型 | 参考文件 |
+|---------|---------|
+| clist 分页排行 | `clis/eastmoney/convertible.js` / `rank.js` / `etf.js` / `sectors.js` |
+| ulist 批量报价 | `clis/eastmoney/quote.js` |
+| K 线历史 | `clis/eastmoney/kline.js` |
+| 报表类 | `clis/eastmoney/longhu.js` / `holders.js` |
+| 7x24 快讯 | `clis/eastmoney/kuaixun.js` |
+| 公司公告 | `clis/eastmoney/announcement.js` |
+| 指数 / 北上 | `clis/eastmoney/index-board.js` / `northbound.js` |
+| 资金流 | `clis/eastmoney/money-flow.js` |
+
+新写 eastmoney adapter 时，照最像的那条 copy + 改 `name` / URL 参数 / 字段映射三处。