opencli-adapter-author

适配器编写

选择能够可靠完成所需任务的最简单实现。 如果现有站点适配器已支持所需能力，请直接使用：

opencli list search --site example
opencli example search --help -f json

list 返回 {ok:true,data:{commands,total,nextOffset?}}；使用 --offset 继续获取，使用 --limit 调整分页大小。详细参数请查看命令帮助。

可用证据

opencli browser open https://example.com --session research
opencli browser state --diagnostics --session research
opencli browser network --session research
opencli browser network --static --session research
opencli browser network --detail RequestKey --session research

网络捕获记录已观察到的请求。静态分析会在不执行脚本的情况下，从已加载的脚本中补充候选项。请检查源码位置、未解析的表达式和捕获来源。必要时重放读取请求，并将业务数据与页面进行比较。写入命令会产生真实影响，通过 adapter test 运行时也一样；请使用合适的测试账号或受支持的试运行功能。

如果有稳定契约的公开 API，优先使用。浏览器 fetch、捕获的响应、页面状态和语义化 UI 交互也都是有效选择。请根据任务和观察到的可靠性进行选择。不要猜测端点参数，也不要将失败的操作伪装成空的成功结果。

JS 接口

适配器是普通文件，位于 ~/.opencli/clis/<site>/<command>.js 或仓库中的 clis/<site>/ 下。没有草稿目录、晋升步骤或必需的记忆文件。

opencli adapter init example/search

现有的 cli({...}) 接口保持不变：Node 执行使用 func(args)，浏览器执行使用 func(page, args) 并设置 browser: true。请复用相邻的适配器和共享辅助工具。返回业务数据；CLI 会添加 JSON 成功封装。失败时，抛出带有可操作提示的类型化错误。请准确设置 access: 'read'|'write'。columns 控制人类可读的表格导出；JSON 会保留嵌套结果。

import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'example', name: 'search', description: 'Search example items',
  access: 'read', strategy: Strategy.PUBLIC, browser: false,
  args: [{ name: 'query', positional: true, required: true }],
  func: async (args) => {
    const response = await fetch(`https://example.com/api/search?q=${encodeURIComponent(args.query)}`);
    if (!response.ok) throw new Error(`Search failed: HTTP ${response.status}`);
    return response.json();
  },
});

检查和运行

opencli adapter check example/search
opencli example search 'query'
opencli adapter test example/search --args '{"query":"query"}'

check 会验证定义，但不会执行适配器。test 会执行常规 CLI，并可选择与现有夹具进行比较。--write-fixture、--update-fixture 和 --no-fixture 用于控制可选的预期结果；不会强制检查行结构或站点记忆。--trace retain-on-failure 有助于诊断浏览器执行问题。

对于仓库变更，请通过针对性生产路径测试覆盖核心行为和失败情况，并运行类型检查和构建。验证与任务相关的 ID、字段、单位、分页以及空结果和错误语义。对于结果未知的写入操作，不要自动重放；请先检查状态。

可选参考资料

只阅读当前任务所需的内容：references/adapter-template.md 介绍适配器模式，api-discovery.md 介绍请求调查，output-design.md 介绍结果字段，field-decode-playbook.md 介绍不透明字段，deep-recon.md 介绍复杂的私有协议。站点说明和夹具是可选的知识辅助资料；较早的参考清单不是必需的工作流。