opencli-autofix

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

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

安全上の制約

修復を開始する前に、次の絶対条件を確認してください。

• 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    # 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 <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      # start here
receipt.json    # machine-readable trace receipt
trace.jsonl     # full redacted timeline
network.jsonl   # redacted network events
console.jsonl   # redacted console events
state/          # final snapshots when available
screenshots/    # final screenshots when available

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：現在のウェブサイトを調査する

opencli browser を使って、稼働中のウェブサイトを調査します。壊れたアダプターは絶対に使わないでください — 再び失敗するだけです。

DOM が変更された場合（SELECTOR エラー）

# Open the page and inspect current DOM
opencli browser --session research open https://example.com/target-page && opencli browser --session research 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 --session research open https://example.com/target-page && opencli browser --session research state

# Interact to trigger API calls
opencli browser --session research click <N> && opencli browser --session research network

# Narrow to the request you care about by the fields its body should have
opencli browser --session research network --filter author,text,likes

# Inspect specific API response (key is the `key` field from the default JSON output)
opencli browser --session research network --detail <key>

ステップ 4：アダプターにパッチを適用する

トレースの概要のフロントマターにある adapterSourcePath からアダプターのソースファイルを読み、対象を絞って修正します。このパスが正しいパスです — リポジトリ内（clis/）またはユーザーのローカル環境（~/.opencli/clis/）にある場合があります。

Read ツールを使って、summary.md のフロントマターに記載された正確なパスを読みます。

よくある修正

セレクターの更新：

// 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.wait({ selector: '.loading-spinner', hidden: true })
// After:  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：修正を検証する

# Run the command normally
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 repaired this adapter locally, and the retry passed.

## Adapter
- Site: `<site>`
- Command: `<command>`
- OpenCLI version: `<version from opencli --version>`

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

~~~
<error_message>
~~~

## Local fix summary

~~~
<1-2 sentence description of what you changed and why>
~~~

_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 "<the body above>"

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

停止するタイミング

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

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

条件付き停止（試行後に報告）：

• 3 回の修正ラウンドを使い切った — 停止し、試したことと失敗した内容を報告します
• 機能が完全に削除された — データはもう存在しません
• 大規模な再設計 — opencli-adapter-author スキルを使ったアダプターの全面的な書き直しが必要です

停止する場合は、無駄な修正を試みるのではなく、状況をユーザーにはっきりと伝えてください。

修正セッションの例

1. User runs: opencli zhihu hot
   → Fails: SELECTOR "Could not find element: .HotList-item"

2. AI runs: opencli zhihu hot --trace retain-on-failure 2>trace-error.yaml
   → Gets trace summary with final state and failed action evidence

3. AI reads summary/state: page loaded but uses ".HotItem" instead of ".HotList-item"

4. AI explores: opencli browser --session research open https://www.zhihu.com/hot && opencli browser --session research state
   → Confirms new class name ".HotItem" with child ".HotItem-content"

5. AI patches: Edit adapter at `adapterSourcePath` — replace ".HotList-item" with ".HotItem"

6. AI verifies: opencli zhihu hot
   → Success: returns hot topics

7. AI prepares upstream issue draft, shows it to the user

8. User approves → AI runs: gh issue create --repo jackwener/OpenCLI --title "[autofix] zhihu/hot: SELECTOR" --body "..."