# 解體新書 · Kaitai Shinsho > A four-volume visual anatomy of AI agents. Four volumes × ten chapters each, dissecting AI agents from the Claude Code CLI layer down through Agent SDK, Claude API, to vendor-neutral theory. Aesthetic: washi paper + sumi ink + vermillion seals; each chapter has a hand-drawn SVG diagram with scroll-triggered animations. Drafted 2026-04-08. ## Cover & Navigation - [Cover page (index.html)](index.html): Four-volume index with clickable chapter deep-links. - [README.md](README.md): Project overview and volume layering. - [chapters.json](chapters.json): Machine-readable manifest of all 40 chapters. ## Volume I — Claude Code 解體新書 *Claude Code Anatomy · Claude Code CLI harness · Application layer (CLI)* - [Full visual volume (vol1-claude-code.html)](vol1-claude-code.html): HTML with SVG diagrams and animations. - [Ch 1 · 迴圈之魂 — The Agentic Loop](chapters/vol1/ch-01-迴圈之魂.md): Claude Code 的一次對話並不是一次模型呼叫。當模型決定要用工具( Bash 、 Edit 、 Agent …),harness 會執行工具、把 tool_result 注回上下文、再呼叫模型一次,直到模型只吐純文字為止。這就是 Claude Code 的 agentic loop — 「自主行動」就是從這個迴圈裡長出來的。六站一環,反覆推進。 - [Ch 2 · 脈絡編織 — Context Assembly](chapters/vol1/ch-02-脈絡編織.md): 在你每次按下 Enter 之前,harness 會在幕後悄悄「重新寫完整份 prompt」— 把七八層東西壓進同一個 context window 再遞給模型。模型看見的從來不是你打的那一行字,而是這整疊紙。 - [Ch 3 · 工具之鞘 — Tool Dispatch](chapters/vol1/ch-03-工具之鞘.md): 當模型說「我想 Write 這個檔案」,Claude Code 並不會馬上照辦 — 它先讀 settings.json 裡的 permissions (含 allow / deny 兩份字串模式清單 + defaultMode )決定走哪條路:命中 allow 直接執行、命中 deny 直接拒絕、兩者皆無則依 defaultMode 提示使用者。執行期在沙箱內、捕捉錯誤。這是 harness 風險… - [Ch 4 · 鉤子織時 — Hook Timeline](chapters/vol1/ch-04-鉤子織時.md): Hook 是 harness 允許你「在特定時間點插入自己程式碼」的接縫。它們不是 Claude 在執行 — 是 harness 在執行。當你說「從現在起每次 X 都要 Y」,那不是模型要記住的事,而是一條 hook 設定。 - [Ch 5 · 記憶二界 — Memory Worlds](chapters/vol1/ch-05-記憶二界.md): Claude Code 的記憶分為兩層:短暫的「context 記憶」活在這次對話的 token 預算裡,會隨 turn 與 auto-compression 消逝;永續的「file 記憶」主要靠 CLAUDE.md 階層(全域 ~/.claude/CLAUDE.md 與專案 ./.claude/CLAUDE.md )每 session 開頭自動注入,其餘狀態則存於 ~/.claude.json … - [Ch 6 · 棲所之圖 — The .claude Directory](chapters/vol1/ch-06-棲所之圖.md): Claude Code 的狀態不是放在某個黑盒資料庫裡 — 它全部都是純文字檔,散落在兩個目錄: ~/.claude/ (全域,跟著你這個使用者)與專案下的 .claude/ (跟著這個 repo)。兩者結構相同但作用範圍不同;專案設定覆蓋全域設定,像兩張透明賽璐珞片疊起來看。 - [Ch 7 · 設定之書 — settings.json](chapters/vol1/ch-07-設定之書.md): Claude Code 行為的幾乎一切 — 工具可否執行、hook 何時觸發、用哪個模型、要不要帶 Co-Authored-By — 都寫在 settings.json 這個純文字 JSON 檔裡。它是 harness 的「遺傳密碼」,一改就變體質。本章把它攤開、逐段標註。 - [Ch 8 · 技能之術 — Skills](chapters/vol1/ch-08-技能之術.md): Claude Code 的 skill 系統是一套「漸進揭露」(progressive disclosure)機制 — 不把所有 skill 內容塞進 context(那會爆 token),而是分三層揭開:平時只看見 skill 的名字與一行描述;一旦判斷需要,才呼叫 Skill 工具把整份 SKILL.md 載入。每層都有自己的 token 預算,層層加深。 - [Ch 9 · 分身之法 — Subagents](chapters/vol1/ch-09-分身之法.md): 當任務需要大量探索、或包含數個彼此獨立的子問題,Claude Code 可以透過 Agent 工具「分身」— 呼叫一個或多個 subagent 平行工作。每個分身有自己的 system prompt、自己的 context window、自己的工具集;它們彼此看不見,最後只傳回一則文字結果給主 agent。這既是效率手段,也是保護主 context 的手段。 - [Ch 10 · 協議之橋 — MCP & Deferred Tools](chapters/vol1/ch-10-協議之橋.md): Claude Code 的工具不全是內建的。透過 MCP (Model Context Protocol)— 由 Anthropic 提出的開放協議 — 任何外部程序都能向 harness 註冊自己的工具,被 Claude 當作「原生工具」呼叫。但若所有 MCP 工具的 schema 都一次塞進 context 會爆 token — 於是 Claude Code 又引入了 deferred too… ## Volume II — Claude Agent SDK 解體新書 *Claude Agent SDK Anatomy · Claude Agent SDK (Python + TypeScript) · Library layer* - [Full visual volume (vol2-agent-sdk.html)](vol2-agent-sdk.html): HTML with SVG diagrams and animations. - [Ch 1 · query() 之魂 — the one-shot call](chapters/vol2/ch-01-query()-之魂.md): Agent SDK 的入口只有一個函式: query() 。你餵它一段 prompt 與一組 options,它回傳一個 async iterator — 不是一次性結果,而是一條流。模型與工具每產生一則訊息,iterator 就吐出一項,直到最後一則 ResultMessage 為止。這是最簡入口,也是最常用的入口。 - [Ch 2 · 訊息之型 — message types](chapters/vol2/ch-02-訊息之型.md): 從 query() 流出來的每一項都是某種 Message 。SDK 定義了四個主要型別 — SystemMessage 、 UserMessage 、 AssistantMessage 、 ResultMessage — 外加一個可選的 StreamEvent (細粒度串流用)。其中 AssistantMessage 的 content 欄位又裝著一串 content block :文字、工具呼… - [Ch 3 · 客身持續 — ClaudeSDKClient](chapters/vol2/ch-03-客身持續.md): query() 是一次性的 — 每呼叫一次都建立新 session。如果你要做多輪對話、讓模型記得前面說過的話,就要用 ClaudeSDKClient 。它是一個 async context manager:進入時 connect ,期間可以 query / receive_response 多次,最後 disconnect 。同一個 client 內部自動維持 session id,不用你手動管… - [Ch 4 · 系統之諭 — ClaudeAgentOptions](chapters/vol2/ch-04-系統之諭.md): ClaudeAgentOptions 是 SDK 所有可調參數的集合 — system prompt、model、工具白名單、權限 callback、hook 註冊、MCP server、subagent 定義、session 恢復等都寫在這一份 dataclass(Python)或 object(TypeScript)裡。本章把它分成六大區,逐區標註。 - [Ch 5 · 器具自製 — Custom Tools](chapters/vol2/ch-05-器具自製.md): 內建的 Bash / Read / Edit 不夠用?SDK 讓你寫自己的 — 只要一個 decorator(Python)或一個 helper(TypeScript)。你提供名稱、描述、輸入 schema、與一個 async handler,SDK 會把它包成 MCP tool 註冊進 registry,從此模型看得見、叫得動。核心公式: name + description + schema … - [Ch 6 · 協議內融 — In-Process MCP](chapters/vol2/ch-06-協議內融.md): 傳統的 MCP server 是 另一個進程 — 你的 host 用 stdio 或 SSE 與它通訊,開銷是啟動、序列化、IPC。Agent SDK 獨有的 create_sdk_mcp_server 把這層全部蒸發:你的工具函式直接在當前 Python / Node 進程裡執行,沒有跨進程呼叫,沒有序列化,共享同一記憶體空間。部署、除錯、效能都更舒服。 - [Ch 7 · 權限之掌 — canUseTool & permissionMode](chapters/vol2/ch-07-權限之掌.md): 內建的 allow / ask / deny 清單已經能擋下大多數問題,但若你要的是「對 Bash 的 rm 一律拒絕、對 ls 一律放行、對其他指令依靠 LLM 判斷」這種更細緻的規則 —— 就需要 canUseTool 。它是一個 async callback,接住 harness 傳來的工具呼叫,自己決定 allow / deny,甚至改寫參數。加上 permission_mode ,你可以… - [Ch 8 · 鉤子入碼 — Programmatic Hooks](chapters/vol2/ch-08-鉤子入碼.md): Claude Code 的 hook 寫在 settings.json 裡、呼叫 shell 指令。SDK 的 hook 則寫在程式碼裡、呼叫你的 async 函式 —— 同一個引擎,但對 SDK 使用者來說更直接:不需要離開 Python / TypeScript 生態,可以直接讀寫記憶體、呼叫 ORM、拒絕工具、改寫 prompt。本章拆解 HookMatcher 的註冊方式與 callbac… - [Ch 9 · 分身召喚 — Custom Subagents](chapters/vol2/ch-09-分身召喚.md): 在 Claude Code 卷一的第玖回,我們看過 subagent 的運作 —— 隔離的 context、curated tools、獨立 system prompt。SDK 讓你用程式碼定義這些 subagent,而不是在 .claude/agents/ 擺 Markdown 檔。每個 AgentDefinition 是四件事:描述、可用工具、system prompt、模型。註冊到 opti… - [Ch 10 · 會話續命 — Sessions](chapters/vol2/ch-10-會話續命.md): 如果你的 agent 是一個長壽的後端服務,使用者今天問一半、明天回來繼續 — 你需要的是 resume 。SDK 把每個 session 的歷史透明地保存在 transcript 檔裡;下次只要把 session id 丟進 options.resume ,agent 就能從斷點接續,模型記得昨天講過的話。 fork_session=True 則是另一招:基於舊會話建立一個分歧新會話 — 適合「… ## Volume III — Claude API 解體新書 *Claude API Anatomy · Anthropic Messages API · HTTP protocol layer* - [Full visual volume (vol3-claude-api.html)](vol3-claude-api.html): HTML with SVG diagrams and animations. - [Ch 1 · 信之所至 — POST /v1/messages](chapters/vol3/ch-01-信之所至.md): Claude API 表面上是一個 REST API,但實際上你幾乎只需要記住一條 URL: POST https://api.anthropic.com/v1/messages 。一切與模型的對話都走這一條。本章拆解它的最小必要請求 — 哪些 header 非附不可、哪些欄位必填、以及三種呼叫方式(curl / Python / TypeScript)怎麼寫。 - [Ch 2 · 對話之骨 — messages array & content blocks](chapters/vol3/ch-02-對話之骨.md): messages 是一個陣列,依時間順序排列使用者與模型的交替輪次。每個 message 有 role ( "user" 或 "assistant" )與 content 。content 可以是一個字串(最簡)— 也可以是一個 content block 陣列 (多模態、工具、思考)。本章列出所有 content block 型別與它們出現的場合。 - [Ch 3 · 回音之型 — response envelope](chapters/vol3/ch-03-回音之型.md): API 回你的不是一堆字 — 是一個結構化的 JSON envelope。裡面有九個欄位,其中 stop_reason 告訴你為什麼模型停下來、 usage 告訴你花了多少 token。讀懂這兩個欄位,你的應用層就知道該繼續、該重試、還是該結算。 - [Ch 4 · 諭令微調 — system prompt & sampling parameters](chapters/vol3/ch-04-諭令微調.md): 在 messages 之外,request body 還有一堆旋鈕可轉 — system 定義模型身分、 temperature / top_p / top_k 控制隨機性、 stop_sequences 設早停條件、 metadata 帶請求辨識資訊。本章把這些全部列出來並給出合理預設。 - [Ch 5 · 器械交響 — tool use protocol](chapters/vol3/ch-05-器械交響.md): Tool use 是 API 層最精巧的協議。你宣告工具、模型決定用哪個、你執行它、把結果回傳 — 這個循環在 API 層全都要你親手跑。三個步驟: 宣告 ( tools 欄位)、 接收 ( ToolUseBlock )、 回注 ( ToolResultBlock 放進下一個 user message)。 - [Ch 6 · 流之八事 — SSE Streaming](chapters/vol3/ch-06-流之八事.md): 把 request body 加上 "stream": true ,API 就改用 Server-Sent Events 格式回你 — 不再是一個大 JSON,而是一連串小事件。總共八種事件型別,按序出現。本章畫出它們的時間序與組裝邏輯:客戶端如何從一堆 delta 重建完整訊息。 - [Ch 7 · 靜思一界 — Extended Thinking](chapters/vol3/ch-07-靜思一界.md): Extended thinking 讓模型在「回答前」先做一段結構化思考 — 這些思考以 ThinkingBlock 的形式出現在 content 陣列裡。你可以在 request 設定 thinking.budget_tokens 控制允許的思考量。這一層是透明的:你看得見思考過程,但在多輪對話中把 ThinkingBlock 原封保留回傳,模型可以「繼續原本的思考線索」。 - [Ch 8 · 憶之快徑 — Prompt Caching](chapters/vol3/ch-08-憶之快徑.md): 有些 prompt 的前段很長且很固定 — 例如放了 50K tokens 的 API 文件當 system prompt。每次都重送是浪費。 Prompt caching 讓你標記「這段請快取」— 下次請求若開頭一致,就按 10% 的折扣價從快取讀(cache_read)而不是重新處理。本章拆解它的協議、TTL 選項、與計費模型。 - [Ch 9 · 多模之眼 — Vision & Documents](chapters/vol3/ch-09-多模之眼.md): Claude 可以看圖、讀 PDF、分析文件 — 都透過 content block 系統實現。 ImageBlock 接受 base64 或 URL 來源、 DocumentBlock 吃 PDF、 SearchResultBlock 用於 RAG 管線。本章列出所有 source 型別與尺寸限制,並附實際 request 範例。 - [Ch 10 · 批次與檔案 — Message Batches & Files API](chapters/vol3/ch-10-批次與檔案.md): 若你能接受「幾分鐘到 24 小時內完成」而不是即時,可以走 Message Batches API — 價格打五折。一次提交最多 100,000 筆請求,API 會排進低優先佇列慢慢跑,跑完後把結果以 JSONL 提供下載。搭配 Files API 可讓你把大型附件(PDF、長文件)預先上傳、反覆引用而不必每次重傳。本章拆解這兩個端點的生命週期。 ## Volume IV — 通用 AI Agent 解體新書 *Universal AI Agent Anatomy · Agent architecture principles (vendor-neutral) · Theory layer* - [Full visual volume (vol4-universal-agent.html)](vol4-universal-agent.html): HTML with SVG diagrams and animations. - [Ch 1 · 何謂代理人 — What is an agent](chapters/vol4/ch-01-何謂代理人.md): 「Agent」這個詞被用得太鬆 — 任何用了 LLM 的東西都自稱 agent。本章先把線畫清楚:純 LLM 不是 agent、RAG 不是 agent、scripted workflow 不是 agent、chatbot 不是 agent。 Agent 的最小定義 = LLM + 自主迴圈 + 工具 。三樣缺一不可。其餘只是 LLM 的應用。 - [Ch 2 · 認知迴圈 — The cognitive loop](chapters/vol4/ch-02-認知迴圈.md): 所有 agent 的內核都是同一個四站迴圈。它早於 LLM — 1980 年代的 BDI 認知架構、1990 年代的 robotics 控制理論、2000 年代的 reinforcement learning,全都用同一個框架: 感知(perceive)→ 推理(reason)→ 行動(act)→ 觀察(observe) 。LLM agent 只是把「推理」這一站換成了 next-token pr… - [Ch 3 · 工具之介面 — Tool interface](chapters/vol4/ch-03-工具之介面.md): 所有現代 LLM 都用同一套抽象 — function calling :開發者宣告函式(name、description、input schema),模型在輸出中產生 {name, arguments} 物件。差別只在 wire format。本章把 OpenAI、Anthropic、Gemini 三家的格式並排,讓你一眼看出它們其實只是同一個概念的三種編碼。 - [Ch 4 · 記憶四界 — Four realms of memory](chapters/vol4/ch-04-記憶四界.md): 認知心理學自 Tulving 1972 之後把記憶分成四類:working、episodic、semantic、procedural。出乎意料地,這個分類在 LLM agent 上完全成立 — 對應 context window、過去 session、知識庫、工具/skill。本章把這個四象限攤開:每一界活在哪、怎麼讀、怎麼寫、會不會失效。看清楚你需要哪幾界,避免把東西塞錯地方。 - [Ch 5 · 計畫之術 — Planning](chapters/vol4/ch-05-計畫之術.md): Agent 要不要先擬一份計畫?這個問題沒有單一答案 — 它是一條光譜:左端是純反應式(每步現想),右端是純審慎式(先寫完整計畫再執行)。實務上多數成功 agent 落在中間: plan-and-execute (先擬中間粒度的計畫,執行時可修訂)。本章拆光譜兩端與中間幾種典型模式。 - [Ch 6 · 反思之鏡 — Reflection](chapters/vol4/ch-06-反思之鏡.md): LLM 的第一答常常是錯的、第二答常常更好。這個觀察催生了一整套「自我修正」模式 — 從最簡的 self-critique 到 Reflexion (Shinn et al. 2023) 的記憶式反思、到外部 verifier 的客觀檢查。本章拆四種反思結構與它們各自的適用情境。 反思不是萬靈丹 :用對地方加分、用錯地方只是燒 token 走原路。 - [Ch 7 · 群體智慧 — Multi-agent](chapters/vol4/ch-07-群體智慧.md): 多 agent 系統聽起來很性感 — 多個 specialist 彼此協作就像團隊 — 但實踐上最常見的結局是:成本爆炸、context 不同步、決策推卸責任、整體比單一 agent 更糟。本章畫三種主流拓撲,並更重要地:列出 「不該用 multi-agent 的紅燈情境」 。 - [Ch 8 · 護衛之圍 — Guardrails](chapters/vol4/ch-08-護衛之圍.md): Agent 會自主行動 — 這是它的力量也是它的危險。靠單一防線(例如「我寫了個好 system prompt」)不夠 — 任何單層防禦都會被繞過。安全的 agent 系統用 縱深防禦 :五層由內而外的護欄,每一層都假設前一層已被攻破。本章畫這五層的邊界與職責。 - [Ch 9 · 試煉之地 — Evaluation](chapters/vol4/ch-09-試煉之地.md): 「你怎麼知道你的 agent 變好了?」這是 agent 工程裡最難回答的問題。傳統軟體可以靠單元測試 — agent 的非確定性讓單元測試只能驗證「沒崩潰」而非「答對了」。本章畫出 agent 評估的五層金字塔:從便宜快速但表淺的單元測試,到昂貴慢但有信度的人類審查。 - [Ch 10 · 部署實戰 — Deployment](chapters/vol4/ch-10-部署實戰.md): 原型 agent 跑通是一回事,把它送上生產又是另一回事。Agent 的 ops 跟一般 web 服務有共通之處(監控、scaling、deploy),但也有自己的怪癖(單次請求可能跑 5 分鐘、成本不可預測、失敗可能是「答得不好」而非「拋例外」)。本章列出生產 agent 必備的五大 ops 能力。 ## Volume V — Claude Managed Agents 解體新書 *Claude Managed Agents Anatomy · Anthropic hosted agent runtime (public beta) · Cloud platform layer* - [Full visual volume (vol5-managed-agents.html)](vol5-managed-agents.html): HTML with SVG diagrams and animations. - [Ch 1 · 何謂託管 — What is Managed — Messages API vs Managed Agents](chapters/vol5/ch-01-何謂託管.md): Messages API 是一把手術刀——你自己握柄、控制角度、決定切多深。Managed Agents 是一座自動手術台——你描述手術目標,平台負責執行迴圈、管理容器、提供工具、串流結果。兩者的根本差異在於 誰擁有迴圈 :前者是你,後者是 Anthropic。此章以官方對照表為藍本,逐項比對兩種範式。 - [Ch 2 · 代理人定義 — POST /v1/agents — Define the Agent](chapters/vol5/ch-02-代理人定義.md): 一切始於 POST /v1/agents 。Agent 是一份不可變的定義:指定模型(如 claude-sonnet-4-20250514 )、系統提示詞、以及工具集。每次建立都產生一個 agent.id 與 agent.version ,如同一份蓋章的處方——內容不可竄改,但可以新建版本。工具集 agent_toolset_20260401 內建 bash、檔案操作、網頁搜尋/擷取,並可掛載 M… - [Ch 3 · 環境配置 — POST /v1/environments — Container Template](chapters/vol5/ch-03-環境配置.md): Agent 定義「做什麼」,Environment 定義「在哪裡做」。 POST /v1/environments 建立一個容器模板,指定網路策略( unrestricted 或 restricted + 白名單)與預裝套件。每個 session 啟動時,都會從此模板生成一個隔離的容器實例。環境也是不可變的——修改即建新版。 - [Ch 4 · 會話開啟 — POST /v1/sessions — Launch and Lifecycle](chapters/vol5/ch-04-會話開啟.md): Agent + Environment = 定義。Session = 運行實例。 POST /v1/sessions 引用 agent ID 與 environment ID,Anthropic 即啟動一個容器、載入工具、進入 agentic 迴圈。Session 有明確的生命週期: created → active → idle → (更多事件) → ended 。每個 session 持續計費… - [Ch 5 · 事件交響 — Events & Streaming — the Bidirectional Protocol](chapters/vol5/ch-05-事件交響.md): Session 的靈魂是事件。你透過 POST /v1/sessions/{id}/events 發送 user.message ;你透過 GET /v1/sessions/{id}/stream 以 SSE 接收 agent 的回應——包括 agent.message (文字)、 agent.tool_use (工具呼叫)與 session.status_idle (完成等待)。這是一個非對稱的… - [Ch 6 · 工具全譜 — Agent Toolset](chapters/vol5/ch-06-工具全譜.md): Messages API 要求開發者逐一定義 tools[] ;Managed Agents 則以單一 agent_toolset_20260401 聲明一次注入全部能力。此工具集涵蓋四大類別—— Shell 執行、檔案操作、網路存取、以及外部 MCP 伺服器連接——讓 agent 在容器內擁有 與 Claude Code 對等的操作面。每個類別獨立授權,可於 environment 層級啟用或停… - [Ch 7 · 串流與操控 — Streaming & Steering](chapters/vol5/ch-07-串流與操控.md): 傳統 API 呼叫是「送出、等待、接收」的單次往返。Managed Agents 的串流架構則開啟了 一條持續的 SSE(Server-Sent Events)通道:客戶端透過 GET /v1/sessions/{id}/stream 建立連線,伺服器持續推送事件—— agent.message (文字串流)、 agent.tool_use (工具呼叫)、 直到 session.status_id… - [Ch 8 · 容器與持久 — Containers & Persistence](chapters/vol5/ch-08-容器與持久.md): 每個 Managed Agent session 都在一個隔離的容器中執行。容器由 environment 定義的模板 建立,預裝 Python、Node.js、Go 等常見語言執行環境。容器內的檔案在同一 session 的 多次對話間持久存在——agent 第一輪寫入的程式碼,第二輪仍可讀取和修改。更重要的是, session 本身具備持久性:即使客戶端斷線重連,agent 的狀態和容器內容都… - [Ch 9 · 進階能力 — Advanced Features — Research Preview](chapters/vol5/ch-09-進階能力.md): Managed Agents 平台提供三項研究預覽功能,目前需要申請存取權限。 Outcomes 讓你為 agent 定義明確的成功準則,系統會據此評估任務是否完成; Multiagent 支援多個 agent 之間的協調與通訊,實現任務分工; Memory 則提供跨 session 的持久記憶,讓 agent 能從歷史互動中學習。 這三項能力分別對應了 agent 系統的三大缺口——目標量化、水… - [Ch 10 · 選型與定價 — Choosing & Pricing](chapters/vol5/ch-10-選型與定價.md): Anthropic 的 Claude 生態已形成五層堆疊:最底層是理論與原理(卷壹至肆), 之上是 Managed Agents(本卷),再上是 Messages API、Agent SDK、最頂層則是 Claude Code 本身。每一層都在下一層之上增加抽象與便利——但也增加了成本與限制。 選擇哪一層,取決於你對控制力、便利性、與成本的權衡。Managed Agents 的定價模型 為標準 t… ## Optional - All chapter markdown files live under `chapters/vol{1..4}/`. They contain plain prose (导言 + 要點) extracted from the HTML — no SVG, no CSS, no animations. Ideal for LLM retrieval and RAG indexing.