看看 Claude Code 怎么做 Harness，這才是 Agent 工程化的真正難點(diǎn)

Claude Code 源代碼泄露的事情在 X 等平臺(tái)上引發(fā)了極大的關(guān)注。

不過，這次更值得關(guān)注的不是泄露本身，而是 Claude Code 非常典型的生產(chǎn)級(jí) AI agent harness 設(shè)計(jì)，向外界完整地展示了一個(gè)成熟的 Autonomous Agent 產(chǎn)品應(yīng)該長什么樣，從底層的工程實(shí)現(xiàn)到上層的產(chǎn)品決策邏輯，包含了各種細(xì)節(jié)。

結(jié)合 Substack 以及 Hacker News 上對于源代碼的分析，我們整理了 Claude Code 在 Agent 架構(gòu)設(shè)計(jì)上值得開發(fā)者關(guān)注、學(xué)習(xí)的一些要點(diǎn)。

??關(guān)注 Founder Park，最及時(shí)最干貨的創(chuàng)業(yè)分享

超 22000 人的「AI 產(chǎn)品市集」社群！不錯(cuò)過每一款有價(jià)值的 AI 應(yīng)用。

邀請從業(yè)者、開發(fā)人員和創(chuàng)業(yè)者，飛書掃碼加群：

進(jìn)群后，你有機(jī)會(huì)得到：

• 最新、最值得關(guān)注的 AI 新品資訊；
  

• 不定期贈(zèng)送熱門新品的邀請碼、會(huì)員碼；
  

• 最精準(zhǔn)的 AI 產(chǎn)品曝光渠道

01真正的難點(diǎn)，在模型之外的 Harness

Claude Code 的架構(gòu)核心，是一個(gè)「Harness」本地運(yùn)行時(shí)的外殼，更多地是依靠 Harness 的工程化與可靠性。

根據(jù)公開鏡像倉庫 nirholas/claude-code，Claude Code 的 TypeScript 源代碼跨越了約 1,900 個(gè)文件，超過 512,000 行嚴(yán)格類型的 TypeScript，基于 Bun 運(yùn)行時(shí)構(gòu)建，用 React 和 Ink 驅(qū)動(dòng)終端 UI。

在架構(gòu)文檔里，描述的 Claude Code 系統(tǒng)相當(dāng)龐大：一個(gè)大型 QueryEngine、集中式工具注冊表、數(shù)十個(gè)斜杠命令、持久化記憶、IDE 橋接、MCP 集成、遠(yuǎn)程會(huì)話、插件、技能，以及支持后臺(tái)和并行工作的任務(wù)層。

更準(zhǔn)確的比喻是，Claude Code 更像是一個(gè)用于軟件工作的操作系統(tǒng)，圍繞模型堆疊了權(quán)限管理、記憶層、后臺(tái)任務(wù)、IDE 橋接、MCP 管道和多代理編排。

Vikash Rungta 在他的逆向工程分析里把這個(gè)東西叫做 Harnes：一個(gè)本地運(yùn)行時(shí)外殼，把 LLM（Brain）包裹在工具、記憶和編排邏輯（Body）之中，讓模型能在現(xiàn)實(shí)世界里行動(dòng)。

要想理解 Claude Code，首先要理解 Agent 架構(gòu)的三個(gè)代際演進(jìn)：

• 第一代是 Chatbot，無狀態(tài)問答；

• 第二代是 Workflow，用 n8n、LangChain 這類工具把 LLM 嵌進(jìn)代碼驅(qū)動(dòng)的 DAG 流里，代碼決定模型下一步做什么；

• 第三代是 Autonomous Agent，模型控制循環(huán)，運(yùn)行時(shí)只是執(zhí)行器。

Claude Code，就是屬于第三代的商業(yè)化產(chǎn)品。

Claude Code 的源碼也說明了，真正難的是 Harness，給任何支持工具調(diào)用的 LLM 提供文件系統(tǒng)訪問、shell、分層記憶和聲明式擴(kuò)展能力。所有的這些，都要在一個(gè)由可組合權(quán)限約束的有界自主循環(huán)里運(yùn)行。

02TAOR Loop 設(shè)計(jì)：Orchestrator 越笨，架構(gòu)越穩(wěn)定

Claude Code 的執(zhí)行引擎是一個(gè)叫 TAOR 的循環(huán)：Think-Act-Observe-Repeat。這個(gè)設(shè)計(jì)本身不復(fù)雜，但背后的設(shè)計(jì)哲學(xué)，很值得關(guān)注。

它的 Orchestrator 本身被設(shè)計(jì)得極其「愚蠢」，只負(fù)責(zé)驅(qū)動(dòng)循環(huán)、執(zhí)行工具調(diào)用、感知結(jié)果。所有的推理、決策、何時(shí)停止，全部都交給模型。運(yùn)行時(shí)不知道代碼是什么，不知道文件在哪，它只是跑循環(huán)，讓模型決定下一步。

總結(jié)來講：運(yùn)行時(shí)越笨，架構(gòu)越穩(wěn)定。把智能下沉到模型，把確定性留給框架。

這和早期 LangChain 試圖在框架層做各種「聰明編排」的路線形成了鮮明對比。LangChain 更傾向于把編排邏輯寫進(jìn)代碼，用復(fù)雜的 Orchestrator 控制 LLM 的每一步。Claude Code 的做法是，所有的推理、決策和停止判斷，統(tǒng)統(tǒng)下放給大模型本身。TAOR 循環(huán)的核心邏輯大約只有 50 行，但給了模型無限的操作空間。

同樣，在工具層遵循這個(gè)「笨」的哲學(xué)。Claude Code 沒有給模型配備 100 個(gè)專項(xiàng)工具，而是只提供四種能力原語：Read、Write、Execute、Connect。其中 Bash 是通用適配器，允許模型使用任何人類開發(fā)者會(huì)用的工具——git、npm、docker，全部通過 shell 組合完成。不要構(gòu)建 100 個(gè)工具，給模型一個(gè) shell，讓它自己組合。

隨著模型變得更強(qiáng)，腳手架應(yīng)該變薄，而不是變厚。硬編碼的腳手架應(yīng)該隨著模型能力提升而被主動(dòng)刪除，架構(gòu)隨時(shí)間推移越來越薄。如果你每次模型升級(jí)都要往框架里加更多腳手架，說明你在對抗模型，而不是利用模型。

03Context Window 是稀缺資源，不是越大越好

Context 不是越大越好，而是越干凈越好。這是 Claude Code 整個(gè)架構(gòu)里貫穿始終的設(shè)計(jì)原則。

一般來說，Context Collapse 是 Agent 系統(tǒng)最普遍的失敗模式。隨著對話進(jìn)行，上下文窗口被填滿，記憶退化，幻覺出現(xiàn)，Agent 開始在自己積累的噪音里迷失方向。但 Claude Code 把 Context Window 看成了一種需要主動(dòng)管理的稀缺資源，圍繞 Context 構(gòu)建了一套自動(dòng)壓縮、子 Agent 隔離和詳盡的緩存經(jīng)濟(jì)學(xué)防御體系。

第一層是 Auto-Compaction。當(dāng) Context 使用量達(dá)到約 50% 時(shí)自動(dòng)觸發(fā)，用 LLM 摘要替換原始對話輪次，釋放空間的同時(shí)保留關(guān)鍵決策。這不是簡單地截?cái)鄽v史，而是用摘要壓縮，確保重要信息不丟失。這個(gè)機(jī)制對應(yīng)的故障模式叫做 Context Collapse，解決方案是：Auto-compaction at ～50% + sub-agents with isolated context windows。

第二層是 Sub-Agent 隔離。把重型的探索、研究任務(wù)卸載給獨(dú)立的子 Agent。子 Agent 運(yùn)行自己獨(dú)立的 TAOR 循環(huán)，有自己的 Context 預(yù)算，任務(wù)完成后只把摘要返回給主 Agent。這樣，無論子任務(wù)消耗了多少 token，主 Agent 的 Context 都不會(huì)被污染。

從代碼結(jié)構(gòu)上看，這個(gè)機(jī)制的設(shè)計(jì)非常精細(xì)。子 Agent 運(yùn)行時(shí)：有自己的 maxTurns 上限、有自己的 compaction 機(jī)制（獨(dú)立壓縮，不影響主對話）、有自己的 MEMORY.md。主 Agent 派出子 Agent 之后，只等一個(gè) summary 回來，整個(gè)子任務(wù)的 token 消耗對主 Context 完全透明隔離。

第三層是 Prompt Cache 經(jīng)濟(jì)學(xué)。promptCacheBreakDetection.ts 里追蹤了 14 個(gè) cache-break 向量，也就是 14 種會(huì)讓 prompt 緩存失效的情況。代碼里還有一個(gè)函數(shù)叫 DANGEROUS_uncachedSystemPromptSection()，光是這個(gè)命名本身就是一種文檔：這里加?xùn)|西要小心，會(huì)破壞緩存。代碼里還有多個(gè) sticky latches，防止模式切換破壞 prompt 緩存的鎖定機(jī)制。

當(dāng)你為每個(gè) token 付費(fèi)的時(shí)候，緩存失效不再是計(jì)算機(jī)科學(xué)笑話，更多的是一個(gè)財(cái)務(wù)問題。

此外，還有一個(gè)細(xì)節(jié)是：Session Continuity。在 Claude Code 里，會(huì)話不是一次性的。它們像 git branch 一樣運(yùn)作，可以 checkpoint、rollback，或者把某個(gè)探索方向 fork 成一條新路徑。這意味著 Context 的管理不只是在單次會(huì)話內(nèi)，而是跨會(huì)話的。

04記憶系統(tǒng)的核心是索引，不是存儲(chǔ)

Claude Code 的記憶系統(tǒng)設(shè)計(jì)，也非常有意思。

大多數(shù)人想象「Agent 記憶」就像一個(gè)更大的背包，裝得越多越好。但 Claude Code 的記憶系統(tǒng)，更像是一個(gè)帶有嚴(yán)格圖書管理員的檔案系統(tǒng)。

核心設(shè)計(jì)原則是：記憶是索引，不是存儲(chǔ)。能從代碼庫中重新推導(dǎo)出的信息，絕不應(yīng)該被存儲(chǔ)。

從架構(gòu)上看，Claude Code 的記憶系統(tǒng)分為六層，在每次會(huì)話啟動(dòng)時(shí)按層加載：

• Managed Policy（組織級(jí)策略）：企業(yè)或團(tuán)隊(duì)層面的統(tǒng)一規(guī)范

• Project CLAUDE.md（項(xiàng)目配置）：當(dāng)前項(xiàng)目的特定指令和上下文

• User Preferences（用戶偏好）：個(gè)人層面的習(xí)慣和偏好設(shè)置

• Auto-Memory（自動(dòng)學(xué)習(xí)模式）：Agent 從歷史交互中學(xué)到的用戶模式

• Session（會(huì)話上下文）：當(dāng)前會(huì)話的臨時(shí)信息

• Sub-Agent Memory（子 Agent 記憶）：各子 Agent 獨(dú)立維護(hù)的專項(xiàng)記憶

其中，Auto-Memory 循環(huán)甚至允許 Agent 學(xué)習(xí)用戶的工作模式，并把這些模式寫入 MEMORY.md 供未來會(huì)話使用。用戶不需要反復(fù)解釋相同的事情，Agent 會(huì)從之前的交互里學(xué)習(xí)并記住重要信息。

同時(shí)，Claude Code 的子 Agent 記憶機(jī)制也值得一提。在自定義子 Agent 的配置里，可以設(shè)置 memory: user，Agent 會(huì)把學(xué)到的模式寫入 ~/.claude/agent-memory/ /MEMORY.md，下次調(diào)用時(shí)自動(dòng)加載前 200 行。這意味著每個(gè)子 Agent 都可以有自己獨(dú)立的、持續(xù)積累的專項(xiàng)記憶。

更關(guān)鍵的是，這個(gè)系統(tǒng)具有主動(dòng)自我編輯能力。它不僅會(huì)記錄，還會(huì)重寫、去重、甚至剪除互相矛盾的信息，過期且無效的記憶在這里被視為「負(fù)債」而非資產(chǎn)。

Claude Code 的記憶系統(tǒng)設(shè)計(jì)，也側(cè)面反映了：在產(chǎn)品層面，記憶不只是一個(gè) Feature，它是決定用戶是否繼續(xù)使用的核心留存機(jī)制，因?yàn)橛脩粽嬲诖氖且粋€(gè)「會(huì)學(xué)習(xí)」的 Agent。

05權(quán)限系統(tǒng)的設(shè)計(jì)更像是 UX 設(shè)計(jì)，信任是可組合的

權(quán)限與安全問題，是 Agent 走向企業(yè)級(jí)應(yīng)用的前提。

Claude Code 的權(quán)限系統(tǒng)被設(shè)計(jì)為一個(gè)五檔的信任光譜：

• plan：只讀，完全不能寫入，信任級(jí)別最低

• default：編輯和 shell 操作前都需要詢問，標(biāo)準(zhǔn)模式

• acceptEdits：自動(dòng)批準(zhǔn)文件編輯，shell 操作仍需詢問，中等信任

• dontAsk：自動(dòng)批準(zhǔn)白名單內(nèi)的所有操作，高信任

• bypassPermissions：跳過所有檢查，僅限托管組織使用，最高信任

每個(gè)工具調(diào)用都經(jīng)過靜態(tài)分析層的多層白名單校驗(yàn)。bashSecurity.ts 里有 23 項(xiàng)編號(hào)的安全檢查，包括：

• 18 個(gè)被阻止的 Zsh 內(nèi)置命令

• 防御 Zsh equals expansion：=curl 這種寫法可以繞過對 curl 的權(quán)限檢查

• unicode 零寬字符注入

• IFS null-byte 注入

• 一個(gè)在 HackerOne 審查期間發(fā)現(xiàn)的惡意 token 繞過

這種可組合的信任光譜，讓 Claude Code 能夠適應(yīng)完全不同的使用場景：從什么都要確認(rèn)的高度受限企業(yè)環(huán)境，到全速運(yùn)行的個(gè)人開發(fā)環(huán)境。權(quán)限設(shè)計(jì)更像是 UX 設(shè)計(jì)。對于 Agent 產(chǎn)品來說，這也是從 Demo 進(jìn)入企業(yè)生產(chǎn)環(huán)境的「門檻」。

同時(shí)，Claude Code 還有一個(gè)更底層、巧妙的機(jī)制是，API 請求在 JS 層之下做了身份驗(yàn)證。

在 system.ts 文件里，每個(gè) API 請求都包含一個(gè) cch=00000 占位符。在請求真正離開進(jìn)程之前，Bun 的原生 HTTP 棧（用 Zig 編寫，運(yùn)行在 JavaScript 運(yùn)行時(shí)之下）會(huì)把這五個(gè)零替換成一個(gè)計(jì)算出的哈希值。服務(wù)端會(huì)驗(yàn)證這個(gè)哈希，確認(rèn)請求來自真實(shí)的 Claude Code 二進(jìn)制文件，而不是第三方偽造的客戶端。

之所以用等長的占位符，是為了讓替換不改變 Content-Length 頭部，也不需要緩沖區(qū)重新分配，這是一個(gè)很細(xì)節(jié)的工程考量。整個(gè)計(jì)算過程發(fā)生在 JS 層之下，對運(yùn)行在 JS 里的任何代碼都完全不可見。本質(zhì)上是在 HTTP 傳輸層實(shí)現(xiàn)的 API 調(diào)用 DRM。

這也是 Anthropic 此前向 OpenCode 發(fā)律師函背后的技術(shù)基礎(chǔ)。Anthropic 不只是要求第三方工具不要使用他們的 API，二進(jìn)制文件本身通過加密證明了自己的身份。OpenCode 社區(qū)在收到法律通知后不得不訴諸會(huì)話拼接技巧和認(rèn)證插件，原因就在這里。

06多 Agent 編排，從子 Agent 到 Agent Teams

Claude Code 的多 Agent 編排采用了橫向擴(kuò)展的方式，分為兩層。

第一層：Sub-Agent

子 Agent 以獨(dú)立進(jìn)程方式運(yùn)行，有自己的 TAOR 循環(huán)、自己的 Context 預(yù)算、自己的 maxTurns 上限、自己的記憶。任務(wù)完成后，只把摘要返回給主 Agent，主 Agent 的 Context 完全不受影響。

Claude Code 內(nèi)置了三種預(yù)設(shè)子 Agent，各有分工：

• Explore：用 Haiku 模型（速度快、成本低），只有只讀工具（Read、Grep、Glob），專門做文件發(fā)現(xiàn)和代碼庫探索

• Plan：繼承主 Agent 的模型，只有只讀工具，專門做代碼庫研究和規(guī)劃前的信息收集

• General-purpose：繼承主 Agent 的模型，配備全套工具，處理復(fù)雜的多步驟操作

自定義子 Agent 通過 .md 文件加 YAML frontmatter 定義，可以指定模型（sonnet/opus/haiku/inherit）、權(quán)限模式、maxTurns、可用工具白名單、禁用工具黑名單，甚至可以預(yù)加載特定的 Skills。存儲(chǔ)位置有三種：~/.claude/agents/（用戶級(jí)）、.claude/agents/（項(xiàng)目級(jí)），或通過 --agents CLI 參數(shù)指定。

子 Agent 還支持前臺(tái)和后臺(tái)兩種執(zhí)行模式。前臺(tái)模式會(huì)阻塞主對話，權(quán)限詢問和問題會(huì)透傳給用戶；后臺(tái)模式則在用戶繼續(xù)工作的同時(shí)并發(fā)運(yùn)行，權(quán)限在啟動(dòng)前就預(yù)先收集，如果遇到?jīng)]有預(yù)批準(zhǔn)的權(quán)限請求，工具調(diào)用直接失敗，Agent 繼續(xù)運(yùn)行。按 Ctrl+B 可以把正在運(yùn)行的前臺(tái) Agent 切換到后臺(tái)。

第二層：Agent Teams

這不再是主 Agent 派遣子 Agent 的主從關(guān)系，而是完全獨(dú)立的 Claude Code 實(shí)例通過共享文件系統(tǒng)協(xié)調(diào)任務(wù)。兩者區(qū)別：

Agent Teams 的協(xié)調(diào)機(jī)制包括：Shared Task List（所有 Agent 可見任務(wù)狀態(tài)，完成當(dāng)前任務(wù)后自主認(rèn)領(lǐng)下一個(gè)未分配任務(wù)）、單播 Message（發(fā)給特定 Teammate）、Broadcast（發(fā)給所有 Teammate，注意成本隨團(tuán)隊(duì)規(guī)模線性增長）、以及 Automatic Idle Notification（Teammate 完成任務(wù)停止時(shí)自動(dòng)通知 Lead）。

同時(shí)，還有兩個(gè)專門針對團(tuán)隊(duì)的質(zhì)量門控 Hook：TeammateIdle（Teammate 即將進(jìn)入空閑時(shí)觸發(fā)，返回 exit code 2 可以發(fā)送反饋?zhàn)屗^續(xù)工作）和 TaskCompleted（任務(wù)即將被標(biāo)記完成時(shí)觸發(fā)，返回 exit code 2 可以阻止完成并要求修復(fù)）。

但 Agent Teams 目前還是實(shí)驗(yàn)性功能，需要通過 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 環(huán)境變量或 settings.json 啟用。

07還沒發(fā)布的 KAIROS，一個(gè) Always-On Agent

在這次泄露中，有一個(gè) Claude Code 還未發(fā)布的功能 KAIROS，可以在后臺(tái)持續(xù)運(yùn)行的 Agent。

根據(jù) main.tsx 里的代碼路徑，KAIROS 是一個(gè)功能門控的未發(fā)布模式，包含以下特征：

• /dream 技能，用于夜間記憶蒸餾（nightly memory distillation）

• 每日 append-only 日志

• GitHub Webhook 訂閱

• 后臺(tái) Daemon 工作進(jìn)程

• 每 5 分鐘的 Cron 調(diào)度刷新

把這些特征拼在一起，是一個(gè)完全不同的產(chǎn)品形態(tài)：常駐后臺(tái)、持續(xù)學(xué)習(xí)、主動(dòng)感知代碼庫變化的 Autonomous Agent。不是你召喚它，它來幫你，而是它一直在，主動(dòng)為你工作。

現(xiàn)有的 Claude Code 是一個(gè)召喚式 Agent：你打開終端，它來幫你，你關(guān)掉終端，它就停了。但 KAIROS 描繪的是下一代形態(tài)：Agent 在后臺(tái)持續(xù)運(yùn)行，通過 GitHub Webhook 感知代碼庫的變化，每天晚上做記憶蒸餾，把當(dāng)天的工作模式和項(xiàng)目狀態(tài)壓縮進(jìn)長期記憶，第二天一早已經(jīng)「預(yù)熱」好了。

雖然不知道 Anthropic 內(nèi)部對 KAIROS 的開發(fā)已經(jīng)進(jìn)展到了什么程度。但 KAIROS 的泄露說明了，Claude Code 的產(chǎn)品野心已經(jīng)遠(yuǎn)超「LLM + 命令行包裝」，朝著「終端操作系統(tǒng)級(jí) Agent」方向前進(jìn)。

08一些彩蛋：Anti-Distillation 機(jī)制、Undercover Mode

此外，在這次泄露的源碼里，還有一些非常有爭議性的工程決策，被扒了出來。

Anti-Distillation 機(jī)制

claude.ts 第 301-313 行有一個(gè)叫 ANTI_DISTILLATION_CC 的標(biāo)志。當(dāng)它開啟時(shí)，Claude Code 會(huì)在 API 請求里攜帶 anti_distillation: ['fake_tools'] 參數(shù)，服務(wù)端會(huì)向系統(tǒng)提示中靜默注入虛假的工具定義。

邏輯很直接：如果有人在錄制 Claude Code 的 API 流量來訓(xùn)練競品模型，這些假工具會(huì)污染訓(xùn)練數(shù)據(jù)。這個(gè)機(jī)制通過 GrowthBook 功能標(biāo)志 tengu_anti_distill_fake_tool_injection 控制，只對第一方 CLI 會(huì)話激活。

還有第二層機(jī)制在 betas.ts 第 279-298 行：服務(wù)端 connector-text 摘要。啟用時(shí)，API 會(huì)緩沖 Assistant 在工具調(diào)用之間的推理文本，對其摘要后返回帶加密簽名的版本。在后續(xù)輪次里，原始文本可以從簽名恢復(fù)。錄制 API 流量的人只能拿到摘要，拿不到完整的推理鏈。

Undercover Mode

undercover.ts 文件大約 90 行，實(shí)現(xiàn)了一個(gè)單向門：當(dāng) Claude Code 在非 Anthropic 內(nèi)部倉庫里使用時(shí)，它會(huì)指示模型永遠(yuǎn)不提及內(nèi)部代號(hào)（比如 Capybara、Tengu）、內(nèi)部 Slack 頻道、倉庫名稱，甚至不提及 Claude Code 這個(gè)名字本身。

第 15 行有一條注釋寫得很清楚：

There is NO force-OFF. This guards against model codename leaks.

你可以用 CLAUDE_CODE_UNDERCOVER=1 強(qiáng)制開啟，但沒有辦法強(qiáng)制關(guān)閉。在外部構(gòu)建里，整個(gè)函數(shù)會(huì)被死代碼消除為平凡返回。這是一個(gè)單向門。

這意味著，Anthropic 員工在開源項(xiàng)目里用 Claude Code 生成的 commit 和 PR，將沒有任何 AI 參與的標(biāo)記。如何在商業(yè)防御需求與 AI 透明度倫理之間做權(quán)衡，也是值得思考的事情。

轉(zhuǎn)載原創(chuàng)文章請?zhí)砑游⑿牛篺ounderparker