CodePilot/docs/handover/onboarding-setup-center.md

首次引导 Setup Center + Claude Code 环境检测

完成时间：2026-03-13 | 涉及 ~25 个文件 | 6 阶段交付

概述

为 CodePilot 新增可跳过的首次设置引导（Setup Center），替代原先被动的"失败后提示"模式。引导覆盖三个核心前置条件：Claude Code CLI 连接、API Provider 配置、默认项目目录。同时修复 Windows 顶栏重叠，统一错误反馈路径。

架构

整体流程

应用启动
  ↓
AppShell.useEffect → GET /api/setup
  ↓
setup_completed !== true?
  ├── 是 → 弹出 SetupCenter 蒙层
  │         ├── ClaudeCodeCard: 检测 CLI 环境
  │         ├── ProviderCard: 检测 API 凭据
  │         └── ProjectDirCard: 选择项目目录
  │         用户可逐个完成或跳过，全部完成后自动关闭
  └── 否 → 正常进入应用
              ↓
         /chat 页独立校验 provider + 目录
         缺失时显示 ChatEmptyState 引导

组件结构

AppShell
  └── SetupCenter (fixed overlay, z-50)
        ├── WelcomeCard (静态)
        ├── ClaudeCodeCard → /api/claude-status
        ├── ProviderCard → /api/providers + /api/settings/app
        └── ProjectDirCard → /api/setup/recent-projects

状态持久化

Setup 状态存储在 SQLite settings 表，键名：

键	值	说明
setup_completed	'true'	整体完成标记，控制是否自动弹出
setup_claude_skipped	'true'	用户跳过了 Claude Code 检测
setup_provider_skipped	'true'	用户跳过了 Provider 配置
setup_project_skipped	'true'	用户跳过了项目目录选择
setup_default_project	路径字符串	用户选择的默认项目目录

重新打开

• 设置页 GeneralSection 中有"首次设置引导"入口（FieldRow + Open 按钮）
• 代码中任何位置可通过 window.dispatchEvent(new CustomEvent('open-setup-center')) 触发
• 支持 initialCard 参数跳转到指定卡片：{ detail: { initialCard: 'provider' } }

自动关闭逻辑

• 用 initialCompletedCountRef 记录打开时的已完成数
• 只在用户当前会话中完成了最后一张卡时才自动关闭
• 已全部完成的状态下手动打开不会自动关（避免从设置页点开瞬间关闭）

Claude Code 环境检测（详细）

检测链路

ClaudeCodeCard
  ↓ GET /api/claude-status
  ↓
findClaudeBinary() + findAllClaudeBinaries()  (src/lib/platform.ts)
  ↓
返回:
  connected: boolean        — 是否找到可用二进制
  version: string | null    — 版本号
  binaryPath: string | null — 当前使用的路径
  installType: string       — native / npm / bun / homebrew / unknown
  otherInstalls: Array<{path, version, type}>  — 其他冲突安装
  missingGit: boolean       — Windows 上未检测到 Git

四种状态及 UI 展示

1. 已检测到（connected = true, 无冲突）

• 绿色 completed 状态
• 显示版本号、安装类型、二进制路径

2. 已检测到但存在冲突（connected = true, otherInstalls.length > 0）

• 黄色警告框，标题："检测到多个安装版本，可能导致版本冲突"
• 显示当前使用的版本（路径 + 安装类型 + 版本号）
• "查看清理方式"按钮 → 展开详情：
  • 逐条列出每个冲突安装的路径、类型、版本
  • 根据安装类型给出卸载命令（带一键复制按钮）：
    • npm: npm uninstall -g @anthropic-ai/claude-code
    • bun: bun remove -g @anthropic-ai/claude-code
    • homebrew: brew uninstall --cask claude-code
  • 底部提示"清理完成后，点击重新检测以确认" + Re-detect 按钮

3. 未找到（connected = false, missingGit = false）

• 显示安装命令：
  • macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash
  • Windows: irm https://claude.ai/install.ps1 | iex
• Re-detect 按钮

4. 缺少 Git（Windows 专用, missingGit = true）

• 显示 Git for Windows 安装步骤（三步引导）
• Re-detect 按钮

冲突处理的设计决策

• 不自动切换：冲突状态下仍标记为 completed（能正常工作），只给出警告和清理建议
• 复用 InstallWizard 的卸载逻辑：getUninstallCommand() 与 InstallWizard 的 getUninstallAdvice() 保持一致
• CopyableCommand 组件：卸载命令支持一键复制，降低操作门槛

Provider 检测（详细）

三条凭据来源（优先级从高到低）

1. DB provider：api_providers 表中配置的自定义服务商（含 preset 预设）
2. 进程环境变量：ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN
3. App settings token：getSetting('anthropic_auth_token')（旧版本的凭据存储路径）

关键判断规则

• ANTHROPIC_BASE_URL 不算凭据：只有 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 才是真正的认证凭据，仅有 base URL 无法发起请求
• OPENAI_API_KEY 不参与判断：运行时 env 解析不支持它，setup 也不应把它算作可用 provider
• skipped 不等于 completed：/chat 页只认 completed，跳过引导的用户在发消息前仍会看到"去配置 provider"的提示
• skipped 不是粘性状态：/api/setup 先查真实凭据，有任何一条就返回 completed；只有完全没有凭据时才看 setup_provider_skipped flag

ProviderCard 交互

• 检测到 env 凭据 → 显示"使用 Claude Code 环境"按钮，一键确认
• 无凭据 → 显示"添加服务商"按钮，跳转 /settings#providers（hash 路由）
• 监听 provider-changed 事件自动刷新状态

项目目录

目录回退链

page.tsx 初始化 workingDir:
  1. localStorage['codepilot:last-working-directory']
     ↓ 校验 /api/files/browse → 有效则使用
     ↓ 无效 → 清除 localStorage
  2. GET /api/setup → defaultProject
     ↓ 校验 /api/files/browse → 有效则使用并写入 localStorage
  3. 都无效 → 显示空状态（ChatEmptyState）

ChatListPanel 的 handleNewChat 使用相同的回退链：最近目录 → defaultProject → 弹 picker。

跨组件同步

• ProjectDirCard 选中目录后，通过 project-directory-changed CustomEvent 通知 /chat 页
• /chat 页监听该事件，实时更新 workingDir 状态
• 同时写入 localStorage 和 /api/setup（server 端持久化）

Toast 系统

架构

• useToast.ts：全局状态 + showToast() 命令式 API
• toast.tsx：<Toaster /> 组件，渲染在 AppShell 底层
• FIFO 策略，最多 3 条，默认 5s 消失（error 8s）
• 支持 action: { label, onClick } 可选操作按钮

使用场景

场景	类型	位置
Push 成功/失败	success/error	GitStatusSection
标题保存失败	error	UnifiedTopBar
目录失效	warning + action	ChatListPanel

Windows 适配

• UnifiedTopBar 右侧添加 138px spacer（3 × 46px 系统标题按钮宽度），通过 useClientPlatform().isWindows 判断
• 路径分割统一使用 split(/[\\/]/).filter(Boolean) 兼容反斜杠
• ProjectGroupHeader 的"在文件管理器中打开"文案根据平台动态切换（Finder / Explorer / Files）

文件清单

新增文件

文件	用途
src/hooks/useClientPlatform.ts	SSR 安全的平台检测 hook
src/hooks/useToast.ts	Toast 状态管理 + 全局 API
src/components/ui/toast.tsx	Toaster 渲染组件
src/components/ui/error-banner.tsx	内联错误条
src/app/api/setup/route.ts	Setup 状态 CRUD
src/app/api/setup/recent-projects/route.ts	最近项目列表
src/components/setup/SetupCenter.tsx	引导蒙层主组件
src/components/setup/SetupCard.tsx	可复用卡片壳
src/components/setup/WelcomeCard.tsx	欢迎卡片
src/components/setup/ClaudeCodeCard.tsx	Claude Code 检测 + 冲突处理
src/components/setup/ProviderCard.tsx	Provider 检测 + 配置入口
src/components/setup/ProjectDirCard.tsx	项目目录选择
src/components/chat/ChatEmptyState.tsx	/chat 空状态引导

关键修改文件

文件	改动
src/components/layout/AppShell.tsx	挂载 SetupCenter + Toaster
src/components/layout/UnifiedTopBar.tsx	Windows safe zone、路径兼容、移除 commit/push 按钮
src/components/git/GitStatusSection.tsx	新增 Commit + Push 按钮
src/components/layout/ConnectionStatus.tsx	断连时派发 setup-center 事件
src/components/settings/GeneralSection.tsx	首次设置引导入口
src/app/chat/page.tsx	目录校验回退链 + provider 检测 + ChatEmptyState
src/components/layout/ChatListPanel.tsx	失效目录回退到 defaultProject
src/i18n/en.ts / zh.ts	~80 个新 i18n 键

已知限制

• Setup Center 不是分步向导，而是所有卡片同时展示在滚动面板中
• Claude Code 冲突检测依赖 findAllClaudeBinaries() 的路径扫描，可能遗漏非标准安装路径
• Provider 检测不覆盖 OPENAI_API_KEY（运行时 env 模式不支持），如果未来支持需要同步更新检测逻辑
• 目录校验使用 /api/files/browse 接口，额外产生一次文件系统访问