Product Analysis · Claude Code 解读系列

云端超级规划

输入 "ultraplan" 关键词,Claude Code 会在云端启动一个使用最强模型的远程会话,花 10-30 分钟制定详细计划。你在浏览器中审批,然后选择在云端执行或传回本地。

ULTRAPLANOpus 模型30min 超时Plan Mode
01

这是什么功能

把最复杂的规划任务外包给云端最强模型。

一句话版本

当你面对一个复杂任务不知道从哪下手时,输入 "ultraplan 重构整个认证系统",Claude Code 会在云端(Claude Code on the Web)启动一个使用 Opus 模型的远程会话,在 Plan 模式下花 10-30 分钟制定一个详细的执行计划。你可以在浏览器中和 AI 讨论、修改计划,审批后选择在云端执行或传回本地终端执行。整个过程中你的本地终端不会被阻塞。

Opus
默认使用最强模型
30min
最大超时时间
3s
轮询间隔
02

用生活比喻理解

把 ULTRAPLAN 想象成请一个高级顾问。

想象这样一个场景

你是一个项目经理,手头有个复杂的系统重构任务。你可以自己慢慢想,也可以:

  • 请一个高级顾问(Opus 模型)到一间独立的会议室(云端 CCR 会话)
  • 给他一个简报(你的 prompt + 项目上下文)
  • 他在会议室里花 10-30 分钟研究、规划
  • 期间你可以随时走进去看看进度、提意见(浏览器交互)
  • 他做完后拿出一份详细计划书让你审批
  • 你可以说"就在这间会议室执行吧"(云端执行)或"把计划书带回我办公室,我自己来"(传回本地)
  • 整个过程中你的办公桌(本地终端)是空闲的,可以做别的事
03

关键词触发的精巧设计

keyword.ts 中 120 行代码只为做好一件事:准确识别用户意图。

两种触发方式

方式示例说明
关键词"帮我 ultraplan 一下这个重构"输入中包含 ultraplan 关键词,彩虹高亮显示
斜杠命令/ultraplan 重构认证系统直接调用命令

关键词检测会跳过的情况

代码中精心处理了大量误触场景(findKeywordTriggerPositions 函数):

  • 引号/反引号内——`ultraplan` 不触发(代码引用)
  • 括号内——(ultraplan) [ultraplan] {ultraplan} 不触发
  • 文件路径——src/ultraplan/foo.ts 不触发(前后有 / 或 \)
  • 文件扩展名——ultraplan.tsx 不触发(后跟 . + 字母)
  • 连字符——--ultraplan-mode 不触发
  • 问号结尾——"ultraplan 是什么?" 不触发(问问题不应该启动)
  • 斜杠命令中——/rename ultraplan foo 不触发(这是 /rename 命令)
  • 粘贴内容中——使用 preExpansionInput 检测,粘贴的文本中的关键词不触发

单引号的处理尤其精巧:只有当前后不是字母时才算引号("let's ultraplan it's" 仍然触发,因为 ' 被识别为撇号而非引号)。

关键词替换

触发后,"ultraplan" 被替换为 "plan",保持语法通顺:

"please ultraplan this refactor""please plan this refactor" → 保留用户原始大小写的 "plan" 后缀
04

完整流程

从输入关键词到计划落地的 8 个步骤。

1. 触发

用户输入包含 "ultraplan" 的文本,或直接 /ultraplan <描述>

2. 预启动对话框

弹出 UltraplanLaunchDialog,显示服务条款链接(code.claude.com/docs/en/claude-code-on-the-web),用户确认后继续

3. 资格检查

checkRemoteAgentEligibility() 验证用户是否有权使用云端会话(需要 OAuth 登录、订阅状态等)

4. 远程会话创建

teleportToRemote() 在 Claude Code on the Web 创建新会话。使用 Opus 模型(通过 tengu_ultraplan_model GrowthBook 配置),强制 Plan 模式(permissionMode: 'plan')。本地终端立即显示"Starting Claude Code on the web…"

5. 后台轮询

startDetachedPoll() 每 3 秒轮询远程会话事件流。本地显示进度药丸(pill),用户可以继续使用终端做其他事

6. 浏览器交互

用户可以在浏览器中看到 AI 的规划过程。AI 可能会提问(phase 变为 needs_input),用户在浏览器中回复

7. 计划审批

AI 完成规划后调用 ExitPlanMode 工具。用户在浏览器中看到计划,可以编辑、批准或拒绝。拒绝后 AI 继续迭代

8. 执行选择

批准后两个选项:① "在云端执行"——远程会话继续编码,结果作为 PR 落地 ② "传回本地"——计划文本传回终端,弹出 UltraplanChoiceDialog 让用户选择如何执行

05

状态机与轮询

ExitPlanModeScanner 是一个纯状态机,无 I/O、无定时器。

三阶段状态机

阶段含义转换条件
runningAI 正在规划初始状态 / 用户在浏览器回复后
needs_inputAI 提了问题,等用户回复会话状态为 idle 且无新事件
plan_ready计划已生成,等待审批检测到 ExitPlanMode tool_use 但无 tool_result

ExitPlanModeScanner 的设计

这是一个纯函数式的事件流分类器(ccrSession.ts),设计非常精巧:

  • 无 I/O——只接收 SDKMessage[] 批次,返回 ScanResult。可以用合成事件做单元测试
  • 优先级——approved > terminated > rejected > pending > unchanged
  • 批次安全——一次 ingest 可能跨越数秒的事件(最多 50 页),可能同时包含 approved 和 terminated
  • 拒绝追踪——用户可以多次拒绝计划,Scanner 用 rejectedIds Set 跳过已拒绝的
  • Teleport 检测——用户点"传回本地"时,浏览器发送一个特殊的拒绝(is_error=true),但内容中包含 __ULTRAPLAN_TELEPORT_LOCAL__ 标记 + 计划文本

轮询参数

参数说明
轮询间隔3 秒POLL_INTERVAL_MS
最大超时30 分钟ULTRAPLAN_TIMEOUT_MS
最大连续失败5 次MAX_CONSECUTIVE_FAILURES,之后抛出错误
瞬态错误重试自动isTransientNetworkError 判断是否可重试
06

计划提取

从远程会话的事件流中提取审批后的计划文本。

两种提取路径

路径标记含义
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 中通过标记提取。

07

执行选择

计划审批后,用户有两条路。

云端执行

用户在浏览器中选择"在 CCR 中执行"。远程会话退出 Plan 模式,开始编码。本地终端显示通知:

Ultraplan approved — executing in Claude Code on the web. Follow along at: [URL] Results will land as a pull request when the remote session finishes. There is nothing to do here.

本地不归档远程会话(它还在运行),任务标记为 completed。

传回本地

用户点"teleport back to terminal"。浏览器发送一个特殊的拒绝(让远程保持 Plan 模式),计划文本嵌入反馈中。

本地弹出 UltraplanChoiceDialog,用户可以:

  • 在本地终端执行这个计划
  • 开一个新会话执行

远程会话被归档(archiveRemoteSession)。

08

错误处理与容错

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 失败 → 显示具体原因
09

用户界面

从输入到完成的视觉体验。

交互时间线

时刻用户看到什么
输入关键词时"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]"
10

产品策略总结

ULTRAPLAN 的核心价值和设计智慧。

一句话总结

ULTRAPLAN 把"规划"和"执行"解耦——用最强的模型在云端深度思考,本地终端不阻塞,用户在浏览器中参与决策,最终选择在哪里执行。

关键设计决策

决策选择理由
触发方式关键词 + 斜杠命令关键词降低使用门槛(不需要记命令),斜杠命令给高级用户
模型选择Opus(通过 GrowthBook 可配置)规划需要最强推理能力,成本由云端承担
执行模式Plan Mode远程会话只能规划不能执行,直到用户审批
轮询而非 WebSocket3 秒 HTTP 轮询简单可靠,30 分钟内约 600 次调用,可容忍
双执行路径云端 / 本地用户可以选择信任云端自动执行,或拿回本地手动控制
关键词替换"ultraplan" → "plan"转发给远程时保持语法通顺,避免远程自触发
预启动对话框显示服务条款云端执行涉及数据传输,需要用户明确同意

与其他功能的关系

  • KAIROS——ULTRAPLAN 可以在 KAIROS 模式中使用,AI 自主决定何时需要深度规划
  • Plan Mode——ULTRAPLAN 强制远程会话进入 Plan Mode,复用了 ExitPlanMode 工具
  • Remote Agent——复用了 RemoteAgentTask 基础设施(任务注册、进度药丸、kill 机制)
  • Bridge——如果本地有活跃的 Remote Control 桥接,启动前会断开(避免冲突)