Day 03：工程架構設計：資訊流向、狀態機與非同步解耦

許多初學者在開發 AI 自動化系統時，常急著寫 Prompt 或串接 API，最後卻做出一個脆弱的系統：前端網頁抓取稍微延遲，後端程式就跟著逾時崩潰；或是模型遇到 Rate Limit 當掉時，整批資料直接憑空消失。

要打造可長期維運的「情報決策雷達」，第一步不是敲程式碼，而是定好資料契約（Data Contract）與狀態機（State Machine）。

為什麼「非同步解耦」是長期運作的關鍵？

在我們的預設架構中，前端主要由 Gemini Spark（或後續擴充的 Colab / 爬蟲腳本）負責高頻巡邏，後端則由 Google ADK 多代理人叢集 進行深度推演。這兩者的運作節奏完全不同：

• 收集端 是隨機、零碎且高頻的，它可能在任何時間點抓到新論文或財經數據。
• 推演端 則是批次、吃 Token 且耗時的，需要呼叫多個 Agent 交叉辯駁與回寫報告。

如果讓兩者同步硬連線（Synchronous），只要一端卡住，整條管線就會癱瘓。因此，我們使用 Google Sheets 作為非同步訊息佇列（Message Queue）與暫存資料庫：收集端只管把資料往裡塞，推演端則照自己的節奏批次撈取處理，達成時間與空間上的完全解耦。

情報項目的生命週期：4 節點狀態機

為了避免重複推演或資料遺失，每一筆進入系統的情報都必須遵循嚴格的狀態流轉：

[ 收集端寫入 ] ──> PENDING (待處理)
                      │
                      ▼ (ADK 鎖定任務)
                  ANALYZING (分析審核中)
                      │
        ┌─────────────┴─────────────┐
 (評分 >= 4分)                (評分 < 4分)
        ▼                           ▼
PROCESSED (已建檔/納入週報)   ARCHIVED (雜訊封存)

1. PENDING：收集端剛寫入，等待處理。
2. ANALYZING：ADK 撈取該筆資料並立即將其改為此狀態（作為分散式鎖，避免同時被多個 Worker 重複執行）。
3. PROCESSED：經審查員 Agent 核可，具備重大價值，寫入 Google Docs 週報排版區。
4. ARCHIVED：日常微幅波動或邊際創新，僅歸檔留存，不浪費篇幅打擾使用者。

資料契約：核心定死，彈性留活

為了讓前端未來能隨時抽換或擴充（例如未來加入 arXiv API 爬蟲），我們將 Google Sheets 的 Schema 拆分為兩大層次：

把插座的規格（Schema 與狀態機）焊牢後，未來不論你想插上 Spark、Colab 還是自建爬蟲的插頭，系統都能隨插即用。

明天（Day 04），我們將正式進入實作準備：配置 Google Cloud 專案權限、取得 Gemini API Key，並在本機建立乾淨的 Python 開發環境！