开发工具CLI人工智能AI 应用浏览器控制GUI 自动化【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址https://gitcode.com/gh_mirrors/ope/OpenCLI点击查看免费下载本文是 OpenCLIskills/opencli-adapter-author中面向 adapter 作者的输出设计规范详解核心讲解 adapter 声明的columns数组——也就是 CLI 表格输出与下游消费的数据结构契约。读完本文你将掌握为什么columns不能随便列、camelCase 命名与类型/单位约定、识别列→业务数字→metadata 三段式排布、单条 ≤15 列的控量手段以及如何对齐邻居 adapter、避免常见错误并理解仓库内置的 convention audit 如何把这份规范变成机器检查。文中所有结论均对照仓库源码src/registry.ts、src/output.ts、src/convention-audit.ts、clis/eastmoney/convertible.js与实际测试印证。一、columns是什么不只是表格表头而是数据契约在 OpenCLI 中一份 adapter 就是一次cli({...})调用其中columns是声明里独立于func的一个数组字段类型为columns?: string[]见 src/registry.ts 的 CLI 声明接口。它有两重身份渲染层的表头来源默认输出格式下表格的列头、Markdown 表头、CSV 列名都取自columns。在 src/output.ts 中resolveColumns的取值逻辑是opts.columns ?? Object.keys(rows[0] ?? {})——也就是说adapter 声明了columns就按声明渲染没声明才退化为看第一行的 key。而renderTable还会对列头做capitalize首字母大写展示因此marketCap会显示为MarketCap。下游消费的结构契约adapter 的输出会被用户直接阅读、被其他 adapter 合并、被 agent 做后续分析。columns一旦定下就是这些消费方读取数据的依据。正如原文档开篇所述adapter 的columns不是随便列要让下游用户、其他 adapter 合并、agent 后续分析都能直接读。此外columns的顺序直接决定输出表格的列顺序——func返回对象的 key 顺序与columns必须一致这一点在 adapter-template.md 中被列为硬性规则columns数组必须跟func返回的 object keys 完全对上顺序也一致并有专门的机器审计兜底详见本文第八节。二、核心约定一命名 —— camelCase全英文命名总则所有列名使用camelCase 全英文。原文档给出的对照好差marketCapmarket_cap/市值/MarketCapchange24hPctchange_percentage_24h/涨跌幅24h/changePct_24hbondCodebond_code/BOND_CODEpubTimepublish_time/pubdate中英混写、大小写混乱、下划线风格、口语化缩写都会让下游解析和合并成本剧增——统一 camelCase 是让任何 adapter 的输出都能被任何消费方读懂的前提。缩写约定缩写含义典型列名pct百分比percentchangePct/convPremiumPctpe市盈率peTtm等pb市净率pbytm到期收益率ytmid标识符postId/threadId时间后缀Time具体时刻如pubTime、updateTimeDate日期如listDate、issueDateTsunix 秒时间戳如pubTs百分比一律Pct结尾百分比字段必须用Pct后缀且数值是已乘 100的形式2.5表示 2.5%不是0.025。这与 field-conventions.md 中对 eastmoneyf3涨跌幅 %、f237转股溢价率等字段的解读一致——convertible.js中bondChangePct、convPremiumPct直接透传接口返回的×100 后数值。数量后缀Count整数计数如commentCount、replyCountTotal累计值如totalVolume、amountTotal三、核心约定二类型与格式 —— 每个字段的 JS 类型都有明确约束字段类JS 类型格式要求价格 / 金额number原始小数别除 1000、别取整百分比number已 × 1002.5 2.5%计数 / ranknumber正整数代码 / id / symbolstring股票代码600000要保留前导 0名称 / 标题string去首尾空白时间stringISO2024-01-15T10:30:00Z或numberunix 秒不要本地字符串2024/1/15布尔boolean不用0/1URLstring绝对路径相对路径要拼 host特殊规则缺失用null不用0/0和空字符串在业务语义上可能是有效值比如涨跌幅恰好为 0、标题恰好为空混用会让下游无法区分没有这个数据与数据就是 0。这一点与 adapter-template.md 中某列永远是null时优先回查字段路径的调试指引呼应——null是字段没取到的信号0是数值为 0的业务事实。枚举 → string不要 int 代号listed比0清楚得多。int 代号只有站点内部字典能解释一旦脱离字典就无法自明。从渲染层看src/output.ts 的renderTable在展示时会统一String(v)并处理null/undefined为空串但 JSON / YAML / CSV 输出则是原样透出——也就是说类型错误会在 JSON 场景下原形毕露绝不能在数据层妥协。四、核心约定三顺序 —— 固定三段式排布columns的排列顺序固定为三段[识别列 ...] [业务数字 ...] [metadata ...]识别列前 1-3 列rank / symbol / code / bondCode / name / title / id。这是用户第一眼要看到的定位信息。业务数字中间价格、涨跌幅、成交量、市值等业务语义字段。metadata最后 1-3 列pubTime / updateTime / source / url。该顺序在 src/output.ts 的表格渲染中会被直接落实为列顺序同时它是 SKILL.md 中 Step 8设计 columns的 checklist 项命名 camelCase 且对齐邻居 adapter类型/单位/百分比格式清楚顺序识别列 → 业务数字 → metadata。五、核心约定四必有列 —— 按 adapter 类型决定最小集合adapter 类型必须包含排行 / 列表rank 识别列 业务数字时序 / K 线date或ts 数值详情单对象识别列 业务字段新闻 / 公告titlepubTimeurl这是最小完整性要求rank让排行可排序、可定位date/ts让时序可绘图、可对齐url让新闻可回溯原文。缺失这些列下游就无法对该类型数据做最基本的消费。六、核心约定五控量 —— 单条 ≤ 15 列单条记录最多 15 列。超出时必须主动做减法原文档给出三种处理手段拆成多个 adapter列表版少量核心列 详情版完整字段。次要字段合进extras: {...}对象把低频字段打包成一个对象列。默认隐藏只有少数用户关心的字段靠参数开关控制是否输出。仓库中 clis/eastmoney/convertible.js 是一个恰好压线的活例子它的columns共 15 列rank, bondCode, bondName, bondPrice, bondChangePct, stockCode, stockName, stockPrice, stockChangePct, convPrice, convValue, convPremiumPct, pureBondPremiumPct, putTriggerPrice, listDate识别列rank 债券/正股代码与名称在前、业务数字居中、metadatalistDate收尾字段类型与顺序完全符合本规范。可转债行情字段多也正是因为15 列上限作者选择了把行情字段收进可转债适配器本身、将完整字段留给详情类命令的设计。七、对齐邻居 adapter先 grep 再命名写新 adapter 前先看同站点现有 adapter 是怎么命名的复用同类列名不要发明平行命名grep -h columns: clis/site/*.js原文档给出的实例clis/eastmoney/convertible.js用bondCode / bondName / stockCode / stockName那么新写 eastmoney 某个涉及股票代码的 adapter 就沿用stockCode / stockName不要发明securityId / securityName。这一约定在仓库中有直接证据eastmoney 目录下 17 个 adapterclis/eastmoney共享同一套f12→code、f14→name、f2→price、f3→changePct的映射口径字段代号词典集中记录在 field-conventions.md 的 eastmoney 节如f229正股价、f232正股代码、f235转股价、f237转股溢价率。列名是站点级方言同一站点内必须一致跨站点才允许按业务差异分化。八、常见错误对照与机器审计原文档列出的常见错误表错对columns: [id, name, data.price]点路径把data.price在 func 里打平成price{date: 2024-01-15 10:30}空格 非 ISO2024-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 必须在返回对象里顺序也一致机器审计convention-audit 把规范变成 CI 检查这些约定并非只靠人肉遵守——仓库的 src/convention-audit.ts 内置了专门的审计规则camelCase-in-columns规则src/convention-audit.ts遍历每个命令声明的columns用/[a-z][A-Z]/正则检测列名中是否出现 camelCase 特征对不符合命名风格的列报违规并给出具体列名。silent-column-drop 审计auditColumnDropsrc/convention-audit.ts对比func源码里实际 emit 的 keys 与columns集合——row emits key(s) not present in columns直接对应columns 和 func 返回的 keys 对不上这条错误同时它会用findTransformedIntermediateKeys识别中间解析对象 key 与 columns 重叠的写法这正是 adapter-template.md 中警告的中间对象{pid, html, start}应改成{postId, body, offset}最后 push row 时再 destructure aliasing 回列名否则该 key 会被误判为 row 候选导致列被静默丢弃。所以columns 对不上 func 返回 keys不只是可读性问题而会被仓库的 convention audit 直接判为违规。写 adapter 时应以一次通过 audit为目标。九、description 字段用户第一眼看到的入口文案adapter 的description是用户在opencli list/opencli site -h里第一眼看到的内容要写清楚三件事数据是什么A 股涨幅排行vs大盘指数分时——一眼区分同类命令。默认行为默认按涨幅排序前 20 条——说明不带参数时会发生什么。重要参数支持 market 参数切换沪深/北证——提示关键扩展能力。不要写get data—— 废话查询 xxx 数据—— 也是废话塞完整 URL / 字段代号列表 —— 那些留给help一行 30 字左右够了。仓库实例clis/eastmoney/convertible.js的 description 是可转债行情列表默认按成交额排序——数据是什么可转债行情列表、默认行为按成交额排序一句话带全正好落在 30 字上下的区间。十、args 命名参数名也是接口的一部分args的命名同样有统一约定避免每个 adapter 发明一套同义词limit而不是count / num / n / sizesort而不是sort_by / order_by / sortKeymarket而不是exchange / platform / typesymbol/code/query根据业务选保持和邻居 adapter 一致布尔参数用enableX / includeX默认false免得给用户增加认知负担help 文案要给出所有合法值help文案必须列出全部合法取值别让用户猜{ name: sort, type: string, default: turnover, help: 排序turnover / change / drop / price / premium }仓库中的 clis/eastmoney/convertible.js 是更完整的实例args: [ { name: sort, type: string, default: turnover, help: 排序turnover / change / drop / price / premium / value / put-trigger }, { name: limit, type: int, default: 20, help: 返回数量 (max 100) }, ],其func内部对非法sort值直接抛ArgumentError并列出合法值Unknown sort ... Valid: ...与help 给全合法值形成前后呼应limit的边界校验1100 的整数也封装为可测试的parseConvertibleLimit见 convertible.test.js 对应的单测覆盖。十一、示例对比一眼看懂好坏差的columns: [股票代码, name, PRICE, change%, vol, time]问题中英混股票代码vsname、大小写乱PRICEvsname、百分号字符串change%、缩写不统一vol、时间含义不明time。好的columns: [rank, stockCode, stockName, price, changePct, volume, updateTime]识别列rank / stockCode / stockName在前metadataupdateTime在后命名统一 camelCase百分比以Pct结尾数量用全写volume。十二、把规范落到产出一份可验证的 columns 长什么样综合以上全部约定一个符合规范的 adapter 输出设计可以这样自查命名全部 camelCase 英文百分比Pct结尾时间按Time / Date / Ts区分计数Count、累计Total。类型数字就是数字价格不清零、百分比已 ×100、计数为正整数代码是保留前导 0 的 string时间是 ISO 或 unix 秒缺失一律null枚举用 string 不用 int 代号。顺序[识别列...] [业务数字...] [metadata...]三段识别列 1-3 个、metadata 1-3 个。必有列按排行/时序/详情/新闻四类检查最小集合。控量≤15 列超了拆 adapter 或收进extras/ 参数开关。对齐先grep -h columns: clis/site/*.js复用邻居命名。验证columns与func返回 keys 完全对齐含顺序中间解析对象 key 不与任何列名重叠——保证通过 src/convention-audit.ts 的camelCase-in-columns与 silent-column-drop 审计并在opencli browser verify的 verify fixture 中配好columns/types/patterns/notEmpty期望值见 adapter-template.md 的 Verify fixture 一节。columns设计是 adapter 开发流程中承上启下的一环上接字段解码field-conventions.md / field-decode-playbook.md下接opencli browser verify的结构校验verify-fixture.ts。按本文规范产出的列既能被用户一眼读懂也能被 agent、其他 adapter 和后续分析链路直接消费——这正是Make Any Website into CLI体验一致性的基础。赞分享开发工具CLI人工智能AI 应用浏览器控制GUI 自动化【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址https://gitcode.com/gh_mirrors/ope/OpenCLI点击查看免费下载相关推荐Perfetto Data Explorer 的 Modify Columns 节点列选择、重命名、排序与类型转换完全指南Perfetto Data Explorer 的 Modify Columns 节点列选择、重命名、排序与类型转换完全指南 导读 Modify Column可观测性后端开发工具前端数据可视化TypeScript类型工具命名规范ts-toolbelt的API设计哲学TypeScript类型工具命名规范ts toolbelt的API设计哲学 在TypeScript开发中类型工具库的命名一致性直接影响开发效率和代码可维护性开发工具Vector 配置规范Configuration Specification深度解析命名、类型与多态设计指南Vector 配置规范Configuration Specification深度解析命名、类型与多态设计指南 Vector 是一款高性能的可观测性数据管道可观测性数据工程数据集成日志分析上一篇掌握raylib游戏设计模式简单高效的状态管理与场景切换指南下一篇终极指南Redash数据刷新策略——增量更新与全量同步的最佳实践方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考