OpenCLI 适配器编写指南
从零开始，在 30 分钟内为任意网站编写并通过验证的 OpenCLI 适配器。
证据：技能明确边界，不教破解签名、验证码、风控（coverage-matrix.md），要求只复用页面已合法获得的数据；提供策略选择的证据纪律和 typed errors 防止静默失败；强调不保存凭证、脱敏存储，回写前需验证。扣分：缺少用户确认机制（如执行高风险操作前确认），依赖登录态可能涉及敏感数据，但未明确最小权限范围和权限升级；publisher 未验证，归属和更新责任不清晰。
证据：详细的 runbook 和降级路径，结构清晰；引用真实 PR（#1329、#1312 等）和 adapter 实例；异常处理分类明确。扣分：无可见测试套件或 CI 证据覆盖 key paths；未被执行的静态审查无法验证命令是否可复现；大量依赖外部站点和浏览器状态，不确定性高。
证据：明确的目标用户（编写 adapter 的 AI agent）、适用场景和快速自测（coverage-matrix.md 三个问题）；提供不支持列表；语义触发条件清晰。扣分：有效性依赖海外服务（如 GitHub、npm 包、Chrome Web Store），在中国大陆网络环境下可能受限，未提供替代方案。
证据：文档结构清晰，有进阶披露（runbook、参考资料），安装/依赖说明存在，参数和命名规则明确，多个示例，已知限制和边界（coverage-matrix.md），Apache-2.0 许可证，引用众多 PR 和文件表明维护活跃。扣分：无版本号或更新日志，贡献者维护责任未明确，依赖上游项目但未说明更新路径。
证据：描述清晰，目标明确（30分钟内闭环）；有多个 adapter 实例和 fixture 模式，说明输出格式可直接使用；引用 PR 合并证据。扣分：未提供可验证的端到端示例或第三方执行证据，静态评估无法确认实际完成度；输出直接可用性未验证。
证据：文中引用真实 PR、adapter 文件和 fixture 文件，可作为审计材料；策略选择和字段解码有证据要求。扣分：未提供可运行的测试或 CI 证据；静态审查无法独立复现核心路径；缺少跨来源佐证（除作者自身报告外）。
- 核心功能依赖海外服务（GitHub、npm、Chrome Web Store），中国大陆网络环境下可能无法访问，需提前准备替代方案或镜像。
- 技能要求复用用户登录态，若处理敏感数据，需确保用户明确授权并注意最小权限原则。
- 未提供版本和更新日志，使用时需注意维护责任不明确，依赖上游项目变更可能影响稳定性。
- 静态审查无法验证实际执行效果，建议在真实环境中验证后再采用。
这个 Skill 能做什么，适合哪些场景？
这份技能指导你为新的网站编写 OpenCLI 适配器，或为已有站点添加命令。它提供完整的工作流程：侦察、API 发现、策略选择、字段解码、编码和验证。它强调基于外部契约选择数据来源策略（公开 API、cookie、UI 选择器等），并提供了详细的决策树和失效降级路径。该技能使用 `opencli browser` 系列命令完成整个过程，并要求使用站点记忆库来加速后续适配。它专为 OpenCLI 生态设计，适合希望在 OpenCLI 框架内为网站构建 CLI 接口的开发者。
运行 opencli doctor 检查环境，读取本地站点记忆（endpoints.json、notes.md），使用 opencli browser analyze 进行站点侦察，通过 opencli browser network、state 抽取、bundle 搜索或拦截发现 API 端点，直接 fetch 验证端点，根据契约级别选择策略并记录策略说明，解码字段（使用 field-conventions 或 decode-playbook），使用 opencli browser init 生成 adapter 骨架，使用 opencli browser verify 验证并生成 fixture，最后将端点、字段映射和笔记写回 ~/.opencli/sites/。
- 开发者需要为 OpenCLI 未覆盖的新网站（如企业内部系统）添加 CLI 命令。
- 开发者需要为已有 adapter 的网站添加新命令（例如为 Bilibili 增加'关注列表'命令）。
- 开发者需要修复因网站改版而失效的 adapter，需要重新侦察和调整数据来源。
- 开发者需要将稳定的 UI/DOM 数据抓取迁移到更稳定的公开 API，但需评估契约稳定性。
- AI Agent 需要将网站操作封装成可复用的 CLI 接口，供后续自动化使用。
这个 Skill 有哪些优点和局限？
- 提供从侦察到验证的完整、结构化流程，降低随机性。
- 强调数据源契约的稳定性，有助于减少维护成本。
- 具有详细的降级路径和故障排除指南。
- 通过站点记忆库加速后续 adapter 开发。
- 专为 OpenCLI 生态设计，依赖其特定命令和工具。
- 需要先安装和配置 OpenCLI 运行环境及浏览器扩展。
- 对于简单数据抓取可能过于繁琐。
- 未提供测试套件或示例 adapter 的完整代码。
如何安装这个 Skill？
该技能是 OpenCLI 仓库的一部分。安装整个技能集合：npx skills add jackwener/opencli，或仅安装此技能：npx skills add jackwener/opencli --skill opencli-adapter-author。需要先安装 OpenCLI 运行时（如 OpenCLIApp 或 npm install -g @jackwener/opencli，需 Node.js 20+）和浏览器桥接扩展。
如何使用这个 Skill？
确保 opencli doctor 通过。阅读技能中的前置检查（coverage-matrix）。按照 runbook：侦察站点、发现 API、编写策略说明、解码字段、使用 opencli browser init <site>/<name> 初始化 adapter、使用 opencli browser verify <site>/<name> 验证。遵循技能中的决策树和降级路径。参考 references/ 目录下的详细文档。
这个 Skill 与同类方案有什么区别？
与同仓库的 opencli-browser 技能相比，它专注于编写可复用的 adapter，而不是临时驱动浏览器。