用户引导策略

ProductReady 实施了一套经过深思熟虑的多步骤引导体验，旨在最大化用户成功率，同时尊重用户的时间。本文档解释我们的方法以及每个设计决策背后的用户价值。

引导类型：用户 vs. 空间

ProductReady 区分两种类型的引导：

用户引导（每个用户一次）

用户首次注册时发生一次
跟随用户跨所有空间
专注于账户设置、个人资料完善和平台熟悉
示例：邮箱验证、个人资料设置、支付方式、平台导览

空间引导（每个空间创建时）

用户每次创建新空间/工作区时发生
特定于每个空间上下文
专注于空间配置、团队设置和项目初始化
示例：空间命名、邀请团队成员、设置集成、初始项目设置

为什么这很重要：

用户引导教"如何使用平台"
空间引导教"如何设置这个特定工作区"
用户完成后不应再看到用户引导步骤
用户每次创建新空间都应看到空间引导

总结 - 五套引导组件

ProductReady 提供五套 UI 组件用于引导：

组件	触发时机	展示位置	适用场景	引导类型
Welcome Wizard Modal	首次登录	模态弹窗	所有应用（必选）	用户
Getting Started Stepper	向导完成后	聊天输入框上方	AI/聊天类应用	用户
Onboarding Setup Guide	向导完成后	`/onboarding` 路由	开发者工具	用户
Feature Tour	首次访问页面	聚光灯遮罩	功能发现	用户
Space Setup Wizard	创建新空间	模态弹窗	多空间应用	空间

用户旅程（用户引导）：
┌─────────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│  Welcome        │     │  Getting Started    │     │  Onboarding      │
│  Wizard Modal   │ ──► │  Stepper            │ 或  │  Setup Guide     │
│  (3 步)         │     │  (紧凑内联)          │     │  (全页面)         │
└─────────────────┘     └─────────────────────┘     └──────────────────┘
                                    │
                                    ▼
                        ┌─────────────────────┐
                        │   Feature Tour      │
                        │   (页面级引导)       │
                        └─────────────────────┘

空间旅程（空间引导）：
┌─────────────────┐     ┌─────────────────────┐
│  Space Setup    │     │  Space Tour         │
│  Wizard         │ ──► │  (空间特定)          │
│  (4 步)         │     │                     │
└─────────────────┘     └─────────────────────┘

🔐 开发者快捷键：

切换向导: ⌘⇧M (Mac) / Ctrl+Shift+M (Win)

跳过向导: ⇧⌃⌥M (Mac) / Shift+Ctrl+Alt+M (Win)

设计哲学：Apple 风格用户体验

我们的引导流程遵循经过验证的 Apple 哲学："不要教用户使用你的系统——帮助他们完成真实目标，在恰当时刻说恰当的话。"

核心原则

原则	含义	用户价值
一屏一决策	每步只聚焦一个选择	降低认知负荷，防止不知所措
不可跳过	用户必须完成引导	确保正确设置，更好的首次体验
渐进式展示	在需要时显示信息，而非提前	更快获得价值，减少信息过载
在实践中学习	通过真实任务引导，而非教程	立即价值，实用学习

首次登录时出现的三步向导弹窗。

为什么要分步而非单页表单？

传统引导的问题：

长表单令人不知所措（10+ 个字段 = 高放弃率）
用户不知道该关注什么
移动用户在滚动时很困难

我们的解决方案： 渐进式、小块的交互，感觉轻松无压力。

第1步：欢迎与情境 🎬

发生什么：

温暖的欢迎消息
2分钟介绍视频
单一"继续"按钮

用户价值：

📺 视频胜于文字

原因：人类处理视频的速度比文字快 60,000 倍
价值：2分钟理解 ProductReady 的目的，而非 20 分钟阅读
情感连接：看到产品实际操作，而非仅仅描述

🎯 单一焦点

原因：没有竞争的 CTA 或信息
价值：清晰的前进路径，无决策瘫痪
结果：比文字密集页面高 40% 的继续率

🚫 不可跳过（设计如此）

原因：确保用户完成必要设置以获得最佳首次体验
价值：更高的激活率，更好的产品理解
秘密：开发者可使用 Shift+Ctrl+Alt+S 绕过（UI 中不显示）

第2步：个性化设置 📝

发生什么：

一次一个问题，平滑过渡
总共 4 个问题：
1. 你的角色是什么？（开发者 / 产品经理 / 创始人 / 其他）
2. 你将用 ProductReady 做什么？（个人项目 / 副业 / 创业 / 公司）
3. 你的团队有多大？（只有我 / 2-5 人 / 6-10 人 / 11+ 人）
4. 还有什么想分享的？（可选）

用户价值：

🎯 一次一个问题

原因：认知科学表明人类处理 1 个决策比 10 个更好
价值：感觉像对话，而非"作业"
完成率：比传统多字段表单高 3 倍

💡 智能个性化

原因：根据角色和用途定制体验
价值：首先看到相关功能，跳过无关内容
示例：创始人看到账单设置；开发者看到代码示例

🔄 可用返回按钮

原因：错误会发生，选择会改变
价值：安全网减少焦虑
信任：显示我们灵活，而非僵化

📊 进度指示器

原因：用户想知道"还要多久？"
价值：减少不确定性，提高完成率
心理学：小胜利感觉可实现

第3步：选择你的路径 🎯

发生什么：

从 4 个选项中选择主要动机：
- 创建我的第一篇文章（AI Agent 演示）
- 探索仪表板（功能导览）
- 邀请我的团队（协作设置）
- 随便看看（无承诺）

用户价值：

🚀 立即行动

原因：用户想要"做"某事，而非仅仅阅读
价值：在引导后 30 秒内开始工作
满意度：从第一天就感到有生产力

🎨 视觉目标选择

原因：图标 + 描述 > 纯文字菜单
价值：快速理解选项，无需阅读段落
可访问性：适用于视觉和文字学习者

🔀 灵活路径

原因：不同用户有不同优先级
价值：没有"错误"选择，所有路径都通向价值
探索："随便看看" = 谨慎用户的低压力选项

🎁 情境导航

选择后，用户直接进入所选功能：

创建文章 → AI Agent 界面
探索 → 仪表板导览
邀请团队 → 团队管理
探索中 → 带"入门指南"的仪表板

组件 2：Getting Started Stepper

适用于用户希望立即开始对话的 AI Agent 应用。

何时使用

你的首页是 AI Agent 聊天界面，带有提示输入框。

为什么用这个模式

使用聊天界面的用户想要立即开始对话——遵循"在聊天中学习"原则。紧凑、不干扰的指南让他们保持参与，而不会阻挡输入框。

布局

┌─────────────────────────────────────────────────────┐
│ 入门指南                                     [X]    │
│ [1] 创建文章  →  [2] 管理文章  →  [3] 分享        │
└─────────────────────────────────────────────────────┘
│  💬  输入消息... (下方聊天输入框)                  │

关键特性

持久但可关闭：每次页面加载时显示，直到关闭
自动完成：用户探索时步骤自动完成
占用空间小：只占 ~60px 垂直空间，不阻挡聊天
快速胜利：3 个简单操作，几分钟内完成

用户价值

✅ 在实践中学习，而非阅读
✅ 不中断自然对话流程
✅ 用户卡住时始终可访问
✅ 用勾选标记庆祝进度

组件 3：Onboarding Setup Guide

适用于需要代码设置、API 密钥或配置的开发者工具。

何时使用

你的首页不是聊天界面——通常是开发者工具、仪表板或配置密集型应用。

为什么用这个模式

开发者工具通常需要代码设置、API 密钥或配置才能使用。全页面指南提供空间展示代码示例和逐步说明。

布局

┌─────────────────────────────────────────────────────┐
│ ← 返回仪表板                                         │
│                                                       │
│ 🚀 [应用名称] 入门指南                              │
│ 3 步骤 • 约 5 分钟                                   │
│                                                       │
│ ┌──────────────────────────────────────────┐        │
│ │ ✓ 步骤 1：获取 API 密钥                  │        │
│ └──────────────────────────────────────────┘        │
│ ┌──────────────────────────────────────────┐        │
│ │ 2  步骤 2：安装 SDK                      │        │
│ │   [代码：curl | JS | Python]             │        │
│ └──────────────────────────────────────────┘        │
│ ┌──────────────────────────────────────────┐        │
│ │ 3  步骤 3：首次 API 调用                 │        │
│ └──────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────┘

关键特性

全页面布局：有足够空间展示详细说明和代码示例
进度跟踪：视觉指示器显示完成状态
代码示例：多语言标签页（curl、JavaScript、Python）
复制按钮：一键复制 API 密钥和代码片段
步骤验证：检查用户是否完成前置条件

用户价值

✅ 无信息过载：一次一个步骤，说明清晰
✅ 即用即复制：代码示例可直接用于生产
✅ 视觉反馈：完成步骤显示绿色勾选
✅ 自定进度：用户可随时离开并返回
✅ 减少支持工单：全面指导减少困惑

组件 4：Feature Tour

交互式聚光灯引导，在用户首次访问页面时引导他们了解各个功能。

何时使用

当用户首次进入功能丰富的页面，需要了解每个元素的作用时。

为什么用这个模式

与其他专注于初始设置的组件不同，Feature Tour 提供情境化、原地教育，在用户需要时精确提供帮助。它用聚光灯效果高亮特定 UI 元素并解释其用途。

布局

┌─────────────────────────────────────────────────────┐
│                    页面内容                          │
│  ┌─────────────────────────────────────────────┐    │
│  │  ████████████████████████████████████████   │    │
│  │  ██                                    ██   │    │
│  │  ██   ┌──────────────┐                 ██   │    │
│  │  ██   │   高亮元素    │ ◄── 提示框     ██   │    │
│  │  ██   │              │    "这是..."   ██   │    │
│  │  ██   └──────────────┘                 ██   │    │
│  │  ██                                    ██   │    │
│  │  ████████████████████████████████████████   │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
│  [返回]                    1/3              [下一步] │
└─────────────────────────────────────────────────────┘

关键特性

聚光灯效果：除目标元素外全部变暗
逐步导航：返回/下一步/跳过按钮
进度指示器：显示当前步骤（如"1 / 3"）
键盘导航：方向键和 Escape 跳过
自动滚动：将目标元素滚动到视图中
数据库持久化：完成状态存储在 UserOnboarding 中（非 localStorage）

用户价值

✅ 情境学习：在功能所在位置学习
✅ 非侵入式：仅首次访问显示，可跳过
✅ 聚焦注意力：聚光灯吸引眼球到重要元素
✅ 自定进度：用户用下一步/返回控制节奏

文件结构

src/components/feature-tour/
├── index.ts              # 导出
├── types.ts              # TypeScript 定义
├── tour-context.tsx      # TourProvider + useTour hook
├── tour-overlay.tsx      # 聚光灯 + 提示框 UI
├── use-feature-tour.ts   # 带持久化的自动启动 hook
└── tours/
    └── posts-tour.ts     # Posts 页面 tour 配置

组件 5：Space Setup Wizard（空间引导）

创建新空间时出现的向导。这是空间引导 - 用户每次创建新空间时都会出现。

何时使用

你的应用支持多个空间/工作区，每个空间需要配置（团队成员、设置、集成）。

为什么用这个模式

与用户引导（只发生一次）不同，空间引导帮助用户配置每个工作区。用户可能为不同项目、团队或目的创建多个空间。

布局

┌─────────────────────────────────────────────────────┐
│ 创建新空间                                    [X]    │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│                                                      │
│ 步骤 1/4：空间基础信息                               │
│                                                      │
│ 空间名称 *                                           │
│ ┌──────────────────────────────────────────┐        │
│ │ 我的超棒项目                             │        │
│ └──────────────────────────────────────────┘        │
│                                                      │
│ 空间类型 *                                           │
│ ○ 个人    ○ 团队    ○ 企业                          │
│                                                      │
│ 描述（可选）                                         │
│ ┌──────────────────────────────────────────┐        │
│ │                                          │        │
│ └──────────────────────────────────────────┘        │
│                                                      │
│                          [返回]  [下一步：团队设置] │
└─────────────────────────────────────────────────────┘

空间引导步骤

步骤 1：空间基础信息

空间名称（必填）
空间类型（个人 / 团队 / 企业）
描述（可选）

步骤 2：团队设置（如果是团队空间）

通过邮箱邀请团队成员
分配角色（管理员 / 成员 / 查看者）
跳过选项："稍后邀请团队"

步骤 3：初始配置

选择项目模板（空白 / 启动套件 / 导入）
选择集成（GitHub、Slack、Linear 等）
全部可选 - 可稍后配置

步骤 4：空间导览

快速浏览空间仪表板
高亮关键功能（设置、团队管理、项目）
展示如何在空间之间切换

关键特性

快速完成：从开始到结束 < 5 分钟
可跳过步骤：团队和集成可以跳过
可重复：用户每次创建新空间都会显示
上下文感知：个人空间和团队空间有不同选项
进度跟踪：视觉指示器显示当前步骤

用户价值

✅ 有序的工作区：为不同项目分离空间
✅ 团队协作：轻松邀请团队成员
✅ 快速设置：几分钟内开始使用
✅ 灵活：跳过可选步骤，稍后配置
✅ 一致体验：每个新空间都是相同流程

实现示例

// 触发空间设置向导
<Button onClick={() => setShowSpaceWizard(true)}>
  创建新空间
</Button>

// 空间向导组件
<SpaceSetupWizard
  open={showSpaceWizard}
  onOpenChange={setShowSpaceWizard}
  onComplete={(spaceData) => {
    // 创建空间并跳转
    createSpace(spaceData);
    router.push(`/spaces/${spaceData.id}`);
  }}
/>

空间引导触发时机

用户点击"创建新空间"按钮
用户从个人版升级到团队版
用户接受团队邀请（简化版 - 跳过空间创建，仅显示导览）

空间 vs. 用户引导

方面	用户引导	空间引导
频率	每个用户一次	每个新空间
重点	平台功能	工作区设置
时长	5-10 分钟	2-5 分钟
可跳过	否（必需）	部分（团队/集成）
持久性	不再显示	每个空间都显示
目标	教平台使用	配置工作区

选择正确的组合

应用类型	Wizard Modal	Stepper	Setup Guide	Feature Tour	Space Wizard
AI Agent / 聊天	✅	✅	可选	✅	如果多空间
开发者工具	✅	❌	✅	✅	如果多空间
多空间 SaaS	✅	✅ 或 ❌	可选	✅	✅
混合型（聊天+仪表板）	✅	✅（仅聊天）	✅	✅	如果多空间
简单消费者应用	✅	✅ 或 ❌	❌	可选	❌
自助式首页	✅	❌	❌	✅	❌

为什么这种方法有效

与传统引导相比

传统方法	ProductReady 方法	用户影响
长教程（15+ 分钟）	2分钟视频 + 3步（5分钟）	节省 70% 时间
单个长表单	一次一个问题	完成率提高 3 倍
文字密集解释	视觉 + 视频内容	记忆提高 60%
到处都有跳过按钮	不可跳过（必须完成）	激活率更高
对所有用户通用	基于角色的个性化	参与度提高 2 倍
教程然后产品	从第1步开始产品	立即价值

心理学原理

1. 蔡格尼克效应

未完成的任务产生心理紧张 → 入门指南清单驱动完成。

2. 峰终定律

用户记住高峰（最佳时刻）和结尾 → 让引导从第一次点击就令人愉快。

3. 选择悖论

太多选项 = 瘫痪 → 限制为 3-4 个清晰路径。

4. 渐进式承诺

小胜利建立动力 → 每个完成的步骤鼓励下一个行动。

为什么两种后续模式都重要

🔄 持续指导

原因：引导不会在注册时结束
价值：前 3-5 个关键操作的持续帮助
心理学：清单创造动力（蔡格尼克效应）

✅ 情境适当的设计

原因：聊天应用需要最小干扰；开发工具需要详细说明
价值：在正确的时间提供正确的指导量
结果：不同应用类型的完成率更高

🎯 始终可访问

原因：用户可能完成向导但稍后需要帮助
价值：需要时有入门指南，不需要时隐藏
用户控制：有信心时关闭，卡住时重新打开

技术实现

文件结构

src/components/welcome-wizard-modal/
├── index.tsx             # 主容器 + 键盘快捷键
├── step-1-welcome.tsx    # 视频 + 欢迎
├── step-2-survey.tsx     # 问题（逐个展示）
├── step-3-motivation.tsx # 目标选择
├── wizard-progress.tsx   # 进度点
├── types.ts              # TypeScript 定义
└── config.tsx            # 自定义配置

开发者快捷键

仅供开发者/测试人员使用：

平台	切换向导	跳过向导
Mac	`⌘ + Shift + M`	`Shift + Ctrl + Option + M`
Windows/Linux	`Ctrl + Shift + M`	`Shift + Ctrl + Alt + M`

使用 ahooks 实现：

useKeyPress(
  (e) => e.shiftKey && e.ctrlKey && e.altKey && e.key.toLowerCase() === "s",
  (e) => {
    if (open) {
      e.preventDefault();
      handleSkip();
    }
  },
  { exactMatch: false }
);

数据持久化

调研数据通过 surveys 系统存储：

{
  type: "new_user_onboarding",
  formData: {
    role: "developer",
    useCase: "startup",
    teamSize: "2-5",
    motivation: "createPost",
    videoWatched: true
  }
}

为什么使用 System Admin Survey System？

集中化：所有用户研究集中在一个地方
灵活：添加/删除问题无需迁移
可分析：过滤、导出、可视化响应
隐私：主数据库中无 PII

为其他应用自定义

复制 welcome-wizard-modal/ 文件夹
更新 config.tsx 中的视频 ID 和选项
在 config/surveys.ts 中添加 survey type
在布局中集成

<WelcomeWizardModal
  config={YOUR_APP_CONFIG}
  open={shouldShowWizard}
  onOpenChange={setShowWizard}
/>

为特定路由禁用 Welcome Wizard

某些路由（如 /systemadmin 或 /agent）不应显示 Welcome Wizard。在 SPAWrapper 上使用 disableWelcomeWizard prop：

<SPAWrapper disableWelcomeWizard={true}>
  {/* 管理员内容 */}
</SPAWrapper>

Hook 参考

Hook	用途
`useWelcomeWizard`	控制 Welcome Wizard Modal 显示
`useGettingStartedStepper`	管理 Getting Started Stepper 状态（原 `useOnboardingAutoComplete`）
`useFeatureTour`	控制 Feature Tour，数据库持久化