fischer-agentkit/docs/brainstorms/2026-06-13-gui-productization-requirements.md

date	topic	status
2026-06-13	gui-productization	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> 组件可满足过渡动画需求