はじめに

​
失敗を報告して再検証する

コマンドが失敗する、取得結果が依頼に合わない、同じ手順を完了できないときに使います。コマンドの終了コードが 0 でも、結果が部分的・不正確なら報告対象です。失敗したワークフローの URL と手順を起点に、期待した結果と実際の結果を Orchestor へ送ります。

このワークフローで失敗した箇所を切り分け、秘密情報を除いた再現手順をまとめてください。送信する内容を確認してから、Orchestor のフィードバックに送り、受付 ID を残してください。

​
1. 失敗した段階を確認する

セットアップの診断で、認証、対象ワークスペース、権限、実際の取得を確認します。引数や対象の間違いを直して完了できた場合は、その結果を返します。同じ不具合が残る、仕様に反する、説明どおりに進められない場合は報告へ進みます。

再試行は API のエラーと待機指示に従います。書き込みの結果が不明な場合は読み戻しや元の冪等キーで確認し、新しいキーで同じ操作を繰り返しません。空のデータ、認証失敗、実装されていない提案コマンドを、一律に製品の不具合とは判断しません。

​
2. 再現できる報告を用意する

次の情報を message の 2,000 文字以内にまとめます。報告先は Orchestor のフィードバック受付です。

情報記録する内容
起点ワークフロー URL、失敗した手順、利用者が達成したかったこと
環境CLI バージョン、OS、エージェント名。実測値だけを記載
再現秘密を除いたコマンド、対象の種類、必要最小限の操作
期待と実際期待した出力と、実際のエラーコード・症状・発生時刻
証拠応答で得られた request ID や実在する run ID。取得できなければ「未取得」
試したこと再試行や対象確認の結果、利用できる回避策

API キー、認証ヘッダー、環境変数の一覧、会話全文、顧客の回答本文を貼り付けません。送信する範囲を利用者が確認できる形にし、送信の依頼または継続的な許可がある場合に送ります。自動報告を無効にした利用者には下書きだけを返します。サーバー側の伏せ字処理だけに依存せず、送る前に内容を取り除きます。

client_context に保存されるのは url、route、app_revision、locale などの既定項目です。任意の workflow_id や run_id を追加しても保存されません。現在はそれらを message に含めます。conversation_id は実際の Orchestor 会話があるときだけ指定し、他の実行 ID を代入しません。

次の JSON を feedback.json に保存し、角括弧の内容を確認済みの情報へ置き換えます。

{
  "category": "slow-or-broken",
  "message": "Workflow: /cli/workflows/install-first-read\nStep: [failed step]\nCLI/OS/agent: [measured versions]\nReproduce: [redacted command]\nExpected: [expected result]\nActual: [error and time]\nRequest/run ID: [observed ID or unavailable]\nAttempted: [checks and results]",
  "client_context": {
    "route": "/cli/workflows/install-first-read",
    "locale": "ja"
  }
}

不正確な出力は inaccurate、指示への不一致は instruction-not-followed、対象の取り違えは out-of-scope、動作不良は slow-or-broken、その他は other を選びます。各カテゴリーの仕様は feedbacks リファレンスを参照してください。

--stdin を使う場合は JSON の category が必須 body field を満たすため、--category を重複指定する必要はありません。フラグだけで送る場合は --category を指定します。

​
3. 内容を確認して送る

認証済みの送信が既定です。認証できる場合は、報告対象の workspace を指定して送ります。ログイン自体の失敗を報告する場合は --anonymous を指定します。匿名送信は保存済みの API キー、ブラウザーの cookie、設定済みの workspace を使いません。--workspace や --screenshot-file-ids と併用できません。

WORKSPACE_ID を報告対象に置き換え、同じ報告の再送で使うキーを一度だけ生成します。この値は API キーではありません。再試行に備えて、報告と一緒にローカルで保持します。

FEEDBACK_IDEMPOTENCY_KEY=$(node -p 'crypto.randomUUID()')
orc feedbacks create --stdin --workspace WORKSPACE_ID --dry-run < feedback.json

内容と対象ワークスペースを確認したら送信します。WORKSPACE_ID を報告対象に置き換えてください。

orc feedbacks create --stdin --workspace WORKSPACE_ID \
  --idempotency-key "$FEEDBACK_IDEMPOTENCY_KEY" --json < feedback.json

返された feedback_id を保存します。これは受付の証拠であり、担当者への通知完了や修正完了を意味しません。タイムアウトで受付が不明なら、同じ本文・対象・冪等キーで再試行します。冪等キーの保持期間は 24 時間です。本文を変更した別の報告には新しいキーを使います。

ログインできない場合は、同じ確認済みの報告を匿名で送信します。この例にブラウザーの cookie や API キーは不要です。

orc feedbacks create --anonymous --category slow-or-broken --stdin \
  --idempotency-key "$FEEDBACK_IDEMPOTENCY_KEY" --json < feedback.json

送信が失敗した場合は報告をローカルに残し、「未送信」と失敗理由を返します。フィードバック送信の失敗をさらに自動送信するループは作りません。

​
4. 受付と修正後の結果を確認する

ワークスペースの owner は直近の受付を一覧で確認できます。一般の利用者にはこの一覧の権限がないため、作成時の受付 ID を保持します。

orc feedbacks list --workspace WORKSPACE_ID --json

一覧は最新 20 件です。見つからないことだけで送信失敗と判断しません。new、triaged、resolved は保存される状態ですが、CLI に状態更新コマンドはありません。

修正版を確認できたら、元のワークフロー、対象、入力、期待結果を揃えて同じ手順を実行します。受付 ID、検証したバージョン、再実行の結果、残る問題を記録します。受付や resolved の表示だけを、再現手順が成功した証拠にはしません。

ワークフロー一覧 · feedbacks リファレンス · セットアップの診断