opencode-qa

opencode QA

opencode コーディングエージェント自体を QA します。このスキルでは、QA の各ニーズに、テスト済みのヘルパースクリプトと詳細なリファレンスを対応付けています。すべてのスクリプトには、稼働中のマシンでシナリオを検証する --self-test が用意されているため、スクリプトは QA ツールであると同時に、自身の回帰チェックも担います。

opencode v1.17.7（bun 1.3.12、macOS）で検証済みです。インストール済みのバージョンは opencode --version で確認してください。インターフェースは安定していますが、フラグは必ず opencode <cmd> --help で動作を確認してください。

基本ルール（実行前にお読みください）

• 稼働中の DB の読み取りは安全であり、想定された操作です。セッションの調査（ケース D）では、~/.local/share/opencode/opencode.db のみを読み取ります。
• opencode を起動する操作（serve、run、TUI）では、QA によって実際の DB に不要なセッションが書き込まれないよう、分離された XDG サンドボックスを使用する必要があります。付属のスクリプトではすでにこの設定が済んでいます。QA のために opencode を手動で実行する場合は、最初に XDG_DATA_HOME / XDG_CONFIG_HOME / XDG_STATE_HOME / XDG_CACHE_HOME を一時ディレクトリに設定してください。
• part テーブル全体を対象にしたグローバルテキスト検索では、数 GB のスキャンが発生します。必ず対象を絞り込んでください（--session、--recent、または --since）。テキストスクリプトでは、意図的に絞り込みのないスキャンを拒否します。
• opencode のソースリポジトリ（packages/opencode）では bun test を使ってテストしますが、リポジトリのルートからはテストを実行できません。references/testing-harness.md を参照してください。

セットアップ

スクリプトはこのファイルと同じ場所にある scripts/ にあります。このスキルのディレクトリから（または絶対パスを使って）実行してください。

cd <this-skill-dir>                        # .agents/skills/opencode-qa
bash scripts/lib/common.sh --self-check    # confirm the harness + deps

QA では Docker を標準として使用します。 最新の opencode と設定のコピーがある使い捨てコンテナ内で QA を実行し、ホストには変更を加えません。script/agent/qa-docker.sh を使用してください（references/docker-qa.md を参照）。 以下のローカルスクリプトは、Docker を利用できない場合や Windows での代替手段です。

common.sh は共有ハーネス（DB パス、SQL エスケープ、分離された XDG サンドボックス、空きポート、サーバーの起動／停止、EXIT トラップによるクリーンアップ）を提供します。PATH 上に opencode、sqlite3、curl、jq、tmux が必要です。

ルーター：ケースを選択する

やりたいこと	ケース	スクリプト	リファレンス
opencode を非対話形式で実行する／CLI コマンドを確認する	A	opencode run --format json（インライン）	references/cli-commands.md
ID からセッションを検索する	D	scripts/db-session-by-id.sh <ses_id>	references/db-investigation.md
タイトル／名前からセッションを検索する	D	scripts/db-session-by-name.sh "<text>"	references/db-investigation.md
メッセージのテキストからセッションを検索する	D	scripts/db-session-by-text.sh --recent N "<text>"	references/db-investigation.md
セッション全体を JSON としてエクスポートする	D	scripts/export-roundtrip.sh <ses_id>	references/db-investigation.md
HTTP サーバー／エンドポイントを確認する	B	scripts/server-smoke.sh	references/server-api.md
フック／アクション／イベントが発火したことを検証する	B	scripts/sse-hook-probe.sh	references/events-hooks.md
serve-topology wake runner-split の再現／修正を検証する	B	scripts/serve-wake-split-probe.sh --expect reproduced|fixed --evidence-dir DIR（セルフテスト：--self-test、偽の LLM：scripts/lib/fake-openai-server.mjs）	references/events-hooks.md
TUI のスモークテストを行う	C	scripts/tui-smoke.sh	references/tui-tmux.md
opencode のソースでテストを作成／実行する	-	（bun test）	references/testing-harness.md
Bun/TS スクリプトから opencode を操作する	-	（SDK）	references/sdk.md

ケース A：CLI／ターミナルが動作する

スクリプトから実行する場合の標準的な非対話型エントリーポイントは opencode run です。JSON モードではイベントが 1 行ずつ出力されるため、内容を検証できます。

# stream structured events (types: text, tool_use, step_start, step_finish, reasoning, error)
opencode run "list files in src" --format json
# run a slash command
opencode run --command commit
# resume the last session
opencode run -c "continue"
# target an already-running server instead of booting one
opencode run "explain auth" --attach http://127.0.0.1:4096 -p "$OPENCODE_SERVER_PASSWORD"

QA に役立つその他のコマンド：opencode db path、opencode debug paths、opencode session list --format json、opencode models --verbose。フラグの詳細は references/cli-commands.md を参照してください。

ケース B：特定のフック、アクション、またはイベント

opencode は、Server-Sent Events を通じてライフサイクルイベントを GET /event で公開します。 プラグインは event フックを通じて同じイベントを監視するため、ワイヤー上でイベントを確認できれば、フックが発火することも証明できます。

# prove the SSE plumbing works (isolated server, asserts server.connected)
bash scripts/sse-hook-probe.sh --self-test

# watch a REAL server for a specific event while you trigger an action
bash scripts/sse-hook-probe.sh --attach http://127.0.0.1:4096 \
  --password "$OPENCODE_SERVER_PASSWORD" --directory "$PWD" \
  --event message.part.updated --timeout 30

HTTP 経由でアクションをトリガーします（ストリームがブロックされないよう、結果を待たずに実行します）。

curl -X POST -u opencode:$OPENCODE_SERVER_PASSWORD -H 'Content-Type: application/json' \
  -d '{"parts":[{"type":"text","text":"say hi"}]}' \
  "http://127.0.0.1:4096/session/<ses_id>/prompt_async?directory=$PWD"

実際のプロンプトには設定済みのプロバイダーが必要なため、分離されたサンドボックスではなく、実際のサーバーに対して監視とトリガーのパターンを実行してください。イベントタイプのカタログ、21 個のプラグインフックポイント、ローカルプラグインの読み込み方法については、references/events-hooks.md を参照してください。 サーバーの起動、認証、ルートについては、references/server-api.md を参照してください。

ケース C：TUI

bash scripts/tui-smoke.sh --self-test

これにより、分離されたサンドボックス内で tmux を使って TUI を起動し、表示されること（capture-pane）と、send-keys がコンポーザーに届くことを確認した後、tmux セッションを終了し、実際の DB セッション数が変わっていないことを確認します。

PR で TUI のビジュアル QA の証跡が必要な場合は、docs/reference/web-terminal-visual-qa.md に従ってください。実際の xterm.js ウェブターミナルを通じて TUI を表示し、スクリーンショットを撮影してください。色と CJK の幅が損なわれる tmux capture-pane のフレームは絶対に使用しないでください。リポジトリのルートから実行します。

node script/qa/web-terminal-visual-qa.mjs --title "OpenCode TUI QA" \
  --command "opencode" --input "{Enter}" \
  --evidence-dir .omo/evidence/<slug>/opencode-web-terminal

これにより実際の pty が起動し、Chrome 上の xterm.js で表示され、terminal.txt、terminal-ansi.txt、terminal.png（真の色を保持する成果物）、およびクリーンアップの記録を含む metadata.json が書き出されます（--from-file <capture.ansi> は保存済みの生ストリームを再生します）。分離された scripts/tui-smoke.sh は、今回のビジュアル証跡とは別に、OpenCode TUI の起動を確認する標準のスモークテスト（tmux）として引き続き使用します。

率直な結論：tmux はスモークテスト（起動したか、表示されたか、キー入力を受け付けたか）には適していますが、会話の出力を検証するには不安定です（TUI は 60fps の全画面アプリです）。実際の動作を検証するには、ケース A（opencode run）、ケース B（サーバー API と SSE）、または TUI 制御用 HTTP API（POST /tui/append-prompt、POST /tui/submit-prompt、POST /tui/execute-command）を使用してください。詳細と tmux を手動で使う手順については、references/tui-tmux.md を参照してください。

ケース D：DB 内のセッションを調査する

実行中の SQLite DB に対する読み取り専用の操作です。session テーブルは小さいため（タイトルや ID の検索は即座に完了します）が、メッセージ本文は数 GB の part テーブルに格納されているため、テキスト検索の範囲を絞る必要があります。

# by id
bash scripts/db-session-by-id.sh ses_3a4ee6335ffedFB8f76BPU1Eb3
# by title / name (newest first; second arg = limit)
bash scripts/db-session-by-name.sh "auth refactor" 20
# by message text - scope with --session, --recent N, or --since "<window>"
bash scripts/db-session-by-text.sh --session ses_3a4e... "ULTRAWORK"
bash scripts/db-session-by-text.sh --recent 50 "permission denied"
bash scripts/db-session-by-text.sh --since "7 days" --limit 50 "TODO"
# export an entire session as clean JSON
bash scripts/export-roundtrip.sh ses_3a4e... > session.json

アドホックなクエリには、opencode db "<SQL>" --format json を使用します。スキーマ、実行時間付きのテスト済みクエリ形式、従来の message／part と V2 の session_message の違い、および 25 GB に関する注意事項については、references/db-investigation.md を参照してください。

スクリプト一覧

--self-test を付けて任意のスクリプトを実行すると、実際のマシン上で動作を検証できます。使い方を確認するには -h を指定してください。DB 読み取り用のスクリプトは読み取り専用です。serve／sse／tui スクリプトは分離されたサンドボックスを使用し、終了時にクリーンアップします。

スクリプト	ケース	セルフテストでの検証内容
scripts/lib/common.sh --self-check	-	依存関係が存在する、DB パスが解決される、SQL エスケープが機能する、空きポートを確認できる、サンドボックスが自動削除される
scripts/db-session-by-id.sh	D	実際のセッション ID が往復して一致する
scripts/db-session-by-name.sh	D	導出したタイトルの検索文字列で 1 行以上が返される
scripts/db-session-by-text.sh	D	範囲を絞った検索で結果が返される、範囲を絞らないスキャンは拒否される、範囲を絞った検索が 30 秒未満で完了する
scripts/export-roundtrip.sh	D	エクスポートの標準出力が有効な JSON であり、.info.id が往復して一致する
scripts/server-smoke.sh	B	/global/health が正常、/doc に 100 以上のパスがある、認証なしの場合は 401 が返される
scripts/sse-hook-probe.sh	B	/event が接続され、server.connected が配信される
scripts/tui-smoke.sh	C	TUI が tmux 上で表示され、終了後も実際の DB に変更がない

リスクと注意事項

• 25 GB のパートテーブル：無制限のテキストスキャンは実行しないでください。--session、 --recent、または --since を使用してください。単純な JOIN ... WHERE session.time_created >= X は古いデータからスキャンするため、約50秒かかることがあります。スクリプトでは、最新のセッションを対象にした IN サブクエリを使用しており、約20ミリ秒で完了します。
• opencode export はバナーを STDERR に出力します。jq の前に 2>/dev/null を指定してパイプしないと、 パースエラーが発生します。
• サーバーが認証を適用するのは、OPENCODE_SERVER_PASSWORD が設定されている場合のみです。 それ以外の場合、認証なしで実行されます。認証付きの呼び出しでは -u opencode:$PASS を使用します。 認証が必要なサーバーに認証なしで呼び出すと、HTTP 401 が返されます。
• インストール済みバイナリと開発用ソース：内部実装については開発用ソースのパスを参照し、 フラグについてはインストール済みの opencode <cmd> --help で確認してください。
• 隔離：opencode を起動する QA は、実際の DB を汚染しないよう、隔離された XDG サンドボックスを使用する必要があります。 実行前と実行後に sqlite3 "$(opencode db path)" "SELECT count(*) FROM session" を比較して確認してください。
• TUI の出力に対するアサーションは不安定です。実際のアサーションには API を使用してください。

参考資料

• references/cli-commands.md - QA に関連する opencode のすべてのサブコマンドとフラグ
• references/db-investigation.md - DB スキーマ、検証済みのクエリ、25 GB に関する注意事項
• references/server-api.md - サーバーの起動、認証、ルート一覧、/doc
• references/events-hooks.md - SSE エンドポイント、イベントタイプ、プラグインフック
• references/tui-tmux.md - tmux の手順、隔離、TUI 制御 API
• references/testing-harness.md - opencode 自身のテスト方法（bun test）
• references/sdk.md - @opencode-ai/sdk クライアント（参考情報のみ）
• references/docker-qa.md - 使い捨ての Docker コンテナで QA を実行する方法（デフォルト。ローカル実行は代替手段）