文章對 2026 年 3 月 31 日洩露的 Claude Code（v2.1.88）原始碼進行了深度技術分析，將其視為一份揭示前沿 AI Agent 工程化架構的寶貴案例。

文章作者、來源：Max

今天（2026年3月31日），Anthropic 因打包流程的低級失誤，再次將其最新版 Claude Code（v2.1.88）的完整前端與客戶端原始碼暴露於 npm 倉庫中。

網友發布了一個未被移除的 cli.js.map 檔案，直接還原出約 1900 個檔案、超過 51 萬行的原生 TypeScript 代碼。

對於 Anthropic 而言，這是繼幾天前 Mythos 模型文件外洩後的又一次嚴重 OpSec 事故。

But for developers and industry researchers in the entire large model application layer, this source code is a fully disclosed, highly valuable whitepaper on cutting-edge AI Agent engineering architecture.

拋開合規與洩露事件的爭議，我花了一些時間在本地對這份源碼進行了深度梳理。

如果將其視為一個生產級 AI 編程助手架構的案例，而非八卦，其中包含大量突破常規思維的工程決策。

以下是我以客觀視角，對 Claude Code 底層架構、調度機制、記憶系統及安全策略的詳細技術拆解。

文章較長，適合從事 AI Infra、Agent 開發以及對大模型應用層架構感興趣的從業者閱讀。

PART.01 不只是一個 CLI 工具

從目錄結構（src/ 下約 40 個一級模組）可以看出，Claude Code 的複雜度遠超目前市面上開源的常規單體 Agent。

它的技術棧選型非常務實且注重終端交互體驗：

語言為 TypeScript，執行時選擇了性能更激進的 Bun，CLI 框架使用 Commander，而終端渲染層則出人意料地使用了 React + Ink。

為什麼一個命令行工具要用 React？

源碼中的 screens/REPL.tsx（高達 5005 行）給出了答案。

在大模型流式輸出（Streaming）和多工具併發執行的場景下，終端 UI 的狀態管理變得極其複雜（例如同時渲染思考過程、工具調用進度條、代碼 Diff 預覽等）。

採用聲明式的 React 配合極簡的 Zustand 風格自定義 Store（state/store.ts），是應對這種高頻局部刷新的最佳工程實踐。

在運行模式上，系統被嚴密地劃分為兩種形態：

互動式 REPL 模式：透過 Ink 驅動前端終端 UI，主要面向人類開發者。

無頭/SDK 模式（QueryEngine 類）：完全剝離 UI，支援 JSON 流式輸出。這為後續將其作為底層引擎嵌入 IDE（如類似 Cursor 的形態）或 CI/CD 流程中埋下了伏筆。

The system startup process has also been optimised for maximum concurrency.

在 main.tsx 中，配置讀取（MDM Settings）和 Keychain 密鑰預取等 I/O 密集型操作被置於子進程中，與主模塊 ~135ms 的加載過程並行執行，這種對啟動延遲的毫秒級苛求，貫穿了整個代碼庫。

PART.02 提示詞緩存（Prompt Cache）工程學

這是整個原始碼中最具技術含量的部分，也是拉開 Claude Code 與普通套殼應用體驗差距的核心壁壘。

目前 Agent 工具在處理長上下文時，往往還在簡單粗暴地拼接 System Prompt 和歷史對話。

而在 Claude Code 的 services/api/claude.ts（長達 3419 行的核心交互模塊）中，提示詞組裝被做到了字節級的精打細算。

众所周知，Anthropic 的 Prompt Cache 機制採用前綴匹配（Prefix Matching）。

為最大化快取命中率，Claude Code 設計了嚴密的分段快取架構：

靜態段（全域可快取）：由 systemPromptSection() 生成，包含模型身分介紹（"You are Claude Code..."）、系統級安全規則、程式碼風格限制、工具使用基礎指南等。這部分在整個會話生命週期內幾乎不變。

動態分界線：在原始碼中硬編碼了一個特殊標記 SYSTEM_PROMPT_DYNAMIC_BOUNDARY。

動態段（會話級快取／不快取）：包含目前工作目錄資訊（CWD）、Git 狀態、MCP（Model Context Protocol）指令、使用者設定等高頻變化的資料。

並且為防止 Prompt 發生微小變化導致快取穿透，系統進行了大量看似繁瑣的兜底工作：

Deterministic sorting: The tool descriptions passed to the large model are strictly sorted alphabetically by the built-in tool prefix + MCP tool suffix.
哈希路徑映射：配置文件的路徑不使用隨機 UUID，而是使用基於內容的哈希值，避免每次注入路徑不同而破壞快取。
狀態外置：連當前可用的 Agent 列表，也被從工具描述中剝離，轉移到了訊息附件（Attachments）中。據原始碼註釋透露，僅這一項改動就減少了約 10.2% 的 Cache Creation Tokens 消耗。

這一切都在說明一個行業現狀：現階段優秀的 AI 應用層開發，本質上就是在貪婪且精細地壓榨 API 緩存系統的價值。

PART.03 工具與流式並行執行

Claude Code 內建超過 40 種工具（涵蓋檔案讀寫、Bash 執行、網路抓取等），其工具系統架構採用高度模組化的工廠模式（Factory Pattern）。

每個工具繼承自基礎的 Tool 接口，必須實現如 checkPermissions()、validateInput() 和 isConcurrencySafe()（是否併發安全）等方法。

按需加載的 ToolSearch 機制：當工具數量超過某個閾值時，若將所有工具的描述都塞進 Prompt，Token 成本將不可接受。

The source code demonstrates an elegant strategy called ToolSearch: non-core tools (such as certain specific analysis plugins) are marked with defer_loading: true.

模型在當前 Prompt 中看不到這些工具的具體定義，只知道有一個 ToolSearch 工具。當模型認為自己需要額外能力時，必須先調用 ToolSearch 去動態加載對應的工具配置。

StreamingToolExecutor（流式工具執行器）：為提升執行效率，系統支援工具的併發調用。

協調器（toolOrchestration.ts）會將大模型返回的工具調用請求分區為並發批次和串行批次。

並行安全的工具（例如同時讀取多個不相關的檔案、並發發起網路搜尋）會被並行觸發；而非並行安全的工具（例如先後修改同一個程式碼檔案）則會嚴格串行執行。

工具處理大結果集（例如全盤 Grep 搜尋）時設有 maxResultSizeChars 預算，超過預算的內容會被直接截斷並持久化至本地暫存檔案，僅向 LLM 傳回預覽摘要，以防止過大的結果填滿上下文視窗。

PART.04 解決上下文污染的 Fork 機制

目前的單體 Agent 存在一個致命缺陷：

在執行複雜任務（例如跨檔案排查 Bug）時，模型可能會反覆讀取錯誤的檔案、嘗試錯誤的指令，這些試錯過程會產生大量的垃圾上下文，迅速污染主對話，導致模型在後續推理中精神分裂或遺忘初始目標。

Claude Code 引入了複雜的協調器模式（Coordinator Mode）和 Fork Subagent（派生子代理）機制來解決這一問題。

在環境變數啟用協調器模式後，系統會被重構為 Coordinator-Workers 架構：

協調者（Coordinator）：已撤銷直接操作文件的權限，僅保留 Agent（派生子代理）、SendMessage 和 TaskStop 三個工具。其唯一工作是規劃工作流程（Research → Synthesis → Implementation → Verification）。
Workers（執行者）：攜帶具體的工具描述被派生出來。

最值得稱道的是其 Fork 繼承機制。

當需要進行大範圍程式碼探索時，Coordinator 會 Fork 出一個 Explore Agent。

這個子 Agent 會繼承父對話的快取（共用 Prompt Cache 以節省成本），但其後續的探索動作和讀取的垃圾檔案，完全在其隔離的上下文中進行。

探索結束後，子 Agent 只需透過特定的 XML 格式，將提煉好的關鍵結論（Synthesis）傳回給 Coordinator 的主上下文即可。

這種用完即毀、只留結論的設計，是目前業界處理複雜多 Agent 長文本協同的最佳實踐之一。

PART.05 突破單體的 Agent Swarm 并發機制

除了用於解決上下文污染的串行 Fork 機制，原始碼還展示了更具野心的併發多 Agent 架構——Swarm（Teammate）叢集。

這部分邏輯主要隱藏在 utils/swarm/ 和 tasks/ 目錄中。

系統支援一種名為 in_process_teammate 的任務類型。

在這種架構下，主進程可以並行喚醒多個 Agent（被稱為 Teammate）同時執行不同的任務。

但在終端 CLI 環境中運行多 Agent 併發，會面臨兩個致命的工程挑戰：權限彈窗衝突和 UI 渲染混亂。

Anthropic 的解決方案極為優雅：

Leader 權限橋接（permissionSync.ts）：所有的 Teammate 子進程均不允許直接向用戶彈窗請求權限。它們會透過內部通道將權限請求「橋接」至主進程的 Leader Agent，由 Leader 統一在主終端進行安全攔截與用戶確認。
終端佈局自動化：為讓用戶能清晰監控多個並行 Agent 的工作狀態，原始碼直接整合了 iTerm2 和 Terminal.app 的 AppleScript 控制指令。當派生新的 Teammate 時，系統會自動在終端中切分窗格（Split Pane），為每個子 Agent 分配獨立的輸出視窗。

這標誌著 AI 正從「單體思考」正式向「集群並發協作」演進。

PART.06 Dream（夢境）記憶架構

在 RAG（檢索增強生成）大行其道的今天，幾乎所有的 AI 產品都在整合向量資料庫（Vector DB）。

但令人意外的是，Claude Code 的記憶系統（memdir/ 模組）極其復古且務實，它完全基於本地檔案系統。

其架構由一個核心的 MEMORY.md（作為高層索引，限制在最多 200 行/25KB 以內）和多個基於 Frontmatter 格式的主題文件組成。

記憶被精細劃分為 User、Feedback、Project、Reference 四大類。

更有趣的是隱藏在原始碼中的 KAIROS 助手模式。

這是一個尚未正式發布的長期運行（Daemon）模式。

在 KAIROS 模式下，記憶系統不再是簡單的索引更新，而是採用了類似人類日誌的追加模式（寫入 logs/YYYY/MM/YYYY-MM-DD.md）。

在夜間或閒置時間，後台會喚醒一個名為 Dream（做夢）的離線任務 Agent。

該 Agent 的職責是對白天的流水賬日誌進行總結、提煉，並將其提取固化至結構化的長期主題文件中。

這種從短期日誌到長期記憶的異步整合機制，不僅繞過了向量檢索的召回率痛點，還代表了端側 AI 助理向永遠在線、持續學習演進的明確方向。

PART.07 權限收斂與安全

Granting AI permission to execute local Shell commands and modify files is a double-edged sword.

頻繁彈窗要求用戶確認會徹底破壞自動化體驗，而不加限制的自動執行則可能導致系統崩潰（如誤執行 rm -rf）。

Claude Code 採用了一套多層權限收斂架構：

從基於 @anthropic-ai/sandbox-runtime 的底層檔案/網路沙箱，到針對特定危險操作（如 git push --force）的硬編碼攔截，再到工具級別的校驗。

但最引人注目的是其名為 Auto Mode Classifier (yoloClassifier.ts) 的組件。

當用戶開啟自動模式時，系統並未使用僵化的正則表達式來評估命令的危險性，而是採用了一個側查詢（Side Query）機制。

系統會在後台靜默調用一個更小、更便宜的 LLM，將當前對話的精簡轉錄（Transcript）和即將執行的 Bash 命令拋給它，讓這個側邊模型輸出 Allow 或 Deny 的決策。

此外，系統內部還有一個基於閾值的 Denial Tracking（拒絕追蹤），當自動工具被頻繁拒絕時，系統會優雅降級，退回到 Prompting 模式請求人類介入。

這種使用小 AI 監管大 AI 的動態權限系統，比傳統的靜態攔截規則靈活得多。

PART.08 一些小彩蛋

最後，源碼中大量存在的 Feature Flags（如 VOICE_MODE、SSH_REMOTE 等）和 process.env.USER_TYPE === 'ant' 的環境變數判斷，向我們展示了大廠在內部測試和外部發布時的雙重標準。

對於 Anthropic 內部員工（Ant-only），系統注入的代碼規範極其嚴厲甚至偏執：

不要擅自添加功能，如果要求沒提就不要重構，三行相似的代碼比過早的抽象更好，預設不寫任何註釋，除非 WHY 極不明顯，測試失敗了必須如實報告。

至於外部公開構建，系統提示詞則溫和得多：直接切入主題，嘗試最簡單的方法，盡量簡明扼要。

這種反差說明大模型的行為邊界在很大程度上取決於硬編碼的指令傾向。

值得注意的是，代碼裡包含了兩個有趣的模組。

臥底模式（Undercover Mode）：

這是一個備受安全社區爭議的功能。

針對員工在開源或公共倉庫工作的場景，系統預設啟用且無法強制關閉此模式。此模式會在 Prompt 中明確要求模型 Do not blow your cover（不要暴露身份），並強制移除所有由 AI 生成的免責聲明或代號痕跡。

從公關角度來看，這或許顯得缺乏透明度，但從側面印證了廠商對模型角色扮演和輸出干預的絕對控制力。

寶貝系統（電子寵物）彩蛋：

源碼中包含了一個隱藏的電子寵物系統（生成鴨子、貓頭鷹等）。

為確保寵物生成的隨機性與確定性，工程師使用用戶的 ID 搭配 Mulberry32 偽隨機數生成演算法。

TypeScript

18 種物種：duck、goose、blob、cat、dragon、octopus、owl、penguin、...

5 種稀有度：common（60%）、uncommon（25%）、rare（10%）、epic（4%）、legendary（1%）

// 屬性：DEBUGGING、PATIENCE、CHAOS、WISDOM、SNARK

// 配件：crown、tophat、propeller、halo、wizard、beanie、tinyduck

// 特殊：1% 概率 shiny

最搞笑的細節是，某種動物物種的英文名稱恰好與 Anthropic 極度機密的內部模型代號相同（也許是前兩天洩露的最強 Claude 卡皮巴拉）。

為了繞過合規程式碼掃描器的禁用詞檢測，工程師竟然使用了 String.fromCharCode() 來動態拼裝這個單詞。

這種充滿幽默感的極客做法，在極其嚴肅的基礎設施代碼中顯得別具一格。

PART.09 我們能學到什麼？

在短時間內連續遭遇核心模型技術文檔和核心應用源碼的洩露，Anthropic 在內部流程管控上的確需要做深刻檢討。但技術無罪，這份 51 萬行的代碼對於行業而言是一份極好的教材。

From the underlying design of Claude Code, it is clear that the era of starting businesses at the large model application layer by merely piecing together prompts, stacking vector databases, and wrapping a simple loop has ended.

真正的壁壘，建立在對 Token 成本的極致抠門（Prompt Cache 優化）、對多狀態機協同的流式調度（Coordinator 與 Fork 機制）、對用戶意圖容錯與安全干預的平衡（YOLO Classifier），以及對宿主操作系統深度的文件流集成上。

目前在 GitHub 上 fork 這些原始碼的倉庫正面臨隨時被 DMCA 請求下架的風險。

但無論如何，Claude Code 展示出的工程化水平，已經為 2026 年的 AI 助理產品樹立了一個全新的技術標杆。

Professionals should seize this opportunity to carefully review and adopt the engineering best practices involved.