125 lines
10 KiB
Markdown
125 lines
10 KiB
Markdown
---
|
||
date: 2026-07-01
|
||
topic: ui-ue-enhancement
|
||
---
|
||
|
||
## Summary
|
||
|
||
强化 AgentKit 聊天与日历模块的 UI/UE：让 agent 思考过程与团队/私董会结果真正流式可见，让 @team/@board 模式在对话顶部持久显式，去除常驻噪声，给用户消息补齐复制/删除/回填操作，并让日历回到 Notion 风格的统一设计语言。
|
||
|
||
---
|
||
|
||
## Problem Frame
|
||
|
||
当前聊天主界面 `src/agentkit/server/frontend/src/views/ChatView.vue` 在顶部堆叠了三个 banner（`ExpertTeamView`、`BoardStatusView`、`PhaseIndicator`），但前两者为静态文案且不可点击，无法回答"这次 @team 要解决什么任务、由哪些专家参与"这类基本问题。助手消息区域有两个层面的可读性问题：`ThinkingBlock.vue` 默认折叠且渲染为纯文本，看不到 agent 的推理过程；`AssistantText.vue:32-42` 的路由元信息 tag（matched_skill / confidence / routing_method）常驻显示，对终端用户是无意义噪声。用户消息气泡 `UserBubble.vue` 是一个纯 `<div>`，无任何悬停操作，复制、删除、回填输入框重发都做不到。私董会与专家团的最终结果在 `chatStream.ts:677-696`（`expert_result`）和 `chatStream.ts:771-787`（`team_synthesis`）中以完整事件块到达前端，无法流式呈现，与 `final_answer`（`chatStream.ts:526-532`，token 累加流式）体验割裂。日历模块 `CalendarGrid.vue` 直接使用 FullCalendar 默认样式，硬编码 `#1677ff`（`CalendarGrid.vue:38`）与 `styles/tokens.css` 的 Notion 调色板（`--color-primary: #1a1a1a`、`--accent-team: #3b82f6`、`--accent-board: #a855f7`）完全脱节。
|
||
|
||
---
|
||
|
||
## Key Decisions
|
||
|
||
- **思考展示采用"展开流式 + 完成后收起为摘要条"的混合方案。** 思考进行中时始终展开并显示流式光标，思考结束后自动收起为一行摘要条（点击可再展开查看完整内容），既满足"看到 agent 在想什么"的诉求，又避免长篇思考内容长期挤占对话视野。
|
||
- **@team/@board 头部采用 sticky 持久条，替换 `ExpertTeamView` 与 `BoardStatusView`。** 新头部由"模式 badge + 任务目标 / 私董会主题 + 专家头像组"组成，专家头像点击后弹出详情面板查看具体专家清单与角色。`PhaseIndicator`（PLAN_EXEC 模式）独立保留在 sticky 头部下方，不并入头部条。
|
||
- **日历采用"FullCalendar 核心 + 自定义外壳"方案。** 保留 FullCalendar 的视图切换、日期网格、事件拖拽能力，但侧栏、事件卡片、头部工具栏使用 token 重绘，FC 内部 `.fc-*` 元素通过覆盖式 CSS 对齐 Notion 风格。
|
||
- **team/board 结果流式在范围内，需后端改动。** 当前 `expert_result` 与 `team_synthesis` 作为完整事件块发送，需引入事件变体（如 `expert_result_chunk` / `team_synthesis_chunk`）或 token 分块推送，前端再做流式渲染，与 `final_answer` 的流式体验对齐。
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
### 思考展示（Thinking Display）
|
||
|
||
- R1. 思考进行中时，`ThinkingBlock` 默认展开并显示流式光标，token 实时累加，不折叠。
|
||
- R2. 思考完成后自动收起为一行摘要条，摘要条显示思考开始时间与 token 数（或等价摘要信息），点击可重新展开查看完整内容。
|
||
- R3. 摘要条与展开态之间切换不丢失已流式接收的内容，再次展开时定位到上一次滚动位置。
|
||
|
||
### @team/@board 头部（Sticky Mode Header）
|
||
|
||
- R4. `@team` / `@board` 模式进入对话后，在消息列表上方渲染一条 sticky 持久头部条，替换现有 `ExpertTeamView` 与 `BoardStatusView` 两个组件。
|
||
- R5. 头部条左侧显示模式 badge（"专家团" / "私董会"），中间显示任务目标（@team）或主题（@board），右侧显示专家头像组。
|
||
- R6. 专家头像组中的每个头像可点击，点击后弹出详情面板显示该专家的现有元数据（与 `configs/experts/*.yaml` 中的 `description` / `persona` / `avatar` / `color` 字段对齐；不假设存在 `role` / `bio` 等未定义字段）。
|
||
- R7. `PhaseIndicator`（PLAN_EXEC 模式）独立显示在 sticky 头部条下方，不并入头部条，保持其现有阶段进度展示语义。
|
||
|
||
### 团队/私董会流式输出（Team/Board Streaming）
|
||
|
||
- R8. `expert_result` 事件改为流式输出体验：专家生成结果时前端流式累加渲染，与 `final_answer` 的流式体验对齐。后端推送机制（token 分块、文本块、或事件变体）属跨切面依赖，见"Scope Boundaries"。
|
||
- R9. `team_synthesis` 事件改为流式输出体验：Lead 综合阶段的结果前端流式累加渲染。后端推送机制同 R8。
|
||
- R10. 流式过程中显示专家/团队身份标识（如"专家 A 正在输出…"），流式结束后标识保留在最终消息上。此"身份标识"属用户可见的专家 badge，区别于 R12 的内部路由元信息 tag。
|
||
- R11. 流式推送方案待定（事件变体或 token 分块二者择一），由后端协议设计阶段决定；前端订阅流式输出即可，不预设具体实现方案。
|
||
|
||
### 路由元信息标签（Routing Tags）
|
||
|
||
- R12. `AssistantText.vue:32-42` 的路由元信息 tag 区（matched_skill / confidence / routing_method）默认隐藏，仅当用户悬停助手消息时显示。
|
||
- R13. 悬停显示时使用淡入过渡，避免突兀闪烁；移开悬停后淡出。
|
||
|
||
### 用户消息悬停操作（User Message Hover Actions）
|
||
|
||
- R14. 用户消息气泡（`UserBubble.vue`）支持悬停时显示操作工具条，包含三个操作：复制、删除、回填输入框重发。
|
||
- R15. 复制：将消息文本复制到剪贴板，复制成功后给一个轻量反馈（如工具条图标短暂变色）。
|
||
- R16. 删除：从当前视图隐藏该消息（从 `chatStore.currentMessages` 中移除），需二次确认以防止误删。此为前端隐藏，不删除服务端副本；服务端删除语义留待后续迭代。
|
||
- R17. 回填输入框重发：将消息文本回填到 `ChatInput` 的输入框，不自动发送，由用户决定是否修改后重发；回填后该消息不从列表中删除。
|
||
|
||
### 日历重设计（Calendar Redesign）
|
||
|
||
- R18. 提取主界面 Notion 设计语言为可复用 token 集，日历模块统一消费 `styles/tokens.css` 中的颜色、间距、圆角、阴影变量，禁止硬编码颜色值（如 `CalendarGrid.vue:38` 的 `#1677ff`）。
|
||
- R19. 日历侧栏（事件列表/筛选）使用 token 重绘，与主界面的卡片、列表视觉语言一致。
|
||
- R20. 日历事件卡片使用 token 调色板，事件类型颜色从配置映射到 token（如 `--accent-team` 用于团队事件、`--accent-board` 用于私董会事件）。
|
||
- R21. 日历头部工具栏（视图切换、今天按钮、导航箭头）使用 token 重绘，按钮风格与主界面按钮一致。
|
||
- R22. FullCalendar 内部 `.fc-*` 元素通过覆盖式 CSS 对齐 Notion 风格（字体、边框、表头背景、今日高亮），覆盖范围最小化以保持 FC 升级兼容性。
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
### Deferred for later
|
||
|
||
- 思考内容的 markdown 渲染：本期 `ThinkingBlock` 仍以纯文本或等宽文本呈现，markdown 解析渲染留待后续迭代。
|
||
- 日历事件的拖拽创建、resize 行为变更：本期仅重绘视觉外壳，不改变 FC 既有交互行为。
|
||
- 专家头像组中专家在线状态指示：本期仅展示静态头像与详情，不接入实时在线状态。
|
||
- 路由元信息 tag 的可配置显示规则：本期固定为"默认隐藏 + 悬停显示"，不做用户偏好配置。
|
||
|
||
### Outside this product's identity
|
||
|
||
- 不引入新的 UI 组件库或设计系统（继续基于 Ant Design Vue + token 覆盖）。
|
||
- 不替换 FullCalendar 为自建日历组件（保留 FC 核心，仅覆盖外壳与 `.fc-*` 样式）。
|
||
- 不改变 `PhaseIndicator` 的现有阶段进度语义与展示形式（仅独立保留，不重设计）。
|
||
|
||
### Cross-cutting dependencies（非 UI/UE scope，但需协同）
|
||
|
||
- 后端流式推送协议：R8/R9 的流式体验依赖后端推送机制（token 分块 / 文本块 / 事件变体），具体方案由后端协议设计阶段决定，不属本文档 scope。
|
||
|
||
---
|
||
|
||
## Open Questions
|
||
|
||
需用户判断或设计决策的事项，来自 ce-doc-review 审查。
|
||
|
||
### 交互状态与无障碍
|
||
|
||
- OQ1. 交互状态覆盖（错误态 / 空态 / 加载态）的范围与规范——流式中断、专家失败、无结果等场景如何呈现？（design-lens, P1, conf 100）
|
||
- OQ2. 响应式与无障碍策略——sticky 头部、头像组、悬停操作、日历重设计的断点、键盘可达、ARIA 规范？（design-lens, P1, conf 100）
|
||
|
||
### 流式输出设计决策
|
||
|
||
- OQ3. R8/R9 流式结构——事件变体（如 `expert_result_chunk`）vs token 分块推送？结构化事件元数据（专家身份、阶段标识）如何与流式 token 边界协调？（adversarial, P1, conf 75）
|
||
|
||
### 删除语义
|
||
|
||
- OQ4. R16 删除作用域——前端隐藏（当前 R16 已改述）是否满足用户意图？是否需要服务端删除以避免刷新后消息复活？（adversarial + scope-guardian, P1/P2, conf 75）
|
||
|
||
### 用户流与交互细节
|
||
|
||
- OQ5. @team/@board 模式切换与多专家并发流式输出的用户流——并发到达时如何呈现身份与顺序？（design-lens, P2, conf 75）
|
||
- OQ6. 关键交互细节——删除确认 UI 形态（Modal/Popconfirm）、头像溢出规则、详情面板组件类型（Drawer/Modal/Popover）？（design-lens, P2, conf 75）
|
||
|
||
### FullCalendar 兼容性
|
||
|
||
- OQ7. R22 `.fc-*` 类名覆盖的升级风险容忍度——`.fc-*` 非公开 API，FC 升级时可能破坏；是否接受定期维护成本，或约束覆盖范围至更稳定的选择器？（adversarial, P2, conf 75）
|
||
|
||
### Sticky 头部替代方案
|
||
|
||
- OQ8. Sticky 头部决策是否考虑过更简替代——使现有 `ExpertTeamView` / `BoardStatusView` banner 可点击展开详情，而非整体替换为 sticky 条？（adversarial, P2, conf 75）
|
||
|
||
### 模式可发现性
|
||
|
||
- OQ9. @team/@board 模式可发现性目标——用户如何得知这两个模式存在？是否需要在输入提示或空态中引导？（product-lens, FYI, conf 50）
|