Harness 工程實踐復盤：100% Cache 命中的 Agent 怎么設計？

本文作者 ClackyAI 創始人李亞飛。OpenClacky 是他們推出的開源 AI Agent 項目。

Harness，正在被越來越多的團隊重視。

簡單說，Harness 是 Agent 除了大模型之外的一切工程，包括 prompt 怎么組裝、工具怎么設計、上下文怎么管理、成本怎么控制等等。模型能力再強，但 Harness 做得差，賬單和效果都會很難看。

ClackyAI 團隊近期拿 4 家 Agent 做了一次橫向測評，結果發現：

同樣的 prompt、同樣的模型、同樣的任務，成本最高可以相差 6 倍，且能與 ClaudeCode 保持同等能力。也再次印證了，Harness 工程的水平，才是 Agent 產品真正拉開差距的地方。

這篇文章，是 ClackyAI 團隊在 Harness 工程實踐上的實踐復盤。ClackyAI 的開源 Agent 項目 OpenClacky，在 Harness 工程上摸索了兩年，經歷了兩代失敗，最后用 Ruby 從零完成了第三代重寫。（OpenClacky：https://www.openclacky.com/）

在這篇文章中，他們復盤并總結了影響成本和效果的 7 個關鍵決策。對于正在做 Agent 產品的團隊來說，值得一讀。

??關注 Founder Park，最及時最干貨的創業分享

Founder Park 正在持續尋找值得被看見的 AI 團隊與項目。

我們將通過「AI 產品市集」、內容報道、社群分發等方式，幫你觸達早期用戶、獲得真實反饋，以及建立關鍵連接。

如果你正在做 AI 相關的事，歡迎和我們聊聊。

01踩過兩次坑：搞 RAG、做多 Agent 工作流

在講決策之前，先講兩段失敗。現在回頭看失敗得很徹底，但這兩個彎路我感覺還有很多團隊在走。

第一代：RAG / 知識庫。把用戶代碼庫、文檔、歷史會話全部 embedding 進向量庫，檢索 + 重排 + 改寫查詢。聽起來合理，實際跑下來三個致命問題：向量更新成本高且實時性差；90% 的召回率聽著不錯但對 Agent 場景完全不夠用（我判斷 97% 才剛剛夠用）；多了一個會掛的部件，延遲也上來了。

結論：不要搞 RAG。如果你要上 Agent，直接上 Agent，外加一個適合 AI 閱讀的文檔站就夠了。

第二代：多 Agent 工作流。Planner、Coder、Reviewer、Tester 各一個 agent，消息總線編排。結果：每個 sub-agent 各有 cache 命名空間，交接一次就 miss 一次。單 agent 4 分鐘能完成的任務，多 agent 編排到 14 分鐘，成本翻 6 倍。SWEBench 分數能刷上去，但實際用戶體驗脫節得厲害。

結論：不要做多 Agent 編排。人類的分工邏輯不適用于 AI——AI 不需要「一個人想、一個人寫、一個人審」，一個足夠好的 agent 加一套足夠好的 harness 就夠了。Benchmark 跑分也不重要，模型每半年跨一個臺階，用工作流堆出來的分數會被下一代模型 + 樸素 harness 直接抹平。

第三代從零重寫，圍繞兩件事組織：Cache 局部性和工具集穩定性。以下 7 個決策都屬于這一代。

027 個關鍵工程決策決策 1：雙 Cache 標記

大模型的 prompt cache 是按前綴匹配的——前綴里改一個字節，從那里往后全部失效。所以前綴的層次結構和標記位置，決定了下一輪還能命中多少。

最直覺的做法是每輪在消息末尾打一個標記。但這個做法在三個場景下會失效：歷史消息追加后原標記位置的內容變了；模型回退一次工具調用后標記直接作廢；切換模型時標記抖動導致額外的 miss。

我們的做法是每輪標兩條連續消息，形成一個滾動雙緩沖：任何時刻都持有兩個斷點，一個讀一個寫。下一輪把「讀」再讀一次，在新尾部寫一個新的。這樣即使模型回退了一步，倒數第二個標記仍然落在有效消息上——單步回退仍能命中。

為什么是 2 不是 3？因為雙標記正好覆蓋「舊尾部 / 新尾部」這一個邊界，第三個標記落在更前面的位置，對應的 cache 段永遠會被前兩個覆蓋——多寫一次白花錢。

決策 2：System Prompt 字節凍結

OpenClacky 的 system prompt 在 session 啟動時一次性構建，之后一個字節都不動。這是 cache 命中率的第一道地基——system prompt 一變，后面所有 cache 全廢。

但日常運行中至少有四類信息「天然想插進 system prompt」：當前時間、當前模型、新裝的 Skill、用戶偏好更新。如果真寫進去，任何一次變更都是全量失效。

我們的做法是把這些動態信息寫成一條普通消息插進對話歷史，打上「系統注入」標簽。它不會被 cache 標記選中，不會被算作真實用戶輪數，壓縮時也不會原樣搬進新歷史。同一天內只注入一條，跨天或切模型時再插一條新的。

代價是：session 中途裝的新 Skill，當前 session 里看不到，要開新 session 才能用。我們接受這個摩擦——裝 Skill 是低頻操作，cache 命中是每輪都在享受的收益。

決策 3：Skill 子 Agent 架構

invoke_skill 是整個 OpenClacky 最核心的設計。它啟動一個子 agent，子 agent 擁有跟主 agent 完全相同的工具集，執行完后把結果返回給主 agent。主 agent 的歷史里只看到一對「調用 → 結果」消息。

這個設計一口氣解決了好幾個問題：

狀態隔離。做代碼審查的 Skill 可能需要讀幾十個文件、跑大量搜索、輸出長篇分析。這些中間過程隔離在子 agent 的 session 里，主 agent 的歷史沒有被污染——cache 命中率不受影響，壓縮也不會被提前觸發。

動態加載，不改工具列表。裝新 Skill 就是放一個文件到指定目錄。invoke_skill 這個工具本身始終存在，Skill 的內容是調用那一刻才讀取的。不需要改 system prompt，不需要改工具 schema，不需要重啟 session。

能力可以無限擴展，但工具數始終是 16 個。代碼探索、記憶召回、PPT 生成、部署上線——這些能力全部是 Skill，通過 invoke_skill 這一個工具入口調用。主 agent 的 system prompt 里只需要列出 Skill 名稱和描述，不需要為每個能力增加獨立工具。

決策 4：固定 16 個工具

工具 schema 緊貼 system prompt 之后，在 cache 前綴里。每多一個工具，不只多了 schema 的 token 成本，還多了「下次改工具時全量失效」的風險面。但工具太少也有代價：模型本來一步能做完的事要分好幾步，輪次上去了，每輪都在付錢。

我們的答案是 16 個：文件讀寫 3 個、代碼搜索 2 個、終端 1 個、瀏覽器 1 個、網絡 2 個、任務管理 4 個、用戶交互 1 個、Skill 調用 1 個、安全刪除 1 個。

設計原則是：參數盡量少（減少模型出錯），粒度剛好夠用（不冗余也不過度合并），每個工具有充分的測試覆蓋（1600+ 測試用例）。

那些「看起來需要專用工具」的能力——代碼庫分析、記憶讀寫、瀏覽器多動作、sub-agent 編排、定時任務——全部通過 Skill 實現（決策 3），不占工具位。這一套跑了 4 個月，沒有需要加第 17 個工具的時候。

決策 5：壓縮不換模型，空閑時做

上下文窗口再大也會填滿。壓縮不可避免，但壓縮是 cache 命中率最大的單點威脅：老消息被替換成摘要，前綴從那一刻起就不一樣了，必然 miss。

不換模型壓縮。很多 agent 開一個獨立的 LLM call 用小模型做摘要。問題是這個獨立 call 跟主 session 沒有任何共享前綴，壓縮本身就是 100% miss；壓完之后主 session 的歷史也變了，又是一輪 miss。等于每次壓縮付兩筆錢。

我們的做法是把壓縮指令作為一條消息插進當前對話末尾，走正常請求路徑。壓縮 call 命中現有 cache（只有尾部幾百 token 的指令是冷的），壓完后重建歷史只 miss 一輪。對比獨立 call 方案，一次 50K token 會話的壓縮事件，冷 token 從 50000 降到 500。

空閑第 3 分鐘啟動壓縮。大模型廠商的 cache 有 TTL，一段時間無請求就過期。我們跑了一個后臺計時器：用戶停止輸入 90 秒后檢查，如果歷史接近閾值就立刻壓縮——此時 cache 還是熱的，代價極低。用戶思考幾分鐘回來，看到的是一個已經壓縮好、cache 已經 warm 的 session。不做這一步的話，用戶回來面對的是 cache 過期的長歷史，單那一輪可能就是 10 倍成本。

積極壓縮而非用滿上下文。「百萬 token 上下文」聽起來性感，但模型在超長上下文里注意力會分散，而且你真用不起——100 萬 token 即使全部 cache hit，一輪也要付 10 萬 token 等價的錢。我們的策略是壓縮后保持歷史在 1 萬 token 以內。短歷史 + 高命中率，比長歷史 + 偶爾 miss 便宜得多，效果也更可控。

決策 6：工具自進化

PDF、Excel、Word、PPT 的讀取是 Agent 高頻需求。內置專用工具會讓工具列表膨脹（違背決策 4），做成 Skill 讓用戶手動裝體驗又差。

我們選了第三條路：首次安裝時把一組 Python 腳本復制到用戶目錄，agent 需要讀文檔時用終端工具跑這些腳本。工具列表沒有增加。如果腳本跑不過（缺依賴、格式變了），agent 自己修改腳本、裝依賴，下次就不會出問題。

處理文檔的能力不是寫死在代碼里的，它活在用戶目錄的腳本里，agent 自己可以維護和進化。

決策 7：內置瀏覽器，接管已有 Chrome

瀏覽器自動化越來越重要。主流做法是 Headless 瀏覽器或外接 MCP 服務，我們兩種都不用——內置了一個 MCP Client，直接接管用戶已經在跑的 Chrome / Edge。

Headless 的問題是「看不見」：用戶不知道 agent 在干什么，出了問題無法判斷，登錄態和 cookie 也拿不到。外接 MCP 的問題是安裝成本高、穩定性不可控、工具 schema 不可控（外部 MCP 可能暴露幾十個細粒度工具，直接打進工具列表就違背了決策 4）。

接管已有瀏覽器的好處是：用戶看得見 agent 的操作、登錄態和 cookie 直接可用、對外只暴露一個 browser 工具（snapshot / click / type / navigate 等動作都是這一個工具的參數），schema 穩定。代價是需要維護 daemon 的生命周期管理，但這是一次性的工程投入。

03把工程預算花在 Harness 上，把智能預算留給模型

回到文章開頭的這張表。

這 7 個決策背后其實只有一句話：把工程預算花在 Harness 上，把智能預算留給模型。

不做 RAG，不做多 Agent 編排，不做工具堆疊——不是因為這些東西沒用，而是因為模型在快速變好。半年前需要 4 個 agent 協作才能通過的任務，今天一個 agent + 一套好的 harness 就能做得更快更便宜。

我們選擇把精力放在那些不會隨模型進步而過時的事情上：cache 命中率、工具穩定性、安裝體驗、壓縮策略。這些是 Harness 層面的基礎設施，不管模型換到哪一代都用得上。

OpenClacky 七個核心工程決策，讓它成為了和 ClaudeCode 同一梯位的 Agent 產品，與其他同類 Agent 拉開了較大距離。

OpenClacky 完全開源，免費使用，MIT 協議，支持自用 LLM Key。如果你是工程師，歡迎 Github 點贊支持，深入了解源碼。如果你用過其他 Agent 賬單起飛想要一個更省錢的 Agent，歡迎試用。如果你是新人，無須猶豫，立刻下載安裝。

• 安裝指引和產品文檔：openclacky.com

• 4 家 Agent 橫評的完整數據、產物對比、錄像回放：openclacky.com/benchmark

• Github 地址：github.com/clacky-ai/openclacky

轉載原創文章請添加微信：founderparker