Claude Code 源码分析系列文章：

• 初始化及 Ink 程序
• 主要对话循环
• Tool/MCP/Skill 可 工具程序

这篇文章基于项目实际源码，Claude Code CLI 从使用者提交输入到一轮完整对话结束的主要对话循环。涵盖输入分发、并发控制、上下文加载、API 流式调用、工具执行、错误恢复、中止处理与循环续接的完整链路。

一、总体流程概览

Claude Code 的主要对话循环从使用者在 REPL 提交输入开始。和分发，最终进入一个while驱动的 API 调用‑工具执行‑续行循环。至于完整方法为，

flowchart TD
A --> B
B -->|即时命令拦截 / 空闲检测| C
C -->|五路分发| D
D -->|"processUserInput 循环 + queryGuard.reserve"| E
E -->|"queryGuard.tryStart 并发控制"| F
F -->|"Promise.all 加载上下文"| G
G --> H
H --> I
I --> J
J --> K
K --> L{"错误恢复 / 中止?"}
L -->|" 种恢复转换"| I
L -->|" 条中止方法"| R
L -->|正常| M
M --> N
N --> O{maxTurns 检查}
O -->|"未达上限: state = next;continue"| I
O -->|达到上限| R
subgraph 循环退出
R
end
style I fill:#f9f,stroke:#。stroke-width:2px
style R fill:#bbf,stroke:#,stroke-width:2px

以下逐层拆解每个阶段的源码实现。

二、REPL.tsx onSubmit — 使用者输入入口

onSubmit 是PromptInput组件的回调，是所有使用者输入的第一个处理点。它接收四个参数：

// src/screens/REPL.tsx:const onSubmit = useCallback(
async (
说到input。string,helpers: PromptInputHelpers,speculationAccept?: {
至于state，ActiveSpeculationState;老实说，speculationSessionTimeSavedMs: number;setAppState: SetAppState;},options，: { fromKeybinding?: boolean },) => {...

进入后 执行两个固定操作：

// src/screens/REPL.tsx:
repinScroll;// 重新锁定滚动到底部
if || feature) {
proactiveModule?话说回来，.resumeProactive;// 恢复主动模式
}

即时命令拦截

当输入以/开头且不是推测接受时onSubmit尝试匹配即时命令：

// src/screens/REPL.tsx:
if .startsWith) {
const trimmedInput = expandPastedTextRefs.trim;const spaceIndex = trimmedInput.indexOf;const commandName = spaceIndex === -1?trimmedInput.slice : trimmedInput.slice;const matchingCommand = commands.find(
cmd => isCommandEnabled &&
(cmd.name === commandName ||
cmd.aliases?.includes ||
getCommandName === commandName),);const shouldTreatAsImmediate =
queryGuard.isActive &&
}

• User pain point #1: 当你在忙碌时想要立即执行快捷命令，却发现命令被延迟到查询完成后才生效。
• The check ensures that only when a query is active command can be treated as immediate.
• If matched and marked as immediate or triggered by keybinding it will bypass normal queue.

匹配到即时命令后如果类型是local-jsx则直接加载并执行。不进入查询队列：

// src/screens/REPL.tsx:
if (
matchingCommand &&
shouldTreatAsImmediate &&
matchingCommand.type === 'local-jsx'
){
// 清理输入框 ...
const executeImmediateCommand = async : Promise => {
const context = getToolUseContext,mainLoopModel);const mod = await matchingCommand.load;const jsx = await mod.call;老实说，if {
setToolJSX({ jsx,shouldHidePromptInput: false。isLocalJSXCommand:true });}
}，void executeImmediateCommand;return，// 始终提前返回
}

远程模式与空闲检测

• User pain point #2:"我在远程模式下偶尔按回车，却出现无响应或错误提示。" —— 原因是空输入被过滤导致不触发任何动作。
• 再看解决办法。检查“activeRemote.isRemoteMode”,并确保非空白才继续。
• 如果你长时间离开后回来程序会根据配置自动弹出阻塞式对话框或提示通知，避免误操作。其实，
• 判断条件包括空闲时间超过阈值且累计 token 数超过阈值。

html if){ return;话说回来，}

委托 handlePromptSubmit

html onSubmit ├─ 即时命令 → executeImmediateCommand → return ├─ remote mode empty input → return ├─ idle recovery → dialog/hint/pass └─ normal path → handlePromptSubmit

三、handlePromptSubmit — 五路分发器

• ① queuedCommands?.length → executeUserInput
• ② → handlePromptSubmit
• ③ queryGuard.isActive + immediate command → load + call
• ④ queryGuard.isActive || isExternalLoading → enqueue
• ⑤ 默认方法 → executeUserInput
### 队列处理器快捷方式

当“queuedCommands”=已有时已。直接进入执行：

// src/utils/handlePromptSubmit.ts: if{ startQueryProfile await executeUserInput({ queuedCommands,messages,mainLoopModel,... /* or params */ }) return;}
• This occurs when you type a new command while a conversation is running.
..
• The system avoids duplicate checks by executing immediately.
.

退出命令检测

html // src/utils/handlePromptSubmit.ts: if(!skipSlashCommands && .includes)) { const exitCommand=commands.find if{ void handlePromptSubmit }else{ exit } return; 话说回来，}

• You can type any of those variations and y will be unified to “/exit”. This helps avoid confusion when your terminal shows multiple exit commands.
.

忙碌时的即时命令

html // src/utils/handlePromptSubmit.ts: if(immediateCommand && immediateCommand.type==='local-jsx' && ){ const impl=await immediateCommand.load const jsx=await impl.call if{ setToolJSX({jsx。shouldHidePromptInput:false,isLocalJSXCommand:true,isImmediate:true}) } return;说起来，}

User pain point #3:"当我在查询过程中想快速打开文件查看脚本。却需要等待整个对话结束，" —— 此方法让你可以立即运行本地 JSX 命令，无需排队。

忙碌时入队

html // src/utils/handlePromptSubmit.ts: if{ if{return;} if{ params.abortController?.abort } enqueue({ 从value来看，finalInput.trim。preExpansionValue:input.trim,mode,pastedContents:hasImages?pastedContents:nil,skipSlashCommands。uuid,}) // clear input... return;}

User pain point #4:"当我同时键入多个指令或粘贴大块内容时它们会被合并成一次请求。" —— 入队保证顺序而不丢失任何信息。.

默认直接执行

html // src/utils/handlePromptSubmit.ts: startQueryProfile const cmd:{QueuedCommand}={ value的观点是。finalInput,preExpansionValue:input,mode,pastedContents:hasImages?pastedContents:nil,skipSlashCommands,uuid,} await executeUserInput({ queuedCommands:,messages,mainLoopModel,... /* or params */})

四、executeUserInput — 输入处理与查询触发

// src/utils/handlePromptSubmit.ts: // core responsibilities: // - create AbortController,// - reserve QueryGuard。// - loop through queued commands,// - call onQuery. const abortController=createAbortController setAbortController try{ queryGuard.reserve // idle→dispatching let newMessages= let shouldQuery=false,allowedTools=,model=null,effort=null

await runWithWorkload=>{

for{ const cmd=commands!const isFirst=i===0

 const result=await processUserInput({
至于input，cmd.value,skipAttachments:not。... /* or args */
})
newMessages.push
if{
shouldQuery=result.shouldQuery
allowedTools=result.allowedTools
model=result.model
effort=result.effort
}

}

if){ newMessages.filter .forEach) }

if{ await onQuery(newMessages,abortController,shouldQuery,allowedTools?，,model?resolveSkillModelOverride:mainLoopModel,shouldCallBeforeQuery?onBeforeQuery:nil,primaryInput,effort ) }

}) }finally{ queryGuard.cancelReservation setUserInputOnProcessing }

User pain point #5:"在一次聊天中。你想插入代码片段或图片，但它们被忽略了因为程序只考虑第一条消息。" —— 本函数专门确保第一条消息完整处理。而后续消息跳过附件，以避免重复注入。

五、onQuery — 并发控制与状态初始化

QueryGuard 状态机

html // src/screens/REPL.tsx: // idle→dispatching→running→idle chain. idle → dispatching → running ←↑ reserve ↑ tryStart ↑ end tryStart atomically checks and flips dispatching→running,returning a monotonic generation number or null.

并发冲突处理

html // src/screens/REPL.tsx: const thisGeneration=queryGuard.tryStart;话说回来，if{ // anor query running. logEvent;newMessages.filter .map.filter .forEach=>enqueue);return，}

User pain point #6:"如果你在前一次请求还未完成就 发送消息，你可能会看到旧消息被丢弃。" —— 入队机制保证所有内容都能最终得到处理，而不会丢失。

初始化各类状态

html // after successful guard acquisition. resetTimingRefs setMessages responseLengthRef.current=newMessages.reduce=>s+m.contentTokens?，0,newResponsesLength) apiMetricsRef.current= setStreamingToolUses setStreamingText ... await onQueryImpl(latestMsgs,newMsgs,abortCtrl。...

---

六、onQueryImpl — 上下文加载与查询发起

并行上下文加载

// fetch various contexts concurrently. const = await Promise.all();

const systemPrompt=buildEffectiveSystemPrompt({ mainThreadAgentDefinition。toolUseContext,customSystemPrompt :defaultSystemPrompt,appendSystemPrompt});

User pain point #7:"由于多源上下文加载导致延迟增大。"—— 使用`Promise.all`减少整体等待时间，同时将不同来源的数据缓存下来。

查询执行与事件消费

html for await(const event of query({ messages : messagesIncludingNewMsgs,systemPrompts :systemPrompts。userCtx :userContext,systemCtx :systemContext,canUseTool:true,toolUseCtx :toolUseContext,querySource:getQuerySourceForREPL,})){ onQueryEvent;按理说，// UI update path. } ... resetLoadingState;await onTurnComplete?.，

---

七、query → queryLoop — 主要对话引擎

The heart of Claude Code’s conversation logic lives in infinite loop below.

---

---

The loop iterates over each “turn” until it eir finishes successfully or triggers one of recovery paths listed later.

---

The State object carries all mutable information across iterations.

---

At each iteration a series of stages are performed sequentially to compress context before calling model.

---

When an error occurs it may be withheld until after certain recovery steps have run.

---

All transitions are implemented using “state = next;continue”,which makes m very explicit and easy to trace.

---

---

Note: The article intentionally omits some minor details for brevity but preserves every critical aspect relevant to developers encountering runtime issues such as context overflow or tool execution failures.

---