Imported from Wujidadi/custom-gmail-sender (AGENTS.md). Install upstream with npx skills add Wujidadi/custom-gmail-sender. Copyright stays with the author.

AGENTS.md

給 AI agent 的開發指引。 安裝、設定與使用方式見 README.md，此處只寫維護程式碼時需要知道、但 README 與程式本身看不出來的事。

架構約束

• 全部邏輯集中在單一腳本 gmail_send.py，勿拆分成套件；相依套件清單在 requirements.txt，虛擬環境固定位於專案根目錄的 .venv
• 腳本開頭有「自我引導」區塊：在載入任何第三方套件之前，以 importlib.util.find_spec 偵測相依套件是否齊全； 缺套件時自動建立 .venv（不存在才建）、安裝 requirements.txt，再以 .venv 直譯器重跑自身， 並以環境變數 GMAIL_SEND_BOOTSTRAPPED 防止安裝不完整時無窮重跑；套件齊全的直譯器（如 conda 環境）直接沿用
  • 因此第三方 import（css_inline、markdown、google.*）必須保持在引導區塊之後，標準庫 import 在其之前；調整 import 順序時不可破壞此結構
  • KeyboardInterrupt 在引導的 subprocess.call 與 main() 進入點各攔一次：Ctrl+C 訊號會同時打進外層直譯器與子行程，訊息由子行程印出，外層僅回傳 130
• OAuth scope 除 gmail.send 外還帶 openid 與 userinfo.email，用途是從 id_token 解出登入帳號寫入 profile.json，供 From 標頭組合寄件位址——gmail.send 權限不足以呼叫 getProfile，勿改用該 API
• 授權時攔截 oauthlib 的 Scope has changed Warning：使用者在 Google 同意畫面漏勾寄信權限（部分同意）時會發生，須維持友善的單行錯誤訊息

Gmail API 行為（外部約束）

• Gmail 會強制將 From 的信箱位址改寫為登入帳號或已驗證別名，僅顯示名稱照 MIME 標頭使用；--from-name 的功能依賴此行為
• GCP 端的 OAuth 應用程式已發布為正式版（未驗證）；PRIVACY.md 與 TERMS.md 是 Google Auth Platform「品牌」頁面所填連結的目標檔案，修改或改名前須同步考慮該設定

驗證方式

• 語法檢查：.venv/bin/python -m py_compile gmail_send.py
• 功能驗證一律用 --dry-run（輸出信件摘要並產生 preview.html），勿實際寄信
• 無測試框架，也不要引入

機密檔案

credentials.json、token.json、profile.json 為 OAuth 機密，已列入 .gitignore： 不可讀取其內容、不可輸出到對話或日誌、不可提交