OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add joeseesun/qiaomu-opencli-skills --skill qiaomu-opencli-autofix
Automatically fix broken OpenCLI adapters when commands fail. Load this skill when an opencli command fails — it guides you through diagnosing the failure via OPENCLI_DIAGNOSTIC, patching the adapter, and retrying. Works with any AI agent.
npx skills add joeseesun/qiaomu-opencli-skills --skill qiaomu-opencli-autofix
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.
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.Scope constraint:
RepairContext.adapter.sourcePath — this is the authoritative adapter location (may be clis/<site>/ in repo or ~/.opencli/clis/<site>/ for npm installs)src/, extension/, tests/, package.json, or tsconfig.jsonRetry budget: Max 3 repair rounds per failure. If 3 rounds of diagnose → fix → retry don't resolve it, stop and report what was tried.
Use when opencli <site> <command> fails with repairable errors:
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:
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.opencli doctor / re-login, not editing source.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.
Run the failing command with diagnostic mode enabled:
This outputs a RepairContext JSON between ___OPENCLI_DIAGNOSTIC___ markers in stderr:
Parse it:
Read the diagnostic context 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:
source field)snapshot field)networkRequests)Use opencli browser to inspect the live website. Never use the broken adapter — it will just fail again.
Read the adapter source file at the path from RepairContext.adapter.sourcePath and make targeted fixes. This path is authoritative — it may be in the repo (clis/) or user-local (~/.opencli/clis/).
Selector update:
API endpoint change:
Response schema change:
Wait condition update:
columns and return format must stay compatible@jackwener/opencli/* imports only — never add third-party package importsIf it still fails, go back to Step 1 and collect fresh diagnostics. You have a budget of 3 repair rounds (diagnose → fix → retry). If the same error persists after a fix, try a different approach. After 3 rounds, stop and report what was tried.
Hard stops (do not modify code):
Soft stops (report after attempting):
opencli-explorer skillIn all stop cases, clearly communicate the situation to the user rather than making futile patches.
{
"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;}'# Open the page and inspect current DOM
opencli browser open https://example.com/target-page && opencli browser state
# Look for elements that match the adapter's intent
# Compare the snapshot with what the adapter expects# Open page with network interceptor, then trigger the action manually
opencli browser open https://example.com/target-page && opencli browser state
# Interact to trigger API calls
opencli browser click <N> && opencli browser network
# Inspect specific API response
opencli browser network --detail <index># Read the adapter (use the exact path from diagnostic)
cat <RepairContext.adapter.sourcePath>// Before: page.evaluate('document.querySelector(".old-class")...')
// After: page.evaluate('document.querySelector(".new-class")...')// 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"]')# Run the command normally (without diagnostic mode)
opencli <site> <command> [args...]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 browser open https://www.zhihu.com/hot && opencli browser state
→ Confirms new class name ".HotItem" with child ".HotItem-content"
5. AI patches: Edit adapter at RepairContext.adapter.sourcePath — replace ".HotList-item" with ".HotItem"
6. AI verifies: opencli zhihu hot
→ Success: returns hot topics