# 新用户首次 Agent 对话 Onboarding Proposal > Canonical path: `specs/product/proposals/onboarding.md` > Status: proposal > Scope: AgentTeam 新用户首次 Agent 对话 onboard 的产品范围与用户路径。 ## 目标 AgentTeam onboard 要让一个从官网进入的新用户，通过 AgentTeam Desktop 在三分钟内拥有至少一个可运行 Agent，并完成至少一次和 Agent 的频道对话。 这里的三分钟是产品设计目标，不是服务端、Desktop 或模型响应 SLA。默认衡量口径是：用户安装并登录 AgentTeam Desktop、进入一个可访问的 Workspace 后，从首次使用路径开始，到用户在 channel 中看到第一条 Agent 回复。 首次使用路径必须足够窄：官网首页主入口引导用户下载 AgentTeam Desktop；用户在 Desktop 内注册或登录后进入 `Quick Start`，创建第一个 Agent，创建请求同时把 Agent 作为成员加入频道；系统用普通持久化消息和 thread mention 演示一次完整 Agent 对话，延迟数秒后由该 Agent 身份返回预置的本地化回复和 `index.html`，用户看到回复后 onboard 完成。默认示例交互不触发 Agent runtime，避免首次体验受模型速度、稳定性或生成质量影响；完成后的追问和其他普通消息继续走真实 Agent 投递。用户不需要在创建后手动处理频道成员关系。如果用户的 `Quick Start` 中已经有可运行 Agent，则跳过创建，直接引导完成第一次 Agent 对话。Web 端不是 Quick Start tutorial 的执行环境；用户在任意 channel 完成第一次真实 Agent 对话，也视为 onboard 完成。 ## 关键变化 本 proposal 相比现有首次使用体验，关键变化是： - 新增 `Quick Start` 作为未完成 onboard 用户的默认引导频道。它是带有 `subsystem=tutorial` 标记的真实频道，不是新的 channel 类型或独立教程页；特殊性只体现在 Desktop 首次使用时的空态、主动作、输入框引导和聚焦交互。 - 官网首页主 CTA 指向 AgentTeam Desktop 下载页。Web 登录入口只作为弱入口保留，不启动 Quick Start tutorial。 - 第一个 Agent 创建路径收窄为最短表单：用户默认只需要确认或填写 Agent 名称，角色可选。 - 从 `Quick Start` 创建 Agent 时，创建请求自动把 Agent 作为成员加入该频道。创建前后的 UI 都应让用户明确知道这一点，不再提供额外的手动加入步骤。 - Web 端不创建 `Quick Start` / tutorial channel。未完成状态下的 Web direct link 只显示 Desktop 引导阻断页；完成后它可以作为普通频道呈现，但设置入口仍隐藏。 - Agent 创建使用 AgentTeam 默认 runtime、默认模型 `deepseek-v4-flash` 和推荐运行配置。 - 首次 onboard 赠送 300 `agentteam_credit`，按当前 hosted credits 价格约等于人民币 3 元（CNY 3.00），让用户不需要先理解 billing 或 quota。 - Desktop 自动准备 Machine 是减少首次创建步骤的前置依赖。如果目标用户使用的 Desktop 版本还不支持该能力，需要配套发版或升级引导。 - Onboard 完成标准从“进入产品”收窄为“用户在任意 channel 中完成至少一次 Agent 对话，并看到 Agent 回复”。 - `Quick Start` 的默认示例对话使用 onboarding 域拥有的预置交换：消息、mention、回复和附件都按普通会话数据持久化并实时展示，但示例 prompt 与 thread request 不进入 Agent 投递；预置回复按当前界面语言提供简体中文、英语或日语版本。该交换结束后的消息恢复普通 Agent 行为。 ## 范围 三分钟 onboard 只覆盖“在频道里完成第一次成功的 Agent 对话”。 范围内： - 一个名为 `Quick Start` 的默认引导频道。 - 对没有可运行 Agent 的用户，提供一个聚焦入口，引导用户创建第一个 Agent。 - 使用推荐默认值的最短 Agent 创建路径。 - 标准路径将新创建的 Agent 加入 `Quick Start`。 - 在 `Quick Start` 里分阶段保存示例需求、打开 thread、保存 `@Agent` reply，并在短暂延迟后保存该 Agent 身份的预置结果；如果用户先在其他 channel 完成真实 Agent 对话，也算完成。 - 在发起对话的 channel 中展示 Agent 的第一条回复。 - 用户拥有至少一个可运行 Agent，并在任意 channel 完成至少一次 Agent 对话后结束 onboard。 范围外： - 注册、登录和身份验证流程重做。 - 默认 Workspace 创建逻辑。 - Workspace 选择器重做。 - 邀请和 pending invite 流程重做。 - 完整产品教程。 - Agent Team 设置。 - Task onboard。 - 权限教育和 Workspace 治理。 - 除直接阻塞提示外的 billing、购买和 quota 教育。 - 长任务架构或模型上下文窗口教育。 - 全局空状态重做。 - Web 端执行 Quick Start tutorial。 ## 产品前置边界 Onboard 的起点不是“获得 Workspace access”，而是“用户已经在 AgentTeam Desktop 中被带入一个可访问的 Workspace”。 - 用户已经安装并打开 AgentTeam Desktop。 - 用户已经在 Desktop 内完成必要的注册、登录和身份验证流程。 - AgentTeam 已经打开一个可访问的 Workspace；对普通首次注册用户，这由默认 Workspace bootstrap 自动满足。 - 默认 Workspace bootstrap 已经确保基础聊天入口存在。 - 如果用户停留在邀请接受、pending invite、Workspace 选择、Workspace 不可访问或 bootstrap 错误恢复中，不进入三分钟 onboard；这些前置流程负责先把用户带到 Workspace。 ## 默认用户路径 1. 用户从官网首页点击主 CTA，进入下载页并下载 AgentTeam Desktop。Web 登录入口只作为弱入口保留。 2. 用户打开 AgentTeam Desktop，在 Desktop 内注册或登录。 3. Desktop 进入可访问 Workspace。如果用户尚未完成 onboard，且本次进入没有明确目标页面，Desktop 打开 `Quick Start`。 4. `Quick Start` 的第一屏不展示普通空频道文案，而是展示一个明确主动作：创建第一个 Agent。 5. 用户点击创建入口，进入最短 Agent 创建表单。表单使用推荐默认值，用户只需要确认必要信息。 6. 如果当前环境缺少让 Agent 可运行的必要条件，创建流程停在一个明确的恢复动作上；用户完成恢复后继续创建。常见阻塞包括试用 credit 不可用，或用户当前 Desktop 版本还没有自动准备 Machine 的能力。 7. Agent 创建成功后，用户仍停留在 `Quick Start`。该 Agent 已经作为成员自动加入频道；消息流出现普通 channel member event，明确 Agent 已加入频道。 8. Agent 可运行且 mention hint 准备好后，系统在 `Quick Start` 主频道保存真实用户消息形式的示例需求。消息发送成功并显示后停留约一秒。该 onboarding 专用写入保留普通浏览器消息投影，但不创建 Agent recipients 或 wake 投递。 9. Desktop 打开该消息对应的 thread，并在 thread 中保存真实用户 reply，内容提及刚创建的 Agent。mention 元数据按普通消息规则持久化，但该 onboarding 专用写入同样不触发 Agent runtime。 10. Desktop 等待数秒后请求服务端以该 Agent 身份保存当前界面语言对应的预置回复，并附上同语言的自包含 `index.html`。预置回复保存成功即结束 onboard；Desktop 在展示回复约一秒后播放一次短暂纸片礼花和完成提示。 11. 结束后，`Quick Start` 继续作为普通频道存在；用户可以继续提问，也可以离开去其他频道工作。 ## UX 草图 以下草图展示默认路径，不表示 onboard 只能在 `Quick Start` 完成。草图只表达信息架构、状态和主动作，不规定具体组件实现。 首次进入 `Quick Start`： ```text +------------------+--------------------------------------------------+ | Channels | # Quick Start | +------------------+--------------------------------------------------+ | > Quick Start | | | all | Create your first Agent | | | Create one Agent, then ask it a question here. | | | | | | [ Create Agent ] | | | | | +--------------------------------------------------+ | | Message... | +------------------+--------------------------------------------------+ ``` 进入现有创建 Agent 界面： ```text +------------------------------------------+ | Create Agent | |------------------------------------------| | Name | | [ assistant ] | | Only this field may need user input. | | | | Role | | [ Optional role v ] | | Optional. | | | | Defaults | | Default runtime set by AgentTeam. | | Model: deepseek-v4-flash. | | Machine prepared by Desktop. | | | | Advanced settings | | | | [ Cancel ] [ Create ] | +------------------------------------------+ ``` 默认情况下，用户只需要确认或填写 Agent 名称；Agent 角色可选。runtime 使用 AgentTeam 默认 runtime，模型默认使用 `deepseek-v4-flash`，初始运行资源使用推荐配置。Desktop 环境中，Machine 由 Desktop 安装并登录后自动准备，创建 Agent 时作为默认运行位置。 Agent 创建成功后回到 `Quick Start`： ```text +------------------+--------------------------------------------------+ | Channels | # Quick Start | +------------------+--------------------------------------------------+ | > Quick Start | [system] assistant joined this channel. | | all | | | | huohao | | | Build a static browser game... | | | | | +--------------------------------------------------+ | | Message... | +------------------+--------------------------------------------------+ ``` 图中的示例需求是系统替当前人类用户保存的真实频道消息，不写入特殊 tutorial 消息模型。该消息显示后，Desktop 再打开 thread；带 mentions 的 `@Agent` reply 与 Agent 身份回复也都是普通持久化消息。特殊行为只属于 active onboarding 状态下的这一组专用写入：Human 消息没有 Agent 投递，Agent 回复直接使用内置的本地化 Markdown 和 HTML 资源。服务端必须校验当前用户、Workspace、tutorial channel、thread、Agent 和 origin message 的精确关系，且重试不得重复创建可见消息。 收到第一条 Agent 回复： ```text +------------------+--------------------------------------------------+ | Channels | # Quick Start | +------------------+--------------------------------------------------+ | > Quick Start | huohao | | all | Build a static browser game... | | | | | | assistant | | | I created the game. Open index.html... | | | | | | [ Ask more ] | | +--------------------------------------------------+ | | Message... | +------------------+--------------------------------------------------+ ``` ## 行为规则 ### 快速上手频道 快速上手频道是真实频道，不是独立教程页。服务端创建频道时将内部显示名固定写为 `quick start`。频道列表和频道顶部不直接展示该持久化值，而是根据当前界面语言显示：英语为 `Quick Start`，简体中文为“快速上手”，日语为“クイックスタート”。切换界面语言会立即改变这两处展示，不修改数据库中的频道名。引导标题、说明、按钮和状态等其他 UI 文案继续按当前语言本地化；简体中文引导文案使用“智能体”和“积分”，不混用英文 `Agent` 或 `credits`。 每个用户在 Workspace 中拥有一个私有的快速上手频道，服务端用 `subsystem=tutorial` 标记它。该标记用于稳定识别教程频道，不依赖创建时写入的本地化显示名称。 Desktop 只有在当前服务端启用 Billing，且通过 public config 明确声明支持快速上手时，才允许启动快速上手流程。`billingEnabled` 或 `desktopQuickStartEnabled` 缺失、值不为 `true`，或 public config 无法读取时，Desktop 必须在任何 bootstrap 写操作和自动跳转发生前禁用该流程，并按普通 Workspace 的默认落点继续。服务端在 Billing 关闭时不得创建或恢复快速上手状态。 Desktop 版本还必须通过客户端内置的 release gate 显式启用快速上手。服务端后续开启 capability 不能绕过该 gate 为旧客户端开启此功能；每个发布版必须由客户端自身选择是否参与。 参与快速上手的 Desktop release 还必须在客户端内置注册时间 cutoff，并在 Desktop 注册、Desktop OIDC 回调和 tutorial bootstrap 请求中显式携带该值。当前 release 的 cutoff 为 `2026-08-09T00:00:00Z`；只有服务端记录的用户 `created_at` 严格晚于该时间，才允许准备试用额度或创建、恢复快速上手状态。认证响应和 `/api/v1/me` 必须返回该用户的 `createdAt`，Desktop renderer 在调用 tutorial bootstrap 或自动跳转前先与客户端内置 cutoff 比较；`createdAt` 缺失、格式无效或不晚于 cutoff 时必须 fail closed。服务端仍须在注册、OIDC 和 bootstrap 写操作处重复校验，防止旧客户端或直接请求绕过客户端判断。两侧都使用认证流程或认证中间件已经加载的用户注册时间，不得为 gating 增加额外的用户查询。 普通 Workspace 的默认频道落点不得选择 `subsystem=tutorial` 或 `tutorial=true` 的遗留快速上手频道。只有已通过上述 gating 且仍处于 active 状态的 Desktop onboarding owner 可以主动进入该频道；显式打开频道的链接不受默认落点规则影响。 它在消息历史、成员关系、mention、已读状态和后续复用上都应表现为普通频道。唯一的投递例外是默认示例交换：onboarding 域在 active tutorial 状态下保存无 Agent recipients 的 Human transcript，并保存一条预置 Agent reply；通用消息 API 不提供跳过 Agent 投递的客户端开关。该交换结束后的追问与普通频道消息必须恢复真实 Agent 投递。它的首次使用呈现可以比普通频道更有引导性，但用户应该通过正常频道交互学习 AgentTeam 的核心心智。 该频道不负责讲完整产品，只负责让第一次成功的 Agent 对话快速发生。 Onboard 结束后，`Quick Start` 继续作为普通频道存在。未完成时它只在 Desktop 中可见，Web 的频道列表不展示它；完成后 Web 和 Desktop 都恢复它的普通频道能力，但必须继续隐藏“设置”tab，防止用户修改频道名。用户已经在任意 channel 中完成一次 Agent 对话后，首次使用引导不应继续主导这个页面。 在 Desktop 的 onboard 未完成状态下，用户进入自己的 `Quick Start` 后，引导内容在频道内容区水平和垂直居中展示。只有当前作为 `Quick Start` 有效成员的 Agent 才参与可运行状态判断；Workspace 中其他 Agent 不改变该频道的引导状态。Agent 可运行前不展示普通空频道文案，消息输入保持可见但处于禁用状态；Agent 可运行后输入恢复可用，系统分阶段保存示例需求、打开 thread、保存提及 Agent 的 Human reply，并在数秒后保存预置 Agent reply。频道成员管理、分享、定时消息、频道次级页签和频道右侧栏等频道内入口暂时隐藏。Workspace 导航、全局搜索、Machine 状态、账户菜单、退出登录和其他应用级操作始终可用。该聚焦状态不改变明确 deep link 的落点；onboard 完成后立即恢复普通频道操作。 Web 端不启动、创建或恢复 Quick Start tutorial。创建 tutorial channel 的服务端入口是 `POST /api/v1/workspaces/:workspaceId/onboarding/bootstrap`，前端只允许 Desktop onboarding provider 调用它。Browser runtime 如果通过旧链接、历史恢复、手动拼 URL 或客服调试链接打开未完成的 `subsystem=tutorial` channel，必须 hard block：不展示 Quick Start guide，不自动发送示例 prompt，不打开 Agent thread，也不调用 bootstrap。阻断页只引导用户下载或打开 AgentTeam Desktop，并提供返回普通工作区入口。 ### 自动打开规则 如果用户尚未完成 onboard，且用户是自然打开 AgentTeam Desktop 或 Desktop Workspace，默认打开 `Quick Start`。 自然打开指用户不是通过邀请链接、通知链接、分享链接或具体页面 URL 进入。如果用户尚未完成 onboard，但本次进入已经指向明确目标，AgentTeam Desktop 打开该目标页面，不跳转到 `Quick Start`。 如果用户已经完成 onboard，AgentTeam 使用正常默认落点逻辑，不再因为 onboard 自动打开 `Quick Start`。 Onboard 完成指：用户拥有至少一个可运行 Agent，并满足以下任一条件：服务端在 `Quick Start` 中保存了与当前 active tutorial 精确绑定的预置 Agent 回复；或用户在任意普通 channel 中发送包含 `@Agent` 的消息并看到该 Agent 的真实回复。预置交换在回复保存成功时直接完成；真实 Agent 对话仍只有在服务端记录了合格回复，且 mounted channel UI 的可见范围与权威已读游标都覆盖该回复后才完成。 ### 第一个 Agent 创建 对没有可运行 Agent 的用户，第一个 Agent 创建路径应该足够短，用户无需理解完整 Agent 模型也能完成。 Onboard 不定义新的 Agent 创建 dialog。它应复用 AgentTeam 现有 Agent 创建能力，只通过入口、推荐默认值和创建成功后的频道回落来服务三分钟路径。 从 `Quick Start` 发起创建时，创建请求必须携带该频道作为初始 channel membership，使新 Agent 在创建事务中自动加入 `Quick Start`。UI 在创建操作前应说明 Agent 会自动加入当前频道，创建成功后应确认 Agent 已加入并可直接被 mention。用户不需要再打开成员管理或执行一次额外的加入操作。 在 Desktop 环境中，用户不需要先手动创建 Machine，也不需要在首次 Agent 创建路径中选择 Machine。 Desktop 安装并登录后，会自动为当前电脑准备 Machine。创建第一个 Agent 时，AgentTeam 使用这台 Machine 作为默认运行位置。 Machine 自动准备属于 Desktop 安装与连接体验，不作为三分钟 onboard 主路径中的用户步骤。 ### 赠送 credit 与默认配置 为了让新用户在三分钟内完成第一次 Agent 对话，AgentTeam 应为首次 onboard 赠送 300 `agentteam_credit` 的试用 credit。按当前 hosted credits 价格 `100 agentteam_credit = CNY 1.00` 折算，这笔赠送约等于人民币 3 元（CNY 3.00）。 赠送 credit 只属于启用本流程且通过注册时间 cutoff 的 Desktop release。Desktop 注册请求必须显式声明当前客户端已启用 onboarding，并携带客户端内置的 cutoff；只有新建用户的服务端注册时间严格晚于该 cutoff，服务端才准备默认 hosted 模型 entitlement 并赠送 300 `agentteam_credit`。release opt-in 或 cutoff 缺失、值无效，或注册时间未通过时不得赠送。因此服务端发布不能为关闭 onboarding 的当前或旧 Desktop 客户端、Web 注册用户意外发放试用 credit。启用流程的新 Desktop release 必须同时开启客户端 onboarding gate、注册 opt-in 和对应 cutoff。 赠送 credit 的产品要求是：新用户在第一次创建 Agent 和发送第一条 `@Agent` 消息前，不应该被要求先完成充值、购买套餐或手动配置 quota。 当试用 credit 可用时，第一个 Agent 创建表单只要求用户确认 Agent 名称；Agent 角色可以作为可选项出现。runtime 使用 AgentTeam 默认 runtime，模型默认使用 `deepseek-v4-flash`，初始运行资源使用推荐配置。Desktop 环境中的 Machine 使用 Desktop 自动准备的默认运行位置，不出现在最短表单的必填项中。 试用准备必须同时建立 300 `agentteam_credit` 余额和默认 hosted 模型 entitlement。两者是独立的 billing 状态；只有余额和 entitlement 都可用时，`deepseek-v4-flash` 才能作为默认模型出现在最短创建路径中。Desktop 包内的内置 OpenCode runtime 是该路径的默认 runtime，不要求用户安装或选择外部 OpenCode。 如果试用 credit 不可用，onboard 应停在一个明确的恢复动作上，避免让用户在创建 Agent 前先理解完整 billing、quota 或运行资源模型。 本 proposal 定义首次 onboard 的赠送面额；有效期、账本写入、幂等性和滥用控制需要由 SaaS 或 Billing 规范承接。 创建界面应优先展示： - Agent 名称，并提供合理默认值。 - 可选的 Agent 角色。 - AgentTeam 默认 runtime。 - 默认模型 `deepseek-v4-flash`。 - 高级设置放在次级入口。 如果 Agent 因 credit、runtime 或模型配置暂时无法运行，onboard 应停在一个明确的恢复动作上。用户不应该在解决阻塞时被迫在多个无关产品区域之间选择。 ### 第一条消息 默认引导的第一条消息应该发生在 `Quick Start`，而不是 Agent DM。 产品应替用户发送一个具体、可见、真实的示例需求。示例需求应该像真实工作请求，而不是内部测试说明；它应该要求 Agent 生成一个无需安装依赖、无需远程资源、由单个自包含 `index.html` 构成的静态网页小游戏。为了让用户理解 thread 心智，频道主消息发送成功后应短暂停留，再打开该消息的 thread，并在 thread reply 中 `@Agent` 请求实现。 完成后，Agent 必须通过正常话题消息附件链路把 `index.html` 发送到当前 thread，使用户可以直接在 AgentTeam 的 HTML 附件预览中查看和试玩结果。引导指令不得要求 Agent 启动系统浏览器，也不得把本地绝对路径作为唯一交付物；同一条回复应包含简短的完成说明。 示例主消息发送、thread 打开或 mention reply 发送都不代表 onboard 完成，创建 Agent 也不代表 onboard 完成。只有被 mention 的同一个 Agent 产生关联的可见回复，并且用户在可见的频道或 thread 界面中实际看到该回复，才算完成。如果用户自行在其他 channel 中完成第一次 Agent 对话，也算 onboard 完成。 ### 状态分流 Onboard 只根据两个产品状态分流：用户的 `Quick Start` 是否有可运行 Agent，以及用户是否已经在任意 channel 中完成过 Agent 对话。 - 如果用户的 `Quick Start` 没有可运行 Agent，onboard 引导用户创建一个 Agent 并将其加入该频道。 - 如果用户的 `Quick Start` 已经有可运行 Agent，但还没有完成 Agent 对话，onboard 跳过 Agent 创建，引导用户在 `Quick Start` 使用该 Agent。 - 如果用户已经在任意 channel 中完成 Agent 对话，首次使用 onboard 路径应该退场。 通过 `Quick Start` 创建并加入该频道的 Agent 会改变“频道中是否有可运行 Agent”的分流状态；通过普通入口创建但未加入 `Quick Start` 的 Agent 不改变该状态。创建 Agent 不会结束 onboard，也不会停止后续自然打开 Desktop 时自动进入 `Quick Start`。只有用户看到一次合格的 Agent channel 回复后，自动进入规则才永久退场。 ## 发布边界 本 proposal 的主范围是 AgentTeam 首次使用 onboarding，但落地前需要确认目标用户使用的 Desktop 版本已经具备自动准备 Machine 的能力。 如果目标 Desktop 版本尚未包含该能力，需要在 onboard 优化落地前配套发版或引导用户升级 Desktop。如果不处理这个版本缺口，用户仍可能在第一次创建 Agent 时看到创建或选择 Machine 的步骤，三分钟路径会被破坏。如果目标 Desktop 版本已经包含该能力，则不需要额外 Desktop 发版。 Desktop 相关依赖只覆盖减少首次创建 Agent 时的 Machine 步骤：Desktop 安装并登录后自动准备当前电脑的 Machine，AgentTeam 创建第一个 Agent 时使用该 Machine 作为默认运行位置，不要求用户手动创建或选择 Machine。 本 proposal 不重做 Desktop 安装、登录、连接状态管理或完整 Machine 管理体验；这些能力只作为首次 Agent 创建路径的前置支持。 ## 产品理由 三分钟路径优化的是第一次成功，而不是完整产品理解。 把频道作为第一个工作现场，能让用户直接理解 AgentTeam 的核心协作模型：人和 Agent 在共享上下文里一起工作。Agent DM 可以保留为兜底或后续工作流，但不是 onboard 主目的地。 `Quick Start` 给首次使用体验一个可以更明确引导的位置，同时不改变普通工作频道的行为。 ## 相关规范 - [AgentTeam Product Overview](../overview.md) - [Collaboration](../../collaboration/collaboration.md) - [Agent Read Model API](../../agent/read-model-api.md) - [Hosted Credits Payment Flow](../../billing/hosted-credits-payment.md) - [Hosted Model Onboarding](../../billing/hosted-model-onboarding.md) - [Daemon](../../daemon/daemon.md)