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

opencli コマンドが Web サイトの DOM、API、またはレスポンススキーマの変更により失敗した場合、自動的に診断してアダプターを修復し、再試行します — エラーを単に報告するだけではありません。

安全境界

修復を開始する前に、これらの停止条件をチェックしてください:

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

スコープ制約:

• トレース summary.md フロントマターの adapterSourcePath にあるファイルのみを変更してください — これが正式なアダプターの場所です (リポジトリの clis/<site>/ または npm インストールの ~/.opencli/clis/<site>/ の場合があります)
• 決して変更しないでください: src/、extension/、tests/、package.json、tsconfig.json

再試行の予算: 失敗ごとに最大 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 を返します。スナップショットは構造的に正しく見えます。数秒後の再試行は、多くの場合「一時的に非表示」と「実際に削除」を区別します。
• 「0 件の結果」は答えです。 アダプターが検索エンドポイントに正常に到達し、HTTP 200 を取得し、プラットフォームが results: [] を返した場合、それは有効な答えです — アダプターをパッチするのではなく、ユーザーに「このクエリに一致するものはありません」と報告してください。

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

ステップ 1: トレースコンテキストを収集

失敗時に保持されるトレースを有効にして、失敗したコマンドを実行します:

opencli <site> <command> [args...] --trace retain-on-failure 2>trace-error.yaml

失敗時、stderr には通常のエラーエンベロープと小さい trace ブロックが含まれます:

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"

まず summaryPath を読んでください。これは LLM 指向のエントリーポイントであり、フロントマターを含みます:

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

アーティファクトディレクトリには以下が含まれます:

summary.md      # ここから開始
receipt.json    # マシン読み取り可能なトレース領収書
trace.jsonl     # 完全な編集されたタイムライン
network.jsonl   # 編集されたネットワークイベント
console.jsonl   # 編集されたコンソールイベント
state/          # 利用可能な場合の最終スナップショット
screenshots/    # 利用可能な場合の最終スクリーンショット

stderr をファイルにリダイレクトした場合は、そのファイルを読み、trace.summaryPath をコピーしてください。

レガシー診断環境変数で再実行するようユーザーに求めないでください。トレースは修復の証拠パスです。

ステップ 2: 失敗を分析

トレース概要とアダプターソースを読みます。根本原因を分類してください:

エラーコード	考えられる原因	修復戦略
SELECTOR	DOM 再構築、クラス/ID 名変更	現在の DOM を探索 → 新しいセレクターを検索
EMPTY_RESULT	API レスポンススキーマ変更、データ移動	ネットワークを確認 → 新しいレスポンスパスを検索
API_ERROR	エンドポイント URL 変更、新しいパラメーター必須	ネットワークインターセプト経由で新しい API を検出
AUTH_REQUIRED	ログインフロー変更、Cookie 有効期限切れ	中止 — ユーザーにログインを指示し、コードを変更しないでください
TIMEOUT	ページの読み込み方が異なる、スピナー/遅延読み込み	待機条件を追加/更新
PAGE_CHANGED	大規模な再設計	完全なアダプター書き直しが必要な場合があります

回答すべき重要な質問:

1. アダプターは何をしようとしていますか? (adapterSourcePath のファイルを読んでください)
2. 失敗時のページはどのように見えましたか? (summary.mdを読んでから、必要に応じて state/ を読んでください)
3. どのネットワークリクエストが発生しましたか? (summary.md の「Failed Network」を読んでから、必要に応じて network.jsonl を読んでください)
4. アダプターが期待していることと、ページが提供していることのギャップは何ですか?

ステップ 3: 現在の Web サイトを探索

opencli browser を使用してライブ Web サイトを検査してください。破損したアダプターを使用しないでください — 再度失敗するだけです。

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

# 本文に持つべきフィールドでリクエストを絞り込む
opencli browser network --filter author,text,likes

# 特定の API レスポンスを検査 (キーはデフォルト JSON 出力の `key` フィールド)
opencli browser network --detail <key>

ステップ 4: アダプターにパッチを当てる

トレース概要フロントマターの adapterSourcePath でアダプターソースファイルを読み、対象の修正を行います。このパスは正式です — リポジトリ (clis/) またはユーザーローカル (~/.opencli/clis/) にある場合があります。

summary.md フロントマターからの正確なパスで Read ツールを使用してください。

一般的な修正

セレクター更新:

// 前: page.evaluate('document.querySelector(".old-class")...')
// 後:  page.evaluate('document.querySelector(".new-class")...')

API エンドポイント変更:

// 前: const resp = await page.evaluate(`fetch('/api/v1/old-endpoint')...`)
// 後:  const resp = await page.evaluate(`fetch('/api/v2/new-endpoint')...`)

レスポンススキーマ変更:

// 前: const items = data.results
// 後:  const items = data.data.items  // API は現在 "data" の下にネストしています

待機条件の更新:

// 前: await page.wait({ selector: '.loading-spinner', hidden: true })
// 後:  await page.wait({ selector: '[data-loaded="true"]' })

パッチの適用ルール

1. 最小限の変更を加える — 破損したものだけを修正し、リファクタリングしないでください
2. 同じ出力構造を保つ — columns と戻り形式は互換性を保つ必要があります
3. DOM スクレイピングより API を優先 — 探索中に JSON API を発見した場合、それに切り替えてください
4. @jackwener/opencli/* インポートのみを使用 — サードパーティ製パッケージをインポートしないでください
5. パッチ後にテストする — コマンドを再度実行して検証します
6. 失敗を沈黙させるために verify/<cmd>.json フィクスを緩和しないでください。 失敗した patterns / notEmpty / mustNotContain / mustBeTruthy ルールは、アダプターの出力が破損していることを意味します。フィクスを緩和して破損した値を受け入れるのではなく、アダプターを強化して正しい値を生成するようにしてください。修復中にフィクスを編集する唯一の正当な理由は、サイト自体が形を変えた場合です (例えば URL 形式移行) — その場合はフィクスを更新し、~/.opencli/sites/<site>/notes.md で変更を記録してください。それ以外の場合、フィクスを編集することは自動正確性低下を隠ぺいしています。

ステップ 5: 修復を検証

# コマンドを通常実行
opencli <site> <command> [args...]

まだ失敗する場合は、ステップ 1 に戻って新しいトレースを収集してください。3 つの修復ラウンド (トレース → 修復 → 再試行) の予算があります。修復後も同じエラーが続く場合は、別のアプローチを試してください。3 ラウンド後は、試みたことを報告してください。

ステップ 6: 上流の問題をファイル

再試行が成功した場合、ローカルアダプターは上流からドリフトしています。jackwener/OpenCLI に修正が流れ込むようにするため、GitHub 問題をファイルしてください。

以下の場合はファイルしないでください:

• AUTH_REQUIRED、BROWSER_CONNECT、ARGUMENT、CONFIG — 環境/使用法の問題、アダプターバグではありません
• CAPTCHA またはレート制限 — 上流で修正不可能です
• 実際に修正できなかった失敗 (3 ラウンド終了)

検証されたローカル修復後のみファイルしてください — 再試行は最初に成功する必要があります。

手順:

1. すでに持っているトレース概要から問題コンテンツを準備します:
   • タイトル: [autofix] <site>/<command>: <error_code> (例: [autofix] zhihu/hot: SELECTOR)
   • 本文 (このテンプレートを使用):

## Summary
OpenCLI autofix がこのアダプターをローカルで修復し、再試行が成功しました。

## Adapter
- Site: `<site>`
- Command: `<command>`
- OpenCLI version: `<opencli --version からのバージョン>`

## Original failure
- Error code: `<error_code>`

~~~
<error_message>
~~~

## Local fix summary

~~~
<変更内容と理由を 1～2 文で説明してください>
~~~

_Issue filed by OpenCLI autofix after a verified local repair._

2. ファイル前にユーザーに確認してください。 ドラフトタイトルと本文を表示します。確認した場合のみ進めてください。

3. ユーザーが承認し、gh auth status が成功した場合:

gh issue create --repo jackwener/OpenCLI \
  --title "[autofix] <site>/<command>: <error_code>" \
  --body "<上記の本文>"

gh がインストールされていない、または認証されていない場合は、ユーザーに伝えてスキップします — エラーを起こさないでください。

停止する場合

ハード停止 (コードを変更しないでください):

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

ソフト停止 (試行後に報告):

• 3 つの修復ラウンド終了 — 停止、試みたことと失敗したことを報告
• 機能が完全に削除されました — データは存在しなくなりました
• 大規模な再設計 — opencli-adapter-author スキル経由で完全なアダプター書き直しが必要です

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

修復セッションの例

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

2. AI が実行: opencli zhihu hot --trace retain-on-failure 2>trace-error.yaml
   → 最終状態と失敗したアクション証拠を含むトレース概要を取得

3. AI が読む: summary/state — ページは読み込まれましたが ".HotList-item" の代わりに ".HotItem" を使用しています

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

5. AI がパッチ: `adapterSourcePath` でアダプターを編集 — ".HotList-item" を ".HotItem" に置き換え

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

7. AI がアップストリーム問題ドラフトを準備し、ユーザーに表示

8. ユーザーが承認 → AI が実行: gh issue create --repo jackwener/OpenCLI --title "[autofix] zhihu/hot: SELECTOR" --body "..."