為什麼需要服務帳號（Service Account）？
如果後端要自動讀取 Google Sheets，不適合依賴個人手動登入。比較穩定的方式，是建立 Google 服務帳號，讓後端以一個機器身分存取指定試算表。 建立服務帳號後，你會取得一組憑證。接著需要啟用對應的 Google API，並把測試試算表分享給服務帳號的電子郵件地址。這一步很容易漏掉：即使憑證本身有效，如果試算表沒有授權給這個帳號，後端仍然讀不到資料。 具體流程大致是：先在 Google Cloud Console 選擇或建立一個 Project，到 API Library 啟用 Google Sheets API（若程式需要依檔名列出試算表，再視需要啟用 Google Drive API）；接著到 IAM 建立一個容易辨識用途的 Service Account，例如data-machi-sheets-reader，第一版只需要讀取指定試算表，不必給它專案管理者權限。建立完成後，在 Keys 頁籤新增一組 JSON Key 並妥善下載保存，再複製這個 Service Account 的 Email，回到匿名測試試算表把這個 Email 加進分享名單，權限先設為 Viewer 即可。
憑證和 Gemini API 金鑰一樣，不應直接提交到 GitHub。本機可以把 JSON 暫放在 backend/ 並加入 .gitignore；更適合正式環境的做法，是把整份 JSON 內容存成一個環境變數：
先用匿名資料驗證，不要直接碰正式資料
最適合的第一個測試，是建立一張結構清楚、內容可公開的匿名試算表。例如需求工單資料可以有日期、市場、類別、狀態與處理天數等欄位，內容可以簡單到像下面這樣：
你應該先確認程式能正確讀到欄位名稱與列數，再開始加入自然語言查詢。
這裡同樣延續前面的原則：一次只驗證一層。 先驗證 Google 權限，再驗證資料讀取，接著才驗證篩選與統計。不要一開始就把大型語言模型（LLM）、工具分流與資料權限全部混在一起除錯。如果權限沒設好，通常會遇到
SpreadsheetNotFound（Sheet ID 錯誤或尚未分享）或 Permission Denied（已分享但權限不足）；這代表身分驗證成功、但資源授權不足，回頭確認分享名單即可。
不要讓大型語言模型自己做精確計算
假設使用者問：「今年哪一個市場的工單最多？」比較可靠的流程不是把所有資料列丟給模型請它自己算，而是先把自然語言需求轉成程式可以理解的條件，再由 Pandas 或其他資料處理程式執行篩選、分組與彙總。 模型可以理解「今年」、「市場」、「最多」代表什麼，但真正的計數、加總、平均、排序與比例，應該由可驗證的程式邏輯完成。這個分工是企業分析型代理（Agent）很重要的設計原則。欄位別名：讓使用者不需要知道資料結構
真實資料欄位常常不是人類會使用的語言。例如資料庫裡可能叫request_market、created_at、ticket_category，使用者卻只會問「市場」、「今年」、「需求類別」。因此工具層通常需要一張欄位別名對照（Alias Mapping），將業務語言映射到真實資料結構（Schema）。
這一層做得好，模型不需要猜欄位；資料欄位未來改名時，也不必重寫整個提示詞。對使用者來說，他仍然可以用平常工作的語言發問。
快取不是為了偷懶，而是控制成本與延遲
Google Sheets 不需要每一次對話都完整重新讀取。對更新頻率沒有那麼高的資料，可以設計短時間快取（Cache），降低 API 呼叫與等待時間。不過快取也代表資料可能不是即時，因此快取時間應該根據業務需求決定，而不是一律愈長愈好。 如果使用者問的是「目前最新狀態」，系統也應該有能力選擇重新抓取，而不是盲目沿用舊結果。這個問題之後會在代理記憶與協調者設計中再處理一次。今天要怎麼驗證資料工具真的成功？
至少要測三種問題。第一種是簡單查詢，例如「共有多少筆資料」；第二種是篩選與彙總，例如「今年台灣有多少工單」；第三種是組合條件，例如「今年台灣哪一類工單最多」。 每一次都應該把資料工具的計算結果和試算表人工核對，而不是只看模型最後講得通不通順。可以直接把匿名 Sheet 的原始資料、你問的問題與系統回答放在同一個畫面比對，確認筆數、金額或狀態統計都能被人工重算。當這三層都正確，Data Machi 才真正擁有第一個可驗證的結構化資料工具。實務踩坑｜最新資料、日期與不存在的欄位
實務上有三個很重要的提醒。第一，快取雖然能加快速度，但回答最好保留資料取得時間，讓使用者知道數字是不是最新；如果使用者明確說「我剛更新資料」或「請重新確認」，就應跳過快取重新查詢。第二，「上個月」「最近三個月」「Q1」這些時間語言最好由程式轉成明確日期範圍，而不是讓模型每次自由解讀。第三，如果資料表根本沒有某個欄位，資料工具就應直接回報不存在，而不是自行找一個「看起來很像」的欄位替代。 這三件事都指向同一個原則：模型可以幫忙理解使用者在問什麼，但事實條件最好被轉成可以驗證的程式規則。今天的里程碑是：模型不再負責「猜數字」，而是知道什麼時候把數據問題交給程式計算。