feat(sprint-6): UI/UX 设计稿首发 · 10 wireframes + 5 flows

README.md

@@ -8,7 +8,7 @@
 [![npx](https://img.shields.io/badge/npx-epcode-orange)](./tools/cli/)
 [![License](https://img.shields.io/badge/license-MIT-green)]()
 
-> 📍 **最新进展**: Sprint 5 已完成（统一 `epcode` CLI + Docusaurus 文档站 + 治理文件,2026-04-18）。**5 个 Sprint 全部完成 · 整体完成度 98%**。
+> 📍 **最新进展**: Phase 1 已完成(v0.6.0 · 5 Sprint · 整体完成度 98%)。Phase 2 启动 · Sprint 6 ⑥ UI/UX 设计稿首发(10 wireframes + 5 interaction flows)。
 >
 > - 🧰 [统一 CLI · epcode](./tools/cli/) · 10 个子命令,零依赖 `npx epcode --help`
 > - 🌐 **[文档站 · epcode-ai.github.io/ep-code-ai](https://epcode-ai.github.io/ep-code-ai/)** ✅ 已上线 · 首页以 4 接入模式为一等公民

docs/design/ui/README.md

@@ -0,0 +1,98 @@
+# EP Code AI · 桌面应用 UI/UX 设计稿
+
+> Sprint 6 ⑥ 产出。三平台桌面应用(macOS / Linux / Windows)的统一 UI/UX 设计蓝图。
+>
+> **状态**: v1.0 草案 · 待评审 · 评审通过后作为 Sprint 7-8 实现的权威源
+>
+> **观看顺序**:
+> 1. 本文(原则 + 索引)
+> 2. [wireframes/](./wireframes/) — 10 张静态页面线框图(ASCII)
+> 3. [interaction-flows/](./interaction-flows/) — 5 个关键交互流程图(Mermaid)
+> 4. [cross-platform-constraints.md](./cross-platform-constraints.md) — 三平台一致性约束
+
+---
+
+## 一、设计原则
+
+### 1.1 信息密度优先,装饰其次
+
+- 三栏视图最大化利用屏幕,装饰性留白控制在 8-12%
+- 没用的功能不放(如品牌大 logo、空白引导卡片占满屏)
+
+### 1.2 键盘第一,鼠标第二
+
+- 所有高频操作必须有快捷键(`/` 命令面板、`⌘K` 搜索、`⌘N` 新会话、`⌘,` 设置)
+- 鼠标只是 fallback,不是主要交互方式
+- 命令面板覆盖所有 CLI 子命令(`epcode prd`、`epcode adr` 等),用户在 GUI 里也能跑
+
+### 1.3 状态可见
+
+- 当前供应商、模型、连接状态、环境检查结果 都在视觉上随时可见
+- 失败状态用红/黄高亮,不靠 toast(toast 会闪过)
+
+### 1.4 渐进披露
+
+- 默认隐藏高级功能(模型温度、上下文窗口、调试面板等)
+- 设置页有 "⚗️ 实验性" tab 收纳
+
+### 1.5 三平台一致 + 平台特性
+
+- **必须一致**: 信息架构、核心功能层级、关键术语、快捷键(modifier 键除外)
+- **可分平台定制**: 窗口控件位置、菜单组织、系统托盘、通知样式
+
+---
+
+## 二、索引
+
+### Wireframes(静态线框图,10 张)
+
+| # | 文件 | 主题 |
+|---|------|------|
+| 1 | [main-three-pane.md](./wireframes/01-main-three-pane.md) | 主视图(侧边栏 + 聊天 + Artifact) |
+| 2 | [setup-wizard.md](./wireframes/02-setup-wizard.md) | 首次启动 4 步向导 |
+| 3 | [settings.md](./wireframes/03-settings.md) | 设置页(General / Provider / Shortcuts / Experimental) |
+| 4 | [slash-command-palette.md](./wireframes/04-slash-command-palette.md) | 斜杠命令浮层 |
+| 5 | [artifact-panel-expanded.md](./wireframes/05-artifact-panel-expanded.md) | Artifact 全屏详情 |
+| 6 | [provider-switcher.md](./wireframes/06-provider-switcher.md) | 供应商切换浮层 |
+| 7 | [search-overlay.md](./wireframes/07-search-overlay.md) | 全局搜索(⌘K) |
+| 8 | [conversation-context-menu.md](./wireframes/08-conversation-context-menu.md) | 会话右键菜单 + 收藏 + 分组 |
+| 9 | [empty-states.md](./wireframes/09-empty-states.md) | 各种空状态 |
+| 10 | [env-status-bar.md](./wireframes/10-env-status-bar.md) | 持久化环境健康状态栏 |
+
+### Interaction Flows(交互流程,5 个 Mermaid)
+
+| # | 文件 | 流程 |
+|---|------|------|
+| 1 | [flow-new-conversation.md](./interaction-flows/01-flow-new-conversation.md) | 新建会话从入口到首条消息 |
+| 2 | [flow-env-check-fail.md](./interaction-flows/02-flow-env-check-fail.md) | 环境检查失败的兜底引导 |
+| 3 | [flow-slash-command.md](./interaction-flows/03-flow-slash-command.md) | 斜杠命令调用 + 自动补全 |
+| 4 | [flow-artifact-detect.md](./interaction-flows/04-flow-artifact-detect.md) | AI 输出 → 自动识别为 Artifact |
+| 5 | [flow-provider-switch.md](./interaction-flows/05-flow-provider-switch.md) | 会话中切换供应商的影响处理 |
+
+---
+
+## 三、与 Phase 1 的关系
+
+本设计稿对应 `app/ClaudeCodeHistory/` 已有的 22 个 Swift 文件。Sprint 7 macOS Beta 时:
+
+| 设计稿 | Swift 实现 | 改动评估 |
+|--------|----------|---------|
+| 主三栏 | `ContentView.swift` + `SidebarView.swift` + `ChatView.swift` + `ArtifactPanel.swift` | 中,需补缺失元素(供应商显示、状态栏) |
+| 首次向导 | `SetupWizardView.swift` + `EnvironmentChecker.swift` | 大,加 Provider 配置步骤 |
+| 设置页 | `SettingsView.swift` + `AppSettings.swift` + `ProviderManager.swift` | 大,重构成多 tab |
+| 斜杠命令面板 | (无) | 全新,需加新组件 |
+| 全局搜索 | (无) | 全新 |
+| 状态栏 | `EHUBInfoBar.swift` 局部 | 中,扩展为完整状态栏 |
+
+---
+
+## 四、待评审项
+
+主理人评审时优先关注:
+
+- [ ] 三栏布局比例 (240 / flex / 320 px) 是否合适?
+- [ ] 命令面板是否覆盖了 CLI 全集(10 个 subcommand)?
+- [ ] 首次向导 4 步是否过长?是否能合并 1-4 步?
+- [ ] 跨平台约束(`cross-platform-constraints.md`)是否过严?
+- [ ] 是否需要补 "AI 思考中" 的视觉反馈线框?
+- [ ] 是否需要补 "设置 → 隐私" 页(数据收集/上报开关)?

docs/design/ui/cross-platform-constraints.md

@@ -0,0 +1,124 @@
+# 三平台一致性约束
+
+> 哪些必须三平台完全一致 / 哪些可以分平台定制 / 哪些每平台独有。
+
+## 一、必须一致(违反 = 设计 bug)
+
+### 1.1 信息架构
+
+- 三栏布局(侧边栏 / 聊天 / Artifact 面板)的位置和顺序
+- 设置页的 4 个 tab 顺序: General → Provider → Shortcuts → Experimental
+- 首次向导 4 步的顺序: Welcome → Env Check → Provider → Done
+
+### 1.2 关键术语(中文优先,英文为辅)
+
+| 概念 | 用词 | 不要用 |
+|------|------|--------|
+| AI 一次回复 | "回复" | response / answer |
+| 用户一次输入 | "消息" | prompt / query |
+| 一组对话 | "会话" | conversation / chat / dialog |
+| AI 输出的代码/文档 | "Artifact" | document / output / file |
+| AI 服务方 | "供应商" | provider / vendor |
+
+### 1.3 快捷键(modifier 跨平台映射)
+
+| 功能 | macOS | Linux/Win | 备注 |
+|------|-------|-----------|------|
+| 新会话 | `⌘N` | `Ctrl+N` | |
+| 全局搜索 | `⌘K` | `Ctrl+K` | |
+| 设置 | `⌘,` | `Ctrl+,` | |
+| 斜杠命令 | `/` | `/` | 在输入框首字符触发 |
+| 切换供应商 | `⌘⇧P` | `Ctrl+Shift+P` | |
+| 关闭当前会话 | `⌘W` | `Ctrl+W` | |
+| 退出 | `⌘Q` | `Ctrl+Q` | |
+
+> **macOS modifier (`⌘ ⇧ ⌥ ⌃`)** ↔ **Linux/Windows (`Ctrl Shift Alt Meta`)** 一对一映射
+
+### 1.4 颜色语义
+
+| 语义 | 颜色 | 使用场景 |
+|------|------|---------|
+| Primary | `#2962FF`(深蓝) | 主按钮、链接、激活状态 |
+| Success | `#00C853`(绿) | 环境检查通过、操作成功 |
+| Warning | `#FFB300`(琥珀) | 可降级运行的问题 |
+| Error | `#D50000`(红) | 必须修复的问题、API 失败 |
+| Muted | `#6B7280`(灰) | 次要文本、占位符 |
+
+### 1.5 字体
+
+- **正文**: 系统默认 UI 字体 (San Francisco / Segoe UI / Cantarell)
+- **代码 / Artifact**: `JetBrains Mono` 12px(打包内置;系统无则降级 monospace)
+
+---
+
+## 二、可分平台定制
+
+### 2.1 窗口控件位置
+
+| 平台 | 关闭/最大/最小化 | 应用菜单 |
+|------|----------------|---------|
+| macOS | 左上(红黄绿) | 系统菜单栏(屏幕顶) |
+| Windows | 右上(─ □ ✕) | 应用窗口内顶部 |
+| Linux GNOME | 右上 | 应用窗口内顶部(汉堡菜单) |
+| Linux KDE | 可配置 | 同 Windows |
+
+### 2.2 通知样式
+
+- macOS: 用 `UNUserNotificationCenter` 系统通知中心
+- Windows: 用 toast notification (Windows 10+)
+- Linux: 优先 D-Bus `org.freedesktop.Notifications`,fallback 应用内 banner
+
+### 2.3 文件选择 / 保存对话框
+
+- 各平台用系统原生对话框,不自绘
+
+### 2.4 系统托盘 / 菜单栏图标
+
+- macOS: 菜单栏(顶栏)右侧
+- Windows: 系统托盘
+- Linux: 应用指示器(Unity)/ 系统托盘(其他)
+
+### 2.5 键盘菜单加速键(`Alt+F` 等)
+
+- Windows/Linux 应用菜单显示下划线加速键
+- macOS 不显示
+
+---
+
+## 三、每平台独有(其他平台不实现)
+
+### 3.1 macOS 独有
+
+- **Touch Bar 支持**(2016-2021 MacBook Pro):放常用命令快捷
+- **Spotlight 集成**:Cmd+Space 搜索可命中本应用的会话(可选,Phase 3+)
+
+### 3.2 Windows 独有
+
+- **任务栏跳转列表**:右键应用图标显示"最近会话"
+- **WSL 桥接**:检测到 WSL 时优先在 WSL 里跑 Claude Code
+
+### 3.3 Linux 独有
+
+- **D-Bus 服务**:暴露 RPC 接口供其他工具调用(如 i3wm 快捷键直接跑命令)
+
+---
+
+## 四、必须避免的反模式
+
+| ❌ 反模式 | 为什么避免 |
+|---------|----------|
+| 在 macOS 用 Windows 风格关闭按钮(右上 ✕) | 视觉违和,反 macOS HIG |
+| 三个平台用不同的 emoji(✅ vs ✔ vs 🆗) | 跨平台截图对比时混乱 |
+| 在 Linux 用 Windows 通知 toast 样式 | 不融入桌面环境 |
+| 复制 macOS 的全局菜单到 Linux/Windows 应用窗口外 | 平台习惯不同,用户找不到 |
+| 不同平台快捷键不一致(如 macOS Cmd+T,Win Ctrl+N) | 跨平台用户困惑 |
+
+---
+
+## 五、本约束的演进
+
+任何对本文件的改动需要 ADR(`docs/adr/`):
+
+- 加新约束 → 标 `Status: Proposed`,2 周评审窗口
+- 改约束 → 必须标明影响哪些 wireframe / 流程
+- 删约束 → 在本文末尾追加 "已废止" 段,保留历史

docs/design/ui/interaction-flows/01-flow-new-conversation.md

@@ -0,0 +1,65 @@
+# Flow 01 · 新建会话
+
+> 从触发新建到 AI 出现首条回复的完整流程。
+
+## 主流程
+
+```mermaid
+flowchart TD
+    A[用户触发新建] -->|⌘N / 点击 + 新会话 / 命令面板/init| B{是否已配置供应商?}
+    B -- 否 --> B1[弹供应商配置引导] --> B2[完成配置] --> C
+    B -- 是 --> C[侧边栏新增 '未命名会话',中栏切到空状态-9.3]
+    C --> D[输入框 focus,显示 4 个 prompt 卡片]
+    D --> E{用户操作}
+    E -- 点 prompt 卡片 --> F[卡片内容填入输入框,自动发送]
+    E -- 直接输入 + ⌘↵ --> F
+    E -- 输入 / 触发命令 --> G[斜杠命令面板,见 Flow 03]
+    F --> H[消息进入聊天流, '思考中...' 显示]
+    H --> I[AI 流式输出,逐字显示]
+    I --> J{首次完整回复?}
+    J -- 是 --> K[根据消息生成会话名,侧边栏更新]
+    J -- 否 --> L[保持 '未命名会话']
+    K --> M[Artifact 检测,见 Flow 04]
+    L --> M
+```
+
+## 异常分支
+
+```mermaid
+flowchart TD
+    F[发送消息] --> X1{发送结果}
+    X1 -- 网络超时 --> Y1[显示重试按钮 + 状态栏标红]
+    Y1 --> Y2{用户点重试?}
+    Y2 -- 是 --> F
+    Y2 -- 否 --> Y3[消息暂存本地,断网恢复后自动重发]
+
+    X1 -- API 401/403 --> Z1[弹模态: 'API Key 失效,请重新配置']
+    Z1 --> Z2[跳到设置 Provider tab]
+
+    X1 -- API 429 限流 --> W1[消息排队,显示 '排队中... 第 N 位']
+    W1 --> W2[按 Retry-After 头自动重试]
+
+    X1 -- 上下文超长 --> V1[弹模态: '上下文已满,可截断早期消息或新建会话']
+    V1 --> V2{选项}
+    V2 -- 截断 --> V3[保留最近 80% tokens,继续发送]
+    V2 -- 新建会话 --> V4[新会话带本次消息]
+```
+
+## 关键时序
+
+| 步骤 | 期望延迟 |
+|------|---------|
+| 触发新建 → 中栏切到空状态 | < 50ms |
+| 发送消息 → "思考中..." 出现 | < 100ms |
+| "思考中..." → 首字符显示 | 500ms - 3s(供应商决定) |
+| 首次回复完成 → 自动命名出现 | < 500ms 后台异步 |
+
+## 自动命名规则
+
+调用 AI 一次额外的轻量请求:
+```
+prompt: "用 5-15 字概括以下对话主题,只回答主题:\n用户: <第一条消息>\nAI: <第一条回复>"
+model: 用 haiku 或当前供应商最便宜的模型(降本)
+```
+
+失败 fallback: 取用户首条消息前 20 字 + "..."