作者 ｜ 董道力
郵箱 ｜ dongdaoli@pingwest.com

3 月 31 日，Anthropic 大概沒想到，會以這種方式送給開發者社區一份禮物。

安全研究員 Chaofan Shou 發現，Claude Code 的 npm 包里藏著一個.map 文件——sourcemap，這是給開發者調試用的，按理早該從生產環境剔除。沒剔除就意味著：任何人都可以從這個文件里還原出 Claude Code 完整的源碼。

1906 個文件，512000 行代碼，40 多個工具，85 個斜杠命令。幾小時內，代碼被鏡像到 GitHub，獲得了數千個 Star 和 Fork。

更諷刺的地方在于，代碼里有一個叫"Undercover Mode"的子系統，專門用來防止 Anthropic 內部代號出現在 git commit 里，避免信息泄露。他們精心設計了防泄露機制，然后把整個源碼打包進了 npm。

但這篇文章想聊的不是這個失誤，而是這份代碼里真正值錢的東西：一個生產級 agent harness 長什么樣。

1

Claude Code 質量有多高？

Agent harness 對于整個行業都是在探索的新東西。Anthropic 過去一年反復講一個觀點：模型本身只是引擎，harness 才是整輛車。他們提出了 context engineering、minimal viable tool sets、sub-agent isolation 等一系列設計原則。

現在源碼攤開了，終于可以看看：他們會不會遵循自己寫的技術文檔。

答案是，不僅遵循了，還藏了個焚決。

下文對于 harness 的評價描述，主要基于 Anthropic 的技術文檔。

1

存儲層：上下文工程和記憶

context 是要錢的

上下文越長，模型越容易迷失，這個問題業內叫 context rot。上下文不是越多越好，每多塞一個 token，所有其他 token 分到的注意力就少一點，重要信息被稀釋。

Claude Code 的做法是給每一塊內容設硬上限，強制控制哪些東西能進窗口、進多少。

Skill 列表最多占整個窗口的 1%，每條描述不超過 250 字符：

// verbose whenToUse strings waste turn-1 cache_creation tokens// without improving match rate.export const MAX_LISTING_DESC_CHARS = 250

為什么這么限？因為 Skill 列表的作用是讓模型知道"有這個工具"，不是讓模型讀懂怎么用它。發現工具靠的是關鍵詞匹配，描述寫 500 字和寫 50 字匹配率沒有差別，多出來的全是浪費。

System prompt 被切成兩半。前半部分是所有用戶共用的指令，內容固定，可以緩存，下次調用直接復用。后半部分是這個用戶、這個會話特有的內容，每次動態生成。這樣每次 API 調用只需要處理變化的那一半，省掉了大量重復計算。

大的工具調用結果不放上下文，直接寫到磁盤，給模型一個文件路徑。比如執行了一條命令返回了幾千行日志，把這幾千行塞進上下文會擠掉其他有用的信息，換成文件引用就只占一行。

生產系統的本質是處理失敗

模型接近上下文窗口極限時，會傾向于草草收尾，Anthropic 管這叫"context anxiety"。就像一個人知道自己快沒時間了，會開始跳步驟、走捷徑。解法是徹底清空窗口，把當前進展整理成結構化的交接材料，下一個窗口從交接材料開始，而不是從一個快撐滿的上下文開始。

Claude Code 把這個做成了三級壓縮：先試輕量摘要，不夠再自動壓縮，還不夠等到 API 報錯了再強制壓縮。一級解決不了才走下一級。

三級之上還有熔斷器：

// BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures (up to 3,272)// in a single session, wasting ~250K API calls/day globally.const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

有人在 BigQuery 里跑數據，發現自動壓縮連續失敗的會話每天浪費了約 25 萬次 API 調用。壓縮失敗的原因通常是上下文已經壞掉了，繼續壓根沒有意義。于是加了個規則：連續失敗 3 次就停，不再嘗試。

demo 只需要跑通。生產系統還要知道失敗的時候怎么止損。

記憶不是把所有東西都存起來

跨 context window 的 agent，每次新開一個窗口，之前發生的事情全忘了。Anthropic 把這比作輪班工程師，每班的人來了都不知道上一班干了什么，只能從頭摸索。

Claude Code 用后臺子 agent 定期把對話里的關鍵信息提出來存好，下次需要的時候再注入進來。但不是什么都存，也不是什么都注入。記憶篩選用 Sonnet 來做，判斷哪些記憶和當前任務相關。

有一個細節：剛用過的工具，它的參考文檔不會被推進來：

async function selectRelevantMemories(  query: string,  memories: MemoryHeader[],  recentTools: readonly string[],  // 過濾掉剛用過的工具文檔): Promise

模型剛用過這個工具，上下文里已經有使用記錄了，這時候再把文檔推進來只是重復信息，占位置沒有額外價值。

1

網絡層：工具接入

工具的邊界就是 agent 的能力邊界

工具太多，模型不知道該用哪個，跟沒有工具一樣。這是 agent 設計里公認的坑，工具選擇本身會消耗模型的推理能力，選項越多越容易選錯。

Claude Code 有 50 多個工具，解法是大多數工具初始時根本不出現在上下文里，模型主動搜索才拿到完整定義：

export function isDeferredTool(tool: Tool): boolean {  if (tool.alwaysLoad === true) return false  if (tool.isMcp === true) return true          // MCP工具默認延遲加載  if (tool.name === TOOL_SEARCH_TOOL_NAME) return false  // ToolSearch自己永遠不延遲}

ToolSearch 永遠完整加載，因為模型要靠它找別的工具。如果 ToolSearch 也延遲加載，模型就找不到任何東西了。

每個工具還帶著一套屬性：能不能并行執行、會不會修改文件系統、結果超過多大寫磁盤、用戶打斷時是停掉還是繼續跑完。

這些屬性不是給人看的文檔，是調度引擎決定怎么執行這個工具的依據。

權限彈窗可以被提前消除

工具調用要過五關才能執行：輸入校驗、權限邏輯、規則匹配、hook 攔截、分類器或用戶確認。每一關都可能叫停，但也都需要時間。

其中最慢的是等用戶點確認。為了消除這個等待，分類器在彈窗還沒彈出來的時候就已經開始跑了：

/** * Start a speculative bash allow classifier check early, so it runs in * parallel with pre-tool hooks, deny/ask classifiers, and permission dialog setup. */export function startSpeculativeClassifierCheck(  command: string,  ...): boolean {  const promise = classifyBashCommand(command, ...)  promise.catch(() => {})  // 防止未處理的rejection  speculativeChecks.set(command, promise)  return true}

如果分類器判斷"這個命令大概率沒問題"，彈窗直接跳過。用戶感知不到等待，因為判斷在彈窗準備期間已經做完了。

1

容器層：Sub agent設計

sub-agent 不是套娃，是上下文隔離

sub-agent 的價值是用完即棄：花幾萬 token 去做一個子任務，做完只把結論交給主 agent，中間過程全扔掉。主 agent 的上下文里只有結論，不是整個過程。

有四種執行模式：同步（主 agent 等子 agent 跑完）、異步后臺（子 agent 在后臺跑，完成了通知用戶）、Worktree 文件系統隔離（子 agent 在一個獨立的 git 副本里改代碼，不影響主目錄，改完了再合并）、跨機器隔離（完全在另一臺機器上跑）。風險越高，隔離越徹底。

sub-agent 用的工具是過濾過的，不能遞歸調用自己，防止無限套娃。

}

子 agent 自己建的連接，退出時自己關。復用父 agent 已有的連接，不能關，因為父 agent 還在用。

1

新加了一層Hook系統

hook 系統讓 harness 變成了平臺

Claude Code 開放了 27 個事件節點，在 agent 運行的任何關鍵時刻，用戶都可以插進來做點什么：

export const HOOK_EVENTS = [  'PreToolUse', 'PostToolUse', 'PostToolUseFailure',  'SessionStart', 'SessionEnd',  'SubagentStart', 'SubagentStop',  'PreCompact', 'PostCompact',  'PermissionRequest', 'PermissionDenied',  'WorktreeCreate', 'WorktreeRemove',  // ... 還有14個] as const

插進來能干什么？不只是攔截，還能改。工具執行前可以把入參改掉，比如 agent 要寫一個文件，hook 把路徑悄悄改到沙箱目錄，agent 不知道，照常執行，但文件落在了安全的地方。

有兩種寫法。一種是跑腳本，退出碼 0 就放行，退出碼 2 就攔截，邏輯自己寫。另一種是讓 Haiku 來判斷，給它描述和標準，讓模型決定要不要放行，等 30 秒。

這個設計的結果是：安全策略、審計日志、企業合規要求，全都能從外面接進來，不用改 Claude Code 本身。不同公司有不同的安全規定，以前只能 fork 代碼自己改，現在寫幾個 hook 就行了。harness 從一個固定的產品，變成了可以按需定制的底座。

1

以上七個點，是從源碼里挑出來最容易說清楚的部分。

更多同樣有意思的東西還埋在里面：壓縮后消息的精確重建順序、工具并發分區的狀態競爭處理、Bash 命令里針對 Zsh 和 PowerShell 各自不同的安全繞過邏輯、sub-agent 的 MCP 服務器生命周期管理……每一處細節背后都有一個真實踩過的坑。

想搞清楚一個生產級 harness 到底是怎么運轉的，直接去讀代碼。

512000 行代碼在解決一個問題：怎么讓一個會犯錯的語言模型，穩定地干完一件需要很多步驟的工程任務。

這個問題比"哪個模型更聰明"更難回答，也更值錢。

行業過去兩年把 agent 失敗歸因于模型能力不足。但 Claude Code 認為：模型早就夠用了，缺的是那層認真造出來的 harness。context 配額、壓縮熔斷、工具延遲加載、sub-agent 隔離、hook 平臺……這些東西不是 Anthropic 的獨家秘方，是任何一個想把 agent 做穩的團隊遲早要解決的問題。

Anthropic 先給了個方案，然后意外地把答案公開了，而這可能是這次意外泄露里最值得研究的地方。

點個“愛心”，再走 吧