opencli-adapter-author

アダプターの作成

依頼されたタスクを確実に実行できる、最もシンプルな実装を選びます。 必要な機能を備えた既存のサイトアダプターがある場合は、それを使用します。

opencli list search --site example
opencli example search --help -f json

list は {ok:true,data:{commands,total,nextOffset?}} を返します。続きを取得するには --offset を使用し、ページサイズを調整するには --limit を使用します。詳細な引数はコマンドのヘルプに記載します。

利用できるエビデンス

opencli browser open https://example.com --session research
opencli browser state --diagnostics --session research
opencli browser network --session research
opencli browser network --static --session research
opencli browser network --detail RequestKey --session research

ネットワークキャプチャには、観測されたリクエストが記録されます。静的解析では、読み込まれたスクリプトから候補を追加しますが、スクリプトは実行しません。ソースの場所、解決されていない式、キャプチャの出所を確認してください。必要に応じて読み取りリクエストを再生し、業務データとページの内容を比較してください。書き込みコマンドは、adapter test 経由で実行する場合も含め、実際の影響を伴います。適切なテストアカウントを使うか、対応しているドライランを利用してください。

利用可能な場合は、安定した契約を持つ公開 API を優先してください。ブラウザ fetch、キャプチャしたレスポンス、ページ状態、セマンティックな UI 操作も有効な選択肢です。タスクと観測された信頼性に基づいて選んでください。エンドポイントのパラメーターを推測したり、失敗した操作を空の成功結果で覆い隠したりしないでください。

JS インターフェース

アダプターは ~/.opencli/clis/<site>/<command>.js またはリポジトリの clis/<site>/ に置く通常のファイルです。ドラフト用ディレクトリ、昇格手順、必須のメモリーファイルはありません。

opencli adapter init example/search

既存の cli({...}) インターフェースに変更はありません。Node で実行する場合は func(args)、browser: true の場合は func(page, args) を使います。近隣のアダプターや共有ヘルパーを再利用してください。業務データを返します。JSON の成功エンベロープは CLI が追加します。失敗時は、具体的な対応方法を示すヒントを含む型付きエラーをスローしてください。access: 'read'|'write' は正確に設定します。columns は人が読む形式のテーブル出力を制御します。JSON ではネストされた結果が保持されます。

import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'example', name: 'search', description: 'Search example items',
  access: 'read', strategy: Strategy.PUBLIC, browser: false,
  args: [{ name: 'query', positional: true, required: true }],
  func: async (args) => {
    const response = await fetch(`https://example.com/api/search?q=${encodeURIComponent(args.query)}`);
    if (!response.ok) throw new Error(`Search failed: HTTP ${response.status}`);
    return response.json();
  },
});

確認と実行

opencli adapter check example/search
opencli example search 'query'
opencli adapter test example/search --args '{"query":"query"}'

check はアダプターを実行せずに定義を検証します。test は通常の CLI を実行し、必要に応じて既存のフィクスチャと比較します。--write-fixture、--update-fixture、--no-fixture で任意の期待値を制御できます。行の形式やサイトのメモリーに関する必須チェックはありません。--trace retain-on-failure は、ブラウザー実行の問題を診断する際に役立ちます。

リポジトリを変更する場合は、実運用経路の重要な動作と失敗経路を対象としたテストを追加し、型チェックとビルドを行ってください。タスクに関係する ID、フィールド、単位、ページネーション、空の場合やエラー時の挙動を確認してください。結果が不明な書き込みを自動的に再実行しないでください。先に状態を確認します。

参考資料（任意）

現在のタスクに役立つ資料のみを読んでください。アダプターのパターンについては references/adapter-template.md、リクエストの調査については api-discovery.md、結果フィールドについては output-design.md、不透明なフィールドについては field-decode-playbook.md、難解なプライベートプロトコルについては deep-recon.md を参照してください。サイトのメモやフィクスチャは任意の参考資料です。古い参考用チェックリストに従う必要はありません。