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 runopencli doctor.- CAPTCHA / rate limiting — STOP. Not an adapter issue.
Scope constraint:
- Only modify the file at
adapterSourcePathin the tracesummary.mdfront matter — this is the authoritative adapter location (may beclis/<site>/in repo or~/.opencli/clis/<site>/for npm installs) - Never modify
src/,extension/,tests/,package.json, ortsconfig.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 butopencli 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 Code | Likely Cause | Repair Strategy |
|---|---|---|
| SELECTOR | DOM restructured, class/id renamed | Explore current DOM → find new selector |
| EMPTY_RESULT | API response schema changed, or data moved | Check network → find new response path |
| API_ERROR | Endpoint URL changed, new params required | Discover new API via network intercept |
| AUTH_REQUIRED | Login flow changed, cookies expired | STOP — tell user to log in, do not modify code |
| TIMEOUT | Page loads differently, spinner/lazy-load | Add/update wait conditions |
| PAGE_CHANGED | Major redesign | May need full adapter rewrite |
Key questions to answer:
- What is the adapter trying t