核心問題：長任務不是缺大腦，是上下文太髒
本地 LLM 不太怕 代元 成本，但長時間 程式設計、Wiki 整理、YouTube 逐字稿、Excel 報表與 bot 紀錄 會把 上下文 window 塞滿。當 代理 看太多重複輸出，就會忘記真正要做的決策。
上下文視窗工具輸出長任務
1
課程大綱
Headroom 的定位：進模型前先整理輸入
官方文件說 Headroom 會處理 工具輸出、資料庫結果、檔案讀取結果、RAG 檢索結果、API 回應 等內容，再把較乾淨的 提示詞 送往 LLM provider。它可以用 代理伺服器、SDK、框架整合 或 MCP tools 方式接入。
代理層SDKMCP
最重要的判斷：不要直接裝進核心
Hermes 的核心仍應是 Obsidian/Wiki Agent、Codex 技能 sync、Summary Agent 與原始資料保存。Headroom 可以做輔助層，但不應成為唯一記憶、唯一證據或唯一知識來源。
治理記憶界線
先做自己的 Context Headroom 規則
在安裝工具前，先定義哪些內容可以壓縮、哪些內容必須保留原文、哪些場景要先寫 證據筆記。這比直接接 代理伺服器 更符合本地 代理 治理。
證據筆記原始資料封存審查關卡
最適合試用的地方：Wiki、Codex、art 逐字稿
YouTube 逐字稿、NotebookLM 輸出、build/test logs、RAG 片段 與重複工具輸出最適合先被壓成 課程摘要、證據筆記 或 交接摘要，再交給 代理 做下一步。
Wiki AgentCodex內容輸出 代理
安全邊界：原始資料不可消失
壓縮結果只是給 代理 看，不是正式知識庫。`.env`、代元、Cookie、精確 差異、正式財務法律醫療內容、客戶敏感資料都不應被任意壓縮或交給外部服務。
機密資料精確差異保留來源
2
整體關係圖：上下文清理器在核心外圍
原始來源
逐字稿、紀錄、Excel、email、RAG、工具輸出，原始資料完整保留。
上下文餘裕
先做壓縮、去重、摘要、異常保留與可回取索引，只給 代理 看乾淨輸入。
Agent 決策
Codex、Wiki Agent、內容輸出 代理 或 PM 工作流程 代理 依任務輸出教材、報告或交接。
閱讀方式：Headroom 類工具應放在「原始來源」與「代理決策」之間。它不取代 原始封存，也不直接改 Wiki 正式知識。
3
核心概念與名詞解釋
上下文最佳化層
模型看到資料前的整理層。
- 它的任務是降低輸入雜訊，不是永久儲存知識。
- 適合處理工具輸出、紀錄、資料庫資料列、RAG 片段、API 回應 與長 逐字稿。
- 對本地 LLM 的價值是穩定長任務，而不是單純省 代元 成本。
Michael AI Agent Lab 說法：把它當成進會議前的助理摘要，不是公司的正式文件庫。
SmartCrusher／內容路由
依資料型態選擇壓縮策略。
- 官方文件描述會辨識 JSON、程式碼、紀錄、文字、差異、HTML，再套用不同 轉換。
- JSON array、結構化紀錄、API rows 通常比短對話更值得壓縮。
- 壓縮時應保留 錯誤、異常、邊界 與代表性樣本。
Michael AI Agent Lab 說法：Excel issue list 應保留異常、風險與 負責人，不需要把每列重複欄位塞給 代理。
CCR：壓縮、快取、檢索
壓縮後仍可回取原文。
- 官方架構說被壓縮或丟棄的內容可存入 本機壓縮快取。
- 模型需要細節時，可透過 回取工具 取回原始內容或篩選結果。
- 這個設計很適合長 逐字稿 與 紀錄，但原始 raw 仍要由 Hermes 自己保存。
注意：CCR 不是長期知識庫。TTL、儲存位置、敏感資料策略都要先確認。
代理層、SDK、MCP 工具
三種接法，風險等級不同。
- 代理伺服器 會攔截 LLM 傳輸內容，導入最方便，但治理風險最高，不能先上核心。
- SDK 適合特定 處理管線，例如 Wiki raw 轉 證據筆記。
- MCP tools 適合讓 代理 按需壓縮與回取，較符合 隔離測試 測試。
Michael AI Agent Lab 說法：先用 MCP 或離線 腳本 做試驗，不要一開始改全部 provider 基底網址。
快取最佳化
讓 provider 前綴快取 更容易命中。
- 官方架構描述會把動態日期、UUID、session 代元 等移到後段，保留穩定 前綴。
- 對雲端 API 有成本與延遲價值，對本地 LLM 則不是首要收益。
- 對本地 代理 系統，穩定系統提示與乾淨交接比 快取 折扣更重要。
Michael AI Agent Lab 說法：本地 LLM 不需要為了 快取 折扣犧牲 提示詞 可讀性。
記憶界線
壓縮層不能跨過知識邊界。
- Wiki Agent 才能把知識變成正式長期內容。
- Summary Agent 才負責交接狀態與下次工作入口。
- Context Headroom 只產生 代理 可讀摘要、證據筆記 與風險清單。
禁止：不要讓壓縮器直接刪 raw、覆蓋 Wiki、改正式知識或吞掉精確 差異。
4
適用與不適用：先分清楚，不要迷信工具
最適合本地 AI 代理 系統的場景
| 代理 場景 | 適合壓縮的資料 | 輸出成什麼 |
|---|---|---|
| Codex／程式代理 | 終端機 output、build 紀錄、test 紀錄、長 shell output | 錯誤摘要、失敗原因、下一步、保留關鍵 堆疊追蹤 |
| Wiki Agent | YouTube 逐字稿、NotebookLM 原始筆記、長文章與重複整理稿 | 證據筆記、課程摘要、缺資料清單 |
| 內容輸出 代理 | 教學影片逐字稿、來源研究、HTML 修改紀錄 | 主題、章節、術語、可引用證據、審稿 檢查清單 |
| PM 工作流程代理 | Excel、email、critical issue report、客訴記錄 | 異常、風險、負責人、期限、下一步 |
| 每日維護報告 | 代理 status、紀錄、容量、模型、重複檔案清單 | 乾淨結論、紅黃綠狀態、需人工確認事項 |
不適合直接壓縮的內容
- `.env`、權杖、Cookie、工作階段、API 金鑰。
- 會被用來改程式的精確 差異、修補內容、SQL 遷移。
- 正式財務、法律、醫療與合規內容，除非保留精確來源與可回查證據。
- Wiki 正式知識，不應由壓縮器直接覆寫。
- 客戶敏感資料，尤其是會送到外部服務或 遙測 的流程。
治理原則：壓縮給 代理 看，原始資料仍留 raw。代理 需要引用、寄出或寫入 Wiki 時，必須回查原文。
5
建議導入階段：先規則，再 隔離測試，最後才接工具
階段 1
自建壓縮規則
先定義 Context Headroom 規則：哪些可摘要、哪些必須保留原文、哪些要進 證據筆記。
階段 2
強化交接摘要
讓 Summary Agent 與 交接摘要 固定輸出完成事項、決策、風險、下一步與原始資料路徑。
階段 3
Wiki raw 轉 Evidence
把 逐字稿、NotebookLM 與 原始筆記 先壓成 證據筆記，再由 Wiki Agent 審核吸收。
階段 4
Headroom 隔離環境
在非核心資料上測試 Headroom MCP 或 SDK，觀察壓縮率、漏失、回取能力與本機資源負載。
階段 5
穩定後再接入
若效果穩定，再只接 Wiki、Codex 紀錄、art 逐字稿 幾個管線，不接 機密 與正式知識寫入。
本教材結論
Headroom 值得吸收，但不要直接裝進核心。它是上下文清理器，不是大腦。本地 AI 代理 系統的核心仍是 Wiki、技能 sync、Summary Agent 與 原始封存。
先做的實作規則
- 所有壓縮摘要都要附 raw path 或來源 URL。
- 寄出、寫 Wiki、改 程式碼 前要回查原文。
- 工具輸出 超過一定長度才壓縮，短內容不要多此一舉。
- 保留 錯誤、警告、負責人、期限、決策、未解問題。
6
資料來源與可信度標註
官方文件：簡介
說明 Headroom 是 LLM applications 的 上下文 optimization layer，會在模型看到前壓縮工具輸出、資料庫結果、檔案讀取結果、RAG 檢索結果 與 API 回應。文件列出 代理伺服器、Python/TypeScript SDK、框架整合 與 MCP 等使用方式。
官方文件：架構
描述三階段 處理管線：分析訊息、套用 轉換、呼叫 provider。也說明 代理伺服器、SDK、整合 的接入差異，以及 CCR 可把被壓縮內容存入本地 快取 後回取。
官方文件：MCP Tools
說明 MCP server 暴露 headroom_compress、headroom_retrieve、headroom_stats，可供 Claude Code、Cursor、Codex 與 MCP-compatible host 使用。這是比較適合 隔離測試 驗證的方向。
官方文件：限制
列出哪些內容有效、哪些內容幫助有限。文件特別提到短對話、純程式工作階段、單回合請求收益較低，原始碼 預設多半 直接傳遞 以保留正確性。
官方文件：效能評測
列出官方測試與 遙測。這些數字可作為觀察指標，但導入前仍需用自己的 逐字稿、紀錄、Excel 與 程式設計 output 做 隔離測試 驗證。
GitHub 專案
專案 README 將 Headroom 描述為可壓縮 工具輸出、紀錄、files、RAG 片段 的工具，支援 library、代理伺服器、MCP server。搜尋時看到 最新版本 為 v0.23.0，日期是 2026-06-04。
可信度提醒：壓縮率、準確率、延遲與成本數字多為官方文件或專案頁提供。實務導入時要用自己的資料集驗證，不應只靠官方 效能評測。
7
一頁式重點
本課重點整理
- Headroom 有用：它能幫長任務降低上下文雜訊，特別是 工具輸出、紀錄、RAG、檔案讀取結果、API 回應 與 逐字稿。
- 對本地 LLM 的價值不是省錢：本地系統更需要穩定長任務、乾淨交接、避免 上下文 爆掉。
- 不要取代記憶庫：它不是 Obsidian、Wiki Agent、Codex 技能 sync 或 Summary Agent 的替代品。
- 先自建規則：先定義壓縮邊界、raw 保留、證據筆記、回查流程，再測 Headroom 隔離測試。
- 先試三個管線：Wiki raw 轉 證據筆記、Codex build/log 摘要、art 逐字稿 轉教學 摘要。
- 安全邊界要硬：不要壓縮 機密、精確 差異、正式合規內容，不要讓它直接改 Wiki 正式知識。
一句話：Headroom 是上下文清理器，不是大腦。它可以讓 代理 看得更清楚，但不能替代 Hermes 的知識治理與 原始封存。