CLI 入口模式处理流程:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// cli.tsx 核心逻辑async function main() {  // 1. 快速路径：版本号输出（零导入）  if (args.includes('--version')) {    console.log(VERSION)    return  }  // 2. 特殊模式路由  if (args.includes('--dump-system-prompt')) {    // 输出渲染后的系统提示词    await dumpSystemPrompt()    return  }  // 3. MCP 服务器模式  if (args.includes('--claude-in-chrome-mcp')) {    await startChromeMCPServer()    return  }  // 4. 远程控制模式  if (args.includes('remote-control') || args.includes('rc')) {    await startBridgeMode()    return  }  // 5. 默认：加载完整 CLI  await import('./main.js')}

3.2 查询引擎 (QueryEngine)

QueryEngine 核心实现:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
export class QueryEngine {  private config: QueryEngineConfig  private mutableMessages: Message[]  private abortController: AbortController  private permissionDenials: SDKPermissionDenial[]  private totalUsage: NonNullableUsage  private readFileState: FileStateCache  async *submitMessage(prompt: string): AsyncGenerator<SDKMessage> {    // 1. 构建用户消息    const userMessage = await this.buildUserMessage(prompt)    this.mutableMessages.push(userMessage)    // 2. 获取系统提示词    const systemPrompt = await getSystemPrompt()    // 3. 规范化消息    const normalizedMessages = normalizeMessagesForAPI(      this.mutableMessages,      this.config    )    // 4. 调用 API    const stream = streamMessages({      messages: normalizedMessages,      system: systemPrompt,      tools: this.getEnabledTools(),      ...this.config    })    // 5. 处理流式响应    for await (const event of stream) {      yield* this.processStreamEvent(event)    }  }}

3.3 消息处理系统

4. 工具系统

4.1 工具接口定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
export type Tool<Input, Output, P> = {  // 基础属性  name: string                    // 工具名称  aliases?: string[]              // 别名列表  searchHint?: string             // 搜索提示  // 模式定义  inputSchema: Input              // Zod 输入模式  inputJSONSchema?: JSONSchema    // JSON Schema  // 核心方法  call(): Promise<ToolResult<Output>>  // 执行工具  description(): Promise<string>        // 获取描述  // 状态检查  isEnabled(): boolean            // 是否启用  isReadOnly(): boolean           // 是否只读  isDestructive?(): boolean       // 是否破坏性  isConcurrencySafe(): boolean    // 是否并发安全  // 权限  checkPermissions(): Promise<PermissionResult>  // 验证  validateInput?(): Promise<ValidationResult>  // 渲染  renderToolUseMessage(): React.ReactNode  renderToolResultMessage(): React.ReactNode  // 可选扩展方法  queueConcurrencyKey?(): string | undefined  renderProgress?(): React.ReactNode  updateProgress?(): void  signal?(): AbortSignal  formatResult?(): string  shouldDeferToolUse?(): Promise<boolean>  performNetworkRequest?(): Promise<unknown>  updateEstimatedProgress?(): void  getUnsafeToolUseMessage?(): string  forcePromptCaching?(): boolean  // ... 更多可选方法}

4.2 工具分类

4.3 工具执行流程

4.4 BashTool 示例分析

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
// BashTool 核心实现export const BashTool = buildTool({  name: 'Bash',  inputSchema: z.object({    command: z.string().describe('The command to execute'),    timeout: z.number().optional(),    description: z.string().optional(),    dangerouslyDisableSandbox: z.boolean().optional(),    run_in_background: z.boolean().optional(),  }),  async call() {    const { command, timeout, run_in_background } = this.input    // 1. 沙箱检查    if (!this.input.dangerouslyDisableSandbox) {      const sandboxResult = await checkSandbox(command)      if (sandboxResult.blocked) {        return { error: sandboxResult.reason }      }    }    // 2. 执行命令    const result = await executeCommand(command, {      timeout: timeout ?? 120000,      signal: this.signal,      background: run_in_background,    })    // 3. 返回结果    return {      stdout: result.stdout,      stderr: result.stderr,      exitCode: result.exitCode,    }  },  isReadOnly() {    // 根据命令判断是否只读    return isReadOnlyCommand(this.input.command)  },  isDestructive() {    // 检查是否破坏性命令    return isDestructiveCommand(this.input.command)  },  checkPermissions() {    return checkBashPermission(this.input.command)  },})

5. MCP 集成

5.1 MCP 架构

5.2 MCP 服务器配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// MCP 服务器配置类型type McpServerConfig = {  command: string           // 启动命令  args?: string[]          // 命令参数  env?: Record<string, string>  // 环境变量  cwd?: string             // 工作目录  transport?: 'stdio' | 'sse' | 'http' | 'ws'  url?: string             // 远程服务器 URL  headers?: Record<string, string>  // HTTP 头  disabled?: boolean}// 配置示例const mcpServers = {  'filesystem': {    command: 'mcp-server-filesystem',    args: ['--root', '/home/user/projects']  },  'github': {    transport: 'http',    url: 'https://mcp.github.com/api',    headers: {      'Authorization': 'Bearer ${GITHUB_TOKEN}'    }  }}

5.3 MCP 客户端状态机

5.4 MCP 工具包装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// MCP 工具包装器export class MCPTool {  constructor(    private serverName: string,    private tool: MCPToolDefinition  ) {}  async call(input: unknown): Promise<ToolResult> {    // 1. 获取 MCP 客户端    const client = await this.getMCPClient()    // 2. 调用 MCP 工具    const result = await client.callTool({      name: this.tool.name,      arguments: input    })    // 3. 处理结果    return {      content: result.content,      isError: result.isError    }  }  checkPermissions() {    // MCP 工具权限检查    return checkMCPPermission(this.serverName, this.tool.name)  }}

6. 状态管理

6.1 状态架构

6.2 状态类型定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
export type AppState = DeepImmutable<{  // 设置  settings: SettingsJson  // 任务管理  tasks: {    [taskId: string]: TaskState  }  // MCP  mcp: {    clients: Map<string, MCPClientState>    tools: Map<string, MCPToolDefinition>    commands: Map<string, MCPCommandDefinition>    resources: Map<string, MCPResourceDefinition>  }  // 插件  plugins: {    enabled: Set<string>    disabled: Set<string>    commands: Map<string, PluginCommand>    errors: Map<string, string>  }  // 会话  session: {    id: string    messages: Message[]    usage: Usage    status: SessionStatus  }  // UI  ui: {    mode: 'normal' | 'vim' | 'voice'    theme: ThemeName    showHelp: boolean    scrollPosition: number  }  // 工具  tools: {    enabled: Set<string>    permissions: Map<string, PermissionState>  }  // 缓存  cache: {    fileContents: Map<string, string>    fileHashes: Map<string, string>    embeddings: Map<string, number[]>  }  // ... 100+ 状态字段}>

6.3 状态更新模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// Zustand-like 状态更新const useAppState = create<AppState>((set, get) => ({  // 状态  settings: defaultSettings,  tasks: {},  // ...  // 更新方法  updateSettings: (partial: Partial<SettingsJson>) => {    set(state => ({      settings: { ...state.settings, ...partial }    }))  },  createTask: (task: Task) => {    set(state => ({      tasks: { ...state.tasks, [task.id]: task }    }))  },  updateTask: (taskId: string, update: Partial<TaskState>) => {    set(state => ({      tasks: {        ...state.tasks,        [taskId]: { ...state.tasks[taskId], ...update }      }    }))  },  // 选择器  getEnabledTools: () => {    const state = get()    return Array.from(state.tools.enabled)  },}))

7. 认证系统

7.1 认证流程

7.2 认证源优先级

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
type AuthTokenSource =  | 'ANTHROPIC_API_KEY'           // 1. 直接 API Key  | 'ANTHROPIC_AUTH_TOKEN'        // 2. Auth Token  | 'CLAUDE_CODE_OAUTH_TOKEN'     // 3. OAuth Token  | 'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR'  // 4. 文件描述符  | 'CCR_OAUTH_TOKEN_FILE'        // 5. CCR Token 文件  | 'apiKeyHelper'                // 6. 自定义密钥助手  | 'keychain'                    // 7. 系统钥匙串  | 'none'                        // 8. 无认证// 认证检查顺序async function getAuthToken(): Promise<AuthToken> {  // 1. 检查环境变量  if (process.env.ANTHROPIC_API_KEY) {    return { source: 'ANTHROPIC_API_KEY', token: process.env.ANTHROPIC_API_KEY }  }  // 2. 检查 OAuth Token  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {    return { source: 'CLAUDE_CODE_OAUTH_TOKEN', token: process.env.CLAUDE_CODE_OAUTH_TOKEN }  }  // 3. 调用 apiKeyHelper  const helperToken = await callApiKeyHelper()  if (helperToken) {    return { source: 'apiKeyHelper', token: helperToken }  }  // 4. 从钥匙串读取  const storedToken = await getFromKeychain()  if (storedToken) {    return { source: 'keychain', token: storedToken }  }  // 5. 发起 OAuth 流程  return await performOAuthFlow()}

7.3 多后端支持

8. 会话管理

8.1 会话生命周期

8.2 会话存储结构

1
2
3
4
5
6
7
8
9
10
11
12
~/.claude/projects/<project-hash>/├── sessions/│   ├── session-20260331-001.jsonl    # 会话记录│   ├── session-20260331-002.jsonl│   └── ...├── pastes/│   ├── paste-abc123.txt              # 粘贴内容存储│   └── ...├── memory/│   ├── MEMORY.md                     # 项目记忆│   └── ...└── settings.json                     # 项目设置

8.3 会话存储格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// JSONL 会话记录格式type SessionRecord = {  timestamp: string  type: 'message' | 'tool_use' | 'tool_result' | 'system'  data: {    role: 'user' | 'assistant'    content: ContentBlock[]    usage?: Usage    toolCalls?: ToolCall[]    toolResults?: ToolResult[]  }}// 示例记录{"timestamp":"2026-03-31T10:00:00Z","type":"message","data":{"role":"user","content":[{"type":"text","text":"帮我分析代码"}]}}{"timestamp":"2026-03-31T10:00:05Z","type":"message","data":{"role":"assistant","content":[{"type":"text","text":"我来帮你分析..."}],"usage":{"input_tokens":100,"output_tokens":50}}}{"timestamp":"2026-03-31T10:00:10Z","type":"tool_use","data":{"name":"FileReadTool","input":{"file_path":"src/main.ts"}}}{"timestamp":"2026-03-31T10:00:12Z","type":"tool_result","data":{"content":"文件内容..."}}

8.4 上下文压缩策略

9. 命令系统

9.1 命令类型

9.2 命令定义结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
type Command =  | {      type: 'prompt'      getPromptForCommand(): Promise<string>    }  | {      type: 'local'      handler(): Promise<LocalCommandResult>    }  | {      type: 'jsx'      component: React.FC    }// 命令注册示例const commands: Record<string, Command> = {  '/commit': {    type: 'prompt',    async getPromptForCommand() {      // 获取 git diff      const diff = await getGitDiff()      return `请根据以下变更生成提交信息:\n${diff}`    }  },  '/help': {    type: 'local',    async handler() {      return {        output: generateHelpText(),        exitCode: 0      }    }  },  '/stats': {    type: 'jsx',    component: StatsPanel  }}

9.3 命令执行流程

10. 插件系统

10.1 插件架构

10.2 插件清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
type PluginManifest = {  name: string  version: string  description: string  author: string  // 入口点  main?: string          // 主入口文件  skills?: string[]      // 技能文件  tools?: string[]       // 工具文件  commands?: string[]    // 命令文件  // 依赖  dependencies?: string[]  peerDependencies?: string[]  // 权限  permissions?: {    fileSystem?: boolean    network?: boolean    shell?: boolean  }  // 配置  config?: {    [key: string]: ConfigSchema  }}// 插件示例const examplePlugin: PluginManifest = {  name: 'claude-code-git',  version: '1.0.0',  description: 'Git integration plugin',  author: 'anthropic',  skills: ['./skills/commit.md', './skills/review.md'],  tools: ['./tools/gitTool.ts'],  commands: ['./commands/branch.ts'],  permissions: {    fileSystem: true,    shell: true  }}

10.3 插件生命周期

11. 数据流分析

11.1 完整请求流程

11.2 Token 预算管理

11.3 权限检查流程

12. 技术栈

12.1 核心技术