hongshaorou/claude-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
claude-code/docs/ultraplan-implementation.md

445 lines
19 KiB
Markdown
Raw Normal View History

docs: 添加一大堆 feature 的描述
2026-04-02 22:52:32 +08:00
# ULTRAPLAN（增强规划）实现分析
> 生成日期：2026-04-02
> Feature Flag：`FEATURE_ULTRAPLAN=1`
> 引用数：10（跨 8 个文件）
---
## 一、功能概述
ULTRAPLAN 是一个**远程增强规划**功能，将用户的规划请求发送到 Claude Code on the Web（CCR，云端容器）执行。使用 Opus 模型在云端生成高级计划，用户可以在浏览器中编辑和审批，然后选择在云端继续执行或将计划"传送"回本地终端执行。
**核心卖点**：
- 终端不被阻塞 — 远程在云端规划，本地可继续工作
- 使用最强大的模型（Opus）
- 用户可在浏览器中实时查看和编辑计划
- 支持多轮迭代（云端可追问，用户在浏览器回复）
---
## 二、架构总览
```
用户输入 "ultraplan xxx"
│
▼
┌─────────────────────────────────┐
│ 关键字检测层 (keyword.ts) │ 识别 "ultraplan" 关键字
│ + 输入处理层 (processUserInput) │ 重写为 /ultraplan 命令
└───────────┬─────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 命令处理层 (ultraplan.tsx) │ launchUltraplan()
│ - 前置校验（资格、防重入） │ → launchDetached()
│ - 构建提示词 │ buildUltraplanPrompt()
└───────────┬─────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 远程会话层 │ teleportToRemote()
│ - 创建 CCR 云端会话 │ permissionMode: 'plan'
│ - 设置 plan 权限模式 │ model: Opus
└───────────┬─────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 轮询层 (ccrSession.ts) │ pollForApprovedExitPlanMode()
│ - ExitPlanModeScanner │ 每 3 秒轮询事件流
│ - 状态机: running → needs_input │ 超时: 30 分钟
│ → plan_ready │
└───────────┬─────────────────────┘
│
┌─────┴─────┐
▼ ▼
approved teleport
(云端执行) (传送回本地)
│ │
│ ▼
│ UltraplanChoiceDialog
│ 用户选择执行方式
▼ ▼
完成通知 本地执行计划
```
---
## 三、模块详解
### 3.1 关键字检测 — `src/utils/ultraplan/keyword.ts`
负责检测用户输入中的 "ultraplan" 关键字。检测逻辑相当精细，避免误触发：
**触发条件**：输入中包含独立的 `ultraplan` 单词（大小写不敏感）。
**不触发的场景**：
- 在引号/括号内：`` `ultraplan` ``、`"ultraplan"`、`[ultraplan]`、`{ultraplan}`
- 路径/标识符上下文：`src/ultraplan/foo.ts`、`ultraplan.tsx`、`--ultraplan-mode`
- 问句：`ultraplan?`
- 斜杠命令内：`/rename ultraplan foo`
- 已有 ultraplan 会话运行中或正在启动时
**关键字替换**：触发后将 `ultraplan` 替换为 `plan`，保持语法通顺（如 "please ultraplan this" → "please plan this"）。
```typescript
// 核心导出函数
findUltraplanTriggerPositions(text) // 返回触发位置数组
hasUltraplanKeyword(text) // 布尔判断
replaceUltraplanKeyword(text) // 替换第一个触发词为 "plan"
```
### 3.2 命令注册 — `src/commands.ts`
```typescript
const ultraplan = feature('ULTRAPLAN')
? require('./commands/ultraplan.js').default
: null
```
命令仅在 `FEATURE_ULTRAPLAN=1` 时加载。命令定义：
```typescript
{
type: 'local-jsx',
name: 'ultraplan',
description: '~10–30 min · Claude Code on the web drafts an advanced plan...',
argumentHint: '<prompt>',
isEnabled: () => process.env.USER_TYPE === 'ant', // 仅 ant 用户可用
}
```
> 注意：`isEnabled` 检查 `USER_TYPE === 'ant'`（Anthropic 内部用户），这是命令级限制。关键字触发路径没有此限制，只要 feature flag 开启即可。
### 3.3 核心命令实现 — `src/commands/ultraplan.tsx`
#### 3.3.1 入口函数 `call()`
处理 `/ultraplan <prompt>` 斜杠命令：
1. **无参数调用**：显示使用帮助文本
2. **已有活跃会话**：返回 "already polling" 提示
3. **正常调用**：设置 `ultraplanLaunchPending` 状态，触发 `UltraplanLaunchDialog` 对话框
#### 3.3.2 `launchUltraplan()`
公共启动入口，被三个路径共享：
- 斜杠命令 (`/ultraplan`)
- 关键字触发 (`processUserInput.ts`)
- Plan 审批对话框的 "Ultraplan" 按钮 (`ExitPlanModePermissionRequest`)
关键逻辑：
1. 防重入检查（`ultraplanSessionUrl` / `ultraplanLaunching`）
2. 同步设置 `ultraplanLaunching = true` 防止竞态
3. 异步调用 `launchDetached()`
4. 立即返回启动消息（不等远程会话创建）
#### 3.3.3 `launchDetached()`
异步后台流程：
1. **获取模型**：从 GrowthBook 读取 `tengu_ultraplan_model`，默认 `opus46` 的 firstParty ID
2. **资格检查**：`checkRemoteAgentEligibility()` — 验证用户是否有权限使用远程 agent
3. **构建提示词**：`buildUltraplanPrompt(blurb, seedPlan)`
- 如有 `seedPlan`（来自 plan 审批对话框），作为草稿前缀
- 加载 `prompt.txt` 中的指令模板
- 附加用户 blurb
4. **创建远程会话**：`teleportToRemote()`
- `permissionMode: 'plan'` — 远程以 plan 模式运行
- `ultraplan: true` — 标记为 ultraplan 会话
- `useDefaultEnvironment: true` — 使用默认云端环境
5. **注册任务**：`registerRemoteAgentTask()` 创建 `RemoteAgentTask` 追踪条目
6. **启动轮询**：`startDetachedPoll()` 后台轮询审批状态
#### 3.3.4 提示词构建
```
buildUltraplanPrompt(blurb, seedPlan?)
```
- `prompt.txt`：当前为空文件（反编译丢失），原始内容应包含指导远程 agent 生成计划的系统指令
- 开发者可通过 `ULTRAPLAN_PROMPT_FILE` 环境变量覆盖提示词文件（仅 `USER_TYPE=ant` 时生效）
#### 3.3.5 `startDetachedPoll()`
后台轮询管理：
1. 调用 `pollForApprovedExitPlanMode()` 等待计划审批
2. 阶段变化时更新 `RemoteAgentTask.ultraplanPhase`（UI 展示）
3. 审批完成后的两种路径：
- **`executionTarget: 'remote'`**：用户选择在云端执行
- 标记任务完成
- 清除 `ultraplanSessionUrl`
- 发送通知：结果将以 PR 形式提交
- **`executionTarget: 'local'`**：用户选择传送回本地（teleport）
- 设置 `ultraplanPendingChoice`
- 触发 `UltraplanChoiceDialog` 对话框
4. 失败时：归档远程会话、清除状态、发送错误通知
#### 3.3.6 `stopUltraplan()`
用户主动停止：
1. `RemoteAgentTask.kill()` 归档远程会话
2. 清除所有 ultraplan 状态（`ultraplanSessionUrl`、`ultraplanPendingChoice`、`ultraplanLaunching`）
3. 发送停止通知
### 3.4 CCR 会话轮询 — `src/utils/ultraplan/ccrSession.ts`
#### 3.4.1 `ExitPlanModeScanner`
纯状态机，无 I/O。摄入 `SDKMessage[]` 事件批次，分类 `ExitPlanMode` 工具调用的结果。
**状态类型**：
```typescript
type ScanResult =
| { kind: 'approved' } // 用户批准了计划
| { kind: 'teleport' } // 用户点击"传送回本地"
| { kind: 'rejected' } // 用户拒绝（可继续迭代）
| { kind: 'pending' } // 等待用户审批中
| { kind: 'terminated' } // 远程会话意外终止
| { kind: 'unchanged' } // 无新事件，状态不变
```
**优先级**：approved > terminated > rejected > pending > unchanged
**关键设计**：
- 同一批事件可能包含审批和后续崩溃 — 不丢弃已审批的计划
- 拒绝后重新扫描（`rescanAfterRejection`），因为新事件可能包含修改后的计划
- 使用 `is_error: true` 判断拒绝，`content` 中查找标记提取计划文本
#### 3.4.2 `pollForApprovedExitPlanMode()`
轮询主循环：
- **轮询间隔**：3 秒
- **超时**：30 分钟
- **容错**：连续 5 次网络错误才放弃
- **阶段推断**：
- `hasPendingPlan`（有 ExitPlanMode 无结果）→ `plan_ready`
- `quietIdle`（空闲且无新事件）→ `needs_input`（远程在等用户输入）
- 其他 → `running`
#### 3.4.3 计划文本提取
两种提取路径：
1. **Approved**：从 `tool_result` 中查找 `## Approved Plan:\n` 或 `## Approved Plan (edited by user):\n` 标记
2. **Teleport**：从 `tool_result` 中查找 `__ULTRAPLAN_TELEPORT_SENTINEL__` 标记（浏览器端嵌入）
### 3.5 输入处理集成 — `src/utils/processUserInput/processUserInput.ts`
关键字触发路径（在斜杠命令处理之前）：
```typescript
if (feature('ULTRAPLAN') &&
mode === 'prompt' && // 非非交互模式
!isNonInteractiveSession && // 非后台会话
inputString !== null &&
!inputString.startsWith('/') && // 非斜杠命令
!ultraplanSessionUrl && // 无活跃会话
!ultraplanLaunching && // 非正在启动
hasUltraplanKeyword(inputString)) {
// 重写为 /ultraplan 命令
const rewritten = replaceUltraplanKeyword(inputString).trim()
await processSlashCommand(`/ultraplan ${rewritten}`, ...)
}
```
### 3.6 UI 层
#### 3.6.1 彩虹高亮 — `src/components/PromptInput/PromptInput.tsx`
当输入中检测到 `ultraplan` 关键字时：
- 对每个字符施加**彩虹渐变色**高亮（`getRainbowColor()`）
- 显示通知："This prompt will launch an ultraplan session in Claude Code on the web"
#### 3.6.2 预启动对话框 — `UltraplanLaunchDialog`
在 REPL 的 `focusedInputDialog === 'ultraplan-launch'` 时渲染。
用户选择：
- **确认**：调用 `launchUltraplan()`，先添加命令回显，异步启动远程会话
- **取消**：清除 `ultraplanLaunchPending` 状态
#### 3.6.3 计划选择对话框 — `UltraplanChoiceDialog`
在 `focusedInputDialog === 'ultraplan-choice'` 时渲染。
当 teleport 路径返回已审批计划时，用户可选择执行方式。
#### 3.6.4 Plan 审批按钮 — `ExitPlanModePermissionRequest`
本地 Plan Mode 的审批对话框中，如果 `feature('ULTRAPLAN')` 开启，会显示额外的 "Ultraplan" 按钮：
- 将当前本地计划作为 `seedPlan` 发送给远程
- 按钮仅在无活跃 ultraplan 会话时显示
### 3.7 应用状态 — `src/state/AppStateStore.ts`
```typescript
interface AppState {
ultraplanLaunching?: boolean // 防重入锁（5 秒窗口）
ultraplanSessionUrl?: string // 活跃远程会话 URL
ultraplanPendingChoice?: { // 已审批计划等待选择
plan: string
sessionId: string
taskId: string
}
ultraplanLaunchPending?: { // 预启动对话框
blurb: string
}
isUltraplanMode?: boolean // 远程端：CCR 侧的 ultraplan 标记
}
```
### 3.8 远程任务追踪 — `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx`
Ultraplan 使用 `RemoteAgentTask` 基础设施追踪远程会话：
```typescript
registerRemoteAgentTask({
remoteTaskType: 'ultraplan',
session: { id, title },
command: blurb,
isUltraplan: true // 特殊标记，跳过通用轮询逻辑
})
```
`extractPlanFromLog()` 从 `<ultraplan>...</ultraplan>` XML 标签中提取计划内容。
---
## 四、数据流时序
```
时间线 →
用户 本地 CLI CCR 云端
│ │ │
│ "ultraplan xxx" │ │
│──────────────────────>│ │
│ │ keyword 检测 + 重写 │
│ │ /ultraplan "plan xxx" │
│ │ │
│ [UltraplanLaunch │ │
│ Dialog] │ │
│──── confirm ─────────>│ │
│ │ launchDetached() │
│ │─────────────────────────────>│
│ │ teleportToRemote() │
│ │ (permissionMode: 'plan') │
│ │ │
│ "Starting..." │ │
│<──────────────────────│ │
│ │ │
│ (终端空闲，可继续) │ startDetachedPoll() │
│ │ ═══ 3s 轮询循环 ═══ │
│ │ │
│ │ [浏览器打开]│
│ │ [云端生成计划]
│ │ │
│ │ ← needs_input ─────────────│
│ │ (云端追问用户) │
│ │ │
│ │ [用户在浏览器回复]
│ │ │
│ │ ← plan_ready ──────────────│
│ │ (ExitPlanMode 等待审批) │
│ │ │
│ │ [用户审批/编辑]
│ │ │
│ ┌───────┤ ← approved ────────────────│
│ │ │ │
│ [远程执行] │ │ │
│ 通知完成 │ │ │
│ │ │ │
│ └── OR ─┤ ← teleport ───────────────│
│ │ │
│ [UltraplanChoice │ │
│ Dialog] │ │
│── 选择执行方式 ───────>│ │
│ │ 本地执行计划 │
```
---
## 五、关键文件清单
| 文件 | 职责 |
|------|------|
| `src/utils/ultraplan/keyword.ts` | 关键字检测、高亮位置计算、关键字替换 |
| `src/utils/ultraplan/ccrSession.ts` | CCR 会话轮询、ExitPlanMode 状态机、计划文本提取 |
| `src/utils/ultraplan/prompt.txt` | 远程指令模板（当前为空，需重建） |
| `src/commands/ultraplan.tsx` | `/ultraplan` 命令、启动/停止逻辑、提示词构建 |
| `src/utils/processUserInput/processUserInput.ts` | 关键字触发 → `/ultraplan` 命令路由 |
| `src/components/PromptInput/PromptInput.tsx` | 彩虹高亮 + 通知提示 |
| `src/screens/REPL.tsx` | 对话框渲染（UltraplanLaunchDialog / UltraplanChoiceDialog） |
| `src/components/permissions/ExitPlanModePermissionRequest/` | Plan 审批中的 "Ultraplan" 按钮 |
| `src/state/AppStateStore.ts` | ultraplan 相关状态字段定义 |
| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` | 远程任务追踪 + `<ultraplan>` 标签提取 |
| `src/constants/xml.ts` | `ULTRAPLAN_TAG = 'ultraplan'` |
---
## 六、依赖关系
### 外部依赖
| 依赖 | 用途 | 必要性 |
|------|------|--------|
| `teleportToRemote()` | 创建 CCR 云端会话 | 必须 — 核心功能 |
| `checkRemoteAgentEligibility()` | 验证用户远程 agent 使用资格 | 必须 — 前置检查 |
| `archiveRemoteSession()` | 归档/终止远程会话 | 必须 — 清理 |
| GrowthBook `tengu_ultraplan_model` | 获取使用的模型 ID | 可选 — 默认 opus46 |
| `@anthropic-ai/sdk` | SDKMessage 类型 | 必须 — 类型定义 |
| `pollRemoteSessionEvents()` | 事件流分页轮询 | 必须 — 轮询基础设施 |
### 内部依赖
- **ExitPlanModeV2Tool**：远程端调用的工具，触发 plan 审批流程
- **RemoteAgentTask**：任务追踪和状态管理基础设施
- **AppState Store**：ultraplan 状态管理
---
## 七、当前状态与补全要点
| 组件 | 状态 | 说明 |
|------|------|------|
| 关键字检测 | ✅ 完整 | `keyword.ts` 逻辑完善 |
| 命令框架 | ✅ 完整 | 注册、路由、防重入完整 |
| 启动流程 | ✅ 完整 | `launchUltraplan` / `launchDetached` 完整 |
| CCR 轮询 | ✅ 完整 | `ccrSession.ts` 状态机完整 |
| UI 高亮/通知 | ✅ 完整 | 彩虹高亮 + 提示通知完整 |
| 状态管理 | ✅ 完整 | AppState 字段完整 |
| `prompt.txt` | ❌ 空文件 | 需要重建远程指令模板 |
| `UltraplanLaunchDialog` | ⚠️ 全局声明 | 组件实现未找到（可能在内置包中） |
| `UltraplanChoiceDialog` | ⚠️ 全局声明 | 组件实现未找到（可能在内置包中） |
| `isEnabled` 限制 | ⚠️ `USER_TYPE === 'ant'` | 命令级限制，仅 Anthropic 内部用户 |
### 补全建议
1. **重建 `prompt.txt`**：这是远程 agent 的核心指令，定义如何进行多 agent 探索式规划。需要设计：
- 规划方法论（多角度分析、风险评估、分阶段执行）
- ExitPlanMode 工具的使用引导
- 输出格式要求
2. **对话框组件**：`UltraplanLaunchDialog` 和 `UltraplanChoiceDialog` 在 `global.d.ts` 中声明但实现缺失，需要新建：
- Launch Dialog：确认对话框（含 CCR 使用条款链接）
- Choice Dialog：展示已审批计划 + 执行方式选择
3. **放宽 `isEnabled`**：如果要让非 ant 用户使用斜杠命令，需移除 `USER_TYPE === 'ant'` 检查
---
## 八、与相关 Feature 的关系
| Feature | 关系 |
|---------|------|
| `ULTRATHINK` | 类似的高能力模式，但 `ULTRATHINK` 只调高 effort，不启动远程会话 |
| `FORK_SUBAGENT` | Ultraplan 不使用 fork subagent，使用的是 CCR 远程 agent |
| `COORDINATOR_MODE` | 不同范式的多 agent，Coordinator 在本地编排，Ultraplan 在云端 |
| `BRIDGE_MODE` | 底层依赖相同的 `teleportToRemote()` 基础设施 |
| `ExitPlanModeTool` | 远程端的审批机制，Ultraplan 的核心交互模型 |
Reference in New Issue Copy Permalink