OpenCLI AutoFix — 自動アダプタ自己修復

opencli コマンドが失敗した場合、ウェブサイトの DOM、API、またはレスポンススキーマが変更されたときに、自動的に診断、修復、再試行してください。エラーを報告するだけではなく。

セーフティ境界

修復を開始する前に、これらのハードストップをチェックしてください:

• AUTH_REQUIRED (終了コード 77) — 停止。 コードを変更しないでください。ユーザーに Chrome でサイトにログインするよう指示してください。
• BROWSER_CONNECT (終了コード 69) — 停止。 コードを変更しないでください。ユーザーに opencli doctor を実行するよう指示してください。
• CAPTCHA / レート制限 — 停止。 アダプタの問題ではありません。

スコープ制限:

• RepairContext.adapter.sourcePath のファイルのみ修正 — これが正式なアダプタの位置です (リポジトリの clis/<site>/ または npm インストール用の ~/.opencli/clis/<site>/ の場合があります)
• 決して修正しないでください: src/、extension/、tests/、package.json、または tsconfig.json

再試行予算: 1 つの失敗につき最大 3 回の修復ラウンド。3 ラウンドの診断 → 修復 → 再試行で解決しない場合は、停止して試したことを報告してください。

前提条件

opencli doctor    # 拡張機能とデーモンの接続を確認

このスキルをいつ使用するか

opencli <site> <command> が修復可能なエラーで失敗した場合に使用します:

• SELECTOR — 要素が見つかりません (DOM が変更されました)
• EMPTY_RESULT — データが返されません (API レスポンスが変更されました)
• API_ERROR / NETWORK — エンドポイントが移動または破損しました
• PAGE_CHANGED — ページ構造がもはや一致しません
• COMMAND_EXEC — アダプタロジックのランタイムエラー
• TIMEOUT — ページが異なる方法で読み込まれます。アダプタが間違ったものを待っています

修復を開始する前に: 「空」≠「破損」

EMPTY_RESULT — そして構造的に有効な SELECTOR が何も返さない場合もあります — これはしばしば アダプタのバグではありません。プラットフォームはアンチスクレイプ ヒューリスティックスの下で積極的に結果を低下させ、サイトからの「見つかりません」応答は、コンテンツが実際に欠落していることを意味しません。修復ラウンドを始める前に、これを除外してください:

• 別のクエリまたはエントリポイントで再試行してください。 opencli xiaohongshu search "X" が 0 を返すが opencli xiaohongshu search "X 攻略" が 20 を返す場合、アダプタは問題ありません — プラットフォームは最初のクエリの結果を形成していました。
• 通常の Chrome タブでスポットチェックしてください。 ユーザー自身のブラウザでデータが表示されているがアダプタが空を返す場合、問題は通常、認証状態、レート制限、またはソフトブロック — コードバグではありません。修正は opencli doctor / 再ログインであり、ソースの編集ではありません。
• ソフト 404 を探してください。 xiaohongshu / weibo / douyin などのサイトは、アイテムが非表示または削除されている場合、実際の 404 の代わりに HTTP 200 と空のペイロードを返します。スナップショットは構造的に正しく見えます。2-3 秒後に再試行すると、「一時的に非表示」と「実際に削除」を区別できることがよくあります。
• 検索から「0 件の結果」は答えです。 アダプタが検索エンドポイントに正常に到達し、HTTP 200 を得て、プラットフォームが results: [] を返した場合、それは有効な答えです — アダプタを修正するのではなく、「このクエリに一致するものなし」としてユーザーに報告してください。

空/セレクタ欠落の結果が 複数の再試行と別のエントリポイント全体で再現可能である 場合にのみ、ステップ 1 に進んでください。そうしないと、ノイズを追いかけるために動作しているアダプタを修正していることになり、修正版は次の動作パスを破損します。

ステップ 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"
}

解析:

# stderr 出力からマーカー間の JSON を抽出
cat diagnostic.json | sed -n '/___OPENCLI_DIAGNOSTIC___/{n;p;}'

ステップ 2: 失敗を分析

診断コンテキストとアダプタソースを読みます。根本原因を分類します:

エラーコード	可能な原因	修復戦略
SELECTOR	DOM が再構成、クラス/ID がリネーム	現在の DOM を探索 → 新しいセレクタを見つける
EMPTY_RESULT	API レスポンススキーマが変更、またはデータが移動	ネットワークをチェック → 新しいレスポンスパスを見つける
API_ERROR	エンドポイント URL が変更、新しいパラメータが必要	ネットワークインターセプト経由で新しい API を発見
AUTH_REQUIRED	ログインフロー が変更、クッキーが期限切れ	停止 — ユーザーにログインするよう指示してください。コードを変更しないでください
TIMEOUT	ページが異なる方法で読み込まれます。スピナー/遅延読み込み	待機条件を追加/更新
PAGE_CHANGED	メジャーリデザイン	完全なアダプタ再構築が必要な場合があります

答えるべき主な質問:

1. アダプタは何をしようとしていますか? (source フィールドを読んでください)
2. 失敗したときのページはどのようでしたか? (snapshot フィールドを読んでください)
3. どのネットワークリクエストが発生しましたか? (networkRequests を読んでください)
4. アダプタが期待していることとページが提供していることのギャップは何ですか?

ステップ 3: 現在のウェブサイトを探索

opencli browser を使用してライブウェブサイトを検査します。破損したアダプタを使用しないでください — それはただ再び失敗するだけです。

DOM が変更されました (SELECTOR エラー)

# ページを開いて現在の DOM を検査
opencli browser open https://example.com/target-page && opencli browser state

# アダプタの意図と一致する要素を探してください
# スナップショットをアダプタが期待していることと比較してください

API が変更されました (API_ERROR、EMPTY_RESULT)

# ネットワークインターセプタを使用してページを開いてから、手動でアクションをトリガー
opencli browser open https://example.com/target-page && opencli browser state

# API 呼び出しをトリガーするために操作
opencli browser click <N> && opencli browser network

# 特定の API レスポンスを検査
opencli browser network --detail <index>

ステップ 4: アダプタにパッチを適用

RepairContext.adapter.sourcePath のパスのアダプタソースファイルを読み、ターゲットを絞った修正を行います。このパスは正式です — リポジトリの (clis/) またはユーザーローカル (~/.opencli/clis/) に存在する場合があります。

# アダプタを読む (診断からの正確なパスを使用)
cat <RepairContext.adapter.sourcePath>

一般的な修正

セレクタの更新:

// 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 は現在 "data" の下にネストされています

待機条件の更新:

// Before: await page.waitForSelector('.loading-spinner', { hidden: true })
// After:  await page.waitForSelector('[data-loaded="true"]')

パッチ適用のルール

1. 最小限の変更を行う — 破損していることのみを修復して、リファクタリングをしないでください
2. 同じ出力構造を保つ — columns と戻り値の形式は互換性を保つ必要があります
3. API より DOM スクレイピングを優先 — 探索中に JSON API を発見した場合、それに切り替えます
4. @jackwener/opencli/* インポートのみを使用 — 決してサードパーティ製パッケージのインポートを追加しないでください
5. パッチ適用後にテストしてください — コマンドを再度実行して検証します

ステップ 5: 修正を確認

# コマンドを通常実行 (診断モードなし)
opencli <site> <command> [args...]

それでも失敗する場合は、ステップ 1 に戻って新しい診断を収集してください。3 回の修復ラウンド (診断 → 修復 → 再試行) の予算があります。修正後に同じエラーが発生し続ける場合は、別のアプローチを試してください。3 ラウンド後、停止して試したことを報告してください。

停止するとき

ハードストップ (コードを変更しないでください):

• AUTH_REQUIRED / BROWSER_CONNECT — 環境の問題であり、アダプタのバグではありません
• サイトが CAPTCHA を要求 — 自動化できません
• レート制限 / IP ブロック — アダプタの問題ではありません

ソフトストップ (試行後に報告):

• 3 回の修復ラウンドが枯渇 — 停止して、試したことと失敗したことを報告してください
• 機能が完全に削除 — データはもう存在しません
• メジャーリデザイン — opencli-explorer スキル経由で完全なアダプタ再構築が必要です

すべての停止ケースで、無益なパッチを行うのではなく、状況をユーザーに明確に伝えてください。

修復セッションの例

1. ユーザーが実行: opencli zhihu hot
   → 失敗: SELECTOR "Could not find element: .HotList-item"

2. AI が実行: OPENCLI_DIAGNOSTIC=1 opencli zhihu hot 2>diag.json
   → ページが読み込まれたことを示す DOM スナップショットを含む RepairContext を取得

3. AI が診断を読む: スナップショットはページが読み込まれたが ".HotList-item" の代わりに ".HotItem" を使用していることを示しています

4. AI が探索: opencli browser open https://www.zhihu.com/hot && opencli browser state
   → 新しいクラス名 ".HotItem" (子 ".HotItem-content" を含む) を確認

5. AI がパッチ: RepairContext.adapter.sourcePath のアダプタを編集 — ".HotList-item" を ".HotItem" に置き換える

6. AI が検証: opencli zhihu hot
   → 成功: ホットトピックを返す