@agentrhq/webcmd 0.1.1 → 0.2.0

package/skills/webcmd-adapter-author/references/field-conventions.md

@@ -1,172 +1,89 @@
 # Field Conventions
 
-响应字段代号在主要站点上的解码表。写 adapter 前先查一遍，查不到再用 SKILL.md 里 Step 2 的实测法推出来，推完补到本表。
-
----
-
-## eastmoney（东方财富）
-
-域名：`push2.eastmoney.com` / `push2his.eastmoney.com` / `datacenter-web.eastmoney.com` / `np-listapi.eastmoney.com` / `np-anotice-stock.eastmoney.com`
-
-### 通用行情字段（`push2` clist/ulist/stock）
-
-| 代号 | 含义 | 备注 |
-|------|------|------|
-| `f1`  | 精度位数 | `fltt=2` 后可忽略 |
-| `f2`  | 最新价 | 要 `fltt=2` 才是格式化浮点 |
-| `f3`  | 涨跌幅 % | 同上 |
-| `f4`  | 涨跌额 | 同上 |
-| `f5`  | 成交量（手） | |
-| `f6`  | 成交额（元） | 接口默认是"元"，个别接口是"万元"，看 `f152` |
-| `f7`  | 振幅 % | |
-| `f8`  | 换手率 % | |
-| `f9`  | 市盈率（动态） | |
-| `f10` | 量比 | |
-| `f12` | 代码 | 股票/债券/ETF/指数统一 |
-| `f13` | market | 数字市场代号，见下表 |
-| `f14` | 名称 | |
-| `f15` | 最高 | |
-| `f16` | 最低 | |
-| `f17` | 今开 | |
-| `f18` | 昨收 | |
-| `f20` | 总市值 | |
-| `f21` | 流通市值 | |
-| `f23` | 市净率 | |
-| `f62` | 主力净流入 | **单位是"元"**，但有的接口返回"万元"，要核对 |
-| `f66` | 超大单净流入 | 同上 |
-| `f72` | 大单净流入 | |
-| `f78` | 中单净流入 | |
-| `f84` | 小单净流入 | |
-| `f100` | 所属板块 | |
-| `f152` | 精度（当 `fltt` 不传时要除以 10^f152） | 所以一律 `fltt=2` |
-
-### Convertible bond（可转债）专属
-
-| 代号 | 含义 |
-|------|------|
-| `f229` | 正股价 |
-| `f230` | 正股涨跌幅 |
-| `f232` | 正股代码 |
-| `f234` | 正股名称 |
-| `f235` | 转股价 |
-| `f236` | 转股价值 |
-| `f237` | 转股溢价率 |
-| `f238` | 剩余年限 |
-| `f239` | 到期收益率 (YTM) |
-| `f243` | 上市日期 (YYYYMMDD int) |
-
-### K-line `push2his` stock/kline/get
-
-返回形如 `data.klines: ["2024-01-02,10.5,10.8,10.9,10.4,12345,..."]` 的 CSV 字符串数组。用 `fields1 / fields2` 控制列。典型列序：
-
-```
-date, open, close, high, low, volume, turnover, amplitude, changePct, changeAmt, turnoverRate
+Use this file when response fields are coded, abbreviated, or inconsistent across adapters.
+
+## Naming Rules
+
+- Output column names use `camelCase`.
+- Prefer clear domain names over source field codes.
+- Keep units out of names unless the unit is part of the semantic contract.
+- Use the same names as neighboring adapters when the same concept appears.
+- Do not expose raw source codes as output columns unless the raw code is itself useful to users.
+
+## Common Column Names
+
+| Concept | Preferred column |
+| --- | --- |
+| Display title | `title` |
+| URL | `url` |
+| Author or owner | `author` |
+| Username or handle | `handle` |
+| Description or snippet | `description` or `snippet` |
+| Published date/time | `publishedAt` |
+| Updated date/time | `updatedAt` |
+| Score/rank | `score` or `rank` |
+| Comment count | `commentCount` |
+| Star count | `starCount` |
+| Fork count | `forkCount` |
+| Like count | `likeCount` |
+| View count | `viewCount` |
+| Duration | `duration` |
+| Price | `price` |
+| Currency | `currency` |
+| Rating | `rating` |
+| Location | `location` |
+| Source site | `source` |
+
+## Financial Columns
+
+Use finance names only for finance adapters:
+
+| Concept | Preferred column |
+| --- | --- |
+| Symbol | `symbol` |
+| Company name | `name` |
+| Current price | `price` |
+| Price change | `change` |
+| Percentage change | `changePercent` |
+| Open price | `open` |
+| High price | `high` |
+| Low price | `low` |
+| Previous close | `previousClose` |
+| Volume | `volume` |
+| Market cap | `marketCap` |
+
+Percentages should be documented in output design. If the source gives `0.025`, decide whether the output should be `0.025` or `2.5` and keep it consistent across the adapter.
+
+## Date And Time
+
+- Prefer ISO 8601 strings for exact timestamps.
+- Use date-only strings for date-only source fields.
+- Include timezone in docs or notes when the source uses a local timezone.
+- Do not silently parse unknown date formats into wrong dates.
+
+## IDs And URLs
+
+- Keep stable source IDs when they help users join data.
+- Normalize absolute URLs when the source returns relative paths.
+- Do not manufacture IDs from row position unless the docs say the ID is synthetic.
+
+## Raw Field Codes
+
+When a field code is already known, map it here or in `~/.webcmd/sites/<site>/field-map.json`:
+
+```json
+{
+  "fieldCode": {
+    "meaning": "human readable meaning",
+    "verified_at": "YYYY-MM-DD",
+    "source": "visible page comparison or official docs"
+  }
+}
 ```
 
-### Market 前缀（secid 格式 `<market>.<code>`）
-
-| 前缀 | 市场 |
-|------|------|
-| `1.`   | Shanghai (SSE) |
-| `0.`   | Shenzhen (SZSE) + Beijing (BSE) |
-| `116.` | Hong Kong (HKEX) |
-| `105.` | NASDAQ |
-| `106.` | NYSE |
-| `107.` | AMEX |
-| `100.` | 指数（HSI / SPX / DJIA / 各板块指数） |
-
-判断 symbol 是否已经是 secid 时，只在数字前缀属于上表时才认，否则视作普通 code（防止 `00700.HK` 这种 `<digits>.<alpha>` 误判）。
-
-### fs 市场/板块过滤码
-
-| 代码 | 含义 |
-|------|------|
-| `m:0+t:6,m:0+t:80,m:1+t:2,m:1+t:23,m:0+t:81+s:2048` | 沪深 A 股全集 |
-| `m:1+t:2,m:1+t:23` | 沪 A |
-| `m:0+t:6,m:0+t:80` | 深 A |
-| `m:0+t:81+s:2048` | 北证 A |
-| `m:0+t:80` | 创业板 |
-| `m:1+t:23` | 科创板 |
-| `m:116+t:3,m:116+t:4,m:116+t:1,m:116+t:2` | 港股 |
-| `m:105,m:106,m:107` | 美股 |
-| `b:MK0021` | ETF |
-| `b:MK0354` | 可转债 |
-| `m:90+t:2` | 行业板块 |
-| `m:90+t:3` | 概念板块 |
-| `m:90+t:1` | 地域板块 |
-
-### datacenter-web 报表 `reportName`
-
-| 名称 | 内容 |
-|------|------|
-| `RPT_DAILYBILLBOARD_DETAILS` | 龙虎榜 |
-| `RPT_F10_EH_FREEHOLDERS`     | 十大流通股东 |
-
----
-
-## xueqiu（雪球）
-
-域名：`stock.xueqiu.com` / `xueqiu.com`
-
-行情 API 返回字段是人类可读，不需要词典：
-
-| 字段 | 含义 |
-|------|------|
-| `symbol` | SH600000 / 00700 / AAPL 样式 |
-| `name` | 名称 |
-| `current` | 最新价 |
-| `chg` | 涨跌额 |
-| `percent` | 涨跌幅 % |
-| `volume` | 成交量 |
-| `amount` | 成交额 |
-| `high52w / low52w` | 52 周高低 |
-| `market_capital` | 总市值 |
-| `pe_ttm` | 市盈率 TTM |
-| `pb` | 市净率 |
-
-鉴权：需要 `xq_a_token` cookie。走 `Strategy.COOKIE + browser: true`。
-
----
-
-## bilibili
-
-域名：`api.bilibili.com` / `space.bilibili.com` / `passport.bilibili.com`
-
-B 站接口字段也大多人类可读。关键坑是 **wbi 签名**：
-
-- 凡 URL 含 `/wbi/` 的接口都需要 `w_rid + wts` 签名
-- 签名算法依赖每日轮换的 `img_key + sub_key`（从 `nav` 接口拿）
-- 平台 SDK 在 `clis/bilibili/utils.js`：`apiGet(page, path, { signed: true, params })` 自动签
-- 普通 cookie JSON 接口优先用 `page.fetchJson(url)`
-
-| 字段 | 含义 |
-|------|------|
-| `mid` | 用户 UID |
-| `aid / bvid` | 视频 ID（av 号 / bv 号） |
-| `cid` | 视频分 P ID |
-| `uname / upname` | up 主昵称 |
-| `view / danmaku / reply / favorite / coin / share / like` | 各类计数 |
-| `pubdate / ctime` | 发布/创建时间（秒级 unix） |
-
----
-
-## tonghuashun（同花顺）
-
-域名：`q.10jqka.com.cn` / `d.10jqka.com.cn` / `data.10jqka.com.cn`
-
-同花顺多数接口返回 HTML 表格，需要 DOM 解析。JSONP 接口要设 `Referer: http://q.10jqka.com.cn/`，否则返回空。
-
-| 字段（API） | 含义 |
-|------|------|
-| `openPrice / closePrice` | 开/收盘 |
-| `zdf` | 涨跌幅 % |
-| `hsl` | 换手率 |
-| `zf`  | 振幅 |
-
----
-
-## 字段不在词典时
-
-看 `field-decode-playbook.md`。里面是标准 SOP（排序键对比、结构差分、精度排查），10 分钟能推一条。
+Rules:
 
-推完一个代号补回本文件，下次直接查。
+- Append new field-code meanings.
+- Do not overwrite an existing meaning without visible-page proof.
+- If two sources disagree, trust the visible page and record the conflict in `notes.md`.
+- When a code is unknown, use `field-decode-playbook.md`.

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

@@ -1,181 +1,95 @@
 # Field Decode Playbook
 
-响应里出现 `f237 / zdf / oc5 / x4` 这种看不懂的代号时走这套流程。目标：10 分钟内搞定一条未知字段，不靠猜。
+Use this when a response contains unclear field names or numeric codes.
 
-适用于 `field-conventions.md` 没收录的站点、没收录的代号、或者收录了但怀疑对不上的情况。
+## First Pass
 
----
+1. Save a response sample in `~/.webcmd/sites/<site>/fixtures/` after removing cookies, tokens, and private user data.
+2. Identify which fields are self-explanatory.
+3. Check `field-conventions.md` and `~/.webcmd/sites/<site>/field-map.json`.
+4. Compare at least one row against the visible page.
 
-## 决策树
+Do not guess a field meaning and ship it as a polished column.
 
-```
-拿到一条响应，有字段看不懂？
-├── 字段值是字符串 / 时间 / 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 回浏览器验证
-webcmd browser eval "window.location.origin + '/<path>'"
-```
-
----
-
-## §2 排序键对比法（数字类核心手段）
-
-数字字段是最容易踩坑的一类——看起来都是小数，但可能是涨跌幅、换手率、振幅、溢价率、市盈率……单位和量级也可能带陷阱。
+## Technique 1 - Sort-Key Comparison
 
-### 流程
+Change the site's sort order in the UI, or change known query params, then compare response fields.
 
-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
-   webcmd browser eval "fetch('<url>&fid=f2&po=1').then(r=>r.json()).then(d=>d.data.diff.slice(0,3))"
-   webcmd 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
-   webcmd browser eval "fetch('<url>&fid=f6&po=1').then(r=>r.json()).then(d=>d.data.diff.slice(0,3))"  # 成交额
-   ```
-
-   对照网页上"成交额排行"的前三名。对得上就认。
-
-### 实例：推 f237（可转债溢价率）
+Example workflow:
 
 ```bash
-# 按价格排，拿一条观察
-webcmd 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 排
-webcmd browser eval "fetch('...&fid=f237&po=1...').then(...)"
-# 第一条变了，f237 值变成 400+
-
-# 打开 eastmoney 可转债页，切"溢价率"排序，第一条的溢价率确实是 400+ —— f237 就是溢价率 %
+webcmd browser open <url>
+webcmd browser wait xhr '<endpoint-fragment>'
+webcmd browser network --format json
 ```
 
----
-
-## §3 结构差分法（数组 / 嵌套对象类）
-
-响应顶层是 `{data: {diff: [...]}}` 还是 `{list: [{...}, {...}]}` 还是 `{rows: [{k:v}, ...]}`，不同接口差别大。
-
-### 流程
-
-1. **先数一次嵌套路径**
-
-   ```bash
-   webcmd browser eval "fetch('<url>').then(r=>r.json()).then(j=>({keys:Object.keys(j), type:Array.isArray(j)?'array':'object'}))"
-   ```
+Look for fields that move with:
 
-2. **一层一层剥**
+- rank
+- date
+- score
+- price
+- volume
+- rating
+- comment count
 
-   ```bash
-   webcmd 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]]}})"
-   ```
+If sorting by "newest" changes field `created_at`, that field is likely timestamp-like. If sorting by "comments" changes field `num_comments`, that field is likely a comment count.
 
-3. **数数组长度对照 pz / pageSize**
+## Technique 2 - Visible-Value Matching
 
-   如果请求 `pz=20` 拿回的数组正好 20，那就是结果数组；如果是 1 那可能是 pagination meta。
+Pick a row with distinctive values on the page, then locate matching values in the response.
 
-4. **同一字段在不同条目间是否变化**
+Use distinctive anchors:
 
-   ```bash
-   # 取前三条的 keys，看哪些 key 的值在变（业务数据），哪些不变（常量/配置）
-   webcmd 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})))"
-   ```
+- uncommon title text
+- exact count
+- exact price
+- exact date
+- unique username
+- canonical URL slug
 
----
+Avoid common values such as `0`, `1`, `true`, `false`, and repeated category names.
 
-## §4 常量 / 精度位排查
+## Technique 3 - Structural Diff
 
-有的字段每条都一样，是精度指示器或类型标记。
+Fetch two similar pages or two different query params, then compare response shapes.
 
-| 典型现象 | 通常含义 | 处理 |
-|---------|---------|------|
-| 每条值都是 `2` 或 `3` | 精度位数（小数几位） | 除以 `10^n` 还原浮点 |
-| 每条值都是 `0` 或 `1` | 涨跌方向 / 停牌标记 | 枚举，查同类 adapter |
-| 每条值都是 `6` / `8` / `80` | 市场代号 / 分类 ID | 查 `field-conventions.md` 市场表 |
-| 每条值都是空字符串 | 接口不返回但字段有占位 | 请求里去掉 / 用别的字段 |
+Useful differences:
 
-**eastmoney 精度坑**：不传 `fltt=2` 时，价格字段是 `int * 10^f152`。所以一律加 `fltt=2`，避免所有除法问题。
+- same query with different sort
+- same endpoint with different page number
+- same entity with expanded details
+- logged-in versus logged-out state when allowed
 
----
+Fields that change with the entity are likely content fields. Fields that stay constant across unrelated entities are likely config, experiment, or metadata.
 
-## §5 写完要做的事
+## Technique 4 - Constant Checks
 
-推出一个新代号后：
+Before mapping a field, check whether it is constant across rows.
 
-1. **补进 `references/field-conventions.md`**：找到对应站点的表格加一行。下次直接查。
-2. **在 adapter 代码里留一条注释**：如果是实测推出来的不常见代号，写一行 `// f237 = convertible premium rate (verified 2026-04-20 against page)` 方便复核。
-3. **通过 `webcmd browser verify` 验一次**：字段值能对上网页上眼见的数字。
+- If a field is constant across all rows, it may be source metadata, locale, currency, or feature flag.
+- If a field is null for most rows, it may be optional. Use a union type only when that optionality is real.
+- If a field changes only with the request, it may be a query echo rather than a row value.
 
----
+## Technique 5 - Unit Checks
 
-## §6 通用坑
+Common silent failures:
 
-| 坑 | 症状 | 解 |
-|----|------|-----|
-| 单位"万"当"元"用 | 成交额少 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)` 显式转 |
+- value differs by 100 because the source already uses decimal percentages
+- value differs by 1,000 or 10,000 because source units are compacted
+- timestamps are seconds versus milliseconds
+- money lacks currency
+- local time is parsed as UTC
 
----
+Record unit decisions in `output-design.md` style notes or site memory.
 
-## §7 真推不出来
+## When Still Unsure
 
-三条兜底：
+If a field remains unclear:
 
-1. **找同站点已有的 adapter** — `ls clis/<site>/` 翻文件，别站点邻居的 adapter 通常共享字段命名
-2. **找开源实现** — GitHub 搜 `<域名> fields` 或 `<域名> api`，往往有 Python / Go 库已经解码过
-3. **灰度**：把这条字段先输出成 raw，命令仍可用，下一版再语义化
+- Expose it as a clearly named raw field only if users need it.
+- Otherwise omit it from final columns.
+- Add a note to `~/.webcmd/sites/<site>/notes.md`.
+- Keep the fixture so the next decoding pass starts from evidence.
 
-不要猜。猜错了后面验证不到、线上跑出来用户看到乱码也会误导决策。
+Never silently map an unknown field to a confident business name.