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

导读

本文解析 Warp 终端中"编排卡片（Orchestration Card）内联创建 API Key"功能（对应 specs 中的 QUALITY-702）的完整设计与实现：当用户在RunAgents确认卡片或计划卡片（plan card）的编排配置块中，为 Claude Code、Codex 等非 Oz 环境下的子 Agent 选择认证密钥时，如果当前 harness 尚未配置任何托管密钥，用户可以直接在对话内打开工作区级模态框创建新密钥，而无需离开对话、跳转云模式 FTUX。读完本文，你将掌握AuthSecretSelection状态枚举的设计动机、picker 菜单内容与标签推导规则、Accept 门控与 tooltip 联动、一次性自动打开守卫（auto-open one-shot guard）的状态机，以及 FTUX 视图如何从云模式解耦并复用于工作区模态框。

1. 背景与问题

编排卡片（orchestration card）用于在 Warp 中启动额外的子 Agent（child agents）。当用户在非 Oz harness（如 Claude Code、Codex）下编排时，卡片会展示一个"API key"选择器（picker）。在此之前，该 picker 隐含一个前提：当前 harness 下至少已存在一个托管密钥。

当不存在任何托管密钥时，下拉菜单实际上是空的，卡片内没有任何路径可以创建密钥。用户只能：

1. 离开当前对话；
2. 找到云模式 FTUX（first-time user experience，首次使用引导）界面；
3. 创建密钥；
4. 回到对话并重新触发卡片。

更糟糕的是，在这种空密钥状态下，Accept 按钮仍会静默放行，将"继承自 worker 环境的凭据"直接派发出去——这通常不是用户想要的，且往往在下游执行中失败。这使得用户在新 harness 下的第一次编排尝试变成了一条死路。

2. 方案总览

本次变更（详见产品文档 specs/QUALITY-702/PRODUCT.md 与技术文档 specs/QUALITY-702/TECH.md）从三个层面解决问题：

• 扩展既有编排卡片的 auth-secret picker：当用户没有当前 harness 的托管密钥时，可直接在对话内创建一个，无需离开。
• 解耦云模式创建密钥视图：将 create-key 视图与其对云模式状态（AmbientAgentViewModel）的紧耦合剥离，重新托管到工作区级（workspace-level）的阻塞式模态框中。
• 重塑卡片选择状态：把卡片上Option<String>+ 兄弟布尔值（sibling bool）的双字段编码，收敛为三态（实现中实际为四态）枚举，使 picker 标签、Accept 门控、持久化三者行为一致地匹配产品规格。

两张编排卡片表面——RunAgents确认卡片和计划卡片的行内编排配置块——都获得了新的 picker 条目和新的动作变体（create_new_auth_secret_requested），该请求会被冒泡到工作区，由工作区打开模态框。

3. 核心状态建模：AuthSecretSelection枚举

3.1 旧双字段编码的问题

在引入枚举之前，OrchestrationEditState通过以下两个字段表达密钥选择：

• auth_secret_name: Option<String>
• auth_secret_explicit_inherit: bool

这套编码存在几个微妙的问题（TECH.md 第 3 节明确指出）：

• None + false与None + true含义不同，但都表现为"没有名字"；
• 线格式（on-wire proto）只携带名字，无法表达"显式继承"这个意图；
• picker 标签、Accept 门控、持久化逻辑各自都要对两个字段做特判，极易出现三处判定不一致。

3.2 新枚举：实际实现为四态

技术文档中最初设计为三态，而当前仓库源码 app/src/ai/orchestration/config_state.rs 中的实际实现在此基础上增加了CreatingNew变体，用于区分"尚未选择"与"正在创建（模态框已打开）"：

/// The user's current selection in the auth secret picker. #[derive(Debug, Clone, PartialEq, Eq)] pub enum AuthSecretSelection { /// No choice yet; re-seeded from persisted settings. Blocks Accept. Unset, /// User explicitly chose to inherit credentials from the worker env. Inherit, /// User picked a managed secret by name. Named(String), /// Creating a key (modal open). Blocks Accept and, unlike `Unset`, is /// not re-seeded from persisted settings. CreatingNew, }

各变体语义如下：

文档与实现的差异说明：TECH.md 第 3 节描述的是三态设计（Unset/Inherit/Named）；仓库源码在落地时补充了CreatingNew变体。它与Unset的关键区别在于：Unset每次渲染都会被持久化设置重新播种（re-seed），而CreatingNew不会被重新播种——这样当用户正在创建密钥时，后台刷新不会把一个陈旧的选中状态悄悄恢复回来（config_state.rs）。

3.3 线格式映射与按名取数

• AuthSecretSelection::from_optional_name(Option<String>)将线格式载荷映射进枚举：Some(name)且非空白 →Named(name)；None→Unset。由于线上格式与持久化设置只携带名字，"缺席"永远表示"尚未选择"（config_state.rs）。
• OrchestrationEditState::auth_secret_name()返回Named载荷（对Inherit/Unset/CreatingNew返回None），这样只关心线上字段的派发代码无需匹配整个枚举。同时，该函数会依据当前模式/harness 是否支持托管密钥做可见性门控，防止用户在切换回 Local 或切换到无认证 harness 后，残留的Named(_)泄漏进线上载荷（config_state.rs）。

3.4 持久化边界

只有Named(_)会通过CloudAgentSettings.last_selected_auth_secret持久化（按harness.config_name()键控）。Inherit与Unset属于每个会话、每个 harness 的 UI 状态，不落盘。选中托管密钥会写入该键；选择 Inherit 会清除该键；通过"+ New API key…"切到Unset/CreatingNew同样会清除，避免取消模态框后残留陈旧名字。

4. Picker 内容与触发标签推导

4.1 菜单内容与顺序

populate_auth_secret_picker_for_harness（定义于 app/src/ai/blocklist/inline_action/orchestration_controls.rs）会在 harness 或密钥列表变化时重建下拉菜单条目，顺序如下：

1. "Inherit key from environment"—— 恒常存在；点击时派发auth_secret_changed(None)（空 row id 即为 Inherit 条目，见api_key_snapshot的行映射逻辑）。
2. 已加载的托管密钥—— 按服务器返回顺序排列；若处于 Loading/Failed 状态，则渲染单个禁用的占位条目（OptionSourceStatus::Loading→ "Loading…"，OptionSourceStatus::Failed→ 错误消息文本）。
3. 分隔线 + "+ New API key…"—— 仅当auth_secret_types_for_harness(...)非空（即该 harness 支持至少一种托管密钥类型）时出现；点击派发create_new_auth_secret_requested()动作。

此外，该函数会通过HarnessAvailabilityModel::ensure_auth_secrets_fetched触发一次惰性抓取（lazy fetch），使后续帧中"Loading…"被真实条目替换。

let name = (!row.id.is_empty()).then_some(row.id); MenuItem::Item(MenuItemFields::new(&row.label).with_on_select_action( DropdownAction::select_action_and_close(A::auth_secret_changed(name)), )) // ... if supports_create_new { items.push(MenuItem::Separator); items.push(MenuItem::Item( MenuItemFields::new(AUTH_SECRET_CREATE_NEW_LABEL).with_on_select_action( DropdownAction::select_action_and_close(A::create_new_auth_secret_requested()), ), )); }

4.2 触发标签推导

picker 的触发标签（闭合态下拉框顶部显示的文本）由auth_secret_trigger_label直接从AuthSecretSelection推导（orchestration_controls.rs）：

fn auth_secret_trigger_label(selection: &AuthSecretSelection, supports_create_new: bool) -> String { match selection { AuthSecretSelection::Named(name) => name.clone(), AuthSecretSelection::Inherit => AUTH_SECRET_INHERIT_LABEL.to_string(), AuthSecretSelection::CreatingNew => AUTH_SECRET_CREATE_NEW_LABEL.to_string(), AuthSecretSelection::Unset if supports_create_new => { AUTH_SECRET_CREATE_NEW_LABEL.to_string() } AuthSecretSelection::Unset => AUTH_SECRET_INHERIT_LABEL.to_string(), } }

• Named(name)→ 密钥名；
• Inherit→ "Inherit key from environment"；
• Unset且 harness 支持创建 → "+ New API key…"；
• Unset且不支持创建 → "Inherit key from environment"；
• CreatingNew→ "+ New API key…"。

标签始终使用下拉框的默认文本颜色，不做置灰占位处理。TECH.md 记录了一个值得注意的踩坑：早期迭代曾尝试覆盖触发颜色以弱化占位符，但该覆盖路径会在下拉框自身派发的动作执行过程中再次进入下拉框视图，触发 warpui 的 "Circular view update"（循环视图更新）守卫，因此该覆写被移除（TECH.md 第 4 节）。

5. 动作 trait 与 handler 接线

5.1 新增 trait 方法

OrchestrationControlAction（由RunAgentsCardViewAction与OrchestrationConfigBlockAction共同实现）新增一个工厂方法（orchestration_controls.rs）：

/// User picked the "New API key…" item; opens the workspace create modal. fn create_new_auth_secret_requested() -> Self;

两个实现者都添加了CreateNewAuthSecretRequested变体，处理逻辑完全一致：

1. 调用oc::apply_create_new_auth_secret_requested(...)，将选择重置为CreatingNew并清除持久化的名字——这样取消模态框不会悄悄残留一个陈旧的已选名称；
2. 解析当前活跃 harness；
3. 派发WorkspaceAction::OpenCreateAuthSecretModal { harness }；
4. 卡片刷新 Accept 门控并通知重绘。

5.2 避免循环更新的设计约束

apply_auth_secret_change与apply_create_new_auth_secret_requested刻意不会重新进入 picker 视图（内部没有populate_*或sync_*调用）。因为这些 helper 是从下拉框自身派发的动作内部被调用的，若再次进入下拉框视图，就会触发上文提到的循环更新守卫。下拉框会在菜单点击时自行更新其显示标签；编排器的职责只是记录状态并持久化。

5.3 新密钥被采纳

apply_created_auth_secret_if_matches（orchestration_controls.rs）在HarnessAvailabilityEvent::AuthSecretCreated事件到达时，检查创建密钥的 harness 是否与卡片当前 harness 一致：

• 不一致 → 返回false，不动作；
• 一致且当前选择已是同名Named→ 返回false（幂等）；
• 否则将选择置为Named(created_name)，并调用persist_auth_secret_selection写盘，返回true。

这样，新创建的密钥会被卡片立即采纳为当前选中项，无需等待手动重新填充。

6. 工作区级模态框

6.1 动作与宿主

WorkspaceAction::OpenCreateAuthSecretModal { harness }（定义于 app/src/workspace/action.rs）只由两个卡片动作 handler 派发。工作区视图（app/src/workspace/view.rs 附近）持有一个ModalViewState<Modal<AuthSecretFtuxView>>，在动作到达时惰性构造（lazily constructed）模态框，并以请求的 harness 参数化视图。

模态框是工作区级别的，打开期间会阻塞其余 UI。它内部托管与云模式 FTUX 相同的AuthSecretFtuxView组件，用户可以在其中：

• 选择密钥类型（当 harness 支持多于一种类型时）；
• 输入密钥值与显示名称；
• 提交、取消（Skip 在此模态框模式中被隐藏——picker 中已有的 "Inherit key from environment" 条目承担了同样的角色）。

6.2 生命周期事件处理

工作区订阅视图的生命周期事件（TECH.md 第 6 节）：

两张卡片视图则订阅HarnessAvailabilityEvent::AuthSecretCreated并调用oc::apply_created_auth_secret_if_matches(...)，将新密钥采纳为卡片选中项，同时 Accept 门控立即解除。

7. 一次性自动打开守卫（Auto-Open One-Shot Guard）

为了给首次体验提供引导又不至于烦人，每张卡片持有一个has_auto_opened_create_modal: bool布尔守卫。maybe_auto_open_create_modal是唯一的检查汇聚点（chokepoint），按序执行以下判定（TECH.md 第 7 节）：

1. 守卫已置位 → 直接返回；
2. 卡片不在交互式确认状态（已拒绝、已自动启动、正在 spawning、从历史恢复、动作已结束或正在异步执行）→ 返回；
3. 活跃 harness 没有 auth-secret picker（例如 Oz）→ 返回；
4. auth_secret_selection不是Unset→ 返回；
5. harness 的密钥列表不是Loaded(secrets)且secrets.is_empty()→ 返回。NotFetched、Loading、Failed一律视为"尚不可判定"——HarnessAvailabilityEvent::AuthSecretsLoaded订阅会在密钥真正到达后重新触发检查；
6. 置位守卫并派发WorkspaceAction::OpenCreateAuthSecretModal { harness }。

守卫的复位时机

• 构造时置为false；
• update_request中，当 harness、模型或执行模式经流式（streaming）变化时；
• try_auto_launch_on_stream_complete中（流完成快照是权威的最终状态，需要重新评估）；
• ExecutionModeToggled与HarnessChanged动作 handler 中。

maybe_auto_open_create_modal从上述相同路径以及AuthSecretsLoaded/AuthSecretsFetchFailed订阅 handler 中被调用。切换 harness 或切换 Local/Cloud 会复位一次性守卫，让新 harness / 新模式获得自己的一次自动弹出机会；而取消/跳过模态框不会在下次渲染或通知周期中再次弹出。

8. Accept 门控与 Tooltip

oc::accept_disabled_reason_with_auth(&state.orch, ctx)扩展了既有的OrchestrationEditState::accept_disabled_reason：当auth_secret_selection为Unset且 harness 暴露了 picker 时，返回人类可读的禁用原因（例如 "Pick an API key or choose to inherit from the environment before accepting."）。

两张卡片视图都通过一个小的refresh_accept_button_state方法调用该 helper，并据此设置 Accept 按钮的disabled与tooltip：

• 确认卡片：Accept 是一个CompactibleSplitActionButton，直接设置禁用与提示；
• 计划卡片：使用同一个门控，渲染行内校验错误而不是禁用按钮。

refresh_accept_button_state在每个动作 handler 与每个触碰state.orch的模型订阅 handler 中被调用，包括AuthSecretCreated、AuthSecretsLoaded、AuthSecretsFetchFailed分支。set_disabled/set_tooltip在值未变化时是廉价 no-op。

CompactibleSplitActionButton::set_disabled/set_tooltip会同时委托到主按钮与菜单按钮，使整个拆分按钮呈现为单一门控的交互控件。这两个能力的底座由 app/src/view_components/compactible_action_button.rs 的set_disabled/set_tooltip提供——它让既有的单状态按钮也能从父级门控重新推导自身状态。

9. FTUX 视图解耦细节

9.1 解耦前的问题

此前云模式 FTUX 视图持有Rc<dyn AmbientAgentViewModel>，在render/ 事件 handler 内部从模型读取选中 harness；提交时的副作用也直接针对模型执行（set_harness_auth_secret_name、mark_harness_auth_ftux_completed、last_selected_auth_secret写入，以及云模式特有的set_harness Oz后置动作）。这使得该视图无法脱离云模式复用。

9.2 解耦后的形态

现在 app/src/terminal/view/ambient_agent/auth_secret_ftux_view.rs 中：

• 构造时直接接收harness: Harness，而非视图模型句柄；提供set_harness(harness, ctx)setter，由父级在云模式 harness 选择器变化时调用（切换 harness 会清空进行中的创建状态并同步内嵌下拉框，见 auth_secret_ftux_view.rs）；
• 副作用不再在视图内执行，改为发出生命周期事件（auth_secret_ftux_view.rs）：

#[derive(Debug, Clone)] pub enum AuthSecretFtuxViewEvent { /// User picked an existing secret from the in-view dropdown. SecretSelected { harness: Harness, name: String }, /// User created a new secret via the form. Created { harness: Harness, name: String }, /// User dismissed the form via Cancel. Cancelled, /// User skipped via the in-dropdown "Skip" item. Skipped { harness: Harness }, /// `create_auth_secret` failed. The view also shows a toast. Failed { error: String }, }

• 新增with_skip_hidden(bool)开关，供工作区模态框隐藏 Skip 按钮（该上下文下 Inherit 位于 picker 上）；同文件还提供with_compact_mode，切换到模态框的精简呈现：不显示描述头、下拉框隐藏既有密钥与 Skip、自动进入首个密钥类型的创建表单、并在表单上方渲染 harness 选择器（auth_secret_ftux_view.rs）；
• 创建表单的提交流程由validated_form_snapshot统一校验（名称 trim 后非空、必填字段 trim 后非空），handle_continue构造ValidatedForm后调用HarnessAvailabilityModel::create_auth_secret（auth_secret_ftux_view.rs）；
• 视图只消费"属于自己"的AuthSecretCreated事件：通过is_saving && harness 匹配 && pending_name 匹配三重过滤，避免并发 FTUX 视图的成功事件误关当前模态框（auth_secret_ftux_view.rs）。

9.3 宿主职责

• 云模式：由 app/src/terminal/input.rs 以云模式选中的 harness 构造 FTUX 视图/下拉框，并订阅新的生命周期事件，执行与原先内联完全相同的副作用（持久化选中密钥、标记 FTUX 完成、写入last_selected_auth_secret等），从而保持云模式 UX 端到端不变。
• 工作区模态框：订阅同一组事件，执行模态框特有行为（关闭 + 持久化）。

AuthSecretFtuxDropdown也做了同样的形状变更：直接接收 harness、暴露set_harness、移除subscribe_to_model(AmbientAgentViewModel)依赖；app/src/terminal/view/ambient_agent/mod.rs 更新了 re-exports。

10. 云模式对等性（Parity）

TECH.md 第 10 节明确了两条必须在编排卡片上镜像的云模式行为：

10.1 默认选择逻辑

resolve_default_auth_secret_for_harness只提升（promote）已持久化的last_selected_auth_secret值，绝不回退到"第一个已加载密钥"。这一点同时匹配 warp-server 的 webapp（HarnessAuthSecretSelector+use-agent-form-state.ts）与云模式的auth_secret_selector.rs::maybe_restore_auth_secret_from_settings。没有显式选择时，picker 停留在"+ New API key…"（或在不支持托管类型的 harness 上停留在 Inherit 文案）。

10.2 持久化形态

• 在任一卡片上选中托管密钥 → 写入同一份CloudAgentSettings.last_selected_auth_secret（按harness.config_name()键控），云模式下次启动时读取；
• 选择 Inherit → 清除该键；
• 切到Unset（通过"+ New API key…"）→ 同样清除，保证取消模态框不会残留陈旧名字。

11. 关键文件清单

复用的创建密钥视图（已解耦）

• app/src/terminal/view/ambient_agent/auth_secret_ftux_view.rs —— 构造时接收harness: Harness；暴露set_harness；以AuthSecretFtuxViewEvent::{Created, Cancelled, Skipped, Failed}事件替代直接模型修改；提供with_skip_hidden开关；含compact_mode精简呈现
• app/src/terminal/view/ambient_agent/auth_secret_ftux_dropdown.rs —— 同样的形状变更，移除subscribe_to_model(AmbientAgentViewModel)依赖
• app/src/terminal/view/ambient_agent/mod.rs —— 更新 re-exports

云模式重接线（保留既有 UX）

• app/src/terminal/input.rs —— 以云模式选中 harness 构造 FTUX 视图/下拉框，订阅生命周期事件并执行原内联副作用

编排卡片表面

• app/src/ai/blocklist/inline_action/orchestration_controls.rs —— 共享 picker 逻辑：AuthSecretSelection线程化、"+ New API key…"菜单条目、apply_create_new_auth_secret_requested、apply_created_auth_secret_if_matches、OrchestrationControlAction::create_new_auth_secret_requested变体
• app/src/ai/blocklist/inline_action/run_agents_card_view.rs —— 确认卡片：实现新 trait 变体、接线工作区模态框派发、订阅HarnessAvailabilityEvent::AuthSecretCreated、持有一次性自动打开守卫
• app/src/ai/document/orchestration_config_block.rs —— 计划卡片行内配置块：picker、动作 handler、AuthSecretCreated采纳逻辑与确认卡片一致

工作区模态框宿主

• app/src/workspace/action.rs —— 新增WorkspaceAction::OpenCreateAuthSecretModal { harness }
• app/src/workspace/view.rs —— 持有ModalViewState<Modal<AuthSecretFtuxView>>，响应新动作打开模态框，订阅生命周期事件以关闭并持久化

按钮门控管线

• app/src/view_components/compactible_action_button.rs ——set_disabled/set_tooltip
• app/src/view_components/compactible_split_action_button.rs —— 将set_disabled/set_tooltip委托给主按钮与菜单按钮

12. 验证方式

自动化

仓库技术文档记录的自动化验证命令（TECH.md 第 11 节）：

cargo check -p warp cargo fmt cargo clippy --workspace --all-targets --all-features --tests -- -D warnings

手动验证要点

产品文档 specs/QUALITY-702/PRODUCT.md 第 7 节给出了完整的手动测试矩阵，关键场景包括：

• 清空所有托管 Claude Code 密钥后编排 Cloud + Claude Code：确认模态框自动打开一次；取消后不再弹出；点击 picker 的"+ New API key…"可重新打开；
• 模态框中创建密钥：确认 picker 自动选中新密钥且 Accept 启用；
• 取消模态框：确认 picker 停在"+ New API key…"、Accept 保持禁用并带 hover tooltip；
• 显式选择 "Inherit key from environment"：确认 Accept 启用；
• 卡片从 Claude Code 切到 Codex（无 Codex 密钥）：确认模态框为 Codex 自动打开一次；
• 卡片 Cloud ↔ Local 切换：确认自动打开为新模式重新武装；
• 恢复包含已展示编排卡片的历史对话：确认不弹出模态框；
• 云模式 FTUX 全流程：确认端到端行为不变。

13. 后续事项

TECH.md 第 12 节记录了三条后续方向：

• 考虑把工作区持有的模态框抽取为小型可复用宿主（目前内联在Workspace上），当出现第二个消费方时再引入抽象；
• 待编排 picker 视觉定型后，为"+ New API key…"条目增加轻量视觉处理（如前置加号图标）；
• 长期看，云模式 FTUX 视图的 "Skipped" 路径可整体移除——工作区模态框已隐藏 Skip，编排 picker 也直接暴露 Inherit，Skip 已无实际消费场景。

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