Antigravity CLI 工具使用指南：ask_question

Antigravity CLI 的 ask_question 是提供給 AI 代理使用的內建互動工具。它透過單一的 JSON 結構，彈出互動式視窗來收集使用者的意向。

儘管只有一種 API 結構，但透過調整參數，可以實現 Yes/No、多選，以及包含開放式對話框等多種互動情境。

1. Yes/No 格式（單選確認）

適用於需要使用者明確同意或拒絕的操作。設定兩個選項，並關閉多選功能。

Json 樣式

{
  "questions": [
    {
      "question": "你確定要執行這個操作嗎？這將會覆寫目前的設定檔。",
      "options": ["(Recommended) 是的，請執行", "取消操作"],
      "is_multi_select": false
    }
  ],
  "toolSummary": "使用者確認",
  "toolAction": "詢問使用者確認"
}

結果預覽

? 你確定要執行這個操作嗎？這將會覆寫目前的設定檔。

Question
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Question 1/1: 你確定要執行這個操作嗎？這將會覆寫目前的設定檔。

> 1. (Recommended) 是的，請執行
  2. 取消操作
  3. Write-in...

  ↑/↓ Navigate · enter Select · esc Skip

如果有強烈建議的選項，可以將其放在陣列第一位，並在前方加上 (Recommended)，系統的 UI 會特別標示。

2. 多選格式（核取方塊）

適用於有多個選項，且允許使用者同時選擇多項的情況（例如選擇要安裝的多個套件）。

Json 樣式

{
  "questions": [
    {
      "question": "請選擇你要加入專案的套件：",
      "options": ["React", "Vue", "Tailwind CSS", "TypeScript"],
      "is_multi_select": true
    }
  ],
  "toolSummary": "套件選擇",
  "toolAction": "詢問使用者套件"
}

結果預覽

? 請選擇你要加入專案的套件：

Question
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Question 1/1: 請選擇你要加入專案的套件：

> 1. [ ] React
  2. [ ] Vue
  3. [ ] Tailwind CSS
  4. [ ] TypeScript
  5. Write-in...

  ↑/↓ Navigate · x Toggle · enter Submit · esc Skip

當 is_multi_select 設為 true 時，介面會呈現為 Checkbox，使用者可以勾選零到多個項目後送出。不需要在問題中手動註明「請選擇所有適用項」，UI 介面會自動提示使用者。

3. 對話框 / 文字輸入格式

適用於需要使用者自行輸入文字（如專案名稱、自訂路徑）的情境。

ask_question 彈出的互動視窗，系統預設一定會提供一個「其他 (自行輸入)」(Write-in) 的文字輸入框，讓使用者除了點擊選項外，也能直接打字。

Json 樣式

{
  "questions": [
    {
      "question": "請選擇或輸入你要建立的資料夾名稱：",
      "options": ["src", "app", "lib"],
      "is_multi_select": false
    }
  ],
  "toolSummary": "輸入資料夾名稱",
  "toolAction": "詢問資料夾名稱"
}

結果預覽

? 請選擇或輸入你要建立的資料夾名稱：

Question
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Question 1/1: 請選擇或輸入你要建立的資料夾名稱：

> 1. src
  2. app
  3. lib
  4. Write-in...

  ↑/↓ Navigate · enter Select · esc Skip

? 請選擇或輸入你要建立的資料夾名稱：

Question
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Question 1/1: 請選擇或輸入你要建立的資料夾名稱：

  1. src
  2. app
  3. lib
> 4. Write-in...

  Your answer:


  enter Submit · esc Back

系統預設就會產生文字輸入框，請不要在 options 裡面自己加入一個叫做「其他 (Other)」的選項，否則介面上會出現兩個重複的選項。

如果你純粹只需要使用者輸入一段文字，且沒有任何預設選項可以提供，其實完全不需要呼叫此工具。只要在一般的聊天回應中用文字提問，讓使用者直接在聊天視窗回覆即可。

4. 綜合實戰範例（連續表單）

你可以將多個問題放在同一個 questions 陣列中，Agy CLI 會在同一個互動環節中一次處理完畢。這對於需要連續收集多項設定時非常方便，正如你實際體驗到的那樣。

Json 樣式

{
  "questions": [
    {
      "question": "你確定要執行這個操作嗎？這將會覆寫目前的設定檔。",
      "options": ["(Recommended) 是的，請執行", "取消操作"],
      "is_multi_select": false
    },
    {
      "question": "請選擇你要加入專案的套件：",
      "options": ["React", "Vue", "Tailwind CSS", "TypeScript"],
      "is_multi_select": true
    },
    {
      "question": "請選擇或輸入你要建立的資料夾名稱：",
      "options": ["src", "app", "lib"],
      "is_multi_select": false
    }
  ],
  "toolSummary": "初始化專案設定",
  "toolAction": "詢問初始化設定"
}

結果預覽

? 你確定要執行這個操作嗎？這將會覆寫目前的設定檔。
? 請選擇你要加入專案的套件：
? 請選擇或輸入你要建立的資料夾名稱：

Question
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Question 1/3: 你確定要執行這個操作嗎？這將會覆寫目前的設定檔。

> 1. (Recommended) 是的，請執行
  2. 取消操作
  3. Write-in...

  ↑/↓ Navigate · enter Select · esc Skip

完整參數說明表

欄位名稱	型別	必填	說明
questions	Array	是	要詢問的問題物件陣列。可一次詢問多題。
questions[].question	String	是	問題的標題或內容。（如果需要指定檔案，建議使用 GitHub markdown 連結格式）
questions[].options	Array	是	提供給使用者的選項陣列。至少需要 2 個選項。
questions[].is_multi_select	Boolean	否	如果為 true，使用者可以選擇多個選項。預設為 false（單選）。
toolSummary	String	是	用於顯示在 CLI 狀態列的摘要（2-5 個字的名詞片語）。
toolAction	String	是	正在執行的動作簡述（2-5 個字，像句子的開頭）。