输入 "ultraplan" 关键词,Claude Code 会在云端启动一个使用最强模型的远程会话,花 10-30 分钟制定详细计划。你在浏览器中审批,然后选择在云端执行或传回本地。
把最复杂的规划任务外包给云端最强模型。
当你面对一个复杂任务不知道从哪下手时,输入 "ultraplan 重构整个认证系统",Claude Code 会在云端(Claude Code on the Web)启动一个使用 Opus 模型的远程会话,在 Plan 模式下花 10-30 分钟制定一个详细的执行计划。你可以在浏览器中和 AI 讨论、修改计划,审批后选择在云端执行或传回本地终端执行。整个过程中你的本地终端不会被阻塞。
把 ULTRAPLAN 想象成请一个高级顾问。
你是一个项目经理,手头有个复杂的系统重构任务。你可以自己慢慢想,也可以:
keyword.ts 中 120 行代码只为做好一件事:准确识别用户意图。
| 方式 | 示例 | 说明 |
|---|---|---|
| 关键词 | "帮我 ultraplan 一下这个重构" | 输入中包含 ultraplan 关键词,彩虹高亮显示 |
| 斜杠命令 | /ultraplan 重构认证系统 | 直接调用命令 |
代码中精心处理了大量误触场景(findKeywordTriggerPositions 函数):
`ultraplan` 不触发(代码引用)单引号的处理尤其精巧:只有当前后不是字母时才算引号("let's ultraplan it's" 仍然触发,因为 ' 被识别为撇号而非引号)。
触发后,"ultraplan" 被替换为 "plan",保持语法通顺:
从输入关键词到计划落地的 8 个步骤。
用户输入包含 "ultraplan" 的文本,或直接 /ultraplan <描述>
弹出 UltraplanLaunchDialog,显示服务条款链接(code.claude.com/docs/en/claude-code-on-the-web),用户确认后继续
checkRemoteAgentEligibility() 验证用户是否有权使用云端会话(需要 OAuth 登录、订阅状态等)
teleportToRemote() 在 Claude Code on the Web 创建新会话。使用 Opus 模型(通过 tengu_ultraplan_model GrowthBook 配置),强制 Plan 模式(permissionMode: 'plan')。本地终端立即显示"Starting Claude Code on the web…"
startDetachedPoll() 每 3 秒轮询远程会话事件流。本地显示进度药丸(pill),用户可以继续使用终端做其他事
用户可以在浏览器中看到 AI 的规划过程。AI 可能会提问(phase 变为 needs_input),用户在浏览器中回复
AI 完成规划后调用 ExitPlanMode 工具。用户在浏览器中看到计划,可以编辑、批准或拒绝。拒绝后 AI 继续迭代
批准后两个选项:① "在云端执行"——远程会话继续编码,结果作为 PR 落地 ② "传回本地"——计划文本传回终端,弹出 UltraplanChoiceDialog 让用户选择如何执行
ExitPlanModeScanner 是一个纯状态机,无 I/O、无定时器。
| 阶段 | 含义 | 转换条件 |
|---|---|---|
| running | AI 正在规划 | 初始状态 / 用户在浏览器回复后 |
| needs_input | AI 提了问题,等用户回复 | 会话状态为 idle 且无新事件 |
| plan_ready | 计划已生成,等待审批 | 检测到 ExitPlanMode tool_use 但无 tool_result |
这是一个纯函数式的事件流分类器(ccrSession.ts),设计非常精巧:
| 参数 | 值 | 说明 |
|---|---|---|
| 轮询间隔 | 3 秒 | POLL_INTERVAL_MS |
| 最大超时 | 30 分钟 | ULTRAPLAN_TIMEOUT_MS |
| 最大连续失败 | 5 次 | MAX_CONSECUTIVE_FAILURES,之后抛出错误 |
| 瞬态错误重试 | 自动 | isTransientNetworkError 判断是否可重试 |
从远程会话的事件流中提取审批后的计划文本。
| 路径 | 标记 | 含义 |
|---|---|---|
| approved | ## Approved Plan:\n | 用户在浏览器中点了"批准" |
| approved (edited) | ## Approved Plan (edited by user):\n | 用户编辑后批准 |
| teleport | __ULTRAPLAN_TELEPORT_LOCAL__\n | 用户点了"传回本地" |
注意:AI 在远程会话中把计划写入文件,然后调用 ExitPlanMode({allowedPrompts})。计划文本不在 tool_use 的 input 中(那样会暴露在 threadstore),而是在 tool_result 的 content 中通过标记提取。
计划审批后,用户有两条路。
用户在浏览器中选择"在 CCR 中执行"。远程会话退出 Plan 模式,开始编码。本地终端显示通知:
本地不归档远程会话(它还在运行),任务标记为 completed。
用户点"teleport back to terminal"。浏览器发送一个特殊的拒绝(让远程保持 Plan 模式),计划文本嵌入反馈中。
本地弹出 UltraplanChoiceDialog,用户可以:
远程会话被归档(archiveRemoteSession)。
30 分钟的长轮询需要极其健壮的错误处理。
| 场景 | 处理方式 |
|---|---|
| 用户停止(按 x) | shouldStop() 返回 true → 抛出 'stopped' → RemoteAgentTask.kill() 归档远程会话 → 清除 URL |
| 远程会话崩溃 | 检测到 result(非 success) → 抛出 'terminated' |
| 网络瞬态错误 | 最多重试 5 次,每次间隔 3 秒 |
| 30 分钟超时 | 区分"从未看到 ExitPlanMode"(timeout_no_plan)和"看到了但未审批"(timeout_pending) |
| 计划标记缺失 | 抛出 'extract_marker_missing',附带内容预览前 200 字符 |
| teleport 后本地出错 | 归档远程会话(避免 30 分钟孤儿)+ 清除 URL |
| 重复启动 | 检查 ultraplanSessionUrl 和 ultraplanLaunching,已有活跃会话时返回提示 |
| 资格不足 | checkRemoteAgentEligibility 失败 → 显示具体原因 |
从输入到完成的视觉体验。
| 时刻 | 用户看到什么 |
|---|---|
| 输入关键词时 | "ultraplan" 文字彩虹高亮 + 底部通知"will launch ultraplan" |
| 提交后立即 | 终端显示 "◇ ultraplan\nStarting Claude Code on the web…" |
| 会话创建后 | "◇ ultraplan · Monitor progress in Claude Code on the web [URL]\nYou can continue working — when the ◇ fills, press ↓ to view results" |
| 运行中 | 底部进度药丸显示 running / needs_input / plan_ready |
| 计划就绪 | 药丸变为 plan_ready,按 ↓ 查看详情 |
| 审批后(云端) | 通知"Ultraplan approved — executing in Claude Code on the web" |
| 审批后(本地) | 弹出 UltraplanChoiceDialog,显示计划内容,选择执行方式 |
| 失败时 | 通知"Ultraplan failed: [原因]\n\nSession: [URL]" |
| 停止时 | 通知"Ultraplan stopped.\n\nSession: [URL]" |
ULTRAPLAN 的核心价值和设计智慧。
ULTRAPLAN 把"规划"和"执行"解耦——用最强的模型在云端深度思考,本地终端不阻塞,用户在浏览器中参与决策,最终选择在哪里执行。
| 决策 | 选择 | 理由 |
|---|---|---|
| 触发方式 | 关键词 + 斜杠命令 | 关键词降低使用门槛(不需要记命令),斜杠命令给高级用户 |
| 模型选择 | Opus(通过 GrowthBook 可配置) | 规划需要最强推理能力,成本由云端承担 |
| 执行模式 | Plan Mode | 远程会话只能规划不能执行,直到用户审批 |
| 轮询而非 WebSocket | 3 秒 HTTP 轮询 | 简单可靠,30 分钟内约 600 次调用,可容忍 |
| 双执行路径 | 云端 / 本地 | 用户可以选择信任云端自动执行,或拿回本地手动控制 |
| 关键词替换 | "ultraplan" → "plan" | 转发给远程时保持语法通顺,避免远程自触发 |
| 预启动对话框 | 显示服务条款 | 云端执行涉及数据传输,需要用户明确同意 |