SDK 架构概览

整体架构

Claude Code SDK 是一个模块化、可组合的 TypeScript 库，核心架构分为以下几层：

┌─────────────────────────────────────────────────┐
│                  用户代码                         │
├─────────────────────────────────────────────────┤
│  ask() / askStream()       高级 API              │
├─────────────────────────────────────────────────┤
│  Session Engine      会话管理                     │
│  ┌───────────────────────────────────────────┐   │
│  │ Conversation Manager   对话管理             │   │
│  │ Tool Registry          工具注册与调度       │   │
│  │ Context Builder        上下文构建           │   │
│  │ Permission Manager    权限控制              │   │
│  └───────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│  LLM Connector Layer    多 Provider 适配层        │
│  Anthropic | Bedrock | Vertex | Foundry          │
├─────────────────────────────────────────────────┤
│  Logging | Rate Limit | Config | Hooks           │
│  基础设施层                                      │
└─────────────────────────────────────────────────┘

核心模块

Session Engine

管理会话生命周期，包括创建、持久化、归因和恢复。每个会话包含独立的对话历史和状态。

Conversation Manager

管理对话轮次、token 预算、自动压缩（Auto-Compact）和微压缩（Micro-Compact）。

Tool System

工具注册、执行和结果处理。包含 8 个内置工具和 MCP 协议工具集成。

Context Builder

构建 LLM 请求的上下文，包括 Git 状态、CLAUDE.md 文件、系统提示等。

Permission System

控制工具执行的权限策略，支持 auto/manual/bypass/plan 四种模式。

Config Manager

多源配置管理，支持文件/环境变量/编程三种来源。

Hook System

事件钩子系统，支持在工具调用和 LLM 请求前后插入自定义逻辑。

Logging

调试日志系统，5 级过滤，支持分类过滤和文件/stderr 输出。

设计原则

零运行时依赖 — 核心 SDK 不需要 Claude Code 运行时
模块化 — 按需引入，只 import 需要的功能
TypeScript 优先 — 完整的类型定义和类型安全
可替换 — 每个核心接口都有可替换的实现
渐进式 — 从简单的 ask() 到完整的 Session Engine 逐级深入