小編精選 - 技術文章翻譯 · 04月14日

從 Claude Code 原始碼外洩學到的 10 種測試夾具模式 ── 50 萬行 TypeScript 所揭示的設計思想

前言：3月31日發生了什麼事

2026 年 3 月 31 日未明，Anthropic 在發布的 Claude Code v2.1.88 npm 套件中，誤附帶了一個本應被排除的 59.8MB 原始映射檔（.map）。該檔案使得約 512,000 行、1,906 個檔案的 TypeScript 原始程式碼可被還原並公開。業界稱之為「2026 年 Claude Code 大洩露（The Great Claude Code Leak of 2026）」，並且徹底改寫了之後 AI 智能代理（agent）開發的常識。

追溯事件時序非常驚人：約 04:00 UTC 發佈到 npm 的 v2.1.88，僅 23 分鐘後（04:23 UTC），Solayer Labs 實習生 Chaofan Shou（@Fried_rice）在推特上指出不尋常的巨型 .map 檔案。數小時內即可確認 R2 儲存桶上的來源映射也被設為公開，社群開始鏡像與散佈。上午期間主要的複製儲存庫已出現在 GitHub，並以驚人的速度獲得 star。當 Anthropic 法務團隊啟動 DMCA 刪除請求時，程式碼已透過 IPFS 與各式分散式鏡像廣泛散佈，處於「已放生」狀態。Anthropic 隨後在 4 月 1 日發表簡短聲明，承認流出事實，並呼籲社群避免逆向工程與再散佈。

事故原因並非單一的人為疏失，而是兩項缺陷的不幸疊合。其一是 .npmignore 中遺漏排除 .map 的簡單設定錯誤；其二是 Bun 執行環境的一個已知錯誤（issue #28001，於洩露前 20 日的 3 月 11 日已通報），文件上說「生產構建不會發送來源映射」，實際卻會發送。Anthropic 在 2025 年底收購了 Bun，Claude Code 基於 Bun 運行——自家執行環境的 bug 卻被自家旗艦產品踩到，屬於結構上可能發生的事故。

流出的影響自三個方向擴散。開放原始碼社群獲得了「生產級 AI 代理內部結構」的設計藍圖；競爭對手可以在一夜之間看見與自家產品的設計差異，且隨著下文會述及的「反蒸餾機制」被揭露，顯示其架構在透過 API 流量模仿方面並不容易直接複製；Anthropic 本身短期遭遇信任與法律成本，但中長期上其主張「哈內斯（控制層）才是本體而非模型」反而被洩露意外驗證。

分析流出程式碼的開發者與研究者一致指出：「Claude Code 的本質不在模型表現，而在哈內斯（控制層）的設計。」本文將以 Ken Huang 等人整理的 10 種哈內斯模式為主軸，深入剖析流出程式碼揭露的設計思想。

為何 Claude Code 採閉源（closed source）

在進入主題前，有幾個前提要先確認：為何 Anthropic 要以閉源方式提供商用 AI 代理？為何即便哈內斯模式公開，其競爭優勢仍不會被輕易動搖？

解讀 Anthropic 策略的關鍵在於「模型可交換、哈內斯是經驗結晶」的二分法。對 Anthropic 而言，模型本身雖為其核心研究成果，但既然以 API 形式公開，就可被外界存取。相對地，哈內斯是從數十萬用戶的龐大對話日誌、邊緣情況與失敗案例中累積的運營知識團塊；光看程式碼無法複製其包含的大量卑微知識（tacit knowledge）。許多讀過流出程式碼的研究者反覆指出：「程式碼可以讀，但為何某個參數是該值並未寫在程式裡。」

即便哈內斯公開，為何競爭優勢仍難以動搖？原因可整理為三點。第一，哈內斯與模型會協同演化，Anthropic 對自家模型特性有深入認知，因此能在內部對哈內斯進行精細調校。第二，哈內斯參數通常需要「多年運營」才能看到適切值，數日到數週的逆向工程難以得出正確設定。第三，Anthropic 控握伺服端的模型本體、API 閘道與 feature-flag 控制基礎設施，單看客戶端程式碼無法重現其閉環運營。

在上述前提下，下面看 512,000 行 TypeScript 具體實作了什麼。

內部架構概觀

Claude Code 的整體可視為三層結構：

層	角色	主要技術
UI 層	終端呈現、使用者互動	React + Ink（Int32Array ASCII pool、位元遮罩式的遊戲引擎風格技巧）
哈內斯層	工具執行、權限管理、上下文控制、狀態管理	Zod schema、查詢引擎、權限流水線
模型層	推論、文字生成	Claude API（Sonnet/Opus 切換、系統級提示快取優化）

哈內斯層佔了大部分（約 512,000 行），包含 19 個需權限的工具、6 種 MCP 傳輸（Stdio、SSE、HTTP、WebSocket、SDK、ClaudeAiProxy）、44 個尚未上線的 feature flag，以及 46,000 行的上下文壓縮引擎。UI 層看起來對終端應用非常繁複，實際上是為了支持大量差分渲染、工具執行日誌與長時間會話的效能優化。哈內斯層明確分為「工具、權限、查詢引擎、上下文管理、記憶體」五個區域，且各區域設計為可獨立測試的結構。

哈內斯模式 10 選

以下為本文核心：Ken Huang（DistributedApps.ai）團隊對流出程式碼的系統化分析，歸納出生產級 AI 代理共有的 10 種哈內斯模式。對每個模式說明流出程式碼中的實作、設計意圖，以及如何應用到自己的專案。

模式 1：哈內斯範式 — 模型與控制的分離

最根本的一個模式：設計哲學為「生產級 AI 的挑戰不在模型，而在哈內斯」。哈內斯解決的五個問題：

動作空間約束（透過工具限制可執行的行為）
對話狀態管理
以權限保證安全性
適當的故障處理
資源使用最佳化

這五點之所以重要，是因為單靠模型的「更聰明」無法解決。例如就算推論能力提升，仍無法靠模型本身去保證「不會寫入禁止目錄的檔案」或「不會每天浪費 25 萬次 API 呼叫」。模型是統計性生成回答的機制，哈內斯則是把「看起來合理但危險／低效率」的輸出在執行前過濾掉的機制。

個人專案的簡易應用：在 CLAUDE.md 明確定義工具使用條件與禁止事項。建議步驟：先列出「不想交由模型判斷的領域」（破壞性指令、機密檔案、對外 API 的寫入等），再把這些寫成規則放入 CLAUDE.md，最後在 CLI 的 --allowed-tools 或 hooks 中強制執行。把「給模型的提示（prompt）」與「模型行為控制（哈內斯）」分離的意識，對個人開發者也會顯著提升品質。

模式 2：工具契約（Tool Contract）— 統一介面的力量

所有工具都實作統一介面：ID、執行邏輯、驗證、權限、呈現五個面向，並以 Zod schema 做型別安全定義，buildTool 工廠函式套用保守的預設值。流出程式碼中超過 40 個工具模組（Bash、Read、Edit、Write、Glob、Grep、WebFetch 等）皆以相同結構實作。

示意性偽程式如下（以縮排程式區塊表示）：

const BashTool = buildTool({
  name: "Bash",
  description: "Execute a shell command",
  inputSchema: z.object({
    command: z.string(),
    timeout: z.number().optional(),
    run_in_background: z.boolean().optional(),
  }),
  behaviors: {
    isConcurrencySafe: false, // 預設採安全側
    isReadOnly: false,
    requiresPermission: true,
  },
  permissionCheck: async (input, ctx) => {
    // 23 項 Bash 安全檢查
    return canUseTool("Bash", input, ctx);
  },
  execute: async (input, ctx) => {
    // 執行邏輯
  },
  render: (result) => { /* Ink 繪製 */ },
});

設計核心在於讓哈內斯即使不瞭解工具的內部實作，也能推論其行為。isConcurrencySafe 為 false 的工具不允許並行執行，isReadOnly 為 true 的工具可在 dry-run 時自動通過。哈內斯端的通用邏輯即可處理這些判斷，讓新增工具的成本低且不會破壞既有安全保證。

應用建議：每次定義自訂 Skill 或斜線指令時，養成以統一格式記錄「輸入 schema、輸出格式、副作用有無、所需權限、失敗時行為」五項，能擬似實作此模式。我個人習慣在 .claude/commands/ 下以 Markdown + YAML front-matter 記 allowed-tools 與 description。

模式 3：查詢引擎（Query Engine）— 會話生命週期的中央控制

查詢引擎是管理使用者、語言模型與工具執行環境之間會話生命週期的中央協調器。流出程式碼中該模組就有數萬行，可謂 Claude Code 的心臟。

值得注意的是採用了「continue sites」模式：在工具執行迴圈中設置多個脫離點，當錯誤發生時分段嘗試回復策略，例如：

上下文折疊（將舊資訊摘要／壓縮）
反應式壓縮（對突增的 token 消耗作處理）
token 升階（切換到更大的上下文窗口）
模型升階（Sonnet → Opus）
安全停止（在重複失敗時強制中斷）

流出程式碼中留有註解與實際數據，例如「在 1,279 個會話中出現超過 50 次連續失敗，造成每天約 25 萬次 API 呼叫浪費」，並因此把 MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3 這樣的修正寫入。這正是模式 1 所說「模型本身無法解決」的典型例子，也是唯有大規模運營才會獲得的經驗痕跡。

應用建議：在 .claude/rules/ 中把回復流程（例如「失敗 3 次就暫停並重新規劃」「錯誤不要掩蓋，要查根本原因」）寫成明確的 fallback 規則；在 CLAUDE.md 的「驗證」與「上下文壓力時的行為規範」段落簡單實作即能獲得類似思維。

模式 4：權限系統 — 多層防禦

安全性不是單一檢查點，而是由流水線式的多層評估構成。中央 gatekeeper 函式 canUseTool 在每次工具執行前評估下列管線：

Allow / Deny / Ask 清單（設定檔中的靜態規則）
工具專屬檢查（工具定義的制約，例如 Bash 的 23 項檢查）
分類器的動態判定（Prompt injection 偵測、機密資訊偵測等）
使用者批准（最終閘道，交給 hooks 或 permission prompt）
稽核日誌（記錄批准或拒絕）

僅 Bash 執行就會跑 23 項安全檢查，涵蓋 Zsh builtin 的封鎖、等號展開防護、零寬度空白注入防護、透過環境變數間接執行的檢測、相對路徑遍歷偵測等。這些檢查看來是基於過去事件與紅隊測試所設計，程式碼本身就是安全審查的產物。

應用建議：canUseTool 的檢查順序採「早期拒絕、晚期授權」，即先把明顯危險（Deny）過濾掉，再允許明顯安全（Allow），僅把有疑義的中間情況交給人類或 LLM 做分類判斷。個人專案可從 settings.json 的 permissions 欄位寫入 Deny / Allow 清單開始。

模式 5：上下文熵（Context Entropy）管理 — 三層記憶體

控制「記得什麼、忘記什麼」的三層記憶體架構。流出程式碼中特別被肯定的是把 MEMORY.md 視為「資料的指標（pointer index）而非資料本身」的設計：每行約 150 字元的輕量指標常駐於上下文，實際的知識分散成專題檔案，只有在需要時才載入，避免耗盡上下文視窗。

三層說明：

層	角色	特徵
短期上下文	當前會話輪次	管理於活動視窗內
會話等級（中期）	會話內的持久化學習	索引檔 + 專題檔
長期記憶	跨會話知識	檔案為基底，當作 hint（非絕對事實）

所謂的「嚴格寫入紀律（Strict Write Discipline）」原則：只有在寫入成功被確認後才更新索引，並把保存的知識視為提示而非絕對事實。原因在於若直接把 LLM 生成的摘要固定為事實（authoritative），錯誤（hallucination）就會被永續化。流出程式碼中每次寫入記憶都會附加版本號與信賴度分數，後續會話會把低信賴度的記憶當參考而非依賴。

CLAUDE.md 的 memories/ 結構（例如 preferences、decisions、context-log、case-judgment-framework 等）屬於長期層。實作建議是：「常駐參考內容上限為數百字，其他內容採按需載入」的分工。

模式 6：提示（prompt）快取最佳化 — 靜態 / 動態分離

SYSTEM_PROMPT_DYNAMIC_BOUNDARY 模式把 prompt 分為靜態命令（跨會話不變）與動態上下文（會話間變化）兩部分。Anthropic API 的 prompt cache 以「從開頭比對一致範圍」來做快取，因此把不常變的靜態部分放前面、把動態部分放後面可以最大化快取命中率。

流出程式碼追蹤了 14 種會破壞快取的因素（cache break vectors），例如時間戳（timestamp）混入、使用者名稱插入、亂數種子注入等都是失敗範例。有趣的是他們是刻意設計快取邊界：把系統 prompt 主體、工具定義與專案上下文（CLAUDE.md）歸為靜態領域，僅把使用者發話與工具執行結果放為動態領域，藉此大幅降低每次會話的成本。

應用建議：編寫 CLAUDE.md 時，把「很少改變的基本規則」放在檔案上方、把專案特殊或動態資訊放下方；避免在靜態區混入時間、分支名稱等每次都會變的資訊，就能在個人層級看到顯著的成本下降。

模式 7：反蒸餾（Anti-distillation）機制 — 智財防護

實作了兩種針對競爭者透過 API 流量蒐集與訓練的防護機制。

第一種是 fake_tools 注入。當 ANTI_DISTILLATION_CC flag 生效時，API 請求帶上 anti_distillation: ['fake_tools'] 欄位，伺服器端會在系統 prompt 中注入誘餌（decoy）工具定義。若競爭者蒐集這些 API 流量當作訓練資料，就會學到錯誤的工具架構，造成抽取式模型效能下降。此機制由 GrowthBook flag tengu_anti_distill_fake_tool_injection 控制，僅對 first-party CLI 會話開放。

第二種是透過 CONNECTOR_TEXT 做助理文本的摘要：在工具呼叫之間的文字以帶有簽章的摘要形式回傳，流量記錄器只能獲得摘要而非完整推論鏈，防止競爭者重建連續性的思考流程。

不過如 Alex Kim 所指，透過中間人代理（MITM）移除 anti_distillation 欄位或設定環境變數 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 可繞過這些防護；對於認真要蒸餾的對手而言，大約一小時就能突破。這符合安全設計的一般原則：並非封堵所有繞道，而是把「隨意模仿的成本提高」就有實際價值。

模式 8：挫折偵測（Frustration Detection）— 使用者狀態的推論

用正規表達式檢測使用者挫折的機制，例如快速比對「wtf」「awful」「so frustrating」「this is garbage」等字串，能以極低成本比起用模型推論來得快速又決定性。這延伸自模式 7 的「把能在模型外做的推論放到外面去」原則：便宜、快、決定性的處理就不該交給 LLM。

作為哈內斯模式，該設計是「在把資料交給模型之前先推斷使用者狀態，並根據狀態切換回應策略」。偵測出的挫折分數會作為內部旗標，影響下一輪 prompt（例如改用更細緻的說明或加入更多驗證步驟）。應用上可以在自己的 Skill 中用 hooks 捕捉「使用者反覆問同一問題」或「負向詞彙頻率上升」等信號，進而變更互動策略。

模式 9：臥底模式（Undercover Mode）— 依賴上下文的行為控制

undercover.ts 是在非內部 repo 運行時，會自動移除任何與 Anthropic 有關的字串（代號如 Capybara、Tengu、Slack 頻道名、甚至「Claude Code」字樣），會從 commit message 或 PR 中排除相關痕跡。

特別的是存在「不可強制關閉（NO force-OFF）」保護：外部 build 無法停用此功能，藉此保護 Anthropic 員工在對外貢獻時不會在紀錄中留下 AI 介入的痕跡。此功能在社群中引發透明度與倫理的討論，但其實質是一種「環境適配」模式：根據執行環境動態切換代理行為。

個人層級的應用範例則是依 repo 切換是否在 commit 訊息尾端加入 Co-Authored-By，無關倫理論戰，環境依賴行為切換本身是哈內斯設計的重要元素。

模式 10：原生用戶端驗證（Native Client Attestation）— API 存取控制

API 請求中包含 cch=00000 的佔位字串，Bun 的原生 HTTP stack（以 Zig 實作）會在發送前以雜湊值覆寫。伺服器端驗證此雜湊以確認請求來自合法的 Claude Code 二進位檔，實質上是一種「API 呼叫 DRM」。

有趣的是該雜湊在原生層（Zig）計算，而不是在 JavaScript 層。若在 JavaScript 層計算，洩露的 .map 檔就能輕易還原；把邏輯放到 native binary 裡可顯著提高逆向工程成本。該機制由編譯期旗標 NATIVE_CLIENT_ATTESTATION 門控，並能以環境變數或 GrowthBook 的 kill-switch 關閉，以便在事故時能即時停用。

未出貨功能深掘：KAIROS 與 ULTRAPLAN

流出程式碼中特別受到關注的兩項未發佈功能，指示出 Claude Code 下一步可能的發展方向。

KAIROS — 主動式常駐代理（Proactive Resident Agent）

KAIROS 一詞源自希臘文「契機」，在程式碼中被超過 150 次引用，是一個自律的背景 daemon。現行 Claude Code 屬於「被動」：等使用者指令才動作；KAIROS 則是要成為「在合適時機不需使用者指示就主動行動」的存在。

架構分為四層：最底層為觀察日誌（append-only 的每日檔案），上層為模式偵測引擎（從日誌抽出重複錯誤、使用者手動執行的例行工作、長期未完成的 TODO 等），第三層為觸發器（cron、GitHub webhook、檔案系統變更通知等），最上層則是透過 /dream Skill 的記憶蒸餾。autoDream 在夜間運行，整合分散的觀察、移除邏輯矛盾，將模糊洞察轉為已驗證的事實——類比人類睡眠中記憶整理的過程。這代表從被動式到主動式的轉換，是 Anthropic 未來路線的一個重要訊號。

ULTRAPLAN — 雲端下放型計畫生成（Cloud Offload Planning）

ULTRAPLAN 將計畫階段委託到雲端的 Claude Opus（最長可達 30 分鐘）。當使用者提交複雜任務時，本地 Claude Code 把任務交給 Cloud Container Runtime（CCR）上運行的 Opus session，經過長時間「思考」後回傳計畫案。該計畫會經由瀏覽器式的批准 UI，然後透過 __ULTRAPLAN_TELEPORT_LOCAL__ 這個 sentinel 值送回本地終端。

可抽取的設計理念是「計畫與執行分離、模型分工」。計畫階段可跑大型模型慢速思考，執行階段則由小型模型快速回應；使用者只需同步批准計畫，其他流程非同步處理。結合 Coordinator Mode，單一 Claude 實例可透過 mailbox 系統管理多個 worker agent，分配子任務並整合結果——一種多模型協同（multi-model orchestration）的成熟實作方向。可預期未來 Task 工具（啟動子 agent）會朝此方向擴展。

「即便複製也跑不動」的理由

洩露後 24 小時內就出現用 Python、Rust 等重寫的複製案，名為 claw-code 或 OpenClaw 的 OSS 版本迅速累積 star。但這些複製案本質上無法成為「可運行的等價物」。其原因可歸納為三點。

第一，運營知識的累積不可複製。像是「連續失敗 50 次造成每天 25 萬次 API 呼叫浪費」→「把上限改為 3 次」的修正，是大規模運營後的經驗。複製程式碼無法複製這段試錯歷史；即使用相同參數從零開始運營，也會遇到不同的邊緣案例，需另行調整參數。

第二，調校（tuning）本身是不可見的。追蹤 14 個快取破壞向量、23 項 Bash 檢查、108 個 feature flag——這些數值在程式碼上，但「為何是這些數字」並未寫在程式碼裡。背後的判斷根據存在於公司內部的 Slack、事故報告與紅隊測試紀錄中。流出的只是「結果程式碼」，不是達成該結果的討論與決策過程。

第三，哈內斯與模型是協同演化的。像 prompt cache 最佳化、反蒸餾機制、挫折偵測等都是基於深刻理解模型特性的設計；若基礎模型改變，最佳的哈內斯設計也會改變。各 OSS 複製案難以對基礎模型做出同等深度的調校。即便自行對小型模型做微調，為了和哈內斯做到協同最佳化也需要多年時間與大量計算資源。

正如 Tanmay Deshpande 所言：「邏輯已被調校過——所有模式都把那些沒有寫進程式碼的前提以某種方式隱含起來。」原始碼只是冰山一角，水面下是整個 Anthropic 組織與運營。

能為自己的 CLAUDE.md 帶來的實作重點

從上述模式中，整理出個人開發者可立即採行的重點。無須一次實作全部 10 種模式，按優先度逐步導入即可。

CLAUDE.md 設計檢查表（哈內斯模式對照）

1. 哈內斯範式

是否明確定義工具的使用條件與禁止事項？
是否寫出不想讓模型判斷的領域？

2. 工具契約

自訂 Skills 是否統一記錄輸入 / 輸出 / 副作用 / 權限？
斜線指令是否總在前端寫入 allowed-tools 與 description？

3. 查詢引擎

是否定義錯誤時的回復程序（fallback）？
是否有「連續失敗時暫停並重規劃」的規則？

4. 權限

是否在 settings.json 中註明機密檔案的存取限制？
Deny / Allow 清單是否依「早期拒絕、晚期授權」設計？

5. 記憶管理

是否在 memories/ 下把短期 / 中期 / 長期資訊分離？
是否把常時參考資訊限制在數百字內？

6. 快取最佳化

是否將不常變的規則放檔案上方？
是否避免在靜態區混入時間或動態資訊？

7. 驗證迴路

是否有「完成前必須能證明其運作」的規則？
是否明文化測試 / 日誌檢查 / 構建確認程序？

初期應先著手模式 5（記憶管理）與模式 6（快取最佳化），這兩項只需調整設定或檔案順序即可見到明顯成效，能在長時間會話中大幅減少 API 成本並提升回應品質。接著導入模式 1（哈內斯範式）與模式 4（權限），可以提升安全性與可再現性。

總結

Claude Code 的原始程式碼流出，讓業界看見「哈內斯工程（harness engineering）」的重要性。512,000 行 TypeScript 揭露的不是模型細節，而是決定產品品質的控制層設計。另一方面，即便哈內斯模式公開，Anthropic 的競爭優勢仍未大幅受損，這說明了「藏在程式碼背後的組織知識」才是真正的進入障礙。

模型只是可替換的元件；哈內斯才是本體。而讓哈內斯成為本體的並非程式碼本身，而是刻錄在程式碼中的試錯與運營歷史。

從這個觀點出發，我們日常編寫的 CLAUDE.md 與 Skills 定義，實際上就是小型的哈內斯工程。這 10 種模式都能被映射到個人專案的尺度；不需一口氣全部導入，而是從最影響運營的領域開始依序應用。從流出事件中最大的一課是：別再等待模型，自行去寫哈內斯吧——「Don't wait for the model; write the harness.」