SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场qiaomu-opencli-autofix

qiaomu-opencli-autofix

编程与开发

查看项目

更新于 10-15 10:54

技能介绍

用途

OpenCLI AutoFix 用于自动修复因网站改版而失效的 OpenCLI 适配器。当某条 opencli 命令因为网站改动了 DOM、API 或响应结构而失败时，该技能引导完成诊断、修复适配器并重试，而不是仅报告错误。

适用错误类型

适用于 opencli <site> <command> 出现以下可修复错误时：

  • SELECTOR —— 元素未找到（DOM 变化）
  • EMPTY_RESULT —— 未返回数据（API 响应变化）
  • API_ERROR / NETWORK —— 端点迁移或损坏
  • PAGE_CHANGED —— 页面结构不再匹配
  • COMMAND_EXEC —— 适配器逻辑运行时错误
  • TIMEOUT —— 页面加载方式变化，适配器等待对象错误

前置条件

运行 opencli doctor 以验证扩展与守护进程（daemon）连接。

进入修复前的判断："空" ≠ "坏"

EMPTY_RESULT（有时还包括结构合法但返回空的 SELECTOR）往往不是适配器 bug。平台会在反爬启发式下主动降级结果，网站返回的“未找到”不代表内容真的缺失。在开始修复前应先排除：

  • 用替代查询或入口重试。例如 opencli xiaohongshu search "X" 返回 0，但 opencli xiaohongshu search "X 攻略" 返回 20，说明适配器正常，只是平台对首个查询做了结果塑形。
  • 在普通 Chrome 标签页中抽查。若用户在浏览器中能看到数据而适配器返回空，通常是认证状态、限流或软封锁问题，应使用 opencli doctor / 重新登录，而不是改源码。
  • 识别软 404。小红书 / 微博 / 抖音等站点在内容被隐藏或删除时返回 HTTP 200 加空载荷而非真正 404，快照结构看起来正常。等 2–3 秒重试常可区分“暂时隐藏”与“确实消失”。
  • 搜索结果“0 条”也是一种答案。若适配器成功到达搜索端点、拿到 HTTP 200 且平台返回 results: []，这是有效结果，应告知用户“该查询无匹配”，而非修补适配器。

只有在空结果 / 选择器缺失在多次重试和替代入口下均可复现时，才进入第 1 步。

修复流程

第 1 步：采集诊断上下文。以诊断模式运行失败命令：

OPENCLI_DIAGNOSTIC=1 opencli <site> <command> [args...] 2>diagnostic.json

该命令会在 stderr 的 OPENCLI_DIAGNOSTIC 标记之间输出 RepairContext JSON，包含 error（code、message、hint）、adapter（site、command、sourcePath、source）、page（url、snapshot、networkRequests、consoleErrors）以及 timestamp。可用以下方式提取：

cat diagnostic.json | sed -n '/___OPENCLI_DIAGNOSTIC___/{n;p;}'

第 2 步：分析失败。读取诊断上下文与适配器源码，判定根因并选择修复策略：

  • SELECTOR：DOM 重构、class/id 改名 → 探查当前 DOM，寻找新选择器
  • EMPTY_RESULT：API 响应结构变化或数据位置迁移 → 查看网络请求，寻找新的响应路径
  • API_ERROR：端点 URL 变化、需要新参数 → 通过网络拦截发现新 API
  • AUTH_REQUIRED：登录流程变化、cookie 过期 → 停止，提示用户登录，不要改代码
  • TIMEOUT：页面加载方式变化、加载动画/懒加载 → 添加或更新等待条件
  • PAGE_CHANGED：重大改版 → 可能需整体重写适配器

需回答的关键问题：适配器想做什么（source 字段）、失败时页面是什么样（snapshot 字段）、发生了哪些网络请求（networkRequests）、适配器期望与页面实际之间的差距在哪里。

第 3 步：探查当前网站。使用 opencli browser 检查线上站点，不要使用已损坏的适配器。DOM 变化时：

opencli browser open https://example.com/target-page && opencli browser state

API 变化时，开启网络拦截后再手动触发操作：

opencli browser open https://example.com/target-page && opencli browser state
opencli browser click <N> && opencli browser network
opencli browser network --detail <index>

第 4 步：修补适配器。读取 RepairContext.adapter.sourcePath 指定的文件并做定点修复；该路径是权威位置，可能在仓库的 clis/ 下，也可能在 npm 安装的 ~/.opencli/clis/ 下。

cat <RepairContext.adapter.sourcePath>

常见修复示例（保持代码原样）：

  • 选择器更新：

    // Before: page.evaluate('document.querySelector(".old-class")...') // After: page.evaluate('document.querySelector(".new-class")...')

  • API 端点变更：

    // Before: const resp = await page.evaluate(fetch('/api/v1/old-endpoint')...) // After: const resp = await page.evaluate(fetch('/api/v2/new-endpoint')...)

  • 响应结构变更：

    // Before: const items = data.results // After: const items = data.data.items // API now nests under "data"

  • 等待条件更新：

    // Before: await page.waitForSelector('.loading-spinner', { hidden: true }) // After: await page.waitForSelector('[data-loaded="true"]')

修补规则：做最小改动，只修坏的部分，不要重构；保持输出结构不变，列和返回格式必须兼容；优先使用 API 而非 DOM 抓取，若探查中发现 JSON API 就切换过去；只使用 @jackwener/opencli/* 导入，绝不添加第三方包导入；修补后要测试，再次运行命令验证。

第 5 步：验证修复。正常运行命令（不带诊断模式）：

opencli <site> <command> [args...]

若仍失败，回到第 1 步采集新诊断。修复预算为 3 轮（诊断 → 修复 → 重试）。若修复后同一错误持续出现，尝试不同思路。3 轮后停止并报告已尝试的内容。

安全边界与停止条件

开始任何修复前检查硬性停止条件：

  • AUTH_REQUIRED（退出码 77）—— 停止。不要修改代码。提示用户在 Chrome 中登录该站点。
  • BROWSER_CONNECT（退出码 69）—— 停止。不要修改代码。提示用户运行 opencli doctor。
  • CAPTCHA / 限流 —— 停止。这不是适配器问题。

作用域约束：

  • 只修改 RepairContext.adapter.sourcePath 处的文件，这是权威适配器位置（仓库中可能是 clis/<site>/，npm 安装为 ~/.opencli/clis/<site>/）
  • 绝不修改 src/、extension/、tests/、package.json 或 tsconfig.json
  • 重试预算：每次失败最多 3 轮修复。若 3 轮诊断 → 修复 → 重试仍未解决，停止并报告已尝试内容

硬停止（不修改代码）：AUTH_REQUIRED / BROWSER_CONNECT 属于环境问题而非适配器 bug；站点要求验证码无法自动化；被限流 / IP 封锁不属于适配器问题。

软停止（尝试后报告）：3 轮修复用尽；功能被彻底移除，数据已不存在；重大改版需要借助 opencli-explorer 技能整体重写适配器。所有停止场景都应向用户清晰说明情况，而不是做无效的修补。

示例修复过程

  1. 用户运行 opencli zhihu hot，失败：SELECTOR "Could not find element: .HotList-item"
  2. AI 运行 OPENCLI_DIAGNOSTIC=1 opencli zhihu hot 2>diag.json，获得包含 DOM 快照的 RepairContext
  3. AI 读取诊断：快照显示页面已加载，但使用的是 ".HotItem" 而非 ".HotList-item"
  4. AI 探查：opencli browser open https://www.zhihu.com/hot && opencli browser state，确认新类名 ".HotItem" 及子元素 ".HotItem-content"
  5. AI 修补：编辑 RepairContext.adapter.sourcePath 处的适配器，将 ".HotList-item" 替换为 ".HotItem"
  6. AI 验证：运行 opencli zhihu hot，成功返回热榜话题

限制

除上述错误类型与硬性停止条件外，该技能的收费、价格、平台支持范围等信息暂未提供。