feat: Self-Repair protocol for automatic adapter fixing (#866)

jackwener · web-flow · commit 56d15d186bf0 · 2026-04-07T23:00:03.000+08:00
* feat: add Self-Repair protocol for automatic adapter fixing

When an AI agent uses opencli and a command fails, the agent
automatically diagnoses the failure, fixes the adapter, and retries.

- Add CLAUDE.md with Self-Repair protocol (auto-loaded by Claude Code)
- Add designs/self-repair-protocol.md documenting the approach
- Update opencli-repair skill: add Safety Boundaries (AUTH/BROWSER → STOP,
  sourcePath-only scope, max 3 rounds), fix AUTH_REQUIRED guidance
- Update opencli-usage skill: add Self-Repair section

Key design decisions:
- Repair target is always RepairContext.adapter.sourcePath (works for both
  repo-local clis/ and user-local ~/.opencli/clis/)
- Only adapter files may be modified, never core src/
- Max 3 repair rounds per failure
- AUTH_REQUIRED and BROWSER_CONNECT are hard stops (report, don't modify)

* fix: align auth boundary and scope language across all documents

- Remove "Auth changed (AUTH_REQUIRED)" exploration section from
  opencli-repair skill — contradicted the hard stop rule above it
- Update design doc: scope language matches repo-local + explicit skill
  delivery model, not universal product behavior
- Update usage skill: reference sourcePath instead of "files under clis/"

* fix: replace remaining repo-relative clis/ paths with sourcePath in design doc

* refactor: rename opencli-repair to opencli-autofix, remove CLAUDE.md

CLAUDE.md was wrong — users don't work inside the opencli repo, and
the protocol shouldn't assume Claude Code. The skill is the portable
delivery mechanism for any AI agent.

- Rename skills/opencli-repair → skills/opencli-autofix
- Remove CLAUDE.md (not the right delivery mechanism)
- Update all references in usage skill and design doc
- Design doc rewritten to reflect skill-first approach

* fix: use sourcePath in example repair session

* feat: emit AutoFix hint on repairable adapter errors

When a command fails with a repairable error (SELECTOR, EMPTY_RESULT,
COMMAND_EXEC, or generic http/not-found), the error output now includes
a hint telling agents to re-run with OPENCLI_DIAGNOSTIC=1 for repair
context. This is the trigger mechanism that bridges the gap between
"command failed" and "agent enters autofix loop".

Non-repairable errors (AUTH_REQUIRED, BROWSER_CONNECT, ARGUMENT) do not
emit the hint — these require user action, not adapter fixes.

* fix: narrow AutoFix hint to adapter-drift errors only

Remove hint from CommandExecutionError (covers env/launcher/runtime
issues, not adapter drift) and generic http errors (often temporary
site issues). Keep hint only for SelectorError, EmptyResultError,
and generic not-found — clear adapter-drift signals.
diff --git a/designs/self-repair-protocol.md b/designs/self-repair-protocol.md
@@ -0,0 +1,149 @@
+# Self-Repair Protocol — Design Document
+
+**Authors**: @opus0, @codex-mini0  
+**Date**: 2026-04-07  
+**Status**: Approved  
+**Supersedes**: `designs/autofix-incident-repair.md` (PR #863, deferred to Phase 2)
+
+---
+
+## Problem Statement
+
+When an AI agent uses `opencli <site> <command>` and the command fails (site changed DOM, API, or response schema), the agent should **automatically repair the adapter and retry** — without human intervention or pre-written spec files.
+
+### Why the simpler approach
+
+The previous design (PR #863) required pre-authoring `command-specs.json` with verify checks, safety profiles, and failure taxonomy before any command could be repaired. This created a chicken-and-egg problem: you can only repair commands you've already written specs for.
+
+From first principles, the agent already has everything it needs:
+1. **The failing command** — it just ran it
+2. **The error output** — stdout/stderr
+3. **The adapter source** — resolved via `RepairContext.adapter.sourcePath`
+4. **Diagnostic context** — DOM snapshot, network requests (via `OPENCLI_DIAGNOSTIC=1`)
+5. **A verify oracle** — re-run the same command
+
+No spec file needed. The command itself is the spec.
+
+---
+
+## Design: Online Self-Repair
+
+### Core Protocol
+
+```
+Agent runs: opencli <site> <command> [args...]
+  → Command succeeds → continue task
+  → Command fails →
+      1. Re-run with OPENCLI_DIAGNOSTIC=1 to collect RepairContext
+      2. Read adapter source from RepairContext.adapter.sourcePath
+      3. Analyze: error code + DOM snapshot + network requests → root cause
+      4. Edit the adapter file at RepairContext.adapter.sourcePath
+      5. Retry the original command
+      6. If still failing → repeat (max 3 rounds)
+      7. If 3 rounds exhausted → report failure, do not loop further
+```
+
+### Scope Constraint
+
+**Only modify the adapter file identified by `RepairContext.adapter.sourcePath`.**
+
+The diagnostic resolves the actual editable source path at runtime — it may be:
+- `clis/<site>/*.ts` — repo-local adapters (dev/source checkout)
+- `~/.opencli/clis/<site>/*.ts` — user-local adapters (npm install scenario)
+
+The agent must use the path from the diagnostic, not guess a repo-relative path. This is critical for npm-installed users where `clis/` is not in the repo.
+
+**Never modify:**
+- `src/**` — core runtime (npm package, requires version release)
+- `extension/**` — browser extension
+- `autoresearch/**` — research infrastructure
+- `tests/**` — test files
+- `package.json`, `tsconfig.json` — project config
+
+### When NOT to Self-Repair
+
+The agent should recognize non-repairable failures and stop:
+
+| Signal | Meaning | Action |
+|--------|---------|--------|
+| Auth/login error | Not logged into site in Chrome | Tell user to log in, don't modify code |
+| Browser bridge not connected | Extension/daemon not running | Tell user to run `opencli doctor` |
+| CAPTCHA | Site requires human verification | Report, don't modify code |
+| Rate limited / IP blocked | Not an adapter issue | Report, wait and retry later |
+| Feature removed by site | Data no longer exists | Report, adapter may need deprecation |
+
+### Retry Budget
+
+- **Max 3 repair rounds per command failure**
+- Each round: diagnose → edit adapter → retry command
+- If the error is identical after a repair attempt, the fix didn't work — try a different approach
+- After 3 rounds, stop and report what was tried
+
+---
+
+## Implementation
+
+### What Already Exists
+
+| Component | Status | Location |
+|-----------|--------|----------|
+| Diagnostic output (RepairContext) | ✅ Done | `src/diagnostic.ts` |
+| Diagnostic wiring in execution | ✅ Done | `src/execution.ts` |
+| Error taxonomy (CliError codes) | ✅ Done | `src/errors.ts` |
+| Adapter source resolution | ✅ Done | `src/diagnostic.ts:resolveAdapterSourcePath` |
+
+### What's New (This Design)
+
+| Component | Description |
+|-----------|-------------|
+| `skills/opencli-autofix/SKILL.md` (renamed from `opencli-repair`) | AutoFix skill with safety boundaries, sourcePath-based scope, 3-round limit. The primary delivery mechanism for the self-repair protocol. |
+| `skills/opencli-usage/SKILL.md` (updated) | Self-Repair section for discoverability |
+
+### Delivery mechanism
+
+The `opencli-autofix` skill is the portable self-repair protocol. Any AI agent — regardless of framework, provider, or working directory — can load this skill to get the full autofix workflow. It is not tied to any specific agent framework or repo location.
+
+- **No new runtime code** — the diagnostic infrastructure already exists
+- **No CLAUDE.md dependency** — the skill is the protocol, not a repo-local file
+
+---
+
+## The AutoFix Protocol (in the skill)
+
+The `opencli-autofix` skill instructs agents:
+
+1. When `opencli <site> <command>` fails, **don't just report the error**
+2. Re-run with `OPENCLI_DIAGNOSTIC=1` to get structured context
+3. Parse the RepairContext (error code, adapter source, DOM snapshot)
+4. Read and fix the adapter at `RepairContext.adapter.sourcePath`
+5. Retry the original command
+6. Max 3 repair rounds, then stop
+
+---
+
+## Relationship to PR #863
+
+PR #863 (spec/runner/incident framework) is **not needed for Phase 1**. It becomes useful later as a "hardening layer":
+
+- **Phase 1 (now)**: Self-Repair via `opencli-autofix` skill — agent repairs on the fly
+- **Phase 2 (later)**: High-frequency failures get hardened into `command-specs.json` for offline regression testing and CI
+
+The spec/runner framework is the "asset layer" — it turns ad-hoc repairs into reusable, verifiable test cases. But it's not the entry point.
+
+---
+
+## Usage
+
+No new commands. No new scripts. The agent loads the `opencli-autofix` skill and uses opencli normally:
+
+```bash
+# Agent runs a command as part of its task
+opencli weibo hot --limit 5 -f json
+
+# If it fails, the agent automatically:
+# 1. Runs OPENCLI_DIAGNOSTIC=1 opencli weibo hot --limit 5 -f json 2>diag.json
+# 2. Reads the diagnostic context
+# 3. Fixes the adapter at RepairContext.adapter.sourcePath
+# 4. Retries: opencli weibo hot --limit 5 -f json
+# 5. Continues with the task
+```
diff --git a/skills/opencli-autofix/SKILL.md b/skills/opencli-autofix/SKILL.md
@@ -1,12 +1,26 @@
 ---
-name: opencli-repair
-description: Diagnose and fix broken OpenCLI adapters when websites change. Use when an opencli command fails with SELECTOR, EMPTY_RESULT, API_ERROR, or PAGE_CHANGED errors. Reads structured diagnostic output and uses browser automation to discover what changed and patch the adapter.
+name: opencli-autofix
+description: 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.
 allowed-tools: Bash(opencli:*), Read, Edit, Write
 ---
 
-# OpenCLI Repair — AI-Driven Adapter Self-Repair
+# OpenCLI AutoFix — Automatic Adapter Self-Repair
 
-When an adapter breaks because a website changed its DOM, API, or auth flow, use this skill to diagnose the failure and patch the adapter.
+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 `RepairContext.adapter.sourcePath`** — 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
 
@@ -16,7 +30,7 @@ opencli doctor    # Verify extension + daemon connectivity
 
 ## When to Use This Skill
 
-Use when `opencli <site> <command>` fails with errors like:
+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
@@ -72,7 +86,7 @@ Read the diagnostic context and the adapter source. Classify the root cause:
 | 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 | Walk login flow with operate |
+| 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 |
 
@@ -109,23 +123,13 @@ opencli operate click <N> && opencli operate network
 opencli operate network --detail <index>
 ```
 
-### Auth changed (AUTH_REQUIRED)
-
-```bash
-# 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
-```
-
 ## Step 4: Patch the Adapter
 
-Read the adapter source file and make targeted fixes:
+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/`).
 
 ```bash
-# Read the adapter
-cat <sourcePath from diagnostic>
+# Read the adapter (use the exact path from diagnostic)
+cat <RepairContext.adapter.sourcePath>
 ```
 
 ### Common Fixes
@@ -169,18 +173,21 @@ cat <sourcePath from diagnostic>
 opencli <site> <command> [args...]
 ```
 
-If it still fails, go back to Step 3 and explore further. If the website has fundamentally changed (major redesign, removed feature), report that the adapter needs a full rewrite.
-
-## When to Give Up
+If 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.
 
-Not all failures are repairable with a quick patch:
+## When to Stop
 
+**Hard stops (do not modify code):**
+- **AUTH_REQUIRED / BROWSER_CONNECT** — environment issue, not adapter bug
 - **Site requires CAPTCHA** — can't automate this
+- **Rate limited / IP blocked** — not an adapter issue
+
+**Soft stops (report after attempting):**
+- **3 repair rounds exhausted** — stop, report what was tried and what failed
 - **Feature completely removed** — the data no longer exists
 - **Major redesign** — needs full adapter rewrite via `opencli-explorer` skill
-- **Rate limited / IP blocked** — not an adapter issue
 
-In these cases, clearly communicate the situation to the user rather than making futile patches.
+In all stop cases, clearly communicate the situation to the user rather than making futile patches.
 
 ## Example Repair Session
 
@@ -196,7 +203,7 @@ In these cases, clearly communicate the situation to the user rather than making
 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"
+5. AI patches: Edit adapter at RepairContext.adapter.sourcePath — replace ".HotList-item" with ".HotItem"
 
 6. AI verifies: opencli zhihu hot
    → Success: returns hot topics
diff --git a/skills/opencli-usage/SKILL.md b/skills/opencli-usage/SKILL.md
@@ -156,8 +156,13 @@ opencli record <url>            # Record API calls manually
 
 All commands support: `--format` / `-f` with `table` `json` `yaml` `md` `csv`
 
+## Self-Repair
+
+If a command fails due to a site change (selector, API, or response schema), **automatically fix the adapter and retry** instead of reporting failure. Re-run the command with `OPENCLI_DIAGNOSTIC=1` to get structured diagnostic context, then fix the adapter file at `RepairContext.adapter.sourcePath` and retry. Max 3 repair rounds. See the `opencli-autofix` skill for the full workflow.
+
 ## Related Skills
 
 - **opencli-operate** — Browser automation for AI agents (navigate, click, type, extract via Chrome)
 - **opencli-explorer** — Full guide for creating new adapters (API discovery, auth strategy, YAML/TS writing)
 - **opencli-oneshot** — Quick 4-step template for adding a single command from a URL
+- **opencli-autofix** — Automatically fix broken adapters when commands fail
diff --git a/src/commanderAdapter.ts b/src/commanderAdapter.ts
@@ -31,6 +31,7 @@ import {
   CommandExecutionError,
 } from './errors.js';
 import { checkDaemonStatus } from './browser/discover.js';
+import { isDiagnosticEnabled } from './diagnostic.js';
 
 export function normalizeArgValue(argType: string | undefined, value: unknown, name: string): unknown {
   if (argType !== 'bool' && argType !== 'boolean') return value;
@@ -192,6 +193,14 @@ function renderBridgeStatus(running: boolean, extensionConnected: boolean): void
   }
 }
 
+/** Emit AutoFix hint for repairable adapter errors (skipped if already in diagnostic mode). */
+function emitAutoFixHint(cmdName: string): void {
+  if (isDiagnosticEnabled()) return; // Already collecting diagnostics, don't repeat
+  console.error();
+  console.error(chalk.cyan('💡 AutoFix: re-run with OPENCLI_DIAGNOSTIC=1 for repair context.'));
+  console.error(chalk.dim(`    OPENCLI_DIAGNOSTIC=1 ${cmdName}`));
+}
+
 async function renderError(err: unknown, cmdName: string, verbose: boolean): Promise<void> {
   // ── BrowserConnectError: real-time diagnosis, kind as fallback ────────
   if (err instanceof BrowserConnectError) {
@@ -233,6 +242,7 @@ async function renderError(err: unknown, cmdName: string, verbose: boolean): Pro
     console.error(chalk.yellow(`→ ${err.hint ?? 'The page structure may have changed — this adapter may be outdated.'}`));
     console.error(chalk.dim(`  Debug:  ${cmdName} --verbose`));
     console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
+    emitAutoFixHint(cmdName);
     return;
   }
 
@@ -277,6 +287,7 @@ async function renderError(err: unknown, cmdName: string, verbose: boolean): Pro
     console.error(chalk.red(`${classified.icon} ${msg}`));
     console.error(chalk.yellow(`→ ${classified.hint}`));
     if (classified.kind === 'not-found') console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
+    if (classified.kind === 'not-found') emitAutoFixHint(cmdName);
     return;
   }
 
