holaOS 首次启动 Onboarding 重设计：从三步向导到“登录即对话“的单屏体验-平芜编程栈

人工智能
AI Agent
AI 应用
前端
后端
即时通讯
交互助手
工具调用

【免费下载链接】holaOS

Open-source agentic workspace enterprises can make their own. Connect the systems you already run — 100+ integrations, MCP, chat tools, apps, browser, local files — with shared memory. Any agent (Claude Code, Codex), any model, or BYOK. Set up in clicks, not months. Local-first: your data never leaves your machines.

项目地址：https://gitcode.com/GitHub_Trending/ho/holaOS

点击查看免费下载

本文基于 holaOS 仓库内设计文档 docs/plans/2026-06-04-first-launch-onboarding-design.md，系统拆解桌面端首次启动引导（First-Launch Onboarding）的完整重设计方案：从"名称 → 文件夹 → 布局"三步模态向导，收敛为登录后一个屏幕直达首条聊天消息；同时给出模型提供商透明化、上下文集成提示、一次性 Coachmarks、模板与起始芯片等配套机制的设计细节与分阶段落地路线，并结合当前仓库源码说明现状与演进方向。读完本文，你可以完整复现该方案的交互流程、视觉规范、触发规则与度量口径，并理解它如何与 holaOS 的应用（Apps）、队友（Teammates）、技能（Skills）、集成（Integrations）四层能力相互咬合。

一、问题背景：为什么现有的三步向导需要重做

设计文档指出现有首次启动体验由两部分组成：一个"名称 → 文件夹 → 布局"的三步模态向导（对应仓库中apps/desktoprenderer 侧的旧FirstWorkspacePane流程），以及向导之后一个带两张抽象操作卡（"Build an app" / "Hire a teammate"）的空工作区。这套体验存在四个核心问题：

价值交付前先加摩擦：用户在获得任何价值之前就被迫完成三步表单输入；
落地页过于泛化：向导后的空工作区无法传达 holaOS 的差异化能力，侧边栏里一排空的 Apps / Skills / Cronjobs 区块反而构成认知负担；
模型提供商不可见：用户不知道当前在用什么模型、经由什么代理，只能去 Settings 里找；
无产品内引导：没有 in-product tour，也没有上下文相关的集成提示，新用户需要自己摸索一切。

文档还点出行业背景：主流 AI SaaS（ChatGPT、Claude.ai、Cursor、v0、Bolt、Lovable、Replit Agent、Perplexity）的 onboarding 都跳过了角色/行业采集，第一屏就把用户放在一个可产出的输入框前。holaOS 的现状与这一趋势脱节。

二、设计目标与非目标

Goals

一屏一动作：登录与首条聊天消息之间只有一个屏幕；
60 秒内让差异化可见：apps、teammates、skills、integrations 应作为用户首个任务的"副作用"自然出现，而不是一份待勾选的清单；
模型提供商透明：不藏在 Settings 里；
集成提示上下文化：按需出现，而非前置的集成网格；
高级功能一次性 Coachmark：在用户即将使用某功能时给出单次引导。

Non-goals

强制 API-key 配置（默认 Holaboss Proxy 开箱即用）；
角色 / 行业 / "tell us about yourself" 调查问卷；
模态视频导览、启动轮播、自动播放教程；
首次启动的文件夹位置 / 布局选择器（默认值即可，二者之后都可改）。

三、总体流程：工作区在入口选择之后才创建

Sign in ──→ Welcome Screen (one screen) ──→ Workspace + Chat │ ↑ ├─ Type a prompt ───────────────┤ ├─ Click a starter chip ────────┤ ├─ Click a template card ───────┤ (template seeds apps + teammates) └─ "Skip & start blank" ────────┘

流程的核心变更在于时序：工作区是在用户从四个入口中做出选择之后才创建的，而不是在之前。工作区名称由动作推导而来（如 "Inbox summary"、"Content creator workspace"），文件夹使用 Holaboss 管理的默认路径，布局默认split——三者均可事后修改。

这一设计与当前仓库代码的实现方向一致：apps/desktop/src/components/panes/ChatPane/onboarding/OnboardingFlow.tsx中明确指出，"在单工作区世界里，遗留的 'name your workspace' 阶段已经移除：服务器在首次登录时惰性预置一个工作区（见 runtime 侧GET /api/v1/workspaces）"，用户看到 onboarding 时工作区已经存在，因此不再需要命名/选目录这类前置输入。同时electron/main.ts中已出现template_mode（"template" | "empty" | "empty_onboarding"）、workspace_onboarding_mode（"start" | "skip"）、workspace_onboarding_engine（"deterministic" | "agentic"）等运行时字段，表明"模板播种工作区"与"start/skip 二选一"的执行语义已进入主进程侧的建模范围。

四、Screen 1 — Welcome：唯一的 onboarding 屏幕

该屏幕取代现有的FirstWorkspacePane向导，是登录后唯一的 onboarding 屏幕。设计文档给出了完整的线框：

╭──────────────────────────────────────────────────────────────╮ │ ● ● ● │ │ │ │ holaOS │ │ your AI workspace │ │ │ │ ╭──────────────────────────────────────────────╮ │ │ │ ✦ What would you like to get done? ↵ │ │ │ ╰──────────────────────────────────────────────╯ │ │ │ │ Try one of these │ │ ╭──────────────────╮ ╭──────────────────╮ │ │ │ ✉️ Summarize my │ │ 🔍 Research the │ │ │ │ inbox today │ │ best CRM tools │ │ │ ╰──────────────────╯ ╰──────────────────╯ │ │ ╭──────────────────╮ ╭──────────────────╮ │ │ │ ✍️ Draft a cold │ │ 📅 Plan my week │ │ │ │ email to … │ │ from my cal. │ │ │ ╰──────────────────╯ ╰──────────────────╯ │ │ │ │ ───────── or start from a template ───────── │ │ │ │ ╭──────────────╮ ╭──────────────╮ ╭──────────────╮ │ │ │ 👤 │ │ ✍️ │ │ 🔍 │ │ │ │ Personal │ │ Content │ │ Researcher │ │ │ │ Assistant │ │ Creator │ │ │ │ │ │ ───────── │ │ ───────── │ │ ───────── │ │ │ │ Gmail · Cal │ │ Twitter · │ │ Browser · │ │ │ │ · memory │ │ LinkedIn │ │ summarizer │ │ │ ╰──────────────╯ ╰──────────────╯ ╰──────────────╯ │ │ │ │ Skip & start blank │ ╰──────────────────────────────────────────────────────────────╯

屏幕结构自上而下依次为：品牌区（holaOS + tagline "your AI workspace"）、作为视觉锚点的中央 Composer 输入框、四张起始芯片（starter chips）、三张模板卡片（template cards）、以及弱化视觉的 "Skip & start blank" 逃生通道。

交互规则

输入框自动聚焦：键盘路径是最快路径；
起始芯片点击即发送：不把用户丢回 Composer 编辑，而是立即发送消息——"置信度优先于编辑焦虑"（Confidence over edit-anxiety）；
模板卡片创建预载工作区：使用该模板的 apps + teammates + skills 预装的工作区，然后带一条模板专属 prefill 进入聊天（如Help me get started with my Researcher workspace）；
"Skip & start blank" 视觉上刻意做小：它是逃生通道，而不是推荐项。

视觉基调

Linear 风格空状态，垂直留白充足；
H1 与 chips 使用 Inter，仅 tagline（"your AI workspace"）使用 Newsreader 以增加工艺感；
卡片无渐变，纯色背景 + 1px 细边框；
Composer 输入框是视觉锚点，比屏幕上其他元素更大、对比更强。

当前仓库的apps/desktop/src/components/onboarding/OnboardingShell.tsx提供了可复用的全屏 onboarding 画布：品牌行 + 发丝分隔线 + 可选 Back 链接 + 居中内容槽 + 底部版权栏，并保留了 macOS 拖拽区（titlebar-drag-region）。新 Welcome 屏可以直接套用这一外壳，只替换中间的内容槽。

五、Screen 2 — 首条消息之后：工作区壳 + 进行中的对话

用户通过任一入口发出首条消息后，直接落入常规工作区壳（workspace shell），聊天已经在进行中：

╭────────────╮ ╭──────────────────────────────────────────────╮ │ ▾ Personal │ │ ◀ Home Inbox Artifacts ⊕ │ ├────────────┤ ├──────────────────────────────────────────────┤ │ │ │ You │ │ (sidebar │ │ Summarize my inbox today │ │ fades in │ │ │ │ AFTER │ │ ● Connecting to Gmail… │ │ first │ │ │ │ reply) │ │ Assistant │ │ │ │ Here's what's in your inbox today… │ │ │ │ … │ │ │ │ ╭──────────────────────────────────────╮ │ │ │ │ │ 💡 Want this on your real inbox? │ │ │ │ │ │ Connect Gmail to make this live. │ │ │ │ │ │ [Connect] [Maybe later] │ │ │ │ │ ╰──────────────────────────────────────╯ │ │ │ ├──────────────────────────────────────────────┤ │ │ │ ▷ Reply… Claude Sonnet 4.6 │ │ │ ╰──────────────────────────────────────────────╯ ╰────────────╯

三个刻意设计的细节

1. 侧边栏在首个回复流式完成前淡出。空白的Apps/Skills/Cronjobs区块对新用户是认知税；先让用户看到价值，再让侧边栏出现。这对应apps/desktop/src/components/layout/shell/AppShell.tsx中的侧边栏挂载路径（Sidebar、Center等均在 AppShell 内组装），实现时只需在首个回复完成前对侧边栏施加透明度动画与交互降级。

2. Composer 铬条始终展示当前模型。如 "Claude Sonnet 4.6"、"via Holaboss Proxy"，可点击进入 Settings → Providers。"透明 = 信任"。这与 holaOS"任何模型（Claude Code、Codex）、任何模型或 BYOK"的定位一致——用户应随时知道自己在用什么模型、经由什么代理。

3. 集成提示卡上下文化出现。仅当消息实际用到了需要真实集成的工具时才出现（例如 agent 调用了 Gmail 工具但当前未绑定 Gmail 账户）。规则是：每个缺失集成、每个会话最多一条提示。文档将其明确列为 P1 阶段的独立工作项："将现有connect integration流程接到 agent 的 tool-call 站点上"，使得提示"在该出现时出现，仅在该出现时出现"。

仓库中已有的集成连接能力可直接支撑该提示卡：apps/desktop/src/lib/listAllIntegrationConnections.ts枚举所有已建立的集成连接，apps/desktop/src/components/layout/shell/IntegrationCredentialDialog.tsx提供凭据绑定对话框，而apps/desktop/src/lib/workspaceDesktop.tsx中的composioToolkitSlugForProvider等函数负责 provider 与 Composio toolkit slug 的映射。这些是"Connect / Maybe later"按钮的现成接线点。

六、Coachmarks：一次性、可关闭、按需触发

Coachmark 系统负责在不打断用户的前提下，恰好在"用户即将用到某功能"的时机出现：

╭──────────────────────╮ │ Press ⌘T to open more│ │ tabs anywhere. │ │ [ Got it ]│ ╰─────────┬────────────╯ │ ╭──────────────────────────────────────────▾──╮ │ ◀ Home Inbox Artifacts ⊕ │ ╰──────────────────────────────────────────────╯

触发条件表

Coachmark	Triggered when
`⌘T`opens tabs	User opens the second tab manually
`⌘K`global search	User hovers the sidebar search > 3s without typing
`/`slash commands	First time composer is focused with > 0 characters typed
`@`mentions	After the user has sent 3+ messages

规则

同一时刻至多显示一个 Coachmark；
每个 Coachmark 对同一用户终生最多显示一次（通过 electron settings 持久化）；
Settings 中提供全局 "Reset onboarding tips" 入口，供用户重新开启。

文档建议实现为通用 hook：useCoachmark(id, trigger, anchor)，配合 electron-settings 支撑的 dismissal 状态。四个初始 Coachmark 的触发时机分别覆盖了标签页系统、全局搜索、斜杠命令与 @ 提及这四类"高阶但高频"的能力。仓库中⌘K全局搜索对应apps/desktop/src/components/layout/shell/SearchDialog.tsx，⌘T标签页系统对应apps/desktop/src/components/layout/shell/state/internalTabs.ts中的internalTabsAtom/activeInternalTabIdAtom，这些模块即为 Coachmark 的锚点（anchor）候选。

七、模板（初始集）：三模板 + 空白

每个模板都足够具体，能在首个会话中就展示 holaOS 的 apps + teammates 层。

Template	Pre-installed apps	Pre-hired teammate	Prefill message
Personal Assistant	Gmail, Calendar, Notes	"Alex" (assistant persona)	`Help me organize my day`
Content Creator	Twitter, LinkedIn, Browser	"Sam" (content strategist)	`Draft a post about [topic]`
Researcher	Browser, Notes	"Maya" (research lead)	`Help me research [topic]`
Blank	—	—	(empty composer)

文档明确"三个模板足够覆盖大多数 'I don't know what I want' 的用户；更多模板可等看到点击分布后再补充"。这与仓库中 teammate/employee 机制的现状吻合：apps/desktop/src/features/employees/下的EmployeeChatPane、EmployeeChatStreamManager以及AppShell.tsx中的useHostEmployeesChanged，说明"预雇用队友"（pre-hired teammate）在运行时侧有真实的宿主通信与聊天流支持。

八、起始芯片（初始集）：六个各有使命的提示

六条具体提示，每一条都会解析为一条至少动用一款 app 或 skill 的聊天消息：

Summarize my inbox today(gmail)
Research the best CRM tools for product designers(browser + summarize)
Draft a cold email to investors(writing skill)
Plan my week from my calendar(calendar)
Build me a personal CRM with contacts and notes(app builder)
Hire me a teammate who helps me review code(teammates)

它们并非随机选取——每一条都用于揭示产品的一个不同表面：集成（integrations）、浏览器（browser）、写作技能（writing skills）、应用构建器（app builder）、队友（teammates）。

这一设计在仓库中已有同构的前身：apps/desktop/src/components/panes/ChatPane/PersonalizedSuggestions.tsx维护了一张"按集成 slug 的单条起始提示"表（SUGGESTION_TEMPLATES，含 gmail、github、notion、slack、linear、googledrive、googlecalendar、googlesheets、jira、zoom），以及一组"能力示例"（CAPABILITY_SUGGESTIONS，如写简报、做对比表格、起草幻灯片提纲、vibe-code 落地页），其注释给出的原则与本文档高度一致："每个提示必须产出用户能展示给他人的有形产物"（every prompt must produce a tangible artifact the user can show someone），且"每个 slug 只保留一条提示以保持列表可扫读"。首次启动的六颗起始芯片可以视为这一机制在登录后第一屏上的前置化部署。

九、明确不做什么（Explicitly NOT doing）

角色 / 行业 / 人设下拉框；
首次启动的工作区名称输入框；
首次启动的文件夹选择器；
首次启动的布局选择器；
"How did you hear about us" 调查；
首次聊天前强制 API-key 配置；
模态视频导览；
自动播放的启动轮播。

这份"不做清单"本质上是约束设计边界的护栏：所有会延迟"第一条消息"的动作全部排除，所有会打断沉浸感的营销/教学形式全部排除。与 Goals 一一对应，确保演进过程不回归。

十、分阶段上线（Phased rollout）

阶段	内容	说明
P0	Welcome 屏幕取代向导	影响最大、独立性强；上线前后对比"首条消息转化率"
P0	起始芯片 + 模板	与 Welcome 同屏一起上线；v1 三个模板足够
P1	Composer 铬条展示模型	聊天 composer 头部的小范围独立改动
P1	上下文集成提示	将现有`connect integration`流程接到 agent 的 tool-call 站点
P2	Coachmarks 系统	构建通用`useCoachmark(id, trigger, anchor)`hook，用 electron-settings 持久化 dismissal 状态，接入四个初始 Coachmark
P2	侧边栏首条消息后淡入	打磨项，不阻塞 P0 / P1

值得注意的工程约束：P0 两个工作项相互独立且同屏共发；P1 两项都是小范围改动（composer 头部、tool-call 站点接线）；P2 是通用机制（Coachmark hook）加打磨，明确"不要因为打磨项阻塞核心路径"。这种依赖分级让团队可以先拿到最大收益（首条消息转化率），再逐步叠加透明化与引导层。

十一、开放问题（Open questions）

起始芯片是否也应出现在任意新聊天会话的空 Composer 中（而非仅首次启动），作为常态化的 "what next" 提示？
模板是否应支持创建后转换（如"将此工作区转换为 Researcher 模板"）？文档倾向 v1 不做；
"用户已完成首次启动 onboarding" 的标志存在哪里：electron settings、runtime DB 还是后端用户档案？文档认为后端最佳（重装后仍保留），但 electron settings 最快上线；
自动推导的工作区名称来自本地启发式还是快速 LLM 调用？LLM 名称更佳但引入延迟。

这些问题的取舍直接决定了后续实现的技术选型，尤其是持久化位置（本地 electron settings vs 后端 profile）与命名延迟（本地启发式 vs LLM 调用）两处，属于典型的产品/工程权衡点。

十二、成功指标（Success metrics）

从登录到发出首条消息的时间：目标中位数 < 30 秒；
注册当会话内发出首条消息的新用户占比：目标 > 80%；
入口分布（输入提示 vs 起始芯片 vs 模板 vs 跳过）：用于持续优化芯片与模板列表；
7 天内至少连接一个集成的新用户占比：作为上下文提示是否奏效的间接信号。

度量体系与设计目标一一对应：前两项直接度量"一屏一动作"的转化效率；入口分布驱动芯片/模板的迭代；集成连接率验证"上下文提示优于前置网格"的假设。仓库apps/desktop/src/main.tsx中recordLaunch()与trackUmamiEvent("desktop_launched", { is_first_launch: launch.isFirstLaunch })已提供首次启动事件埋点的基础设施，后续可在其基础上补充首条消息时间、入口类型等自定义事件，用于支撑上述指标的量化对比。

结语

这份设计文档的价值在于把"首次启动"从一次表单填写，重新定义为一次"用户带着真实意图进入工作区"的机会：一个屏幕、四个入口、60 秒内让 holaOS 的应用/队友/技能/集成层自然浮现；模型透明化建立信任；上下文集成提示在需要时出现；一次性 Coachmark 在用户即将使用高阶功能时轻推一把。P0→P2 的分阶段路线与明确的度量指标，使这套方案既能快速验证核心假设（首条消息转化），又能持续演进（Coachmark、侧边栏淡入）。配合仓库中已有的 OnboardingFlow 三阶段流程、PersonalizedSuggestions 起始提示机制、集成连接与凭据对话框、employee 队友聊天流等现成模块，落地路径清晰且大多有可复用的接线点。