企业官网建设流程全解析

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体

本篇技术指南以 Warp 仓库中 handoff-cloud-cloud-pr2 技术规格 为骨架，系统拆解 Cloud-to-cloud handoff PR 2 的完整设计：如何把一次已结束的云端 Agent 运行（cloud agent run）编排成一次 follow-up 执行，并把新产生的共享会话（shared session）交给既有的 hotswap 热切换路径。读完本文，你将掌握可复用的运行轮询流设计、SessionStartupKind状态建模、FollowupSessionReady事件链路，以及该特性如何在默认关闭的前提下安全落地。

一、背景与问题定义：什么是 Cloud-to-cloud handoff PR 2

在 Warp 的 Cloud Mode（云端模式）中，一次 ambient agent 运行（run）会经历：创建运行 → 轮询get_ambient_agent_task获取任务状态 → 直到第一个可加入（joinable）的共享会话出现 → 通过connect_to_session挂接会话。当一次运行结束后，用户往往希望在同一运行（run）上继续追加新的提示词（prompt），让云端在既有上下文中产生一次新的执行（execution），这就是 "handoff"（接力）场景；当接力发生在云端到云端之间时，即为 cloud-to-cloud handoff。

PR 2 的职责是添加编排层（orchestration layer）：把一次已存在的 cloud agent run 转变为一次 follow-up 执行，并将结果生成的全新共享会话交给 hotswap 路径。其核心边界是模型/API 行为：

未来某个 UI 只需调用一个 ambient-model 方法并传入 follow-up 提示词，客户端提交POST agent/runs/{runId}/followups，持续轮询同一个 run 直到出现新的可加入会话，忽略已结束的旧会话，最终发出FollowupSessionReady事件，让既有的 viewer manager 以 append 模式挂接新会话。

目标（Goals）

• 提供可复用的 follow-up 编排：向既有 run 提交提示词，并等待一个全新的活跃执行会话；
• 让 ambient view model 显式区分"等待初始会话"与"等待 follow-up 会话"；
• 跟踪活跃的或上一次已结束的执行会话 ID，使 follow-up 轮询能忽略旧会话带来的陈旧就绪信号；
• 在新会话就绪时发出已被支持的FollowupSessionReady事件，复用既有 hotswap 路径挂接；
• 复用既有 Cloud Mode 的 setup/loading/error 状态机制处理 follow-up 等待与失败，但不新增可见的 Continue 入口；
• 实现整体保持在FeatureFlag::HandoffCloudCloud之后，特性关闭时行为保持不变。

非目标（Non-goals）

PR 2 刻意收敛边界，以下内容明确不在本次范围内：

• 不新增 tombstone 上的 Continue 按钮、action 或文案改动；
• 不做终端输入路由（terminal input submission route）来提交 follow-up 提示词；
• 不在 tombstone 内嵌入 follow-up 提示词编辑器；
• 不做 tombstone 堆叠或原地更新（update-in-place）的产品决策；
• 不做一等的服务端 execution 数组解析（除非本分支的公开 API 响应形状已经暴露它）；
• 不开启HandoffCloudCloud的 rollout。

这一组非目标解释了 PR 2 的设计哲学：编排能力先行、产品 UI 后置，保证该 PR 在默认禁用状态下保持可合并（mergeable），把用户可见的入口（Continue 按钮、输入路由）留给后续 UX PR。

二、现状盘点：PR 1 打下的基础设施

PR 2 构建在 PR 1 的成果之上。PR 1 已经完成了以下基础工作：

1. 特性标志与编译期依赖：新增默认禁用的HandoffCloudCloud标志，并在 app/Cargo.toml 中编码了对cloud_mode_setup_v2的 Cargo feature 依赖。
2. API 请求模型与客户端方法：在 app/src/server/server_api/ai.rs 中新增：
   • RunFollowupRequest（请求体，携带message字段，位于 ai.rs）；
   • AIClient::submit_run_followup，通过post_public_api_unit(&build_run_followup_url(run_id), &request)提交；
   • URL 构造器build_run_followup_url(run_id)，其实现位于 ai.rs，即把请求路由到agent/runs/{runId}/followups端点；
   • 端点/序列化测试位于 ai_test.rs。
3. 任务访问器：AmbientAgentTask新增run_id()、conversation_id()、active_run_execution()访问器，把当前扁平化的响应字段投影为RunExecution视图（位于 app/src/ai/ambient_agents/task.rs）。SessionJoinInfo::from_task已消费该投影，其实现位于 app/src/ai/ambient_agents/spawn.rs：从active_run_execution()取出session_id字符串并解析为SessionId，优先使用服务端下发的session_link，否则用shared_session::join_link(&session_id)自行构造。
4. 会话热切换接收端：create_cloud_mode_view已把SessionReady路由到connect_to_session、把ExecutionSessionReady路由到attach_execution_session（位于 app/src/terminal/view/ambient_agent/mod.rs）；viewer manager 的 follow-up 挂接路径会替换活跃网络并以 append-mode 滚动回放加入（相关实现见 app/src/terminal/shared_session/viewer/terminal_manager.rs，事件循环侧的 append 滚动回放逻辑见 event_loop.rs）。

PR 2 需要填补的缺口

• 初始云端启动目前是一个单一的组合 helper：spawn_task创建 run → 轮询get_ambient_agent_task→ 发状态变更事件 → 在第一个会话可加入时结束（位于 app/src/ai/ambient_agents/spawn.rs）。尚不存在可复用的"轮询既有 run 直到新执行会话就绪"的 helper。
• AmbientAgentViewModel仍把启动建模为Status::WaitingForSession { progress }，无法区分初始 run 与 follow-up 执行（原状态位于 app/src/terminal/view/ambient_agent/model.rs）。
• 既有SessionStarted处理逻辑依赖"当前状态恰好在AgentRunning"来隐式推断 follow-up 就绪，这种隐式推断对模型驱动的 follow-up 流程过于脆弱。
• 既有的attach_followup_session方法只是为已知会话 ID 发出FollowupSessionReady，作为测试脚手架可用，但不会真正提交或轮询 follow-up。
• UI 存在与初始 dispatch 强绑定的副作用：DispatchedAgent事件会在TerminalView::handle_ambient_agent_event中插入初始的乐观用户查询，并驱动 ambient entry-block 的插入订阅（位于 app/src/terminal/view/ambient_agent/view_impl.rs）。PR 2 明确不应为 follow-up 复用该事件，否则会在 UX PR 落地前就混淆初始 run 与 follow-up 的行为。

三、核心设计一：可复用的运行轮询与 follow-up helper

3.1 从spawn_task中抽取轮询能力

规格要求重构spawn_task（app/src/ai/ambient_agents/spawn.rs），让"创建 run"与"监控 run 就绪"分离，同时保持公开spawn_task(request, ai_client, timeout)的行为不变：内部在spawn_agent成功后调用新的轮询 helper。

源码中的落地形态：spawn_task只负责调用ai_client.spawn_agent拿到(task_id, run_id, at_capacity)，然后转发给新抽取的monitor_spawned_task；而monitor_spawned_task先发出TaskSpawned（以及条件性的AtCapacity），再进入poll_run_until_joinable_session轮询循环。这正好满足了规格中"拥有任务创建权的调用方可以避免发出第二次 spawn 请求"的诉求——后续 follow-up 场景只需直接进入轮询，无需重新创建 run。

轮询过程的关键参数（均在 spawn.rs 中定义）：

3.2RunPollMode：区分初始运行与 follow-up

规格提议一个形如poll_run_until_joinable_session(run_id, ai_client, previous_session_id, timeout)的 helper。源码以RunPollMode枚举实现了这一语义：

enum RunPollMode { InitialRun, Followup { previous_session_id: Option<SessionId>, }, }

poll_run_until_joinable_session会反复调用get_ambient_agent_task(&run_id)（外层包裹with_bounded_retry，对 429/5xx 等瞬时 HTTP 错误做指数退避重试），在状态变化时发出StateChanged事件，并仅在任务处于InProgress且SessionJoinInfo::from_task解析出与previous_session_id不同的session_id时才返回SessionStarted。

3.3 一个重要的实现细节：陈旧终态跳过（stale-state skipping）

规格强调"终端状态不应让 follow-up 等待无限期滞留"，而源码的注释进一步揭示了一个微妙问题：服务端在submit_run_followup返回时并不会同步地把任务从先前的终态转移出去——转移发生在 dispatcher 循环拾取新入队的执行、worker 认领之后，是异步发生的。

如果轮询把第一次观察到的状态当作 follow-up 的结果，就会把先前 run 的status_message误报为失败并结束流，导致模型永久卡在Failed，尽管新 run 其实即将开始。为此，源码引入了seen_working_state门控：

• 初始 run 从全新任务开始，首次观察即反映 spawn 本身，所以seen_working_state初始为true；
• follow-up 的seen_working_state初始为false，必须先观察到至少一个 working 状态（task.state.is_working()）才允许发出事件；
• 在观察到 working 状态之前，非 working、非 cancelled 的状态会被当作"先前 run 的残留终态"跳过（skipped_stale_polls计数），直到超过MAX_STALE_POLLS_BEFORE_FAILURE才放弃；
• Cancelled是特例：它只能经由显式的用户/管理员/服务端取消到达，且服务端不会自行转移出该状态，因此始终穿透跳过逻辑。

3.4 follow-up helper 的完整契约

规格提出的submit_run_followup(prompt, run_id, previous_session_id, ai_client, timeout)在源码中的落点为 spawn.rs 的同名函数，契约如下：

1. 先构造RunFollowupRequest { message: prompt }并调用ai_client.submit_run_followup(&run_id, request)；
2. API 在受理前失败则直接返回错误、绝不进入轮询；
3. 受理成功后进入poll_run_until_joinable_session，轮询错误与初始 spawn 走同一错误通道。

此外，规格对会话元数据的容差做了明确区分：

• 初始 spawn：保留对"存在会话链接但解析不出会话 ID"的既有容忍（SessionJoinInfo::from_task内部要求解析出session_id，但对session_link的空链接做过滤回退）；
• follow-up 就绪：必须解析出会话 ID，因为 hotswap API 需要SessionId。

3.5 终端状态的错误语义

规格要求：在新会话出现之前，follow-up 等待不得无限滞留。失败类状态应发出状态变更并把任务状态消息作为错误浮出；成功的终端完成（terminal completion）却没有新会话时，应以明确的"没有可用的 follow-up 会话"错误收尾。源码中对应逻辑为：task.state.is_terminal()时，follow-up 模式区分两种错误文案——若因跳过计数耗尽则报"Cloud follow-up did not start in time"；否则优先取status_message，失败类状态回退到"Cloud agent failed"，非失败类终态回退到"Cloud follow-up finished before a new session became available"。

四、核心设计二：显式化的会话启动类型（SessionStartupKind）

4.1 状态建模：Status::WaitingForSession携带启动类型

规格提议引入小枚举SessionStartupKind { InitialRun, Followup }，并让Status::WaitingForSession携带{ progress, kind }，同时保持既有访问器（如agent_progress()、is_waiting_for_session()）行为不变。源码落点为 app/src/terminal/view/ambient_agent/model.rs：

pub enum SessionStartupKind { InitialRun, Followup, } pub enum Status { Setup, Composing, WaitingForSession { progress: AgentProgress, kind: SessionStartupKind, }, AgentRunning, Failed { progress: AgentProgress, error_message: String }, NeedsGithubAuth { progress: AgentProgress, error_message: String, auth_url: String }, Cancelled { progress: AgentProgress }, // ... }

注意is_waiting_for_session()使用matches!(self.status, Status::WaitingForSession { .. })的通配匹配，因此携带kind后访问器依然行为保持。

4.2 事件分派：SessionReadyvsExecutionSessionReady

规格要求：初始 spawn 置WaitingForSession { kind: InitialRun }；AmbientAgentEvent::SessionStarted处理逻辑改为依据kind决定发SessionReady（初始）还是FollowupSessionReady（follow-up），而不是依赖"当前状态恰好在AgentRunning"。

源码中的实际落点（model.rs）在SessionStarted处理器内按kind匹配：

• InitialRun→ 发AmbientAgentViewModelEvent::SessionReady { session_id }；
• Followup（以及兼容的AgentRunning）→ 发AmbientAgentViewModelEvent::ExecutionSessionReady { session_id }；
• 其余状态（Setup/Composing/Failed/NeedsGithubAuth/Cancelled）直接返回，不发出会话事件。

同时在收到SessionStarted后统一收尾：停止进度定时器、更新active_execution_session_id、清空last_ended_execution_session_id与pending_followup_prompt、置status = Status::AgentRunning。事件枚举的完整定义见 model.rs，其中ExecutionSessionReady的文档注释明确了它的语义："一次执行已开始为既有的 canonical ambient pane 共享会话（即前一次运行结束后新 VM 上的 follow-up 运行）"，驱动视图侧TerminalManager::attach_execution_session的会话交换。

4.3 模型新增字段与提交方法

规格要求为AmbientAgentViewModel增加 follow-up 记账字段：活跃执行的SessionId、可用的最近一次已结束执行的SessionId、当前已提交的 follow-up 提示词（该字段为 PR 3 的乐观渲染预留，PR 2 只存储、不插入可见的 follow-up 查询块）。源码字段落点为 model.rs。

新增方法AmbientAgentViewModel::submit_cloud_followup(prompt, ctx)（model.rs）的完整前置条件与流程：

1. 特性门控：要求FeatureFlag::HandoffCloudCloud已启用，否则仅记录 warn 日志并直接返回；
2. 任务存在：要求已有task_id（run ID），否则 warn 返回；
3. 捕获前一会话：previous_session_id = active_execution_session_id.or(last_ended_execution_session_id)——这是规格"若会话结束通知丢失，则回退到最后活跃执行会话 ID"的风险缓解措施的落地；
4. 置状态：status = Status::WaitingForSession { progress: AgentProgress::new(), kind: SessionStartupKind::Followup }；
5. 启动计时：start_progress_timer(ctx)；
6. 记录待处理提示词：pending_followup_prompt = Some(prompt)；
7. 发出独立事件：ctx.emit(AmbientAgentViewModelEvent::FollowupDispatched)；
8. 启动 helper 流：ctx.spawn_stream_local(stream, ...)消费submit_run_followup流，事件结果交给handle_ambient_agent_event_result。

成功路径：停止计时器、置AgentRunning、更新活跃执行会话 ID、清空待处理提示词、发ExecutionSessionReady { session_id }；失败路径复用既有的 failed/auth/quota/capacity 映射逻辑（handle_spawn_error等），使 follow-up 的 setup 错误与初始 setup 错误渲染在同一套状态上。

模型侧还提供了is_ready_for_cloud_followup_prompt()（model.rs）判定"既有 ambient task 是否可以接受 follow-up 提示词"：要求存在task_id、无活跃执行会话、无待处理提示词、且状态为AgentRunning。其注释点明：Cloud Mode 执行结束后状态保持AgentRunning而活跃会话被清空，这个"可编辑的运行后状态"正是允许 follow-up 的时刻——它构成了未来 PR 3 中 Continue 入口的启用条件。

五、核心设计三：执行结束记账与事件/视图集成

5.1 执行结束的纯记账扩展

规格要求：仅扩展 ambient session 结束路径做记账。viewer::TerminalManager::ambient_session_ended目前让 pane 保持可恢复并清空活跃网络；PR 2 在HandoffCloudCloud开关后通知 ambient view model 记录已结束会话 ID，以便模型拒绝来自该会话的重复就绪信号。

源码落点record_ambient_execution_ended(session_id, ctx)（model.rs）：若该会话恰是active_execution_session_id则清空并发出RunLifecycleChanged，然后写入last_ended_execution_session_id。

关键约束（规格明确列出，源码遵守）：该通知不得调用TerminalView::on_session_share_ended、不得插入 tombstone、不得设置SharedSessionStatus::FinishedViewer、不得取消本地会话——这些 UI 与生命周期决策全部留在 PR 3。

5.2 新事件与视图接线

• 新增模型事件FollowupDispatched（model.rs），不复用DispatchedAgent，避免再次插入初始 run 的 UI 痕迹；
• create_cloud_mode_view（app/src/terminal/view/ambient_agent/mod.rs）只需对新事件做穷尽匹配更新，因为ExecutionSessionReady已接入attach_execution_session；
• TerminalView::handle_ambient_agent_event处理FollowupDispatched时仅通知/重渲染进度 UI、若存在活跃 ambient 会话则将其标记为ConversationStatus::InProgress；不插入CloudModeInitialUserQuery、不插入第二个AmbientAgentEntryBlock、不自动打开超出既有 setup/progress 渲染的新 UI（见 app/src/terminal/view/ambient_agent/view_impl.rs）；
• 既有加载屏（view_impl.rs 的 loading 渲染区域）在 PR 2 中继续从AgentProgress派生消息；如需为 follow-up 调整文案，保持最小改动并基于SessionStartupKind区分，且规格允许将用户可见文案推迟到 PR 3。

六、测试策略：以流级测试验证编排契约

规格要求的测试重点集中在 app/src/ai/ambient_agents/spawn_tests.rs，源码中已存在覆盖以下关键路径的用例：

同时要求：保留既有spawn_task测试，确保重构后初始 spawn 行为不变；模型级测试若有轻量 harness 则补充，否则保持模型改动小、以流测试加定向编译检查验证。模型断言应覆盖submit_cloud_followup前置条件、WaitingForSession { kind: Followup }以及新会话上的ExecutionSessionReady发出。

规格给出的定向验证命令：

cargo nextest run -p warp ai::ambient_agents::spawn::tests \ server::server_api::ai::tests::build_run_followup_url_routes_to_run_followups \ server::server_api::ai::tests::serialize_run_followup_request cargo check -p warp --features handoff_cloud_cloud

若新增模型或终端视图测试，需包含对应模块过滤器。注意：不要使用cargo fmt --all或针对单个文件的cargo fmt，仅在准备 PR 更新时使用仓库的标准格式化命令。

七、发布、兼容性与风险缓解

7.1 双重门控下的安全性

• 标志关闭时：生产 UI 不会调用新的 follow-up 方法，既有初始 Cloud Mode 启动行为与今天完全一致（spawn_task公开流契约不变、初始spawn_task测试保持绿色）；
• 标志开启时：PR 2 只暴露内部/模型级 follow-up 路径，由于没有可见入口，可以安全地在产品 UX 落地前合并，单元测试仍可完整演练编排路径；
• 运行时代码在HandoffCloudCloud启用时可假定CloudModeSetupV2可用，因为该 Cargo feature 依赖已在 PR 1 编码进 app/Cargo.toml。

7.2 风险与缓解对照

7.3 并行化路径

该 PR 体量较小，可顺序实现；如需并行可拆成两条独立轨道：

• 轨道 A：用 mockedAIClient重构并测试 spawn.rs 的 follow-up 轮询；
• 轨道 B：接线AmbientAgentViewModel的状态/事件与 terminal-manager 的记账。

两条轨道在submit_cloud_followup汇合——它消费 follow-up helper 并发出ExecutionSessionReady。

八、完成定义（Definition of Done）

对照规格，PR 2 的完成标准如下，这也是评审者逐项验收的清单：

1. 抽取可复用轮询后，spawn_task对初始 run 的行为与之前完全一致；
2. follow-up helper 提交提示词、轮询稳定 run、忽略陈旧会话 ID、返回全新可加入会话；
3. AmbientAgentViewModel::submit_cloud_followup存在于HandoffCloudCloud开关之后，并驱动WaitingForSession { kind: Followup }走完成功与错误状态；
4. 新会话发出ExecutionSessionReady，并继续通过既有 hotswap 路径挂接；
5. 本 PR 不新增 tombstone Continue UI 或终端输入 follow-up 路由；
6. 定向测试与cargo check -p warp --features handoff_cloud_cloud全部通过。

九、从规格到代码：如何继续深入

若要进一步研究本机制的实现细节，建议按以下路径阅读仓库：

• 编排流核心：app/src/ai/ambient_agents/spawn.rs（spawn_task/monitor_spawned_task/submit_run_followup/poll_run_until_joinable_session/SessionJoinInfo）及其测试 spawn_tests.rs；
• 任务与执行投影：app/src/ai/ambient_agents/task.rs（AmbientAgentTask、active_run_execution、RunExecution、AmbientAgentLiveSessionState）；
• API 客户端：app/src/server/server_api/ai.rs（RunFollowupRequest、submit_run_followup、build_run_followup_url）与 ai_test.rs；
• 视图模型状态机：app/src/terminal/view/ambient_agent/model.rs（SessionStartupKind、Status、submit_cloud_followup、record_ambient_execution_ended、事件枚举）；
• 视图与热切换接线：app/src/terminal/view/ambient_agent/mod.rs、view_impl.rs、app/src/terminal/shared_session/viewer/terminal_manager.rs。

整体来看，PR 2 通过"可复用的轮询流 + 显式的启动类型枚举 + 纯记账的会话结束通知 + 独立的分派事件"四层设计，把 cloud-to-cloud handoff 的编排骨架与既有 hotswap 机制无缝衔接，同时以特性标志与严格非目标保住合并安全——这是一份典型的"能力先行、UI 后置"的分阶段落地范本，也为后续 PR 3 的 tombstone Continue 交互预留了清晰的挂载点（is_ready_for_cloud_followup_prompt、pending_followup_prompt与SessionStartupKind::Followup）。

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体