跳至主要內容

Claude Code 架构图阅读目录

util62026/4/27大约 6 分钟

Claude Code 架构图阅读目录

基于页面：

  • https://www.waylandz.com/diagrams/claude-code-architecture.html

整理目标：

  • 先按架构图建立阅读顺序
  • 再把每个功能模块映射到当前恢复版仓库里的实际文件
  • 优先覆盖主干链路，不追求一次穷尽所有边缘特性

说明：

  • 这是恢复版源码树，部分图上的能力可能被拆散、降级或用 shim 替代。
  • 下文的“核心文件”适合第一遍阅读；“延伸文件”适合第二遍追踪调用链。

总阅读顺序

  1. 启动入口与 CLI 分流
  2. Query Loop 对话主循环
  3. System Prompt 与 API 请求组装
  4. Tool Runtime 与工具调度
  5. 权限系统与安全边界
  6. 上下文压缩与恢复
  7. Commands / Skills / Plugins / MCP 扩展层
  8. Agent / Task 子系统
  9. Interactive UI / Headless / Remote / Bridge / Server
  10. 状态持久化、历史与记忆
  11. Feature Flag、实验能力与遥测

1. 启动入口与 CLI 分流

架构图对应：

  • Interactive REPL
  • Headless
  • Remote / CCR
  • Bridge
  • Server Mode

核心文件：

  • src/bootstrap-entry.ts
  • src/entrypoints/cli.tsx
  • src/main.tsx
  • src/commands.ts

延伸文件：

  • src/dev-entry.ts
  • src/bootstrap/state.ts
  • src/dialogLaunchers.tsx
  • src/replLauncher.tsx

阅读重点：

  • bootstrap-entry.ts 只做最外层准备，然后进入真正 CLI。
  • entrypoints/cli.tsx 负责各种 fast-path 分流，例如 --version、bridge、daemon、background session。
  • main.tsx 是主程序装配中心，负责初始化、命令行、配置、服务和主循环接线。
  • commands.ts 是 slash command 注册中心。

2. Query Loop 对话主循环

架构图对应：

  • Query Loop
  • 单次迭代
  • API 流式
  • tool_use 检测
  • tool_result 回填
  • 循环控制

核心文件：

  • src/query.ts
  • src/QueryEngine.ts
  • src/query/config.ts
  • src/query/deps.ts
  • src/query/transitions.ts
  • src/query/stopHooks.ts

延伸文件：

  • src/utils/messages.ts
  • src/utils/api.ts
  • src/utils/attachments.ts
  • src/utils/sessionStorage.ts
  • src/services/toolUseSummary/toolUseSummaryGenerator.ts

阅读重点：

  • query.ts 是最关键文件，负责一次 turn 中的流式请求、工具执行、错误恢复和继续条件。
  • QueryEngine.ts 是会话级对象，通常承载消息数组、文件缓存、用量等更高层状态。
  • query/config.ts 和 query/deps.ts 体现主循环把“策略”和“依赖实现”拆开。

3. System Prompt 与 API 请求组装

架构图对应：

  • System Prompt 组装
  • DYNAMIC_BOUNDARY
  • Claude API 流式
  • prompt cache

核心文件：

  • src/services/api/claude.ts
  • src/constants/prompts.ts
  • src/utils/systemPromptType.ts
  • src/context.ts
  • src/query.ts

延伸文件：

  • src/services/api/bootstrap.ts
  • src/services/api/client.ts
  • src/services/api/withRetry.ts
  • src/services/api/errors.ts
  • src/services/api/promptCacheBreakDetection.ts
  • src/constants/systemPromptSections.ts

阅读重点：

  • services/api/claude.ts 看请求体怎么组装、模型参数怎么下发、流式响应怎么处理。
  • constants/prompts.ts 和 context.ts 看静态前缀与动态上下文如何合并。
  • promptCacheBreakDetection.ts 对应架构图里“cache break detection”。

4. Tool Runtime 与工具调度

架构图对应：

  • Tool Runtime
  • tools.ts 注册中心
  • toolOrchestration.ts
  • toolExecution.ts
  • Tool.ts 统一协议
  • StreamingToolExecutor

核心文件：

  • src/tools.ts
  • src/Tool.ts
  • src/services/tools/toolOrchestration.ts
  • src/services/tools/toolExecution.ts
  • src/services/tools/StreamingToolExecutor.ts

代表性工具文件：

  • src/tools/BashTool/BashTool.ts
  • src/tools/FileReadTool/FileReadTool.ts
  • src/tools/FileEditTool/FileEditTool.ts
  • src/tools/FileWriteTool/FileWriteTool.ts
  • src/tools/GlobTool/GlobTool.ts
  • src/tools/GrepTool/GrepTool.ts
  • src/tools/WebFetchTool/WebFetchTool.ts
  • src/tools/WebSearchTool/WebSearchTool.ts
  • src/tools/AgentTool/AgentTool.ts
  • src/tools/SkillTool/SkillTool.ts
  • src/tools/MCPTool/MCPTool.ts
  • src/tools/SendMessageTool/SendMessageTool.ts

阅读重点：

  • Tool.ts 先看统一接口，再看具体工具。
  • tools.ts 看工具清单、稳定排序、feature gate 和不同运行环境下哪些工具会启用。
  • toolOrchestration.ts 看并发调度与分组策略。
  • toolExecution.ts 看 schema、权限、hook、遥测接入点。

5. 权限系统与安全边界

架构图对应：

  • 4 路权限竞争
  • PermissionMode
  • User / Hook / Classifier / Bridge
  • allow / deny / ask
  • ResolveOnce
  • Tool 安全边界

核心文件：

  • src/utils/permissions/PermissionMode.ts
  • src/utils/permissions/permissions.ts
  • src/utils/permissions/PermissionRule.ts
  • src/utils/permissions/permissionRuleParser.ts
  • src/utils/permissions/PermissionResult.ts
  • src/utils/permissions/PermissionUpdate.ts
  • src/utils/permissions/bashClassifier.ts
  • src/utils/permissions/classifierDecision.ts

延伸文件：

  • src/utils/permissions/pathValidation.ts
  • src/utils/permissions/filesystem.ts
  • src/utils/permissions/dangerousPatterns.ts
  • src/utils/permissions/denialTracking.ts
  • src/utils/permissions/shellRuleMatching.ts
  • src/utils/permissions/autoModeState.ts
  • src/remote/remotePermissionBridge.ts
  • src/bridge/bridgePermissionCallbacks.ts
  • src/hooks/toolPermission/handlers/interactiveHandler.ts
  • src/hooks/toolPermission/handlers/swarmWorkerHandler.ts
  • src/hooks/toolPermission/handlers/coordinatorHandler.ts

UI 对应文件：

  • src/components/permissions/PermissionDialog.tsx
  • src/components/permissions/BashPermissionRequest/BashPermissionRequest.tsx
  • src/components/permissions/FileEditPermissionRequest/FileEditPermissionRequest.tsx
  • src/components/permissions/FileWritePermissionRequest/FileWritePermissionRequest.tsx
  • src/components/permissions/FilesystemPermissionRequest/FilesystemPermissionRequest.tsx

阅读重点：

  • 先理解 permission mode 与 rule model，再看 bash classifier。
  • 再看 interactive UI、bridge、worker 这几路审批入口怎样汇合。

6. Shell、PowerShell 与沙箱

架构图对应：

  • Shell / 子进程
  • Bash / PowerShell
  • sandbox

核心文件：

  • src/tools/BashTool/BashTool.ts
  • src/tools/BashTool/bashPermissions.ts
  • src/tools/BashTool/bashSecurity.ts
  • src/tools/PowerShellTool/PowerShellTool.tsx
  • src/tools/PowerShellTool/powershellPermissions.ts
  • src/tools/PowerShellTool/powershellSecurity.ts
  • src/utils/Shell.ts
  • src/utils/ShellCommand.ts
  • src/utils/sandbox/sandbox-adapter.ts

延伸文件：

  • src/utils/bash/parser.ts
  • src/utils/bash/bashParser.ts
  • src/utils/bash/treeSitterAnalysis.ts
  • src/utils/bash/registry.ts
  • src/utils/shell/resolveDefaultShell.ts
  • src/tasks/LocalShellTask/LocalShellTask.tsx

阅读重点：

  • Bash/PowerShell 工具层负责“如何暴露给模型”。
  • utils/bash/* 负责命令解析和安全语义。
  • sandbox-adapter.ts 负责把命令落到实际沙箱执行层。

7. 上下文压缩与恢复

架构图对应：

  • 5 层上下文压缩
  • snip compact
  • microcompact
  • context collapse
  • autoCompact
  • reactive PTL
  • compact boundary

核心文件：

  • src/services/compact/snipCompact.ts
  • src/services/compact/apiMicrocompact.ts
  • src/services/compact/compact.ts
  • src/services/compact/autoCompact.ts
  • src/services/compact/reactiveCompact.ts
  • src/services/contextCollapse/index.ts
  • src/services/contextCollapse/operations.ts
  • src/services/contextCollapse/persist.ts

延伸文件：

  • src/services/compact/postCompactCleanup.ts
  • src/services/compact/sessionMemoryCompact.ts
  • src/services/compact/prompt.ts
  • src/query.ts
  • src/utils/messages.ts

阅读重点：

  • 这块最好直接从 query.ts 里的调用点反向跳进去读。
  • 图上的“五层压缩”在代码里分布在 services/compact/ 与 services/contextCollapse/ 两个区域。

8. Commands / Skills / Plugins / MCP 扩展层

架构图对应：

  • 四层扩展体系
  • Commands
  • Skills
  • Plugins
  • MCP Client

8.1 Commands

核心文件：

  • src/commands.ts
  • src/types/command.ts

延伸文件：

  • src/commands/*

阅读重点：

  • 从 commands.ts 看所有内建命令如何注册、按 feature 动态启用、和插件/skill 命令如何合并。

8.2 Skills

核心文件：

  • src/skills/loadSkillsDir.ts
  • src/skills/mcpSkills.ts
  • src/skills/bundled/

延伸文件：

  • src/utils/skills/skillChangeDetector.ts
  • src/components/skills/SkillsMenu.tsx

阅读重点：

  • 动态发现本地技能目录。
  • bundled skills 如何作为 Markdown prompt 资源接入。

8.3 Plugins

核心文件：

  • src/plugins/builtinPlugins.ts
  • src/services/plugins/PluginInstallationManager.ts
  • src/services/plugins/pluginCliCommands.ts
  • src/services/plugins/pluginOperations.ts
  • src/utils/plugins/loadPluginCommands.ts
  • src/utils/plugins/loadPluginHooks.ts
  • src/utils/plugins/loadPluginAgents.ts
  • src/utils/plugins/pluginLoader.ts

延伸文件：

  • src/utils/plugins/pluginDirectories.ts
  • src/utils/plugins/managedPlugins.ts
  • src/utils/plugins/validatePlugin.ts
  • src/utils/plugins/mcpPluginIntegration.ts
  • src/utils/plugins/lspPluginIntegration.ts

阅读重点：

  • 插件并不只是命令，代码里还覆盖 skill、hook、agent、MCP 等接入面。

8.4 MCP

核心文件：

  • src/services/mcp/client.ts
  • src/services/mcp/config.ts
  • src/services/mcp/types.ts
  • src/services/mcp/MCPConnectionManager.tsx
  • src/services/mcp/InProcessTransport.ts
  • src/services/mcp/SdkControlTransport.ts
  • src/tools/MCPTool/MCPTool.ts
  • src/tools/ListMcpResourcesTool/ListMcpResourcesTool.ts
  • src/tools/ReadMcpResourceTool/ReadMcpResourceTool.ts

延伸文件：

  • src/services/mcp/auth.ts
  • src/services/mcp/officialRegistry.ts
  • src/services/mcp/normalization.ts
  • src/services/mcp/channelPermissions.ts
  • src/services/mcp/elicitationHandler.ts
  • src/services/mcp/claudeai.ts

阅读重点：

  • 先看 MCP 配置与 client，再看连接管理和资源读取工具。

9. Agent / Task 子系统

架构图对应：

  • AgentTool
  • Task 统一壳
  • local_agent / remote / bash / workflow
  • SendMessageTool
  • worktree / remote 隔离
  • Coordinator

核心文件：

  • src/tools/AgentTool/AgentTool.ts
  • src/tools/SendMessageTool/SendMessageTool.ts
  • src/tasks/types.ts
  • src/tasks/LocalAgentTask/LocalAgentTask.tsx
  • src/tasks/RemoteAgentTask/RemoteAgentTask.tsx
  • src/tasks/LocalShellTask/LocalShellTask.tsx
  • src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts
  • src/tasks/LocalMainSessionTask.ts

延伸文件：

  • src/coordinator/coordinatorMode.ts
  • src/coordinator/workerAgent.ts
  • src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx
  • src/tasks/MonitorMcpTask/MonitorMcpTask.ts
  • src/tasks/DreamTask/DreamTask.ts
  • src/utils/worktree.ts
  • src/tools/EnterWorktreeTool/EnterWorktreeTool.ts
  • src/tools/ExitWorktreeTool/ExitWorktreeTool.ts

阅读重点：

  • 这块体现“Agent 是一级概念”。
  • 先看 AgentTool 如何派生任务，再看不同 task 类型怎样共享壳层与生命周期。

10. Interactive UI / Headless / Remote / Bridge / Server

架构图对应：

  • Interactive REPL React/Ink
  • Headless / SDK
  • Remote / CCR WebSocket
  • Bridge 工作节点
  • Server Mode HTTP API

10.1 Interactive REPL / Ink

核心文件：

  • src/main.tsx
  • src/replLauncher.tsx
  • src/components/
  • src/hooks/

阅读重点：

  • main.tsx 决定何时进入交互模式。
  • components/ 与 hooks/ 是终端 UI 层。

10.2 Headless / SDK

核心文件：

  • src/query.ts
  • src/interactiveHelpers.tsx
  • src/dialogLaunchers.tsx

说明：

  • 当前恢复树里“headless”相关逻辑分散在主循环、输出渲染和命令分流，没有单独一个 headless.ts 式总入口。

10.3 Remote / CCR

核心文件：

  • src/remote/RemoteSessionManager.ts
  • src/remote/SessionsWebSocket.ts
  • src/remote/sdkMessageAdapter.ts
  • src/remote/remotePermissionBridge.ts

10.4 Bridge

核心文件：

  • src/bridge/bridgeMain.ts
  • src/bridge/bridgeApi.ts
  • src/bridge/remoteBridgeCore.ts
  • src/bridge/sessionRunner.ts
  • src/bridge/createSession.ts
  • src/bridge/bridgeMessaging.ts
  • src/bridge/bridgeConfig.ts

延伸文件：

  • src/bridge/replBridge.ts
  • src/bridge/replBridgeTransport.ts
  • src/bridge/bridgePermissionCallbacks.ts
  • src/bridge/trustedDevice.ts

10.5 Server Mode

核心文件：

  • src/server/createDirectConnectSession.ts
  • src/server/directConnectManager.ts
  • src/server/types.ts

阅读重点：

  • 这几块适合在理解 Query Loop 之后再读，否则会被传输层细节打散注意力。

11. 状态持久化、历史与记忆

架构图对应：

  • bootstrap/state.ts
  • AppStateStore
  • sessionStorage.ts
  • history.ts
  • fileHistory
  • memdir

核心文件：

  • src/bootstrap/state.ts
  • src/state/AppStateStore.ts
  • src/utils/sessionStorage.ts
  • src/utils/sessionStoragePortable.ts
  • src/history.ts
  • src/utils/fileHistory.ts
  • src/memdir/memdir.ts
  • src/memdir/findRelevantMemories.ts
  • src/memdir/teamMemPaths.ts
  • src/memdir/memoryScan.ts

延伸文件：

  • src/services/SessionMemory/sessionMemory.ts
  • src/services/SessionMemory/sessionMemoryUtils.ts
  • src/projectOnboardingState.ts

阅读重点：

  • bootstrap/state.ts 是进程级状态。
  • AppStateStore.ts 是运行时 UI/应用状态。
  • sessionStorage.ts 与 transcript 恢复强相关。
  • memdir/ 与 SessionMemory/ 是“长期记忆/团队记忆”方向。

12. Feature Flag、实验能力与遥测

架构图对应：

  • Feature-Flagged
  • GrowthBook
  • BUDDY
  • KAIROS
  • ULTRAPLAN
  • analytics / OTel / Datadog

核心文件：

  • src/services/analytics/growthbook.ts
  • src/services/analytics/index.ts
  • src/services/analytics/datadog.ts
  • src/services/analytics/config.ts

与实验能力直接相关的目录：

  • src/services/autoDream/
  • src/coordinator/
  • src/tasks/DreamTask/
  • src/bridge/
  • src/tools/BriefTool/BriefTool.ts
  • src/tools/RemoteTriggerTool/RemoteTriggerTool.ts

阅读重点：

  • 先看 GrowthBook 与 analytics，再回头看各 feature flag 如何在 main.tsx、commands.ts、tools.ts 中控制模块挂载。

建议的第一轮阅读清单

如果你准备按“先主干、后扩展”的方式学，建议顺序如下：

  1. src/bootstrap-entry.ts
  2. src/entrypoints/cli.tsx
  3. src/main.tsx
  4. src/commands.ts
  5. src/query.ts
  6. src/QueryEngine.ts
  7. src/services/api/claude.ts
  8. src/Tool.ts
  9. src/tools.ts
  10. src/services/tools/toolOrchestration.ts
  11. src/services/tools/toolExecution.ts
  12. src/utils/permissions/permissions.ts
  13. src/services/compact/compact.ts
  14. src/services/contextCollapse/index.ts
  15. src/services/mcp/client.ts
  16. src/tasks/LocalAgentTask/LocalAgentTask.tsx
  17. src/bootstrap/state.ts
  18. src/utils/sessionStorage.ts

图与仓库的名称差异

  • 架构图写的是 sessionStorage.ts，当前仓库实际在 src/utils/sessionStorage.ts。
  • 架构图写的是 AppStateStore，当前仓库实际文件是 src/state/AppStateStore.ts。
  • 架构图写的是 Tool Runtime，代码里分散在 Tool.ts、tools.ts、services/tools/ 和各 src/tools/* 下。
  • 架构图把 “Bridge / Remote / Server” 画成独立块，恢复版代码里这三块的边界是清晰的，但很多权限、消息、状态逻辑会交叉复用。
util6 knowledge hub
Copyright © 2026 util6