提示词到工具再到渲染
这一页解释一次普通 prompt 如何从输入解析进入主循环，再经过工具执行、状态同步和终端渲染。它是理解 Claude Code 运行时行为的关键主线。
输入为什么有时变成命令、有时进入 QueryEngine、有时触发工具？
理解输入层、主循环、工具层、状态层和扩展层如何接力。
先看总链路，再看每个模块透视，最后回到源码入口逐个对应。
流程总览
一次普通 prompt 真正跑起来时，不只是“模型回答问题”这么简单。它至少会穿过输入解析、命令判断、上下文组装、QueryEngine 主循环、工具编排、状态同步和终端渲染这几层。读懂这条链，基本就抓住了 Claude Code 的执行骨架。动态路径
- 用户在终端输入内容
src/utils/processUserInput/processUserInput.ts判断它是普通 prompt 还是 slash command- 普通 prompt 进入
src/query.ts/src/QueryEngine.ts - QueryEngine 组装上下文并发起模型调用
- 如果模型请求工具，则进入
src/tools.ts与对应src/tools/* - 工具执行结果回流给 QueryEngine
- QueryEngine 产出消息与状态变化
src/state/与src/components//src/ink/把结果渲染到终端
这个流程里最重要的分叉点
分叉点 1：命令还是 prompt
这一步决定当前输入是本地命令逻辑，还是模型对话逻辑。分叉点 2：文本回答还是工具调用
这一步决定当前轮次是否只需要模型文本，还是要进入文件系统、shell、搜索、插件等能力。分叉点 3：前台渲染还是后台任务
这一步决定结果是直接显示给用户，还是转入任务系统、多代理或远程能力继续处理。输入与命令模块透视
模块定位
输入层负责把“终端里的一段文本”变成系统可理解的动作。它既是流程入口，也是第一道分流器。关键文件
src/utils/processUserInput/processUserInput.tssrc/commands.ts- 输入与命令层模块页
上游 / 下游
- 上游：终端输入、远程桥接输入、系统生成 prompt
- 下游：本地命令执行、
query.ts、用户消息对象、hook 链
运行时行为
- 识别 slash command、普通 prompt、附件、meta prompt
- 执行 prompt submit hooks 与部分前置检查
- 决定这次输入是留在本地命令层，还是进入 QueryEngine
常见误区
输入层不是业务主循环，它负责“分流”和“标准化输入”，不负责承载大部分后续执行逻辑。建议阅读顺序
processUserInput的参数与返回结构- slash command 分支
- shouldQuery 分支如何把消息送往后续链路
查询入口与上下文模块透视
模块定位
查询入口层负责把已经标准化的输入转成一次真正可发起的查询。它是输入层和 QueryEngine 之间的桥。关键文件
src/query.tssrc/context.ts- QueryEngine 模块页
上游 / 下游
- 上游：输入解析结果
- 下游：系统 prompt、上下文注入、模型调用配置、QueryEngine
运行时行为
- 统一消息格式
- 拼接系统上下文和用户上下文
- 构建查询期需要的配置、工具上下文和预算信息
常见误区
很多人只盯着QueryEngine.ts，忽略了 query.ts 和上下文层。这样会看不清“消息是如何被包装后送入主循环”的。建议阅读顺序
query.ts的 query loop 入口context.ts里的上下文收集逻辑- 再进入
QueryEngine.ts
QueryEngine 模块透视
模块定位
QueryEngine 是这条链中真正的会话级调度器。只有经过它，输入才会变成带有模型交互、工具往返和状态更新的一次完整回合。关键文件
src/QueryEngine.tssrc/query.ts- QueryEngine 模块页
上游 / 下游
- 上游：输入层、查询入口层、上下文层
- 下游：模型 API、工具层、会话存储、预算与成本跟踪
运行时行为
- 持有消息历史和文件状态缓存
- 发起模型调用并处理流式响应
- 在需要时触发工具执行，再把结果拼回后续轮次
- 记录权限拒绝、结构化输出、token 使用和会话状态
常见误区
它不是单纯的“API caller”。真正难的部分在于：它还要维持消息演化、工具结果配对、预算恢复和错误回流。建议阅读顺序
submitMessage- QueryEngine 对
query()的调用与状态持有 - 再回看
query.ts里的流式循环
工具执行模块透视
模块定位
工具层定义了模型从“会回答”到“会执行”的边界。它是整条流程里最重要的能力出口之一。关键文件
src/tools.tssrc/Tool.tssrc/tools/*- 工具执行层模块页
上游 / 下游
- 上游：QueryEngine 发出的工具请求
- 下游：文件系统、shell、网络、MCP、插件、任务、多代理
运行时行为
- 根据 feature gate、环境和权限上下文决定哪些工具暴露给模型
- 执行具体工具逻辑
- 将工具结果格式化后回流给 QueryEngine
常见误区
tools.ts 不是具体实现目录，而是能力注册表；真正的执行细节分布在各个 Tool 实现和工具服务编排里。建议阅读顺序
Tool.tstools.ts- 代表性工具，例如
BashTool、FileReadTool、AgentTool
状态与 UI 模块透视
模块定位
状态层和 UI 层负责把内部执行过程转成用户可感知的终端体验。没有这层，前面所有过程都只能停留在内部数据结构里。关键文件
src/state/AppStateStore.tssrc/components/src/ink/- 状态与任务系统模块页
- UI 渲染模块页
上游 / 下游
- 上游：QueryEngine 产出的消息、任务状态、工具结果、权限反馈
- 下游：终端界面、任务面板、状态栏、输入区和后续交互
运行时行为
- AppState 存储 UI 需要消费的事实，例如任务、bridge、remote、footer 选择、toolPermissionContext
- Ink 和组件层把这些状态渲染为持续变化的终端界面
- 在前台回答、后台任务、多代理切换之间维持一致的用户感知
常见误区
UI 层不是单纯“最后打印结果”，而是在持续消费状态变化；因此必须结合AppStateStore.ts 一起看。建议阅读顺序
AppStateStore.tsinteractiveHelpers.tsx/ink.ts- 再看具体组件
服务与扩展参与模块透视
模块定位
服务和扩展层并不总在每次 prompt 中显式出现，但它们常常是这条流程是否能继续下去的隐形基础，例如 API、MCP、bridge、plugins、skills。关键文件
上游 / 下游
- 上游：QueryEngine、工具层、命令层
- 下游：外部 API、MCP Server、IDE、插件运行时、技能装载
运行时行为
- 提供模型 API 和协议接入
- 为工具调用提供外部资源与协议支撑
- 在后台任务、多代理、bridge 场景中把本地流程扩展到更大边界
常见误区
这层虽然经常“看不见”，但不是可有可无的附属层。很多工具和高级能力其实都建立在这里。建议阅读顺序
services/api/services/mcp/bridge/、plugins/、skills/
对应源码入口
src/utils/processUserInput/processUserInput.ts
src/query.ts、src/QueryEngine.ts
src/tools.ts、src/Tool.ts
src/state/AppStateStore.ts、src/components/、src/ink/