從 Claude Code 洩漏源碼學到的:如何打造生產級 AI Coding Agent

基於 Claude Code 512K 行洩漏源碼的工程分析,系統性整理 AI coding agent 的核心架構模式、安全設計、記憶系統、Context 壓縮、多 Agent 編排等關鍵工程決策,形成一套可複製的 agent 開發藍圖。

從 Claude Code 洩漏源碼學到的:如何打造生產級 AI Coding Agent

研究日期

2026-04-04

簡介

2026 年 3 月 31 日,Anthropic 因 .npmignore 配置失誤意外公開了 Claude Code 的完整源碼——512,000 行 TypeScript、1,906 個檔案、44 個隱藏 feature flag。這不是一個聊天介面包裝器,而是一個 $2.5B ARR 的生產級 agentic harness

本文從工程師的角度,將洩漏源碼中驗證過的架構模式提煉成一套可複製的 agent 開發藍圖。不談理論,只談「Claude Code 做了什麼、為什麼這樣做、你可以怎麼複製」。


核心認知:Agent Harness ≠ Chat Wrapper

大多數人對 AI coding agent 的理解停留在「LLM + 工具呼叫 + REPL」。Claude Code 的源碼揭示了一個更複雜的現實:

  flowchart TB
    subgraph "Agent Harness 的真實複雜度"
        A[Tool System<br>40+ 工具,每個獨立權限模型] --> B[Query Engine<br>46,000 行,LLM 編排核心]
        B --> C[Context Management<br>4 層壓縮體系]
        B --> D[Security Layer<br>23 項 bash 驗證 + 8 步權限級聯]
        B --> E[Memory System<br>三層架構 + AI 驅動召回]
        B --> F[Subagent System<br>Fork / Teammate / Worktree]
        C --> G[Prompt Cache<br>14 個 break vectors + 全域快取]
        E --> H[AutoDream<br>Forked subagent 記憶整合]
        F --> I[KAIROS<br>自主 daemon(未發佈)]
        A --> J[MCP Layer<br>所有工具統一介面]
        D --> K[Hook System<br>25+ 事件攔截點]
        B --> L[Telemetry<br>640 事件 + 40 指紋維度]
        G --> M[Remote Kill Switches<br>GrowthBook feature flags]
    end

Claude Code 中,LLM 推理只佔工程複雜度的 ~30%。 剩下的 70% 是 context 管理、安全防禦、工具編排、記憶持久化和效能優化。

核心迴圈的簡潔性

getaibook.com 的分析指出了一個被廣泛引用的發現——Claude Code 的核心就是一個 while(tool_call) 迴圈

1
2
3
4
while (tool_call) {
    result = execute(tool_call)
    response = claude(result)
}

沒有意圖分類器、沒有任務路由器、沒有 RAG 管線、沒有 DAG 編排器、沒有 planner/executor 分離。模型自己決定呼叫哪些工具、以什麼順序、何時停止。

512,000 行程式碼的全部複雜性——記憶、安全、權限、context 管理、多 agent 協調——都是圍繞這個簡單迴圈建構的防禦性和增強性基礎設施。

對建構者的啟示:不要一開始就建 DAG 編排器或 planner/executor 分離。先讓簡單迴圈跑起來,再根據實際痛點逐步加基礎設施。Claude Code 的複雜性不是設計出來的,是被真實攻擊和使用場景逼出來的。


第一課:架構設計

模組化工具系統

每個能力都是獨立的、有權限控制的模組:

1
2
3
4
5
設計原則:
1. 每個工具 = 獨立檔案 + 獨立權限模型 + 獨立驗證邏輯
2. 工具註冊用 schema 描述輸入/輸出(不靠 prompt 約束)
3. 工具執行有狀態機:queued → executing → completed → yielded
4. 工具分為「始終安全」「輸入依賴」「預設不安全」三類

Claude Code 的實作

  • 40+ 工具,base tool definition 29,000 行
  • 併發安全分類:FileRead(始終安全)、BashTool(輸入依賴)、FileEdit(預設不安全)
  • 併發控制:canExecuteTool() — 沒有執行中 → 可執行;自身安全 + 所有執行中也安全 → 可執行

MCP-first 工具架構

洩漏中最具架構意義的發現之一:Claude Code 不是「在 MCP 之上構建」——它的工具架構本身就是 MCP。

1
@ant/computer-use-mcp  ← Computer Use 就是一個 MCP Server

Computer Use(桌面自動化)不是特殊處理的模型層功能,而是一個使用與所有其他工具完全相同 MCP 介面的 Server——tools/list 發現、tools/call 呼叫、結構化結果返回。

可複製的設計模式

  flowchart LR
    A[Agent Loop] --> B[MCP Client]
    B --> C[tools/list]
    B --> D[tools/call]
    B --> E[resources/read]
    B --> F[prompts/get]
    
    C --> G[本地 MCP Server]
    C --> H[遠端 MCP Server<br>stdio/SSE/HTTP/WS]
    C --> I[託管 MCP Server<br>mcp-proxy 路由]
    
    G --> J[Bash / Read / Edit / Grep]
    H --> K[第三方整合<br>GitHub / Jira / Slack]
    I --> L[claude.ai-managed<br>Slack / Gmail / Drive]

claude.ai-managed MCP 代理路徑

  • 6 個整合(Slack、Gmail、Google Drive、Google Calendar、PubMed、BigQuery)透過 mcp-proxy.anthropic.com 路由
  • 使用者透過 claude.ai OAuth 連接,而非本地 MCP 配置
  • 與用戶本地 MCP 是平行共存的混合模式

Collapse Allowlist:489 個 MCP 工具有 collapse 分類(40 個標籤分組),決定哪些工具輸出可以在 context 壓縮時被清理。89 個 WebFetch 預審主機無需 URL 即可抓取。

對建構者的啟示:採用 MCP 作為統一工具介面,可以獲得生態系整合(任何 MCP Server 即插即用)、標準化發現機制、和一致的權限模型。不要為特殊功能建構專屬管線——把所有能力都變成 MCP Server。

Query Engine 作為「大腦」

Query Engine 不只是把 prompt 送給 API,它負責:

  flowchart LR
    A[使用者訊息] --> B[Context 載入<br>CLAUDE.md + 記憶 + git status]
    B --> C[Prompt 組裝<br>全域快取 + session-specific]
    C --> D[API 呼叫 + 串流]
    D --> E[Tool 執行<br>流式重疊]
    E --> F[Context 管理<br>微壓縮 / 自動壓縮]
    F --> G{繼續?}
    G -->|Yes| C
    G -->|No| H[最終回應]

關鍵設計

  • 流式工具執行:工具在模型還在生成 token 時就開始執行,不等待完整回應
  • Progressive context management:每輪都做微壓縮,不等到緊急才處理
  • Prompt cache boundary:system prompt 在固定位置分割,全域部分跨組織共享快取

第二課:安全系統

深度防禦的權限系統

  flowchart TB
    A[使用者/Agent 想執行 Bash 命令] --> B{Tree-sitter AST 解析}
    B -->|simple| C{沙盒放行?}
    B -->|too-complex| D{LLM 分類器}
    B -->|parse-unavailable| E[Legacy parser]
    C -->|Yes| F[✅ 允許]
    C -->|No| G{精確匹配}
    D -->|高置信度| H[自動批准/拒絕]
    D -->|低置信度| G
    E --> G
    G --> I{操作符拆分}
    I --> J[遞迴檢查每個子命令]
    J --> K{8 步子級聯}
    K --> F
    K --> L[❌ 拒絕]
    K --> M[❓ 詢問使用者]

可複製的設計模式

模式 做法 為什麼重要
AST-first 驗證 用 tree-sitter 建構命令 AST,不依賴正則 正則有 parser differential 漏洞
多層級聯 deny > ask > allow,每層獨立檢查 防止單層被繞過
不對稱環境變數處理 deny 用激進剝離,allow 用保守白名單 防止 FOO=bar denied_cmd 繞過
Shadow mode 新舊 parser 並行運行,記錄分歧 安全迭代不中斷服務
預設 fail-closed 不確定 → 拒絕;未知工具 → 不安全 安全優先

命令注入防禦清單

從 Claude Code 的 23 個驗證器提煉的必做清單:

  • Zsh =cmd expansion=curl 展開為完整路徑,繞過 blocklist
  • Heredoc injection$(cat <<'EOF' ... EOF) 在命令位置
  • ANSI-C quoting$'\x63\x61\x74' = cat
  • IFS injectionIFS=/ ls /etc 改變 tokenization
  • Unicode zero-width spaces:不可見字元繞過字串比對
  • Process substitution<(cmd)>(cmd)
  • /proc environ:封鎖 /proc/self/environ(防 API key 外洩)
  • Carriage return\r 在 shell-quote 和 bash 之間的解析差異
  • Compound command 防護cd /path && evil.py 不被 cd:* 放行

FileEditTool 的 TOCTOU 防禦

1
2
3
驗證階段:檢查 mtime → 通過
  → 調用階段:重新讀取檔案 → 再次檢查 mtime 和內容
  → 防止 validate 和 call 之間的 Time-Of-Check-Time-Of-Use 競態

Hook 系統:可擴展的事件攔截

utils/hooks.ts(~160KB,5,023 行),25+ hook 事件類型:

Hook Event 觸發時機 典型用途
SessionStart Session 開始或恢復 載入 context、設定 env vars
SessionEnd Session 終止 清理、保存狀態
UserPromptSubmit 使用者提交訊息 注入 git diff 作為 context
PreToolUse Tool 執行前 阻擋危險命令、auto-lint
PostToolUse Tool 成功後 自動 git stage、跑 formatter
PostToolUseFailure Tool 失敗後 錯誤處理、重試邏輯
SubagentStop Subagent 完成時 結果收集

可複製的設計模式

  • Hook 可以是 shell 命令或 HTTP endpoint
  • Hook 回傳 JSON {"decision": "allow"}{"decision": "deny", "reason": "..."}
  • 超時保護:每個 hook 有獨立超時設定

⚠️ 已知風險

  • Fork bomb:一位開發者寫了 SessionStart hook 啟動 2 個 Claude Code instance,每個又觸發 hook → 指數增長 1→2→4→8→2^N。SessionStart hook 必須冪等。
  • 權限繞過:HTTP hook 回傳 {"decision": "allow"} 可以繞過所有權限檢查。SDK/non-interactive 模式下不會彈出 workspace trust 對話框。
  • 安全建議:SDK 模式下須加 --trust-project flag 進行顯式信任設定

Auto Mode:獨立 LLM 分類器 + Circuit Breaker

Auto mode 不是 prompt 指令——是一個獨立的模型呼叫

1
2
3
4
5
每次 tool invocation
  1. Claude 決定要呼叫某個 tool
  2. 系統將 tool name + 參數 + 使用者意圖發送給 Sonnet 4.6 classifier
  3. Classifier 回傳:LOW / MEDIUM / HIGH
  4. LOW  自動批准;MEDIUM/HIGH  需要使用者確認

成本影響:每個 tool call 額外增加一次 Sonnet 4.6 inference——這是自主工作流中必須納入成本模型的開銷。

Circuit Breaker(Hard Limit)

  • 3 consecutive blocks → 暫停 auto mode,切換手動確認
  • 20 total blocks → 同上

可複製的設計:如果你要建 auto mode,不要用 prompt 指令控制權限——用獨立的(最好是更便宜的)模型做分類器,加上硬性限制防止失控。

CVE 教訓:Claude Code 安全的實際缺陷

洩漏後的安全審計揭示了 Claude Code 安全系統的實際缺陷:

CVE CVSS 漏洞 教訓
CVE-2025-59536 8.7 🔴 惡意專案設定檔 → RCE 專案配置檔(.claude/CLAUDE.md)是 attack surface
CVE-2025-59537 5.3 🟠 環境變數操作 → API key 外洩 環境變數處理是持久攻擊向量
CVE-2026-25725 沙盒繞過 → 未授權檔案存取 沙盒邊界比想像中容易繞過

最關鍵的教訓

  1. Tree-sitter parser 已存在但未啟用:Claude Code 內部已經有正確的 AST parser,但公開版仍在使用有 CR 注入漏洞的舊版 splitCommand_DEPRECATED。僅一行修改——將 fallback 從「ask」改為「deny」——就能修補。安全修補不僅僅是寫程式碼,更是部署正確的程式碼。

  2. SDK 模式權限削弱:non-interactive / SDK 模式下不會彈出 workspace trust 對話框,hook 可繞過權限。自動化環境的安全模型必須獨立設計,不能只是互動模式的子集。

  3. npm 供應鏈風險:洩漏同日出現惡意 axios 版本(含 RAT 木馬)。依賴鏈本身就是攻擊面——考慮 native installer 或獨立二進位發佈。


第三課:Context 管理

4 層壓縮體系

  flowchart LR
    A[每輪查詢] --> B["第 1 層:微壓縮<br>規則操作,<1ms"]
    B --> C["第 2 層:自動壓縮<br>上下文接近上限時"]
    C --> D{優先嘗試}
    D --> E["第 4 層:Session Memory<br>已有摘要,<10ms"]
    D -->|失敗| F["第 3 層:傳統壓縮<br>Fork Agent,5-30s"]
層級 成本 觸發條件 做法
微壓縮 零 API 呼叫 每輪 替換舊工具輸出為 [cleared];或用 cache_edits API 保持 prompt cache
Session Memory 壓縮 零 API 呼叫 自動壓縮觸發時優先 直接使用已積累的 Session Memory(10 個固定章節)
傳統壓縮 一次 Fork Agent inference Session Memory 不可用 Fork Agent 生成結構化摘要(共享 prompt cache)
手動 /compact 一次 inference 使用者觸發 同上,使用者控制時機

核心原則:盡可能用廉價規則操作延遲昂貴的 LLM 呼叫。

Prompt Cache 設計

  flowchart TB
    subgraph "System Prompt"
        A["--- SYSTEM_PROMPT_DYNAMIC_BOUNDARY ---<br>(全域快取區)<br>工具定義、核心指令<br>跨所有組織共享"] --- B["(Session-specific)<br>CLAUDE.md、git status、日期<br>每個 session 獨立"]
    end

可複製的設計

  • 固定分割點讓全域部分快取命中最大化
  • 追蹤 cache break vectors(14 種),但不嘗試恢復已打破的 cache(sticky latch)
  • 壓縮後保留最近存取的檔案(每檔 ≤ 5K tokens),重新注入 context

壓縮的注意事項

⚠️ 摘要不區分指令來源:從檔案讀取的指令和用戶直接輸入的指令在摘要中無法區分。攻擊者可通過 CLAUDE.md 植入指令,經壓縮後永久存活。

防禦:壓縮 prompt 中要求列出「所有非工具結果的使用者訊息」,但仍無法區分指令來源。這是所有基於摘要的 context 管理的固有缺陷。


第四課:記憶體系統

三層記憶架構

  flowchart TB
    subgraph "記憶體層級"
        L1["Layer 1:MEMORY.md 索引<br>(永遠載入 context)<br>每行 ≤ 150 字元,≤ 200 行"]
        L2["Layer 2:Topic Files<br>(按需載入)<br>帶 YAML frontmatter<br>4 種類型"]
        L3["Layer 3:原始 Transcript<br>(永不完整載入)<br>僅 grep 特定識別碼"]
    end
    
    L1 <-->|索引指向| L2
    L1 -.->|grep 查詢| L3

記憶提取:Fork Agent + 嚴格工具限制

1
2
3
觸發:每 query loop 結束(Stop Hook),fork subagent 執行
工具限制:Read/Grep/Glob 無限;Bash 僅只讀;Edit/Write 僅限記憶目錄
最多 5 輪,失敗不推進游標(下次重新考慮)

6 類不保存的內容(即使使用者要求):

  1. 可從程式碼推導的資訊(架構、檔案路徑)
  2. Git 歷史(git log 是權威來源)
  3. 除錯步驟(修復在程式碼中)
  4. CLAUDE.md 中已有的內容
  5. 臨時任務細節
  6. 無意外之處的摘要

AI 驅動召回

1
2
3
掃描記憶目錄 → mtime 降序取 200 檔 → Sonnet 模型評分
→ 「只包含你確定有幫助的。不確定就不包含。最多 5 個。」
→ 超過 1 天的記憶注入過期警告

關鍵原則:Skeptical Memory

  • MEMORY.md 條目是「提示而非事實」
  • 使用前必須對照實際程式碼驗證
  • 「記憶說 X 存在」≠「X 現在存在」

秘密掃描

30 種秘密模式檢測,涵蓋 AWS/GCP/Azure/Anthropic/OpenAI/GitHub/Slack/Stripe 等 API 金鑰。匹配到的值永遠不被記錄或返回——只返回規則 ID 和人類可讀標籤。


第五課:多 Agent 編排

三種 Subagent 模式

模式 用途 隔離方式 適用場景
Fork Context 壓縮、並行任務 共享 prompt cache 的獨立 context 短生命週期、需要快取命中
Teammate 持久協作 InProcess / Tmux / iTerm2 長期並行工作
Worktree Git 隔離 獨立 git worktree 需要獨立程式碼修改

Swarm 架構

  flowchart TB
    L[Leader Agent] -->|spawn| W1[Worker A<br>Tmux pane]
    L -->|spawn| W2[Worker B<br>InProcess]
    L -->|spawn| W3[Worker C<br>iTerm2]
    W1 <-->|檔案 mailbox| W2
    W2 <-->|檔案 mailbox| W3
    W1 -->|權限請求| L
    W2 -->|權限請求| L

可複製的設計

  • 檔案 mailbox 通信:JSON 檔案 + proper-lockfile(10 次重試,5-100ms 退避)
  • 權限委託:Worker 的權限請求路由到 Leader 的 UI
  • Coordinator 模式:Research → Synthesis → Implementation → Verification 四階段
  • Worker prompt 必須自包含:看不到協調者對話,每個 prompt 需要完整上下文

Fork Agent 的 Cache 共享

1
2
3
保留完整父級 assistant 訊息(所有 tool_use 塊)
建構 tool_result 塊(佔位文本:"Fork started"
只有最後的 text 塊不同  最大化 prompt cache 命中

第六課:效能優化

終端渲染

技術 效果 可複製性
Int32Array 雙緩衝 每 cell 8 bytes,位打包樣式 ✅ 任何 TUI 框架
charCache(16K 上限) 跨幀快取 grapheme 聚類
DECSTBM 硬體滾動 用終端原生滾動取代全區域重寫 ✅ 支援的終端
Blit 優化 乾淨節點直接 TypedArray.set() 複製
Peephole 優化 合併 cursor moves、取消 hide/show 對

啟動優化

1
2
3
// 在所有 import 之前觸發副作用(並行)
startMdmRawRead()        // macOS MDM 子進程讀取
startKeychainPrefetch()  // macOS 鑰匙串雙讀取(省 65ms)

純 TypeScript 原生移植

Claude Code 將所有 C++/Rust 依賴移植為 TypeScript:

原始依賴 移植 效果
Yoga(C++) TypeScript Flexbox 引擎 4 槽環形快取:76K → 4K layoutNode 呼叫
nucleo/fzf(Rust) TypeScript 模糊搜索 字元位圖 O(1) 拒絕 + gap-bound 剪枝
syntect/bat(Rust) TypeScript 語法高亮 highlight.js 延遲載入省 200ms 啟動

啟示:消除 native binary 依賴可大幅簡化部署和跨平台支援。


第七課:反蒸餾與認證

反蒸餾(如果需要)

方法 做法 效果
假工具注入 API 請求中注入 decoy tool 定義 汙染訓練資料
推理壓縮 伺服器端摘要 + 密碼學簽名 隱藏完整 CoT

現實:技術上可被 MITM proxy 或環境變數繞過。真正的防禦是法律和運營層面。

客戶端認證

1
2
3
API 請求包含 cch=00000 佔位符(固定 5 字元)
→ Bun 的原生 Zig HTTP stack 替換為計算出的 hash
→ 佔位符長度不變 = Content-Length 不變 = 零 buffer reallocation

啟示:將認證邏輯放在 JavaScript runtime 之下(Zig 層),防止 runtime patch 繞過。


第九課:遙測與可觀測性

遙測設計模式

Claude Code 的遙測系統不是事後加的——是從第一天就整合進去的基礎設施:

規模:640 遙測事件、40 裝置指紋維度、每 5 秒一次 API 查詢追蹤。

PII 隱私分層

  flowchart LR
    A[遙測事件] --> B{PII 標記?}
    B -->|是| C[_PROTO_ 前綴 key]
    C --> D[First-Party Exporter<br>→ 受保護 BigQuery]
    B -->|否| E[一般後端<br>→ Datadog / GrowthBook]
    A --> F[離線] --> G[~/.claude/telemetry/<br>本地暫存]

PII 標記的值使用 _PROTO_ 前綴的 payload key,在傳送到 Datadog 等一般存取後端前被剝離,僅由 first-party exporter 路由到受保護的 BigQuery 欄位。

Statsig → GrowthBook 遷移教訓:Anthropic 原本使用 Statsig,直到 OpenAI 收購了 Statsig(2025/9),必須緊急遷移到開源的 GrowthBook。不要依賴可能被競爭對手收購的分析平台。

可複製的設計

1
2
3
4
5
1. 啟動時收集:user ID、session ID、版本、平台、feature gates
2. 每次互動收集:message length、system prompt 大小、工具 schema 大小
3. PII 用前綴標記,在出口處分流到不同後端
4. 離線時本地暫存,上線後傳送
5. 裝置指紋用於 anti-abuse(而非定位追蹤)

關鍵差異:傳統 IDE 遙測記錄使用者如何操作介面。Agent 遙測記錄 agent 為使用者做了什麼——讀取了哪些檔案、執行了哪些命令。這是全新的可觀測性類別。


第十課:遠端控制與 Feature Flags

6 個遠端殺開關

Claude Code 有至少 6 個遠端殺開關,透過 GrowthBook feature flags 管理:

1
2
3
4
遠端設定端點(每 5 秒輪詢)
  → feature flag 評估
  → 決定啟用/禁用特定功能
  → 用戶無法覆蓋

所有 flag 以 tengu_ 為前綴:tengu_auto_mode_configtengu_harbortengu_amber_quartz_disabled 等。

55+ 編譯時特性開關

更強大的控制是編譯時 feature flags:外部 build 中為 false 的分支會被死代碼消除徹底刪除。涵蓋 KAIROS(6 個子開關)、CHICAGO_MCP、PROACTIVE、VOICE_MODE、ULTRAPLAN、COORDINATOR_MODE、SPECULATION 等。

1
2
3
feature("KAIROS")
  ? require("./kairos")      // 內部 build:包含
  : null                     // 外部 build:DCE 完全移除

可複製的設計

  • Runtime flags:用於 A/B 測試、緊急關閉功能、分階段推廣
  • Compile-time flags:用於內部/外部 build 差異化,確保內部功能不會外洩到公開版本
  • 兩者結合:compile-time 確保代碼不存在,runtime 確保可以遠端控制行為

對建構者的啟示:如果你要建商用 agent,feature flags 不是可選的——它們是發布管理、緊急響應和內部/外部版本差異化的基礎設施。


第八課:從零到一的實作路線圖

Phase 1:MVP(2-4 週)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
必做:
□ Tool registry + dispatch(3-5 個工具:Bash、Read、Edit、Grep)
□ 基礎 REPL(Ink/React terminal 或簡單 readline)
□ 權限系統(allow/deny 規則 + 使用者確認)
□ System prompt 組裝(固定 + 動態分割)
□ 基礎 context 壓縮(單層:Fork Agent 摘要)

不急:
□ 細粒度 bash 安全(先靠沙盒)
□ 記憶體系統(先靠 CLAUDE.md)
□ 多 agent(先單 agent)
□ 快取優化(先不快取)

Phase 2:安全加固(2-4 週)

1
2
3
4
5
6
7
8
9
□ Tree-sitter bash AST 解析
□ 5+ 項命令注入防禦(至少 =cmd、heredoc、IFS、ANSI-C、zero-width)
□ 環境變數白名單
□ FileEditTool 驗證鏈(mtime 檢查 + UNC 防護)
□ 權限模式(plan / default / acceptEdits / auto / bypass)
□ Auto mode classifier(獨立 LLM inference + circuit breaker)
□ Hook 系統(至少 PreToolUse / PostToolUse / SessionStart)
□ Hook 冪等性保護(防 fork bomb)+ 超時
□ SDK/non-interactive 模式獨立安全模型

Phase 3:智慧 Context(2-4 週)

1
2
3
4
5
6
□ 4 層壓縮體系(微壓縮 → Session Memory → 自動壓縮 → 傳統壓縮)
□ Prompt cache boundary 設計
□ CLAUDE.md / 記憶檔案載入
□ 基礎記憶提取(fork agent + 工具限制)
□ MEMORY.md 索引
□ Token 預算追蹤

Phase 4:多 Agent(4-6 週)

1
2
3
4
5
□ Fork subagent(共享 prompt cache)
□ InProcess teammate(AsyncLocalStorage 隔離)
□ 檔案 mailbox 通信
□ 權限委託(Worker → Leader UI)
□ Coordinator 模式(Research → Synthesis → Implementation → Verification)

Phase 5:進階功能(持續)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
□ 記憶 AI 驅動召回(Sonnet 評分選取)
□ 團隊記憶同步(REST API + 樂觀鎖)
□ 秘密掃描(30+ 種模式)
□ Hook 系統完整版(25+ 事件 + HTTP endpoint)
□ 終端渲染優化(雙緩衝 + diff + blit)
□ 投機執行(background fork agent)
□ 自主 daemon 模式(KAIROS 式)
□ MCP Server 生態整合(本地 + 遠端 + 託管混合模式)
□ 遙測系統(PII 分層 + 離線暫存 + agent 行為可觀測性)
□ Feature flag 系統(runtime + compile-time)
□ Native installer / 獨立二進位發佈(避免 npm 供應鏈風險)
□ 驗證 Agent(anti-laziness checklist,AI 生成代碼品質保障)

工程原則總結

做什麼

原則 做法
AST-first 安全 用 tree-sitter 解析命令,不依賴正則
Fail-closed 不確定 → 拒絕;未知 → 不安全
Cache-aware 每個設計決策考慮對 prompt cache 的影響
Bandwidth-aware Context window 是稀缺資源,記憶用索引 + 按需載入
Skeptical memory 記憶是提示不是事實,使用前驗證
Fork for isolation 記憶整合、壓縮摘要用 forked subagent 隔離
Progressive compression 每輪微壓縮,不等到緊急
Shadow mode for iteration 新舊安全檢查並行運行,記錄分歧

不做什麼

反模式 為什麼
❌ 單層安全檢查 任何一層都可被繞過
❌ 信任工具輸出 Tool result 是 hostile input,需要 prompt-injection 掃描
❌ 全量載入記憶 索引 + 按需載入才有效率
❌ 一個壓縮策略 4 層遞進,用廉價操作延遲昂貴操作
❌ 正則做安全驗證 Parser differential 會導致安全漏洞
❌ 不設 circuit breaker Claude Code 因無限重試每天浪費 250K API 呼叫

重點整理

  • Agent Harness ≠ Chat Wrapper:LLM 推理只佔 ~30%,剩下是 context 管理、安全、工具編排、記憶、效能
  • 核心就是 while(tool_call):沒有意圖分類器、沒有 DAG 編排器——512K 行複雜性圍繞簡單迴圈建構
  • MCP-first 工具架構:所有工具(包括 Computer Use)都是 MCP Server,統一介面、即插即用
  • 安全是深度防禦:23 項 bash 驗證 + 8 步權限級聯 + TOCTOU 防禦 + 秘密掃描 + Hook 系統,每一層獨立運作
  • Auto Mode 用獨立分類器:不是 prompt 指令,是額外 LLM inference + circuit breaker 硬限制
  • CVE 教訓:安全修補不僅是寫程式碼,更是部署正確的程式碼;SDK 模式需要獨立安全模型
  • Context 管理是核心競爭力:4 層壓縮 + prompt cache boundary + sticky latch,直接影響使用者體驗和 API 成本
  • 記憶用 Skeptical 模式:索引指向 + 按需載入 + AI 評分召回 + 使用前驗證
  • 多 Agent 用檔案 mailbox:簡單、可靠、易除錯,不需要 WebSocket 或 gRPC
  • 效能優化從啟動開始:並行預取、延遲載入、消除 native 依賴
  • 遙測是新類別的可觀測性:不只記錄使用者操作介面,更記錄 agent 為使用者做了什麼;PII 用前綴分流
  • Feature flags 是基礎設施:runtime flags 控制行為 + compile-time flags 控制代碼存在
  • 實作路線:MVP → 安全加固 → 智慧 Context → 多 Agent → 進階功能,每階段 2-6 週

參考資料