opencli-repair

用途

OpenCLI Repair 是一个 AI 驱动的适配器自修复技能。当某个 OpenCLI 适配器因为目标网站更改了 DOM、API 或认证流程而失效时，使用该技能来诊断失败原因并修补适配器。

前置条件

运行以下命令验证扩展与守护进程（daemon）的连通性：

opencli doctor

何时使用

当 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	页面加载方式不同，出现 spinner/懒加载	添加/更新等待条件
PAGE_CHANGED	重大改版	可能需要完全重写适配器

需要回答的关键问题：

适配器试图做什么？（阅读 source 字段）
失败时页面是什么样子？（阅读 snapshot 字段）
发生了哪些网络请求？（阅读 networkRequests）
适配器期望的内容与页面实际提供的内容之间差距在哪里？

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

修补规则：

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

第 5 步：验证修复

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

如果仍然失败，回到第 3 步继续探索。如果网站已发生根本性变化（重大改版、功能移除），则报告该适配器需要完全重写。

何时放弃

并非所有失败都能通过快速修补修复：

网站需要 CAPTCHA——无法自动化
功能被完全移除——数据已不存在
重大改版——需要通过 opencli-explorer 技能完全重写适配器
被限流 / IP 被封——不是适配器问题

在这些情况下，应向用户清楚说明情况，而不是做无用的修补。

示例修复会话

用户运行：opencli zhihu hot → 失败：SELECTOR "Could not find element: .HotList-item"
AI 运行：OPENCLI_DIAGNOSTIC=1 opencli zhihu hot 2>diag.json → 获得包含 DOM 快照的 RepairContext，显示页面已加载
AI 阅读诊断：快照显示页面已加载，但使用的是 ".HotItem" 而不是 ".HotList-item"
AI 探索：opencli operate open https://www.zhihu.com/hot && opencli operate state → 确认新类名 ".HotItem" 及其子元素 ".HotItem-content"
AI 修补：编辑 clis/zhihu/hot.ts——将 ".HotList-item" 替换为 ".HotItem"
AI 验证：opencli zhihu hot → 成功：返回热门话题

适用场景

适用于 OpenCLI 适配器因目标网站变更而失效时的诊断与修复，尤其是 DOM 选择器变更、API 端点或响应结构变更、认证流程变更、页面加载方式变更等场景。

限制

网站需要 CAPTCHA 时无法自动化修复
功能被完全移除时无法修复
重大改版可能需要完全重写适配器
被限流或 IP 被封不属于适配器问题
修补时必须保持输出结构兼容，且只能使用 @jackwener/opencli/* 导入