24 KiB

Raw Blame History

status	date	type	origin
active	2026-06-19	feat	docs/brainstorms/2026-06-18-chat-area-vi-redesign-requirements.md

feat: 聊天主区 VI 重梳与新功能适配 — 实施计划（执行中 / 复审版）

Summary

本计划承接聊天主区 VI 重梳需求文档，目标是把需求中的设计令牌、消息视觉范式、右屏 Tab 面板、@team / @board 消息适配以及 Preview 静态样例全部落地。

当前进展（截至复审时点）：

U1. 补齐设计令牌与主题映射 已完成：tokens.css 与 theme.ts 新增 --radius-card、--font-mono、--accent-team*、--accent-board*、--shadow-card 等；关键组件已使用语义 token。
U2. 消息模型与分发器对齐后端事件 已完成：IChatMessage 扩展了 plan_phases、error_detail、board_conclusion 等字段；useMessageRenderer.ts 已新增 team_plan、board_banner、board_conclusion、error 等路由；chat.ts 已调整 board_started / board_concluded 事件推送。
U3. TeamPlanCard 视觉升级 已完成：蓝色顶条、阶段时间线、进度条、状态图标就位。
U4. Board 复杂消息组件群 已完成：BoardBannerCard.vue、BoardRoundCard.vue、BoardConclusionCard.vue 已新建/升级；Scene4BoardDiscussion.vue 已加入 banner、多轮发言、小结、结论的完整示例。
U5. ErrorCard 重试与渲染集成 已完成：ErrorCard 支持重试事件，useMessageRenderer.ts 已路由 error 类型。
U6. ChatInput 交互补全 已完成：拖拽上传浮层、清空按钮、专家团/私董会语义色按钮就位。
U7. 右屏 Tab 面板内容补全 部分完成：Tab bar 与「监控」内容已就位，但「技能 / 系统 / 知识库」三个 Tab 的内容尚未根据 activeTab 切换渲染。

剩余工作：

U7 完成：实现 SkillsTab / SystemTab / KnowledgeTab 三个子组件，并在 SystemMonitorPanel.vue 中按 activeTab 切换。
U7 结对代码审查。
U8 Preview 样例场景精修。
U8 结对代码审查。
U9 BoardMeetingModal VI 适配收尾。
U9 结对代码审查。
U10 质量门与后端回归测试。

执行纪律： 每个开发单元完成后，启动一个子 agent 进行结对代码审查；审查通过后再进入下一单元。全部完成后统一跑 vue-tsc --noEmit / npm run build / pytest 并修复问题。

Problem Frame

聊天主区既要承载普通对话（user / assistant 文本），也要承载越来越复杂的 AI 运行态：专家团计划、私董会多轮讨论、工具调用链、错误恢复。现有实现已经把这些类型拆成独立组件，但：

视觉语言与需求文档仍有偏差（TeamPlanCard 缺少进度条、BoardRoundCard 缺少紫色边框与角色标签、ErrorCard 缺少重试）；
消息分发器没有为 error、board_started、board_conclusion、plan_update 等类型预留专属渲染路径；
右屏 SystemMonitorPanel 只有「监控」有内容，「技能 / 系统 / 知识库」尚未接入；
部分设计令牌（--radius-card、--font-mono）和交互细节（拖拽上传、清空输入、按钮语义色）尚未补齐。

Requirements Traceability

需求来源	本计划覆盖范围
§2 Color System	补齐 `--radius-card`、`--font-mono`，深色模式同步，移除硬编码旧色
§3.1 整体布局	ChatView max-width 已居中；右屏折叠由 `RightPanel` 负责，本计划补 Tab 内容
§3.2 消息类型表	为 `team_plan`、`board_banner`、`board_speech`、`board_summary`、`board_conclusion`、`error` 补齐/升级组件与分发
§3.3 关键交互	ChatInput 拖拽浮层、清空按钮、按钮语义色；ErrorCard 重试；ToolCallCard 默认收起已具备
§4 Right Panel	SystemMonitorPanel 增加「技能 / 系统 / 知识库」可切换内容
§5 Input Area	专家团/私董会按钮着色、拖拽上传、清空
§6.3 Mockup 6 场景	调整 Scene1/4/5，使预览更接近需求图

Key Technical Decisions

继续沿用 MessageShell + useMessageRenderer 分发架构。 复杂消息统一走 ChatMessage 分发，不在 ChatView 里写大量 v-if。
扩展 IChatMessage 模型承载复杂消息字段。 新增 plan_phases、error_detail、board_conclusion，让后端事件可以无损透传到组件层，而不是把所有状态塞进 content。
Board 顶部 Banner 用消息流中的 milestone 卡片表达。 board_started 事件进入聊天列表时渲染为 BoardBannerCard，关闭原来的纯文本 milestone fallback；board_concluded 渲染为 BoardConclusionCard。
右屏 Tab 内容复用现有 store 与组件，但做紧凑版。 避免把完整 SkillsView / KnowledgeBaseView 的页面级 padding 和 header 搬进侧边栏；新建 SkillsPanel / KnowledgePanel / SystemPanel 只保留核心列表/指标。
所有新增/修改组件必须先过 vue-tsc --noEmit。 由于前端没有单元测试，类型检查 + 构建即主要质量门。
每个单元完成后启动结对审查子 agent。 审查范围：类型安全、Vue 范式、设计令牌使用、边界条件处理；审查通过后再进入下一单元。

Implementation Units

U1. 补齐设计令牌与主题映射

Goal: 让需求文档 §2 中新增的 --radius-card、--font-mono 等令牌就位，并清理组件中残留的硬编码色值。

Requirements: §2.1 / §2.2 / §2.4 / §2.5

Dependencies: 无

Files:

src/agentkit/server/frontend/src/styles/tokens.css
src/agentkit/server/frontend/src/styles/theme.ts
src/agentkit/server/frontend/src/components/chat/BoardMeetingModal.vue
src/agentkit/server/frontend/src/components/layout/SystemMonitorPanel.vue

Approach:

在 :root 与 [data-theme="dark"] 中新增 --radius-card: 12px 和 --font-mono: 'SF Mono', 'Fira Code', ...。
theme.ts 的 Card / Modal 组件 token 优先读取 --radius-card。
将 BoardMeetingModal.vue 中硬编码的 rgba(142, 68, 173, ...) 与 rgba(99, 102, 241, ...) 替换为 --accent-board-soft / --accent-board-bg。
将 SystemMonitorPanel.vue 中硬编码的健康色 #22c55e、错误色 #ef4444 替换为语义令牌。

Test scenarios:

vue-tsc --noEmit 通过。
在浏览器开发者工具中检查 :root 包含 --radius-card 与 --font-mono。
深色模式下 --accent-board-soft 为带透明度的紫色。

Verification: 类型检查通过；浏览器 computed styles 可见新增令牌；BoardMeetingModal 选中态背景不再出现旧紫色。

Pair review: 由子 agent 检查 token 命名一致性、深色模式同步、是否仍有遗漏硬编码色值。

U2. 消息模型与分发器对齐后端事件

Goal: 让 useMessageRenderer 能正确识别 error、board_started、board_conclusion、plan_update 等消息类型，并给组件传递结构化数据。

Requirements: §3.2 / §6.1

Dependencies: U1

Files:

src/agentkit/server/frontend/src/api/types.ts
src/agentkit/server/frontend/src/components/chat/helpers/useMessageRenderer.ts
src/agentkit/server/frontend/src/components/chat/messages/index.ts
src/agentkit/server/frontend/src/components/chat/ChatMessage.vue
src/agentkit/server/frontend/src/stores/chat.ts
src/agentkit/server/frontend/src/components/chat/messages/BoardBannerCard.vue（已新建）
src/agentkit/server/frontend/src/components/chat/messages/BoardConclusionCard.vue（已新建）

Approach:

在 IChatMessage 中新增可选字段：plan_phases?: ITeamPlanPhase[]、error_detail?: string、board_conclusion?: IBoardConcludedData。
扩展 MessageViewType 为 'user' | 'assistant' | 'team_plan' | 'board_banner' | 'board_speech' | 'board_summary' | 'board_conclusion' | 'milestone' | 'error'。
resolveMessageType 按 message_type 返回 team_plan（plan_update）、board_banner（新增 board_started）、board_conclusion、error（新增 error）。
team_plan 分支从 message.plan_phases 取阶段，而不是从 tool_calls 映射（当前实现是错误映射）。
chat.ts 中 board_started 不再推送纯文本 milestone，而是推送 message_type: 'board_started' 的消息；board_concluded 推送 message_type: 'board_conclusion' 并带上 board_conclusion 数据。
error 分支对应后端 error 事件或本地把 status === 'error' 的消息路由到 ErrorCard。

Test scenarios:

Happy path: plan_update 消息渲染 TeamPlanCard 且阶段名称正确。
Happy path: board_started 渲染 BoardBannerCard，显示主题、专家 chips、轮次。
Happy path: board_conclusion 渲染 BoardConclusionCard，展示共识 / 分歧 / 建议。
Error path: 后端 error 事件渲染 ErrorCard 并带重试按钮。
Edge case: message.plan_phases 为空时 TeamPlanCard 不崩溃。

Verification: 在 Preview Scene3/4/6 中可见正确渲染；vue-tsc 无新增类型错误。

Pair review: 由子 agent 检查类型定义完整性、分发器分支覆盖、chat.ts 事件转换是否遗漏字段。

U3. TeamPlanCard 视觉升级

Goal: 让专家团计划 card 符合需求图：蓝色顶条、Lead 头像、阶段时间线、进度条、状态图标。

Requirements: §3.2 Team Plan Card 图示

Dependencies: U2

Files:

src/agentkit/server/frontend/src/components/chat/messages/TeamPlanCard.vue
src/agentkit/server/frontend/src/components/preview/scenes/Scene3TeamPlan.vue

Approach:

顶部增加 4px 高的 --accent-team 顶条，左侧显示 Lead 头像 + 「专家团计划」标签 + 完成计数。
阶段列表使用相对时间线：每个阶段左侧圆点/状态图标（● 执行中、○ 待执行、✓ 完成、✕ 失败），下方可展开专家子步骤（预留 result / milestone 字段）。
底部增加进度条：completed / total 百分比，用 --accent-team 填充。
颜色统一使用 --accent-team* 系列，不再使用默认 Ant Design 紫色。

Test scenarios:

Happy path: 3 个阶段中 1 个运行、2 个待执行，进度条显示 33%。
Edge case: 所有阶段失败，进度条为 0%，状态图标全为错误色。
Edge case: 阶段名超长时显示 text-overflow: ellipsis。

Verification: Preview Scene3 与需求图一致；无类型错误。

Pair review: 由子 agent 检查样式 token 使用、进度计算正确性、状态图标映射。

U4. Board 复杂消息组件群

Goal: 补齐私董会所需的 BoardBannerCard、BoardRoundCard 紫色边框样式、BoardConclusionCard。

Requirements: §3.2 Board Banner / Board Round Card / board_conclusion

Dependencies: U2

Files:

src/agentkit/server/frontend/src/components/chat/messages/BoardBannerCard.vue（已新建）
src/agentkit/server/frontend/src/components/chat/messages/BoardRoundCard.vue
src/agentkit/server/frontend/src/components/chat/messages/BoardConclusionCard.vue（已新建）
src/agentkit/server/frontend/src/components/chat/messages/index.ts
src/agentkit/server/frontend/src/components/preview/scenes/Scene4BoardDiscussion.vue

Approach:

BoardBannerCard：跨整行 card，顶部 4px --accent-board 条，显示 🏛️ 私董会主题、专家 emoji chips、主持人标签、当前轮次 / 最大轮次进度条。
BoardRoundCard：外层包裹增加左侧 3px --accent-board 边框、--accent-board-soft 背景；header 显示专家头像 chip、第 N 轮、角色标签（主持/专家）。
BoardConclusionCard：跨整行 card，紫色渐变顶条，内部展示「共识」「分歧」「决策建议」三个区块；默认折叠分歧与建议，点击展开。
导出到 messages/index.ts；更新 Preview Scene4 包含 banner + 3 轮发言 + 小结 + 结论。

Test scenarios:

Happy path: banner 显示主题、专家、主持人、轮次进度。
Happy path: 专家发言 card 左侧紫边，主持人 meta 带「主持」标签。
Happy path: 结论 card 默认展开共识，折叠分歧/建议，点击可展开。
Edge case: 结论数据为空时隐藏对应区块。

Verification: Preview Scene4 完整呈现 banner、发言、小结、结论；vue-tsc 通过。

Pair review: 由子 agent 检查紫色 token 一致性、BoardRoundCard 结构与需求图差异、折叠状态实现。

U5. ErrorCard 重试与渲染集成

Goal: 错误 card 支持重试操作，并能在消息流中正确触发。

Requirements: §3.2 error / §3.3 错误重试

Dependencies: U2

Files:

src/agentkit/server/frontend/src/components/chat/messages/ErrorCard.vue
src/agentkit/server/frontend/src/components/chat/helpers/useMessageRenderer.ts
src/agentkit/server/frontend/src/components/chat/ChatMessage.vue
src/agentkit/server/frontend/src/components/preview/scenes/Scene6Error.vue
src/agentkit/server/frontend/src/stores/chat.ts

Approach:

ErrorCard 增加 onRetry prop / emit('retry')，在 card 底部显示「重试」按钮。
ChatMessage 监听 retry 事件，调用 chatStore.resendLastUserMessage() 或类似 action；若不存在则新增该 action：取当前对话最后一条 user 消息重新发送。
useMessageRenderer 对 message_type === 'error' 或 status === 'error' 的消息渲染 ErrorCard。
Preview Scene6 的 ErrorCard 带重试按钮，点击后触发重发模拟。

Test scenarios:

Happy path: 点击 ErrorCard「重试」重新发送最后一条 user 消息。
Error path: 对话中没有 user 消息时重试按钮禁用或不显示。
Edge case: 连续多次重试不追加重复占位消息。

Verification: Scene6 可交互；类型检查通过。

Pair review: 由子 agent 检查重试逻辑幂等性、空消息边界、事件冒泡处理。

U6. ChatInput 交互补全

Goal: 完成输入区的语义色按钮、拖拽上传浮层、清空按钮。

Requirements: §5.2 / §5.3

Dependencies: U1

Files:

src/agentkit/server/frontend/src/components/chat/ChatInput.vue
src/agentkit/server/frontend/src/components/preview/scenes/Scene1Welcome.vue

Approach:

「专家团」按钮默认/悬停使用 --accent-team；「私董会」按钮默认/悬停使用 --accent-board；图标尺寸保持 14px。
在 textarea 区域监听 dragenter / dragover / dragleave / drop，放下文件时显示「拖放以附加」半透明浮层并调用现有 handleFileChange 逻辑。
在 footer 增加「清空」按钮，点击后 inputText = '' 并清空已选附件 pills。
Preview Scene1 的输入框预填文本改为 @team:tech_lead,frontend_engineer,backend_engineer 设计一个用户认证系统。

Test scenarios:

Happy path: 拖拽文件到输入区出现浮层，松开后文件被引用到输入框。
Happy path: 点击清空后输入框与附件 pills 清空。
Edge case: 非文件拖拽（如文本）不触发上传浮层。

Verification: 浏览器手动验证；vue-tsc 通过。

Pair review: 由子 agent 检查拖拽事件处理是否健壮、清空是否同时清理附件、按钮语义色是否正确。

U7. 右屏 Tab 面板内容补全

Goal: SystemMonitorPanel 的「技能 / 系统 / 知识库」三个 Tab 有真实内容。

Requirements: §4.1 / §4.3

Dependencies: 无

Files:

src/agentkit/server/frontend/src/components/layout/SystemMonitorPanel.vue
src/agentkit/server/frontend/src/stores/skills.ts
src/agentkit/server/frontend/src/stores/knowledge.ts
src/agentkit/server/frontend/src/components/skills/SkillCard.vue
src/agentkit/server/frontend/src/components/kb/SearchTest.vue
src/agentkit/server/frontend/src/api/system.ts（已新建）

Approach:

保持 Tab bar 与切换逻辑不变，把当前监控内容拆到 MonitorTab 子组件。
新增 SkillsTab：使用 useSkillsStore 拉取技能列表，以紧凑列表展示技能名 + 描述 + 状态，点击展开 SkillDetail；复用 SkillCard 但减少 padding。
新增 SystemTab：展示当前 resources（CPU / 内存 / 磁盘）与服务健康检查，避免重复监控 Tab 的 4 个 metric card。
新增 KnowledgeTab：使用 useKnowledgeStore 拉取 sources，展示知识库源列表，并在底部嵌入 SearchTest 做检索测试。
激活 Tab 的下划线颜色改为 --accent-team。

Test scenarios:

Happy path: 切换到「技能」Tab 可见技能列表，点击技能弹出详情。
Happy path: 切换到「系统」Tab 可见资源使用率与服务状态。
Happy path: 切换到「知识库」Tab 可见源列表与检索测试入口。
Error path: API 失败时显示友好错误提示。

Verification: 在 /agent/chat 打开右屏切换 4 个 Tab；vue-tsc / npm run build 通过。

Pair review: 由子 agent 检查 store 使用是否引入重复请求、Tab 切换状态、API 错误处理。

U8. Preview 样例场景精修

Goal: 让 6 个 Preview 场景与需求文档 §6.3 一一对应，便于视觉 review。

Requirements: §6.3

Dependencies: U2 / U3 / U4 / U5 / U6

Files:

src/agentkit/server/frontend/src/components/preview/ChatPreviewShell.vue
src/agentkit/server/frontend/src/components/preview/scenes/Scene1Welcome.vue
src/agentkit/server/frontend/src/components/preview/scenes/Scene3TeamPlan.vue
src/agentkit/server/frontend/src/components/preview/scenes/Scene4BoardDiscussion.vue
src/agentkit/server/frontend/src/components/preview/scenes/Scene5ToolCall.vue

Approach:

Scene1：顶部 hero + 4 能力提示 + 预填 @team:... 的输入框。
Scene3：使用升级后的 TeamPlanCard，第 1 阶段 running、专家子项展开。
Scene4：包含 BoardBannerCard、3 轮不同专家发言、1 个小结、1 个 BoardConclusionCard。
Scene5：展示嵌套 2 层 tool call，状态点变化（running → completed / error）。
ChatPreviewShell：场景切换按钮增加键盘左右箭头监听，方便演示。

Test scenarios:

Happy path: 6 个场景全部可切换且无 console error。
Happy path: Scene4 的 banner 与结论 card 完整渲染。
Edge case: 快速切换场景不残留上一个场景的滚动位置（滚动容器复位）。

Verification: /agent/preview 可完整演示 6 个场景；构建通过。

Pair review: 由子 agent 检查 mock 数据类型与真实接口是否一致、场景切换是否健壮。

U9. BoardMeetingModal VI 适配

Goal: 私董会 Modal 使用新的紫色语义令牌，移除旧 #8E44AD 与 indigo 硬编码。

Requirements: §6.1

Dependencies: U1

Files:

src/agentkit/server/frontend/src/components/chat/BoardMeetingModal.vue

Approach:

选中态背景改为 --accent-board-bg / --accent-board-soft。
选中边框使用 --accent-board。
主持人标签颜色从 Ant Design purple 改为自定义 Tag，背景 --accent-board-soft、文字 --accent-board。
hover 边框改为 --color-primary（近黑）。

Test scenarios:

Happy path: 选中专家后卡片边框为紫色，主持人卡片背景为浅紫色。
Edge case: 深色模式下紫色令牌仍可见。

Verification: 在 ChatInput 打开「私董会」Modal 验证；vue-tsc 通过。

Pair review: 由子 agent 检查是否仍有遗漏硬编码色值、深色模式表现。

U10. 质量门与后端回归

Goal: 确保前端类型安全、构建成功，后端单元测试不回归。

Requirements: §8.1 完成定义

Dependencies: U1-U9

Files:

src/agentkit/server/frontend/package.json
src/agentkit/server/routes/chat.py（仅验证上传接口未破坏）
src/agentkit/server/routes/experts.py（仅验证专家列表未破坏）

Approach:

在前端目录运行 npx vue-tsc --noEmit。
运行 npm run build。
在仓库根目录运行 ruff check src/ 与 ruff format src/。
运行 python3 -m pytest tests/unit/ -x -q；若 test_rewoo_agent_yaml_loads 失败则按已知问题跳过。
修复所有阻塞性错误后重新跑门。

Test scenarios:

vue-tsc --noEmit 通过。
npm run build 生成 src/agentkit/server/static/ 且无报错。
pytest tests/unit/ -x -q 通过（允许跳过已知失败）。
ruff check src/ 通过。

Verification: 三个命令均返回 0（或 pytest 仅因已知用例跳过）。

Pair review: 由子 agent 检查类型错误修复是否引入新的运行时问题、构建产物是否正常。

Scope Boundaries

In Scope

聊天主区 VI 令牌补齐与深色模式同步。
ChatMessage 分发器与 IChatMessage 模型扩展。
TeamPlanCard、BoardBannerCard、BoardRoundCard、BoardConclusionCard、ErrorCard 的升级/新建。
ChatInput 的拖拽上传、清空、语义色按钮。
SystemMonitorPanel 的「技能 / 系统 / 知识库」Tab 内容。
ChatPreviewView 6 个样例场景精修。
BoardMeetingModal VI 适配。
质量门（vue-tsc / build / ruff / pytest）。
每个开发单元后的结对代码审查。

Out of Scope

侧边栏 ChatSidebar、顶部 TopNav、抽屉布局改造。
移动端响应式优化。
实际 WebSocket 数据流改造（仅前端渲染层适配）。
可访问性（a11y）专项审计。
虚拟滚动、消息懒加载等性能优化。
消息编辑 / 分支对话（Trae 范式）。

Deferred to Follow-Up Work

UserBubble / AssistantText 的 hover 操作条（编辑/复制/重新生成/反馈）—— 需求 §3.3 提到，但本期以复杂事件 card 和右屏为主，可在后续 PR 补齐。
流式光标竖线动画 —— 当前使用 a-spin 占位，后续可替换为闪烁竖线。

Risks & Dependencies

风险	等级	缓解措施
扩展 `IChatMessage` 会影响现有对话持久化格式	中	新增字段均为 optional；后端返回 JSON 不校验未知字段时无影响。
`SystemMonitorPanel` 嵌入完整 Skills/KB 组件可能触发重复请求	中	使用 store 缓存，Tab 切换不重新 fetch；`onMounted` 仍负责首次加载。
Preview Scene 精修引入新的假数据类型与真实后端不一致	低	Preview 明确为静态 mockup，不依赖真实 WebSocket。
后端 `pytest` 已有已知失败 `test_rewoo_agent_yaml_loads`	低	按项目规则跳过该用例。
多单元改动叠加导致类型错误难以定位	中	每单元独立跑 `vue-tsc --noEmit`，不累积错误。

Open Questions

以下问题来自需求文档 §9，实施前按默认值处理，后续可再调整：

Q1 @team 蓝 vs @board 紫：保持当前分配（蓝=协作，紫=深度）。
Q2 流式光标：保持当前 spin 占位，竖线动画 deferred。
Q3 私董会按钮文字：保持「私董会」。
Q4 专家团按钮文字：保持「专家团」。
Q5 消息引用：本期不做。

Success Criteria

tokens.css + theme.ts 新增令牌就位。
BoardBannerCard / BoardRoundCard / BoardConclusionCard 结构与样式就位。
/agent/preview 6 个场景全部可见且可交互。
无硬编码旧色残留（U1、U9 收尾）。
vue-tsc --noEmit 与 npm run build 通过。
ruff check src/ 通过。
pytest tests/unit/ -x -q 通过（允许跳过已知失败）。
右屏 4 个 Tab 都有内容。
ErrorCard 支持重试。
每个开发单元都经过子 agent 结对审查并确认无阻塞问题。

Sources & Research

Origin: docs/brainstorms/2026-06-18-chat-area-vi-redesign-requirements.md
Local patterns: src/agentkit/server/frontend/src/components/chat/messages/, src/agentkit/server/frontend/src/components/layout/RightPanel.vue

24 KiB Raw Blame History Unescape Escape

feat: 聊天主区 VI 重梳与新功能适配 — 实施计划（执行中 / 复审版）

Summary

Problem Frame

Requirements Traceability

Key Technical Decisions

Implementation Units

U1. 补齐设计令牌与主题映射

U2. 消息模型与分发器对齐后端事件

U3. TeamPlanCard 视觉升级

U4. Board 复杂消息组件群

U5. ErrorCard 重试与渲染集成

U6. ChatInput 交互补全

U7. 右屏 Tab 面板内容补全

U8. Preview 样例场景精修

U9. BoardMeetingModal VI 适配

U10. 质量门与后端回归

Scope Boundaries

In Scope

Out of Scope

Deferred to Follow-Up Work

Risks & Dependencies

Open Questions

Success Criteria

Sources & Research

24 KiB

Raw Blame History