IronClaw 新用户首次体验（OOBE）设计解析：从冷启动到第一条建议卡片-育师

人工智能
AI 应用
交互助手
AI Agent

【免费下载链接】ironclaw

IronClaw is an Agent OS focused on privacy, security and extensibility

项目地址：https://gitcode.com/gh_mirrors/iro/ironclaw

导读

本文基于 IronClaw 仓库 docs/internal/design/oobe.md 设计简报展开，系统讲解 WebChat v2 面向新用户「前五分钟」的首次体验（Out-of-Box Experience, OOBE）设计：用户在完成账号/工作区开通后第一次进入 Web 聊天界面的那一刻，产品如何通过「建议任务卡片」完成冷启动、如何呈现第一条自动化建议、以及如何在返回用户场景中复用同一套抽屉控件。读完本文，你将掌握该设计的双轨演进历史（Foundational → Vision）、建议任务卡片的视觉语言与状态模型、可复用任务抽屉的交互形态，以及它与仓库中已落地的持久化后端建议契约（suggestions.list / generate / start / dismiss）之间的真实对接关系。

一、要解决的核心问题：冷启动与第一条自动化

WebChat v2 的落地视图（landing view）今天是「大标题 + 输入框 + 三个静态建议 chip」，对应组件为 empty-state.tsx。仓库中已经原型化的自动化表面——「Done for you」轮播（carousel）、行内日历改期卡片、Plan 卡片、agent 模式药丸（pill）——全都假设自动化已经存在。而一个全新账号没有任何自动化，因此两个关键时刻是空白的：

冷启动（cold start）：什么都没有，用户不知道 IronClaw 能为他做什么；
第一条自动化出现（first automation appearing）：第一个「替你完成」的时刻如何呈现。

设计简报给出的目标是：设计新用户的前五分钟——账号/工作区开通后落在 Web 聊天界面的瞬间。非目标（non-goals）同样明确：不重设计稳态聊天、不重设计自动化管理页、不重设计扩展目录，只在其上增加一层首次运行体验并复用已有能力。

二、双轨设计：Foundational 与 Vision（Version 开关）

设计载体是自包含的交互原型 mockup.html，内置Version开关（Foundational / Vision）与Scene开关（First run / Thread / Plan），可在浏览器中直接打开播放。两套设计共享同一套卡片语言，并在自动化存在后收敛到同一个「已填充的轮播」。

2.1 Foundational —— 近期的、贴合当前 main 的实现

面向多租户企业部署，只做今天 v2 系统上轻量可行的事：

工具由管理员白名单、用户自行授权：不设独立的连接面板；每张建议卡片携带「Connect <Tool>」CTA，授权通过模态 OAuth「浏览器」对话框完成（登录 → 批准 scopes）。连接成功后卡片变为可操作的建议。
建议卡片在第一步即出现：agent 立即给出第一批建议（无需先「挣得」一个空冷启动）；每张卡片从connect状态开始，工具授权后变为 approve/modify/dismiss。卡片以提案语气呈现（"Triage your inbox"），运行后翻转成结果语气（"Triaged your inbox"）。
无用户名：除非能从确定性来源（管理员预配置、email、Slack 资料）推导出来；默认是匿名称呼（"Welcome to IronClaw."）+ 普通账号 chip。
agent 模式收敛为三种，默认Suggest：
- Suggest——执行任务或自动化前始终请求批准；
- Plan——先描述活动与所需步骤，等待批准；
- Auto Approve——自动批准用户已批准过的任务类型，以及用户显式请求的任何任务。
使用main 的 composer和朴素pills-collapse 抽屉（用户开始输入时，任务卡片折叠为 composer 上方的一行药丸），无边框/无吸附抽屉。

2.2 Vision —— 北极星目标

在 Foundational 之上叠加理想化的首次运行体验：

冷启动连接流：一个「连接你的工具」面板，用户选择工具后，排队式模态 OAuth「浏览器」对话框逐个走完（一次登录、每个工具批准 scopes），直到全部授权；随后是期待节拍 → 第一张卡片揭晓。支持具名问候语与四模式集合（Suggest / Plan / Auto /Bypass）。
首条自动化揭晓：情感峰值——一段短暂的期待节拍（品牌化NEAR 进度指示器+ 骨架瓦片），随后第一张「Done for you」卡片以 Gemini 风格ai-spark边框扫光凭空浮现。在prefers-reduced-motion下被抑制。
吸附式任务抽屉：建议卡片放入一个吸附在 composer 上、向上延伸的带边框抽屉框内；品牌化进度指示器 + agent 活动字符串位于抽屉上方；抽屉头部携带副标题（左上）+折叠/展开（卡片 ↔ 药丸）+关闭（✕，关闭后出现「Show suggestions」恢复条）。输入时仍折叠为药丸。

设计原则：Vision 的每一件都是 Foundational 对应物的超集（逐卡连接 → 批量连接；静态首卡 → 动画揭晓；朴素抽屉 → 吸附框；3 模式 → 4 模式），Foundational 永不丢弃，Vision 只是扩展它。

三、任务抽屉：可复用控件而非一次性 OOBE 装置

设计简报明确强调：抽屉不只是 OOBE 设备，它是返回用户或打开新线程时「建议任务」的可复用表面：

折叠态：紧凑的可滚动药丸行（品牌 logo + 标题），吸附在 composer 上；
展开态（Vision）：完整卡片框。

这为返回用户提供了一个持久的、可关闭的「这是我接下来可以接手的事」提示（affordance），而不会霸占线程。抽屉的状态机（open / collapsed / dismissed）在 PLAN.md 中被明确复用：Vision 的吸附抽屉「复用 Foundational 抽屉状态机」。

四、卡片设计语言（两个版本共享）

真实品牌产品 logo（Gmail、Google Calendar、Docs、Drive、Slack 全彩；GitHub + Notion 通过currentColor单色以跟随主题），而非占位字形。
标题优先的头部（图标 + 任务标题），无状态标签；状态从操作行读取。
弱化的「From <app> · <time>」来源行；实心主按钮 + 次级文字按钮（Approve / Modify / Dismiss），所有模式下链接按钮均带图标。
更大圆角、柔和阴影、紧凑高度；操作行底部对齐。

这份卡片语言在仓库中的实现位置与原型记录可对照 mockup.html 与 integration-review.html（后者为自包含的视觉评审页面，含 5 层集成示意图、依赖图与阶段时间线）。

五、代码落点：这套设计住在哪里

设计简报给出了精确的仓库落点（SPA 技术栈为React 19 + TypeScript + Tailwind v4，设计令牌在styles/app.css）：

落地视图：empty-state.tsx（在main上）；
自动化表面组件族：automation-carousel.tsx、automation-task-card.tsx、task-action-bar.tsx、mode-selector.tsx，mock 数据接缝lib/automation-tasks*.ts+hooks/useAutomationTasks.ts，以及 DEV 环境pages/design-preview/design-preview-page.tsx——这些在 PR #6994 中原型化后被回滚，不在main上，其形态记录在 mockup 与接线契约中；
后端契约文件：AUTOMATION-TASKS-CONTRACT.md（提案版接线：AutomationTask领域模型、5 个持久事件、投影、HTTP 路由与 facade 方法）；
治理文档：VISION-RECONCILIATION.md（governs——当与 PROPOSAL/PLAN/IMPLEMENTATION 冲突时以此为准），配套 README.md（概述）、PROPOSAL.md（完整规格）、PLAN.md（执行顺序）、CHECKLIST.md（完成定义）。

设计简报同时指出了当前的真实状态：今天轮播在无任务时return null，全新账号看到的是未变化的 hero + composer——即冷启动状态目前未被设计，这正是该 mockup 要填补的部分。

六、已经落地的 vs. 需要后端的

设计简报把工作分成两类，边界清晰：

已原型化后回滚（PR #6994，纯展示、mock 数据）：轮播 + 任务卡 + 操作栏、日历改期卡、Plan 卡、agent 模式药丸，以及端点形态的数据接缝。而品牌化的NearProcessIndicator（#6901）与AuthRequired连接器路径已在main上。

需要后端（issue #6993）：「还没有自动化」/「正在做第一条」的投影状态；揭晓由AutomationTaskAutomated投影事件驱动；期待/骨架状态；返回用户的抽屉建议 feed；三模式 vs 四模式的 agent 模式门控——这些是 AUTOMATION-TASKS-CONTRACT.md §2–§7 接线之上的新 UI。

6.1 提案契约（历史记录）：AutomationTask 领域模型

契约文档（§§1–3 已被 PR #7694 取代，仅作设计意图记录）曾规划如下 Rust 模型（镜像 TS 的AutomationTask，标识符用ironclaw_common的 newtype）：

pub struct AutomationTaskId(String); // newtype，校验 pub enum AutomationApp { // #[serde(rename_all = "snake_case")] Gmail, GoogleCalendar, GoogleDocs, Slack, Notion, } pub enum AutomationTaskKind { // snake_case EmailTriage, CalendarAccept, CalendarReschedule, DocInsights, } pub enum AutomationTaskState { // snake_case Suggested, InProgress, Automated, Reverted, Cancelled, }

以及 5 个持久事件：AutomationTaskProposed/Modified/Automated/Reverted/Cancelled（每个都脱敏、可重放、经持久化 sink 追加），配(tenant, user)作用域过滤的AutomationTaskProjection（带重放游标，并强制跨用户隔离回归测试）。

七、治理变更：Vision 直接对接已落地的持久化后端建议契约

关键转折：PR #7694 直接落地了「持久化后端建议」契约（feat: add durable backend suggestions），它是后端纯实现，明确「前端文件不变、前端消费不在其范围」。这恰好补上了 PR #6994 占据的接缝——#7694 是生产者，#6994 变为消费者。于是程序从「先 Foundational 后 Vision」转向直接构建 Vision，Foundational（Phase 1）UX 被裁掉，VISION-RECONCILIATION.md 成为治理文档。

7.1 冻结在 ironclaw_product_contracts 中的契约

方法	WebUI 路由	产品操作
`GET`	`/api/webchat/v2/suggestions`	`suggestions.list`
`POST`	`/api/webchat/v2/suggestions/generate`	`suggestions.generate`
`POST`	`/api/webchat/v2/suggestions/{id}/start`	`suggestion.start`
`DELETE`	`/api/webchat/v2/suggestions/{id}`	`suggestion.dismiss`

响应形态：

RebornSuggestionsResponse { status: "empty" | "generating" | "ready" | "failed", generation_id?: string, retry_after_seconds?: number, suggestions: RebornSuggestion[], } RebornSuggestion { id, title, description, suggested_prompt, thread_id?, run_id? } RebornSuggestionStartResponse { suggestion_id, thread_id, run_id } RebornSuggestionDismissResponse { suggestion_id, dismissed }

这些类型在仓库中有源码级印证：suggestions.rs 声明了SUGGESTIONS_LIST_VIEW（suggestions.list，无分页 ProductView）、SUGGESTIONS_GENERATE_COMMAND（suggestions.generate）、SUGGESTION_START_COMMAND（suggestion.start）与SUGGESTION_DISMISS_COMMAND（suggestion.dismiss）四个命令描述符，并配有序列化测试（generate请求必须携带client_action_id，list请求为空输入，响应含status/generation_id/retry_after_seconds/suggestions字段）。对应的 DTO 与响应类型位于 product_wire.rs，路由处理器与描述符行在 handlers.rs 与 descriptors.rs，并有 webui_v2_descriptors_contract.rs 等契约测试守护。

异步生成语义：POST generate（携带client_action_id）返回202与status: generating及retry_after_seconds提示；客户端轮询GET suggestions。每个(tenant_id, user_id)存在一套卡片；新一轮生成清除上一套。卡片数量限制在1–5条（schemas/suggestions.output.v1.json），title≤ 80、description≤ 240、suggested_prompt≤ 2000 字符。路由与前端建议表面始终开启，且表面保持懒加载，使其卡片/图标代码不进入 eager/chatbundle。

7.2 Vision 因此获得了什么

POR 元素	之前	有了 #7694
持久卡片存储、路由、生产者	全新未建	已落地
期待 /「正在做第一条」状态	「新投影状态（#6993）」	真实：`empty`/`generating`+`retry_after_seconds`
首卡揭晓（ai-spark conjure）	需要`AutomationTaskAutomated`事件	可用：触发`generating → ready`转换
Approve → 运行	经`handleSend`提示注入	被取代：`suggestion.start`返回`{thread_id, run_id}`
卡片实时状态	已退役——无持久绑定	复活：卡片携带持久`thread_id`/`run_id`
Dismiss	本地组件状态	持久`DELETE`
吸附抽屉 · 具名问候	前端 / 开放决策	不受影响

其中影响最大的是「卡片实时状态」：卡片级持久状态曾因「需要持久化的逐任务记录」而被退役，而 #7694 正是那条记录——返回用户卡片能显示真实状态，因为 suggestion→thread/run 的绑定是持久化的、重启后依然存活。

7.3 连接模型的裁决：connect 不再是一个卡片状态

生成的卡片原不携带工具身份与连接状态（{ id, title, description, suggested_prompt, thread_id?, run_id? }），这是刻意为之：prompts/suggestion_generation.md 指示生成器「没有证据表明账号/扩展/凭证/能力可用时，不得声称其可用」，且偏好「assistant 在普通对话中能完成的工作」。模型能看到扩展（扩展搜索在能力白名单内），但输出 schema 无处声明它。

最终裁决（§3.1）：connect 不再是卡片状态。Vision 冷启动连接面板作为独立的落地表面保留，由扩展目录（useExtensions）驱动，而非由建议卡片驱动。connect 与 suggestions 成为两个并列表面：

Landing ├── Connect panel ← extensions catalog (useExtensions)，批量 OAuth walk └── Suggestion drawer ← GET /suggestions，工具无关的卡片

后果：

卡片永不因连接而阻塞——卡片一经存在即可 start；
即时（just-in-time）授权仍然有效——若一次 start 的运行需要未连接的工具，agent 发出既有的AuthRequired门框，线程渲染AuthOauthCard（已落地的既有路径，不变）；（待 QA 验证假设：AuthRequired会为 suggestion-started 运行触发，因为是同一 agent loop，应会触发，但尚未测试。）
面板失去逐卡「为什么这个工具重要」的框架——被接受的权衡；
resolveConnectExtension被废弃删除（其职责是卡片appid → 目录扩展；目录驱动面板直接读目录）。但它验证的复用模式——懒加载真实ConfigureModal而非克隆useOauthSetup约 250 行的弹窗/轮询状态机——被继承到 V1 面板，也正是该面板构建便宜的原因。

落地后的icon/sources细节见 SUGGESTION-ICONS.md：icon是必填的、provider 中立的语义任务枚举（email/calendar/document/storage/spreadsheet/presentation/code/messaging/notes/web/memory/generic，generic为兜底），只控制卡片字形，不是扩展身份；sources是 1–5 条人类可读来源标签，纯展示、前端绝不从中推导图标或 setup 路由。

八、契约带来的两个已决决策

卡片并行运行——单一活动锁被移除。原设计将「同时只有一个活动任务」建立在submit_turn返回DeferredBusy/RejectedBusy（线程上已有运行在跑）之上；但suggestion.start为每条建议创建独立线程，后端并无约束需要镜像——批准一张卡不再禁用其他卡，这正是 Vision 多卡抽屉想要的。
「+ Automation」被移除。卡片 schema 没有automation_prompt字段，#7694 也未新增自动化路由，没有可构建的依据；与其保留一个无持久背书的客户端合成提示注入，不如整条从卡片移除。（若日后循环自动化成为首运行目标，需要自己的后端契约。）

九、重构映射与切片计划（PR #6994）

治理文档给出 keep/change/delete 重构映射：

Keep	Change	Delete
`SuggestedTaskCard`（展示层）	`DEMO_TASKS`→`GET /suggestions`+ generate/poll	`resolveConnectExtension`+ 测试
`SuggestedTaskSurface`外壳	Approve →`POST /{id}/start`→`onSelectThread(thread_id)`	`unconnected`卡片状态
常开建议表面（路由无 flag）	Dismiss →`DELETE /{id}`	卡片上的`ConfigureModal`接线
懒加载 + bundle 纪律	`SuggestedTask`类型 →`RebornSuggestion`形态	`chat.oobe.connectUnavailable`（11 个 locale）
`NearProcessIndicator`render-prop	卡片状态派生自绑定的`run_id`	`connectedIds`状态

切片计划（slices 1–6、9、10 已构建）：

✅ 建议 API 客户端 + 类型（四个类型化调用，遵循lib/api.ts约定：apiFetch、clientActionId()；DTO 镜像RebornSuggestion）；
✅ 表面消费真实数据（mount 时list；empty→ generate CTA；generating→ 按retry_after_seconds轮询；ready→ 渲染卡片；failed→ 重试）；
✅ start + dismiss（Approve 调start并导航到返回的thread_id；dismiss 调DELETE）；
✅ 移除连接模型（unconnected状态、解析器、i18n key）；
✅ V3 期待状态（empty CTA / generating 骨架 / failed 重试；generating 态在静态.v2-skeleton瓦片上渲染品牌化 NEAR 指示器）；
✅ V2 揭晓（克制的卡片入场.oobe-card-reveal，复用已批准的v2-page-in关键帧，prefers-reduced-motion抑制；注意这是治理干净的版本，不是mockup 中即兴的 conic-gradient ai-spark 边框扫光——那会绕过app.css的静态运动策略）；
⏳ 卡片实时状态（订阅绑定run_id，反映运行中/完成/失败；未构建）；
⏳ V1 连接面板（目录驱动的冷启动「Connect your tools」表面，复用ConfigureModal模式；未构建）；
✅ V4 吸附抽屉框（表面以带边框抽屉渲染，头部「Suggested for you · approve to run, or tweak first」，吸附在 composer 附近；未做真正的边框融合，保留圆角框 + 紧凑间隙以不触碰已落地的ChatInput）；
✅ 刷新 + 连接入口（issue #7815，F1/F2）——抽屉头部带刷新控件（重跑generate，进行中禁用）与/extensions入口；空/失败 CTA 行将 generate/retry 与同一连接入口配对。

剩余的 Vision 后续（未构建，供设计评审跟踪）：卡片实时状态（slice 7）、V1 连接面板（slice 8）、agent 模式选择器（Suggest / Plan / Auto / Bypass，net-new，需持久住所 + 类型化门控接线）、输入折叠为药丸、具名问候 + 顶栏客户端用户名调用（V5）（推迟：需要确定性用户名来源）、ai-spark 揭晓（若采用不绕过运动策略的动画方案）。

十、安全与隔离约束

租户/用户作用域：投影按(tenant, user)过滤，跨用户隔离回归测试强制；
仅经中介的效果：Approve/Modify(rerun)/Revert 是真实第三方效果，必须经能力宿主 + 产品适配器，成功仅由 provider 证据 + 回读确认，绝无乐观回显；
脱敏：每个事件 payload 默认敏感，在 log / 持久追加 / 投影 / 传输 / 模型可见结果之前承担脱敏义务；
自主性升级：auto（Foundational）与bypass（Vision）对整类任务抑制批准门，均需显式门控抑制测试 + 每次自动运行动作的审计痕迹；auto把global_auto_approve从单一布尔推广为按类型的同意；
无新认证路径：connect 复用共享扩展授权解析器，凭证身份与扩展身份保持分离。

十一、开放问题（截至文档状态）

分期：Foundational 先对当前 main 落地；Vision 中哪件先毕业——吸附抽屉、连接流还是揭晓动画？
用户名推导（Foundational）：多个确定性来源同时存在时哪个优先（管理员预配置 vs email vs Slack 资料），全部失败时的兜底是什么？
Auto Approve 范围：「用户已批准的任务类型」如何定义与界定（按工具、按动作、消费/影响上限）？
企业工具配置：管理员预配置的工具集如何呈现给用户——只读「由你的工作区连接」提示，还是不可见？
Vision 冷启动是否播种一条真实的低风险自动化以保证首卡出现，还是等待有机活动？
替换 UX：新一轮生成清除上一套；用户在阅读中遇到替换落地时抽屉该做什么？
逐卡连接：未来若加逐卡连接动作，必须由后端给出类型化扩展身份或经扩展目录解析，绝不能从icon或人类可读的sources字符串推断身份。