---
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>` 组件可满足过渡动画需求