ADR 0003: 以 TOON 格式取代 JSON 的語境壓縮策略¶
Status¶
Accepted (2026-02-27)
Context (背景脈絡)¶
當系統需要將最近一個月甚至半年的 Google Calendar 事件與 Google Tasks 任務餵給 AI 進行分析時，傳統的作法是直接將 API 的回傳結果以 JSON 字串格式塞進 Prompt 中。 這帶來兩個嚴重的問題： 1. Context Window 暴漲：JSON 中大量重複性字詞 (如 "summary", "description", "start_time") 與嵌套括號佔據了近半的 Token。 2. 推理速度下降與成本增加：過長的前置 Context 會顯著拖慢大語言模型 (LLM) 的首字回應時間 (TTFT)，同時也直接推高了輸入成本。
根據 scripts/analyze_toon_compression.py 的精確分析，傳統 JSON 在處理大規模行程時會產生極高的無效負擔。
Decision (技術決策)¶
實作自定義的 Token-Oriented Object Notation (TOON) 格式，攔截所有傳向 MCP Host 的資料輸出並進行精簡編碼。
此格式核心機制包含： 1. Schema-less Header：標題行定義結構，消除欄位 Key 的重複出現。 2. 外部索引化 (Indexing)：地點、重複規則提取至外部索引表，內部使用 L1, R1 等短標籤參照。 3. 日期元件化 (Date Decompose)：將 ISO DateTime 分解為最小整數元件，如 st_d, st_wd, st_hm。 4. 語義分組 (Semantic Grouping)：按月份分組（Calendar）或按狀態/截止月份細分（Tasks），並建立父子任務樹 (Parent Tree)。
Consequences (決策結果)¶
Positive (優點)¶
- 極致壓縮率：實測 Token 壓縮率高達 83.7% (Chars 壓縮率 90.5%)。來源見 TOON_STATS_REPORT.md。
- 資訊密度大幅提升：同樣的 Context Window 下，AI 能夠處理約 6.1 倍 的行程資料。
- 人類可讀性保良好：層次化的 YAML 式縮排讓開發者在 Debug 時仍能快速追蹤資料分布，優於扁平的壓縮格式。
- 減少注意力渙散：模型專注於資料本身而非冗餘的
{}與引號，提高了排程生成準確率。
Negative (缺點)¶
- 維護成本：每次擴增新的資料結構（例如引入新的集成來源時），都必須維護對應的 Encoder 邏輯。