383 lines
16 KiB
Markdown
383 lines
16 KiB
Markdown
---
|
||
date: "2026-06-13"
|
||
status: active
|
||
origin: docs/brainstorms/2026-06-13-gui-productization-requirements.md
|
||
---
|
||
|
||
## Summary
|
||
|
||
对 Fischer AgentKit GUI 进行产品级提升，三线并行：布局重构为「左对话 + 右双栏」、建立双主题设计系统、增强交互体验。分 3 个迭代交付。
|
||
|
||
## Problem Frame
|
||
|
||
当前 GUI 处于"功能可用但体验粗糙"状态：四象限等分布局让对话空间被压缩到 1/4 屏幕；Design Token 体系仅覆盖浅色主题，暗色主题缺失；无过渡动画、操作无反馈、空状态单调。需要从布局、视觉、交互三个维度全面提升到产品级。
|
||
|
||
## Key Technical Decisions
|
||
|
||
**KTD-1. 暗色主题通过 `[data-theme="dark"]` 选择器切换，而非独立 CSS 文件。**
|
||
|
||
现有 `tokens.css` 在 `:root` 上定义了约 80 个 token。暗色主题在 `[data-theme="dark"]` 选择器上覆盖同名变量，切换时只需修改 `document.documentElement.dataset.theme`。这保持了 CSS 变量为唯一真实来源，Ant Design Vue 主题通过 `readToken()` 运行时自动跟随。无需引入 CSS-in-JS 主题切换或独立 CSS 文件。
|
||
|
||
**KTD-2. 布局重构通过调整 AgentLayout 的 SplitPane 嵌套结构实现，不修改子视图。**
|
||
|
||
当前 AgentLayout 使用三层 SplitPane 嵌套（水平 → 左侧垂直 + 右侧垂直）。重构为两层：水平（左对话 + 右侧）→ 右侧垂直（右上 + 右下）。左侧不再嵌套垂直 SplitPane，ChatView 直接占满左半屏。所有子视图（ChatView、WorkflowView、EvolutionView 等）代码零修改。
|
||
|
||
**KTD-3. 侧边导航改为 32px 图标模式，复用现有 QuadrantPanel 的 Tab 切换机制。**
|
||
|
||
点击导航图标时调用 QuadrantPanel 的 `setActiveTab()` 方法切换 Tab 并展开面板。导航状态通过 `activeNav` ref 与 QuadrantPanel 的 `activeTab` 双向同步。不引入新的路由机制。
|
||
|
||
**KTD-4. 交互增强使用 Vue 3 内置 `<Transition>` 和 `<TransitionGroup>`，配合现有 `transitions.css` 定义的动画类。**
|
||
|
||
现有 `transitions.css` 已定义 7 种动画类（fade、slide-up、slide-down、slide-right、collapse、scale、stagger-list）和 3 种关键帧动画（skeleton-pulse、pulse-dot、gentle-bounce）。交互增强直接复用这些动画类，不引入第三方动画库。
|
||
|
||
---
|
||
|
||
## High-Level Technical Design
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Layout["布局重构"]
|
||
HSplit["水平 SplitPane<br/>55:45"]
|
||
Left["左半屏<br/>ChatView"]
|
||
Right["右半屏"]
|
||
VSplit["垂直 SplitPane<br/>60:40"]
|
||
TR["右上面板<br/>代码/工作流/知识库"]
|
||
BR["右下面板<br/>监控/技能/设置"]
|
||
Left --> HSplit
|
||
Right --> HSplit
|
||
TR --> VSplit
|
||
BR --> VSplit
|
||
VSplit --> Right
|
||
end
|
||
|
||
subgraph Theme["双主题"]
|
||
Light["浅色 Token<br/>:root"]
|
||
Dark["暗色 Token<br/>[data-theme=dark]"]
|
||
Toggle["TopNav 切换按钮"]
|
||
Toggle --> Light
|
||
Toggle --> Dark
|
||
end
|
||
|
||
subgraph Interaction["交互增强"]
|
||
Anim["过渡动画<br/>Transition 组件"]
|
||
Feedback["操作反馈<br/>骨架屏/Toast"]
|
||
Empty["空状态<br/>品牌化插图"]
|
||
Drag["拖拽增强<br/>比例提示"]
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## Requirements Traceability
|
||
|
||
| Origin R-ID | Plan Coverage |
|
||
|---|---|
|
||
| R1. 左对话 + 右双栏布局 | U1 |
|
||
| R2. 面板折叠为 Tab 栏 | U1 (QuadrantPanel 已支持，调整默认行为) |
|
||
| R3. 侧边导航精简为图标模式 | U2 |
|
||
| R4. Design Token 体系基础 | U3 (已有基础，补充暗色 token) |
|
||
| R5. 小屏幕适配 | U1 (调整 responsive.css 断点) |
|
||
| R6. 暗色主题 | U3 |
|
||
| R7. 组件样式统一 | U4 |
|
||
| R8. 过渡动画 | U5 |
|
||
| R9. 操作反馈 | U6 |
|
||
| R10. 空状态设计 | U7 |
|
||
| R11. 拖拽交互增强 | U8 |
|
||
|
||
---
|
||
|
||
## Implementation Units
|
||
|
||
### 迭代 1：布局骨架 + 暗色主题
|
||
|
||
### U1. AgentLayout 布局重构
|
||
|
||
**Goal:** 将四象限等分布局重构为「左对话 + 右双栏」布局。
|
||
|
||
**Requirements:** R1, R2, R5
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/components/layout/AgentLayout.vue` (修改)
|
||
- `src/agentkit/server/frontend/src/styles/responsive.css` (修改)
|
||
- `src/agentkit/server/frontend/src/router/index.ts` (修改)
|
||
|
||
**Approach:**
|
||
- 修改 AgentLayout 的 SplitPane 嵌套结构：移除左侧垂直 SplitPane，ChatView 直接作为水平 SplitPane 的 first slot
|
||
- 右侧保留垂直 SplitPane（右上 + 右下），与当前相同
|
||
- 调整水平 SplitPane 默认比例为 55:45（左:右）
|
||
- 调整路由：移除 `agent-terminal` 路由（终端不再作为独立象限），终端功能可通过右侧面板 Tab 访问
|
||
- 调整 responsive.css 断点：小屏幕阈值从 1280px 调整为 1024px
|
||
- QuadrantPanel 的折叠功能已实现，无需修改
|
||
|
||
**Patterns to follow:** 现有 SplitPane + QuadrantPanel 嵌套模式
|
||
|
||
**Test scenarios:**
|
||
- 页面加载后左半屏显示 ChatView，右半屏上下分割为代码/工作流和监控
|
||
- 左右分割线可拖拽，默认比例 55:45
|
||
- 右侧上下分割线可拖拽，默认比例 60:40
|
||
- 分割比例保存到 localStorage，刷新后恢复
|
||
- 右上面板可折叠为 Tab 栏
|
||
- 右下面板可折叠为 Tab 栏
|
||
- 两个面板同时折叠后对话面板获得最大空间
|
||
- 屏幕宽度 < 1024px 时显示小屏幕提示
|
||
- 旧路由 `/terminal` 重定向正确
|
||
|
||
**Verification:** 打开 GUI 后左半屏是对话，右半屏上下分割，拖拽和折叠功能正常
|
||
|
||
### U2. 侧边导航精简为图标模式
|
||
|
||
**Goal:** 将侧边导航精简为 32px 宽的图标导航，点击切换右侧面板 Tab。
|
||
|
||
**Requirements:** R3
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/components/layout/AgentLayout.vue` (修改)
|
||
- `src/agentkit/server/frontend/src/components/layout/TopNav.vue` (修改)
|
||
|
||
**Approach:**
|
||
- 在 AgentLayout 的水平 SplitPane 之前添加 32px 宽的图标导航栏
|
||
- 导航项：对话（MessageOutlined）、工作流（ApartmentOutlined）、知识库（BookOutlined）、技能（AppstoreOutlined）、监控（DashboardOutlined）、设置（SettingOutlined）
|
||
- 点击导航图标时调用对应 QuadrantPanel 的 `setActiveTab()` 方法并展开面板
|
||
- 当前激活的导航图标高亮显示（使用 `--color-primary`）
|
||
- TopNav 添加导航栏折叠/展开按钮
|
||
- 导航栏折叠时宽度为 0px，展开时为 32px
|
||
- 导航状态与路由同步
|
||
|
||
**Patterns to follow:** QuadrantPanel 的 `setActiveTab()` 方法
|
||
|
||
**Test scenarios:**
|
||
- 导航栏显示 6 个图标，宽度 32px
|
||
- 点击「工作流」图标 → 右上面板切换到工作流 Tab 并展开
|
||
- 点击「监控」图标 → 右下面板切换到监控 Tab 并展开
|
||
- 点击「对话」图标 → 聚焦左侧对话面板
|
||
- 当前激活图标高亮
|
||
- TopNav 按钮可折叠/展开导航栏
|
||
- 折叠后导航栏宽度为 0px
|
||
|
||
**Verification:** 导航栏图标可切换右侧面板内容，折叠/展开正常
|
||
|
||
### U3. 暗色主题 Token 定义与切换
|
||
|
||
**Goal:** 在现有浅色 Token 基础上新增暗色主题 Token，支持一键切换。
|
||
|
||
**Requirements:** R4, R6
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/styles/tokens.css` (修改 — 添加 `[data-theme="dark"]` 块)
|
||
- `src/agentkit/server/frontend/src/styles/theme.ts` (修改 — 暗色主题 Ant Design 映射)
|
||
- `src/agentkit/server/frontend/src/components/layout/TopNav.vue` (修改 — 添加主题切换按钮)
|
||
- `src/agentkit/server/frontend/src/stores/theme.ts` (新建 — 主题状态管理)
|
||
|
||
**Approach:**
|
||
- 在 `tokens.css` 末尾添加 `[data-theme="dark"]` 选择器块，覆盖所有颜色相关 token（背景、文本、边框、主色、语义色、灰色阶、代码色）
|
||
- 暗色主题配色：深色背景（#1a1a2e 系列）、荧光强调色（保持 Indigo 主色但调亮）、终端原生感
|
||
- 新建 `stores/theme.ts`：管理主题状态（`light`/`dark`），切换时修改 `document.documentElement.dataset.theme`，偏好保存到 localStorage
|
||
- TopNav 添加太阳/月亮图标切换按钮
|
||
- `theme.ts` 中的 `readToken()` 已在运行时从 CSS 变量读取，暗色 token 覆盖后 Ant Design 主题自动跟随
|
||
|
||
**Patterns to follow:** 现有 `tokens.css` 的 `:root` 定义模式，`theme.ts` 的 `readToken()` 模式
|
||
|
||
**Test scenarios:**
|
||
- 点击 TopNav 月亮图标 → 界面切换到暗色主题
|
||
- 点击太阳图标 → 切换回浅色主题
|
||
- 暗色主题下所有组件正常显示（文字可读、边框可见、按钮可点击）
|
||
- 暗色主题下 Ant Design 组件（按钮、输入框、下拉框、模态框）正常显示
|
||
- 主题偏好保存到 localStorage，刷新后保持
|
||
- 代码块在暗色主题下使用暗色代码配色
|
||
|
||
**Verification:** 主题切换按钮可用，两种主题下所有界面元素正常显示
|
||
|
||
---
|
||
|
||
### 迭代 2：组件样式统一
|
||
|
||
### U4. 组件样式统一与 Ant Design 覆盖清理
|
||
|
||
**Goal:** 所有组件统一引用 Design Token，清理 App.vue 中的 `!important` 覆盖。
|
||
|
||
**Requirements:** R7
|
||
|
||
**Dependencies:** U3
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/App.vue` (修改 — 清理全局覆盖)
|
||
- `src/agentkit/server/frontend/src/components/layout/SideNav.vue` (修改 — 迁移到 token)
|
||
- `src/agentkit/server/frontend/src/styles/theme.ts` (修改 — 增强组件级 token 映射)
|
||
- 各组件 scoped 样式中的硬编码值 (修改 — 替换为 token 引用)
|
||
|
||
**Approach:**
|
||
- 将 App.vue 中的 `.ant-btn`、`.ant-card` 等全局覆盖迁移到 `theme.ts` 的组件级 token 映射中，消除 `!important`
|
||
- SideNav.vue 的硬编码 `rgba()` 值替换为 token 引用
|
||
- 扫描所有组件 scoped 样式中的硬编码颜色/间距值，替换为 token 引用
|
||
- 主色统一为 `--color-primary`（消除 `#1677ff`/`#1890ff` 残留）
|
||
|
||
**Patterns to follow:** `theme.ts` 的组件级 token 映射模式
|
||
|
||
**Test scenarios:**
|
||
- App.vue 中无 `!important` 覆盖
|
||
- 所有组件 scoped 样式中无硬编码颜色值
|
||
- 浅色和暗色主题下所有组件样式一致
|
||
- Ant Design 组件（按钮、卡片、标签、模态框、选择框）圆角和间距统一
|
||
|
||
**Verification:** 搜索代码中无硬编码颜色值（除 token 定义文件外），两种主题下样式一致
|
||
|
||
---
|
||
|
||
### 迭代 3：交互增强
|
||
|
||
### U5. 过渡动画
|
||
|
||
**Goal:** 为所有交互添加过渡动画。
|
||
|
||
**Requirements:** R8
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/components/layout/QuadrantPanel.vue` (修改 — 折叠/展开动画)
|
||
- `src/agentkit/server/frontend/src/components/layout/AgentLayout.vue` (修改 — Tab 切换动画)
|
||
- `src/agentkit/server/frontend/src/views/ChatView.vue` (修改 — 消息列表动画)
|
||
- `src/agentkit/server/frontend/src/styles/transitions.css` (修改 — 如需新增动画类)
|
||
|
||
**Approach:**
|
||
- QuadrantPanel 折叠/展开：使用 Vue `<Transition>` 包裹 body 区域，应用 `collapse` 动画类
|
||
- Tab 切换：使用 Vue `<Transition>` 包裹 content 区域，应用 `fade` 动画类
|
||
- ChatView 消息列表：使用 `<TransitionGroup>` 包裹消息列表，应用 `stagger-list` 动画类
|
||
- 路由切换：使用 `<Transition>` 包裹 `<router-view>`，应用 `fade` 动画类
|
||
|
||
**Patterns to follow:** 现有 `transitions.css` 定义的动画类
|
||
|
||
**Test scenarios:**
|
||
- 面板折叠/展开有平滑过渡（200ms ease）
|
||
- Tab 切换有淡入淡出（150ms）
|
||
- 新消息出现有交错渐入效果
|
||
- 动画不影响操作响应速度
|
||
|
||
**Verification:** 所有交互有流畅的过渡动画，无生硬切换
|
||
|
||
### U6. 操作反馈
|
||
|
||
**Goal:** 为用户操作提供即时反馈。
|
||
|
||
**Requirements:** R9
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/components/common/AppToast.vue` (新建 — Toast 通知组件)
|
||
- `src/agentkit/server/frontend/src/components/common/SkeletonLoader.vue` (新建 — 骨架屏组件)
|
||
- `src/agentkit/server/frontend/src/components/layout/TopNav.vue` (修改 — WebSocket 断连横幅)
|
||
- `src/agentkit/server/frontend/src/stores/chat.ts` (修改 — 使用 Toast 替代错误提示)
|
||
|
||
**Approach:**
|
||
- 新建 AppToast 组件：基于 Ant Design Vue `message` API 封装，支持 success/error/warning/info 四种类型
|
||
- 新建 SkeletonLoader 组件：使用现有 `skeleton-pulse` 关键帧动画，支持不同形状（文本/卡片/列表）
|
||
- TopNav 添加 WebSocket 断连横幅：使用 `slide-down` 动画类
|
||
- chat.ts 中的错误提示从 `console.error` 改为 Toast 通知
|
||
|
||
**Patterns to follow:** 现有 `transitions.css` 的 `skeleton-pulse` 动画
|
||
|
||
**Test scenarios:**
|
||
- 操作成功时显示绿色 Toast 通知
|
||
- 操作失败时显示红色 Toast 通知
|
||
- 加载状态显示骨架屏而非 `<a-spin>`
|
||
- WebSocket 断连时顶部显示黄色横幅
|
||
- 重连后横幅自动消失
|
||
|
||
**Verification:** 所有操作有即时视觉反馈
|
||
|
||
### U7. 空状态设计
|
||
|
||
**Goal:** 为所有空状态提供品牌化插图和引导文案。
|
||
|
||
**Requirements:** R10
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/components/common/EmptyState.vue` (新建 — 通用空状态组件)
|
||
- `src/agentkit/server/frontend/src/views/ChatView.vue` (修改 — 对话空状态)
|
||
- `src/agentkit/server/frontend/src/views/WorkflowView.vue` (修改 — 工作流空状态)
|
||
- `src/agentkit/server/frontend/src/views/EvolutionView.vue` (修改 — 监控空状态)
|
||
- `src/agentkit/server/frontend/src/views/KnowledgeBaseView.vue` (修改 — 知识库空状态)
|
||
- `src/agentkit/server/frontend/src/views/SkillsView.vue` (修改 — 技能空状态)
|
||
|
||
**Approach:**
|
||
- 新建 EmptyState 通用组件：接受 icon（Ant Design 图标组件）、title、description、action（可选操作按钮）三个 props
|
||
- 各视图的空状态使用 EmptyState 组件替换当前的纯文字提示
|
||
- 对话空状态：MessageOutlined + "开始对话" + "输入消息与 Agent 交互"
|
||
- 工作流空状态：ApartmentOutlined + "创建工作流" + "拖拽节点构建自动化流程"
|
||
- 监控空状态：DashboardOutlined + "暂无监控数据" + "执行任务后数据将自动更新"
|
||
- 知识库空状态：BookOutlined + "添加知识源" + "上传文档或配置外部知识库"
|
||
- 技能空状态：AppstoreOutlined + "注册技能" + "通过 YAML 配置定义技能"
|
||
|
||
**Patterns to follow:** Ant Design Vue 的 `a-empty` 组件模式
|
||
|
||
**Test scenarios:**
|
||
- 新用户打开对话页面显示空状态引导
|
||
- 工作流列表为空时显示空状态引导
|
||
- 监控数据为空时显示空状态引导
|
||
- 空状态组件在浅色和暗色主题下正常显示
|
||
|
||
**Verification:** 所有空状态有品牌化插图和引导文案
|
||
|
||
### U8. 拖拽交互增强
|
||
|
||
**Goal:** 优化拖拽操作的视觉反馈。
|
||
|
||
**Requirements:** R11
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/components/layout/SplitPane.vue` (修改 — 拖拽比例提示)
|
||
- `src/agentkit/server/frontend/src/views/WorkflowView.vue` (修改 — 节点拖拽预览，如 FlowCanvas 支持)
|
||
|
||
**Approach:**
|
||
- SplitPane 拖拽时：在分割线旁显示当前比例百分比（如 "55%"），拖拽结束后淡出
|
||
- SplitPane 拖拽时：分割线高亮加粗（从 2px 到 4px），颜色从 `--border-color` 变为 `--color-primary`
|
||
- 工作流节点拖拽：如果 Vue Flow 支持自定义拖拽预览，添加放置预览指示
|
||
|
||
**Patterns to follow:** 现有 SplitPane 的拖拽处理模式
|
||
|
||
**Test scenarios:**
|
||
- 拖拽分割线时显示当前比例百分比
|
||
- 拖拽时分割线高亮加粗
|
||
- 拖拽结束后比例提示淡出
|
||
- 键盘调整分割线时也显示比例提示
|
||
|
||
**Verification:** 拖拽操作有清晰的视觉反馈
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
**Deferred to follow-up work:**
|
||
- 代码 Diff 查看器实现（右上「代码」Tab 仍为占位）
|
||
- Cmd+K 内联编辑
|
||
- @-mention 上下文引用
|
||
- 响应式移动端适配
|
||
- SideNav (Legacy) 组件迁移（AppLayout 保留作为回退）
|
||
|
||
**Outside this product's identity:**
|
||
- 多用户协作/实时协同编辑
|
||
- 插件市场
|
||
- 代码编辑器（只读预览）
|
||
|
||
---
|
||
|
||
## Risks & Dependencies
|
||
|
||
| Risk | Impact | Mitigation |
|
||
|------|--------|-----------|
|
||
| 暗色主题 token 覆盖不完整 | 部分组件在暗色下显示异常 | 逐组件验证，优先覆盖高频组件 |
|
||
| Ant Design Vue 4.x CSS-in-JS 主题跟随 | 暗色切换后 Ant 组件可能不跟随 | `readToken()` 运行时读取确保跟随，需验证 |
|
||
| 布局重构影响子视图高度计算 | 子视图内容溢出或空白 | 子视图使用 `height: 100%` + `overflow: auto` |
|
||
| 过渡动画性能 | 大量 DOM 操作时卡顿 | 使用 CSS transform/opacity 触发 GPU 加速 |
|