# 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 体系 —— 文本是主体，色彩是信号
- 重新设计聊天主区布局：常规气泡 + 复杂事件拆为 card（Cursor / 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 bar：48px 高，左对齐文字 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)
