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 怎么命名：

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 是用户第一眼看到的，写清楚：

数据是什么："A 股涨幅排行" vs "大盘指数分时"
默认行为："默认按涨幅排序，前 20 条"
重要参数："支持 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 文案给所有合法值，别让用户猜：

{ name: 'sort', type: 'string', default: 'turnover', help: '排序：turnover / change / drop / price / premium' }

示例对比

差的：

columns: ['股票代码', 'name', 'PRICE', 'change%', 'vol', 'time']

问题：中英混、大小写乱、百分号字符串、缩写不统一。

好的：

columns: ['rank', 'stockCode', 'stockName', 'price', 'changePct', 'volume', 'updateTime']

识别列在前，metadata 在后，命名统一 camelCase。

/opencli-adapter-author

referencesoutput-design.md