diff --git a/README.md b/README.md
index 46bf5dd..1020331 100644
--- a/README.md
+++ b/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 接入模式为一等公民
diff --git a/docs/design/ui/README.md b/docs/design/ui/README.md
new file mode 100644
index 0000000..37516cf
--- /dev/null
+++ b/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 思考中" 的视觉反馈线框?
+- [ ] 是否需要补 "设置 → 隐私" 页(数据收集/上报开关)?
diff --git a/docs/design/ui/cross-platform-constraints.md b/docs/design/ui/cross-platform-constraints.md
new file mode 100644
index 0000000..806e99b
--- /dev/null
+++ b/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 / 流程
+- 删约束 → 在本文末尾追加 "已废止" 段,保留历史
diff --git a/docs/design/ui/interaction-flows/01-flow-new-conversation.md b/docs/design/ui/interaction-flows/01-flow-new-conversation.md
new file mode 100644
index 0000000..2be9060
--- /dev/null
+++ b/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 字 + "..."
diff --git a/docs/design/ui/interaction-flows/02-flow-env-check-fail.md b/docs/design/ui/interaction-flows/02-flow-env-check-fail.md
new file mode 100644
index 0000000..abe3ab2
--- /dev/null
+++ b/docs/design/ui/interaction-flows/02-flow-env-check-fail.md
@@ -0,0 +1,102 @@
+# Flow 02 · 环境检查失败的兜底引导
+
+> 任何时机检测到环境问题(启动 / hover 状态栏 / 跑命令前)的统一处理。
+
+## 主流程
+
+```mermaid
+flowchart TD
+    A[触发环境检查] --> B[并行检查所有依赖]
+    B --> C{结果分类}
+
+    C -- 全绿 --> C1[状态栏显示 ✅]
+    C -- 有 ⚠️ 但无 ❌ --> D[状态栏黄色,允许继续]
+    C -- 有 ❌ --> E[状态栏红色,关键操作禁用]
+
+    D --> D1{用户操作}
+    D1 -- 忽略 --> D2[继续工作,状态栏持续黄]
+    D1 -- 点 [▶ 修复] --> F[进入修复流程]
+
+    E --> E1[禁用'发送消息'按钮]
+    E --> E2[弹一次性 banner: '环境损坏,功能受限']
+    E1 --> F
+
+    F[修复流程] --> F1{依赖类型}
+    F1 -- npm 包 (Claude Code 等) --> F2[内置一键安装]
+    F1 -- 系统命令 (xcode-select 等) --> F3[显示命令 + 复制按钮]
+    F1 -- 系统包 (apt/brew/winget 等) --> F4[显示对应包管理器命令]
+
+    F2 --> G[打开内置终端面板,实时显示输出]
+    G --> G1{安装结果}
+    G1 -- 成功 --> H[自动重测,显示 ✅]
+    G1 -- 失败 --> G2[显示错误日志 + '复制错误' + '重试' + '查文档']
+    G2 --> F1
+
+    F3 --> I[等待用户去外部终端跑]
+    F3 --> I1[显示 '已运行?' 按钮]
+    I1 -- 点击 --> J[重测]
+
+    F4 --> I
+    H --> K[关修复对话框,状态栏更新]
+    J --> K
+```
+
+## 修复对话框线框图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🔧 修复环境问题                                          ✕     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  发现 2 个问题,正在协助修复:                                       │
+│                                                                 │
+│  ❌ Claude Code 未安装                                            │
+│     需要: @anthropic-ai/claude-code 全局安装                     │
+│     [▶ 一键安装]                                                  │
+│                                                                 │
+│  ❌ Xcode CLT 未安装 (macOS)                                      │
+│     需要: 系统命令工具                                             │
+│     [📋 复制命令: xcode-select --install]                         │
+│     ⚠️ 此项需在外部终端执行,完成后点 [✓ 已运行,重测]              │
+│                                                                 │
+│  ─────────────────────────────────────────────────────────     │
+│  内置终端                                                        │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │ $ npm install -g @anthropic-ai/claude-code               │  │
+│  │ npm WARN deprecated ...                                  │  │
+│  │ added 234 packages in 12s                                │  │
+│  │ ✅ 安装完成,版本 v1.2.3                                  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                                                                 │
+│                         📋 复制日志    重新检查   关闭          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 不打扰原则
+
+- **启动时**: 不主动弹模态,只在状态栏标色,用户主动点才修复
+- **跑命令前**: 如果命令依赖某个缺失项,弹模态;否则放行
+- **常驻提示**: 每天最多 1 次顶部 banner,点 ✕ 关闭后当天不再提
+- **修复成功**: 不打扰,只更新状态栏,2 秒淡入淡出 ✅ 提示
+
+## 修复脚本来源
+
+每种依赖的修复命令定义在 `tools/cross-platform/scripts/fixes/<dependency>.json`:
+
+```json
+{
+  "name": "Claude Code",
+  "check": "claude --version",
+  "minVersion": "1.0.0",
+  "install": {
+    "darwin": ["npm", "install", "-g", "@anthropic-ai/claude-code"],
+    "linux": ["npm", "install", "-g", "@anthropic-ai/claude-code"],
+    "win32": ["npm.cmd", "install", "-g", "@anthropic-ai/claude-code"]
+  },
+  "manualHint": {
+    "darwin": "xcode-select --install"
+  }
+}
+```
+
+应用启动加载这个目录,自动构建检查清单 + 修复策略。
diff --git a/docs/design/ui/interaction-flows/03-flow-slash-command.md b/docs/design/ui/interaction-flows/03-flow-slash-command.md
new file mode 100644
index 0000000..9dace96
--- /dev/null
+++ b/docs/design/ui/interaction-flows/03-flow-slash-command.md
@@ -0,0 +1,101 @@
+# Flow 03 · 斜杠命令调用 + 自动补全 + 执行
+
+> 输入框首字符 `/` 触发命令面板,选命令,补参数,执行。
+
+## 主流程
+
+```mermaid
+flowchart TD
+    A[输入框获焦] --> B{首字符输入 '/'}
+    B -- 是 --> C[弹命令面板,默认显示最近 + 全部]
+    B -- 否,中间输入 / --> C0[不触发,普通字符]
+
+    C --> D{用户操作}
+    D -- 继续输入字符 --> E[模糊搜索过滤,更新列表]
+    D -- ↑↓ --> F[在列表中导航]
+    D -- esc --> G[关面板,保留 '/xxx' 在输入框]
+    D -- ↵ 选中项 --> H{选中命令是否有必填参数?}
+
+    E --> D
+    F --> D
+
+    H -- 无必填 --> M[直接执行]
+    H -- 有必填 --> I[切到参数补齐界面]
+
+    I --> I1[显示参数表单<br/>必填/可选分组]
+    I1 --> I2{用户操作}
+    I2 -- 填写参数 --> I3[实时预览生成的命令行]
+    I2 -- ⌘↵ --> J[校验参数完整性]
+    I2 -- esc --> I4[回到命令列表]
+
+    J -- 必填缺 --> J1[红色高亮缺失项]
+    J -- 通过 --> M[执行]
+
+    M --> N[输入框关闭面板,光标失焦]
+    N --> N1[在聊天流插入 '⚙ 12:42 · /xxx ...' 系统消息]
+    N1 --> O[后台跑命令,显示 spinner]
+    O --> P{执行结果}
+    P -- 成功 --> P1[替换 spinner 为输出 + 操作按钮]
+    P -- 失败 --> P2[显示错误 + 重试 / 复制错误 / 查文档]
+```
+
+## 参数补齐表单设计
+
+参数类型 → UI 控件:
+
+| 类型 | UI |
+|------|-----|
+| `string` | 单行输入框 |
+| `text` | 多行 textarea |
+| `enum` (limited choices) | radio group |
+| `boolean` | checkbox |
+| `file` | 输入框 + 浏览按钮(系统文件对话框) |
+| `dir` | 同 file,但只选目录 |
+| `number` | 数字输入,带 min/max 校验 |
+
+## 命令元数据来源
+
+```js
+// tools/cli/commands/init.js
+/**
+ * @command init
+ * @description 按接入模式起项目
+ * @category project
+ * @param {enum:A,B,C,D} mode 接入模式 (必填)
+ * @param {string} name 项目名 (必填)
+ * @param {dir} dir 目标目录 (可选,默认当前)
+ */
+```
+
+应用启动时扫描 `tools/cli/commands/*.js`,解析 JSDoc 头建命令注册表。
+新增 CLI 子命令 → GUI 自动支持,无需改 GUI 代码。
+
+## 输出渲染
+
+命令输出在聊天流中以特殊样式呈现:
+
+```
+⚙ 12:42  ·  /init --mode=B --name=payment-service
+   ✅ 已初始化 B 模式项目: ./payment-service
+      复制 4 个文件
+      下一步: cd payment-service && cat README.md
+
+   [📂 在 Finder 中打开]   [📋 复制路径]   [📤 发送到 AI 评审]
+```
+
+按钮:
+- **在 Finder/资源管理器中打开**: 平台原生
+- **复制路径**: 剪贴板
+- **发送到 AI 评审**: 把命令输出作为消息发给 AI,常用于 "看 metrics 后让 AI 解读"
+
+## 性能与限制
+
+- 命令面板打开延迟 < 50ms (本地索引)
+- 模糊搜索 < 20ms
+- 命令执行有 30s 超时,超时显示 "进程未结束,继续等待 / 取消"
+- 同一会话内可并发跑多个命令(各自独立 spinner)
+
+## 历史 / 收藏
+
+- 最近用 5 条持久化(本地)
+- 用户可右键命令 → "收藏"(收藏的命令永远在列表前部)
diff --git a/docs/design/ui/interaction-flows/04-flow-artifact-detect.md b/docs/design/ui/interaction-flows/04-flow-artifact-detect.md
new file mode 100644
index 0000000..d99df32
--- /dev/null
+++ b/docs/design/ui/interaction-flows/04-flow-artifact-detect.md
@@ -0,0 +1,112 @@
+# Flow 04 · AI 输出 → 自动识别为 Artifact
+
+> AI 流式输出代码块/Markdown/JSON 等结构化内容时,自动抽取为 Artifact,加进右栏。
+
+## 主流程
+
+```mermaid
+flowchart TD
+    A[AI 开始流式输出] --> B[逐 chunk 喂给 ArtifactDetector]
+    B --> C{检测器实时判断}
+    C -- 普通文本 --> C1[正常渲染到聊天流]
+    C -- 检测到代码块 ``` --> D[判断语言 + 内容长度]
+    C -- 检测到 Markdown 长文本 --> E[判断是否独立文档]
+    C -- 检测到 JSON / YAML --> F[判断是否完整结构]
+
+    D --> D1{是否值得 artifact 化?}
+    D1 -- 否 (短代码 < 5 行) --> C1
+    D1 -- 是 --> G[在聊天流插入 Artifact 占位卡]
+
+    E --> E1{是否独立文档?}
+    E1 -- 是 (有标题 + 章节) --> G
+    E1 -- 否 --> C1
+
+    F --> F1{结构完整?}
+    F1 -- 是 --> G
+    F1 -- 否 --> C1
+
+    G --> H[Artifact 进入右栏列表,顶部高亮]
+    H --> I[流式继续,Artifact 内容增量更新]
+    I --> J[流结束]
+    J --> K[Artifact 自动命名]
+    K --> L[首次有 artifact 时,右栏自动展开]
+```
+
+## 抽取规则
+
+### 4.1 代码块
+
+- 触发: ` ``` ` fenced code block
+- 长度门槛: ≥ 5 行 OR ≥ 200 字符
+- 文件名提取: 优先从 ```language:filename 提取,否则用 `<lang>-<时间戳>.<ext>`
+- 例外: 单行命令(如 `` `npm install` ``)不抽取
+
+### 4.2 Markdown 文档
+
+- 触发: 检测到首行 `# `(一级标题) + 至少 1 个 `## `(二级标题)
+- 长度门槛: ≥ 50 行 OR ≥ 1000 字符
+- 文件名: 从 H1 标题转换(slug)+ `.md`
+
+### 4.3 结构化数据
+
+- JSON: 完整对象 `{...}`,长度 ≥ 100 字符
+- YAML: `---` 起始或显著缩进结构
+- CSV: 显著表格结构
+
+## 视觉反馈
+
+```
+聊天流中:                                    右栏 Artifacts:
+
+🤖 11:33                                     ▾ user-stories.md  ← 新加,1.5s
+  我帮你拆成 8 条 user story:                   📋 8 条 · 4KB
+                                                生成于 11:35
+  ┌──────────────────────────────────────┐
+  │ 📄 user-stories.md                    │
+  │ 8 条 user story · 已添加到右栏         │
+  │ [👁 查看] [📋 复制] [💾 保存到文件]    │
+  └──────────────────────────────────────┘
+
+  生成完成。详见右侧。
+```
+
+## 占位卡的状态
+
+```mermaid
+stateDiagram-v2
+    [*] --> Streaming: AI 开始流式输出代码/Markdown
+    Streaming --> Streaming: 内容增量更新
+    Streaming --> Complete: 流结束
+    Streaming --> Cancelled: 用户取消生成
+    Complete --> Renamed: 自动命名
+    Renamed --> [*]
+    Cancelled --> [*]: 占位卡删除,流式内容仍在聊天流
+```
+
+## 用户选项
+
+设置 → General 提供:
+- `[✓] 自动 Artifact 化 AI 输出`(默认开)
+- 长度阈值可调
+
+如果关掉,所有代码/文档都直接渲染在聊天流,右栏永远空。
+
+## Artifact 类型与图标
+
+| 类型 | 扩展名 | 图标 | 大纲 |
+|------|--------|------|------|
+| Markdown | .md | 📄 | 标题 |
+| JavaScript / TypeScript | .js .ts | 💛 / 🔷 | function/class/export |
+| Python | .py | 🐍 | def/class |
+| JSON / YAML | .json .yml | { | 顶层 keys |
+| HTML | .html | 🌐 | DOM 结构 |
+| 图表 (mermaid) | .mmd | 📊 | 节点 |
+| 通用 | .txt | 📝 | 无 |
+
+## 与 Phase 1 的关系
+
+抽取逻辑已有 `app/ClaudeCodeHistory/ArtifactDetector.swift` 雏形。本设计稿明确:
+
+- 把"长度门槛"统一(原 Swift 版只检测代码块)
+- 加 Markdown 文档抽取
+- 流式更新 Artifact 内容(原 Swift 版仅在流结束时抽)
diff --git a/docs/design/ui/interaction-flows/05-flow-provider-switch.md b/docs/design/ui/interaction-flows/05-flow-provider-switch.md
new file mode 100644
index 0000000..ed729e2
--- /dev/null
+++ b/docs/design/ui/interaction-flows/05-flow-provider-switch.md
@@ -0,0 +1,124 @@
+# Flow 05 · 会话中切换供应商的影响处理
+
+> 这是个潜在风险操作 —— 切换不当会丢上下文 / 增费用。流程要明确预警 + 给安全默认。
+
+## 主流程
+
+```mermaid
+flowchart TD
+    A[用户触发切换] -->|顶栏点击 / ⌘⇧P| B[弹切换浮层 wireframe-06]
+    B --> C{用户选择}
+    C -- esc / 关闭 --> Z[无操作,返回]
+    C -- 选目标供应商 --> D{勾选 '在新会话中切换'?}
+
+    D -- 是 (默认,推荐) --> E[创建新会话]
+    E --> E1[新会话默认供应商 = 目标]
+    E1 --> E2{当前会话有未发消息?}
+    E2 -- 是 --> E3[把未发消息复制到新会话输入框]
+    E2 -- 否 --> E4[新会话空状态]
+    E3 --> F[侧边栏选中新会话,中栏切换]
+    E4 --> F
+
+    D -- 否 (高级) --> G[弹二次确认对话框]
+    G --> G1[显示风险:<br/>- 上下文丢失<br/>- 可能费用增加<br/>- 回复偏离]
+    G1 --> G2{用户输入 '切换' 确认}
+    G2 -- 取消 --> Z
+    G2 -- 确认 --> H[当前会话切换供应商]
+
+    H --> H1[聊天流插入 '⚙ 已切换到 X' 系统消息]
+    H1 --> H2[顶栏供应商显示更新]
+    H2 --> H3[token 计数器重置 0]
+    H3 --> I{下一条消息发送时}
+    I --> J{新供应商是否需要重塑上下文?}
+    J -- 是 (大多数情况) --> K[把历史消息以 system 消息发给新供应商]
+    J -- 否 (兼容协议) --> L[直接发当前消息]
+    K --> M[新供应商回复]
+    L --> M
+```
+
+## "重塑上下文" 详细策略
+
+```mermaid
+flowchart TD
+    A[切换后第一次发消息] --> B[计算历史消息 token 数]
+    B --> C{是否超过新供应商上下文窗口?}
+    C -- 否,全部塞得下 --> D[把全部历史 + 新消息一次发出]
+    C -- 是,塞不下 --> E[摘要压缩:<br/>用便宜模型把早期消息压成摘要]
+    E --> F[摘要 + 最近 N 条原文 + 新消息发出]
+    F --> G{压缩后仍超?}
+    G -- 是 --> H[弹模态: '上下文超长,需截断或新建']
+    G -- 否 --> I[正常发送]
+```
+
+## 状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle: 会话稳定状态
+    Idle --> Switching: 用户触发切换浮层
+    Switching --> Idle: 取消
+    Switching --> NewConversation: 选'在新会话中切换'
+    Switching --> Confirming: 选'在当前会话中切换'
+    Confirming --> Idle: 取消
+    Confirming --> InCurrent: 输入'切换'确认
+    InCurrent --> Reshaping: 下次发消息时
+    Reshaping --> Idle: 重塑成功
+    Reshaping --> Failed: 重塑失败 (超长 / API 错)
+    Failed --> Idle: 用户决定下一步 (截断 / 新建 / 取消)
+    NewConversation --> [*]: 已转移到新会话
+```
+
+## 切换的用户消息
+
+切换的系统消息样式:
+
+```
+⚙ 12:51  · 切换供应商
+   Anthropic Claude opus  →  AWS Bedrock claude-opus-4-v1
+
+   📊 影响:
+   • 历史 156k tokens 将以摘要形式重塑
+   • 预估额外费用: $0.18 (摘要 + 重塑)
+
+   [📋 看摘要预览]   [🔙 撤销切换]
+```
+
+撤销窗口: 3 分钟内可点 "🔙 撤销切换" 回到原供应商,撤销后系统消息标 "已撤销"。
+
+## 用户教育
+
+第一次用户做 "在当前会话切换" 时:
+
+```
+        ┌──────────────────────────────────────────────┐
+        │  💡 高级操作 · 仅这一次提示                    │
+        ├──────────────────────────────────────────────┤
+        │                                               │
+        │  你正在做"会话内切换",这是一个高级操作。      │
+        │                                               │
+        │  大多数情况下,"在新会话中切换"更安全:           │
+        │  ✓ 不丢历史                                    │
+        │  ✓ 无重塑费用                                  │
+        │  ✓ 回复方向更稳定                              │
+        │                                               │
+        │  会话内切换适合: 临时尝试不同模型对比同一问题    │
+        │                                               │
+        │  [✓] 知道了,不再提示                           │
+        │                              继续切换 →        │
+        └──────────────────────────────────────────────┘
+```
+
+## 失败处理
+
+切换后第一次发送失败的处理:
+
+| 失败类型 | 行为 |
+|---------|------|
+| API 401/403 | 弹模态 "新供应商鉴权失败,要回退到原供应商吗?" |
+| 上下文超长 | 弹模态 "无法重塑全部上下文,选择: 截断早期 50% / 新建会话 / 切回原" |
+| 网络 | 重试 3 次,仍失败弹 "切换可能未生效,看右上状态" |
+
+## 与 Sprint 1-5 的对接
+
+- 切换日志写入会话历史 JSON,key: `provider_switches: [{ timestamp, from, to, reshape_strategy }]`
+- 度量脚本 `tools/metrics/development/collect.js` 可加新维度: 周内供应商切换次数(衡量稳定性)
diff --git a/docs/design/ui/wireframes/01-main-three-pane.md b/docs/design/ui/wireframes/01-main-three-pane.md
new file mode 100644
index 0000000..b3717b6
--- /dev/null
+++ b/docs/design/ui/wireframes/01-main-three-pane.md
@@ -0,0 +1,79 @@
+# Wireframe 01 · 主视图(三栏)
+
+> 应用启动后默认进入这里。三栏布局:左会话列表 / 中聊天区 / 右 Artifact 面板。
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│  EP Code AI                                            [Anthropic ▾]  ⚙   ─ □ ✕   │①
+├──────────────┬───────────────────────────────────────────────┬─────────────────────┤
+│ 🔍 搜索...    │  会话: 「需求评审 - 离职流程」          📌 ⋮  │  📦 Artifacts (2)  │②
+│  ⌘K          │  Anthropic Claude · opus · 156k tok / 200k    │                     │
+│              │ ─────────────────────────────────────────────│  ▾ prd-v1.2.md      │
+│ ▼ 今天 (3)    │                                                │  📄 132 行 · 2KB     │
+│ ● 需求评审    │  👤 11:32                                       │  生成于 11:34        │
+│ ○ Bug-1024    │     帮我把 prd-v1.2.md 拆成 user story         │                     │③
+│ ○ 部署 SOP    │     [📎 prd-v1.2.md 132 行]                    │  ▾ user-stories.md  │
+│              │                                                │  📋 8 条 · 4KB       │
+│ ▼ 昨天 (2)    │  🤖 11:33  · 思考 12s · 输出 2.3k tokens       │  生成于 11:35        │
+│ ○ 度量周报    │     已读 prd-v1.2.md(132 行)。识别出 8 个用户   │                     │
+│ ○ ADR-002     │     场景,按 INVEST 拆成 8 条 user story:       │  ─────────────      │
+│              │                                                │   下载所有           │
+│ ▼ 4-15 周一   │     1. 员工提交离职申请                          │   导出 .zip          │
+│ ○ 设计评审    │     2. HR 审核基本资料                           │                     │
+│              │     3. ...                                       │                     │
+│ ▼ 收藏 ⭐ (1) │                                                │                     │
+│ ⭐ 故障复盘    │     已生成 → user-stories.md (右侧已添加)        │                     │
+│              │                                                │                     │
+│ ─────────    │  👤 11:36                                       │                     │
+│ + 新会话 ⌘N   │     [输入中...]                                  │                     │
+│              │                                                │                     │
+│              │ ─────────────────────────────────────────────│                     │
+│              │  [/]      [📎]      [⚡ opus]               ⌘↵ │④
+│              │  ┌──────────────────────────────────────┐  │                     │
+│              │  │ 输入消息(⌘↵ 发送 / shift+↵ 换行)... │  │                     │
+│              │  └──────────────────────────────────────┘  │                     │
+├──────────────┴───────────────────────────────────────────────┴─────────────────────┤
+│  ✅ 环境正常 · Node v20 / Claude Code v1.2.3        ●  连接正常 · 延迟 240ms      │⑤
+└──────────────────────────────────────────────────────────────────────────────────┘
+   240px         ←──────  flex,占满 ──────→                       320px(可拖拽)
+```
+
+## 元素说明
+
+| # | 元素 | 行为 |
+|---|------|------|
+| ① | 顶栏 · 供应商切换 | 点 `[Anthropic ▾]` 弹切换浮层(见 wireframe-06)。`⚙` 开设置(wireframe-03) |
+| ② | 中栏标题区 | 显示当前会话名 + 模型 + token 用量。`📌` 收藏切换;`⋮` 弹更多操作(改名/导出/删) |
+| ③ | 右栏 Artifacts | 列出本会话产生的所有 Artifact。可折叠/展开。无 Artifact 时整个右栏自动折起 |
+| ④ | 底部输入栏 | `/` 触发命令面板(wireframe-04);`📎` 附件;`⚡` 切模型(本会话内);`⌘↵` 发送 |
+| ⑤ | 状态栏 | 持久显示环境健康 + 网络状态(wireframe-10) |
+
+## 三栏宽度
+
+- 左侧 240px(可在 200-360 拖拽,记忆)
+- 右侧 320px(可在 280-500 拖拽;无 Artifact 自动 0px)
+- 中间 flex(min 480px,小于则强制折叠左/右)
+
+## 响应式
+
+| 窗口宽度 | 行为 |
+|---------|------|
+| `≥ 1280` | 三栏全开 |
+| `1024 - 1280` | 右栏自动折叠成抽屉(图标按钮唤起) |
+| `768 - 1024` | 左栏也折叠,变成移动版双层抽屉 |
+| `< 768` | (不支持,强制最小窗口 768) |
+
+## 会话列表分组
+
+按以下顺序固定:
+1. **收藏**(⭐ 标记的,任何时候置顶)
+2. **今天 / 昨天 / 本周** (按最后活动时间)
+3. **本月 / 更早** (按月分组)
+
+每组可折叠。计数显示在组名旁。
+
+## 空状态
+
+- 无会话: 中栏显示欢迎卡 + "+ 新会话 ⌘N" 大按钮
+- 无 Artifact: 右栏完全折叠,不显示空白
+- 详见 wireframe-09
diff --git a/docs/design/ui/wireframes/02-setup-wizard.md b/docs/design/ui/wireframes/02-setup-wizard.md
new file mode 100644
index 0000000..73ac79f
--- /dev/null
+++ b/docs/design/ui/wireframes/02-setup-wizard.md
@@ -0,0 +1,134 @@
+# Wireframe 02 · 首次启动向导
+
+> 用户首次打开应用时强制进入。4 步,每步可"跳过"(标记为待修复),全部完成后进主视图。
+
+## 步骤 1 / 4 · 欢迎 + 主题
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Setup · 第 1 步 / 共 4 步                          ✕ 跳过引导   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│                       👋  欢迎使用                                │
+│                       EP Code AI                                 │
+│                                                                 │
+│       覆盖业务 · 开发 · 测试 · 运维 四大场景的 Claude 增强生态     │
+│                                                                 │
+│   ─────────────────────────────────────────────────────────     │
+│                                                                 │
+│   🎨 选择主题                                                     │
+│                                                                 │
+│      ┌─────────┐  ┌─────────┐  ┌─────────┐                      │
+│      │  浅色    │  │ ● 深色  │  │ 跟随系统 │                      │
+│      └─────────┘  └─────────┘  └─────────┘                      │
+│                                                                 │
+│   📍 应用语言                                                     │
+│      [中文 ▾]    (其他: English)                                  │
+│                                                                 │
+│                                                                 │
+│                                              下一步 ▶            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 步骤 2 / 4 · 环境检查
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Setup · 第 2 步 / 共 4 步                          ✕ 跳过       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   🔍 正在检查运行环境...                                          │
+│                                                                 │
+│   ✅  Node.js                v20.10.0    满足(需要 ≥ 18)         │
+│   ✅  npm                    v10.2.3                             │
+│   ✅  git                    v2.42.0                             │
+│   ⚠️   Claude Code           未安装                              │
+│       └─ [▶ 一键安装(运行 npm install -g @anthropic-ai/claude-code)] │
+│                                                                 │
+│   ❌  Xcode CLT             未检测到 (macOS 专属)                │
+│       └─ 终端运行: xcode-select --install                        │
+│       └─ [📋 复制命令]                                            │
+│                                                                 │
+│   ─────────────────────────────────────────────────────────     │
+│   [详细日志 ⌃]                                                   │
+│                                                                 │
+│                            ◀ 上一步     重新检测     下一步 ▶    │
+│                                                  (灰色)         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 步骤 3 / 4 · 配置供应商
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Setup · 第 3 步 / 共 4 步                          ✕ 跳过       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   ⚡ 配置 AI 供应商                                                │
+│                                                                 │
+│   选择类型:                                                       │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │ ● Anthropic 官方   ○ AWS Bedrock   ○ Google Vertex      │   │
+│   │ ○ 第三方代理(自定义 endpoint)                           │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+│   API Key                                                       │
+│   ┌─────────────────────────────────────────────────────┐  👁  │
+│   │ sk-ant-xxx ······                                   │      │
+│   └─────────────────────────────────────────────────────┘      │
+│                                                                 │
+│   默认模型     [claude-opus-4 ▾]                                 │
+│                                                                 │
+│   ─────────────────────────────────────────────────────────     │
+│                                                                 │
+│   [🔗 测试连接]                                                   │
+│   ✅ 连接成功 · 延迟 220ms · 账号余额 $42.18                      │
+│                                                                 │
+│                            ◀ 上一步                  下一步 ▶    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 步骤 4 / 4 · 完成
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Setup · 第 4 步 / 共 4 步                                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│                       🎉  设置完成                                │
+│                                                                 │
+│   你已就绪。EP Code AI 把 Claude 与四大场景方法论结合,            │
+│   建议从这里开始:                                                  │
+│                                                                 │
+│   ┌─────────────────────┐  ┌─────────────────────┐              │
+│   │  🆕 创建第一个会话    │  │  📚 看 5 分钟教程    │              │
+│   │   (跳到主视图)       │  │   (打开文档站)      │              │
+│   └─────────────────────┘  └─────────────────────┘              │
+│                                                                 │
+│   ─────────────────────────────────────────────────────────     │
+│                                                                 │
+│   提示                                                           │
+│   • 用 `/` 触发命令面板(写 PRD / 跑 ADR / 看度量等)              │
+│   • 用 `⌘K` 全局搜索历史会话                                      │
+│   • 设置入口: 顶栏齿轮 ⚙ 或 `⌘,`                                 │
+│                                                                 │
+│                                          ▶ 进入应用              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 关键交互
+
+| 步骤 | 行为 |
+|------|------|
+| 任意步 | 右上 `✕ 跳过引导`: 标记 setup 状态为"未完成",下次启动仍提示 |
+| 步骤 2 | 一键安装按钮内嵌 Claude Code 安装命令,输出实时日志在折叠区 |
+| 步骤 2 | "下一步" 在有 ❌ 时禁用;有 ⚠️ 但无 ❌ 时可继续(警告 toast) |
+| 步骤 3 | API Key 输入框默认遮蔽,👁 切显隐;支持粘贴 |
+| 步骤 3 | 测试连接前 "下一步" 禁用,确保 API Key 有效后才放行 |
+| 步骤 4 | 选 "创建第一个会话" 跳到主视图并自动 + 新会话 |
+
+## 跳过的影响
+
+- **步骤 2 跳过**: 主视图状态栏显示 ⚠️ 红色 "环境未配置",点击重开向导
+- **步骤 3 跳过**: 主视图无法发消息,顶栏供应商显示 "未配置 ⚠️",点击跳到配置
+- **步骤 4 跳过**: 直接进主视图,行为与"进入应用"等同
diff --git a/docs/design/ui/wireframes/03-settings.md b/docs/design/ui/wireframes/03-settings.md
new file mode 100644
index 0000000..4591ddd
--- /dev/null
+++ b/docs/design/ui/wireframes/03-settings.md
@@ -0,0 +1,126 @@
+# Wireframe 03 · 设置页
+
+> `⌘,` / `Ctrl+,` 唤起。Modal 居中,可拖拽窗口 / 关闭。
+
+## 整体结构
+
+4 个 tab,左侧导航条,右侧内容区。
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  设置                                                          ✕    │
+├──────────────┬──────────────────────────────────────────────────────┤
+│ ● General    │  General · 通用设置                                   │
+│ ○ Provider   │ ────────────────────────────────────────────────     │
+│ ○ Shortcuts  │                                                       │
+│ ○ Experimental │  外观                                                │
+│              │   主题       [深色 ▾]   (浅 / 深 / 跟随系统)            │
+│              │   字号       [中 ▾]     (小 / 中 / 大)                 │
+│              │   字体       [系统默认 ▾]                              │
+│              │                                                       │
+│              │  会话                                                 │
+│              │   自动命名     [✓] 让 AI 根据首条消息生成会话名         │
+│              │   自动归档     [✓] 30 天未活动会话自动归档              │
+│              │   保留时长     [永久 ▾]                                │
+│              │                                                       │
+│              │  通知                                                 │
+│              │   AI 回复完成   [✓] 系统通知                           │
+│              │   长任务完成    [✓] 仅当应用在后台                      │
+│              │                                                       │
+│              │  数据                                                 │
+│              │   导出会话    [📦 导出全部 .zip]                        │
+│              │   清空数据    [🗑 清空全部本地数据]    (有二次确认)       │
+│              │                                                       │
+│              │ ─────────────────────────────────────────────────    │
+│              │                              取消    应用    保存      │
+└──────────────┴──────────────────────────────────────────────────────┘
+```
+
+## Tab 2 · Provider
+
+```
+│ ○ General    │  Provider · 供应商管理                                │
+│ ● Provider   │ ────────────────────────────────────────────────     │
+│              │                                                       │
+│              │  已配置的供应商 (2)                          [+ 添加]   │
+│              │                                                       │
+│              │  ┌───────────────────────────────────────────────┐  │
+│              │  │ ● Anthropic 官方 (默认)                  ⋮     │  │
+│              │  │   sk-ant-····xxxx     · 余额 $42.18           │  │
+│              │  │   默认模型: claude-opus-4                       │  │
+│              │  │   连接: ✅ 220ms                                │  │
+│              │  └───────────────────────────────────────────────┘  │
+│              │                                                       │
+│              │  ┌───────────────────────────────────────────────┐  │
+│              │  │ ○ AWS Bedrock                            ⋮     │  │
+│              │  │   role: arn:aws:iam:... · region: us-east-1   │  │
+│              │  │   默认模型: anthropic.claude-opus-4-v1         │  │
+│              │  │   连接: ⚠️ 上次失败 (1 小时前)                 │  │
+│              │  └───────────────────────────────────────────────┘  │
+│              │                                                       │
+│              │  ⋮ 菜单: 编辑 / 测试连接 / 设为默认 / 删除                │
+```
+
+## Tab 3 · Shortcuts
+
+```
+│              │  Shortcuts · 快捷键                                   │
+│              │ ────────────────────────────────────────────────     │
+│              │                                                       │
+│              │  搜索快捷键... [_______]                               │
+│              │                                                       │
+│              │  会话                                                 │
+│              │   新建会话           ⌘N         [编辑]                 │
+│              │   关闭当前会话       ⌘W         [编辑]                 │
+│              │   重命名当前会话     ⌘R         [编辑]                 │
+│              │   切换上一个会话     ⌘[         [编辑]                 │
+│              │                                                       │
+│              │  导航                                                 │
+│              │   全局搜索           ⌘K         [编辑]                 │
+│              │   设置               ⌘,         [编辑]                 │
+│              │   切换供应商         ⌘⇧P        [编辑]                 │
+│              │                                                       │
+│              │  输入                                                 │
+│              │   命令面板           /          (固定,不可改)          │
+│              │   发送消息           ⌘↵         [编辑]                 │
+│              │   换行              ⇧↵          (固定)                │
+│              │                                                       │
+│              │  [恢复默认]                                            │
+```
+
+## Tab 4 · Experimental
+
+```
+│              │  Experimental · 实验性功能 ⚗️                          │
+│              │ ────────────────────────────────────────────────     │
+│              │                                                       │
+│              │  ⚠️ 以下功能不稳定,启用前请知悉风险                    │
+│              │                                                       │
+│              │  [✗] AI 长上下文优化 (256k → 1M tokens)                │
+│              │       beta · 可能更慢、更贵                            │
+│              │                                                       │
+│              │  [✗] 多模态输入(图片 / PDF)                          │
+│              │       alpha · 部分供应商不支持                        │
+│              │                                                       │
+│              │  [✓] 命令面板模糊搜索                                 │
+│              │       beta · 已开启,如有问题可关                      │
+│              │                                                       │
+│              │  [✗] 离线模式(本地模型)                              │
+│              │       概念验证 · 需 16GB+ 内存                        │
+│              │                                                       │
+│              │  [✗] 调试面板(F12)                                   │
+│              │       开发者用                                         │
+│              │                                                       │
+│              │  ─────────────────────────────────────────────       │
+│              │  日志                                                 │
+│              │   日志级别     [info ▾]                                │
+│              │   [📁 打开日志目录]                                     │
+```
+
+## 关键交互
+
+- 切换 tab 时不丢已修改未保存的内容(顶部 banner 提示"有未保存更改")
+- "保存" 按钮在有改动时高亮,无改动时灰色
+- "取消" 关闭并丢弃改动,有改动时弹确认框
+- 任何会影响连接的更改(API Key、Endpoint)保存后自动重测连接
+- "清空全部本地数据" 二次确认要求输入 `DELETE` 确认
diff --git a/docs/design/ui/wireframes/04-slash-command-palette.md b/docs/design/ui/wireframes/04-slash-command-palette.md
new file mode 100644
index 0000000..694090b
--- /dev/null
+++ b/docs/design/ui/wireframes/04-slash-command-palette.md
@@ -0,0 +1,109 @@
+# Wireframe 04 · 斜杠命令面板
+
+> 输入框首字符输入 `/` 触发。浮层覆盖输入框上方,Spotlight 风格。
+
+## 默认状态
+
+```
+   ┌─────────────────────────────────────────────────┐
+   │  /  搜索命令...                                 │
+   ├─────────────────────────────────────────────────┤
+   │  🔥 最近使用 (2)                                  │
+   │   /prd <file>          PRD 校验 + 可测性打分     │
+   │   /adr index           重建 ADR 索引             │
+   │  ─────────────────────────────────────────────  │
+   │  📋 全部命令 (10)                                 │
+   │ ► /init <mode>         按接入模式起项目          │
+   │   /adopt --level=N     模式 C 渐进启用          │
+   │   /migrate             模式 B 反向生成 API      │
+   │   /check               跑全部校验                │
+   │   /prd <file>          PRD 校验 + 可测性        │
+   │   /adr <action>        ADR 索引                 │
+   │   /metrics [--since]   生成度量看板              │
+   │   /linkage <type>      跨场景联动               │
+   │   /incident <action>   故障处理                 │
+   │   /jira <action>       Jira 集成                │
+   ├─────────────────────────────────────────────────┤
+   │  ↑↓ 选择   ↵ 执行   esc 取消    [→ 帮助]         │
+   └─────────────────────────────────────────────────┘
+```
+
+## 模糊搜索状态(用户输入了 `/me`)
+
+```
+   ┌─────────────────────────────────────────────────┐
+   │  /me                                             │
+   ├─────────────────────────────────────────────────┤
+   │  📋 匹配 (2)                                      │
+   │ ► /metrics [--since]   生成度量看板              │
+   │   /migrate             模式 B 反向生成 API      │
+   ├─────────────────────────────────────────────────┤
+   │  ↑↓ 选择   ↵ 执行   esc 取消                     │
+   └─────────────────────────────────────────────────┘
+```
+
+## 参数补齐状态(选了 `/init`,弹参数)
+
+```
+   ┌─────────────────────────────────────────────────┐
+   │  /init <mode> --name=<name>                     │
+   ├─────────────────────────────────────────────────┤
+   │  按接入模式起项目                                  │
+   │                                                  │
+   │  mode (必填)                                      │
+   │  ○ A · 绿地项目                                   │
+   │  ● B · 开发中追溯                                  │
+   │  ○ C · 迭代中渐进                                  │
+   │  ○ D · 稳态运维                                    │
+   │                                                  │
+   │  name (必填)                                      │
+   │  ┌──────────────────────────────────────────┐   │
+   │  │ payment-service                         │   │
+   │  └──────────────────────────────────────────┘   │
+   │                                                  │
+   │  dir (可选,默认当前)                               │
+   │  ┌──────────────────────────────────────────┐   │
+   │  │ ./                                       │   │
+   │  └──────────────────────────────────────────┘   │
+   │                                                  │
+   │  ─────────────────────────────────────────────  │
+   │  预览命令                                          │
+   │  $ epcode init --mode=B --name=payment-service   │
+   │                                                  │
+   │  esc 取消    ◀ 返回    ✓ 执行 (⌘↵)               │
+   └─────────────────────────────────────────────────┘
+```
+
+## 执行后输出状态
+
+命令执行结果以特殊消息形式插入聊天流,带"机器执行"图标:
+
+```
+  ⚙ 11:42  · /init --mode=B --name=payment-service
+     ✅ 已初始化 B 模式项目: ./payment-service
+        复制 4 个文件
+        下一步: cd payment-service && cat README.md
+     [📂 在 Finder 中打开]   [📋 复制路径]
+```
+
+## 关键交互
+
+| 触发条件 | 行为 |
+|---------|------|
+| 输入框光标在第一位输入 `/` | 立即弹面板,无延迟 |
+| 输入框中间输入 `/` | **不**触发(避免误触) |
+| 选中后按 ↵ | 如有必填参数,进参数补齐;否则直接执行 |
+| 参数补齐界面按 ⌘↵ | 直接执行(跳过 "✓ 执行" 按钮) |
+| 任何时刻按 esc | 关面板,光标回到输入框,保留已输入的 `/xxx` 文本 |
+| 按 → 或点 "[→ 帮助]" | 在聊天流插入命令的完整 Markdown 帮助 |
+
+## 命令来源
+
+命令面板的清单 = `tools/cli/commands/` 目录扫描结果。新加 CLI 子命令自动出现,无需 GUI 改动。
+
+每个命令的元数据(描述 / 参数定义)从对应 `.js` 文件的 JSDoc 头部提取。
+
+## 历史
+
+- "🔥 最近使用" 持久化到本地,按使用次数排序,Top 5
+- "📋 全部命令" 按字母顺序
diff --git a/docs/design/ui/wireframes/05-artifact-panel-expanded.md b/docs/design/ui/wireframes/05-artifact-panel-expanded.md
new file mode 100644
index 0000000..b786327
--- /dev/null
+++ b/docs/design/ui/wireframes/05-artifact-panel-expanded.md
@@ -0,0 +1,88 @@
+# Wireframe 05 · Artifact 全屏详情
+
+> 在主视图右栏点 Artifact → 全屏展开。可看完整内容、跳转、导出、版本对比。
+
+## 默认展开状态
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  ◀ 返回会话                  prd-v1.2.md             [📋 复制] [💾 导出]  │
+│                              132 行 · 2.1KB                                 │
+├──────────────────────────────────────────────────────────────────────────┤
+│  ◀ 在 6 个 Artifact 中切换 ▶                  v3 (最新) ▾   📜 历史 (3)  │
+├──────────────────┬───────────────────────────────────────────────────────┤
+│  🗂 大纲           │   1  # PRD - 离职流程 v1.2                              │
+│                   │   2                                                     │
+│  ▾ 1. 概述        │   3  ## 1. 概述                                         │
+│   1.1 背景        │   4                                                     │
+│   1.2 目标        │   5  ### 1.1 背景                                       │
+│  ▾ 2. 用户与场景   │   6  公司目前离职流程涉及 5 个部门(HR / 财务 / IT /     │
+│   2.1 角色        │   7  上级 / 行政),平均处理时长 7-10 工作日,员工反馈    │
+│   2.2 主流程      │   8  断点多。                                            │
+│  ▾ 3. 功能需求    │   9                                                     │
+│   3.1 功能清单    │  10  ### 1.2 目标                                       │
+│   3.2 验收标准    │  11  - 端到端处理时长 ≤ 3 工作日                         │
+│  ▶ 4. 非功能需求  │  12  - 关键步骤透明可追溯                                │
+│  ▶ 5. 数据规则    │  13  - 员工 NPS ≥ 60                                    │
+│  ▶ 6. 交互设计    │  14                                                     │
+│  ▶ 7. 风险        │  15  ## 2. 用户与场景                                   │
+│  ▶ 8. 变更历史    │  16                                                     │
+│                   │  ...                                                     │
+│  ─────────       │                                                         │
+│  📊 元数据        │                                                         │
+│  生成: 11:34     │                                                         │
+│  修订: 4 次       │                                                         │
+│  来源: 会话「需求评审」│                                                     │
+│                   │                                                         │
+├──────────────────┴───────────────────────────────────────────────────────┤
+│  📍 跳转到生成时的对话         📤 发送到 Jira     ✨ AI 重新润色           │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## 版本对比模式(用户选 v3 vs v2)
+
+```
+│  ◀ 返回会话           prd-v1.2.md           v2 ↔ v3   [⇆ 反向]  [合并 ▾]  │
+├──────────────────┬─────────────────────────────────────────────────────┤
+│  v2 (3 小时前)    │   v3 (最新 · 11 分钟前)                                 │
+├──────────────────┼─────────────────────────────────────────────────────┤
+│   1  # PRD       │   1  # PRD                                              │
+│   2              │   2                                                     │
+│ - 3  目标:       │ + 3  目标(量化):                                       │
+│ - 4    快速完成   │ + 4  - 端到端时长 ≤ 3 工作日                            │
+│                  │ + 5  - 员工 NPS ≥ 60                                    │
+│   6              │   6                                                     │
+│   7  ## 用户     │   7  ## 用户                                            │
+│   ...            │   ...                                                   │
+└──────────────────┴─────────────────────────────────────────────────────┘
+```
+
+## 关键交互
+
+| 元素 | 行为 |
+|------|------|
+| ◀ 返回会话 | 关闭全屏,回到主视图三栏布局 |
+| 📋 复制 | 复制全文到剪贴板 |
+| 💾 导出 | 弹格式选择: `.md`(原始) / `.pdf`(渲染后) / `.html`(嵌入样式) |
+| ◀▶ 切换 Artifact | 在本会话所有 Artifact 间循环切换 |
+| 版本下拉 | 选历史版本看,选 "对比 v2 ↔ v3" 进入对比模式 |
+| 大纲 | 点击跳到对应行,鼠标 hover 显示行号 |
+| 📍 跳转到生成时对话 | 关全屏 + 滚动聊天到生成这个 artifact 的那条 AI 回复 |
+| 📤 发送到 Jira | 弹 Jira 集成对话框(Project / Type / Summary 预填) |
+| ✨ AI 重新润色 | 在聊天里插入 prompt "请优化以下 Artifact: ..." 并附带 |
+| 合并(对比模式) | 选 "用 v3 替换 v2 / 选区合并 / 创建新版本" |
+
+## 大纲生成
+
+- Markdown: 自动从 `#`-`####` 抽取
+- JSON / YAML: 抽顶层 keys
+- 代码: 抽 function / class / export
+- 其他: 显示 "无大纲"
+
+## 元数据
+
+| 字段 | 来源 |
+|------|------|
+| 生成 | AI 第一次输出这个 artifact 的时间 |
+| 修订 | 后续 AI 改/用户改的次数 |
+| 来源 | 会话名 + 链接(点击关全屏跳到对话) |
diff --git a/docs/design/ui/wireframes/06-provider-switcher.md b/docs/design/ui/wireframes/06-provider-switcher.md
new file mode 100644
index 0000000..63dcaa6
--- /dev/null
+++ b/docs/design/ui/wireframes/06-provider-switcher.md
@@ -0,0 +1,94 @@
+# Wireframe 06 · 供应商切换浮层
+
+> 顶栏点 `[Anthropic ▾]` 或按 `⌘⇧P` / `Ctrl+Shift+P` 触发。
+
+## 浮层
+
+```
+                ┌────────────────────────────────────────┐
+                │  ⚡ 切换供应商                            │
+                ├────────────────────────────────────────┤
+                │  当前会话                                │
+                │   ● Anthropic 官方                      │
+                │     opus · 156k / 200k tok 已用          │
+                ├────────────────────────────────────────┤
+                │  可切换到                                │
+                │ ► ○ AWS Bedrock                         │
+                │     anthropic.claude-opus-4-v1          │
+                │     ✅ 220ms                              │
+                │                                          │
+                │   ○ Google Vertex                        │
+                │     claude-opus-4@vertex                │
+                │     ⚠️  未测连接                          │
+                │                                          │
+                │   ○ 第三方代理                            │
+                │     claude-3-opus (proxy.example.com)    │
+                │     ❌ 上次失败                           │
+                ├────────────────────────────────────────┤
+                │  ─────────────────────────────────────  │
+                │  ⚠️  切换会丢失当前会话的上下文                │
+                │      (新供应商无法看到历史消息)              │
+                │                                          │
+                │  [✓] 在新会话中切换(推荐)                 │
+                │  [ ] 在当前会话中切换(高级)               │
+                │                                          │
+                │  esc 取消    ↵ 切换                      │
+                └────────────────────────────────────────┘
+```
+
+## 切换确认 - 在当前会话中切换
+
+```
+                ┌────────────────────────────────────────┐
+                │  ⚠️  切换确认                             │
+                ├────────────────────────────────────────┤
+                │                                          │
+                │  你正在切换供应商:                          │
+                │  Anthropic 官方  →  AWS Bedrock          │
+                │                                          │
+                │  影响:                                    │
+                │  • 新供应商看不到此会话的 156k tokens 历史  │
+                │  • 可能导致回复偏离原话题                    │
+                │  • 可能产生额外费用(重新读上下文)            │
+                │                                          │
+                │  推荐: 用 "在新会话中切换"                   │
+                │                                          │
+                │  ─────────────────────────────────────  │
+                │  仍要继续? 输入 "切换" 确认                │
+                │  ┌─────────────────────────────────┐    │
+                │  │                                 │    │
+                │  └─────────────────────────────────┘    │
+                │                                          │
+                │  取消                确认(灰色,需输入)    │
+                └────────────────────────────────────────┘
+```
+
+## 关键交互
+
+| 元素 | 行为 |
+|------|------|
+| 当前供应商旁的 ● | 不可选(已选中) |
+| 状态徽章 | 实时反映上次连接结果。点击徽章重测连接 |
+| 默认 "在新会话中切换" | 安全选项,90% 用户用这个 |
+| "在当前会话中切换" | 进入二次确认,要求输入 "切换" 确认 |
+| esc | 关浮层,无操作 |
+| 滚轮 / ↑↓ | 在可切换列表中导航 |
+| ↵ | 按勾选项执行 |
+
+## 切换后的视觉反馈
+
+- 顶栏供应商名 0.5s 淡入淡出更新
+- 中栏标题更新为新供应商 + 模型
+- 在聊天流插入 "⚙ 11:45 · 已切换到 AWS Bedrock" 系统消息
+
+## 没有可切换供应商时
+
+```
+                │  当前会话                                │
+                │   ● Anthropic 官方                      │
+                ├────────────────────────────────────────┤
+                │  无其他可用供应商                          │
+                │                                          │
+                │  [+ 添加供应商]  → 跳到设置 Provider tab  │
+                └────────────────────────────────────────┘
+```
diff --git a/docs/design/ui/wireframes/07-search-overlay.md b/docs/design/ui/wireframes/07-search-overlay.md
new file mode 100644
index 0000000..594b8d0
--- /dev/null
+++ b/docs/design/ui/wireframes/07-search-overlay.md
@@ -0,0 +1,90 @@
+# Wireframe 07 · 全局搜索浮层
+
+> `⌘K` / `Ctrl+K` 触发。Spotlight 风格全局搜索。
+
+## 默认状态(未输入)
+
+```
+        ┌──────────────────────────────────────────────────────────┐
+        │  🔍  搜索会话、消息、Artifact 或命令...                     │
+        ├──────────────────────────────────────────────────────────┤
+        │  最近访问                                                   │
+        │   📁 需求评审 - 离职流程               (会话 · 11 分钟前)    │
+        │   📁 Bug-1024                          (会话 · 3 小时前)     │
+        │   📄 prd-v1.2.md                       (Artifact · 11 分前) │
+        │   📁 度量周报                          (会话 · 昨天)        │
+        ├──────────────────────────────────────────────────────────┤
+        │  常用命令                                                   │
+        │   ⚙ 设置                              ⌘,                  │
+        │   ⚙ 切换供应商                         ⌘⇧P                │
+        │   ⚙ 新建会话                          ⌘N                  │
+        ├──────────────────────────────────────────────────────────┤
+        │   ↑↓ 选择   ↵ 打开    esc 关闭          [筛选 ⌃ →]          │
+        └──────────────────────────────────────────────────────────┘
+```
+
+## 输入关键词后(用户输入 "PRD")
+
+```
+        ┌──────────────────────────────────────────────────────────┐
+        │  🔍  PRD                                                   │
+        ├──────────────────────────────────────────────────────────┤
+        │  📁 会话 (3)                                                │
+        │ ► 需求评审 - 离职流程                  (今天 11:32)         │
+        │     ...帮我把 prd-v1.2.md 拆成 user story...               │
+        │                                                            │
+        │   产品评审 - 支付优化                  (4-15)               │
+        │     ...这个 PRD 还需要补充非功能...                          │
+        │                                                            │
+        │  📄 Artifacts (2)                                           │
+        │   prd-v1.2.md                          (132 行)             │
+        │     # PRD - 离职流程 v1.2 ...                                │
+        │                                                            │
+        │   prd-payment-v0.3.md                  (89 行)              │
+        │     # PRD - 支付优化 v0.3 ...                                │
+        │                                                            │
+        │  ⚙ 命令 (1)                                                │
+        │   /prd <file>                          PRD 校验 + 可测性    │
+        │                                                            │
+        │  💬 消息 (8 条匹配)                       [展开 →]           │
+        ├──────────────────────────────────────────────────────────┤
+        │  esc 关闭          ↵ 打开第一项                              │
+        └──────────────────────────────────────────────────────────┘
+```
+
+## 筛选模式(用户按 ⌃→ 或点筛选)
+
+```
+        ┌──────────────────────────────────────────────────────────┐
+        │  🔍  PRD              筛选: [✓会话 ✓Artifact ✗消息 ✓命令]  │
+        ├──────────────────────────────────────────────────────────┤
+        │  时间  ●全部  ○今天  ○本周  ○本月  ○自定义                 │
+        │  供应商 [全部 ▾]                                            │
+        ├──────────────────────────────────────────────────────────┤
+        │  ...(搜索结果,按筛选条件过滤)...                           │
+        └──────────────────────────────────────────────────────────┘
+```
+
+## 关键交互
+
+| 元素 | 行为 |
+|------|------|
+| 输入框 | 输入即搜,300ms 防抖。空时显示 "最近访问 + 常用命令" |
+| 类型分组 | 默认顺序 会话 → Artifact → 命令 → 消息;每组最多 3-5 条,有更多时显示 "[展开 →]" |
+| ↑↓ | 跨组导航 |
+| ↵ | 打开高亮项 |
+| ⌃→ | 进/退筛选模式 |
+| 搜索消息 | 显示消息片段(关键词高亮),点击跳到该消息位置并滚动 |
+| esc | 关浮层 |
+| Cmd+1/2/3/4 | 直接跳到第 N 项 |
+
+## 搜索算法
+
+- 会话/Artifact 名: 子串匹配 + 模糊匹配
+- 消息内容: 全文索引(SQLite FTS5)
+- 命令: 命令名 + 描述模糊匹配
+
+## 性能
+
+- 本地索引,首次启动建索引(后台任务,UI 不阻塞)
+- 输入到结果出现 < 100ms (10000 条会话规模)
diff --git a/docs/design/ui/wireframes/08-conversation-context-menu.md b/docs/design/ui/wireframes/08-conversation-context-menu.md
new file mode 100644
index 0000000..b06b58e
--- /dev/null
+++ b/docs/design/ui/wireframes/08-conversation-context-menu.md
@@ -0,0 +1,129 @@
+# Wireframe 08 · 会话右键菜单 + 收藏 + 分组
+
+> 侧边栏会话右键 / macOS Ctrl+点击 / 长按(触摸板)触发。
+
+## 右键菜单
+
+```
+   ┌──────────────────┐
+   │ ○ Bug-1024     ⋮ │           ┌──────────────────────────────┐
+   │ ○ 部署 SOP        │  ←右键→  │  ⭐ 加入收藏                   │
+   │                  │           │  📌 置顶                       │
+   │                  │           │  ✏ 重命名               ⌘R    │
+   │                  │           │  ─────────────────────────    │
+   │                  │           │  📂 移到分组 ►                  │
+   │                  │           │     • 工作                      │
+   │                  │           │     • 学习                      │
+   │                  │           │     • + 新建分组...             │
+   │                  │           │  ─────────────────────────    │
+   │                  │           │  📋 复制链接                    │
+   │                  │           │  📤 导出会话                    │
+   │                  │           │     ▸ Markdown                 │
+   │                  │           │     ▸ JSON                     │
+   │                  │           │     ▸ 仅 Artifacts (.zip)       │
+   │                  │           │  ─────────────────────────    │
+   │                  │           │  📊 查看统计 (token / 时长)      │
+   │                  │           │  🔄 重置上下文                  │
+   │                  │           │  ─────────────────────────    │
+   │                  │           │  🗑 删除                ⌘⌫     │
+   │                  │           └──────────────────────────────┘
+```
+
+## 重命名内联编辑
+
+```
+   │ ▼ 今天 (3)        │
+   │ ┌──────────────┐  │
+   │ │需求评审 - 离职│  ← 输入框获得焦点,蓝色边框
+   │ └──────────────┘  │
+   │ ○ Bug-1024        │      ↵ 保存   esc 取消
+```
+
+## 收藏与置顶
+
+收藏的会话有独立 "⭐ 收藏" 分组,任何时候置顶,顺序按收藏时间倒序:
+
+```
+   │ ▼ 收藏 ⭐ (2)      │
+   │ ⭐ 故障复盘 - DB 慢 │  ← 收藏图标 + 始终在最上
+   │ ⭐ ADR 模板         │
+   │ ─────────         │
+   │ ▼ 今天 (3)         │
+   │ ...                │
+```
+
+置顶(📌)只在所在分组内置顶,不跨分组:
+
+```
+   │ ▼ 今天 (3)         │
+   │ 📌 紧急 Bug 排查    │  ← 置顶,在"今天"组首位
+   │ ○ 需求评审          │
+   │ ○ 部署 SOP          │
+```
+
+## 分组管理
+
+新建分组弹小窗:
+
+```
+                ┌─────────────────────────────┐
+                │  新建分组                     │
+                ├─────────────────────────────┤
+                │  名称  [____________________]│
+                │  颜色  ●  ●  ●  ●  ●  ●     │
+                │        红 橙 黄 绿 蓝 紫     │
+                │                              │
+                │  取消              创建      │
+                └─────────────────────────────┘
+```
+
+分组在侧边栏的视觉:
+
+```
+   │ ▼ 工作 ● (5)       │  ← 分组色点
+   │ ○ 需求评审          │
+   │ ○ Bug-1024          │
+   │ ...                 │
+   │ ▼ 学习 ● (2)       │
+   │ ○ Rust 入门         │
+```
+
+## 多选(⌘ 点击 / Shift 点击)
+
+```
+   │ ▼ 今天 (3)         │
+   │ ☑ 需求评审    🔵   │  ← 多选,蓝色高亮
+   │ ☑ Bug-1024    🔵   │
+   │ ○ 部署 SOP         │
+   │                    │
+   │ ─────────         │
+   │ 📦 已选 2 项 [操作 ▾] │  ← 底部操作条
+   │   • 移到分组         │
+   │   • 加入收藏         │
+   │   • 批量导出         │
+   │   • 删除选中         │
+```
+
+## 删除二次确认
+
+```
+                ┌─────────────────────────────┐
+                │  ⚠️  删除会话                  │
+                ├─────────────────────────────┤
+                │                              │
+                │  会话「需求评审 - 离职流程」  │
+                │  和它的 6 条消息将被删除      │
+                │                              │
+                │  Artifact 会一起删除吗?       │
+                │  ● 一起删 (推荐)              │
+                │  ○ 保留 Artifact (移到回收站)  │
+                │                              │
+                │  取消               删除      │
+                └─────────────────────────────┘
+```
+
+## 关键交互
+
+- 删除有 30 天回收站(设置可关)
+- 移到分组支持拖拽
+- 重命名支持 Tab 自动补全(基于会话内容生成的候选)
diff --git a/docs/design/ui/wireframes/09-empty-states.md b/docs/design/ui/wireframes/09-empty-states.md
new file mode 100644
index 0000000..9c04bf6
--- /dev/null
+++ b/docs/design/ui/wireframes/09-empty-states.md
@@ -0,0 +1,133 @@
+# Wireframe 09 · 空状态合集
+
+> 各场景下的"无内容"展示。每个空状态都要给用户**下一步行动**,不能只是空白页。
+
+## 9.1 首次使用 · 无任何会话
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  EP Code AI                                              [无供应商 ⚠️] │
+├──────────────┬───────────────────────────────────────────────────────┤
+│ 🔍 搜索...    │                                                        │
+│              │                                                        │
+│              │                       👋 欢迎                          │
+│  无会话       │                                                        │
+│              │       开始你的第一个会话                                  │
+│              │       Claude 会在这里和你协作                             │
+│              │                                                        │
+│              │                                                        │
+│              │       ┌────────────────────┐                           │
+│              │       │ ✨ 新建第一个会话    │                           │
+│              │       │       ⌘N            │                           │
+│              │       └────────────────────┘                           │
+│              │                                                        │
+│              │       或者:                                              │
+│              │       📚 查看 5 分钟教程                                 │
+│              │       📋 用 / 调命令 (无需会话)                          │
+│              │                                                        │
+│ + 新会话 ⌘N   │                                                        │
+└──────────────┴───────────────────────────────────────────────────────┘
+```
+
+## 9.2 已有会话 · 没选中任何会话
+
+```
+│              │                                                        │
+│ ▼ 今天 (3)   │                                                        │
+│ ○ 需求评审    │              📂  选择一个会话                            │
+│ ○ Bug-1024    │                                                        │
+│ ○ 部署 SOP    │              点左侧列表,或:                              │
+│              │                                                        │
+│              │              ⌘N  新建会话                               │
+│              │              ⌘K  全局搜索                               │
+│              │              /   命令面板                               │
+```
+
+## 9.3 新会话 · 还没发任何消息
+
+```
+│              │  会话: 「未命名会话」                       📌 ⋮         │
+│              │  Anthropic Claude · opus                                │
+│              │ ──────────────────────────────────────────────         │
+│              │                                                        │
+│              │                                                        │
+│              │              ✨ 新会话                                   │
+│              │                                                        │
+│              │              发一条消息开始,或试试:                       │
+│              │                                                        │
+│              │              💡 帮我把这份 PRD 拆成 user story            │
+│              │              💡 review 这段代码,找 N+1 查询             │
+│              │              💡 把昨天的故障复盘整理成 Jira issue          │
+│              │              💡 给我生成本周度量周报                       │
+│              │                                                        │
+│              │              (点击 prompt 卡片直接发送,或自由输入)        │
+│              │                                                        │
+│              │ ──────────────────────────────────────────────         │
+│              │  [/]      [📎]      [⚡ opus]               ⌘↵          │
+│              │  ┌──────────────────────────────────────┐              │
+│              │  │ 输入消息...                           │              │
+│              │  └──────────────────────────────────────┘              │
+```
+
+> Prompt 卡片来自最近 7 天用户消息抽取的 Top 4 类别 + 系统默认建议(供应商未连时只显默认)
+
+## 9.4 搜索无结果
+
+```
+        ┌──────────────────────────────────────────────────────────┐
+        │  🔍  xxxyyyzzz                                             │
+        ├──────────────────────────────────────────────────────────┤
+        │                                                            │
+        │              😶 没找到匹配的内容                             │
+        │                                                            │
+        │              试试:                                           │
+        │              • 减少关键词长度                                 │
+        │              • 切换搜索类型(当前只搜 "会话")                  │
+        │              • 用模糊搜索: 输入 fuz/                         │
+        │                                                            │
+        │              或者:                                           │
+        │              ✨ 用这个查询新建一个会话 → "xxxyyyzzz"          │
+        └──────────────────────────────────────────────────────────┘
+```
+
+## 9.5 Artifact 面板 · 无 Artifact
+
+> 这种情况下面板**不显示**(整个右栏宽度变 0,中栏 flex 撑满)。
+> 顶栏右侧出现 "📦 Artifacts (0)" 灰色按钮,点开手动展开。
+
+## 9.6 网络断开 / API 失败
+
+```
+│              │  会话: 「需求评审」                          📌 ⋮       │
+│              │  Anthropic Claude · opus · ⚠️ 连接失败                  │
+│              │ ──────────────────────────────────────────────         │
+│              │  ...历史消息正常显示...                                  │
+│              │                                                        │
+│              │  ❌ 12:01  发送失败: 网络超时(10s)                     │
+│              │     [🔄 重试]   [📋 复制消息]   [⚙ 检查供应商]           │
+│              │                                                        │
+│              │ ──────────────────────────────────────────────         │
+│              │  ⚠️ 网络异常,消息已暂存。恢复后将自动重发                │
+```
+
+## 9.7 供应商未配置
+
+```
+│              │  ⚠️ 未配置供应商                                          │
+│              │                                                        │
+│              │  EP Code AI 需要 AI 供应商才能工作                        │
+│              │                                                        │
+│              │  ┌──────────────────────┐  ┌──────────────────────┐    │
+│              │  │ 🔧 立即配置供应商      │  │ 📚 查看支持的供应商    │    │
+│              │  └──────────────────────┘  └──────────────────────┘    │
+│              │                                                        │
+│              │  当前只能用本地命令(`/check` `/adr` `/metrics` 等)       │
+```
+
+## 关键原则
+
+| ❌ 不要 | ✅ 要 |
+|--------|------|
+| 只显示 "暂无数据" | 显示**为什么没有 + 下一步做什么** |
+| 用大图标占满屏 | 适度图标 + 明确 CTA |
+| 把空状态做成营销页 | 保持简洁,1-2 个核心 CTA + 1-2 个备选路径 |
diff --git a/docs/design/ui/wireframes/10-env-status-bar.md b/docs/design/ui/wireframes/10-env-status-bar.md
new file mode 100644
index 0000000..63910ee
--- /dev/null
+++ b/docs/design/ui/wireframes/10-env-status-bar.md
@@ -0,0 +1,100 @@
+# Wireframe 10 · 持久化环境健康状态栏
+
+> 永远在主视图最底部 24px 高度。一眼能看出环境健康 + 网络状态。
+
+## 健康状态(全绿)
+
+```
+├──────────────────────────────────────────────────────────────────────────────────┤
+│  ✅ 环境正常 · Node v20 / Claude Code v1.2.3        ●  Anthropic · 240ms          │
+└──────────────────────────────────────────────────────────────────────────────────┘
+   ↑                                                  ↑
+   左半 · 环境信息                                    右半 · 网络/供应商
+```
+
+## 异常状态(环境某项失败)
+
+```
+│  ⚠️ Claude Code 缺失 [▶ 修复]                       ●  Anthropic · 240ms          │
+   ↑ 黄色高亮                                          ↑ 网络仍正常
+```
+
+## 严重异常(全红)
+
+```
+│  ❌ 环境损坏 [▶ 修复]                                ●  断网 [🔄 重试]              │
+   ↑ 红色背景                                          ↑ 红色
+```
+
+## 加载中状态
+
+```
+│  ⏳ 检查环境中...                                    ⏳ 测连接中...                  │
+```
+
+## hover 展开详情
+
+鼠标 hover 在左半,弹 tooltip 显示完整列表:
+
+```
+              ┌─────────────────────────────┐
+              │  环境检查                     │
+              │  ✅ Node.js        v20.10.0   │
+              │  ✅ npm            v10.2.3    │
+              │  ✅ git            v2.42.0    │
+              │  ✅ Claude Code    v1.2.3    │
+              │  上次检查: 1 分钟前            │
+              │  [▶ 重新检查]                  │
+              └─────────────────────────────┘
+              ↑
+│  ✅ 环境正常 · ...
+```
+
+hover 在右半,弹连接详情:
+
+```
+                                       ┌──────────────────────────────┐
+                                       │  Anthropic 官方                │
+                                       │  状态: ✅ 正常                  │
+                                       │  延迟: 240ms (10 次平均)        │
+                                       │  本月用量: 2.3M tokens · $42    │
+                                       │  [▶ 测连接] [⚙ 切换]           │
+                                       └──────────────────────────────┘
+                                                              ↑
+                                                  ●  Anthropic · 240ms │
+```
+
+## 点击行为
+
+| 点击区域 | 行为 |
+|---------|------|
+| 左半 (环境) | 异常时弹模态修复对话框;正常时打开"环境检查"页 |
+| `[▶ 修复]` 按钮 | 直接开始一键修复(走 wizard 步骤 2 的逻辑) |
+| 右半 (供应商) | 弹供应商切换浮层(wireframe-06) |
+| `[🔄 重试]` | 立即重测连接 |
+
+## 视觉规范
+
+- **高度**: 24px(固定)
+- **左右内边距**: 16px
+- **背景**: 默认与窗口背景同;异常时变 `Warning` / `Error` 浅色背景
+- **字号**: 12px
+- **图标**: 用 emoji,跨平台一致
+
+## 不显示状态栏的场景
+
+- 全屏 Artifact 详情(wireframe-05) 时隐藏
+- 设置页(wireframe-03) 时隐藏
+- 首次向导(wireframe-02) 时隐藏
+
+## 通知降级
+
+如果系统通知(macOS Notification Center / Windows Toast / Linux D-Bus)被禁:
+- 严重错误从静默升级为底部 banner(状态栏上方插入,可关闭)
+
+```
+│  ⚠️ Claude Code 进程崩溃,正在重启...    [详情] [✕]                                  │
+├──────────────────────────────────────────────────────────────────────────────────┤
+│  ❌ 环境损坏 [▶ 修复]                               ●  断网 [🔄 重试]              │
+└──────────────────────────────────────────────────────────────────────────────────┘
+```