完全指南)
如何為Caveman添加新的Compressor壓縮器注冊與開發(fā)完全指南【免費下載鏈接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman項目地址: https://gitcode.com/GitHub_Trending/caveman1/cavemanCaveman 是一款面向 AI Agent 的 Token 壓縮引擎核心賣點是用最少的 token 把事辦成——通過壓縮器Compressor把 JSON、日志、代碼等上下文縮減最多 65%。當你想支持一種新內容類型比如 Markdown 表格、SVG、數據庫查詢結果就需要為 Caveman 注冊一個新的 Compressor。本文用通俗的方式講清楚壓縮器注冊機制、開發(fā)步驟、安全等級聲明和測試要求幫助你從零到提交 PR。一、先搞懂Caveman 的壓縮器注冊機制Caveman 的引擎采用「檢測 → 查注冊表 → 壓縮 → 門禁校驗」的流水線。所有 Compressor 都集中在engine/compressors/目錄下由一張**注冊表Registry**統(tǒng)一路由Compressor 接口每個壓縮器只需實現 3 個方法見 compressor.goContentType()返回它負責的內容類型名如json、logSafetyClass()聲明自身在 S0–S4 安全階梯上的等級Compress(input)純字節(jié)變換成功返回壓縮結果任何解析失敗都返回okfalse引擎會把原始字節(jié)原樣透傳fail-closed 設計Registry一張「內容類型 → Compressor」的映射表。Default()函數一次性注冊全部 15 個內置壓縮器你的新壓縮器也在這里上崗。type Compressor interface { ContentType() string SafetyClass() safety.Class Compress(input []byte) (out []byte, ok bool) }內置 Compressor 一覽內容類型壓縮器選擇方式jsonJSON 數組折疊保留錯誤項、首尾元素自動檢測log日志降噪保留 ERROR/FATAL 行自動檢測code源碼精簡tree-sitter / go-ast 雙實現自動檢測diff/search-result/text/html/tabular/config/terminal對應專用壓縮器自動檢測toon/a11y/toolschema/repetition等高級變換僅顯式指定Options.Type幾個設計要點值得新手特別注意純字節(jié)變換Compressor 不數 token、不存恢復記錄、不碰網絡——這些由引擎核心負責所以每個壓縮器都是自包含、可獨立測試的模塊。確定性 冪等相同輸入永遠得到相同輸出且壓縮結果再壓縮不會變化。更小的門禁壓縮結果必須比原文小否則引擎丟棄結果、回退原文。有損可恢復聲明為 S4有損的壓縮器原始字節(jié)必須先存入 CCR 恢復存儲engine/ccr/模型后續(xù)可按 handle 取回原文。二、開發(fā)新 Compressor 的 5 個步驟步驟 1新建一個壓縮器文件在engine/compressors/下新建文件如markdown.go參照 json.go 或 config.go 的寫法定義一個結構體持有可調參數如保留行數、閾值并提供NewXxx() Compressor構造函數。以 config 壓縮器為例它用一組正則識別 YAML/TOML/INI結構體里只有minLines、keepHead、keepTail等幾個參數非常輕量。步驟 2聲明安全等級安全等級由壓縮方法本身決定寫在 engine/safety/safety.go 的階梯里等級含義是否可改模型可見字節(jié)是否需要 CCR 恢復S0 / S1元數據、緩存提示類否否S2 / S3結構性 / 行為性變更是否S4有損壓縮絕大多數壓縮器是是且必須披露丟棄了什么如果你做的壓縮會刪減模型可見內容折疊數組、省略行就老老實實聲明 S4。步驟 3實現 fail-closed 的 Compress三條鐵律可對照 compressor.go 頂部注釋有界解析不要無限制地遞歸解析避免內存爆炸任何疑問都放棄解析失敗、結構不支持、沒有把握 → 返回(nil, false)絕不輸出看起來差不多的結果省略要留標記像日志壓縮器那樣用... N lines elided (caveman)標記折疊區(qū)域讓模型知道內容被省略且可恢復。步驟 4在 Default 注冊表中注冊打開 compressor.go 的Default()函數加一行r.Register(NewMarkdown())。這里有個進階細節(jié)如果自動檢測可能誤判比如 Markdown 和純文本很難區(qū)分學 TOON 和 a11y 的做法——注冊但只允許顯式指定類型到達不進自動檢測鏈如果你的壓縮器編譯產物永遠路由不到把它加進manifestExcluded白名單。否則它會進入能力清單導致RegistrySHA256變化讓所有已發(fā)布的 Cave Build 鎖在運行期失效——這是注冊時最容易踩的坑。步驟 5接入內容檢測如需自動選擇自動檢測邏輯在 engine/detect.go順序是嚴格 JSON → 終端輸出 → diff → HTML → 表格 → 代碼 → 日志 → 搜索結果 → 配置 → 兜底text。新增檢測信號時注意信號必須是確定性、可證的參考 ANSI 轉義序列作為終端判定依據的做法——只有終端輸出才合法攜帶它低置信度內容一律落入text交給保守壓縮器兜底。三、Compressor 測試怎么寫參考 log_test.go 的測試套路一個好壓縮器的測試至少覆蓋 4 類用例用例驗證點核心行為錯誤/關鍵行被保留噪音被折疊輸出出現省略標記體積門禁輸出嚴格小于輸入冪等性壓縮結果二次壓縮保持不變失敗回退畸形輸入返回okfalse原樣透傳測試 fixture 放在engine/compressors/testdata/邊界用例空輸入、恰好閾值長度、超大輸入用真實數據支撐發(fā)布任何性能聲明前必須有 fixture 背書要求見 extending.md。四、提交前檢查清單 ? 無歧義的內容類型名 已聲明的安全等級? 有界解析、確定性輸出、冪等? 非法輸入回退原始字節(jié)fail-closed? S4 輸出已接入 CCR 恢復存儲? 明確選擇方式自動檢測 or 僅顯式指定? 覆蓋有效/無效/輸出變大/邊界的 fixture 測試? 更新Default()注冊表及 engine.md 中的注冊器數量與文檔五、關鍵文件路徑速查路徑說明engine/compressors/compressor.goCompressor 接口、Registry 與 Default 注冊表engine/compressors/json.goJSON 壓縮器省略標記、BM25 相關性選取engine/compressors/config.goYAML/TOML/INI 壓縮器engine/compressors/html.goHTML 正文提取純 Go 可讀性啟發(fā)式engine/detect.go內容類型自動檢測路由engine/safety/safety.goS0–S4 安全等級注冊表engine/ccr/有損壓縮的原始字節(jié)恢復存儲docs/technical/engine.md壓縮引擎官方文檔含流水線圖docs/technical/extending.md擴展指南新增壓縮器要求清單掌握「接口三方法 注冊表 安全等級 fail-closed 測試」這四件套你就能像維護者一樣為 Caveman 貢獻一個穩(wěn)健的新 Compressor 了?！久赓M下載鏈接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman項目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 如何為Caveman添加新的Compressor：壓縮器注冊與開發(fā)完全指南
如何為Caveman添加新的Compressor壓縮器注冊與開發(fā)完全指南【免費下載鏈接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman項目地址: https://gitcode.com/GitHub_Trending/caveman1/cavemanCaveman 是一款面向 AI Agent 的 Token 壓縮引擎核心賣點是用最少的 token 把事辦成——通過壓縮器Compressor把 JSON、日志、代碼等上下文縮減最多 65%。當你想支持一種新內容類型比如 Markdown 表格、SVG、數據庫查詢結果就需要為 Caveman 注冊一個新的 Compressor。本文用通俗的方式講清楚壓縮器注冊機制、開發(fā)步驟、安全等級聲明和測試要求幫助你從零到提交 PR。一、先搞懂Caveman 的壓縮器注冊機制Caveman 的引擎采用「檢測 → 查注冊表 → 壓縮 → 門禁校驗」的流水線。所有 Compressor 都集中在engine/compressors/目錄下由一張**注冊表Registry**統(tǒng)一路由Compressor 接口每個壓縮器只需實現 3 個方法見 compressor.goContentType()返回它負責的內容類型名如json、logSafetyClass()聲明自身在 S0–S4 安全階梯上的等級Compress(input)純字節(jié)變換成功返回壓縮結果任何解析失敗都返回okfalse引擎會把原始字節(jié)原樣透傳fail-closed 設計Registry一張「內容類型 → Compressor」的映射表。Default()函數一次性注冊全部 15 個內置壓縮器你的新壓縮器也在這里上崗。type Compressor interface { ContentType() string SafetyClass() safety.Class Compress(input []byte) (out []byte, ok bool) }內置 Compressor 一覽內容類型壓縮器選擇方式jsonJSON 數組折疊保留錯誤項、首尾元素自動檢測log日志降噪保留 ERROR/FATAL 行自動檢測code源碼精簡tree-sitter / go-ast 雙實現自動檢測diff/search-result/text/html/tabular/config/terminal對應專用壓縮器自動檢測toon/a11y/toolschema/repetition等高級變換僅顯式指定Options.Type幾個設計要點值得新手特別注意純字節(jié)變換Compressor 不數 token、不存恢復記錄、不碰網絡——這些由引擎核心負責所以每個壓縮器都是自包含、可獨立測試的模塊。確定性 冪等相同輸入永遠得到相同輸出且壓縮結果再壓縮不會變化。更小的門禁壓縮結果必須比原文小否則引擎丟棄結果、回退原文。有損可恢復聲明為 S4有損的壓縮器原始字節(jié)必須先存入 CCR 恢復存儲engine/ccr/模型后續(xù)可按 handle 取回原文。二、開發(fā)新 Compressor 的 5 個步驟步驟 1新建一個壓縮器文件在engine/compressors/下新建文件如markdown.go參照 json.go 或 config.go 的寫法定義一個結構體持有可調參數如保留行數、閾值并提供NewXxx() Compressor構造函數。以 config 壓縮器為例它用一組正則識別 YAML/TOML/INI結構體里只有minLines、keepHead、keepTail等幾個參數非常輕量。步驟 2聲明安全等級安全等級由壓縮方法本身決定寫在 engine/safety/safety.go 的階梯里等級含義是否可改模型可見字節(jié)是否需要 CCR 恢復S0 / S1元數據、緩存提示類否否S2 / S3結構性 / 行為性變更是否S4有損壓縮絕大多數壓縮器是是且必須披露丟棄了什么如果你做的壓縮會刪減模型可見內容折疊數組、省略行就老老實實聲明 S4。步驟 3實現 fail-closed 的 Compress三條鐵律可對照 compressor.go 頂部注釋有界解析不要無限制地遞歸解析避免內存爆炸任何疑問都放棄解析失敗、結構不支持、沒有把握 → 返回(nil, false)絕不輸出看起來差不多的結果省略要留標記像日志壓縮器那樣用... N lines elided (caveman)標記折疊區(qū)域讓模型知道內容被省略且可恢復。步驟 4在 Default 注冊表中注冊打開 compressor.go 的Default()函數加一行r.Register(NewMarkdown())。這里有個進階細節(jié)如果自動檢測可能誤判比如 Markdown 和純文本很難區(qū)分學 TOON 和 a11y 的做法——注冊但只允許顯式指定類型到達不進自動檢測鏈如果你的壓縮器編譯產物永遠路由不到把它加進manifestExcluded白名單。否則它會進入能力清單導致RegistrySHA256變化讓所有已發(fā)布的 Cave Build 鎖在運行期失效——這是注冊時最容易踩的坑。步驟 5接入內容檢測如需自動選擇自動檢測邏輯在 engine/detect.go順序是嚴格 JSON → 終端輸出 → diff → HTML → 表格 → 代碼 → 日志 → 搜索結果 → 配置 → 兜底text。新增檢測信號時注意信號必須是確定性、可證的參考 ANSI 轉義序列作為終端判定依據的做法——只有終端輸出才合法攜帶它低置信度內容一律落入text交給保守壓縮器兜底。三、Compressor 測試怎么寫參考 log_test.go 的測試套路一個好壓縮器的測試至少覆蓋 4 類用例用例驗證點核心行為錯誤/關鍵行被保留噪音被折疊輸出出現省略標記體積門禁輸出嚴格小于輸入冪等性壓縮結果二次壓縮保持不變失敗回退畸形輸入返回okfalse原樣透傳測試 fixture 放在engine/compressors/testdata/邊界用例空輸入、恰好閾值長度、超大輸入用真實數據支撐發(fā)布任何性能聲明前必須有 fixture 背書要求見 extending.md。四、提交前檢查清單 ? 無歧義的內容類型名 已聲明的安全等級? 有界解析、確定性輸出、冪等? 非法輸入回退原始字節(jié)fail-closed? S4 輸出已接入 CCR 恢復存儲? 明確選擇方式自動檢測 or 僅顯式指定? 覆蓋有效/無效/輸出變大/邊界的 fixture 測試? 更新Default()注冊表及 engine.md 中的注冊器數量與文檔五、關鍵文件路徑速查路徑說明engine/compressors/compressor.goCompressor 接口、Registry 與 Default 注冊表engine/compressors/json.goJSON 壓縮器省略標記、BM25 相關性選取engine/compressors/config.goYAML/TOML/INI 壓縮器engine/compressors/html.goHTML 正文提取純 Go 可讀性啟發(fā)式engine/detect.go內容類型自動檢測路由engine/safety/safety.goS0–S4 安全等級注冊表engine/ccr/有損壓縮的原始字節(jié)恢復存儲docs/technical/engine.md壓縮引擎官方文檔含流水線圖docs/technical/extending.md擴展指南新增壓縮器要求清單掌握「接口三方法 注冊表 安全等級 fail-closed 測試」這四件套你就能像維護者一樣為 Caveman 貢獻一個穩(wěn)健的新 Compressor 了?！久赓M下載鏈接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman項目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考