opencli-repair

OpenCLI Repair — AI 驱动的适配器自修复

当网站的 DOM、API 或认证流程发生变化导致适配器失效时，使用此 Skill 诊断故障并修补适配器。

前置条件

opencli doctor    # Verify extension + daemon connectivity

何时使用此 Skill

当 opencli <site> <command> 出现以下错误时使用：

• SELECTOR — 找不到元素（DOM 已变化）
• EMPTY_RESULT — 未返回数据（API 响应已变化）
• API_ERROR / NETWORK — 端点已迁移或失效
• PAGE_CHANGED — 页面结构不再匹配
• COMMAND_EXEC — 适配器逻辑中出现运行时错误
• TIMEOUT — 页面加载方式不同，适配器等待了错误的内容

第 1 步：收集诊断上下文

在启用诊断模式的情况下运行失败的命令：

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

这会在 stderr 中的 ___OPENCLI_DIAGNOSTIC___ 标记之间输出一个 RepairContext JSON：

{
  "error": {
    "code": "SELECTOR",
    "message": "Could not find element: .old-selector",
    "hint": "The page UI may have changed."
  },
  "adapter": {
    "site": "example",
    "command": "example/search",
    "sourcePath": "/path/to/clis/example/search.ts",
    "source": "// full adapter source code"
  },
  "page": {
    "url": "https://example.com/search",
    "snapshot": "// DOM snapshot with [N] indices",
    "networkRequests": [],
    "consoleErrors": []
  },
  "timestamp": "2025-01-01T00:00:00.000Z"
}

解析它：

# Extract JSON between markers from stderr output
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 已过期	使用 operate 走一遍登录流程
TIMEOUT	页面加载方式变化，出现加载动画/懒加载	添加或更新等待条件
PAGE_CHANGED	大幅重新设计	可能需要完全重写适配器

需要回答的关键问题：

1. 适配器想要做什么？（阅读 source 字段）
2. 失败时页面是什么样子？（阅读 snapshot 字段）
3. 发生了哪些网络请求？（阅读 networkRequests）
4. 适配器的预期与页面实际提供的内容之间存在什么差距？

第 3 步：探索当前网站

使用 opencli operate 检查线上网站。切勿使用已损坏的适配器——它只会再次失败。

DOM 已变化（SELECTOR 错误）

# Open the page and inspect current DOM
opencli operate open https://example.com/target-page && opencli operate state

# Look for elements that match the adapter's intent
# Compare the snapshot with what the adapter expects

API 已变化（API_ERROR、EMPTY_RESULT）

# Open page with network interceptor, then trigger the action manually
opencli operate open https://example.com/target-page && opencli operate state

# Interact to trigger API calls
opencli operate click <N> && opencli operate network

# Inspect specific API response
opencli operate network --detail <index>

认证已变化（AUTH_REQUIRED）

# Check current auth state
opencli operate open https://example.com && opencli operate state

# If login page: inspect the login form
opencli operate state  # Look for login form fields

第 4 步：修补适配器

阅读适配器源文件并进行有针对性的修复：

# Read the adapter
cat <sourcePath from diagnostic>

常见修复

更新选择器：

// 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"]')

修补规则

1. 做最小化修改——只修复已损坏的部分，不要重构
2. 保持相同的输出结构——columns 和返回格式必须保持兼容
3. 优先使用 API 而非 DOM 抓取——如果在探索中发现 JSON API，就切换过去
4. 仅使用 @jackwener/opencli/* 导入——切勿添加第三方包导入
5. 修补后进行测试——再次运行命令以验证

第 5 步：验证修复

# Run the command normally (without diagnostic mode)
opencli <site> <command> [args...]

如果仍然失败，返回第 3 步进一步探索。如果网站发生了根本性变化（大幅重新设计、功能被移除），请报告该适配器需要完全重写。

何时放弃

并非所有故障都能通过快速补丁修复：

• 网站要求验证码（CAPTCHA）——无法自动化处理
• 功能已被完全移除——数据已不存在
• 大幅重新设计——需要通过 opencli-explorer Skill 完全重写适配器
• 被限流 / IP 被封禁——不属于适配器问题

在这些情况下，应向用户清楚说明情况，而不是进行无效的补丁尝试。

示例修复会话

1. User runs: opencli zhihu hot
   → Fails: SELECTOR "Could not find element: .HotList-item"

2. AI runs: OPENCLI_DIAGNOSTIC=1 opencli zhihu hot 2>diag.json
   → Gets RepairContext with DOM snapshot showing page loaded

3. AI reads diagnostic: snapshot shows the page loaded but uses ".HotItem" instead of ".HotList-item"

4. AI explores: opencli operate open https://www.zhihu.com/hot && opencli operate state
   → Confirms new class name ".HotItem" with child ".HotItem-content"

5. AI patches: Edit clis/zhihu/hot.ts — replace ".HotList-item" with ".HotItem"

6. AI verifies: opencli zhihu hot
   → Success: returns hot topics