qiaomu-opencli-autofix

OpenCLI AutoFix — アダプターの自動修復

ウェブサイトの DOM、API、またはレスポンススキーマの変更により opencli コマンドが失敗した場合、エラーを報告するだけでなく、自動的に原因を診断し、アダプターを修正して、再試行します。

安全上の制約

修復を開始する前に、次の処理停止条件を確認してください。

• 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 は変更しないでください。

再試行回数の上限： 失敗ごとの修復は最大 3 ラウンドです。診断 → 修正 → 再試行を3ラウンド行っても解決しない場合は、停止して試した内容を報告してください。

前提条件

opencli doctor    # Verify extension + daemon connectivity

このスキルを使う場面

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

標準エラー出力の ___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"
}

解析してください：

# Extract JSON between markers from stderr output
cat diagnostic.json | sed -n '/___OPENCLI_DIAGNOSTIC___/{n;p;}'

Step 2: 失敗の原因を分析する

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

エラーコード	考えられる原因	修正方法
SELECTOR	DOM の構造変更、クラス名や ID の変更	現在の DOM を調査 → 新しいセレクターを特定
EMPTY_RESULT	API レスポンスのスキーマ変更、またはデータの移動	ネットワークを確認 → 新しいレスポンスのパスを特定
API_ERROR	エンドポイント URL の変更、新しいパラメーターが必要	ネットワークインターセプトで新しい API を特定
AUTH_REQUIRED	ログインフローの変更、Cookie の期限切れ	停止 — ユーザーにログインを依頼し、コードを変更しない
TIMEOUT	ページの読み込み方法の変更、スピナーや遅延読み込み	待機条件を追加・更新
PAGE_CHANGED	大幅な再設計	アダプター全体の書き直しが必要な場合があります

確認すべき主な質問：

1. アダプターは何をしようとしていますか？（source フィールドを読みます）
2. 失敗時、ページはどのような状態でしたか？（snapshot フィールドを読みます）
3. どのようなネットワークリクエストが発生しましたか？（networkRequests を読みます）
4. アダプターが想定している内容とページが提供している内容には、どのような違いがありますか？

Step 3: 現在のウェブサイトを調査する

opencli browser を使って、現在のウェブサイトを調査します。壊れたアダプターは決して使用しないでください — 再び失敗するだけです。

DOM の変更（SELECTOR エラー）

# 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

API の変更（API_ERROR、EMPTY_RESULT）

# 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>

Step 4: アダプターにパッチを適用する

RepairContext.adapter.sourcePath にあるパスからアダプターのソースファイルを読み込み、必要な箇所だけを修正します。このパスを正とします — リポジトリ内（clis/）またはユーザーのローカル環境（~/.opencli/clis/）にある場合があります。

# 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")...')

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 now nests under "data"

待機条件の更新：

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

パッチ適用のルール

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

Step 5: 修正を検証する

# Run the command normally (without diagnostic mode)
opencli <site> <command> [args...]

それでも失敗する場合は、Step 1 に戻り、新しい診断情報を収集します。修復に使える回数は 3 回 です（診断 → 修正 → 再試行）。修正後も同じエラーが続く場合は、別の方法を試してください。3 回試したら停止し、試した内容を報告します。

停止するタイミング

即時停止（コードを変更しない）：

• AUTH_REQUIRED / BROWSER_CONNECT — 環境の問題であり、アダプターの不具合ではありません
• サイトで CAPTCHA が必要 — 自動化できません
• レート制限中 / IP がブロックされている — アダプターの問題ではありません

試行後に停止（結果を報告する）：

• 修復を 3 回試しても解決しない — 停止し、試した内容と失敗した内容を報告します
• 機能が完全に削除されている — データはもう存在しません
• 大幅な再設計 — opencli-explorer スキルを使ってアダプター全体を書き直す必要があります

いずれの場合も、効果のないパッチを繰り返すのではなく、状況をユーザーにはっきりと伝えてください。

修復セッションの例

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