Google Forms 問卷自動生成系統

從 JSON/YAML 檔案自動生成 Google Forms 問卷的 Python 命令列工具。

核心功能

• 從 JSON/YAML 自動建立 Google Forms
• 更新現有表單內容
• 下載現有表單為 YAML/JSON 格式
• 支援 11 種問題類型（單選、多選、簡答、段落、量表、下拉、日期、時間、網格、文字說明、圖片）
• 條件邏輯（根據回答顯示不同區段）
• 完整的資料驗證和錯誤處理
• 簡單易用的命令列介面

快速開始

1. 安裝 uv

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. 安裝依賴

cd dance-survey-generator
uv sync

3. 設定 Google API 認證

1. 前往 Google Cloud Console
2. 建立新專案並啟用「Google Forms API」
3. 設定「OAuth 同意畫面」（選擇「外部」，新增測試使用者）
4. 建立「OAuth 客戶端 ID」（選擇「電腦版應用程式」）
5. 下載 JSON 檔案，重新命名為 credentials.json，放到 config/ 目錄

4. 建立表單

uv run python -m src.cli --input data/demo_survey.yaml

首次執行會開啟瀏覽器進行授權。

基本使用

建立新表單

# 驗證問卷資料
uv run python -m src.cli --input data/demo_survey.yaml --validate-only

# 建立表單
uv run python -m src.cli --input data/demo_survey.yaml

# 儲存表單 URL
uv run python -m src.cli --input data/demo_survey.yaml --output form_url.txt

更新現有表單

# 更新表單內容（需要表單 ID）
uv run python -m src.cli --update FORM_ID --input data/updated_survey.yaml

# 更新並儲存 URL
uv run python -m src.cli --update FORM_ID --input data/updated_survey.yaml --output form_url.txt

下載現有表單

# 下載表單為 YAML 格式
uv run python -m src.cli --download FORM_ID --output downloaded_survey.yaml

# 下載表單為 JSON 格式
uv run python -m src.cli --download FORM_ID --output downloaded_survey.json --format json

# 輸出到終端機（不儲存檔案）
uv run python -m src.cli --download FORM_ID

完整工作流程：下載 → 編輯 → 更新

# 1. 下載現有表單
uv run python -m src.cli --download FORM_ID --output my_survey.yaml

# 2. 編輯 my_survey.yaml（使用任何文字編輯器）

# 3. 驗證修改後的資料
uv run python -m src.cli --input my_survey.yaml --validate-only

# 4. 更新表單
uv run python -m src.cli --update FORM_ID --input my_survey.yaml

取得表單 ID

表單 ID 可以從表單 URL 中取得：

https://docs.google.com/forms/d/FORM_ID/edit
                                 ^^^^^^^^
                                 這就是表單 ID

或者在建立表單時，系統會顯示表單 ID。

問卷資料格式

以下是 demo_survey.yaml 的範例：

title: "咖啡愛好者調查問卷"
description: "歡迎參加咖啡愛好者調查！我們想了解您的咖啡偏好和習慣。"

sections:
  - id: "welcome"
    title: "歡迎"
    questions:
      - id: "welcome_banner"
        text: "咖啡愛好者調查"
        type: "image_item"
        image_url: "https://images.unsplash.com/photo-1495474472287-4d71bcdd2085?w=800"
        image_width: 800
        image_alignment: "CENTER"
      
      - id: "intro_text"
        text: "感謝您參與本次調查！"
        type: "text_item"

  - id: "basic_info"
    title: "基本資料"
    questions:
      - id: "name"
        text: "您的暱稱或姓名"
        type: "short_answer"
        required: true
      
      - id: "coffee_drinker"
        text: "您喝咖啡嗎？"
        type: "multiple_choice"
        required: true
        choices:
          - value: "是，我是咖啡愛好者"
            goto_section: "coffee_habits"
          - value: "不喝咖啡"
            goto_section: "non_drinker"

支援的問題類型：multiple_choice、checkbox、short_answer、paragraph、linear_scale、dropdown、date、time、grid、text_item、image_item

完整範例請參考 data/demo_survey.yaml

查看表單回應

表單建立後，前往 https://docs.google.com/forms/ 查看回應統計。

詳細說明請參考 USAGE.md

文件

• USAGE.md - 詳細使用指南（給人類）
• AGENTS.md - 技術架構文件（給 AI）

範例檔案

• data/demo_survey.yaml - 簡單的示範問卷
• data/demo_survey.json - JSON 格式示範

常見問題

Q: 授權時顯示「此應用程式未經驗證」？
A: 這是正常的。點擊「進階」→「前往 [應用程式名稱]（不安全）」即可繼續。

Q: 顯示「Access blocked」錯誤？
A: 需要在 Google Cloud Console 的「OAuth 同意畫面」中將你的 Google 帳號加入「測試使用者」。

Q: 如何查看有多少人填寫表單？
A: 在 Google Forms 網頁介面的「回應」分頁可以看到統計資料。

Q: 更新表單時會保留原有的回應嗎？
A: 是的，更新表單只會修改問題內容，不會影響已收集的回應資料。

Q: 下載表單需要什麼權限？
A: 您需要對該表單有「檢視」或「編輯」權限。如果是別人分享給您的表單，請確認對方已授予您適當的權限。

Q: 可以下載別人的表單嗎？
A: 可以，只要對方將表單分享給您並授予檢視或編輯權限即可。

Q: 支援哪些輸出格式？
A: 支援 YAML 和 JSON 兩種格式，使用 --format 參數指定（預設為 YAML）。

更多問題請參考 USAGE.md

授權

本專案僅供學術研究使用。

---

注意: 本系統使用 Google Forms API，需要遵守 Google API 服務條款。