OFFICIAL SOURCE ANALYSIS

内部机制

数据迁移、入口点差异、Zod Schema 验证、费用追踪、Deep Link 深度链接。

16. Migrations 数据迁移

随着 Claude Code 版本的迭代，配置格式、数据结构和存储方案可能发生变化。Migrations 系统确保用户从旧版本升级时，其数据能够自动、无损地迁移到新格式。

每个 Migration 是一个编号的脚本，描述了从版本 N 到版本 N+1 的数据转换逻辑。系统在启动时检查当前数据版本与期望版本，如果不匹配则按顺序执行所有中间 Migration。这个过程是自动且幂等的——即使同一个 Migration 被意外执行多次，结果也是一致的。

Migration 覆盖的范围包括：配置文件格式变更（如 JSON schema 变化）、会话数据结构调整、缓存清理（当缓存格式不兼容时）和权限模型升级。用户通常不会感知到 Migration 的存在，除非迁移过程中出现错误需要手动干预。

Migration 执行流程
Claude Code 启动 │ ├─→ 读取本地数据版本号 (stored_version) ├─→ 比较期望版本号 (expected_version) │ ├─ 如果 stored_version == expected_version → 跳过，正常启动 │ ├─ 如果 stored_version < expected_version → │ ├─→ 创建备份快照 │ ├─→ 按顺序执行 migration_N+1, migration_N+2, ... │ ├─→ 验证每步迁移结果 │ └─→ 更新 stored_version │ └─ 如果 stored_version > expected_version → 降级场景，发出警告但不回滚

每个 Migration 在执行前会先创建数据备份。如果迁移过程中出现错误，系统会自动回滚到备份状态，并在下次启动时重试。连续三次失败后，系统会要求用户手动干预。

17. Entrypoints 入口点

Claude Code 有多个入口点（Entrypoint），每个入口点针对不同的使用场景进行了优化。理解入口点的区别有助于理解 Claude Code 在不同环境下的行为差异。

CLI 入口

最常见的入口。用户在终端输入 claude 启动交互式会话，或使用 claude -p "prompt" 进行非交互式调用。CLI 入口会完整初始化终端 UI（Ink 框架）、加载所有 Skill 和 Plugin，并启动交互循环。

SDK 入口

面向程序化调用的入口。开发者可以在 Node.js/Bun 脚本中引入 Claude Code SDK，以编程方式调用其能力。SDK 入口跳过终端 UI 初始化，但保留完整的工具和权限系统。返回值是结构化数据（JSON），而非终端渲染的文本。

Bridge 入口

专为 IDE 集成设计的入口。Bridge 入口启动 Claude Code 为一个后台服务进程，通过 IPC 协议与 IDE 扩展通信。它不初始化终端 UI，但额外初始化 JWT 验证和 WebSocket 服务器。

入口点初始化差异
初始化步骤CLISDKBridge
终端 UI (Ink)✓✗✗
Skill / Plugin 加载✓✓✓
权限系统✓✓✓ + 回调
Feature Flags✓✓✓
JWT 验证✗✗✓
WebSocket Server✗✗✓
交互循环✓✗事件驱动

18. Schemas 验证

Claude Code 使用 Zod v4 作为运行时数据验证库。Zod 提供了 TypeScript-first 的 schema 声明方式，在运行时对数据进行类型安全的验证。这在一个需要处理大量动态数据（模型返回、工具输入、配置文件、用户输入）的系统中至关重要。

Schema 的应用范围覆盖了系统的几乎每一层。工具 Input Schema 定义了每个工具接受的参数格式——当模型生成的工具调用参数不符合 schema 时，系统会拒绝执行并告知模型错误原因。配置 Schema 验证用户配置文件的格式，防止配置错误导致运行时崩溃。消息类型 Schema 确保系统内部消息传递的类型安全。

Zod v4 相比 v3 在性能上有显著提升（解析速度提高约 2 倍），这对 Claude Code 这种每次工具调用都需要验证参数的系统来说非常重要。Schema 定义还被复用于生成模型可见的工具描述——模型看到的工具参数说明直接来源于 Zod schema，确保了文档和实现的一致性。

Schema 在各层的应用
层Schema 对象验证内容
工具层Tool Input Schema模型生成的工具调用参数
配置层Config Schemasettings.json、CLAUDE.md 结构化部分
消息层Message Schema内部消息格式、API 请求/响应
插件层Plugin Manifest Schema插件元数据和接口声明
迁移层Migration Schema数据版本和迁移脚本声明

19. Cost Tracking 费用追踪

Claude Code 内置了详细的费用追踪系统。每次 API 调用的 token 消耗会被实时记录，并根据当前使用的模型和定价策略计算费用。这让用户对使用成本有清晰的认知，避免意外的高额账单。

通过 /cost 命令，用户可以随时查看当前会话的累计费用，包括输入 token 数、输出 token 数、缓存命中情况和对应的美元金额。系统支持多种模型（如 Claude Opus、Sonnet、Haiku），每种模型有不同的定价，费用计算会根据实际使用的模型自动调整。

费用追踪还与 Policy Limits 集成。当会话费用接近管理员设定的预算上限时，系统会发出警告；达到上限时会阻止进一步的 API 调用。这为企业用户提供了自动化的成本控制机制。

费用计算公式
会话总费用 = Σ (每次调用的 input_tokens × 模型输入单价 + 每次调用的 output_tokens × 模型输出单价 - cache_hit_tokens × 缓存折扣)
/cost 命令输出示例
╭─ Session Cost Summary ─────────────────────╮ │ Model: claude-sonnet-4-20250514 │ │ API Calls: 12 │ │ Input: 45,230 tokens ($0.135) │ │ Output: 12,840 tokens ($0.077) │ │ Cache Hits: 28,100 tokens (-$0.042) │ │ ─────────────────────────────────────────── │ │ Total: $0.170 │ │ Budget: $5.00 remaining (policy limit) │ ╰──────────────────────────────────────────────╯

费用数据在会话结束后也会被持久化，用户可以通过历史记录查看过去每次会话的费用明细。这些数据对于团队的成本分析和预算规划非常有价值。

Deep Link 功能允许外部应用通过 URL scheme 直接打开 Claude Code 并跳转到特定的状态或操作。例如，一个 CI/CD 系统可以在构建失败时生成一个 Deep Link，用户点击后 Claude Code 会自动打开并加载相关的错误上下文。

Deep Link 使用自定义的 URL scheme（如 claude-code://），操作系统会将匹配的 URL 路由到 Claude Code 进程。URL 中可以编码多种信息：要打开的项目路径、要执行的初始命令、要加载的会话 ID 等。

这个功能的一个重要应用场景是 IDE 和 Web 界面的联动。开发者在 Web 上的代码审查工具中看到一个问题时，可以点击"在 Claude Code 中打开"的链接，直接在终端中启动一个已经加载了相关上下文的 Claude Code 会话。这种无缝跳转减少了手动设置上下文的摩擦。

Deep Link URL 结构
claude-code://action?param1=value1&param2=value2 示例： claude-code://open?project=/path/to/repo&prompt=fix+the+build+error claude-code://session?id=abc123 claude-code://command?run=/review-pr+456

Deep Link 处理器在 Claude Code 启动时注册到操作系统。如果 Claude Code 已经在运行，新的 Deep Link 会被传递到现有进程；如果没有运行，系统会先启动 Claude Code 再处理链接内容。

17. Entrypoints 入口点

Claude Code 有多个入口点（Entrypoint），每个入口点针对不同的使用场景进行了优化。理解入口点的区别有助于理解 Claude Code 在不同环境下的行为差异。

CLI 入口

最常见的入口。用户在终端输入 claude 启动交互式会话，或使用 claude -p "prompt" 进行非交互式调用。CLI 入口会完整初始化终端 UI（Ink 框架）、加载所有 Skill 和 Plugin，并启动交互循环。

SDK 入口

面向程序化调用的入口。开发者可以在 Node.js/Bun 脚本中引入 Claude Code SDK，以编程方式调用其能力。SDK 入口跳过终端 UI 初始化，但保留完整的工具和权限系统。返回值是结构化数据（JSON），而非终端渲染的文本。

Bridge 入口

专为 IDE 集成设计的入口。Bridge 入口启动 Claude Code 为一个后台服务进程，通过 IPC 协议与 IDE 扩展通信。它不初始化终端 UI，但额外初始化 JWT 验证和 WebSocket 服务器。

入口点初始化差异
初始化步骤CLISDKBridge
终端 UI (Ink)✓✗✗
Skill / Plugin 加载✓✓✓
权限系统✓✓✓ + 回调
Feature Flags✓✓✓
JWT 验证✗✗✓
WebSocket Server✗✗✓
交互循环✓✗事件驱动

18. Schemas 验证

Claude Code 使用 Zod v4 作为运行时数据验证库。Zod 提供了 TypeScript-first 的 schema 声明方式，在运行时对数据进行类型安全的验证。这在一个需要处理大量动态数据（模型返回、工具输入、配置文件、用户输入）的系统中至关重要。

Schema 的应用范围覆盖了系统的几乎每一层。工具 Input Schema 定义了每个工具接受的参数格式——当模型生成的工具调用参数不符合 schema 时，系统会拒绝执行并告知模型错误原因。配置 Schema 验证用户配置文件的格式，防止配置错误导致运行时崩溃。消息类型 Schema 确保系统内部消息传递的类型安全。

Zod v4 相比 v3 在性能上有显著提升（解析速度提高约 2 倍），这对 Claude Code 这种每次工具调用都需要验证参数的系统来说非常重要。Schema 定义还被复用于生成模型可见的工具描述——模型看到的工具参数说明直接来源于 Zod schema，确保了文档和实现的一致性。

Schema 在各层的应用
层Schema 对象验证内容
工具层Tool Input Schema模型生成的工具调用参数
配置层Config Schemasettings.json、CLAUDE.md 结构化部分
消息层Message Schema内部消息格式、API 请求/响应
插件层Plugin Manifest Schema插件元数据和接口声明
迁移层Migration Schema数据版本和迁移脚本声明

19. Cost Tracking 费用追踪

Claude Code 内置了详细的费用追踪系统。每次 API 调用的 token 消耗会被实时记录，并根据当前使用的模型和定价策略计算费用。这让用户对使用成本有清晰的认知，避免意外的高额账单。

通过 /cost 命令，用户可以随时查看当前会话的累计费用，包括输入 token 数、输出 token 数、缓存命中情况和对应的美元金额。系统支持多种模型（如 Claude Opus、Sonnet、Haiku），每种模型有不同的定价，费用计算会根据实际使用的模型自动调整。

费用追踪还与 Policy Limits 集成。当会话费用接近管理员设定的预算上限时，系统会发出警告；达到上限时会阻止进一步的 API 调用。这为企业用户提供了自动化的成本控制机制。

费用计算公式
会话总费用 = Σ (每次调用的 input_tokens × 模型输入单价 + 每次调用的 output_tokens × 模型输出单价 - cache_hit_tokens × 缓存折扣)
/cost 命令输出示例
╭─ Session Cost Summary ─────────────────────╮ │ Model: claude-sonnet-4-20250514 │ │ API Calls: 12 │ │ Input: 45,230 tokens ($0.135) │ │ Output: 12,840 tokens ($0.077) │ │ Cache Hits: 28,100 tokens (-$0.042) │ │ ─────────────────────────────────────────── │ │ Total: $0.170 │ │ Budget: $5.00 remaining (policy limit) │ ╰──────────────────────────────────────────────╯

费用数据在会话结束后也会被持久化，用户可以通过历史记录查看过去每次会话的费用明细。这些数据对于团队的成本分析和预算规划非常有价值。

Deep Link 功能允许外部应用通过 URL scheme 直接打开 Claude Code 并跳转到特定的状态或操作。例如，一个 CI/CD 系统可以在构建失败时生成一个 Deep Link，用户点击后 Claude Code 会自动打开并加载相关的错误上下文。

Deep Link 使用自定义的 URL scheme（如 claude-code://），操作系统会将匹配的 URL 路由到 Claude Code 进程。URL 中可以编码多种信息：要打开的项目路径、要执行的初始命令、要加载的会话 ID 等。

这个功能的一个重要应用场景是 IDE 和 Web 界面的联动。开发者在 Web 上的代码审查工具中看到一个问题时，可以点击"在 Claude Code 中打开"的链接，直接在终端中启动一个已经加载了相关上下文的 Claude Code 会话。这种无缝跳转减少了手动设置上下文的摩擦。

Deep Link URL 结构
claude-code://action?param1=value1&param2=value2 示例： claude-code://open?project=/path/to/repo&prompt=fix+the+build+error claude-code://session?id=abc123 claude-code://command?run=/review-pr+456

Deep Link 处理器在 Claude Code 启动时注册到操作系统。如果 Claude Code 已经在运行，新的 Deep Link 会被传递到现有进程；如果没有运行，系统会先启动 Claude Code 再处理链接内容。

18. Schemas 验证

Claude Code 使用 Zod v4 作为运行时数据验证库。Zod 提供了 TypeScript-first 的 schema 声明方式，在运行时对数据进行类型安全的验证。这在一个需要处理大量动态数据（模型返回、工具输入、配置文件、用户输入）的系统中至关重要。

Schema 的应用范围覆盖了系统的几乎每一层。工具 Input Schema 定义了每个工具接受的参数格式——当模型生成的工具调用参数不符合 schema 时，系统会拒绝执行并告知模型错误原因。配置 Schema 验证用户配置文件的格式，防止配置错误导致运行时崩溃。消息类型 Schema 确保系统内部消息传递的类型安全。

Zod v4 相比 v3 在性能上有显著提升（解析速度提高约 2 倍），这对 Claude Code 这种每次工具调用都需要验证参数的系统来说非常重要。Schema 定义还被复用于生成模型可见的工具描述——模型看到的工具参数说明直接来源于 Zod schema，确保了文档和实现的一致性。

Schema 在各层的应用
层Schema 对象验证内容
工具层Tool Input Schema模型生成的工具调用参数
配置层Config Schemasettings.json、CLAUDE.md 结构化部分
消息层Message Schema内部消息格式、API 请求/响应
插件层Plugin Manifest Schema插件元数据和接口声明
迁移层Migration Schema数据版本和迁移脚本声明

19. Cost Tracking 费用追踪

Claude Code 内置了详细的费用追踪系统。每次 API 调用的 token 消耗会被实时记录，并根据当前使用的模型和定价策略计算费用。这让用户对使用成本有清晰的认知，避免意外的高额账单。

通过 /cost 命令，用户可以随时查看当前会话的累计费用，包括输入 token 数、输出 token 数、缓存命中情况和对应的美元金额。系统支持多种模型（如 Claude Opus、Sonnet、Haiku），每种模型有不同的定价，费用计算会根据实际使用的模型自动调整。

费用追踪还与 Policy Limits 集成。当会话费用接近管理员设定的预算上限时，系统会发出警告；达到上限时会阻止进一步的 API 调用。这为企业用户提供了自动化的成本控制机制。

费用计算公式
会话总费用 = Σ (每次调用的 input_tokens × 模型输入单价 + 每次调用的 output_tokens × 模型输出单价 - cache_hit_tokens × 缓存折扣)
/cost 命令输出示例
╭─ Session Cost Summary ─────────────────────╮ │ Model: claude-sonnet-4-20250514 │ │ API Calls: 12 │ │ Input: 45,230 tokens ($0.135) │ │ Output: 12,840 tokens ($0.077) │ │ Cache Hits: 28,100 tokens (-$0.042) │ │ ─────────────────────────────────────────── │ │ Total: $0.170 │ │ Budget: $5.00 remaining (policy limit) │ ╰──────────────────────────────────────────────╯

费用数据在会话结束后也会被持久化，用户可以通过历史记录查看过去每次会话的费用明细。这些数据对于团队的成本分析和预算规划非常有价值。

Deep Link 功能允许外部应用通过 URL scheme 直接打开 Claude Code 并跳转到特定的状态或操作。例如，一个 CI/CD 系统可以在构建失败时生成一个 Deep Link，用户点击后 Claude Code 会自动打开并加载相关的错误上下文。

Deep Link 使用自定义的 URL scheme（如 claude-code://），操作系统会将匹配的 URL 路由到 Claude Code 进程。URL 中可以编码多种信息：要打开的项目路径、要执行的初始命令、要加载的会话 ID 等。

这个功能的一个重要应用场景是 IDE 和 Web 界面的联动。开发者在 Web 上的代码审查工具中看到一个问题时，可以点击"在 Claude Code 中打开"的链接，直接在终端中启动一个已经加载了相关上下文的 Claude Code 会话。这种无缝跳转减少了手动设置上下文的摩擦。

Deep Link URL 结构
claude-code://action?param1=value1&param2=value2 示例： claude-code://open?project=/path/to/repo&prompt=fix+the+build+error claude-code://session?id=abc123 claude-code://command?run=/review-pr+456

Deep Link 处理器在 Claude Code 启动时注册到操作系统。如果 Claude Code 已经在运行，新的 Deep Link 会被传递到现有进程；如果没有运行，系统会先启动 Claude Code 再处理链接内容。

19. Cost Tracking 费用追踪

Claude Code 内置了详细的费用追踪系统。每次 API 调用的 token 消耗会被实时记录，并根据当前使用的模型和定价策略计算费用。这让用户对使用成本有清晰的认知，避免意外的高额账单。

通过 /cost 命令，用户可以随时查看当前会话的累计费用，包括输入 token 数、输出 token 数、缓存命中情况和对应的美元金额。系统支持多种模型（如 Claude Opus、Sonnet、Haiku），每种模型有不同的定价，费用计算会根据实际使用的模型自动调整。

费用追踪还与 Policy Limits 集成。当会话费用接近管理员设定的预算上限时，系统会发出警告；达到上限时会阻止进一步的 API 调用。这为企业用户提供了自动化的成本控制机制。

费用计算公式
会话总费用 = Σ (每次调用的 input_tokens × 模型输入单价 + 每次调用的 output_tokens × 模型输出单价 - cache_hit_tokens × 缓存折扣)
/cost 命令输出示例
╭─ Session Cost Summary ─────────────────────╮ │ Model: claude-sonnet-4-20250514 │ │ API Calls: 12 │ │ Input: 45,230 tokens ($0.135) │ │ Output: 12,840 tokens ($0.077) │ │ Cache Hits: 28,100 tokens (-$0.042) │ │ ─────────────────────────────────────────── │ │ Total: $0.170 │ │ Budget: $5.00 remaining (policy limit) │ ╰──────────────────────────────────────────────╯

费用数据在会话结束后也会被持久化，用户可以通过历史记录查看过去每次会话的费用明细。这些数据对于团队的成本分析和预算规划非常有价值。

Deep Link 功能允许外部应用通过 URL scheme 直接打开 Claude Code 并跳转到特定的状态或操作。例如，一个 CI/CD 系统可以在构建失败时生成一个 Deep Link，用户点击后 Claude Code 会自动打开并加载相关的错误上下文。

Deep Link 使用自定义的 URL scheme（如 claude-code://），操作系统会将匹配的 URL 路由到 Claude Code 进程。URL 中可以编码多种信息：要打开的项目路径、要执行的初始命令、要加载的会话 ID 等。

这个功能的一个重要应用场景是 IDE 和 Web 界面的联动。开发者在 Web 上的代码审查工具中看到一个问题时，可以点击"在 Claude Code 中打开"的链接，直接在终端中启动一个已经加载了相关上下文的 Claude Code 会话。这种无缝跳转减少了手动设置上下文的摩擦。

Deep Link URL 结构
claude-code://action?param1=value1&param2=value2 示例： claude-code://open?project=/path/to/repo&prompt=fix+the+build+error claude-code://session?id=abc123 claude-code://command?run=/review-pr+456

Deep Link 处理器在 Claude Code 启动时注册到操作系统。如果 Claude Code 已经在运行，新的 Deep Link 会被传递到现有进程；如果没有运行，系统会先启动 Claude Code 再处理链接内容。

Deep Link 功能允许外部应用通过 URL scheme 直接打开 Claude Code 并跳转到特定的状态或操作。例如，一个 CI/CD 系统可以在构建失败时生成一个 Deep Link，用户点击后 Claude Code 会自动打开并加载相关的错误上下文。

Deep Link 使用自定义的 URL scheme（如 claude-code://），操作系统会将匹配的 URL 路由到 Claude Code 进程。URL 中可以编码多种信息：要打开的项目路径、要执行的初始命令、要加载的会话 ID 等。

这个功能的一个重要应用场景是 IDE 和 Web 界面的联动。开发者在 Web 上的代码审查工具中看到一个问题时，可以点击"在 Claude Code 中打开"的链接，直接在终端中启动一个已经加载了相关上下文的 Claude Code 会话。这种无缝跳转减少了手动设置上下文的摩擦。

Deep Link URL 结构
claude-code://action?param1=value1&param2=value2 示例： claude-code://open?project=/path/to/repo&prompt=fix+the+build+error claude-code://session?id=abc123 claude-code://command?run=/review-pr+456

Deep Link 处理器在 Claude Code 启动时注册到操作系统。如果 Claude Code 已经在运行，新的 Deep Link 会被传递到现有进程；如果没有运行，系统会先启动 Claude Code 再处理链接内容。

← 上一章
终端 UI
Ink 框架 · 390+ 组件
下一章 →
S01: Agent Loop
一个循环 + Bash = 一个 Agent