企业官网建设流程全解析

• 人工智能
• AI 应用
• AI Agent
• 交互助手
• MCP Clients
• 本地部署

本文基于 CodePilot 仓库中的 助理体验升级设计方案 展开。该方案旨在让 AI 助理从"侧栏里的一个灰色项目"变成"有名字、有头像、有存在感的个人 AI"。读完本文，你将掌握：如何用确定性 Identicon 生成助理头像、如何用三步 Onboarding Wizard 取代 AI 对话式引导、如何设计记忆驱动的 Quick Actions，以及这些设计在 CodePilot 源码中的实际落点。

一、设计目标与总体思路

CodePilot 是一个基于 Electron + Next.js 的多模型 AI Agent 桌面客户端，支持连接任意 AI Provider，并通过 MCP 与 Skills 扩展能力。其"个人助理"（Assistant Workspace）功能为每个用户维护一个常驻的 AI 工作区，包含soul.md（助理人格）、user.md（用户档案）、claude.md（执行规则）、memory.md（长期记忆）、HEARTBEAT.md（心跳检查清单）等核心文件。

原文档开宗明义地指出本次升级的核心目标：让助理从"侧栏里的一个灰色项目"变成"有名字、有头像、有存在感的个人 AI"。围绕这一目标，方案拆分为四大板块：

1. 视觉与人格化：确定性 Identicon 头像 + 侧栏助理项目重设计 + 聊天窗口主题色同步；
2. 文件树与状态面板：助理专属右侧状态面板或文件树状态图标；
3. 用户引导策略：新用户空状态双入口 + 老用户非侵入卡片 + 配置完成后 welcome card；
4. Onboarding Wizard：三步前端向导，彻底取代 AI 对话式 onboarding；
5. 记忆驱动的 Quick Actions：基于日常记忆与目标文件的预设问题芯片。

下文将逐一展开，并结合仓库源码给出实现层面的印证。

二、视觉与人格化：确定性 Identicon 头像

2.1 头像生成方案

方案要求：用助理名字 hash 确定性生成头像（同名字同头像），采用与 CodePilot 设计系统一致的 OKLCH 色彩空间，纯前端渲染、不依赖外部服务。

原文档给出了三条可选路线：@dicebear/core+@dicebear/collection（多风格、支持 SVG）、jdenticon（几何 identicon，轻量）、自建 Murmur3 hash 算法（类似 Vercel Pixel Sprite）。

从仓库源码看，最终实现采用了boring-avatars方案，落点为 src/lib/identicon.ts：

/** * Deterministic avatar generation using boring-avatars. * Same name always produces the same avatar. */ /** * Color palette for assistant avatars. * Derived from CodePilot's OKLCH primary color family. */ export const AVATAR_COLORS = [ '#6C5CE7', // purple-blue (primary) '#A29BFE', // light purple '#74B9FF', // sky blue '#55EFC4', // mint '#FFEAA7', // warm yellow ]; /** * Available avatar variants from boring-avatars. * 'beam' is the default — clean, geometric, friendly. */ export type AvatarVariant = 'marble' | 'beam' | 'pixel' | 'sunset' | 'ring' | 'bauhaus'; export const DEFAULT_VARIANT: AvatarVariant = 'beam';

要点解读：

• 确定性：boring-avatars 以name为输入做确定性渲染，同名必得同头像，满足"同名字同头像"的核心诉求；
• 色彩系统一致：AVATAR_COLORS直接从 CodePilot 的 OKLCH 主色家族（primary 紫蓝#6C5CE7）派生，保证头像与整个设计系统视觉统一；
• 变体可选：默认beam风格（干净、几何、友好），同时提供marble、pixel、sunset、ring、bauhaus五种备选，便于按需切换；
• 零外部依赖：纯前端渲染，不需要外部图片服务。

2.2 头像组件封装

仓库中已将头像封装为可复用组件 src/components/ui/AssistantAvatar.tsx，它在 boring-avatars 基础上进一步扩展了"Buddy"（电子宠物系统）能力：

export function AssistantAvatar({ name, size = 32, variant = DEFAULT_VARIANT, buddySpecies, buddyRarity, buddyEmoji, className, }: AssistantAvatarProps) { // If buddy data provided, use species-specific variant and rarity colors let finalVariant = variant; let finalColors = AVATAR_COLORS; if (buddySpecies) { finalVariant = SPECIES_AVATAR_VARIANT[buddySpecies as Species] || variant; if (buddyRarity) { finalColors = RARITY_AVATAR_COLORS[buddyRarity as Rarity] || AVATAR_COLORS; } } return ( <div className={cn('shrink-0 relative', className)} aria-label={`Avatar for ${name}`}> <Avatar size={size} name={name || 'assistant'} variant={finalVariant} colors={finalColors} /> {/* Emoji overlay for buddy */} {buddyEmoji && size >= 24 && ( <span className="absolute -bottom-0.5 -right-0.5 leading-none" style={{ fontSize: Math.max(10, size * 0.4) }}> {buddyEmoji} </span> )} </div> ); }

组件默认尺寸 32px，支持size自定义；当传入buddySpecies/buddyRarity时，会切换到物种对应的变体与稀有度配色，并叠加 emoji 角标，实现"宠物化"的趣味表达。头像的可访问性也已考虑（aria-label="Avatar for {name}"）。

2.3 头像显示位置

原文档明确头像应出现在三个位置：侧栏助理项目（替代文件夹图标）、聊天消息（AI 回复旁）、设置页。这套位置约定保证了助理在任何入口都有统一的视觉识别。

三、侧栏助理项目重设计

3.1 现状与目标形态

原文档给出了重设计前后的对比。当前侧栏中助理项目与普通项目无异，仅靠右侧小字"助理"标识：

📁 /path/to/workspace [助理] ← 灰色，和普通项目一样，右侧小字"助理"

目标形态是带头像、带名字、带状态行的专属卡片：

┌─────────────────────────────────┐ │ 🤖 小助 │ ← 头像 + 助理名字（或"个人助理"） │ ○ 上次心跳：2h前 · 记忆 23 条 │ ← 状态行 │ /path/to/workspace │ ← 路径（小字灰色） └─────────────────────────────────┘

3.2 关键设计决策表

原文档用一张决策表固化关键决策，必须完整继承：

设计要点：

• 名字来源：优先读取soul.md中定义的助理名字，未设置时回退为"个人助理"，这与仓库中OnboardingWizard默认名（wizard.defaultFallbackName/wizard.defaultAssistantName）的处理逻辑一致；
• 主题色高亮：以--primary（即 identicon 主色#6C5CE7所在的 CSS 变量体系）区分助理项目与普通项目，视觉上一眼可辨；
• 置顶策略：助理项目恒定位于项目列表最上方，增强存在感。

3.3 状态行内容

状态行采用两行小字设计：

• 第一行：最近活动——"上次心跳：2h 前" / "今天聊过 3 轮" / "未设置 → 点击开始"；
• 第二行：记忆统计——"记忆 23 条" / "待办 2 项"；
• 若性能受限，可简化为一行 + 状态点（绿 = 活跃 / 灰 = 未配置）。

状态行数据来源与 src/lib/assistant-workspace.ts 中的心跳、记忆文件管理逻辑相呼应（HEARTBEAT.md、memory/daily/ 目录均由该模块维护）。

四、聊天窗口与文件树的状态可视化

4.1 聊天窗口视觉差异化

助理项目的聊天窗口需与普通项目区分：

• AI 消息旁显示助理头像（普通项目用默认图标）——对应AssistantAvatar在消息流中的复用；
• 顶部 bar 带主题色底边——延续--primary主题色语言；
• 空状态显示助理头像 + 名字（而非通用的 CodePilot logo）——强化"我在和谁对话"的感知。

4.2 助理专属右侧状态面板

原文档建议将普通项目的右侧面板（文件树/Git）替换为"助理状态面板"，包含三块内容：

┌───────────────────────────┐ │ 助理状态 │ ├───────────────────────────┤ │ 📊 状态 │ │ · 心跳：今天 9:30 ✓ │ │ · Workspace: 健康 │ │ · 记忆文件: 5 个 │ │ │ │ 🧠 最近记忆 │ │ · 03-31: 讨论了助理体验设计 │ │ · 03-30: 记忆系统 V3 完成 │ │ │ │ ⚙ 快捷设置 │ │ [编辑 HEARTBEAT.md] │ │ [管理记忆文件] │ │ [助理设置 →] │ └───────────────────────────┘

• 状态区：心跳时间（来自 HEARTBEAT.md）、Workspace 健康度、记忆文件数量；
• 最近记忆：从memory/daily/按日期倒序展示最近条目；
• 快捷设置：一键编辑 HEARTBEAT.md、管理记忆文件、进入助理设置。

4.3 文件树状态图标的轻量替代

如果不想引入独立面板，方案也给出了轻量替代：在文件树中为 workspace 文件加状态图标：

• soul.md✅ / ⚠️（文件健康/有问题）
• HEARTBEAT.md🟢（有内容）/ 🔴（空）
• memory/daily/📊 3 files

两种形态按实现成本取舍：状态面板信息密度高，文件树图标实现成本低。

五、Onboarding Wizard：三步前端向导

5.1 设计理念：放弃 AI 对话式

原文档明确了一个重要的产品决策：放弃 AI 对话式 onboarding，改用前端 Wizard 组件。理由非常实际：

• AI 对话式依赖 API 调用（慢、要钱、可能失败）；
• AI 控制不了问题数量（Codex 审核发现此前对话式问了 8 个问题）；
• 用户不知道什么时候结束；
• 新用户可能不知道怎么和 AI 聊。

而前端 Wizard 的体验目标：每个选择实时落库、零 API 调用秒完成、像填一个可爱的小表单、3 步完成每步 2 秒。

5.2 三步流程与落库文件

Step 1：关于你——填写称呼 + 选择主要工作（开发/设计/产品/写作/研究/其他）。选完立即写user.md（名字 + 角色）。

Step 2：关于助理——给助理取名字（可留空）+ 选择沟通风格（简洁直接/详细耐心/轻松）+ 填写"绝对不要做的事"（可选）。选完立即写soul.md（名字 + 风格 + 边界）。

Step 3：完成——展示生成的头像、列出已创建文件清单，点击"开始聊天 →"结束。

5.3 组件级实现印证

仓库中该组件已落地为 src/components/assistant/OnboardingWizard.tsx，其结构与原文档设计高度吻合：

• 三步状态机：const [step, setStep] = useState(0)，TOTAL_STEPS = 3；
• 角色选项：ROLE_IDS = ['developer', 'designer', 'product', 'researcher', 'student', 'general']（比原文档的 5 个选项多出student，并全部走 i18n 文案）；
• 风格选项：STYLE_IDS = ['concise', 'detailed', 'casual']，每项带styleDesc副文案（如"简洁直接"的说明文字）；
• 步骤校验：canNext逻辑——Step 1 要求用户名字非空，Step 2 要求风格已选，Step 3 恒可完成；
• 提交端点：handleComplete向POST /api/workspace/wizard提交{ userName, userRole, assistantName, style, boundaries }，而非原文档设想的"每步实时落库"——仓库实现采用最后一步统一提交，同时保留了 Step 3 完成页的总结卡片（角色/风格/边界回显）；
• 头像预览：Step 3 完成页直接渲染AssistantAvatar（未配置 Buddy 时），配置 Buddy 时展示 3D 物种形象与稀有度徽章；
• i18n：全部文案通过useTranslation走wizard.*与buddy.*翻译键，支持多语言。

5.4 服务端文件生成：零 API 调用到"AI 兜底"

原文档强调 Wizard 全程零 API 调用，文件全部用模板填充。仓库的服务端实现 src/lib/onboarding-processor.ts 对此做了演进：默认走模板生成，但引入了 AI 生成的"增强"路径与质量兜底：

• 幂等保护：state.onboardingComplete已为 true 时直接返回，避免重复生成；
• 会话归属校验：传入sessionId时校验 session 的working_directory与 workspace 一致，防止串空间；
• AI 生成（可选增强）：通过resolveProvider解析 provider/model，并行生成soul.md、user.md、claude.md、memory.md四份内容；生成失败时降级为原始回答的模板填充（fallback），保证任何情况下都能完成 onboarding；
• 质量校验：validateGeneratedContent检查内容长度（≥50 字符）与关键章节标题（如 Personality/Style/Boundaries 或中文"性格/风格"），不合格则回退到内置模板，例如：

  # Soul ## Core Personality I am your personal assistant. ## Communication Style Concise and direct. ## Behavioral Boundaries Respect user preferences.

• 规则文件模板：claude.md强制保留 5 个系统预设区块——Time Awareness（时间意识）、Memory Rules（记忆规则）、Document Organization（文档组织）、Writing Constraints（写作约束）、Safety（安全），再追加个性化规则，总长限制 3000 字符内。这些预设区块与 src/lib/assistant-workspace.ts 中的内置claude.md默认模板保持一致；
• 附加产物：确保memory/daily/目录与Inbox目录存在、生成config.json（从回答推断organizationStyle：project/time/topic/mixed，以及captureDefault）、按已有目录推断taxonomy.categories、调用generateRootDocs生成README.ai.md与PATH.ai.md等根文档；
• 状态收尾：state.onboardingComplete = true、lastHeartbeatDate = today、同步lastCheckInDate（向后兼容）、schemaVersion = 5。

5.5 文件生成策略对照表

原文档的生成策略表完整继承如下（仓库实现基本一致，config.json与根文档在 Step 3 确认后一并生成）：

需要说明的是：仓库实现中user.md/soul.md的实际写入发生在提交后统一处理阶段（processOnboarding），但"模板填充、无需 AI"的原则一致——AI 生成仅是失败时的增强路径，不影响"秒完成"的体验承诺。

5.6 与 AI 对话式 onboarding 的关系：替代而非共存

原文档明确Wizard 替代 AI 对话式 onboarding，不是共存，并给出了四条理由（API 依赖、问题数量失控、结束不明确、新用户不会聊）。同时，processOnboarding被抽成独立模块（见 src/lib/onboarding-processor.ts 顶部注释），"以便在不走 HTTP 往返的情况下，由服务端完成检测直接调用"——这正对应原文档 4.5 节的约定：

Wizard 完成后state.onboardingComplete = true，AI 对话式 onboarding 不再触发。buildOnboardingInstructions()保留作为 fallback（如果用户通过 API 或旧版本创建 workspace）。

仓库中的完成检测逻辑也保留了兼容层： src/lib/onboarding-completion.ts 能从 AI 消息内容中提取onboarding-complete/checkin-completefence（容忍 CRLF、多余空白与可选语言标签），并用多级 JSON 修复策略（去 markdown 加粗、修复字符串内换行、单引号转双引号、去尾逗号、最后用正则兜底提取q{1,2}键值对）解析答案——这是为旧版/API 直连场景保留的 fallback 通道，与"Wizard 为主"的产品决策不冲突。

六、用户引导策略

6.1 新用户首次引导：空状态双入口

首次打开 CodePilot 且无任何会话时，空状态页给出两个等权重的入口：

• 💬 项目对话：打开项目文件夹，AI 帮你写代码、调试和重构。每个项目独立，互不干扰；
• 🤖 个人助理：设置一个了解你的 AI 助理，它会记住你的偏好，管理日程，辅助创作和思考。跨对话记忆，不需要每次重新解释背景。

交互约定：点击"个人助理"→ 直接进入 Onboarding Wizard（第五节）；点击"项目对话"→ 弹出文件夹选择器。文案核心区隔在于：项目对话 = 按项目隔离的代码上下文；个人助理 = 跨对话的长期记忆。

6.2 老用户非侵入引导

已有项目但未配置助理的用户，在侧栏顶部显示一个可折叠卡片：

✨ 设置你的个人助理 — 记住你的偏好，管理日程，辅助创作。和项目对话不同，助理拥有跨对话的长期记忆。

关键约束：可永久关闭（localStorage标记）、不弹 toast/modal、不打断工作流。这是典型的"引导但不打扰"设计，避免存量用户流失。

6.3 配置完成后的引导

Onboarding 完成后第一次进入助理聊天：显示 welcome card（"设置完成！你可以随时和我聊天，我会记住重要的事情。"），下方放 3 个 quick action chip 引导首次互动——这与下一节的 Quick Actions 组件直接衔接。

七、记忆驱动的 Quick Actions

7.1 设计形态

助理聊天的空输入状态下，在输入框上方显示 2-3 个 quick action chip，示例：

💡 "周五开会的材料准备好了吗？" 💡 "Rust 学习进展" 💡 "回顾本周"

点击 chip 直接作为消息发送，引导用户完成第一次有意义的对话。

7.2 生成策略（纯前端草案与仓库演进）

原文档给出了一份纯前端、零 API 调用的生成算法草案：从 daily memory 提取未完成事项（- [ ]正则）、从user.md提取## Current Goals区块的首条目标、再补一个固定动作"回顾本周"，最终取前 3 条。

仓库的实际实现 src/lib/quick-action-suggestions.ts 在此基础上演进为"缓存 + 增强生成"模型：

• createQuickActionSuggestionsCache实现单槽位缓存：以(workspace, identity)为键，SUCCESS_TTL_MS = 10 分钟，成功结果在 TTL 内直接复用；
• 并发去重：entry.pending保证同一时刻多个请求共享同一次生成，避免重复调用；
• 身份绑定：identity来自当前 provider 配置，配置变更自动落入新槽位（current被替换），从不缓存未知身份；
• 失败冷却：生成失败时expiresAt = now()（立即允许重试）；非 completed 状态遵循retryAt冷却；显式 retry 只刷新成功结果、不绕过失败冷却；
• 模块以 globalThis 上的__codepilotQuickActionSuggestionsV3单例暴露，避免多实例缓存漂移。

组件层 src/components/chat/QuickActions.tsx 负责展示与状态管理：

• 仅当isAssistantProject && !hasMessages（助理项目且无消息）时渲染；
• mount 时GET /api/workspace/quick-actions（cache: 'no-store'，带 AbortController 防竞态），重试时改走POST { action: 'retry' }；
• 监听provider-changed与window focus事件自动刷新，保证切换 Provider 后建议同步更新；
• 特殊动作__review_week__渲染为 i18n 的"回顾本周"文案；
• 提供QuickActionsStatus状态提示行：生成中（generating）、冷却中（cooldown + retry 倒计时）、凭据缺失/配置要求/身份不可用/策略拦截等分场景 hint 文案，并附"重试"按钮与费用提示（retryCost）——说明该端点可能产生模型调用费用。

7.3 API 端点

原文档约定的端点为：

GET /api/workspace/quick-actions → { actions: ["周五开会的材料准备好了吗？", "Rust 学习进展", "回顾本周"] }

仓库实现位于 src/app/api/workspace/quick-actions，并在此基础上扩展了响应结构：{ actions, enhancement }，其中enhancement: AuxiliaryExecutionStatus描述生成状态（completed / in_flight / cooldown / failed 及细分原因），供前端状态提示使用；重试语义通过POST+{ action: 'retry' }表达。仓库中的对应单元测试见 src/tests/unit/quick-actions-route.test.ts 与 src/tests/unit/quick-action-suggestions.test.ts，覆盖了缓存命中、身份变更、失败冷却等边界。

八、实施顺序与优先级

原文档给出了五阶段实施顺序，用于指导渐进落地：

Phase A: Onboarding Wizard（核心，替代 AI 对话式） → 前端组件 + 模板文件生成 + state 管理 Phase B: 侧栏视觉重设计 → Identicon + 名字 + 状态行 + 主题色 + 置顶 Phase C: 聊天主题色 + Quick Actions → 消息头像 + 顶部 bar 主题色 + 记忆驱动 chip Phase D: 用户引导 → 新用户空状态 + 老用户侧栏卡片 Phase E: 助理状态面板 → 右侧面板替换 + 状态/记忆/设置 tab

优先级结论：Phase A 最重要——它直接解决"onboarding 太重、问题太多、结束不明确"的问题；Phase B 其次——它解决"用户发现不了助理"的问题；其余按优先级排。

从仓库现状看，Phase A（OnboardingWizard.tsx+onboarding-processor.ts+onboarding-completion.ts）与 Phase C 的 Quick Actions 部分（QuickActions.tsx+quick-action-suggestions.ts+ API 端点）已经落地并有配套单元测试，Phase B/D/E 可作为后续迭代的路线图参考。

九、涉及文件预估汇总

原文档对涉及模块给出了新建/修改预估与复杂度评估，完整继承如下：

对照仓库实际文件：

• src/lib/identicon.ts✅ 已存在（色彩板 + 变体类型）；
• src/components/assistant/OnboardingWizard.tsx✅ 已存在（三步状态机 + Buddy 揭示）；
• src/components/chat/QuickActions.tsx✅ 已存在（含状态提示行）；
• 头像组件落地于src/components/ui/AssistantAvatar.tsx（原文档未单独列出的新增模块）；
• 服务端生成逻辑落地于src/lib/onboarding-processor.ts（含 AI 兜底与质量校验，复杂度高于原预估）。

结语

CodePilot 的助理体验升级，核心是一条清晰的产品主线：用确定性视觉建立身份，用零成本 Wizard 完成首次配置，用记忆驱动的 Quick Actions 降低首轮对话门槛。本文既完整继承了原设计文档的决策表、流程图、代码草案与实施路线，也结合仓库源码（identicon.ts、AssistantAvatar.tsx、OnboardingWizard.tsx、onboarding-processor.ts、quick-action-suggestions.ts、QuickActions.tsx）印证了设计如何落地、在哪些关键点做了演进（统一提交而非每步落库、AI 兜底而非纯模板、带状态的增强式 Quick Actions）。后续若需继续深入，可从 docs/future/assistant-ux-upgrade.md 出发，沿 src/components/assistant/OnboardingWizard.tsx 与 src/lib/onboarding-processor.ts 追踪实现细节。

• 人工智能
• AI 应用
• AI Agent
• 交互助手
• MCP Clients
• 本地部署