Onboarding + Config Protocol の実装ガイド

新しいツールを導入する際、CLI と UI でセットアップ手順が異なり、戸惑うことはありませんか？一方で行った設定がもう一方に反映されないといった同期の悩みは、開発者の生産性を下げる要因になります。

こうした問題を解決するには、すべてのインターフェースで共通のプロトコルを使用するのが最適です。セットアップのロジックを Wizard engine として共通化することで、どの環境からでも一貫した体験を提供できます。

必要なもの

このプロトコルを実装・利用するために必要な要素は以下の通りです。

• Wizard engine（セッション、プロンプト、状態管理の共有）
• Gateway RPC
• CLI および macOS アプリ
• Web UI

クイックスタート

共通プロトコルを使用して、5分でセットアップフローを開始する手順です。

1. Wizard の開始

Gateway RPC の wizard.start を呼び出してセッションを開始します。mode は local または remote を指定できます。

// wizard.start params
{
  "mode": "local",
  "workspace": "your-workspace-path"
}

2. ステップの進行と回答

wizard.next を使用して、ユーザーの回答を送信し、次のステップへ進みます。

// wizard.next params
{
  "sessionId": "current-session-id",
  "answer": {
    "stepId": "current-step-id",
    "value": "user-input-value"
  }
}

3. ステータスの確認

必要に応じて wizard.status で現在のセッション状態を確認します。レスポンスには done（完了フラグ）や step の情報が含まれます。

// Wizard response shape
{
  "sessionId": "id",
  "done": false,
  "step": { ... },
  "status": "active"
}

4. 設定スキーマの取得

Web UI などで設定フォームをレンダリングするために、JSON Schema と uiHints を取得します。

// config.schema params
{}

トラブルシューティング

実装中によくある問題と解決策です。

• Wizard でエラーが発生する場合: レスポンスに含まれる error フィールドを確認してください。Wizard のレスポンス形状には、エラー情報が含まれる設計になっています。
• UI で特定の項目が表示されない: uiHints が正しく設定されているか確認してください。サポートされていないスキーマノードがある場合、自動的に raw JSON editor にフォールバックされます。
• 機密情報の表示: sensitive フィールドとして指定された項目は password input としてレンダリングされます。ただし、このプロトコルには redaction layer（伏せ字レイヤー）は存在しない点に注意してください。

---

詳細な設定や不明な点の解決には、AI Setup Assistant を活用してください。

次のステップ

• Wizard Flow の詳細仕様
• Gateway RPC API リファレンス