Anthropic AI 程式撰寫代理的架構、模式與內部運作
Note
本專案為 claude-code-from-source 的正體中文翻譯版本。感謝原文作者 Alejandro Balderas 提供如此詳盡且具啟發性的研究與分析內容。
線上閱讀：fullstackladder.dev/claude-code-from-source-zh-tw/
本專案純粹用於教育目的。 不包含 Claude Code 的任何原始碼——一行都沒有。所有程式碼區塊皆為原創虛擬碼，使用不同的變數名稱，用以說明架構模式。目標是幫助工程師理解正式環境的 AI 代理是如何建構的，而非重製或散佈專有軟體。
當 Anthropic 將 Claude Code 發佈到 npm 時，.js.map 原始碼映射（Source Map）中包含了 sourcesContent 欄位，內含完整的原始 TypeScript 原始碼。本書即是研究該架構後的成果，將其中的模式、取捨與設計決策提煉為任何工程師都能學習的技術敘事。
橫跨 7 大篇章，共 18 個章節。 印刷版約 400 頁。
每個章節都具備分層深度：為技術領導者設計的敘事主線、為實作者準備的深入剖析段落，以及結尾的**「實踐應用」**區塊——從中萃取可遷移的模式，供你應用於自己的系統中。圖表使用 Mermaid 繪製，可在 GitHub 上原生渲染。
- 正在建構代理系統的資深工程師 —— 偷走這些模式、理解其取捨、在你自己的技術棧中實作
- 評估架構的技術領導者 —— 跟著敘事走，不必逐行閱讀每個程式碼區塊
- 任何好奇正式環境 AI 工具實際如何運作的人 —— 深入引擎蓋下探究
在代理能思考之前，行程必須先存在。
| # | 章節 | 你將學到 |
|---|---|---|
| 1 | AI 代理的架構 | 六大關鍵抽象、資料流、權限系統、建置系統 |
| 2 | 快速啟動——啟動引導管線 | 五階段初始化、模組層級 I/O 並行、信任邊界 |
| 3 | 狀態——雙層架構 | 啟動引導單例、AppState 儲存、黏性閂鎖、成本追蹤 |
| 4 | 與 Claude 對話——API 層 | 多供應商客戶端、提示快取、串流、錯誤復原 |
代理的心跳：串流、行動、觀察、重複。
| # | 章節 | 你將學到 |
|---|---|---|
| 5 | 代理迴圈 | query.ts 深入剖析、四層壓縮、錯誤復原、token 預算 |
| 6 | 工具——從定義到執行 | 工具介面、14 步管線、權限系統 |
| 7 | 並行工具執行 | 分割演算法、串流執行器、推測性執行 |
一個代理很強大。多個代理協同運作則能帶來變革。
| # | 章節 | 你將學到 |
|---|---|---|
| 8 | 產生子代理 | AgentTool、15 步 runAgent 生命週期、內建代理類型 |
| 9 | 分叉代理與提示快取 | 位元組級相同前綴技巧、快取共享、成本最佳化 |
| 10 | 任務、協調與群集 | 任務狀態機、協調者模式、群集訊息傳遞 |
沒有記憶的代理會永遠犯同樣的錯誤。
| # | 章節 | 你將學到 |
|---|---|---|
| 11 | 記憶——跨對話學習 | 基於檔案的記憶、四類分類法、LLM 召回、過期處理 |
| 12 | 可擴展性——技能與鉤子 | 兩階段技能載入、生命週期鉤子、快照安全性 |
使用者看到的一切都通過這一層。
| # | 章節 | 你將學到 |
|---|---|---|
| 13 | 終端機 UI | 自訂 Ink 分支、渲染管線、雙緩衝、物件池 |
| 14 | 輸入與互動 | 按鍵解析、按鍵綁定、組合鍵支援、Vim 模式 |
代理的觸及範圍超越了 localhost。
| # | 章節 | 你將學到 |
|---|---|---|
| 15 | MCP——通用工具協定 | 八種傳輸方式、MCP OAuth、工具包裝 |
| 16 | 遠端控制與雲端執行 | Bridge v1/v2、CCR、上游代理 |
讓一切快到人類察覺不到背後的機制。
| # | 章節 | 你將學到 |
|---|---|---|
| 17 | 效能——每一毫秒和每一個 Token 都重要 | 啟動、上下文視窗、提示快取、渲染、搜尋 |
| 18 | 結語——我們學到了什麼 | 五個架構賭注、可轉移的知識、代理的未來方向 |
如果你只讀一個段落：
- AsyncGenerator 作為代理迴圈 —— 產出 Messages、具型別的 Terminal 回傳值、自然的背壓與取消機制
- 推測性工具執行 —— 在模型串流期間就啟動唯讀工具，無需等到回應完成
- 並行安全的批次處理 —— 依安全性分區工具，讀取並行執行，寫入序列化
- 分叉代理實現快取共享 —— 平行子代理共享位元組相同的提示前綴，節省約 95% 的輸入 token
- 四層上下文壓縮 —— 裁剪、微壓縮、摺疊、自動壓縮——每一層都比上一層更輕量
- 檔案式記憶搭配 LLM 召回 —— Sonnet 側查詢選擇相關記憶，而非關鍵字匹配
- 兩階段技能載入 —— 啟動時僅載入前置資料，呼叫時才載入完整內容
- 黏性閂鎖確保快取穩定性 —— 一旦發送 beta 標頭，就不再於會話中途取消
- 槽位保留 —— 預設 8K 輸出上限，命中時升級到 64K（在 99% 的請求中節省上下文）
- 鉤子設定快照 —— 啟動時凍結，防止執行期注入攻擊
原始碼從 npm 原始碼映射中提取。36 個 AI 代理分四個階段分析了近兩千個 TypeScript 檔案：
- 探索：6 個並行代理讀取了原始碼樹中的每一個檔案
- 分析：12 個代理撰寫了 494KB 的原始技術文件
- 寫作：15 個代理從零開始將所有內容重寫為敘事章節
- 審閱與修訂：3 位編輯審閱者產出 900 行回饋；3 個修訂代理套用了所有修正
整個過程——從原始碼提取到最終修訂完成——大約耗時 6 小時。
本儲存庫不包含 Claude Code 的任何原始碼。 所有程式碼區塊皆為原創虛擬碼，使用不同的變數名稱，用以說明架構模式。不包含任何專有提示文字、內部常數或精確的函式實作。本專案純粹出於教育目的——幫助工程師理解正式環境 AI 程式撰寫代理背後的設計模式。
「NO'REILLY」封面僅為戲仿/迷因，用於說明目的。本專案與 O'Reilly Media 無任何關聯。那隻螃蟹就只是一隻螃蟹。
這是一份獨立分析。Claude Code 是 Anthropic 的產品。本書與 Anthropic 無關聯、未獲其背書、亦未受其贊助。