跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

opencli-autofix

Automatically fix broken OpenCLI adapters when commands fail. Load this skill when an opencli command fails — it guides you through collecting a trace artifact, patching the adapter, retrying, and filing an upstream GitHub issue after a verified fix. Works with any AI agent.

jackwener · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jackwener/OpenCLI --skill opencli-autofix

技能说明


name: opencli-autofix description: Automatically fix broken OpenCLI adapters when commands fail. Load this skill when an opencli command fails — it guides you through collecting a trace artifact, patching the adapter, retrying, and filing an upstream GitHub issue after a verified fix. Works with any AI agent. allowed-tools: Bash(opencli:), Bash(gh:), Read, Edit, Write

OpenCLI AutoFix — Automatic Adapter Self-Repair

When an opencli command fails because a website changed its DOM, API, or response schema, automatically diagnose, fix the adapter, and retry — don't just report the error.

Safety Boundaries

Before starting any repair, check these hard stops:

  • AUTH_REQUIRED (exit code 77) — STOP. Do not modify code. Tell the user to log into the site in Chrome.
  • BROWSER_CONNECT (exit code 69) — STOP. Do not modify code. Tell the user to run opencli doctor.
  • CAPTCHA / rate limiting — STOP. Not an adapter issue.

Scope constraint:

  • Only modify the file at adapterSourcePath in the trace summary.md front matter — this is the authoritative adapter location (may be clis/<site>/ in repo or ~/.opencli/clis/<site>/ for npm installs)
  • Never modify src/, extension/, tests/, package.json, or tsconfig.json

Retry budget: Max 3 repair rounds per failure. If 3 rounds of diagnose → fix → retry don't resolve it, stop and report what was tried.

Prerequisites

opencli doctor    # Verify extension + daemon connectivity

When to Use This Skill

Use when opencli <site> <command> fails with repairable errors:

  • SELECTOR — element not found (DOM changed)
  • EMPTY_RESULT — no data returned (API response changed)
  • API_ERROR / NETWORK — endpoint moved or broke
  • PAGE_CHANGED — page structure no longer matches
  • COMMAND_EXEC — runtime error in adapter logic
  • TIMEOUT — page loads differently, adapter waits for wrong thing

Before Entering Repair: "Empty" ≠ "Broken"

EMPTY_RESULT — and sometimes a structurally-valid SELECTOR that returns nothing — is often not an adapter bug. Platforms actively degrade results under anti-scrape heuristics, and a "not found" response from the site doesn't mean the content is actually missing. Rule this out before committing to a repair round:

  • Retry with an alternative query or entry point. If opencli xiaohongshu search "X" returns 0 but opencli xiaohongshu search "X 攻略" returns 20, the adapter is fine — the platform was shaping results for the first query.
  • Spot-check in a normal Chrome tab. If the data is visible in the user's own browser but the adapter comes back empty, the issue is usually authentication state, rate limiting, or a soft block — not a code bug. The fix is opencli doctor / re-login, not editing source.
  • Look for soft 404s. Sites like xiaohongshu / weibo / douyin return HTTP 200 with an empty payload instead of a real 404 when an item is hidden or deleted. The snapshot will look structurally correct. A retry 2-3 seconds later often distinguishes "temporarily hidden" from "actually gone".
  • "0 results" from a search is an answer. If the adapter successfully reached the search endpoint, got an HTTP 200, and the platform returned results: [], that is a valid answer — report it to the user as "no matches for this query" rather than patching the adapter.

Only proceed to Step 1 if the empty/selector-missing result is reproducible across retries and alternative entry points. Otherwise you're patching a working adapter to chase noise, and the patched version will break the next working path.

Step 1: Collect Trace Context

Run the failing command with failure-retained trace enabled:

opencli <site> <command> [args...] --trace retain-on-failure 2>trace-error.yaml

On failure, stderr contains the normal error envelope plus a small trace block:

ok: false
error:
  code: SELECTOR
  message: "Could not find element: .old-selector"
trace:
  schemaVersion: 1
  opencliVersion: "..."
  traceId: "..."
  dir: "/path/to/.opencli/profiles/default/traces/..."
  summaryPath: "/path/to/.opencli/profiles/default/traces/.../summary.md"
  receiptPath: "/path/to/.opencli/profiles/default/traces/.../receipt.json"

Read summaryPath first. It is the LLM-oriented entry point and includes front matter:

---
schemaVersion: 1
opencliVersion: "..."
traceId: "..."
status: failure
site: "example"
command: "example/search"
adapterSourcePath: "/path/to/clis/example/search.js"
errorCode: "SELECTOR"
errorMessage: "Could not find element: .old-selector"
---

The artifact directory contains:

summary.md      # start here
receipt.json    # machine-readable trace receipt
trace.jsonl     # full redacted timeline
network.jsonl   # redacted network events
console.jsonl   # redacted console events
state/          # final snapshots when available
screenshots/    # final screenshots when available

If you redirected stderr to a file, read that file and copy trace.summaryPath.

Do not ask the user to rerun with legacy diagnostic env vars. Trace is the repair evidence path.

Step 2: Analyze the Failure

Read the trace summary and the adapter source. Classify the root cause:

Error CodeLikely CauseRepair Strategy
SELECTORDOM restructured, class/id renamedExplore current DOM → find new selector
EMPTY_RESULTAPI response schema changed, or data movedCheck network → find new response path
API_ERROREndpoint URL changed, new params requiredDiscover new API via network intercept
AUTH_REQUIREDLogin flow changed, cookies expiredSTOP — tell user to log in, do not modify code
TIMEOUTPage loads differently, spinner/lazy-loadAdd/update wait conditions
PAGE_CHANGEDMajor redesignMay need full adapter rewrite

Key questions to answer:

  1. What is the adapter trying t
阅读完整来源 ↗