Claude Code 源码剖析 模块一 · 第五节：PromptSuggestion 智能提示与推测执行

模块一 · 第五节PromptSuggestion 智能提示与推测执行核心问题Claude Code 如何预测用户意图Speculative Execution推测执行是什么提示建议和推测执行如何协同工作背后的实现机制是什么◇ 本节位置Claude Code 全局架构 ┌─────────────────────────────────────────────────────────────────────┐ │ 服务层services/ │ │ │ │ PromptSuggestion ← 本节 │ │ ├── 提示建议 │ │ ├── 推测执行Speculation │ │ └── Forked Agent │ └─────────────────────────────────────────────────────────────────────┘一、概述1.1 两大核心功能源码位置src/services/PromptSuggestion/PromptSuggestion 包含两个相关但不同的功能┌─────────────────────────────────────────────────────────────────────┐ │ PromptSuggestion 系统 │ │ │ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ Prompt Suggestion │ │ Speculative Exec │ │ │ │ (提示建议) │ │ (推测执行) │ │ │ │ │ │ │ │ │ │ 预测用户输入内容 │ │ Fork Agent 预执行 │ │ │ │ Tab 键采纳 │ │ 用户确认后应用 │ │ │ └─────────────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘1.2 提示建议Prompt Suggestion作用预测用户可能输入的提示词触发用户开始输入时显示建议采纳按 Tab 键采纳建议1.3 推测执行Speculative Execution作用Fork 一个子代理预先执行可能的操作触发基于用户上下文自动开始应用用户确认后将其修改合并到主会话二、推测执行核心机制2.1 核心常量源码位置src/services/PromptSuggestion/speculation.ts// 推测执行限制constMAX_SPECULATION_TURNS20// 最多执行 20 轮constMAX_SPECULATION_MESSAGES100// 最多 100 条消息2.2 工具白名单// 允许的写操作工具constWRITE_TOOLSnewSet([Edit,Write,NotebookEdit])// 安全的只读工具constSAFE_READ_ONLY_TOOLSnewSet([Read,Glob,Grep,ToolSearch,LSP,TaskGet,TaskList,])推测执行只允许读操作Read, Glob, Grep 等不修改文件写操作Edit, Write, NotebookEdit会修改文件2.3 隔离机制 - Overlay 文件系统源码位置speculation.ts// 推测执行使用 Overlay 文件系统隔离functiongetOverlayPath(id:string):string{returnjoin(getClaudeTempDir(),speculation,String(process.pid),id)}工作原理┌─────────────────────────────────────────────────────────────────────┐ │ Overlay 文件系统隔离 │ │ │ │ 用户真实目录 (cwd) 推测 Overlay 目录 │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ 真实文件 │ │ 隔离副本 │ │ │ │ (不修改) │◄──────►│ (可修改) │ │ │ └─────────────────┘ copy └─────────────────┘ │ │ │ │ │ ▼ │ │ 如果推测被采纳 │ │ │ │ │ ▼ │ │ 复制到真实目录 │ └─────────────────────────────────────────────────────────────────────┘2.4 执行流程// 推测执行完整流程asyncfunctionspeculate(context:REPLHookContext){// 1. 创建隔离的 OverlayconstoverlayPathgetOverlayPath(speculationId)awaitmkdir(overlayPath,{recursive:true})// 2. Fork 子代理执行constforkedAgentawaitrunForkedAgent({prompt:suggestionPrompt,cwd:overlayPath,// 在 Overlay 中执行isolation:overlay})// 3. 收集推测结果constresultawaitforkedAgent.waitForCompletion()// 4. 如果用户采纳if(userAccepts()){// 将 Overlay 中的修改复制回主目录awaitcopyOverlayToMain(overlayPath,result.writtenPaths)}else{// 清理 OverlayawaitsafeRemoveOverlay(overlayPath)}}三、采纳与回滚3.1 采纳机制源码位置speculation.tsasyncfunctioncopyOverlayToMain(overlayPath:string,writtenPaths:Setstring,cwd:string,):Promiseboolean{letallCopiedtruefor(constrelofwrittenPaths){constsrcjoin(overlayPath,rel)constdestjoin(cwd,rel)try{// 确保目标目录存在awaitmkdir(dirname(dest),{recursive:true})// 复制文件awaitcopyFile(src,dest)}catch{allCopiedfalse}}returnallCopied}3.2 自动清理// 安全删除 OverlayfunctionsafeRemoveOverlay(overlayPath:string):void{rm(overlayPath,{recursive:true,force:true,maxRetries:3,// 最多重试 3 次retryDelay:100,// 重试间隔 100ms},(){}// 忽略错误)}四、提示建议实现4.1 生成策略源码位置promptSuggestion.ts// 提示建议通过多种策略生成asyncfunctiongenerateSuggestion(context:{messages:Message[]systemPrompt:string}):Promisestring|null{// 策略 1: 分析最近对话模式constrecentPatternanalyzeRecentConversations(context.messages)// 策略 2: 读取项目文件推断意图constprojectContextawaitinferFromProjectFiles(context)// 策略 3: 用户设置偏好constuserPreferencegetUserPreference()// 综合生成建议returncombineSuggestions([recentPattern,projectContext,userPreference])}4.2 抑制条件// 某些情况下不显示建议functionshouldSuppressSuggestion():swarm_teammate|non_interactive|null{// 1. Swarm 团队成员不显示if(isAgentSwarmsEnabled()isTeammate()){returnswarm_teammate}// 2. 非交互模式不显示if(getIsNonInteractiveSession()){returnnon_interactive}returnnull}五、Forked Agent5.1 Forked Agent 与 Overlay源码位置src/utils/forkedAgent.ts// Forked Agent 是推测执行的核心interfaceForkedAgentParams{prompt:stringcwd:string// Overlay 目录isolation:overlaymaxTurns?:number// 默认 20}asyncfunctionrunForkedAgent(params:ForkedAgentParams):PromiseForkedAgent{// 1. 创建隔离的子进程constchildspawn(node,[--fork,agent.js],{cwd:params.cwd,env:{...process.env,CLAUDE_ISOLATED:1}})// 2. 传递上下文child.send({type:init,...params})// 3. 返回 Agent 接口return{waitForCompletion:()waitForResult(child),abort:()child.kill()}}5.2 文件状态缓存隔离// Magic Docs 和推测执行都使用文件状态缓存隔离functioncloneFileStateCache(original:FileStateCache):FileStateCache{// 克隆缓存避免共享状态returnnewMap(original)}六、实战应用6.1 典型场景场景用户想要添加一个新功能 1. Claude Code 分析用户最近的对话和项目上下文 2. 启动推测执行Fork Agent - 读取相关文件 - 编写代码 - 所有修改在 Overlay 中进行 3. 用户在终端看到推测的代码执行结果 4. 用户输入确认推测被采纳 5. Overlay 中的修改合并到主目录6.2 性能优化// 推测执行优化// 1. 智能阈值// - 只有置信度 阈值时才执行推测// - 避免不必要的资源消耗// 2. 后台执行// - 不阻塞用户输入// - 用户可以继续工作// 3. 早期终止// - 如果用户已经输入不同内容// - 终止推测执行七、思考题思考题 1推测执行和预执行有什么区别答案// 预执行Pre-execution// - 在用户确认前执行// - 结果可见但不生效// - 例如SQL 执行计划// 推测执行Speculative Execution// - Fork 独立 Agent 执行// - 使用 Overlay 隔离// - 用户确认后才合并// - 特点完全隔离可回滚思考题 2Overlay 文件系统有什么优势答案// 优势// 1. 完全隔离// - 不影响主工作目录// - 用户看不到未确认的修改// 2. 原子性// - 用户不采纳时完全不修改// - 采纳时一次性合并// 3. 可回滚// - 不需要版本控制系统// - 直接删除 Overlay 即可思考题 3推测执行有什么限制答案// 限制// 1. 轮数限制// - 最多 20 轮MAX_SPECULATION_TURNS// - 防止推测时间过长// 2. 消息限制// - 最多 100 条消息// - 控制 Token 消耗// 3. 工具限制// - 只能用白名单工具// - 禁止可能有副作用的操作// 4. 环境依赖// - 推测时环境可能变化// - 某些操作不适合推测八、延伸阅读资源说明src/services/PromptSuggestion/promptSuggestion.ts提示建议实现src/services/PromptSuggestion/speculation.ts推测执行核心src/utils/forkedAgent.tsForked Agentsrc/utils/fileStateCache.ts文件状态缓存