[HeiTang]

新增 Groq 語意解析供應商，固定使用 openai/gpt-oss-120b。使用者可在私聊透過 /ai add groq <Key> 新增個人 Key，沿用現有加密、排序、冷卻、最多三組 Key 備援與 18 秒共用等待預算；建立提醒仍須確認，Gemini 仍為預設供應商。

功能與修正

• 使用 strict JSON Schema，遞迴補上 additionalProperties: false，保留共用 schema 的 nullable 型別。
• HTTP／連線錯誤轉成共用錯誤代碼；429 依結構化 headers 分類並使用 Retry-After，不保存上游錯誤原文。
• 捕捉截斷 chunked 回應的 HTTPException，讓連線中斷仍進入冷卻與備援流程。
• 明確設定 User-Agent: Remindly。真實 Key 實測發現預設 Python urllib 遭 Cloudflare 以 HTTP 403／1010 擋下；明確設定 User-Agent 後成功。
• 修正共用 explicit_time() 的週期日期約束：只有時鐘時使用既有 next_fire() 計算首次觸發，明確起始日期仍保留。以 2026/10/30 12:00 Asia/Taipei 為基準，每週一、三、五早上九點的首次日期為 11/2（一），不再覆寫成 10/31（六）。
• Groq metadata 沒有可讀模型名稱，確認卡沿用「使用 AI 解析」，解析紀錄保存供應商與模型 ID。
• 無新增依賴或資料庫 migration。

真實 API 評估工具與回歸資料

• scripts/groq_live_eval.py：透過正式 Groq adapter、中文 prompt 與 schema 呼叫 API，分別比對原始回應與經 SemanticParser 處理後的結果。比對事項、首次時間、缺漏欄位、完整性、對象與週期。
• tests/fixtures/groq_live_cases.jsonl：從既有回歸資料選出 36 個不同案例，每筆保留來源檔名／ID。8 個容易漂移的案例各跑 3 次，共 52 次語意測試。預期值沿用既有核對結果，不從模型輸出產生。
• tests/fixtures/groq_live_results_2026-10-30.jsonl：保存全部原始 JSON、兩層結果、差異、耗時及失敗事件。輸入為合成案例，無 Key 或上游錯誤內文。
• tests/test_groq_live_eval.py：離線重播全部 52 筆真實回應，並驗證資料來源、模型／本機分開計分、429 冷卻與續跑不重送已完成請求。
• 同一輸出路徑可續跑；案例、prompt、schema 或主要解析程式碼變更時拒絕混用舊結果。實測工具不經正式 Key store／Gateway，不接觸正式資料庫或 Telegram；CI 只執行離線回歸，不呼叫 API。
• 使用方式：uv run python scripts/groq_live_eval.py --output /tmp/groq-live-results.jsonl，從專案 .env 載入個人 GROQ_API_KEY。

2026-10-30 真實 Groq 實測結果

本輪在 User-Agent 與週期首次日期修正後執行。每筆使用資料集指定的固定時鐘與時區；涵蓋跨年／閏日、不同時區、無效及過去時間、多人提醒、五種週期、草稿補充／修正及必要追問。

指標	結果
不同案例／完成語意請求	36／52
模型原始結果符合預期	26/52（50%）
本機處理後符合預期	52/52（100%）
模型不符預期的不同案例	14/36
實際 API 請求	58：52 次取得回應、5 次 429、1 次 request 錯誤
成功請求耗時	平均 1.154 秒、中位數 1.109 秒、P95 1.820 秒；範圍 0.704–2.258 秒

5 次 429 均依 adapter 提供的 60 秒冷卻後續跑。一次供應商 request 錯誤使工具停止，保存進度後續跑成功，未重送已完成案例；未保存上游錯誤內文，無法判定該次錯誤根因。耗時包含 adapter 與本機解析，不含失敗請求或冷卻。

模型錯誤包含下下週一日期、未指定上午／下午的五點、過期月日跨年、早上十二點、事項中的「或」被誤當時間選項、事項被改寫及修正時遺失既有條件。本機守衛均修正或保留必要追問；模型被修正仍計為原始結果失敗。8 個重複案例中，2 個原始結果各 3/3 通過，另外 6 個各 0/3；本機均 3/3。

本機驗證

• 最新 make check 通過：Ruff、379 個 unit tests、smoke flow；其中含全部 52 筆真實回應的離線重播。
• 格式檢查、git diff --check 與暫存內容 Key 洩漏檢查通過；.env 未納入提交。
• 截斷 HTTP 回應與每週首次日期回歸均已確認修正前失敗、修正後通過；另覆蓋明確起始日期、User-Agent、備援剩餘預算及確認建立流程。

這批案例刻意集中既有錯誤與邊界，50%／100% 僅為本資料集的嚴格欄位比對，不能推估一般輸入準確率或正式環境可用率。尚未驗證正式 Telegram／部署環境；18 秒為既有等待預算，並非嚴格的整次執行期限。