opencli-repair

OpenCLI Repair — AI 駆動のアダプター自己修復

ウェブサイトの DOM、API、または認証フローが変更されてアダプターが動作しなくなった場合、このスキルを使って問題を診断し、アダプターに修正を加えます。

前提条件

opencli doctor    # Verify extension + daemon connectivity

このスキルを使用するタイミング

opencli <site> <command> が次のようなエラーで失敗した場合に使用します。

• SELECTOR — 要素が見つからない（DOM が変更された）
• EMPTY_RESULT — データが返されない（API レスポンスが変更された）
• API_ERROR / NETWORK — エンドポイントが移動した、または機能しなくなった
• PAGE_CHANGED — ページ構造が一致しなくなった
• COMMAND_EXEC — アダプターのロジックでランタイムエラーが発生した
• TIMEOUT — ページの読み込み方法が変わり、アダプターが誤った対象を待っている

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

解析します。

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

ステップ 2：失敗を分析する

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

エラーコード	考えられる原因	修復方針
SELECTOR	DOM の再構成、class/id の名前変更	現在の DOM を調べる → 新しいセレクターを見つける
EMPTY_RESULT	API レスポンスのスキーマ変更、またはデータの移動	ネットワークを確認する → 新しいレスポンスのパスを見つける
API_ERROR	エンドポイント URL の変更、新しいパラメーターが必要	ネットワークインターセプトで新しい API を見つける
AUTH_REQUIRED	ログインフローの変更、Cookie の期限切れ	operate でログインフローをたどる
TIMEOUT	ページの読み込み方法の変更、スピナー／遅延読み込み	待機条件を追加／更新する
PAGE_CHANGED	大幅な再設計	アダプター全体の書き直しが必要な場合がある

確認すべき主な質問：

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

ステップ 3：現在のウェブサイトを調べる

opencli operate を使って、現在のウェブサイトを調査します。動作しなくなったアダプターは絶対に使わないでください。再び失敗するだけです。

DOM の変更（SELECTOR エラー）

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

# Interact to trigger API calls
opencli operate click <N> && opencli operate network

# Inspect specific API response
opencli operate network --detail <index>

認証の変更（AUTH_REQUIRED）

# 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

ステップ 4：アダプターに修正を加える

アダプターのソースファイルを読み、対象を絞って修正します。

# Read the adapter
cat <sourcePath from diagnostic>

よくある修正

セレクターの更新：

// 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. 修正後にテストする — コマンドを再実行して、修正を確認してください

ステップ 5：修正を検証する

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

それでも失敗する場合は、ステップ 3 に戻ってさらに調査します。ウェブサイトが根本的に変更されている場合（大幅な再設計、機能の削除）は、アダプター全体の書き直しが必要であることを報告します。

あきらめるタイミング

すべての失敗を簡単な修正で解決できるわけではありません。

• サイトで CAPTCHA が必要 — 自動化できません
• 機能が完全に削除された — データが存在しなくなっています
• 大幅な再設計 — opencli-explorer スキルを使ったアダプター全体の書き直しが必要です
• レート制限／IP ブロック — アダプターの問題ではありません

このような場合は、無駄な修正を試みるのではなく、状況を明確にユーザーに伝えてください。

修復セッションの例

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

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