ynab-api

YNAB API 管理技能為與 You Need A Budget (YNAB) 資料互動提供強大的命令列介面。此技能專為希望超越手動輸入的用戶設計，利用 curl 和 jq 從終端機或 AI 代理環境直接執行程式化預算操作。對於個人理財愛好者、需要跨多個帳戶追蹤支出的進階使用者，以及任何希望將自動化財務摘要整合到日常工作流程中的人來說，這是理想的工具。無論您是需要記錄交易、分析每月支出模式，還是監控資金齡 (Age of Money)，此工具都能提供維護財務健康的結構化方式。

• 自動化報告功能，包括每日支出摘要、每月預算進度及月份間支出比較。

• 交易管理能力：建立交易、處理分割類別 (split categories)，並執行收款人搜尋以保持類別一致性。

• 財務洞察：監控類別目標進度、追蹤即將到期的帳單，並接收超支或預算不足的警報。

• 智慧轉帳處理：利用 transfer_payee_id 確保帳戶間的資金移動在 YNAB 分類帳中被正確分類與連結。

• 智慧錯誤處理：針對 401 和 429 API 錯誤提供自動重試機制，防止常見的頻率限制問題中斷用戶體驗。

• 設定需求：需要 YNAB_API_KEY 與 YNAB_BUDGET_ID，並支援透過環境變數或本地 config.json 設定每月預算目標。

• 資料精度：所有金額皆以 milliunits 處理 (例如 10.00 表示為 10000)；與 API 互動時請務必正確使用乘數與除數。

• 操作準則：在新增交易前，請務必先搜尋既有交易或收款人，以防止重複記錄並保持報告準確性。

• 效能優化：API 設有嚴格頻率限制 (每小時約 200 次請求)；針對大量資料應啟用快取並避免激進的輪詢。

• 語境感知：當解釋來自 daily-spending-report.sh 的原始指標時，代理將擔任財務分析師，將資料轉化為對用戶自然且具建設性的建議。