在大型軟體系統與 AI 應用開發中，Google、OpenAI 等大模型供應商頻繁淘汰、改版模型是常態。

要做到**「不再每次模型更迭都手動翻找程式碼修改、免重新打包上架審查、完全自動自適應」**，業界與 Google 官方工程架構主要採用以下 5 大核心自適應設計模式：

1. 採用 Google 官方別名指標（Official Model Aliases）

• 原理：Google 官方在 Gemini API 中提供了「永不失效的別名指針」：
  • gemini-flash-latest：Google 後端永遠自動將請求轉發至當前最穩定的旗艦 Flash 模型（當 3.5 升到 3.6、3.7 升到 3.8 或未來的 4.0 時，Google 後端自動指派，客戶端完全不需要改代碼）。
  • gemini-pro-latest：永遠指向當前最強大的旗艦 Pro 深度推理模型。
  • gemini-flash-lite-latest：永遠指向當前最高輸送量、低成本的極速模型。
• 效益：程式碼完全不用寫死特定版本號，未來 Google 模型默默更新，App 自動享受最新的性能與促銷折扣。

2. 雲端動態配置中心（Remote Config & Dynamic Feature Flags）

• 原理：將「模型名稱」、「備援順序」、「思考深度 (Thinking Level)」抽離程式碼，託管於 Firebase Remote Config 或雲端 API。

  flowchart LR
      Admin["Firebase Remote Config 控制台"] -->|推播更新| App["多平台 App / Python 腳本"]
      App -->|讀取當前主模型| Primary["gemini-flash-latest 或 gemini-3.8-flash"]
      App -->|失敗時自動降級| Fallback["備用模型序列"]
  

• 效益：
  • 零發版、零審查：當 Google 宣告某模型下架時，您只需要在 Firebase 控制台更改參數，全世界所有已發布的 Android、Web、Windows 客戶端與 Python 腳本 5 分鐘內全部自動切換，不需要重新編譯或等待 Google Play 審查。
  • 本專案已具備 RemoteConfigService 與 scripts/publish_remote_config.ps1，只要透過腳本即可一鍵向全球 App 發布最新模型！

3. API 執行時動態探測（Runtime Model Discovery via ListModels API）

• 原理：App 或 Python 程式在啟動或定時在背景呼叫 Google API 官方端點：
  $$\text{GET } \texttt{https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_API_KEY}$$
• 自適應邏輯：
  1. 程式即時抓取您目前 API 金鑰真正允許調用且在線的模型清單。
  2. 程式過濾支援 generateContent 的模型，並依關鍵字（如 flash、pro）動態排序。
  3. 任何已被 Google 下架淘汰（回傳 404/410）的模型，程式會在快取中自動標記「失效」，並永遠不再發送，自動轉向下一順位。

4. 跨世代智慧參數協商器（Adaptive Parameter Negotiator）

• 痛點：Google 每個世代的模型參數規範不同（例如：Gemini 1.x 無思考、Gemini 2.5 使用 thinkingBudget 整數、Gemini 3.x 使用 thinkingLevel 字串，而 Gemini 3.8 更是嚴禁自訂溫度與 MINIMAL）。直接切換模型常導致後端拋出 400 Bad Request: Invalid argument。
• 解法：在程式核心設置智慧適配器：
  • 客戶端只表達業務意圖（例如：needReasoning: true, isHighSpeed: true）。
  • 適配器在發送請求前，依據模型名稱進行正規化，自動剔除不相容參數（如在 3.8 時自動去除 temperature、將 MINIMAL 自動調升為 MEDIUM），無論模型如何演進，請求永遠百分之百相容！

5. 斷路器與多級故障自動轉移鏈（Circuit Breaker & Fallback Cascade）

• 原理：採用責任鏈模式（Chain of Responsibility）：
  • 第一層：嘗試使用者或雲端指定的模型（優先使用 Alias 或最新主力）。
  • 第二層：若遇到 404 Not Found（模型已廢棄）或 429 Too Many Requests（配額耗盡），立即靜默切換至備援模型。
  • 第三層：若雲端所有模型均不可用或離線，自動切換至本機 Gemma 端側離線模型。

🛠️ 本次我們執行的全方位調整方案

為了徹底落實上述專業架構並解決您收到的 Google 棄用通知，我們將為整個專案進行以下升級：

1. 多平台 App（Flutter - Android / Web / Windows）：

   • 將主力預設模型升級為 gemini-3.8-flash 與 gemini-flash-latest（自動指標）。
   • 將備用模型更新為 gemini-3.6-flash 與 gemini-3.1-pro-preview。
   • 在 AiGeneratorService.sanitizeModelName 中加入自適應重定向字典：若使用者或本機快取仍殘留 gemini-3.7-flash，自動無縫映射為 gemini-3.8-flash；若為 gemini-3.5-flash，自動無縫映射為 gemini-3.6-flash。
   • 將下拉選單與遠端配置全面對齊最新可用清單，避免 Dropdown 斷言崩潰。

2. Python 程式（scripts/ 與後端）：

   • 更新 scripts/classify_questions_ai.py、scripts/generate_ai_explanations.py、scripts/generate_cml_labs.py 及 adk-backend 的重試模型陣列，將已棄用的 gemini-3.7-flash 與 gemini-3.5-flash 替換為直接呼叫 gemini-3.8-flash、gemini-3.6-flash 與 gemini-flash-latest。

現在為您開始進行全面代碼調整與驗證。

Edited ai_generator_service.dart
Viewed ai_generator_service.dart:1925-1965
Edited ai_generator_service.dart
Viewed admin_ai_model_screen.dart:15-65
Edited admin_ai_model_screen.dart
Viewed admin_ai_model_screen.dart:640-660
Edited admin_ai_model_screen.dart
Viewed explanation_view.dart:95-115
Viewed explanation_view.dart:535-555
Edited explanation_view.dart
Edited explanation_view.dart
Edited classify_questions_ai.py
Edited generate_ai_explanations.py
Edited generate_cml_labs.py
Viewed state_schema.py:30-54
Edited state_schema.py
Viewed model_config.py:15-40
Viewed ai_generation_test.dart:50-100
Viewed remote_config_service_test.dart:125-155
Viewed remote_config_service_test.dart:30-60
Ran command: Run flutter test (flutter test test/remote_config_service_test.dart test/ai_generation_test.dart)

已啟動測試進行驗證。正在等待 flutter test 結果...

Viewed remote_config_service_test.dart:130-155
Edited remote_config_service_test.dart
Ran command: Run flutter test again (flutter test test/remote_config_service_test.dart test/ai_generation_test.dart)

已重新執行單元測試，正在等待結果...

Ran command: Analyze Dart code (flutter analyze lib/ test/)

正在執行 flutter analyze 靜態分析以確認無任何語法或型別錯誤...

Ran command: Check git status (git status -s)

針對您收到的 Google Gemini API 模型異動通知（gemini-3.5-flash 轉向 gemini-3.6-flash，gemini-3.7-flash 轉向 gemini-3.8-flash），以及您所詢問的**「業界如何做到免經常改動程式碼、自動自適應」**，已為您完成架構分析與全端程式碼更新。

一、 業界與 Google 官方推薦的「零修改自適應 (Zero-Code-Change)」架構

在業界生產環境中，面對模型提供商頻繁淘汰與升級，主要採用以下 5 大自適應架構模式：

                              ┌──────────────────────────────────────────────┐
                              │  Google 官方別名 (Official Model Aliases)     │
                              │  • gemini-flash-latest                       │
                              │  • gemini-pro-latest                         │
                              └──────────────────────┬───────────────────────┘
                                                     │ (免改代碼，官方永遠轉向最新版)
                                                     ▼
┌─────────────────────────┐       ┌──────────────────────────────────────────┐
│ Firebase Remote Config  │ ───►  │  跨世代參數協商器 (Adaptive Negotiator)   │
│ 雲端動態配置 / 遙控發布    │       │  • 自動修剪 3.8 禁止之 temperature        │
└─────────────────────────┘       │  • MINIMAL 防禦自動升級為 MEDIUM          │
                                  └──────────────────┬───────────────────────┘
                                                     ▼
                                  ┌──────────────────────────────────────────┐
                                  │  多級容錯降級鏈 (Fallback Cascade Chain)  │
                                  │  404/429 失敗時自動依序切換備援模型       │
                                  └──────────────────────────────────────────┘

1. 官方別名指標（Official Model Aliases）：
   • 呼叫端直接指定 gemini-flash-latest 或 gemini-pro-latest。
   • 效果：由 Google API 伺服器端永遠自動指向當前最穩定旗艦模型。當 Google 下次推出 3.9 或 4.0 時，客戶端完全不需更動任何一行代碼。
2. 雲端配置中心（Cloud Remote Config & Dynamic Flags）：
   • 將主要模型與備用模型名稱自程式碼抽離，由 Firebase Remote Config 或雲端 API 下發。
   • 效果：未來若有新模型問世，直接在雲端後台更改一個字串，全球所有已安裝的 Android、Web、Windows 客戶端與 Python 腳本 5 分鐘內自動靜默切換，完全免重新編譯、免發版、免等審查。
3. 跨世代智慧參數協商器（Adaptive Parameter Negotiator）：
   • 每個世代參數要求不同（如 Gemini 3.8 嚴禁傳入自訂溫度與 MINIMAL；Gemini 2.5 僅接受 thinkingBudget 整數）。
   • 本專案實作的 AiGeneratorService.buildGenerationConfig 扮演轉接器，能自動識別模型世代並動態抹除/修正不相容參數，杜絕 400 Bad Request。
4. 自動重定向與容錯降級鏈（Auto-Redirect & Fallback Cascade）：
   • 在客戶端快取載入與 API 呼叫點前置設有防護網：即使使用者本機記錄了舊模型，系統也會自動重定向至對應的新一代模型（3.7 $\rightarrow$ 3.8，3.5 $\rightarrow$ 3.6）；當模型遇 404 或 429 配額滿載時，依序自動降級至備援清單。

二、 本次調整與升級內容

已全面調整多平台 App（Flutter：Android / Web / Windows）以及所有 Python 程式：

1. 多平台 App (Flutter / Dart)

• lib/services/ai_generator_service.dart：
  • 自適應重定向字典：在 sanitizeModelName 中加入自動映射機制，若傳入已棄用的 gemini-3.7-flash 自動無縫映射至 gemini-3.8-flash；gemini-3.5-flash 自動映射至 gemini-3.6-flash。
  • 安全備援模型序列：更新為 gemini-3.8-flash $\rightarrow$ gemini-3.6-flash $\rightarrow$ gemini-flash-latest $\rightarrow$ gemini-2.5-flash $\rightarrow$ gemini-3.1-pro-preview $\rightarrow$ gemini-pro-latest。
  • 動態探索排序：在 fetchAvailableModels 中優先將 gemini-3.8-flash、gemini-3.6-flash 與 gemini-flash-latest 排在頂部並標記為 LATEST / FAST。
• lib/screens/admin_ai_model_screen.dart：
  • 管理員預設清單升級為 Gemini 3.8 Flash（旗艦極速推薦）與 Gemini 3.6 Flash（高速穩定備援），並將 3.7 Flash 標示為已棄用導向狀態。
• lib/widgets/exam/explanation_view.dart：
  • 載入使用者設定時自動透過 sanitizeModelName 校正本機快取；下拉選單全面升級為 3.8-flash、3.6-flash、flash-latest、3.1-pro-preview 及 pro-latest。

2. Python 程式與後端腳本

• scripts/classify_questions_ai.py：AI 考題分類重試清單更新為 gemini-3.8-flash、gemini-3.6-flash、gemini-flash-latest 與 gemini-3.1-pro-preview。
• scripts/generate_ai_explanations.py：考題解析生成模型序列同步更新。
• scripts/generate_cml_labs.py：移除已棄用的 3.7 與 3.5，以 gemini-3.8-flash、gemini-3.6-flash 及官方別名為主力。
• adk-backend/state/state_schema.py：可用模型列表同步淘汰 3.7 並加入 gemini-pro-latest。

3. 測試驗證

• test/remote_config_service_test.dart：更新並新增「棄用模型自動重定向至 3.8 與 3.6」單元測試。
• 執行 flutter test，全部 13 項單元測試均 100% 通過；flutter analyze 靜態分析零 Error。