22 KiB
22 KiB
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 的colorPrimarytoken 改为#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 个静态场景，全部用假数据：
- 欢迎页 —— 居中 logo + 4 个能力提示 + 输入框预填「@team:tech_lead,frontend_engineer,backend_engineer 设计一个用户认证系统」
- User 消息 + Assistant 文本 + 代码块 —— user 提问，assistant 流式响应含 markdown + 代码
- @team 计划 + 阶段进行中 —— TeamPlanCard 显示 3 阶段，第 1 阶段 running，专家子项展开
- @board 多轮讨论 —— BoardBanner + 3 轮不同专家发言 + 1 个主持人小结 + 1 个最终结论
- 工具调用链 —— 嵌套 2 层 tool call，状态点变化
- 错误态 —— 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 验收检查点
- Mockup review (核心验收)：用户看
/agent/preview，对 6 个场景逐一 review，决定是否进入实施 - Token review：对照本规范 §2 确认 token 命名和值
- 组件 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
- 来源：Trae CN 2026 完全指南
- 来源：Claude Code vs Cursor 2026