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

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

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

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

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

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

1

Claude Code 質(zhì)量有多高？

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

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

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

下文對于 harness 的評價(jià)描述，主要基于 Anthropic 的技術(shù)文檔。

1

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

context 是要錢的

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

Claude Code 的做法是給每一塊內(nèi)容設(shè)硬上限，強(qiáng)制控制哪些東西能進(jìn)窗口、進(jìn)多少。

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

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

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

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

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

生產(chǎn)系統(tǒng)的本質(zhì)是處理失敗

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

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

三級之上還有熔斷器：

// 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 里跑數(shù)據(jù)，發(fā)現(xiàn)自動壓縮連續(xù)失敗的會話每天浪費(fèi)了約 25 萬次 API 調(diào)用。壓縮失敗的原因通常是上下文已經(jīng)壞掉了，繼續(xù)壓根沒有意義。于是加了個規(guī)則：連續(xù)失敗 3 次就停，不再嘗試。

demo 只需要跑通。生產(chǎn)系統(tǒng)還要知道失敗的時(shí)候怎么止損。

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

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

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

有一個細(xì)節(jié)：剛用過的工具，它的參考文檔不會被推進(jìn)來：

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

模型剛用過這個工具，上下文里已經(jīng)有使用記錄了，這時(shí)候再把文檔推進(jìn)來只是重復(fù)信息，占位置沒有額外價(jià)值。

1

網(wǎng)絡(luò)層：工具接入

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

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

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

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

ToolSearch 永遠(yuǎn)完整加載，因?yàn)槟Ｐ鸵克覄e的工具。如果 ToolSearch 也延遲加載，模型就找不到任何東西了。

每個工具還帶著一套屬性：能不能并行執(zhí)行、會不會修改文件系統(tǒng)、結(jié)果超過多大寫磁盤、用戶打斷時(shí)是停掉還是繼續(xù)跑完。

這些屬性不是給人看的文檔，是調(diào)度引擎決定怎么執(zhí)行這個工具的依據(jù)。

權(quán)限彈窗可以被提前消除

工具調(diào)用要過五關(guān)才能執(zhí)行：輸入校驗(yàn)、權(quán)限邏輯、規(guī)則匹配、hook 攔截、分類器或用戶確認(rèn)。每一關(guān)都可能叫停，但也都需要時(shí)間。

其中最慢的是等用戶點(diǎn)確認(rèn)。為了消除這個等待，分類器在彈窗還沒彈出來的時(shí)候就已經(jīng)開始跑了：

/** * 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}

如果分類器判斷"這個命令大概率沒問題"，彈窗直接跳過。用戶感知不到等待，因?yàn)榕袛嘣趶棿皽?zhǔn)備期間已經(jīng)做完了。

1

容器層：Sub agent設(shè)計(jì)

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

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

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

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

}

子 agent 自己建的連接，退出時(shí)自己關(guān)。復(fù)用父 agent 已有的連接，不能關(guān)，因?yàn)楦?agent 還在用。

1

新加了一層Hook系統(tǒng)

hook 系統(tǒng)讓 harness 變成了平臺

Claude Code 開放了 27 個事件節(jié)點(diǎn)，在 agent 運(yùn)行的任何關(guān)鍵時(shí)刻，用戶都可以插進(jìn)來做點(diǎn)什么：

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

插進(jìn)來能干什么？不只是攔截，還能改。工具執(zhí)行前可以把入?yún)⒏牡?，比?agent 要寫一個文件，hook 把路徑悄悄改到沙箱目錄，agent 不知道，照常執(zhí)行，但文件落在了安全的地方。

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

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

1

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

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

想搞清楚一個生產(chǎn)級 harness 到底是怎么運(yùn)轉(zhuǎn)的，直接去讀代碼。

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

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

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

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

點(diǎn)個“愛心”，再走 吧