如何从零写一个OpenCLI适配器TypeScript适配器完整开发教程【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLIOpenCLI 是一款把任意网站变成命令行工具的项目核心能力是让 AI Agent 复用你已登录的浏览器会话Make Any Website into CLI。本文是一份面向新手的OpenCLI 适配器完整开发教程从环境准备、策略选择、骨架生成到opencli browser verify验收带你从零写出第一个可用的适配器无需逆向、无需爬虫经验。一、适配器是什么为什么值得自己写一个OpenCLI 已内置 Bilibili、知乎、小红书、HackerNews 等上百个站点命令见clis/目录。但当你想查询自己常用的网站内部系统、小众论坛、行业门户时只需写一个适配器就能把它变成opencli 站点 命令这样一条稳定命令——人类和 AI Agent 都能直接调用。一个适配器本质上只是一次cli({...})注册调用由三部分组成部分作用类比declaration声明站点名、命令名、策略、域名身份证args / columns参数与输出列命令接受什么参数、输出哪些列接口契约func函数体真正取数并返回行数据实现官方 TypeScript 适配器开发指南在这里docs/developer/ts-adapter.md完整运行手册见 skills/opencli-adapter-author/SKILL.md。二、环境准备3 步确认桥接可用写适配器前先确认 OpenCLI 与浏览器的桥接正常安装 OpenCLI 并安装 Browser Bridge 浏览器扩展桌面端推荐 OpenCLIAppCLI 端可全局安装jackwener/opencli要求 Node.js ≥ 20.18.1在已登录目标网站的 Chrome 中保持扩展启用运行体检命令opencli doctor看到 Everything looks good 即可开工。 这一步能帮你排除 80% 的玄学失败。三、动手前最重要的一步选对策略先定策略再写代码——这是适配器开发的第一原则。OpenCLI 提供四类策略常量定义见Strategy策略适用场景维护成本PUBLIC无需登录Node 端fetch直接拿 JSON/HTML最低 ⭐COOKIE需要登录态复用浏览器 cookie低UI驱动页面交互点击、填表、发布中INTERCEPT截获页面自然发出的签名请求高官方 skill 给出的经验数据PAGE_FETCH/INTERCEPT类实现的修复频率约为公开接口的 7-8 倍。所以优先找公开/官方接口接口不可用时稳定的页面语义DOM/SSR 数据也比无契约的内部接口更可靠。判断口诀数据在浏览器里看得到吗→ 是 HTTP/JSON/HTML 吗→ 需要实时推送吗三个问题的答案决定你该不该写、怎么写。详见 skills/opencli-adapter-author/references/strategy-selection.md。四、生成骨架一行命令起步不要手写文件。用opencli browser init生成骨架再对着最相似的邻居适配器改三处命令名 / URL / 字段映射opencli browser init mysite/trending # 编辑 ~/.opencli/clis/mysite/trending.js opencli browser verify mysite/trending私人适配器放在~/.opencli/clis/站点/命令.js写完即可运行、无需构建确认稳定后如需贡献或分享再拷贝到仓库clis/站点/目录或打包成插件路径规划见 docs/guide/extending-opencli.md。五、适配器解剖看懂这份活例子以仓库中的真实适配器 clis/eastmoney/convertible.js 为例结构一目了然import { cli, Strategy } from jackwener/opencli/registry; cli({ site: eastmoney, name: convertible, description: 可转债行情列表, domain: push2.eastmoney.com, strategy: Strategy.PUBLIC, browser: false, args: [ { name: sort, type: string, default: turnover }, { name: limit, type: int, default: 20 }, ], columns: [rank, bondCode, bondName, bondPrice, /* ... */], func: async (args) { // fetch 公开接口 → 解析 → map 成与 columns 同名的行对象 return diff.slice(0, limit).map((it, i) ({ rank: i 1, bondCode: it.f12, bondName: it.f14, /* ... */ })); }, });新手只需记住 4 条铁律columns与返回对象的 keys 完全对齐含顺序它决定表格列序browser字段决定函数签名browser: false是func(args)browser: true是func(page, args)。搞反后参数会静默回退到默认值是最常见的坑参数必须给default否则命令会被拒绝启动需要登录时cookie 用page.getCookies()读别用document.cookieHttpOnly 的登录态读不到HTML 请求走 Node 侧fetchJSON 接口用内置page.fetchJson()。完整模板与 COOKIE 骨架在 skills/opencli-adapter-author/references/adapter-template.md。六、错误处理让失败可被机器理解OpenCLI 约定用类型化错误而不是裸Error或静默返回空数组五类错误定义在 src/errors.tsArgumentError—— 参数非法AuthRequiredError—— 需要登录exit code 77EmptyResultError—— 业务上合法的空结果exit code 66CommandExecutionError—— 请求/执行失败TimeoutError—— 超时为什么要这么讲究因为 autofix 自动化修复流程正是靠 exit code 决定是否重试。⚠️ 反例数据为空时返回一行暂无数据的哨兵行会让下游命令拿着空 ID 白跑一趟——直接抛EmptyResultError即可。七、验收与踩坑清单验收流程比跑通了更重要# 首轮通过后生成 fixture 种子 opencli browser verify mysite/trending --write-fixture # 手改 fixture补 patternsURL/日期/ID 正则 notEmpty核心字段 # 再跑一次确认 ✓ matches fixture opencli browser verify mysite/trending然后肉眼比对网页数值——verify 能过但数据错位的静默失败有 11 种典型形态清单见 skills/opencli-adapter-author/references/success-rate-pitfalls.md。高频坑速查现象原因与修法某列永远是null字段路径写错回到字段解码步骤数值差 10000 倍单位不统一万 vs 元百分比小 100 倍接口已返回0.025别再 ×100换中文浏览器后 0 匹配选择器锚在了aria-label/placeholder等本地化文本上应优先data-testid等稳定标识八、上手路径总结 opencli doctor确认桥接 ✅侦察站点opencli browser analyze url→ 选策略验证候选接口 → 解码字段 → 设计 columnsopencli browser init生成骨架 → 参考最像的邻居适配器改写opencli browser verify --write-fixture 肉眼比对私人使用留在~/.opencli/clis/分享则做成插件更多参考资料TypeScript 适配器指南docs/developer/ts-adapter.md适配器模板与 COOKIE 骨架skills/opencli-adapter-author/references/adapter-template.md扩展路径总览插件 / 私人适配器 / 外部 CLIdocs/guide/extending-opencli.md完整开发流程文档docs/developer/contributing.md照着走第一个适配器通常 30 分钟内就能通过 verify。祝你顺利把常用网站变成一条命令【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考