stackbone-debug

Stackbone デバッグスキル

このスキルでは、Stackbone ワークスペースで障害の原因を特定する方法を説明します。エラーの一覧は含まれていません。各コード、ステータス、メッセージの意味はドキュメントに記載されているため、コードが分かったらドキュメントで確認してください。

情報の参照先

ドキュメントは、MCP サーバー stackbone-docs（https://docs.stackbone.ai/mcp、公開、ツール search_docs、get_doc、list_docs）を通じて提供されています。stackbone docs を実行すると、接続情報が表示されます。

• セッションは list_docs から開始してください。 各領域とセクションに含まれるすべてのページが返されます。以下の所有ページの探し方では、コードや症状に該当するページを説明しています。そのページのパスを一覧から取得して、get_doc で読み込んでください。パスを記憶に頼って入力してはいけません。ページは移動しますが、タイトルは変わりません。
• エラーコードが分かったら、そのコードを扱うページを読みます。エラーのセクションに、コードの意味と次に確認すべきことが記載されています。
• コードのないメッセージが分かったら、まずメッセージそのものを search_docs で検索し、次に症状を平易な言葉で検索します。
• コードの意味を記憶に頼って説明しないでください。コードは安定していますが、原因や次に実行するコマンドはリリースによって変わります。

セッションで stackbone-docs のツールを使えませんか？ https://docs.stackbone.ai/llms.txt を取得してください。同じインデックスが、ページごとに1行で、タイトル、説明、raw Markdown へのリンクとともに記載されています。タイトルでページを選び、そのリンクを取得してください。https://docs.stackbone.ai/llms-full.txt には、すべてのページが1つのファイルにまとめられています（約700 KB）。

このスキルの使い方

1. 症状をそのまま記録します：エラーメッセージ、HTTP ステータス、実行 ID、正確なコマンドを記録してください。言い換えてはいけません。
2. コードを取得します。 CLI コマンドを --json 付きで再実行し、error.code と error.suggestion を確認します。SDK 呼び出しでは result.error.code を確認し、HTTP レスポンスではステータスと本文を確認します。実行のログフレームも確認してください。
3. 以下の表から最初の診断をそのまま実行します。ここにあるコマンドはすべて読み取り専用です。変更を加える操作（retry、cancel、approve、reject）には ⚠️ が付いており、実行前にユーザーへ提案する必要があります。
4. 所有ページを読みます（探し方）。コードの意味と次に確認すべきことを調べてください。
5. 確認した内容をコマンドの出力そのまま添えて報告し、適切なスキルに引き継ぎます。コードの変更は stackbone スキルに、コマンドや移行は stackbone-cli スキルに引き継ぎます。

失敗した実行を特定する

エージェントの各ターンと各ワークフロー実行は、ステータス（running / done / failed / interrupted）とログを持つ永続的な実行です。デフォルトの対象は local-dev インストールで、stackbone dev を実行しておく必要があります。デプロイ済みのエージェントを対象にするには、stackbone agents list --json で取得した --agent <id> を指定してください。

stackbone runs list --status failed --json          # find the run id
stackbone runs get <runId> --json                   # header: status, trigger, timing
stackbone logs tail --run <runId> --json            # the per-step frames: each 'use step', its retries, the error that failed it
stackbone logs tail --level error --json --follow   # watch a live installation

runs steps という動詞はありません。ステップのウォーターフォールはログフレームに記録されています。Studio の Runs タブにも同じタイムラインが表示されます。

症状 → 最初の診断

症状	最初の診断
stackbone コマンドが失敗する	--json を付けて再実行し、error.code と error.suggestion を確認します。必要に応じて STACKBONE_LOG_LEVEL=debug でログを詳しくし、起動段階を確認するにはさらに --verbose を付けます
プロジェクトがない状態で終了コード 3 になる／dev_not_running	stackbone metadata --json を実行します。.stackbone/project.json はありますか。stackbone dev は起動していますか
--agent に対して終了コード 4 runtime_not_configured になる	stackbone agents get <slug> --json を実行します。このボックスには登録済みのデプロイがありません
stackbone dev が停止する、または自分のものが何も起動しない	起動バナーを確認します。初回起動時はモデルプロバイダーを待機します（Studio のリンクが表示されます）
ワークフローの開始が拒否され、実行が作成されない（HTTP 400）	stackbone workflows schema <name> --json を実行し、リクエスト本文と 400 の issues[] を比較します
workflow_not_found／workflows list に何も表示されない	workflows/<name>.workflow.ts はありますか。dev はそれを提供していますか
ステップが再試行された後、実行が失敗する	stackbone logs tail --run <runId> --json で、繰り返し発生している error.cause を確認します。ステップは冪等ですか
実行が進展のないまま running で止まっている	requestApproval() ゲートで保留中です。stackbone hitl list --status pending --json を実行します
実行が一時停止しているが、受信トレイが空	stackbone logs tail --run <runId> --json で approval_persist_failed を確認します。または、一時停止がタイムアウトし、fallback が実行された可能性があります
ゲート付きツールでエージェントのターンが interrupted になり、新しいメッセージが拒否される	決定されるまでは想定どおりです：stackbone hitl list --status pending --json → ⚠️ stackbone hitl approve <id> --yes --json
エージェントが会話を忘れた	クライアントは x-stackbone-session を送信しましたか。ワークスペースにチェックポインターのピアはありますか（起動ログに一度だけ警告が表示されます）
実行は成功するが、出力がない	本文が outputSchema に一致するオブジェクトではなく、undefined を返しました
スケジュールが実行されない、または二重に実行される	stackbone workflows list --json を実行します。ステップから stackbone.workflows.listSchedules() を呼び出します
stackbone.connection(id) が例外をスローする	err.code を確認します：connector_installation_required → オペレーターが Studio でそのコネクターをインストールしていません。credential_error／no_token → そのコネクターの認証情報に問題があります。id はコネクターのそのままの id であり、接続ごとの id ではありません
アップロードしたばかりのキーでストレージが 404 を返す。署名付き URL が 403 を返す	アップロード時に error を確認しましたか。URL の TTL が切れていませんか。ローカルの MinIO は起動していますか
クエリが遅い、pgvector の順序が誤っている、tsvector 検索が空になる	stackbone db schemas --json と stackbone db query "<single SELECT>" --json を実行します。EXPLAIN には STACKBONE_POSTGRES_URL 上の psql が必要です
stackbone build／package が中断する	メッセージで、ネイティブ依存関係または 2 つ目の SDK コピー（ネストされた node_modules またはエージェントごとの固定バージョン）が示されています
stackbone.secrets.get が secrets_not_found／_decrypt_failed を返す	stackbone secrets list --json を実行します（名前のみ表示され、値はマスクされます）
モデル呼び出しが何も返さない、429、402 になる	result.error.code（ai_*）を確認し、Studio のゲートウェイ画面でモデルプロバイダーを確認します

オーナーページの見つけ方

• SDK コード（result.error.code の <prefix>_<reason>）：sdk エリアを指定して、コードをそのまま search_docs します。オーナーページにはコードがエラー表に記載されているため、最上位の検索結果がそのページです。プレフィックスは対象の領域を示します（ai_* → stackbone.ai、rag_* → stackbone.rag、secrets_* → stackbone.secrets、…）。例外は 2 つあり、s3_* は stackbone.storage、approval_* は Human-in-the-loop に属します。contract_* と capability_unavailable は @stackbone/sdk overview（SDK › Reference）で説明されています。
• ConnectorCallError コード（connector_installation_required、credential_error、invalid_args、…）：全コードの一覧が記載されている stackbone.connection（SDK › Platform）を参照します。instanceof ではなく、err.code を照合してください。
• CLI の error.code（dev_not_running、runtime_not_configured、no_project、…）または終了コード：まず Troubleshooting（CLI › Guides）、次に終了コードの表がある Configuration reference（CLI › Reference）を参照します。
• box または control plane からの HTTP ステータス：ステータスとルート（400 workflow_input_invalid、404 workflow_not_found）を指定して search_docs します。ワークフローのルートは CLI › Agent protocol にあります。402 の本文（tier_quota_exceeded、*_cap_reached）は SdkError ではなく、再試行もできません。メッセージをそのまま表示してください。アップグレードは組織のオーナーが行います。
• 後から読みたい実行：Logging & observability（SDK › Platform）を参照します。登録されない、または応答しない box については、Home › Deploy の Troubleshooting を参照します。

混同しないための 3 つのポイント

• 例外をスローするのは 3 つの領域で、それ以外は { data, error } を返します。 stackbone.database は Drizzle/Postgres エラーをスローします。callDeepAgent / streamDeepAgent は例外をスローし、外側のステップを失敗させます。stackbone.connection(id) は ConnectorCallError をスローします（instanceof ではなく、err.code を照合してください）。それ以外はすべて、コードを result.error.code に格納し、構造化された詳細情報を取得するための手段として meta と cause を提供します。
• 402 は control plane の本文であり、SDK コードではありません。 クレジットバンドルを使い切った場合に相当する SDK 側のコードは ai_credits_exhausted です。
• 別の組織の --agent <id> に対する 404 は想定どおりです。 Studio でも、存在が漏れないよう同じ 404 を使用します。

このスキルの対象外

ランタイムのパフォーマンス調整（コールドスタート、サイジング）、402 の本文を超えるコスト分析、カスタム OTel パイプラインは対象外です。これらについて現在サポートされている画面は、Studio の Logs タブと Costs タブです。

その他のスキル

• stackbone：コード（defineDeepAgent、ステップ、アンビエント呼び出し）を修正する場合に使用します。
• stackbone-cli：コマンド、マイグレーション、デプロイ手順を修正する場合に使用します。
• stackbone-coder：1 行のアイデアから始めて、ヒアリングを通じて新しいものを作成します。