191 lines
7.8 KiB
Markdown
191 lines
7.8 KiB
Markdown
---
|
||
date: "2026-06-13"
|
||
topic: "gui-productization"
|
||
status: active
|
||
---
|
||
|
||
## Summary
|
||
|
||
对 Fischer AgentKit GUI 进行产品级提升，三线并行推进：布局重构为「左对话 + 右双栏」、建立双主题设计系统、增强交互体验。分 3 个迭代交付，每个迭代可独立部署。
|
||
|
||
## Problem Frame
|
||
|
||
当前 GUI 处于"功能可用但体验粗糙"状态：四象限等分布局让对话空间被压缩到 1/4 屏幕，终端面板大多时间空闲浪费空间；颜色/间距/圆角全部硬编码散落在 30+ 组件中，视觉不统一；无过渡动画、操作无反馈、空状态单调、加载态简陋。竞品（Devin、Cursor、v0.dev）已普遍采用 Agent-First 布局 + 统一设计系统，AgentKit 需要对齐这一标准。
|
||
|
||
## Key Decisions
|
||
|
||
**左对话 + 右双栏布局。** 对话是用户 80% 时间停留的区域，应占据左半屏全部空间。右侧上下分割为代码/工作流（右上）和监控（右下），提供辅助信息。
|
||
|
||
**全面设计系统重构 + 双主题。** 建立 CSS 变量体系（颜色/间距/圆角/字体/阴影），所有组件统一引用。同时支持浅色极简和暗色科技两种主题，用户可一键切换。
|
||
|
||
**三线并行，分迭代交付。** 布局/视觉/交互三线并行推进，分 3 个迭代交付：迭代 1 布局骨架 + 设计 Token 基础，迭代 2 双主题 + 组件样式统一，迭代 3 交互增强。
|
||
|
||
## Actors
|
||
|
||
- A1. **开发者/运维工程师** — 通过对话面板与 Agent 交互，右侧面板提供工作流编辑、监控数据等辅助信息
|
||
|
||
## Requirements
|
||
|
||
### 迭代 1：布局骨架 + 设计 Token 基础
|
||
|
||
#### R1. 左对话 + 右双栏布局
|
||
|
||
将 AgentLayout 从四象限等分布局重构为「左对话 + 右双栏」布局。
|
||
|
||
- 左半屏：对话面板（ChatView），占满左侧全部高度
|
||
- 右半屏上半：代码/工作流面板，Tab 切换代码（占位）/工作流/知识库
|
||
- 右半屏下半：监控面板，Tab 切换监控/技能/设置
|
||
- 左右分割线可拖拽调整宽度，默认比例 55:45
|
||
- 右侧上下分割线可拖拽调整高度，默认比例 60:40
|
||
- 分割比例保存到 localStorage，刷新后恢复
|
||
- 最小比例 20%，最大比例 80%
|
||
|
||
#### R2. 面板折叠为 Tab 栏
|
||
|
||
每个面板可独立折叠，折叠后仅显示 Tab 栏（约 38px 高度）。
|
||
|
||
- 右上面板折叠后仅显示 Tab 栏（代码/工作流/知识库 图标+文字）
|
||
- 右下面板折叠后仅显示 Tab 栏（监控/技能/设置 图标+文字）
|
||
- 折叠状态保存到 localStorage
|
||
- 折叠/展开有平滑过渡动画（200ms ease）
|
||
- 两个面板可同时折叠，对话面板获得最大空间
|
||
|
||
#### R3. 侧边导航精简为图标模式
|
||
|
||
侧边导航栏精简为 32px 宽的图标导航，点击图标切换右侧面板 Tab 内容。
|
||
|
||
- 导航项：对话、工作流、知识库、技能、监控、设置
|
||
- 点击导航图标：对应面板切换到指定 Tab 并展开
|
||
- 当前激活的导航图标高亮显示
|
||
- 导航栏可通过 TopNav 按钮折叠/展开
|
||
|
||
#### R4. Design Token 体系基础
|
||
|
||
建立 CSS 变量体系，定义所有设计令牌。
|
||
|
||
- 创建 `src/styles/tokens.css`，定义浅色主题 Token：颜色、间距、圆角、字体、阴影
|
||
- Ant Design Vue 主题通过 ConfigProvider 注入 Token 值
|
||
- 所有组件引用 Token 变量，不再硬编码颜色/间距值
|
||
- 主色统一为一种（消除 `#1677ff`/`#1890ff` 混用）
|
||
|
||
#### R5. 小屏幕适配
|
||
|
||
- 屏幕宽度 < 1024px 时显示提示"请使用更大的屏幕"
|
||
- 屏幕宽度 1024-1280px 时右侧下面板默认折叠
|
||
- 屏幕宽度 ≥ 1280px 时完整展示所有面板
|
||
|
||
### 迭代 2：双主题 + 组件样式统一
|
||
|
||
#### R6. 暗色主题
|
||
|
||
在浅色主题基础上新增暗色主题 Token 变体。
|
||
|
||
- `src/styles/tokens-dark.css` 定义暗色主题 Token
|
||
- TopNav 增加主题切换按钮（太阳/月亮图标）
|
||
- 主题偏好保存到 localStorage
|
||
- 暗色主题配色：深色背景（#1a1a2e）、荧光强调色、终端原生感
|
||
- 代码/终端区域在浅色主题下也使用深色背景（One Dark Pro 配色）
|
||
|
||
#### R7. 组件样式统一
|
||
|
||
所有组件统一引用 Design Token，消除硬编码值。
|
||
|
||
- 对话面板：消息气泡、工具调用标签、流式输出样式
|
||
- 工作流面板：节点卡片、属性面板、画布样式
|
||
- 监控面板：指标卡片、图表容器、时间线样式
|
||
- 通用：按钮、输入框、标签、徽章、模态框统一圆角和间距
|
||
- Ant Design 全局覆盖通过 Token 驱动，而非逐组件 `!important`
|
||
|
||
### 迭代 3：交互增强
|
||
|
||
#### R8. 过渡动画
|
||
|
||
为所有交互添加过渡动画。
|
||
|
||
- 象限折叠/展开：平滑过渡（200ms ease）
|
||
- Tab 切换：淡入淡出（150ms）
|
||
- 列表项加载：交错渐入（stagger 50ms）
|
||
- 路由切换：淡入淡出（200ms）
|
||
|
||
#### R9. 操作反馈
|
||
|
||
为用户操作提供即时反馈。
|
||
|
||
- 按钮点击：波纹效果或缩放反馈
|
||
- 加载状态：骨架屏替代 `<a-spin>`
|
||
- 成功/失败：Toast 提示（替代 `alert`）
|
||
- WebSocket 断连：顶部横幅提示
|
||
|
||
#### R10. 空状态设计
|
||
|
||
为所有空状态提供品牌化插图和引导文案。
|
||
|
||
- 对话空状态：引导用户输入第一条消息
|
||
- 工作流空状态：引导创建第一个工作流
|
||
- 监控空状态：说明数据来源和更新频率
|
||
- 知识库空状态：引导上传文档或配置信息源
|
||
- 技能空状态：说明如何注册技能
|
||
|
||
#### R11. 拖拽交互增强
|
||
|
||
优化拖拽操作的视觉反馈。
|
||
|
||
- 分割线拖拽：拖拽时高亮分割线，显示当前比例百分比
|
||
- 工作流节点拖拽：放置预览指示，对齐网格
|
||
- 面板折叠：折叠时显示缩略预览
|
||
|
||
## Key Flows
|
||
|
||
- F1. 对话为主的工作流
|
||
- **Trigger:** 用户打开 AgentKit
|
||
- **Steps:** 左侧对话面板占满左半屏 → 右侧显示工作流/监控 Tab 栏 → 用户在对话面板输入 → Agent 回复 → 右侧按需展示辅助信息
|
||
- **Covered by:** R1
|
||
|
||
- F2. 主题切换
|
||
- **Trigger:** 用户点击 TopNav 主题切换按钮
|
||
- **Steps:** 点击月亮图标 → 所有 Token 变量切换为暗色值 → 界面平滑过渡到暗色主题 → 偏好保存到 localStorage
|
||
- **Covered by:** R6
|
||
|
||
- F3. 面板折叠获取最大对话空间
|
||
- **Trigger:** 用户需要专注对话
|
||
- **Steps:** 点击右上面板折叠按钮 → 面板折叠为 Tab 栏（200ms 动画）→ 点击右下面板折叠按钮 → 同样折叠 → 对话面板获得最大空间
|
||
- **Covered by:** R2, R8
|
||
|
||
## Scope Boundaries
|
||
|
||
**在范围内：**
|
||
- 布局重构（左对话 + 右双栏）
|
||
- Design Token 体系 + 双主题
|
||
- 组件样式统一
|
||
- 过渡动画、操作反馈、空状态、拖拽增强
|
||
- 侧边导航精简
|
||
- 小屏幕适配
|
||
|
||
**延迟到后续迭代：**
|
||
- 代码 Diff 查看器实现（右上「代码」Tab 仍为占位）
|
||
- Cmd+K 内联编辑（类似 Cursor）
|
||
- @-mention 上下文引用
|
||
- 代码 Diff 的 Accept/Reject 实际回滚功能
|
||
- 响应式移动端适配
|
||
|
||
**不在本产品身份内：**
|
||
- 多用户协作/实时协同编辑
|
||
- 插件市场
|
||
- 代码编辑器（只读预览，不提供编辑能力）
|
||
|
||
## Success Criteria
|
||
|
||
1. **布局合理** — 对话面板占左半屏，右侧辅助信息可按需折叠
|
||
2. **视觉一致** — 零硬编码颜色值，所有样式通过 Design Token 引用
|
||
3. **双主题可用** — 浅色/暗色一键切换，所有组件在两种主题下正常显示
|
||
4. **交互流畅** — 所有过渡动画 ≤200ms，操作有即时反馈
|
||
5. **渐进交付** — 分 3 个迭代完成，每个迭代可独立部署
|
||
|
||
## Dependencies / Assumptions
|
||
|
||
- 现有 SplitPane 组件支持水平和垂直分割，可直接复用
|
||
- 现有 QuadrantPanel 组件支持 Tab 切换和折叠，可直接复用
|
||
- Ant Design Vue 4.x 的 ConfigProvider 支持 CSS 变量主题注入
|
||
- ChatView 的 ChatSidebar 默认折叠（collapsed = true），不影响左侧对话面板的空间利用
|
||
- Vue 3 的 `<Transition>` 和 `<TransitionGroup>` 组件可满足过渡动画需求
|