前段时间Claude code源码泄露，但一直没来的急仔细读一读源码，最近从头到尾开始捋了一遍源码，给大家分享下从输入到获取输出到底经历了多少部，中间cc又做了哪些工程化的工作和harnness管理。

ClaudeCode 作为一款具备 Agent 能力的交互式工具，其核心优势在于对用户输入的全链路精细化处理——从用户提交需求，到最终返回输出结果，整个流程被清晰拆分为 8 个分层，各层职责单一、协同高效。本文将逐层拆解每一步的核心逻辑、关键代码路径，帮你吃透 ClaudeCode 从输入到输出的完整运行机制，适合源码学习者、Agent 开发爱好者参考学习。

核心结论：ClaudeCode 的输入输出链路并非“用户输入→直接调用模型”的简单流程，而是一套“输入网关→消息标准化→上下文拼装→agent loop→工具编排→状态持久化→异步事件回流”的完整 Agent Runtime 架构，全程通过分层解耦保证可扩展性和可维护性。

一、全流程8层拆解（从启动到输出）

用户需求从提交到获得输出，整体可拆分为 8 个核心分层，每层对应明确的代码文件和核心职责，以下按执行顺序逐层解析：

1. 启动层：运行环境初始化（主入口编排）

核心职责：在用户进入会话前，完成运行环境、权限、外部依赖的初始化，为后续交互做好准备。

关键代码路径：主入口 main.tsx

main.tsx 并非业务主循环，更像是“启动编排器”，核心执行逻辑包括 4 件事：

• 初始化权限上下文：调用initializeToolPermissionContext\(\)，具体代码见 main.tsx:1747，用于管理工具调用的权限控制。

• 连接 MCP（外部工具/命令池）：补齐系统可调用的外部工具和命令，代码见 main.tsx:2704，是后续工具调用的基础。

• 准备核心配置：初始化 sessionConfig（会话配置）、初始状态（initial state）、resume 数据（会话恢复数据），确保会话可正常启动和恢复。

• 进入交互主界面：调用 launchRepl\(\.\.\.\) 启动交互环境，代码见 main.tsx:3798，至此启动流程完成，进入用户交互阶段。

2. 交互入口层：用户输入接收（REPL 交互环境）

核心职责：接收用户输入，判断当前系统状态，决定输入是立即执行还是入队等待。

关键代码路径：REPL.tsx

用户通过 REPL（交互式环境）提交输入后，核心触发 handlePromptSubmit\(\.\.\.\)方法，代码见 REPL.tsx:3490，该方法的核心职责的：

• 读取输入相关信息：获取当前用户输入内容（input）、粘贴内容、当前交互模式。

• 输入类型判断：判断用户输入是否为 slash command（斜杠命令，如 /exit）。

• 系统状态判断：检查当前系统是否处于 loading（加载中）或 query（查询中）状态。

• 输入调度：如果系统正忙（处于 loading/query 中），则将输入放入消息队列；如果系统空闲，则直接向下传递输入，进入后续处理流程。

3. 输入处理层：输入清洗与分流（输入网关）

核心职责：对用户输入进行预处理，判断输入是否需要排队，最终触发输入执行逻辑。

关键代码路径：handlePromptSubmit.ts

该文件是用户输入的“网关”，核心做 3 类事情，确保输入合规、调度合理：

• 输入预处理：清理空输入（避免无效请求）、处理图片/粘贴引用（统一输入格式）、将特殊退出命令（如 quit）转为标准的 /exit 命令，保证输入格式标准化。

• 排队判断：检查当前是否有正在执行的 query，如果有，通过 enqueue\(\.\.\.\) 方法将当前输入放入消息队列，避免并发冲突。

• 输入执行：如果无需排队，调用 executeUserInput\(\.\.\.\) 方法，该方法内部会进一步调用 processUserInput\(\.\.\.\)，将输入传递到下一层。

4. 语义分流层：输入类型判断（决定是否调用模型）

核心职责：对预处理后的输入进行语义判断，分流到不同的处理逻辑，核心决定输入是否需要进入大模型主循环。

关键代码路径：processUserInput.ts

这是整个链路的“分流枢纽”，并非所有输入都会调用大模型，而是先进行分类处理，支持的输入类型包括：

• 普通文本 prompt（如“帮我写一段代码”）

• slash command（斜杠命令，如 /help、/exit）

• bash command（终端命令）

• 带图片/附件的输入

• bridge/remote 输入（远程交互输入）

• meta/system 触发输入（系统级触发的输入）

处理完成后，会输出一个统一的结果结构，包含以下核心字段：

• messages：标准化后的消息内容

• shouldQuery：核心判断字段（true：需要进入模型主循环；false：本地命令可直接处理，无需调用模型）

• allowedTools：当前输入可调用的工具列表

• model：指定使用的模型

• effort：模型推理力度

• resultText：本地处理的结果（若 shouldQuery 为 false）

其中，普通文本输入最终会进入 processTextPrompt\(\.\.\.\) 方法处理，代码见processUserInput.ts:578。

5. 查询调度层：模型调用判断（进入主执行引擎）

核心职责：根据 shouldQuery 的值，决定是否进入模型主执行引擎，同时组装会话上下文。

关键代码路径：

• 交互模式：REPL.tsx:2855（onQuery 方法）

• 非交互/SDK/print 模式：print.ts:2147

核心逻辑：

• 若 shouldQuery = true：REPL 会触发 onQuery\(\.\.\.\) 方法，进而调用 ask\(\.\.\.\) 方法，进入模型主执行引擎；非交互模式下，直接通过 print.ts 路径进入 ask\(\.\.\.\)。

• 上下文组装：调用 ask\(\.\.\.\) 时，会将当前会话的核心状态一并传入，包括：当前 messages、工具池（tool pool）、命令列表（commands）、mcp clients、权限上下文（permission context）、思考配置（thinking config）、模型（model）、应用状态（app state）、中断控制器（abort controller），确保模型能获取完整的会话上下文。

6. 主执行引擎层：Agent 循环启动（QueryEngine 主导）

核心职责：创建 QueryEngine 实例，主导一轮用户请求的完整处理，是整个链路的“总导演”。

关键代码路径：QueryEngine.ts

核心执行逻辑（围绕 ask\(\) 方法展开）：

• 创建 QueryEngine 实例：通过 new QueryEngine\(\.\.\.\) 初始化，将上一层传递的会话上下文、工具池等依赖注入实例。

• 触发消息提交：调用 engine\.submitMessage\(\.\.\.\)方法，启动一轮会话的核心处理流程，该方法的核心代码见 QueryEngine.ts:209。

submitMessage\(\.\.\.\) 方法的主流程的：

1. 构建上下文：组装 system prompt（系统提示）、user context（用户上下文）、system context（系统上下文），为模型推理提供基础。

2. 二次输入处理：再次调用 processUserInput\(\.\.\.\)，确保输入经过二次校验和标准化。

3. 消息写入：将新的用户消息写入 mutableMessages（可变消息列表），用于后续模型推理和状态持久化。

4. 转录写入：若需要，将用户消息写入 transcript（会话转录记录），用于会话回溯。

5. 本地处理判断：若 shouldQuery = false，直接返回本地处理结果，无需进入模型循环。

6. 模型循环启动：若 shouldQuery = true，进入 query\(\.\.\.\) 方法的 for-await 主循环，启动 Agent 推理和工具调用流程。

7. 模型-工具循环层：推理与工具执行（核心 Agent 逻辑）

核心职责：模型推理生成响应，若需要调用工具则执行工具调用，将工具结果回流给模型，循环直至生成最终输出。

关键代码路径：

• 工具编排：toolOrchestration.ts

• 工具执行：toolExecution.ts

完整工具调用链路：

1. 模型输出：模型推理后，返回 assistant 响应内容和 tool\_use（需要调用的工具列表）。

2. 工具并发判断：runTools\(\.\.\.\) 方法判断工具是否可并发执行（读类工具可批量并发，写类工具串行执行，避免冲突）。

3. 工具执行分发：每个 tool\_use 被分发到 runToolUse\(\.\.\.\) 方法，执行具体的工具调用。

4. 工具执行细节：runToolUse\(\.\.\.\) 方法内部完成 5 件事：

- schema 校验：校验工具调用参数是否符合规范。- 权限检查：检查当前用户是否有该工具的调用权限。- 钩子执行：执行工具调用的 pre/post hooks（前置/后置处理）。- 实际调用：调用 `tool\.call\(\)` 执行工具逻辑，获取工具返回结果。- 状态记录：记录工具执行进度（progress）、埋点（telemetry）、错误信息（error）。

1. 结果回流：工具执行结果被封装成消息，重新喂回模型，模型基于工具结果继续推理，进入下一轮循环。

核心 Agent 循环逻辑： 用户输入 → 模型思考 → 调用工具 → 工具结果回流 → 模型继续思考 → 直至生成最终响应（停止工具调用）。

8. 队列与异步事件层：消息管理与回流（避免消息丢失）

核心职责：管理异步消息和事件，确保当前执行过程中收到的新输入、系统事件不丢失，实现异步事件回流。

关键代码路径：messageQueueManager.ts

消息队列（messageQueue）是整个系统的“异步中枢”，核心作用包括：

• 输入入队：当前一轮会话（turn）正在执行时，新提交的用户输入会通过 enqueue\(\.\.\.\) 进入消息队列，等待当前轮次结束后执行。

• 事件处理：背景 Agent 执行完成后，会发送 task\-notification 事件，该事件也会进入消息队列。

• 多源事件兼容：channel/bridge/system 等系统级事件，均会进入消息队列统一管理。

• 消息出队：当前轮次执行完成后，通过 dequeue\(\.\.\.\) 方法从队列中取出下一条消息执行，非交互 print 路径的主循环会持续调用 dequeue\(\.\.\.\)，代码见 print.ts:1935。

• 事件回流：task\-notification 事件不会丢失，会作为下一轮输入重新进入 ask\(\.\.\.\) 方法，继续处理，代码见 print.ts:2012。

二、输入输出全流程流程图（浓缩版）

main.tsx-> 初始化权限 / MCP / session 配置-> launchRepl() 启动交互环境-> 用户提交输入（REPL 界面）-> handlePromptSubmit() （输入清洗、排队判断）-> processUserInput() （语义分流，判断 shouldQuery）-> 若 shouldQuery = false → 本地处理，返回结果-> 若 shouldQuery = true → onQuery() → ask()-> QueryEngine.submitMessage() （组装上下文、启动循环）-> query() 主循环（模型推理 + 工具调用）-> toolOrchestration.ts / toolExecution.ts （工具编排与执行）-> 工具结果回流，模型继续推理-> 生成最终 assistant 响应-> 结果写入 transcript / 会话状态-> 消息队列 dequeue()，等待下一条输入/事件

三、架构视角：核心分层总结

从架构设计来看，ClaudeCode 的输入输出链路可归纳为 6 个核心模块，各模块职责解耦、协同高效，符合 Agent Runtime 的设计规范：

1. 启动编排层：main.tsx，负责环境初始化、依赖加载、启动交互环境，是整个系统的入口。

2. 交互与输入管理层：REPL.tsx + handlePromptSubmit.ts，负责接收用户输入、预处理、排队调度，是输入的“第一道网关”。

3. 输入语义分流层：processUserInput.ts，负责输入分类、标准化，决定是否调用模型，是链路的“分流枢纽”。

4. 会话级执行引擎层：QueryEngine.ts，主导一轮会话的完整处理，是整个链路的“核心驱动”。

5. 工具执行内核层：toolOrchestration.ts + toolExecution.ts，负责工具编排、权限校验、实际执行，是 Agent 能力的核心载体。

6. 异步事件与任务回流层：messageQueueManager.ts + LocalAgentTask.tsx，负责异步消息管理、事件回流，确保系统稳定性和消息不丢失。

四、设计风格总结

ClaudeCode 的输入输出链路，核心设计风格是“精细化分层、异步化管理、标准化流转”，区别于简单的“输入→模型→输出”流程，其核心特点：

• 分层解耦：每个分层职责单一，可独立扩展（如新增工具类型，仅需修改工具执行层，不影响其他层）。

• 异步兼容：通过消息队列管理并发输入和系统事件，避免消息丢失，提升系统稳定性。

• 标准化：输入预处理、消息格式、工具调用均有统一标准，降低各模块协同成本。

• 可扩展：支持交互/非交互多模式，支持远程/本地工具调用，适配不同使用场景。

本质上，这是一套完整的 Agent Runtime 架构，不仅能处理简单的文本输入，还能通过工具调用、异步事件回流，实现复杂任务的自动化处理，这也是 ClaudeCode 核心能力的体现。

补充说明

本文基于 ClaudeCode 源码，完整拆解用户输入到输出的 8 层链路，包含所有关键代码路径、核心逻辑和架构设计，Markdown 格式适配 CSDN 发表，无需额外修改。若需进一步深入，可补充两种拆解方式：1. 完整时序图；2. 核心调用链（processUserInput → ask → query → runTools）的函数级拆解。