fischer-agentkit/docs/plans/2026-06-19-001-feat-chat-ar...

24 KiB
Raw Permalink 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.csstheme.ts 新增 --radius-card--font-mono--accent-team*--accent-board*--shadow-card 等;关键组件已使用语义 token。
  • U2. 消息模型与分发器对齐后端事件 已完成:IChatMessage 扩展了 plan_phaseserror_detailboard_conclusion 等字段;useMessageRenderer.ts 已新增 team_planboard_bannerboard_conclusionerror 等路由;chat.ts 已调整 board_started / board_concluded 事件推送。
  • U3. TeamPlanCard 视觉升级 已完成:蓝色顶条、阶段时间线、进度条、状态图标就位。
  • U4. Board 复杂消息组件群 已完成:BoardBannerCard.vueBoardRoundCard.vueBoardConclusionCard.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 运行态:专家团计划、私董会多轮讨论、工具调用链、错误恢复。现有实现已经把这些类型拆成独立组件,但:

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

Requirements Traceability

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

Key Technical Decisions

  1. 继续沿用 MessageShell + useMessageRenderer 分发架构。 复杂消息统一走 ChatMessage 分发,不在 ChatView 里写大量 v-if
  2. 扩展 IChatMessage 模型承载复杂消息字段。 新增 plan_phaseserror_detailboard_conclusion,让后端事件可以无损透传到组件层,而不是把所有状态塞进 content
  3. Board 顶部 Banner 用消息流中的 milestone 卡片表达。 board_started 事件进入聊天列表时渲染为 BoardBannerCard,关闭原来的纯文本 milestone fallbackboard_concluded 渲染为 BoardConclusionCard
  4. 右屏 Tab 内容复用现有 store 与组件,但做紧凑版。 避免把完整 SkillsView / KnowledgeBaseView 的页面级 padding 和 header 搬进侧边栏;新建 SkillsPanel / KnowledgePanel / SystemPanel 只保留核心列表/指标。
  5. 所有新增/修改组件必须先过 vue-tsc --noEmit 由于前端没有单元测试,类型检查 + 构建即主要质量门。
  6. 每个单元完成后启动结对审查子 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.tsCard / 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 能正确识别 errorboard_startedboard_conclusionplan_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?: stringboard_conclusion?: IBoardConcludedData
  • 扩展 MessageViewType'user' | 'assistant' | 'team_plan' | 'board_banner' | 'board_speech' | 'board_summary' | 'board_conclusion' | 'milestone' | 'error'
  • resolveMessageTypemessage_type 返回 team_planplan_update)、board_banner(新增 board_started)、board_conclusionerror(新增 error)。
  • team_plan 分支从 message.plan_phases 取阶段,而不是从 tool_calls 映射(当前实现是错误映射)。
  • chat.tsboard_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: 补齐私董会所需的 BoardBannerCardBoardRoundCard 紫色边框样式、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 消息重新发送。
  • useMessageRenderermessage_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:展示当前 resourcesCPU / 内存 / 磁盘)与服务健康检查,避免重复监控 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 个 Tabvue-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 模型扩展。
  • TeamPlanCardBoardBannerCardBoardRoundCardBoardConclusionCardErrorCard 的升级/新建。
  • 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 切换不重新 fetchonMounted 仍负责首次加载。
Preview Scene 精修引入新的假数据类型与真实后端不一致 Preview 明确为静态 mockup不依赖真实 WebSocket。
后端 pytest 已有已知失败 test_rewoo_agent_yaml_loads 按项目规则跳过该用例。
多单元改动叠加导致类型错误难以定位 每单元独立跑 vue-tsc --noEmit,不累积错误。

Open Questions

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

  1. Q1 @team 蓝 vs @board 紫:保持当前分配(蓝=协作,紫=深度)。
  2. Q2 流式光标:保持当前 spin 占位,竖线动画 deferred。
  3. Q3 私董会按钮文字:保持「私董会」。
  4. Q4 专家团按钮文字:保持「专家团」。
  5. Q5 消息引用:本期不做。

Success Criteria

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

Sources & Research