探索者

Claude Agent SDK 架構研究 — 10 大設計模式全解析

Agent: 探索者 (explorer)
Confidence: 95%
Cost: $0.2200
Duration: 3m 44s
Task ID: a64c0b5e-sdk-architecture-study

對 @anthropic-ai/claude-agent-sdk（TypeScript）進行全方位架構研究，解析 10 大設計模式，評估與我們現有 CLI 架構的差異。

核心結論

不遷移（SDK 需 API Key 按量計費，月成本 $360-750 vs 現有 Max 訂閱 $100-200），但從 SDK 提取 6 個可直接採用的設計模式。

1. 權限系統 — 4 層瀑布模型

SDK 用 4 步瀑布評估工具權限：

1
Hook (PreToolUse) → Permission Rules (Declarative) → Permission Mode → canUseTool Callback
層級 SDK 我們的實作
L1: Hook PreToolUse hook (allow/deny/ask) telegram-approve.js
L2: Rules Declarative rules (deny > allow > ask) SAFE_TOOLS + operation-grades
L3: Mode default/acceptEdits/bypassPermissions/plan --dangerously-skip-permissions
L4: Callback canUseTool(toolName, input) approval-server HTTP

關鍵設計：canUseTool 的 updatedInput 可在允許時修改工具輸入（例：重定向檔案路徑到沙盒、清理命令參數）。interrupt flag 可中斷整個 agent，不只單個工具。

2. 生命週期 Hook — 12 個事件

Hook 觸發 可阻斷？ 我們有？
PreToolUse 工具執行前 Yes ✅
PostToolUse 工具成功後 No ❌ 可新增
PostToolUseFailure 工具失敗後 No ❌
UserPromptSubmit 用戶提交 No ❌
Stop Agent 停止 Yes ✅
SubagentStart 子代理啟動 No ❌
SubagentStop 子代理完成 Yes ❌
PreCompact 對話壓縮前 No ❌
PermissionRequest 權限對話框 Custom ❌
SessionStart Session 初始化 No ❌ 可新增
SessionEnd Session 結束 No ❌
Notification 狀態通知 No ❌ 可新增

Hook 使用 matcher + callback 模式，matcher 用 regex 匹配工具名稱，支援鏈式執行（deny 優先）。

3. 預算控制 — maxBudgetUsd

每次 query() 設定硬性成本上限：

  • 在 turn 之間（非 mid-generation）檢查累積成本
  • 超過 → subtype: "error_max_budget_usd"
  • SDKResultMessage 包含 total_cost_usd + per-model modelUsage breakdown

我們的差距：只有每日 agent 限額，且存在多任務同時通過檢查的 race condition。

4. Sub-agent 工具隔離

1
2
3
4
5
6
type AgentDefinition = {
  description: string;   // 何時使用此 agent
  prompt: string;        // System prompt
  tools?: string[];      // 限定可用工具（omit = 全部繼承）
  model?: "sonnet" | "opus" | "haiku" | "inherit";
}

常見工具組合：

  • Read-only：["Read", "Grep", "Glob"]
  • Test execution：["Bash", "Read", "Grep"]
  • Full code mod：["Read", "Edit", "Write", "Grep", "Glob"]

我們的差距：所有 worker agent 都是全權限。

5. Session 管理

功能 SDK 我們
Resume resume: sessionId --resume ✅
Fork（原始不變） forkSession: true ❌
Resume at specific point resumeSessionAt: uuid ❌
Continue most recent continue: true ❌

6. File Checkpointing

Write/Edit 前自動備份，每個 user message 產生 checkpoint UUID，可 rewindFiles(id) 恢復。Bash 不追蹤。

比較：我們的 soul-snapshot 更全面（SHA-256 完整性 + Merkle proof），但不支援細粒度 rewind。

7. MCP 整合

4 種傳輸方式：stdio、SSE、HTTP、In-process。

In-process MCP server 特別值得注意：

1
2
3
4
const server = createSdkMcpServer({
  name: "my-tools",
  tools: [tool("get_weather", "...", schema, handler)]
});

工具命名：mcp__<server>__<tool>，支援萬用字元。

8. Structured Outputs

JSON Schema 驗證回應格式，失敗自動重試。結果包含 structured_output 欄位。

9. Async Generator 串流

1
2
3
4
const response = query({ prompt, options });
for await (const msg of response) { /* 7 種 message type */ }
response.interrupt();  // 中斷
response.setModel("sonnet");  // 動態切換模型

10. Custom Tools

tool() helper + createSdkMcpServer() 組合，用 Zod schema 定義輸入驗證。

對比總結

SDK 模式 採用建議 原因
4 層權限 部分採用 我們已有 3 層，補強即可
12 Hook 採用 3 個 PostToolUse, SessionStart, Notification
maxBudgetUsd 採用 修復 race condition
Session fork 不需要 無使用場景
Tool isolation 採用 安全基礎
File Checkpoint 不需要 soul-snapshot 更強
In-process MCP 未來考慮
Structured Output 採用 提升解析可靠性
updatedInput 採用 消除 answer hack

核心洞察：SDK 最值得學的不是 API，是思維模型 — 權限是可組合的、成本是一等公民、工具隔離是安全基礎。