418 lines
18 KiB
Markdown
418 lines
18 KiB
Markdown
---
|
||
title: "refactor: Agent-First GUI Redesign"
|
||
status: completed
|
||
created: 2026-06-13
|
||
origin: docs/brainstorms/2026-06-13-gui-redesign-requirements.md
|
||
---
|
||
|
||
# Plan: Agent-First GUI Redesign
|
||
|
||
## Summary
|
||
|
||
将 Fischer AgentKit GUI 从 SideNav 多页面布局重构为 Agent-First 四象限全屏布局，建立统一 Design Token 体系，采用浅色极简视觉风格。分 3 个迭代渐进式完成，每个迭代可独立部署。
|
||
|
||
## Problem Frame
|
||
|
||
当前 GUI 处于"功能可用但视觉粗糙"状态：300 处硬编码颜色、无设计系统、SideNav 多页面布局无法同时展示 Agent 活动、无响应式支持。竞品（Devin/Cursor/v0.dev）已普遍采用 Agent-First 全屏布局 + 统一设计系统。
|
||
|
||
## Requirements Trace
|
||
|
||
| R-ID | Requirement | Priority |
|
||
|------|-------------|----------|
|
||
| R1 | Design Token 体系 | P0 |
|
||
| R2 | Agent-First 全屏布局 | P0 |
|
||
| R3 | 对话面板重构 | P1 |
|
||
| R4 | 代码/预览面板 | P1 |
|
||
| R5 | 终端面板重构 | P1 |
|
||
| R6 | 状态/监控面板（进化精简） | P1 |
|
||
| R7 | 工作流单页化 | P2 |
|
||
| R8 | 设置分组化 | P2 |
|
||
| R9 | 过渡动画与微交互 | P2 |
|
||
| R10 | 响应式断点 | P2 |
|
||
|
||
## Key Technical Decisions
|
||
|
||
### KTD1: Design Token 双轨制 — CSS 变量 + Ant Design Theme Token
|
||
|
||
**决策：** 同时建立 CSS 自定义属性（`var(--color-primary)`）和 Ant Design Vue ConfigProvider theme token，两者通过映射表保持同步。
|
||
|
||
**理由：** Ant Design Vue 4.x 的 CSS-in-JS 架构通过 `theme.token` 控制组件内部样式，但自定义组件和 ECharts 无法读取 antd token。CSS 变量作为通用层，antd token 作为组件层，映射表桥接两者。
|
||
|
||
### KTD2: 四象限布局实现 — CSS Grid + 可拖拽分隔线
|
||
|
||
**决策：** 使用 CSS Grid 实现四象限基础布局，自定义 `SplitPane` 组件实现可拖拽分隔线，比例持久化到 localStorage。
|
||
|
||
**理由：** CSS Grid 天然支持二维布局和 `fr` 单位，比 Flexbox 更适合四象限。自定义 SplitPane 比引入第三方库（如 splitpanes）更轻量，且可精确控制样式。
|
||
|
||
### KTD3: 路由策略 — 保留 Vue Router，页面切换变为象限内容切换
|
||
|
||
**决策：** 保留 Vue Router 但重构路由结构。顶级路由改为象限内容路由（`/chat`、`/code`、`/terminal`、`/monitor`），通过路由参数控制各象限显示内容。旧路由（`/workflow`、`/knowledge`、`/skills`、`/evolution`、`/settings`）重定向到新的象限路由。
|
||
|
||
**理由：** 保留路由可维持 URL 可访问性、浏览器前进/后退、深层链接。象限内容切换比整页跳转更流畅。
|
||
|
||
### KTD4: 视觉风格 — 浅色极简 + Vercel 式紫黑渐变
|
||
|
||
**决策：** 主背景白色/极浅灰，强调色使用紫黑渐变（`#7c3aed` → `#1e1b4b`），代码/终端区域使用深色背景（One Dark Pro 配色）。
|
||
|
||
**理由：** 用户选择浅色极简风格。Vercel/v0.dev 的紫黑渐变是成熟的浅色极简强调色方案，与白色背景形成强对比。
|
||
|
||
## Scope Boundaries
|
||
|
||
### In Scope
|
||
- Design Token 体系建立
|
||
- 四象限全屏布局重构
|
||
- 所有现有功能迁移
|
||
- 浅色极简视觉风格
|
||
- 过渡动画和微交互
|
||
- 1280px+ 响应式断点
|
||
|
||
### Deferred to Follow-Up Work
|
||
- 暗色模式（需 Design Token 暗色变体）
|
||
- 移动端适配
|
||
- Computer Use 功能实现
|
||
- Cmd+K 内联编辑
|
||
- @-mention 上下文引用
|
||
- 代码 Diff Accept/Reject 实际回滚
|
||
|
||
### Outside This Product's Identity
|
||
- 多用户协作/实时协同编辑
|
||
- 插件市场
|
||
- 代码编辑器（只读预览）
|
||
|
||
---
|
||
|
||
## Implementation Units
|
||
|
||
### U1. Design Token 体系 + 主题配置
|
||
|
||
**Goal:** 建立统一的设计令牌系统，消除所有硬编码颜色/间距/圆角值。
|
||
|
||
**Requirements:** R1
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- Create: `src/agentkit/server/frontend/src/styles/tokens.css`
|
||
- Create: `src/agentkit/server/frontend/src/styles/theme.ts`
|
||
- Create: `src/agentkit/server/frontend/src/styles/index.ts`
|
||
- Modify: `src/agentkit/server/frontend/src/App.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/main.ts`
|
||
|
||
**Approach:**
|
||
1. 创建 `tokens.css`，定义 CSS 自定义属性：颜色（primary/secondary/success/error/warning/灰阶/背景/边框）、间距（4/8/12/16/24/32px）、圆角（4/6/8/12px）、字体（12/13/14/16/20/24px）、阴影（sm/md/lg）
|
||
2. 创建 `theme.ts`，定义 Ant Design Vue theme token 映射（将 CSS 变量值映射到 antd token）
|
||
3. 在 `App.vue` 的 ConfigProvider 中注入 theme 配置
|
||
4. 在 `main.ts` 中引入 `tokens.css`
|
||
5. 统一主色为 `#7c3aed`（紫黑渐变起始色），消除 `#1677ff`/`#1890ff` 混用
|
||
|
||
**Patterns to follow:** Ant Design Vue 4.x theme customization API (ConfigProvider theme prop)
|
||
|
||
**Test scenarios:**
|
||
- 验证 CSS 变量在浏览器中正确计算（`getComputedStyle(document.documentElement).getPropertyValue('--color-primary')` 返回 `#7c3aed`）
|
||
- 验证 Ant Design 组件使用新主题色（Button primary 颜色为 `#7c3aed`）
|
||
- 验证自定义组件可通过 `var(--color-primary)` 引用主题色
|
||
|
||
**Verification:** 所有 CSS 变量可计算，Ant Design 组件使用新主题色，无硬编码 `#1677ff`/`#1890ff`。
|
||
|
||
---
|
||
|
||
### U2. 四象限全屏布局 + 顶部导航
|
||
|
||
**Goal:** 将 SideNav 多页面布局重构为四象限全屏布局，顶部极简导航栏。
|
||
|
||
**Requirements:** R2
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- Create: `src/agentkit/server/frontend/src/components/layout/AgentLayout.vue`
|
||
- Create: `src/agentkit/server/frontend/src/components/layout/SplitPane.vue`
|
||
- Create: `src/agentkit/server/frontend/src/components/layout/TopNav.vue`
|
||
- Create: `src/agentkit/server/frontend/src/components/layout/QuadrantPanel.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/App.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/router/index.ts`
|
||
- Preserve: `src/agentkit/server/frontend/src/components/layout/AppLayout.vue`（旧布局保留，路由切换）
|
||
|
||
**Approach:**
|
||
1. 创建 `AgentLayout.vue`：CSS Grid 四象限布局，每个象限是一个 `<QuadrantPanel>`，支持折叠/展开
|
||
2. 创建 `SplitPane.vue`：可拖拽分隔线组件，支持水平/垂直方向，比例持久化到 localStorage
|
||
3. 创建 `TopNav.vue`：48px 高度顶部导航栏，包含 Logo、任务选择器、Agent 状态指示、模式切换、设置入口
|
||
4. 创建 `QuadrantPanel.vue`：象限容器组件，支持标题栏、折叠按钮、Tab 切换
|
||
5. 修改路由：新增 `/agent` 路由使用 AgentLayout，旧路由保留 AppLayout 作为兼容
|
||
6. 默认路由 `/` 重定向到 `/agent`
|
||
|
||
**Patterns to follow:** Devin 四象限布局模式，CSS Grid `grid-template-rows/columns` + `fr` 单位
|
||
|
||
**Test scenarios:**
|
||
- 四象限正确渲染，各象限可独立折叠/展开
|
||
- 分隔线可拖拽调整比例，刷新后比例保持
|
||
- 顶部导航栏正确显示 Logo、状态指示、设置入口
|
||
- 1280px 以下右下象限自动折叠
|
||
|
||
**Verification:** 四象限布局可交互，分隔线可拖拽，比例持久化，响应式断点生效。
|
||
|
||
---
|
||
|
||
### U3. 对话面板重构（左上象限）
|
||
|
||
**Goal:** 将 ChatView 重构为对话面板，支持 Markdown 渲染和工具调用指示器。
|
||
|
||
**Requirements:** R3
|
||
|
||
**Dependencies:** U1, U2
|
||
|
||
**Files:**
|
||
- Modify: `src/agentkit/server/frontend/src/views/ChatView.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/chat/ChatMessage.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/chat/ChatInput.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/chat/ChatSidebar.vue`
|
||
- Create: `src/agentkit/server/frontend/src/components/chat/ToolCallIndicator.vue`
|
||
- Create: `src/agentkit/server/frontend/src/components/chat/ContextPill.vue`
|
||
|
||
**Approach:**
|
||
1. ChatMessage：替换 `v-html` 为 Markdown 渲染（使用 `markdown-it` 或 `marked`），添加工具调用指示器（`[Read]`/`[Edit]`/`[Bash]` 彩色标签）
|
||
2. ChatInput：添加上下文胶囊（Context Pills），显示当前关联的文件/技能
|
||
3. ChatSidebar：改为可折叠侧栏，默认折叠
|
||
4. 流式输出添加打字机效果
|
||
5. 所有硬编码颜色替换为 Design Token 引用
|
||
|
||
**Patterns to follow:** Claude Code 的 Tool Use Indicators，Trae 的 Context Pills
|
||
|
||
**Test scenarios:**
|
||
- Markdown 正确渲染（标题、代码块、列表、链接）
|
||
- 工具调用指示器正确显示类型和颜色
|
||
- 上下文胶囊显示关联文件名
|
||
- 流式输出打字机效果平滑
|
||
|
||
**Verification:** 对话面板功能完整，Markdown 渲染正确，工具调用可视化，无 `v-html`。
|
||
|
||
---
|
||
|
||
### U4. 代码/预览面板（右上象限）
|
||
|
||
**Goal:** 新增代码 Diff 查看和文件预览能力，集成工作流画布和知识库管理。
|
||
|
||
**Requirements:** R4, R7
|
||
|
||
**Dependencies:** U1, U2
|
||
|
||
**Files:**
|
||
- Create: `src/agentkit/server/frontend/src/components/code/CodeDiffViewer.vue`
|
||
- Create: `src/agentkit/server/frontend/src/components/code/FileTree.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/views/WorkflowView.vue`（单页化）
|
||
- Modify: `src/agentkit/server/frontend/src/views/KnowledgeBaseView.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/workflow/FlowCanvas.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/workflow/NodePalette.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/workflow/PropertyPanel.vue`
|
||
|
||
**Approach:**
|
||
1. 创建 `CodeDiffViewer.vue`：只读代码 Diff 展示，支持逐行高亮（红/绿），语法高亮
|
||
2. 创建 `FileTree.vue`：文件树浏览器，展示 Agent 修改的文件列表
|
||
3. 工作流单页化：列表和编辑在同一象限内通过 Tab 切换
|
||
4. 知识库管理集成为此象限的一个 Tab
|
||
5. 象限 Tab 切换：代码 / 工作流 / 知识库
|
||
6. 所有硬编码颜色替换为 Design Token
|
||
|
||
**Patterns to follow:** Cursor Composer 的 Diff 展示，v0.dev 的 Tab 切换
|
||
|
||
**Test scenarios:**
|
||
- 代码 Diff 正确高亮删除/新增行
|
||
- 文件树正确展示文件结构
|
||
- 工作流列表/编辑 Tab 切换流畅
|
||
- 知识库 Tab 正常工作
|
||
- 象限 Tab 切换无闪烁
|
||
|
||
**Verification:** 右上象限支持三种内容切换，代码 Diff 可视化，工作流单页化完成。
|
||
|
||
---
|
||
|
||
### U5. 终端面板重构（左下象限）
|
||
|
||
**Goal:** 将 TerminalView 重构为终端面板，使用 Ant Design 组件替代原生 HTML。
|
||
|
||
**Requirements:** R5
|
||
|
||
**Dependencies:** U1, U2
|
||
|
||
**Files:**
|
||
- Modify: `src/agentkit/server/frontend/src/views/TerminalView.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/terminal/TerminalEmulator.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/terminal/CommandHistory.vue`
|
||
|
||
**Approach:**
|
||
1. 终端背景改为 One Dark Pro 配色（深色背景 + 语法高亮色）
|
||
2. 命令确认弹窗从原生 HTML 改为 Ant Design Modal
|
||
3. 命令历史侧栏改为可折叠
|
||
4. 输入框从原生 `<input>` 改为 Ant Design Input
|
||
5. 所有硬编码颜色替换为 Design Token
|
||
|
||
**Patterns to follow:** One Dark Pro 终端配色，Ant Design Modal 组件
|
||
|
||
**Test scenarios:**
|
||
- 终端输出 ANSI 颜色正确渲染
|
||
- 命令确认弹窗使用 Ant Design Modal 样式
|
||
- 命令历史可折叠展开
|
||
- WebSocket 连接/断开正常
|
||
|
||
**Verification:** 终端面板视觉统一，无原生 HTML 弹窗，One Dark Pro 配色生效。
|
||
|
||
---
|
||
|
||
### U6. 状态/监控面板（右下象限）+ 进化精简
|
||
|
||
**Goal:** 将 EvolutionView 精简后集成为右下象限，集成技能和设置。
|
||
|
||
**Requirements:** R6, R8
|
||
|
||
**Dependencies:** U1, U2
|
||
|
||
**Files:**
|
||
- Modify: `src/agentkit/server/frontend/src/views/EvolutionView.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/evolution/DashboardOverview.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/evolution/MetricsChart.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/components/evolution/UsagePanel.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/views/SkillsView.vue`
|
||
- Modify: `src/agentkit/server/frontend/src/views/SettingsView.vue`
|
||
- Delete: `src/agentkit/server/frontend/src/components/evolution/PitfallRoutePanel.vue`
|
||
- Delete: `src/agentkit/server/frontend/src/components/evolution/OptimizationPanel.vue`
|
||
- Delete: `src/agentkit/server/frontend/src/components/evolution/MetricsPanel.vue`
|
||
- Delete: `src/agentkit/server/frontend/src/components/evolution/ExperiencePanel.vue`
|
||
|
||
**Approach:**
|
||
1. 进化面板精简：6 个子面板合并为 3 个 Tab — 概览+指标、经验+坑点、用量
|
||
2. DashboardOverview：4 列统计卡片改为 2 列，增加趋势迷你图
|
||
3. 设置分组化：4 个 Tab（LLM/技能/知识库/系统），每组独立保存
|
||
4. 象限 Tab 切换：监控 / 技能 / 设置
|
||
5. 删除不再需要的包装组件（PitfallRoutePanel/OptimizationPanel/MetricsPanel/ExperiencePanel）
|
||
6. 所有硬编码颜色替换为 Design Token
|
||
|
||
**Patterns to follow:** Devin 的 Action Timeline，Ant Design Tabs 分组
|
||
|
||
**Test scenarios:**
|
||
- 进化概览+指标 Tab 正确展示
|
||
- 经验+坑点 Tab 合并后功能完整
|
||
- 设置分组 Tab 切换正常，每组独立保存
|
||
- 技能 Tab 正常展示和安装
|
||
|
||
**Verification:** 右下象限支持三种内容切换，进化面板精简完成，设置分组化完成。
|
||
|
||
---
|
||
|
||
### U7. 过渡动画 + 微交互 + 响应式
|
||
|
||
**Goal:** 为所有交互添加过渡动画，实现 1280px+ 响应式断点。
|
||
|
||
**Requirements:** R9, R10
|
||
|
||
**Dependencies:** U1, U2, U3, U4, U5, U6
|
||
|
||
**Files:**
|
||
- Create: `src/agentkit/server/frontend/src/styles/transitions.css`
|
||
- Create: `src/agentkit/server/frontend/src/styles/responsive.css`
|
||
- Modify: `src/agentkit/server/frontend/src/components/layout/AgentLayout.vue`
|
||
- Modify: all view and component files (transition additions)
|
||
|
||
**Approach:**
|
||
1. 创建 `transitions.css`：定义 Vue transition 类（fade/slide/collapse/stagger），统一时长（150ms/200ms/300ms）
|
||
2. 象限折叠/展开：平滑过渡 200ms ease
|
||
3. Tab 切换：淡入淡出 150ms
|
||
4. 列表项加载：交错渐入 stagger 50ms
|
||
5. 空状态：品牌化插图 + 引导文案（替代 `<a-empty>`）
|
||
6. 加载态：骨架屏替代 `<a-spin>`
|
||
7. 创建 `responsive.css`：定义断点（≥1440px 四象限完整，1280-1440px 右下折叠，<1280px 提示）
|
||
8. 象限比例记忆：localStorage 保存用户调整的比例
|
||
|
||
**Patterns to follow:** Vue `<Transition>` 组件，CSS `@media` 断点
|
||
|
||
**Test scenarios:**
|
||
- 象限折叠/展开动画平滑无卡顿
|
||
- Tab 切换淡入淡出效果正确
|
||
- 列表项交错渐入效果
|
||
- 1440px+ 四象限完整展示
|
||
- 1280-1440px 右下象限自动折叠
|
||
- <1280px 显示提示信息
|
||
- 刷新后象限比例保持
|
||
|
||
**Verification:** 所有过渡动画生效，响应式断点正确，比例持久化。
|
||
|
||
---
|
||
|
||
## High-Level Technical Design
|
||
|
||
### 四象限布局架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ TopNav (48px) │
|
||
│ [Logo] [TaskSelector] [AgentStatus] [ModeToggle] [⚙] │
|
||
├──────────────────────────┬──────────────────────────────┤
|
||
│ │ │
|
||
│ QuadrantPanel │ QuadrantPanel │
|
||
│ position="top-left" │ position="top-right" │
|
||
│ ┌─ Tabs ────────────┐ │ ┌─ Tabs ────────────────┐ │
|
||
│ │ Chat (default) │ │ │ Code/Diff (default) │ │
|
||
│ │ Agent Log │ │ │ Workflow │ │
|
||
│ └────────────────────┘ │ │ Knowledge Base │ │
|
||
│ │ └────────────────────────┘ │
|
||
│ ← SplitPane (vertical) →│ │
|
||
├──────────────────────────┼──────────────────────────────┤
|
||
│ │ │
|
||
│ QuadrantPanel │ QuadrantPanel │
|
||
│ position="bottom-left" │ position="bottom-right" │
|
||
│ ┌─ Tabs ────────────┐ │ ┌─ Tabs ────────────────┐ │
|
||
│ │ Terminal (default) │ │ │ Monitor (default) │ │
|
||
│ │ Command History │ │ │ Skills │ │
|
||
│ └────────────────────┘ │ │ Settings │ │
|
||
│ │ └────────────────────────┘ │
|
||
└──────────────────────────┴──────────────────────────────┘
|
||
```
|
||
|
||
### Design Token 映射架构
|
||
|
||
```
|
||
tokens.css (CSS Custom Properties)
|
||
│
|
||
├─→ 自定义组件 (via var(--xxx))
|
||
│
|
||
└─→ theme.ts (Ant Design Theme Token Mapping)
|
||
│
|
||
└─→ ConfigProvider :theme
|
||
│
|
||
└─→ Ant Design 组件 (via CSS-in-JS)
|
||
```
|
||
|
||
### 路由重构
|
||
|
||
```
|
||
/ → /agent (AgentLayout)
|
||
/agent/chat → 左上象限显示 Chat
|
||
/agent/code → 右上象限显示 Code/Diff
|
||
/agent/terminal → 左下象限显示 Terminal
|
||
/agent/monitor → 右下象限显示 Monitor
|
||
|
||
旧路由兼容:
|
||
/workflow → /agent/code?tab=workflow
|
||
/knowledge → /agent/code?tab=knowledge
|
||
/skills → /agent/monitor?tab=skills
|
||
/evolution → /agent/monitor?tab=monitor
|
||
/settings → /agent/monitor?tab=settings
|
||
/terminal → /agent/terminal
|
||
```
|
||
|
||
---
|
||
|
||
## Risks & Mitigations
|
||
|
||
| Risk | Impact | Mitigation |
|
||
|------|--------|------------|
|
||
| 300 处硬编码颜色迁移遗漏 | 视觉不一致 | U1 完成后全局搜索 `#[0-9a-fA-F]{3,6}` 验证零残留 |
|
||
| Vue Flow 在象限内 resize 问题 | 画布渲染异常 | SplitPane 拖拽结束时触发 window resize 事件 |
|
||
| ECharts 颜色需单独处理 | 图表颜色不跟随主题 | 在 ECharts 初始化时从 CSS 变量读取颜色 |
|
||
| 大型组件迁移引入回归 | 功能损坏 | 每个单元完成后运行现有测试 + 手动验证 |
|
||
| 四象限布局在小屏幕下体验差 | 不可用 | R10 响应式断点确保 1280px+ 可用 |
|
||
|
||
## Open Questions
|
||
|
||
- Code Diff Viewer 是否需要引入第三方库（如 diff2html）还是手写简单 diff 展示？→ 建议先用简单行级高亮，后续迭代引入 diff2html
|
||
- 骨架屏组件是自建还是使用 Ant Design Vue 的 Skeleton？→ 建议使用 antd Skeleton，减少维护成本
|