Claude Code 源码核心技术深度解析

文档概述

本文档对 Claude Code（当前项目为Claw Codes 是Anthropic 把自家 Claude Code 的源码，打包进了 npm 发布包里）进行全面的技术深度解析。作为一个复杂的智能体开发框架，Claude Code 融合了多模型支持、多智能体协作、精细化权限控制、上下文管理、智能工具系统等核心技术。本文档面向具备一定 AI 和系统设计背景的技术人员，旨在提供对框架内部机制的深入理解。

地址：github.com/instructkr/... 不到24小时stars破100k。

---

第一部分：项目定位与设计哲学

1.1 项目起源与定位

Claude Code 起源于对 Claude.ai 网页版 AI 助手的桌面增强需求。不同于传统的命令行工具，Claude Code 被设计为一个全功能的智能体开发平台，支持复杂的软件工程任务、多步骤工作流、多智能体协作等高级场景。

Claw Codes 作为其开源分支，继承并延续了这一设计理念。根据项目文档，其核心目标是构建"更好的工具化执行系统，专注于执行能力而非单纯的代码存储"。这一定位反映了项目对实际效用的重视，而非追求代码结构的完整性。

1.2 设计哲学

Claude Code 的设计哲学可以概括为以下几点：

1. 执行优先（Execution First） 项目强调执行能力的重要性。传统的 AI 编程工具往往侧重于代码生成，而 Claude Code 着力于构建一个能够真正执行复杂任务的智能体系统。这体现在其强大的工具系统、多智能体协作、精细的权限控制等各个方面。

2. 模块化与可扩展性 系统采用高度模块化的设计。从命令系统到工具系统，从桥接层到状态管理层，每个子系统都有清晰的边界和定义的接口。这种设计允许开发者相对独立地扩展或替换各个组件，而不影响整体系统的稳定性。

3. 安全第一 作为一个需要执行用户代码、在用户文件系统中进行操作的系统，安全是设计中的首要考量。Claude Code 实现了多层次的安全机制，包括权限模式分类、命令验证、沙箱执行、安全分类器等，确保系统在提供便利性的同时不牺牲安全性。

4. 开发者体验优先 无论是交互式界面、调试工具，还是详细的日志系统和错误处理，Claude Code 都将开发者体验作为重要考量。这体现在 /doctor 诊断命令、详细的错误信息、结构化的输出格式等方面。

---

第二部分：系统架构总览

2.1 整体架构分层

Claude Code 采用分层架构设计，各层之间通过清晰定义的接口通信。整体架构可以划分为以下八个核心层次：

┌─────────────────────────────────────────────────────────┐
│                    入口层 (Entrypoints)                  │
│        agentSdkTypes.ts, init.ts, mcp.ts               │
├─────────────────────────────────────────────────────────┤
│                    桥接层 (Bridge)                       │
│    bridgeMain.ts, replBridge.ts, bridgeMessaging.ts     │
├─────────────────────────────────────────────────────────┤
│                   命令层 (Commands)                      │
│         100+ 命令，涵盖所有用户交互功能                  │
├─────────────────────────────────────────────────────────┤
│                   状态管理层 (State)                     │
│       AppState.tsx, AppStateStore.ts, selectors.ts      │
├─────────────────────────────────────────────────────────┤
│                    工具层 (Tools)                        │
│   AgentTool, BashTool, FileEditTool, MCPTool 等 50+    │
├─────────────────────────────────────────────────────────┤
│                   服务层 (Services)                      │
│  analytics/, api/, compact/, mcp/, SessionMemory/       │
├─────────────────────────────────────────────────────────┤
│                   CLI层 (CLI)                           │
│     handlers/, transports/, structuredIO.ts             │
├─────────────────────────────────────────────────────────┤
│                  组件层 (Components)                     │
│              React 组件，交互式 UI                      │
└─────────────────────────────────────────────────────────┘

2.2 入口层解析

入口层位于 src/entrypoints/，定义了系统与外部环境的交互接口：

agentSdkTypes.ts 定义了整个 SDK 的类型系统，包括：

• PermissionMode：权限模式枚举（default, bypass, plan, auto 等）
• SDKMessage：SDK 消息类型体系
• SDKStatus：SDK 状态类型
• SDKControlRequest/Response：控制请求和响应类型

init.ts 处理系统初始化流程，包括环境检测、配置加载、早期初始化等。

mcp.ts 实现了 Model Context Protocol 的入口逻辑，支持与 MCP 服务器的连接和通信。

2.3 桥接层------核心通信基础设施

桥接层位于 src/bridge/，是 Claude Code 最复杂和核心的子系统之一。桥接系统负责远程控制、会话管理和客户端与服务器之间的消息路由。

2.3.1 桥接系统职责

桥接系统的核心职责包括：

1. 环境注册：与远程服务器建立环境上下文
2. 会话管理：创建、维护、恢复用户会话
3. 消息路由：在客户端和服务器之间传递消息
4. 工作项轮询：轮询服务器获取分配的工作项
5. 传输协议适配：支持多种传输协议（WebSocket、SSE、HTTP POST）

2.3.2 核心模块

bridgeMain.ts（2400+ 行）是桥接系统的主入口，实现核心逻辑：

// 环境注册流程
const reg = await api.registerBridgeEnvironment(bridgeConfig)
environmentId = reg.environment_id
environmentSecret = reg.environment_secret

// 会话创建
const createdSessionId = await createSession({
  environmentId,
  title,
  gitRepoUrl,
  branch,
  signal: AbortSignal.timeout(15_000),
})

pollConfig.ts 和 pollConfigDefaults.ts 配置轮询机制：

• poll_interval_ms_at_capacity：容量满时的轮询间隔
• poll_interval_ms_not_at_capacity：容量未满时的轮询间隔
• reclaim_older_than_ms：工作项回收阈值
• 心跳间隔配置

bridgeMessaging.ts 处理消息的路由和处理：

• 入站消息过滤和去重
• 服务控制请求处理
• 结果消息构建
• BoundedUUIDSet 用于消息去重

2.3.3 传输协议

桥接系统支持两种主要传输协议：

v1 混合传输（HybridTransport）：

• WebSocket 用于接收服务器推送
• HTTP POST 用于发送事件
• 自动重连机制（指数退避，最多 10 分钟）

v2 CCR 传输：

• 纯 HTTP 实现双向通信
• 适用于严格限制 WebSocket 的网络环境
• 使用 JWT 而非 OAuth 进行认证

2.3.4 崩溃恢复机制

桥接系统实现了完善的崩溃恢复机制：

// crash-recovery pointer 写入
await writeBridgePointer(dir, {
  sessionId: currentSessionId,
  environmentId,
  source: 'repl',
})

// 永久模式下定期刷新指针
const pointerRefreshTimer = setInterval(() => {
  void writeBridgePointer(dir, {
    sessionId: currentSessionId,
    environmentId,
    source: 'repl',
  })
}, 60 * 60_000) // 每小时刷新

2.4 状态管理层

状态管理采用 React 的 Context + useSyncExternalStore 模式。

AppStateStore.ts 定义了完整的状态结构：

interface AppState {
  // 主循环配置
  mainLoopModel: string
  thinkingConfig: ThinkingConfig
  verbose: boolean

  // 工具权限上下文
  toolPermissionContext: ToolPermissionContext

  // MCP 连接
  mcpConnections: MCPServerConnection[]

  // 文件历史
  fileHistory: FileHistoryState

  // 归属信息
  attribution: AttributionState

  // 快速模式状态
  fastMode: FastModeState

  // 任务状态
  tasks: Map<TaskId, TaskState>

  // 设置
  settings: Settings
}

核心特性：

• 不可变更新模式
• 高效的变更检测
• 持久化支持
• 跨组件共享状态

---

第三部分：大模型策略与架构

3.1 多模型支持架构

Claude Code 的模型架构设计支持多个 API 提供商和多种模型选择。

3.1.1 提供商类型

type APIProvider = 'firstParty' | 'bedrock' | 'vertex' | 'foundry'

提供商	环境变量	认证方式
FirstParty（Anthropic）	默认	API Key / OAuth
AWS Bedrock	CLAUDE_CODE_USE_BEDROCK	AWS 凭证 + 刷新逻辑
Google Vertex	CLAUDE_CODE_USE_VERTEX	Google Auth + 项目 ID
Azure Foundry	CLAUDE_CODE_USE_FOUNDRY	Azure AD / API Key

3.1.2 支持的模型

// Haiku 系列
HAIKU_3_5_CONFIG, HAIKU_4_5_CONFIG

// Sonnet 系列
SONNET_3_5_CONFIG, SONNET_3_7_CONFIG, SONNET_4_CONFIG,
SONNET_4_5_CONFIG, SONNET_4_6_CONFIG

// Opus 系列
OPUS_4_CONFIG, OPUS_4_1_CONFIG, OPUS_4_5_CONFIG, OPUS_4_6_CONFIG

每个模型都有提供商特定的标识符：

CLAUDE_OPUS_4_6_CONFIG = {
  firstParty: 'claude-opus-4-6',
  bedrock: 'us.anthropic.claude-opus-4-6-v1',
  vertex: 'claude-opus-4-6',
  foundry: 'claude-opus-4-6',
}

3.2 模型选择策略

3.2.1 选择优先级

用户会话中覆盖 (/model 命令)  ← 最高优先级
启动时覆盖 (--model 参数)
环境变量 (ANTHROPIC_MODEL)
用户保存的设置
内置默认值（基于订阅等级）

3.2.2 模型别名系统

MODEL_ALIASES = ['sonnet', 'opus', 'haiku', 'best', 'sonnet[1m]', 'opus[1m]', 'opusplan']

[1m] 后缀启用 100 万 token 的上下文窗口。

3.3 API 客户端架构

client.ts 实现了统一的 API 客户端工厂：

getAnthropicClient()  // 根据提供商创建合适的客户端

关键特性：

• 认证处理（每个提供商不同）
• 代理支持
• 请求 ID 追踪
• 超时配置（默认 600 秒）
• 区域处理（Bedrock/Vertex）

3.4 重试与回退逻辑

3.4.1 重试机制

// withRetry.ts 实现
withRetry()  // AsyncGenerator 实现指数退避重试

// 默认参数
maxRetries: 10
baseDelay: 500ms
maxDelay: 32s

可重试的错误：

• 429（速率限制）
• 529（过载）
• 401/403（令牌刷新后重试）
• 408, 409
• 5xx 服务器错误
• 连接错误（ECONNRESET, EPIPE）

3.4.2 模型回退

当遇到 3 次连续的 529 错误且使用非自定义 Opus 模型时，触发模型回退：

// FallbackTriggeredError 特殊错误
// Opus 4.6 失败 → 回退到 Opus 4.1
// Sonnet 4.6 失败 → 回退到 Sonnet 4.5

3.5 令牌使用与成本管理

3.5.1 定价表

MODEL_COSTS = {
  // Sonnet/Haiku 3.5
  'sonnet_3_5': { input: 3, output: 15 },  // $/Mtok
  'haiku_3_5': { input: 0.80, output: 4 },

  // Opus 4/4.1
  'opus_4': { input: 15, output: 75 },
  'opus_4_1': { input: 15, output: 75 },

  // Opus 4.5（降价）
  'opus_4_5': { input: 5, output: 25 },

  // Opus 4.6
  'opus_4_6': { input: 5, output: 25 },
  'opus_4_6_fast': { input: 30, output: 150 },  // Fast 模式

  // Haiku 4.5
  'haiku_4_5': { input: 1, output: 5 },
}

3.5.2 会话成本追踪

interface SessionCost {
  totalCostUsd: number
  inputTokens: number
  outputTokens: number
  cacheReadTokens: number
  cacheWriteTokens: number
  webSearchRequests: number
  linesAdded: number
  linesRemoved: number
  apiDurationMs: number
}

3.6 Beta 功能管理

Claude Code 通过 Beta 头支持实验性功能：

getModelBetas()  // 获取模型的 beta 头

// 关键 Beta 功能
CLAUDE_CODE_20250219_BETA_HEADER     // Claude Code 核心 beta
CONTEXT_1M_BETA_HEADER              // 100 万上下文
INTERLEAVED_THINKING_BETA_HEADER     // Thinking 块穿插
PROMPT_CACHING_SCOPE_BETA_HEADER    // Prompt 缓存
WEB_SEARCH_BETA_HEADER              // Web 搜索
TOOL_SEARCH_BETA_HEADER             // 工具搜索
STRUCTURED_OUTPUTS_BETA_HEADER      // 结构化输出

---

第四部分：核心业务流程

4.1 用户输入处理流程

用户输入的处理流程是 Claude Code 最核心的业务流程之一。

4.1.1 入口：processUserInput

// src/utils/processUserInput/processUserInput.ts
async function processUserInput({
  input,
  mode,
  setToolJSX,
  context,
  messages,
  uuid,
  isMeta,
  querySource,
}) {
  // 1. 处理斜杠命令
  // 2. 处理 Bash 命令
  // 3. 处理文本提示
  // 4. 返回消息数组、是否需要查询、允许的工具列表
}

4.1.2 斜杠命令处理

斜杠命令（以 / 开头的命令）通过专门的命令处理系统执行：

// 命令类型
type CommandType = 'prompt' | 'local' | 'local-jsx'

// 命令执行流程
const command = findCommand(commandName, commands)
if (command.type === 'prompt') {
  // 返回提示词内容，发送给模型
  const prompt = await command.getPromptForCommand(args, context)
  return { messages: [userMessage(prompt)], shouldQuery: true }
} else if (command.type === 'local') {
  // 本地执行，返回结果
  const result = await command.execute(args, context)
  return { messages: [systemMessage(result)], shouldQuery: false }
}

4.2 主查询循环

4.2.1 QueryEngine 类

// src/QueryEngine.ts
export class QueryEngine {
  async *submitMessage(
    prompt: string | ContentBlockParam[],
    options?: { uuid?: string; isMeta?: boolean },
  ): AsyncGenerator<SDKMessage, void, unknown> {
    // 1. 处理用户输入
    // 2. 构建系统提示
    // 3. 执行查询循环
    // 4. 处理结果和进度消息
  }
}

4.2.2 query.ts 核心循环

// src/query.ts
async function* query(params: QueryParams): AsyncGenerator<Message> {
  let state: State = {
    messages: params.messages,
    turnCount: 1,
    // ...
  }

  while (true) {
    // 1. 调用模型
    for await (const message of callModel(...)) {
      yield message

      if (isFinalResponse(message)) {
        return  // 完成
      }

      // 2. 执行工具
      const toolResults = await runTools(toolCalls, ...)

      // 3. 将工具结果添加到消息
      state = {
        messages: [...state.messages, ...toolResults],
        turnCount: state.turnCount + 1,
      }
    }
  }
}

4.3 工具执行流程

4.3.1 工具编排

// src/services/tools/toolOrchestration.ts
async function runTools(
  toolUseBlocks: ToolUseBlock[],
  assistantMessages: AssistantMessage[],
  canUseTool: CanUseToolFn,
  toolUseContext: ToolUseContext,
) {
  // 1. 将工具分批
  const { serialTools, concurrentTools } = partitionTools(toolUseBlocks)

  // 2. 并发执行只读工具
  const concurrentResults = await runToolsConcurrently(concurrentTools, ...)

  // 3. 串行执行写操作工具
  const serialResults = await runToolsSerially(serialTools, ...)

  // 4. 合并结果
  return [...concurrentResults, ...serialResults]
}

4.3.2 工具权限检查

// 权限检查流程
async function hasPermissionsToUseTool(
  tool: Tool,
  input: unknown,
  context: ToolPermissionContext,
): Promise<PermissionResult> {
  // 步骤 1: 规则检查
  if (isDeniedByRule(tool, input)) return { behavior: 'deny' }
  if (isAlwaysAllowedByRule(tool, input)) return { behavior: 'allow' }

  // 步骤 2: 模式检查
  if (context.mode === 'bypassPermissions') return { behavior: 'allow' }

  // 步骤 3: 工具特定检查
  return tool.checkPermissions(input, context)
}

4.4 流式响应处理

Claude Code 使用流式 API 响应，需要特殊处理：

// src/QueryEngine.ts 中的流事件处理
case 'stream_event':
  if (message.event.type === 'message_start') {
    // 新的消息开始，重置使用量追踪
    currentMessageUsage = EMPTY_USAGE
  }

  if (message.event.type === 'message_delta') {
    // 捕获 stop_reason
    if (message.event.delta.stop_reason != null) {
      lastStopReason = message.event.delta.stop_reason
    }
    // 累积使用量
    currentMessageUsage = updateUsage(
      currentMessageUsage,
      message.event.usage,
    )
  }

  if (message.event.type === 'message_stop') {
    // 消息结束，累积到总会话使用量
    this.totalUsage = accumulateUsage(
      this.totalUsage,
      currentMessageUsage,
    )
  }

4.5 会话持久化

会话状态通过多个机制持久化：

// transcript 记录
await recordTranscript(messages)

// 及时刷新（关键会话）
if (isEnvTruthy(process.env.CLAUDE_CODE_EAGER_FLUSH)) {
  await flushSessionStorage()
}

// 崩溃恢复指针
await writeBridgePointer(dir, {
  sessionId: currentSessionId,
  environmentId,
  source: 'repl',
})

---

第五部分：多智能体系统

5.1 智能体类型架构

Claude Code 支持多种智能体执行模式：

type TaskType =
  | 'local_bash'           // 本地 Shell 命令
  | 'local_agent'          // 本地后台智能体
  | 'remote_agent'         // 远程 CCR 会话
  | 'in_process_teammate'  // 进程内队友
  | 'local_workflow'       // 本地工作流
  | 'monitor_mcp'         // MCP 服务器监控
  | 'dream'                // Ultraplan 会话

5.2 Fork 子智能体

Fork 模式允许从主会话创建子智能体：

// src/tools/AgentTool/forkSubagent.ts
async function forkSubagent({
  directive,
  assistantMessage,
  parentContext,
}) {
  // 1. 检测递归 Fork（防止无限循环）
  if (hasForkBoilerplate(messages)) {
    throw new Error('Recursive fork detected')
  }

  // 2. 构建子智能体消息
  const childMessages = buildForkedMessages(directive, assistantMessage)

  // 3. 继承父级系统提示
  childMessages.systemPrompt = parentContext.renderedSystemPrompt

  // 4. 在后台启动
  return runInProcessTeammate(childMessages)
}

5.3 进程内队友协作

进程内队友使用 AsyncLocalStorage 实现上下文隔离：

// src/utils/teammateContext.ts
export type TeammateContext = {
  agentId: string           // 例如 "researcher@my-team"
  agentName: string         // 例如 "researcher"
  teamName: string
  color?: string
  planModeRequired: boolean
  parentSessionId: string
  isInProcess: true
  abortController: AbortController
}

// 使用 AsyncLocalStorage 实现
const teammateStore = new AsyncLocalStorage<TeammateContext>()

function runWithTeammateContext(
  context: TeammateContext,
  fn: () => Promise<void>,
) {
  return teammateStore.run(context, fn)
}

5.4 基于文件的邮箱系统

队友之间通过文件系统传递消息：

// src/utils/teammateMailbox.ts
// 消息存储路径
~/.claude/teams/{team_name}/inboxes/{agent_name}.json

// 消息类型
type TeammateMessage =
  | IdleNotificationMessage      // 空闲通知
  | PermissionRequestMessage    // 权限请求
  | ShutdownRequestMessage      // 关闭请求
  | TaskAssignmentMessage       // 任务分配
  | PlanApprovalRequestMessage  // 计划审批请求

消息轮询：

// src/hooks/useInboxPoller.ts
// 每秒轮询一次新消息
setInterval(async () => {
  const messages = await readUnreadMessages(agentName, teamName)
  for (const msg of messages) {
    await handleMessage(msg)
  }
}, 1000)

5.5 进程-based 执行（Tmux/iTerm2）

对于需要可视化分离的队友：

// src/utils/swarm/backends/TmuxBackend.ts
async function createTmuxTeammate(agentName: string, config: TeammateConfig) {
  // 1. 在 tmux 中创建新窗格
  await exec(`tmux split-window -h -t claude-swarm`)

  // 2. 在新窗格中启动队友进程
  await exec(`tmux send-keys -t claude-swame 'claude --agent ${agentName}' Enter`)
}

5.6 远程智能体执行

远程会话使用专门的协调协议：

// src/tasks/RemoteAgentTask/RemoteAgentTask.tsx
async function pollRemoteSessionEvents(sessionId: string) {
  // 1. 初始获取
  const session = await fetchSession(sessionId)

  // 2. 轮询事件
  while (!session.isComplete) {
    const events = await pollRemoteSessionEvents(sessionId)
    for (const event of events) {
      await handleRemoteEvent(event)
    }
    await sleep(pollInterval)
  }
}

---

第六部分：上下文与系统提示管理

6.1 系统提示构建

系统提示是 Claude Code 最重要的上下文来源之一：

// src/constants/prompts.ts
async function getSystemPrompt(options: {
  tools: Tools
  mainLoopModel: string
  additionalWorkingDirectories: string[]
  mcpClients: MCPServerConnection[]
}): Promise<string[]> {
  return [
    // 静态部分（可缓存）
    getSimpleIntroSection(),
    getSimpleSystemSection(),
    getUsingYourToolsSection(),
    // 动态部分（会话特定）
    getSessionGuidanceSection(),
    getMemorySection(),
    getMcpInstructionsSection(),
    getScratchpadSection(),
    // ...
  ]
}

6.2 CLAUDE.md 内存文件系统

CLAUDE.md 文件提供项目级和用户级的自定义指令：

// 文件加载顺序（优先级从低到高）
// 1. 全局管理内存 /etc/claude-code/CLAUDE.md
// 2. 用户内存 ~/.claude/CLAUDE.md
// 3. 项目内存 CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md
// 4. 本地内存 CLAUDE.local.md

interface MemoryFileInfo {
  path: string
  type: 'managed' | 'user' | 'project' | 'local'
  content: string
  frontmatter?: { paths?: string[] }
}

@include 指令支持

// 支持的语法
@path                          // 基础路径
@./relative/path               // 相对路径
@~/home/path                   // 用户目录路径
@/absolute/path                // 绝对路径

6.3 Prompt 缓存

系统实现了精细的 Prompt 缓存机制：

// src/constants/systemPromptSections.ts
type SystemPromptSection = {
  name: string
  compute: ComputeFn
  cacheBreak: boolean  // 每次重新计算
}

// 缓存键分离
const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'
// 边界之前 → scope: 'global'（全局缓存）
// 边界之后 → 会话特定

缓存破坏检测

// src/services/api/promptCacheBreakDetection.ts
async function checkResponseForCacheBreak(
  beforeState: PromptState,
  afterState: PromptState,
  response: ModelResponse,
) {
  // 检测缓存命中率下降
  const cacheHitRatio = response.cacheCreation /
                        response.cacheRead

  if (cacheHitRatio < 0.95) {
    // 缓存被破坏，分析原因
    const cause = categorizeCacheBreak(beforeState, afterState)
    logCacheBreak({ cause, tokens: response.cacheRead })
  }
}

6.4 上下文窗口管理

// 获取模型的上下文窗口
getContextWindowForModel(model: string): number {
  // 基础模型：200K tokens
  // [1m] 后缀：1M tokens
}

// 上下文超限处理
if (error.message.includes('input length exceeds context limit')) {
  // 减少 max_tokens 重新尝试
  const availableContext = getContextWindowForModel(model)
  const newMaxTokens = Math.floor(availableContext * 0.8)
  // 重试
}

---

第七部分：安全与权限系统

7.1 权限模式架构

Claude Code 实现了多层次的权限控制：

// 外部可见模式
type ExternalPermissionMode =
  | 'default'       // 询问用户
  | 'acceptEdits'   // 自动接受编辑
  | 'bypassPermissions'  // 绕过所有检查
  | 'dontAsk'       // 不询问
  | 'plan'          // 计划模式

// 内部模式
type InternalPermissionMode = ExternalPermissionMode | 'auto' | 'bubble'

7.2 权限检查流程

权限检查是一个多步骤的管道：

// src/utils/permissions/permissions.ts
async function hasPermissionsToUseTool(
  tool: Tool,
  input: unknown,
  context: ToolPermissionContext,
): Promise<PermissionResult> {
  // 步骤 1: 规则检查
  // 1a. 整体工具拒绝规则
  if (isDeniedByRule(tool)) return { behavior: 'deny' }

  // 1b. 整体工具允许规则
  if (isAlwaysAllowedByRule(tool)) return { behavior: 'allow' }

  // 步骤 2: 模式检查
  if (context.mode === 'bypassPermissions') return { behavior: 'allow' }

  // 步骤 3: 工具特定检查
  return tool.checkPermissions(input, context)
}

7.3 自动模式分类器

自动模式使用两阶段 XML 分类器：

// src/utils/permissions/yoloClassifier.ts

// 阶段 1: 快速路径（max_tokens=64）
const fastResult = await classify(tool, input, {
  max_tokens: 64,
  stop_sequences: ['</block>'],
})

if (fastResult === 'allow') return { behavior: 'allow' }

// 阶段 2: 思考模式（max_tokens=4096）
const detailedResult = await classifyWithThinking(tool, input, {
  max_tokens: 4096,
})

// 返回结构化结果
return {
  behavior: detailedResult.decision,
  reason: detailedResult.reason,
}

7.4 Bash 安全验证

// src/tools/BashTool/bashSecurity.ts

// 危险命令替换模式
const COMMAND_SUBSTITUTION_PATTERNS = [
  { pattern: /<\(/, message: 'process substitution <()' },
  { pattern: />\(/, message: 'process substitution >()' },
  { pattern: /\$\(/, message: '$() command substitution' },
  { pattern: /\$\{/, message: '${} parameter substitution' },
]

// Zsh 危险命令
const ZSH_DANGEROUS_COMMANDS = new Set([
  'zmodload', 'emulate', 'sysopen', 'sysread', 'syswrite',
  'zpty', 'ztcp', 'zsocket', 'mapfile',
])

// 安全的环境变量白名单
const SAFE_ENV_VARS = new Set([
  'TERM', 'TZ', 'LANG', 'LC_ALL',
  'GOEXPERIMENT', 'GOOS', 'GOARCH',  // Go
  'RUST_BACKTRACE', 'RUST_LOG',     // Rust
  'NODE_ENV',                        // Node
])

7.5 沙箱执行

// src/utils/sandbox/sandbox-adapter.ts
interface ISandboxManager {
  isSandboxingEnabled(): boolean
  wrapWithSandbox(
    command: string,
    binShell?: string,
    customConfig?: Partial<SandboxRuntimeConfig>,
  ): Promise<string>
  getFsWriteConfig(): FsWriteRestrictionConfig
}

// 危险路径保护
const DANGEROUS_FILES = [
  '.gitconfig', '.gitmodules', '.bashrc', '.bash_profile',
  '.zshrc', '.zprofile', '.profile', '.ripgreprc',
  '.mcp.json', '.claude.json'
]

7.6 路径遍历保护

// Windows NTFS 危险模式检测
function hasSuspiciousWindowsPathPattern(path: string): boolean {
  // Alternate Data Streams: file.txt::$DATA
  // 8.3 短名称: GIT~1
  // Long path prefixes: \\?\C:\...
  // DOS 设备名: .git.CON, settings.json.PRN
  // UNC 路径: \\server\share
}

// 路径规范化
function normalizePath(path: string): string {
  // 解析符号链接
  // 大小写不敏感文件系统处理
  // 检测路径遍历
}

---

第八部分：工具系统

8.1 工具架构

每个工具都实现了标准接口：

// src/Tool.ts
export type Tool<Input, Output, P> = {
  name: string
  description(input, options): Promise<string>
  prompt(options): Promise<string>
  inputSchema: z.ZodType
  outputSchema?: z.ZodType

  // 权限
  checkPermissions(input, context): Promise<PermissionResult>

  // 执行
  call(args, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>

  // 渲染
  renderToolUseMessage(input, options): React.ReactNode
  renderToolResultMessage(content, progress, options): React.ReactNode

  // 特性
  isConcurrencySafe(input): boolean
  isReadOnly(input): boolean
  isDestructive?(input): boolean
}

8.2 核心工具列表

工具	文件	功能
BashTool	BashTool/	Shell 命令执行
FileReadTool	FileReadTool/	文件读取
FileWriteTool	FileWriteTool/	文件写入
FileEditTool	FileEditTool/	代码编辑
GlobTool	GlobTool/	模式匹配文件查找
GrepTool	GrepTool/	内容搜索
AgentTool	AgentTool/	智能体执行
MCPTool	MCPTool/	MCP 协议交互
LSPTool	LSPTool/	语言服务器协议
NotebookEditTool	NotebookEditTool/	Jupyter Notebook 编辑

8.3 BashTool 详解

BashTool 是最复杂的工具之一：

// 权限检查
async checkPermissions(
  input: { command: string },
  context: ToolUseContext,
): Promise<PermissionResult> {
  // 1. 命令语义分析
  const semantics = analyzeCommandSemantics(input.command)

  // 2. 安全检查
  if (semantics.isDangerous) {
    return { behavior: 'deny', reason: semantics.dangerReason }
  }

  // 3. 路径验证
  if (semantics.accessesDangerousPaths) {
    return { behavior: 'deny', reason: 'Access to dangerous paths' }
  }

  // 4. 沙箱决策
  if (await shouldUseSandbox(input.command)) {
    return { behavior: 'ask', requiresSandbox: true }
  }

  return { behavior: 'allow' }
}

8.4 AgentTool 详解

AgentTool 支持创建子智能体：

// src/tools/AgentTool/AgentTool.tsx
async function call(
  args: {
    goal: string
    name?: string
    team_name?: string
    agent_type?: AgentType
    model?: string
  },
  context: ToolUseContext,
) {
  // 1. 确定执行模式
  if (args.team_name && args.name) {
    // 团队模式：创建队友
    return spawnTeammate(args, context)
  } else if (isForkEnabled() && !args.agent_type) {
    // Fork 模式
    return forkSubagent(args, context)
  } else {
    // 显式类型模式
    return runAgent(args, context)
  }
}

---

第九部分：MCP（Model Context Protocol）系统

9.1 MCP 架构

// src/services/mcp/types.ts
interface MCPServerConnection {
  name: string
  status: 'connecting' | 'connected' | 'error'
  tools: MCPTool[]
  resources: ServerResource[]
  instructions?: string
}

// MCP 客户端
interface MCPClient {
  connect(config: MCPConfig): Promise<void>
  disconnect(): Promise<void>
  listTools(): Promise<MCPTool[]>
  callTool(name: string, args: object): Promise<ToolResult>
  listResources(): Promise<ServerResource[]>
}

9.2 MCP 工具集成

MCP 工具与内置工具享有同等地位：

// src/tools/MCPTool/MCPTool.ts
async function call(
  args: { server: string; tool: string; args?: object },
  context: ToolUseContext,
) {
  // 1. 查找 MCP 服务器
  const server = findMCPServer(context.mcpClients, args.server)

  // 2. 调用工具
  const result = await server.callTool(args.tool, args.args)

  // 3. 格式化结果
  return {
    content: formatMCPToolResult(result),
    isError: result.isError,
  }
}

9.3 MCP 权限管理

// MCP 工具的权限检查
async checkPermissions(
  input: { server: string; tool: string },
  context: ToolPermissionContext,
): Promise<PermissionResult> {
  // MCP 工具有独立的权限规则
  const rule = findMCPPermissionRule(input.server, input.tool)

  if (rule === 'allow') return { behavior: 'allow' }
  if (rule === 'deny') return { behavior: 'deny' }

  // 回退到默认行为
  return checkDefaultMCPBehavior(input)
}

---

第十部分：CLI 与传输系统

10.1 CLI 入口点

// src/cli/handlers/ 中定义各种处理器
// agents.ts - 智能体子命令
// auth.ts - 认证处理
// autoMode.ts - 自动模式处理
// plugins.ts - 插件管理

10.2 传输层

// src/cli/transports/

// HybridTransport - WebSocket + HTTP POST
class HybridTransport {
  private ws: WebSocket
  private uploader: SerialBatchEventUploader

  // WebSocket 接收
  setOnData(handler: (data: ServerMessage) => void) {}

  // HTTP POST 发送
  async writeBatch(events: SDKMessage[]): Promise<void> {}
}

// SSETransport - 纯 SSE
class SSETransport {
  private eventSource: EventSource

  setOnData(handler: (data: ServerMessage) => void) {}
}

// WebSocketTransport - 纯 WebSocket
class WebSocketTransport {
  private ws: WebSocket

  async write(event: SDKMessage): Promise<void> {}
  setOnData(handler: (data: ServerMessage) => void) {}
}

10.3 结构化输出

// src/cli/structuredIO.ts
interface StructuredOutput {
  format: 'json' | 'text' | 'markdown'
  content: any
  metadata?: {
    tool?: string
    duration?: number
    error?: string
  }
}

// 格式化输出
function formatOutput(result: ToolResult, format: OutputFormat): string {
  switch (format) {
    case 'json':
      return JSON.stringify(result, null, 2)
    case 'text':
      return extractText(result)
    case 'markdown':
      return formatAsMarkdown(result)
  }
}

---

第十一部分：关键文件索引

11.1 核心文件列表

文件路径	行数	核心功能
src/bridge/bridgeMain.ts	2400+	桥接系统主入口
src/query.ts	2000+	主查询循环
src/QueryEngine.ts	1300+	查询引擎类
src/commands.ts	750+	命令注册系统
src/Tool.ts	800+	工具类型定义
src/utils/claudemd.ts	1500+	CLAUDE.md 加载
src/tools/AgentTool/AgentTool.tsx	1000+	智能体工具
src/utils/permissions/permissions.ts	1000+	权限检查
src/utils/model/model.ts	500+	模型选择
src/services/api/claude.ts	1000+	API 客户端

11.2 目录结构

src/
├── bridge/                    # 桥接系统（远程通信）
│   ├── bridgeMain.ts
│   ├── replBridge.ts
│   ├── bridgeMessaging.ts
│   ├── bridgeApi.ts
│   └── transports/
├── cli/                       # CLI 实现
│   ├── handlers/
│   └── transports/
├── commands/                  # 100+ 命令
│   ├── help/
│   ├── config/
│   ├── agents/
│   └── ...
├── components/                # React UI
├── context/                   # React Context
├── entrypoints/              # 入口点
├── hooks/                     # React Hooks
├── services/                  # 服务层
│   ├── analytics/
│   ├── api/
│   ├── compact/
│   ├── mcp/
│   └── SessionMemory/
├── skills/                   # 技能系统
├── state/                     # 状态管理
├── tools/                     # 50+ 工具
│   ├── AgentTool/
│   ├── BashTool/
│   ├── FileEditTool/
│   ├── MCPTool/
│   └── ...
├── types/                     # 类型定义
└── utils/                     # 工具函数
    ├── model/
    ├── permissions/
    ├── plugins/
    └── ...

---

第十二部分：技术栈总结

12.1 运行时环境

• Bun：主要运行时，提供优秀的启动性能和 TypeScript 支持
• Node.js：备用运行时（部分场景）
• TypeScript：全程类型安全

12.2 核心依赖

依赖	版本	用途
React	18+	UI 框架
@anthropic-ai/sdk	latest	Anthropic API 客户端
@modelcontextprotocol/sdk	latest	MCP 协议实现
zod	3.x	运行时类型验证
lodash-es	latest	工具函数
ws	latest	WebSocket 支持

12.3 主要设计模式

1. 依赖注入 ：通过 deps.ts 实现可测试性
2. AsyncLocalStorage：进程内上下文隔离
3. 发布-订阅：状态变更通知
4. 工厂模式：API 客户端创建
5. 策略模式：权限检查、可选执行

---

第十三部分：配置与扩展系统

13.1 设置管理系统

Claude Code 的配置系统支持多层级的设置管理：

// 设置加载优先级（从高到低）
// 1. 环境变量
// 2. 命令行参数
// 3. 项目级配置 (.claude.json)
// 4. 用户级配置 (~/.claude/)
// 5. 内置默认值

interface Settings {
  // API 配置
  apiKey?: string
  baseUrl?: string
  model?: string

  // UI 配置
  theme?: 'dark' | 'light' | 'system'
  color?: string

  // 安全配置
  permissions: {
    mode: PermissionMode
    additionalDirectories: string[]
    rules: PermissionRule[]
  }

  // 高级配置
  experimental: Record<string, boolean>
  features: Record<string, boolean>
}

13.2 功能开关系统

使用 bun:bundle 的特性标签实现条件编译：

// 启用/禁用功能
feature('WORKFLOW_SCRIPTS')  // 工作流脚本
feature('CCR_REMOTE_SETUP')  // CCR 远程设置
feature('FORK_SUBAGENT')     // Fork 子智能体
feature('BUDDY')              // Buddy 伴随系统
feature('PROACTIVE')          // 主动模式

13.3 插件系统架构

// 插件类型
interface Plugin {
  name: string
  version: string
  commands?: Command[]           // 添加的命令
  tools?: Tool[]                 // 添加的工具
  skills?: Skill[]               // 添加的技能
  themes?: Theme[]               // 添加的主题
  hooks?: Hook[]                // 添加的钩子

  // 生命周期
  onLoad?: () => void | Promise<void>
  onUnload?: () => void | Promise<void>
}

// 插件加载流程
async function loadPlugin(plugin: Plugin) {
  // 1. 验证插件
  await validatePlugin(plugin)

  // 2. 注册内容
  if (plugin.commands) registerCommands(plugin.commands)
  if (plugin.tools) registerTools(plugin.tools)
  if (plugin.skills) registerSkills(plugin.skills)

  // 3. 调用 onLoad
  await plugin.onLoad?.()
}

---

第十四部分：调试与诊断系统

14.1 诊断工具

Claude Code 提供了全面的调试工具：

// /doctor 命令 - 系统诊断
interface DoctorResult {
  environment: {
    os: string
    shell: string
    bunVersion: string
  }
  api: {
    configured: boolean
    baseUrl: string
    model: string
  }
  git: {
    repository: string | null
    branch: string
  }
  permissions: {
    mode: PermissionMode
    rulesCount: number
  }
  mcp: {
    servers: MCPServerStatus[]
  }
  plugins: {
    installed: string[]
    errors: PluginError[]
  }
}

14.2 调试日志

// 日志级别
enum LogLevel {
  DEBUG = 0
  INFO = 1
  WARN = 2
  ERROR = 3
}

// 调试日志记录
logForDebugging('bridge:repl', `Session created: ${sessionId}`)
logForDiagnostics('info', 'bridge_repl_session_created')
logEvent('tengu_bridge_repl_started', { ... })

14.3 工具调用调试

// /debug-tool-call - 详细工具调用信息
interface ToolCallDebugInfo {
  toolUseId: string
  tool: string
  input: unknown
  result?: ToolResult
  duration: number
  permissions: PermissionResult
  error?: string
}

---

结语

Claude Code 是一个高度复杂的智能体开发框架，其设计涵盖了软件工程的多个领域：分布式系统、网络通信、安全工程、编译器设计、用户体验等。本文档试图从核心架构、业务流程、关键算法等角度提供深入的技术解析。

理解 Claude Code 的内部机制对于：

• 扩展框架功能
• 调试复杂问题
• 贡献代码
• 构建基于智能体的应用

都具有重要的参考价值。