18-plan与ultraplan命令 - AI规划引擎

18. plan与ultraplan命令 - AI规划引擎所属分组命令系统概述/plan和/ultraplan命令构成了 Claude Code 的 AI 规划引擎允许用户将复杂任务分解为可执行的步骤。/plan命令启用本地规划模式让模型在当前会话中生成和执行计划/ultraplan命令则利用 Claude Code on the web 的多智能体能力进行更深入的任务分析和规划。规划模式的核心设计理念是先规划、后执行通过将大型任务分解为小步骤提高任务成功率和可追溯性。计划文件以 Markdown 格式存储支持在外部编辑器中编辑方便用户手动调整。源码位置plan命令实现[commands/plan/plan.tsx](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/commands/plan/plan.tsx)ultraplan命令[commands/ultraplan.tsx](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/commands/ultraplan.tsx)计划文件管理[utils/plans.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/utils/plans.ts)规划模式工具[tools/ExitPlanModeTool/](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/tools/ExitPlanModeTool/)远程会话管理[utils/teleport.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/utils/teleport.ts)核心实现分析plan命令实现/plan命令的核心逻辑在plan.tsx中实现主要功能包括模式切换当用户不在规划模式时启用规划模式并切换权限上下文exportasyncfunctioncall(onDone:LocalJSXCommandOnDone,context:LocalJSXCommandContext,args:string):PromiseReact.ReactNode{constappStategetAppState()constcurrentModeappState.toolPermissionContext.modeif(currentMode!plan){handlePlanModeTransition(currentMode,plan)setAppState(prev({...prev,toolPermissionContext:applyPermissionUpdate(prepareContextForPlanMode(prev.toolPermissionContext),{type:setMode,mode:plan,destination:session})}))// ...}}计划显示当用户已在规划模式时读取并显示当前计划内容constplanContentgetPlan()constplanPathgetPlanFilePath()if(!planContent){onDone(Already in plan mode. No plan written yet.)returnnull}编辑器集成支持通过/plan open在外部编辑器中打开计划文件if(argList[0]open){constresultawaiteditFileInEditor(planPath)if(result.error){onDone(Failed to open plan in editor:${result.error})}else{onDone(Opened plan in editor:${planPath})}returnnull}ultraplan远程规划/ultraplan是高级规划命令利用 Claude Code on the web 的多智能体能力核心流程资格检查验证用户是否符合使用条件登录状态、权限等会话创建通过teleportToRemote()创建远程会话计划生成远程会话中的模型生成详细计划轮询等待本地通过pollForApprovedExitPlanMode()轮询计划状态结果处理用户批准后选择在远程执行或传送回本地exportasyncfunctionlaunchUltraplan(opts:{blurb:stringseedPlan?:stringgetAppState:()AppStatesetAppState:(f:(prev:AppState)AppState)voidsignal:AbortSignal}):Promisestring{// 资格检查consteligibilityawaitcheckRemoteAgentEligibility()if(!eligibility.eligible){// 处理错误...}// 创建远程会话constsessionawaitteleportToRemote({initialMessage:prompt,description:blurb||Refine local plan,model,permissionMode:plan,ultraplan:true,})// 注册任务并启动轮询const{taskId}registerRemoteAgentTask({...})startDetachedPoll(taskId,session.id,url,getAppState,setAppState)}轮询机制startDetachedPoll()在后台异步轮询远程会话状态functionstartDetachedPoll(taskId:string,sessionId:string,url:string,...):void{void(async(){const{plan,rejectCount,executionTarget}awaitpollForApprovedExitPlanMode(sessionId,ULTRAPLAN_TIMEOUT_MS,phase{// 更新任务状态updateTaskState(taskId,setAppState,t({...t,ultraplanPhase:phaserunning?undefined:phase}))})// 根据执行目标处理结果if(executionTargetremote){// 在远程执行}else{// 传送回本地setAppState(prev({...prev,ultraplanPendingChoice:{plan,sessionId,taskId}}))}})()}计划文件管理utils/plans.ts提供了计划文件的存储和恢复机制计划文件路径exportfunctiongetPlanFilePath(agentId?:AgentId):string{constplanSluggetPlanSlug(getSessionId())if(!agentId){returnjoin(getPlansDirectory(),${planSlug}.md)}returnjoin(getPlansDirectory(),${planSlug}-agent-${agentId}.md)}计划恢复支持从消息历史中恢复丢失的计划文件functionrecoverPlanFromMessages(log:LogOption):string|null{for(letilog.messages.length-1;i0;i--){constmsglog.messages[i]// 从 tool_use 输入中恢复// 从 user message 的 planContent 字段中恢复// 从 attachment 的 plan_file_reference 中恢复}returnnull}关键设计要点模式隔离规划模式通过独立的权限上下文实现安全隔离限制模型在规划阶段的操作范围。文件持久化计划以 Markdown 文件形式存储支持版本控制和外部编辑提高可追溯性和可编辑性。远程/本地协作ultraplan通过 teleport 机制实现本地和远程会话的无缝协作充分利用两端资源。异步轮询远程规划的状态轮询在后台执行不阻塞本地终端操作提升用户体验。计划恢复支持从消息历史中恢复丢失的计划文件提高可靠性。多智能体支持子智能体有独立的计划文件避免冲突。超时控制ULTRAPLAN_TIMEOUT_MS设置 30 分钟超时防止无限等待。优雅降级远程会话失败时自动清理资源确保状态一致性。与其他模块的关系命令系统/plan和/ultraplan注册到全局命令列表权限系统规划模式有独立的权限上下文状态管理计划模式状态存储在AppState中工具系统ExitPlanModeTool用于退出规划模式并执行计划远程会话ultraplan通过 teleport 连接到远程 CCR 会话任务系统远程规划注册为后台任务编辑器集成支持在外部编辑器中编辑计划小结/plan和/ultraplan命令构成了 Claude Code 的 AI 规划引擎实现了先规划、后执行的开发工作流。本地规划模式提供了轻量级的任务分解能力而远程规划则利用多智能体进行深度分析。整个设计注重用户体验异步执行、状态反馈和系统可靠性计划持久化、恢复机制、资源清理是 AI 辅助复杂任务管理的典型实现。