fischer-agentkit/docs/brainstorms/2026-06-18-chat-area-vi-red...

393 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Fischer AgentKit — 聊天主区 VI 重梳与新功能适配 (Requirements)
**Date:** 2026-06-18
**Status:** Draft
**Scope:** 聊天主区布局 + 右屏可收起 Tab 面板 + @team / @board 消息适配
**Out of scope:** 侧边栏 (ChatSidebar)、顶部 (TopNav)、抽屉 (右抽屉)、移动端布局
---
## 1. Context & Problem
### 1.1 现状
- 主色 `#6366f1` (indigo) —— Notion 风格暖灰基底但品牌感弱与「Fischer」德系工业严谨感的名字不匹配
- 聊天主区是简单的气泡 + 流式步骤,缺少对**复杂 AI 响应**@team 计划、@board 多轮讨论、工具调用链、错误恢复)的精细化表达
- 新功能(@board 私董会、@team 专家团)已有后端事件流(`board_started` / `expert_speech` / `round_summary` / `team_formed` / `plan_update` / `phase_started` ...),但前端在 `ChatMessage.vue` 中只是把它们当成普通消息流式渲染,**没有专属视觉表达**
- 私董会当前色 `#8E44AD` 偏沉,与整体调性割裂
### 1.2 目标
- 形成 **「克制中性 + 强调色做语义信号」** 的 VI 体系 —— 文本是主体,色彩是信号
- 重新设计聊天主区布局:常规气泡 + 复杂事件拆为 cardCursor / Trae 范式)
-@team / @board / 工具调用 / 错误四类复杂事件提供专属 card 视觉语言
- 保留右屏可收起 Tab 面板(监控 / 技能 / 系统 / 知识库),但样式与新 VI 一致
- 产出一份**静态高保真 mockup**(独立 preview 路由),供 review 后再进入实施
### 1.3 设计哲学
> **Notion 的留白 + Cursor 的复杂事件 card + Trae 的可收起右屏 + 我们自己的中性克制**
- **Notion**:暖灰基底 (`#fbfbfa` / `#ededec`),柔和阴影 (low-opacity, more spread),暖色代码高亮 (Catppuccin Mocha)
- **Cursor**复杂事件agent 计划、工具调用、错误)拆为独立 card不挤在普通消息流中
- **Trae**:右屏 Tab 面板可收起,主区最大化
- **我们自己的****主色由 indigo 改为近黑 + 中性灰**,强调色 (accent) 仅用于语义信号
---
## 2. Design Language Specification
### 2.1 Color System (Light Theme)
| Token | Value | 用途 |
|---|---|---|
| `--bg-primary` | `#ffffff` | 主背景 (消息区、card) |
| `--bg-secondary` | `#fbfbfa` | 次背景 (整体 app shell、输入框) |
| `--bg-tertiary` | `#f7f7f5` | 三级背景 (hover、嵌套 card) |
| `--bg-code` | `#1e1e2e` | 代码块背景 (Catppuccin Mocha) |
| `--text-primary` | `#1a1a1a` | 主文字 (95% 文本) |
| `--text-secondary` | `#4a4a4a` | 次文字 (元数据、辅助) |
| `--text-tertiary` | `#6b6b6a` | 三级文字 (时间戳、状态) |
| `--text-placeholder` | `#9b9b9a` | 占位符 |
| `--border-color` | `#ededec` | 默认边框 |
| `--border-color-hover` | `#dfdfde` | hover 边框 |
**强调色 (新增)**
| Token | Value | 语义 | 使用场景 |
|---|---|---|---|
| `--accent-team` | `#3b82f6` | 专家团协作 (中性蓝) | @team plan card、expert avatar、team 状态条 |
| `--accent-board` | `#a855f7` | 私董会讨论 (琥珀/紫) | @board banner、moderator 头像、board round 进度 |
| `--accent-team-soft` | `#dbeafe` | 蓝轻量背景 | @team card 顶条、chip |
| `--accent-board-soft` | `#f3e8ff` | 紫轻量背景 | @board card 顶条、moderator chip |
**语义色 (保留)**
| Token | Value | 语义 |
|---|---|---|
| `--color-success` | `#22c55e` | 工具调用成功、阶段 completed |
| `--color-warning` | `#f59e0b` | 主持人小结 (round summary) |
| `--color-error` | `#ef4444` | 错误、阶段 failed |
| `--color-info` | `#3b82f6` | 普通信息 |
> 关键变化:**移除 `--color-primary` (indigo) 作为通用主色**,改用 `--accent-team` / `--accent-board` 作为功能语义色。Ant Design 的 `colorPrimary` token 改为 `#1a1a1a` (近黑),让通用 UI (按钮、菜单选中) 都是中性。
### 2.2 Color System (Dark Theme)
| Token | Value |
|---|---|
| `--bg-primary` | `#1a1a1a` |
| `--bg-secondary` | `#1f1f1f` |
| `--bg-tertiary` | `#2a2a2a` |
| `--text-primary` | `#fbfbfa` |
| `--text-secondary` | `#cececd` |
| `--accent-team` | `#60a5fa` (亮蓝) |
| `--accent-team-soft` | `rgba(59, 130, 246, 0.15)` |
| `--accent-board` | `#c084fc` (亮紫) |
| `--accent-board-soft` | `rgba(168, 85, 247, 0.15)` |
### 2.3 Typography
- 主字体:现有 `font-family` 不变(系统字体栈)
- 字体大小:保留现有 token (`--font-xs` ~ `--font-xl`)
- **新增**`--font-mono` (代码字体, SF Mono / Monaco / Consolas)
- **新增**`--leading-message: 1.65` —— 消息正文行高(比现有 `--leading-normal: 1.5` 更松,提升长文阅读体验)
### 2.4 Spacing & Layout
- 间距:保留现有 4/8/12/16/20/24/32 scale
- 圆角:保留现有 4/6/10/14 scale
- **新增**`--radius-card: 12px` (复杂 card 圆角,比 chat bubble 的 `--radius-lg: 10px` 略大)
- **新增**`--space-message-gap: 24px` (消息之间间距)
### 2.5 Shadow
- 保留现有 4 档 shadow (sm/md/lg/xl)
- **新增**`--shadow-card: 0 1px 3px rgba(0,0,0,0.04), 0 0 0 1px rgba(0,0,0,0.04)` (复杂 card 边框+微阴影组合Notion 风格)
---
## 3. Chat Main Area — Layout & Message Architecture
### 3.1 整体布局
```
┌─────────────────────────────────────────────────────────┐
│ TopNav (48px) │
├──────────┬──────────────────────────────────┬───────────┤
│ │ │ │
│ Sidebar │ Chat Main Area │ Right │
│ 280px │ (resizable) │ Panel │
│ │ │ (320px) │
│ │ ┌────────────────────────────┐ │ Tab: │
│ │ │ BoardStatusView (顶部状态) │ │ - 监控 │
│ │ ├────────────────────────────┤ │ - 技能 │
│ │ │ │ │ - 系统 │
│ │ │ Message List │ │ - 知识库 │
│ │ │ (user / assistant 气泡) │ │ │
│ │ │ + TeamPlanCard │ │ 可收起 → │
│ │ │ + BoardRoundCard │ │ │
│ │ │ + ToolCallCard │ │ │
│ │ │ + ThinkingBlock │ │ │
│ │ │ │ │ │
│ │ ├────────────────────────────┤ │ │
│ │ │ ChatInput (输入框) │ │ │
│ │ └────────────────────────────┘ │ │
└──────────┴──────────────────────────────────┴───────────┘
```
- 主区最大宽度 `max-width: 860px` 居中(防止超宽屏阅读疲劳),左右侧贴边留白用 `--space-4`
- 右屏默认展开 320px可收起至 0折叠按钮在主区右上角IconNav 同步)
- 消息垂直节奏:消息之间 `--space-message-gap: 24px`;气泡内部 padding `--space-3 var(--space-4)`
### 3.2 Message Types & Visual Treatment
| Type | Trigger | 视觉范式 | 颜色信号 | 关键元素 |
|---|---|---|---|---|
| **user** | `role: 'user'` | 60% 宽右对齐气泡 | 中性灰背景 `--bg-tertiary` | 文本 + 附件 pill + hover 显示「编辑/复制」 |
| **assistant (text)** | `role: 'assistant'`, `message_type: 'chat'` | 90% 宽左对齐 flat (无气泡) | 无 | Markdown 渲染 + 代码高亮 + 引用块 |
| **assistant (thinking)** | `thinking` 字段非空 | 折叠块 (Cursor 风格) | 灰色 `--text-tertiary` | 「已思考 N 秒」可点击展开 |
| **tool call** | `tool_calls[]` 非空 | 嵌套 card (边框 + 阴影) | 中性 + 成功绿 / 错误红 | 工具名 + 状态点 (●) + 折叠参数/结果 |
| **team plan** | `team_formed` / `plan_update` | 跨整行大 card | **蓝色顶条** (`--accent-team`) | Lead expert 头像 + 阶段时间线 + 状态图标 |
| **team expert step** | `expert_step` | 内嵌 plan card 的子项 | 蓝 | expert 头像 + 当前步骤描述 |
| **team expert result** | `expert_result` | 内嵌 plan card 的子项 | 蓝 | 折叠结果块 (类似 tool call) |
| **team synthesis** | `team_synthesis` | 跨整行结论 card | 蓝 | 渐变顶条 + 总结文本 |
| **board started** | `board_started` | 跨整行 banner card | **紫色顶条** (`--accent-board`) | 主题 + 专家 chips + 主持人标签 |
| **board expert speech** | `expert_speech` | 90% 宽左对齐,带 expert 头像 chip | 紫 | 头像 + 第 N 轮 + 角色标签 (主持/专家) |
| **board round summary** | `round_summary` | 主持人头像 + 总结文本 | 紫轻背景 `--accent-board-soft` | 折叠块 (默认收起避免噪声) |
| **board conclusion** | `board_concluded` + `final_answer` | 跨整行结论 card | 紫渐变顶条 | 共识 + 分歧 + 决策建议 |
| **error** | `error` | 跨整行 alert 样式 | 红色 `--color-error` | 错误信息 + 「重试」按钮 |
### 3.3 关键交互细节
**气泡 (常规)**
- user 气泡 hover显示「编辑」「复制」图标
- assistant 文本 hover底部浮现操作条「复制」「重新生成」「反馈 👍👎」
- 流式光标:文本末尾 2px 宽闪烁竖线 (Cursor 风格) 或 8x8 圆点 (Claude 风格) —— **选竖线,更克制**
- Markdown 实时渲染:流式过程中不渲染重型 syntax highlight避免闪烁
**Thinking Block (新增)**
- 默认收起,显示「已思考 N 秒」+ chevron
- 展开后显示 thinking 文本 (灰色)
- 动画:展开时 height transition 200ms
**Tool Call Card**
- 默认收起 (只显示工具名 + 状态点)
- 点击展开:参数 (折叠) + 结果 (折叠)
- 错误:状态点变红 + 行内错误信息
- 成功:状态点变绿
- 嵌套调用:缩进 16px最多嵌套 3 层
**Team Plan Card (新增)**
```
┌──────────────────────────────────────────────────────┐
│ ▌ Lead: Sarah Chen (技术负责人) [In Progress] │ ← 蓝色顶条 4px
├──────────────────────────────────────────────────────┤
│ 阶段 1: 数据模型设计 ● running │
│ ├─ 张三 (后端) 正在分析 schema... │
│ └─ 完成时间: ~2 min │
│ │
│ 阶段 2: API 实现 ○ pending (依赖 阶段1) │
│ 阶段 3: 测试 ○ pending (依赖 阶段2) │
├──────────────────────────────────────────────────────┤
│ 进度: ████████░░░░░░ 45% 当前: 阶段 1 / 3 │
└──────────────────────────────────────────────────────┘
```
**Board Banner (新增)**
```
┌──────────────────────────────────────────────────────┐
│ ▌ 🏛️ 私董会 — 主题:「是否应投入资源做这个功能」 │ ← 紫色顶条 4px
├──────────────────────────────────────────────────────┤
│ 专家: 🚀 Elon 🛒 Jeff 🧠 Charlie 💻 Paul │
│ [主持人] Elion Musk │
│ 轮次: 第 2 / 5 [████████░░░░] 40% │
└──────────────────────────────────────────────────────┘
```
**Board Round Card (单轮发言)**
```
┌──────────────────────────────────────────────────────┐
│ 🚀 Elon Musk · 第 2 轮 · 主持人 │ ← 紫色边 1px 左侧
│ │
│ 我认为第一性原理是... │
│ [长文本...] │
│ 09:32 │
└──────────────────────────────────────────────────────┘
```
---
## 4. Right Panel (Tab Panel)
### 4.1 行为
- 位置:主区右侧,初始 320px 宽
- Tab监控 / 技能 / 系统 / 知识库 (4 个,对应附件图)
- 折叠按钮:主区右上角 (ChatView 顶部) 一个 chevron 按钮,折叠后宽度 0折叠按钮变为「展开」chevron
- 折叠状态记忆localStorage 持久化
- 拖拽:可选 (后续迭代,本期不做)
### 4.2 样式
- 背景:`--bg-secondary` (与主区背景区分但不抢戏)
- 顶部 Tab bar48px 高,左对齐文字 Tab激活 Tab 下方 2px 蓝色 (或当前 Tab 主题色) 指示条
- 内边距:`var(--space-3) var(--space-4)`
- 卡片:与主区 card 一致 (12px 圆角 + 1px 边框)
### 4.3 Tab 内容 (沿用现有数据)
- **监控**4 个 metric card (服务可用性 / 平均响应时间 / 请求总数 / 错误率) + 资源使用列表 + 服务状态列表 + 错误趋势图
- **技能**:技能列表 (来自 `useSkillsStore`),点击展开详情
- **系统**:系统信息 (CPU / 内存 / 磁盘)
- **知识库**:知识库源列表 + 检索测试入口
---
## 5. Input Area
### 5.1 现状
- 输入框 + 发送按钮 + 模型选择 + (新增) 私董会按钮
### 5.2 改造
- **私董会按钮 → 重命名为「专家团」** 按钮,紫色 `--accent-board` 高亮
- 新增「**@team** 团队」按钮 (蓝色 `--accent-team`),与私董会按钮并列
- 两个按钮都点击打开对应 Modal (已有的 `BoardMeetingModal.vue` + 新建 `TeamMeetingModal.vue`)
- 拖拽附件:拖入文件到输入框显示「拖放以附加」浮层
- @mention 自动补全:现有 `MentionDropdown` 保留
### 5.3 入口设计
```
┌──────────────────────────────────────────────────┐
│ [📎 附件] [👥 专家团] [🏛️ 私董会] │
├──────────────────────────────────────────────────┤
│ │
│ 输入消息... │
│ │
├──────────────────────────────────────────────────┤
│ [模型: Claude 4 Sonnet ▾] [清空] [发送 →] │
└──────────────────────────────────────────────────┘
```
---
## 6. Components to Build / Modify
### 6.1 修改现有
| 文件 | 改动 |
|---|---|
| `src/agentkit/server/frontend/src/styles/tokens.css` | 新增 `--accent-team*` / `--accent-board*` / `--shadow-card` 等 token移除 `--color-primary` 作为主色 (保留作为渐变背景) |
| `src/agentkit/server/frontend/src/styles/theme.ts` | `colorPrimary` 改为近黑;新增 accent 主题组件配置 |
| `src/agentkit/server/frontend/src/views/ChatView.vue` | 主区 max-width 居中 + 右屏折叠按钮 + 整体留白节奏调整 |
| `src/agentkit/server/frontend/src/components/chat/ChatMessage.vue` | 重构分发:按 `message_type` 路由到对应子组件 |
| `src/agentkit/server/frontend/src/components/chat/ExpertMessage.vue` | 适配新 VI |
| `src/agentkit/server/frontend/src/components/chat/ToolCallCard.vue` | 已有,确认样式对齐新 token |
| `src/agentkit/server/frontend/src/components/chat/ThinkingBlock.vue` | 已有,新增折叠动画 |
| `src/agentkit/server/frontend/src/components/chat/BoardStatusView.vue` | 用 `--accent-board` 替换 `#8E44AD` |
| `src/agentkit/server/frontend/src/components/chat/ExpertTeamView.vue` | 用 `--accent-team` 替换默认色 |
| `src/agentkit/server/frontend/src/components/chat/ChatInput.vue` | 新增「专家团」按钮 (蓝色) + 重命名「私董会」按钮为紫色 |
| `src/agentkit/server/frontend/src/components/chat/BoardMeetingModal.vue` | 适配新 VI |
### 6.2 新增组件
| 文件 | 用途 |
|---|---|
| `src/agentkit/server/frontend/src/components/chat/TeamPlanCard.vue` | @team 计划可视化 (时间线 + 阶段 + 进度) |
| `src/agentkit/server/frontend/src/components/chat/BoardRoundCard.vue` | @board 单轮发言 (专家头像 + 轮次 + 文本) |
| `src/agentkit/server/frontend/src/components/chat/BoardConclusionCard.vue` | @board 最终结论 (共识 + 分歧 + 建议) |
| `src/agentkit/server/frontend/src/components/chat/ErrorCard.vue` | 错误提示 card (含重试按钮) |
| `src/agentkit/server/frontend/src/components/chat/UserBubble.vue` | user 消息气泡 (提取自 ChatMessage) |
| `src/agentkit/server/frontend/src/components/chat/AssistantBubble.vue` | assistant 消息 flat 块 (提取自 ChatMessage) |
| `src/agentkit/server/frontend/src/components/chat/TeamMeetingModal.vue` | @team 专家团选择 Modal (对标 BoardMeetingModal) |
| `src/agentkit/server/frontend/src/components/layout/RightPanel.vue` | 可折叠右屏 Tab 面板 |
| `src/agentkit/server/frontend/src/views/ChatPreviewView.vue` | 静态高保真 mockup 页面 (供 review) |
### 6.3 Mockup 页面 (Preview View)
6 个静态场景,**全部用假数据**
1. **欢迎页** —— 居中 logo + 4 个能力提示 + 输入框预填「@team:tech_lead,frontend_engineer,backend_engineer 设计一个用户认证系统」
2. **User 消息 + Assistant 文本 + 代码块** —— user 提问assistant 流式响应含 markdown + 代码
3. **@team 计划 + 阶段进行中** —— TeamPlanCard 显示 3 阶段,第 1 阶段 running专家子项展开
4. **@board 多轮讨论** —— BoardBanner + 3 轮不同专家发言 + 1 个主持人小结 + 1 个最终结论
5. **工具调用链** —— 嵌套 2 层 tool call状态点变化
6. **错误态** —— ErrorCard + 「重试」按钮
---
## 7. Dependencies & Assumptions
### 7.1 Assumptions
- A1: 用户已确认主色方向为「近黑 + 强调色」
- A2: 用户已确认中等改造范围 (聊天主区 + 右屏),不碰侧边栏/顶部/抽屉
- A3: 用户已确认混合消息范式 (气泡 + card)
- A4: 现有后端事件 (team_formed / expert_step / board_started / expert_speech / round_summary / board_concluded) 的 payload 字段不变
- A5: 现有 WebSocket 协议不变,只改前端渲染
- A6: 暗色模式 token 一并提供 (本需求重点是浅色,深色保持 token 同步)
- A7: 不实现 message editing / branch conversation (Trae 独有)
- A8: 不实现图片/文件 inline 渲染优化 (现有 `FilePreview.vue` 够用)
### 7.2 Risks
- **R1 (高)**: ChatMessage.vue 重构可能影响现有 unit test —— 需检查测试覆盖
- **R2 (中)**: 大量组件修改可能引入回归 —— 建议每组件单独 PR
- **R3 (中)**: mockup 评审 → 实施可能有偏差 —— mockup 应在 PR 之前完成
### 7.3 Out of Scope (Explicit)
- 侧边栏 (ChatSidebar.vue) 重构
- 顶部导航 (TopNav.vue) 重构
- 移动端响应式优化
- 实际 WebSocket 数据流对接 (mockup 阶段)
- 可访问性 (a11y) 审计
- 性能优化 (虚拟滚动、消息懒加载) —— 独立 PR
---
## 8. Success Criteria
### 8.1 完成定义
- [ ] 静态 mockup 页面 (`/agent/preview`) 6 个场景全部可看可交互
- [ ] `tokens.css` + `theme.ts` 全部新 token 已就位且通过 lint
- [ ] 所有改动组件 `vue-tsc --noEmit` 通过
- [ ] 所有改动组件 `ruff check` 通过 (Python 端)
- [ ] 现有 unit test 不回归 (`pytest tests/unit/ -x -q`)
- [ ] 暗色模式 token 同步更新
- [ ] 视觉 review 通过 (用户签字)
### 8.2 验收检查点
1. **Mockup review** (核心验收):用户看 `/agent/preview`,对 6 个场景逐一 review决定是否进入实施
2. **Token review**:对照本规范 §2 确认 token 命名和值
3. **组件 review**:每个新组件单独 PR 走 code review
---
## 9. Open Questions
- Q1: @team 蓝 (`#3b82f6`) vs @board 紫 (`#a855f7`) 的分配是否调换?当前:蓝=协作,紫=深度
- Q2: 流式光标样式:竖线 vs 圆点?提议:竖线 (更克制)
- Q3: 私董会按钮文字:是「私董会」还是「@board 讨论」?提议:「私董会」(短)
- Q4: 专家团按钮文字:是「专家团」「@team」「召唤专家」提议「专家团」
- Q5: 是否需要「消息引用」功能 (Trae 的 <#file> 引用)?提议:本期不做
---
## 10. Reference
- 参考设计语言Notion (留白 / 暖灰 / 柔和阴影), Cursor (复杂事件 card), Trae (可收起右屏 + Side Chat)
- 行业共识 (setproduct 2026-05-29)
- Full-width is current best practice for serious AI chat. Bubbles signal "messenger" and undermine the tool framing.
- Use subtle background shading or alignment to separate user and assistant messages instead.
- Streaming cursor must exist; dropping it is a common mistake.
- Markdown rendering during stream: don't render heavy syntax highlight during streaming to avoid flickering.
- 来源:[Designing AI chat interfaces: Anatomy, patterns, pitfalls](https://www.setproduct.com/blog/ai-chat-interface-ui-design)
- 来源:[Trae CN 2026 完全指南](https://blog.csdn.net/the_finals/article/details/161893557)
- 来源:[Claude Code vs Cursor 2026](https://www.aidesigner.ai/blog/claude-code-vs-cursor)