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

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

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 文案给所有合法值，别让用户猜：

{ 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。