30 KiB

Raw Blame History

date	type	origin
2026-07-01	feat	docs/brainstorms/2026-07-01-ui-ue-enhancement-requirements.md

feat: AgentKit UI/UE 增强 — 聊天流式 + Sticky 头部 + 日历重设计

Summary

强化 AgentKit 聊天与日历模块的 UI/UE：让 agent 思考过程与团队/私董会结果真正流式可见，让 @team/@board 模式在对话顶部持久显式，去除常驻路由噪声，给用户消息补齐复制/删除/回填操作，并让日历回到 Notion 风格的统一设计语言。覆盖 22 个需求（R1-R22），含后端 _phase_executor.py 流式切换以打通 expert_result/team_synthesis 的流式链路。

Problem Frame

当前聊天主界面的思考展示默认折叠且为纯文本，看不到 agent 推理过程；@team/@board 模式的顶部 banner 为静态文案且不可点击，无法回答"这次任务目标是什么、由哪些专家参与"；专家团与私董会的最终结果以完整事件块一次性到达前端，与 final_answer 的流式体验割裂；路由元信息 tag 常驻显示对终端用户是无意义噪声；用户消息气泡无任何悬停操作；日历模块硬编码颜色与 tokens.css 的 Notion 调色板完全脱节。

来源：docs/brainstorms/2026-07-01-ui-ue-enhancement-requirements.md（经 ce-doc-review 审查强化，含 9 个 Open Questions）。

Requirements

需求追溯

需求组	R-IDs	实施单元
思考展示	R1-R3	U1
@team/@board 头部	R4-R7	U2
团队/私董会流式	R8-R11	U3, U4
路由标签	R12-R13	U5
用户消息悬停	R14-R17	U6
日历重设计	R18-R22	U7

完整需求清单见 origin 文档。关键决策（思考混合方案、sticky 持久条、FC+自定义外壳、流式方案待定）已由 brainstorm 确认。

成功标准

思考进行中时 ThinkingBlock 展开并显示流式光标，完成后收起为摘要条
@team/@board 模式进入对话后顶部渲染 sticky 持久条，专家头像可点击查看详情
expert_result 与 team_synthesis 事件按 token/文本块流式累加渲染，与 final_answer 体验对齐
路由元信息 tag 默认隐藏，悬停时淡入显示
用户消息气泡悬停时显示复制/删除/回填操作工具条
日历模块统一消费 tokens.css，无硬编码颜色值

Key Technical Decisions

ThinkingBlock 流式光标采用 CSS 伪元素 + watch content.length 截断展示。后端已将 thinking chunks 累积到 message.thinking（chatStream.ts:512-521），前端无需改事件流，只需在 ThinkingBlock.vue 内 watch content.length 做截断展示 + 闪烁光标。完成后收起为摘要条显示 token 数。
StickyModeHeader 为新组件，替换 ExpertTeamView + BoardStatusView。从 useTeamStore() 和 useChatStore().boardState 读取状态，合并为单一 sticky 条（position: sticky; top: 0; z-index: var(--z-sticky)）。PhaseIndicator 独立保留在 sticky 头部下方，不合并。
expert_result/team_synthesis 流式采用 execute_stream() + token 转发 + 前端累积式 updateMessage。后端 _phase_executor.py 从 agent.execute() 切换为 agent.execute_stream()，在 async for event in 循环中转发 token/final_answer 事件到 WS。前端 chatStream.ts 的 expert_result/team_synthesis 分支从一次性 appendMessage 改为累积式 updateMessage（复用 final_answer 的 526-532 模式）。
路由 tag 隐藏采用 v-show + opacity transition（与 U5 Approach 对齐）。AssistantText.vue 的 showRouting computed 增加 hover 状态依赖，CSS opacity: 0 → 1 + transition: opacity 0.2s ease 淡入淡出。v-show 保留 DOM 避免首次悬停的重挂载闪烁。
UserBubble 回填采用 chatStore 共享状态。新增 chatStore.refillText: string ref，UserBubble 的回填操作设置该值，ChatInput watch 该值回填到 inputText。删除操作新增 chatStore.deleteMessage(convId, msgId) 从 currentMessages 移除（仅前端隐藏，不删服务端副本）。
日历 .fc- 覆盖采用最小范围 CSS 覆盖*。仅覆盖字体、边框、表头背景、今日高亮四类样式，选择器限定为 .fc-toolbar / .fc-col-header / .fc-day-today 等稳定类名，接受 FC 升级时可能需要维护的成本。

High-Level Technical Design

流式事件链路（R8-R11）

Backend: _phase_executor.py
  agent.execute_stream()  ← async generator yields ReActEvent
    ├─ event_type="token"     → broadcast "expert_result_chunk" { expert_id, content }
    ├─ event_type="thinking"  → broadcast "expert_step" { expert_id, thinking }
    ├─ event_type="final_answer" → broadcast "expert_result_chunk" { expert_id, content }
    └─ 循环结束 → broadcast "expert_result" { expert_id, content: full, status: "completed" }

Frontend: chatStream.ts
  case "expert_result_chunk":
    → updateMessage(convId, lastExpertMsg.id, { content: accumulated + chunk })
  case "expert_result":
    → updateMessage(convId, lastExpertMsg.id, { status: "completed" })  ← 仅标记完成，不再 append

组件依赖关系

U1 ThinkingBlock (独立)
U2 StickyModeHeader (独立，替换两个旧组件)
U3 后端流式切换 (独立，无前端依赖)
U4 前端流式消费 (依赖 U3 联调，可 mock 开发)
U5 路由 tag 隐藏 (独立)
U6 UserBubble hover (独立，需 chatStore 新方法)
U7 CalendarGrid 重设计 (独立)

Implementation Units

U1. ThinkingBlock 流式展示重设计

Goal: 让 agent 思考过程在执行时展开流式显示，完成后收起为摘要条，切换不丢失内容。

Requirements: R1, R2, R3

Dependencies: 无

Files:

src/agentkit/server/frontend/src/components/chat/ThinkingBlock.vue（修改）
src/agentkit/server/frontend/tests/unit/components/ThinkingBlock.test.ts（新建）

Approach:

默认展开（expanded = ref(true)），isStreaming 时显示流式光标（CSS ::after 伪元素闪烁动画）
watch content.length 截断展示：流式中仅显示已到达的字符，模拟 token-by-token 效果
完成后（isStreaming 由 true→false）自动收起为摘要条，显示思考开始时间与字符数
摘要条点击切换展开/收起，展开时定位到上一次滚动位置（记录 scrollTop 到 ref）
状态保持：收起时内容不丢失，content prop 始终持有完整文本

Patterns to follow:

ChatView.vue:47-76 的 streamingSteps 渲染模式（字符数 counter）
final_answer 在 chatStream.ts:526-532 的累积模式

Test scenarios:

流式中展开态显示光标 + 已到达字符，完成后自动收起为摘要条
摘要条点击展开，显示完整思考内容
展开→收起→再展开，滚动位置恢复到上次位置
空思考内容（content=""）时不显示 ThinkingBlock
isStreaming=true 但 content="" 时显示加载占位

Verification: 思考流式中可见光标闪烁与字符累加，完成后收起为一行摘要，点击可重新展开查看完整内容。

U2. StickyModeHeader + PhaseIndicator token 化

Goal: 替换静态 banner 为 sticky 持久头部条，显示模式 badge + 任务目标 + 专家头像组；PhaseIndicator 独立保留并 token 化。

Requirements: R4, R5, R6, R7

Dependencies: 无

Files:

src/agentkit/server/frontend/src/components/chat/StickyModeHeader.vue（新建）
src/agentkit/server/frontend/src/components/chat/ExpertTeamView.vue（废弃/删除引用）
src/agentkit/server/frontend/src/components/chat/BoardStatusView.vue（废弃/删除引用）
src/agentkit/server/frontend/src/components/chat/PhaseIndicator.vue（修改 — token 化）
src/agentkit/server/frontend/src/views/ChatView.vue（修改 — 替换 banner 引用）
src/agentkit/server/frontend/tests/unit/components/StickyModeHeader.test.ts（新建）

Approach:

StickyModeHeader 从 useTeamStore() 读取 isTeamMode / teamState（含 task_description / experts），从 useChatStore().boardState 读取私董会状态。注：实际 store 暴露 teamState / activeExperts / leadExpert，无 currentPlan / experts 顶层 ref（FYI F8 提示）— 实施时通过 teamState.value?.task_description 与 activeExperts / teamState.value?.experts 访问
左侧：模式 badge（"专家团" / "私董会"），使用 --accent-team / --accent-board
中间：任务目标（@team 取 teamState.value?.task_description）或主题（@board 取 boardState.topic）
右侧：专家头像组（v-for 渲染 activeExperts，每个显示 avatar emoji + color 边框），溢出时显示 +N
头像点击弹出 a-popover 详情面板，显示 name / description / persona（现有字段，不假设 role/bio）。Popover 关闭：Esc 键 + 外击关闭；关闭时焦点回归触发头像（focus management）。移动端：viewport<768px 隐藏任务主题文本，仅显示 mode badge + avatar group；+N 溢出点击打开完整专家列表 popover
PhaseIndicator 硬编码颜色（#722ed1 / #52c41a / #cf1322）替换为 token（--accent-board / --color-success / --color-error）
ChatView.vue 中 <ExpertTeamView /> + <BoardStatusView /> 替换为 <StickyModeHeader />，<PhaseIndicator /> 保留在其下方

Patterns to follow:

MessageShell.vue:5-11 的 custom-avatar 渲染逻辑
tokens.css 的 --z-sticky: 1020 / --accent-team / --accent-board

Test scenarios:

@team 模式进入对话后渲染 sticky 条，显示"专家团" badge + 任务目标 + 专家头像
@board 模式进入对话后渲染 sticky 条，显示"私董会" badge + 主题 + 专家头像
非 team/board 模式不渲染 sticky 条
专家头像点击弹出 popover 显示 name/description/persona
Popover 通过 Esc 键关闭，关闭后焦点回归触发头像
Popover 通过外击关闭
头像超过 5 个时显示 +N 溢出标识，+N 点击打开完整专家列表 popover
viewport<768px 时隐藏任务主题文本，仅显示 mode badge + avatar group
PhaseIndicator 颜色使用 token 变量而非硬编码

Verification: @team/@board 模式下顶部持久显示 sticky 头部条，专家头像可点击查看详情，PhaseIndicator 颜色与 tokens.css 一致。

U3. 后端 _phase_executor.py 流式切换

Goal: 将专家阶段执行从同步 agent.execute() 切换为流式 agent.execute_stream()，转发 token/thinking/final_answer 事件到 WS。

Requirements: R8, R9（后端依赖）

Dependencies: ConfigDrivenAgent.execute_stream() 暴露 — 需先在 BaseAgent/ConfigDrivenAgent 暴露 stream dispatch（react/rewoo/plan_exec/reflexion 模式委派至底层引擎；direct/llm_generate/tool_call/custom 模式定义显式 fallback）

Files:

src/agentkit/core/config_driven.py（修改 — 暴露 execute_stream() + handle_task_stream() dispatch，镜像 execute() → handle_task() 模式）
src/agentkit/core/base.py（修改 — 在 BaseAgent 加 execute_stream() 抽象方法签名）
src/agentkit/experts/_phase_executor.py（修改 — _run_agent_steps 方法）
src/agentkit/experts/_synthesizer.py（修改 — _synthesize_results 注入 broadcast_callback 参数，保留 dict 返回类型，方法内每次 LLM chunk 调用 callback 广播 team_synthesis_chunk）
src/agentkit/experts/orchestrator.py（修改 — _synthesize_results 调用处传入 _broadcast_event 的部分应用作为 callback；final_result = await self._synthesize_results(...) 与 final_result.get("content") 消费保持不变）
tests/unit/experts/test_phase_executor_streaming.py（新建）

Approach:

_run_agent_steps（line 222）从 await agent.execute(task_msg) 改为 async for event in agent.execute_stream(task_msg, ...) 循环
循环内按 event.event_type 转发（载荷在 event.data: dict[str, object]，无 event.content / event.output 属性 — 见 react.py:131-137 ReActEvent 定义）：
- "token" → _broadcast_event("expert_result_chunk", { expert_id, content: event.data.get("content") })
- "thinking" → _broadcast_event("expert_step", { expert_id, thinking: event.data.get("content") })
- "final_answer" → _broadcast_event("expert_result_chunk", { expert_id, content: event.data.get("output") })
- "tool_call" / "tool_result" → 可选转发（保持现有 expert_step 语义）
循环结束后广播 expert_result 完整事件（content = 累积的完整结果，status: "completed"）
TeamOrchestrator._synthesize_results 接口策略：注入 broadcast_callback 参数，保留 dict[str, object] 返回类型（对 orchestrator.py:289 消费者零破坏）。方法内在每次 LLM 输出 chunk 时调用 broadcast_callback({"chunk": text}) 广播 team_synthesis_chunk，最终返回完整 dict；orchestrator.py:294-301 的最终 team_synthesis 广播路径不变
重试 + 流式合约：_run_agent_steps 的 retry 循环（_phase_executor.py:220-241）与流式交互须遵循：(a) 重试前广播 expert_result_chunk_reset 事件，前端清空已累积内容；(b) 最终 expert_result 事件携带完整内容覆盖（前端在 expert_result 到达时替换而非累加）；(c) 重试不广播新 chunks 直到本次流式完成 — 避免失败 attempt 1 的部分 chunks 与 attempt 2 的 chunks 在前端累积成乱码
异步生成器安全：遵循 AGENTS.md 约定，async def 中第一个 yield 前禁止 return（用 return; yield 模式）
异常分类：遵循 docs/solutions/conventions/any-and-except-exception-governance.md，WS 广播用 except (ConnectionError, RuntimeError, asyncio.TimeoutError)

Patterns to follow:

react.py:1443 的 execute_stream 签名与 ReActEvent 结构
chatStream.ts:526-532 的 final_answer 累积模式（后端镜像）
docs/solutions/logic-errors/long-horizon-reliability-code-review-fixes.md 的 execute_stream 入口 self.reset() 前置条件

Test scenarios:

execute_stream 产出 token 事件时，_broadcast_event 被调用转发 expert_result_chunk
execute_stream 产出 final_answer 事件时，_broadcast_event 被调用转发 expert_result_chunk
循环结束后广播完整 expert_result 事件
execute_stream 抛出异常时，phase 状态标记为 failed 且不阻塞其他阶段
execute_stream 中途抛出异常时，广播 expert_result 事件 status="error" 携带已累积内容，前端可识别错误态并保留部分内容
流式会话必须以 expert_result(completed) 或 expert_result(error) 终结，不允许静默挂起
execute_stream 在 2 chunks 后抛异常 → retry loop 触发 → 广播 expert_result_chunk_reset → 重试成功 → 前端消息仅含 attempt 2 内容（无 attempt 1 残留）
TeamOrchestrator 综合阶段流式广播 team_synthesis_chunk

Verification: 后端日志可见 expert_result_chunk 事件按 token 推送，最终 expert_result 完整事件作为结束标记。

U4. 前端 expert_result/team_synthesis 流式消费 + 身份标识

Goal: 前端将 expert_result/team_synthesis 从一次性 append 改为累积式 update，流式过程中显示专家身份标识。

Requirements: R8, R9, R10, R11

Dependencies: U3（联调，可 mock 开发）

Files:

src/agentkit/server/frontend/src/stores/chatStream.ts（修改 — expert_result/team_synthesis 分支）
src/agentkit/server/frontend/src/components/chat/messages/MessageShell.vue（修改 — 渲染 expert_name/expert_color badge）
src/agentkit/server/frontend/tests/unit/stores/chatStream.test.ts（修改 — 新增流式测试）

Approach:

新增 expert_result_chunk 事件分支：若当前无该专家的流式消息则 appendMessage 创建占位（status: "streaming"），否则 updateMessage 累加 content（复用 final_answer 526-532 模式）
expert_result 事件分支改为：仅 updateMessage 标记 status: "completed"（不再 appendMessage）；status="error" 时标记为错误态并保留部分内容
expert_result_chunk_reset 事件分支（U3 重试合约）：清空已累积 content，重置 streaming 状态
team_synthesis_chunk 同理：首次 append 占位，后续 update 累加
team_synthesis 事件改为：仅 update 标记完成
并发专家流式顺序：每个 expert_id 维护独立 streaming message slot（keyed by expert_id），同 expert 的 chunks 累积到该 expert 的消息；并发专家渲染为独立并行 streaming 消息，按 first-chunk 到达时间排序
流式消息渲染时显示身份标识（expert_name + expert_color badge），流式结束后标识保留
R10 身份标识为用户可见的专家 badge（区别于 R12 的内部路由 tag），通过 message.expert_name / message.expert_color 在 MessageShell 中渲染

Patterns to follow:

chatStream.ts:526-532 的 final_answer 累积模式
dispatchWsEvent 纯函数设计（入参 ChatStreamState，无模块级状态）

Test scenarios:

expert_result_chunk 首次到达时创建 streaming 占位消息
expert_result_chunk 后续到达时累加 content 到已有消息
expert_result 到达时标记消息 status 为 completed
expert_result 到达时 status="error" 时，标记 streaming 消息为错误态并保留部分内容
expert_result_chunk_reset 到达时清空已累积 content 并重置 streaming 状态
team_synthesis_chunk 首次到达时创建 streaming 占位
team_synthesis 到达时标记完成
流式消息显示 expert_name + expert_color badge
流式会话异常终止时，UI 显示错误指示器不静默挂起
两个专家并发流式 → 两条独立 streaming 消息，各自累积自己的 chunks，按 first-chunk 到达时间排序

Verification: 专家结果按 token 流式累加显示，完成后标记为 completed，身份标识保留在最终消息上。

U5. AssistantText 路由标签悬停显示

Goal: 路由元信息 tag 默认隐藏，悬停助手消息时淡入显示。

Requirements: R12, R13

Dependencies: 无

Files:

src/agentkit/server/frontend/src/components/chat/messages/AssistantText.vue（修改）
src/agentkit/server/frontend/tests/unit/components/AssistantText.test.ts（新建）

Approach:

showRouting computed 增加 hover 状态依赖：return props.message.role === 'assistant' && props.message.matched_skill && isHovered.value
根容器加 @mouseenter / @mouseleave 事件设置 isHovered = ref(false)
CSS .assistant-text__routing 加 transition: opacity 0.2s ease，默认 opacity: 0，hover 时 opacity: 1
采用 v-show + opacity transition（保留 DOM 避免首次悬停的重挂载闪烁，opacity:0→1 + transition:opacity 0.2s ease 满足 R13 淡入要求）

Patterns to follow:

Ant Design Vue 的 <a-tag> 组件用法
tokens.css 的 --transition-base 变量（若存在）

Test scenarios:

默认状态路由 tag 不可见
鼠标悬停助手消息时 tag 淡入显示
鼠标移开时 tag 淡出
无 matched_skill 的消息悬停时也不显示 tag
淡入淡出过渡平滑无闪烁

Verification: 路由 tag 默认不可见，悬停时淡入，移开时淡出。

U6. UserBubble 悬停操作（复制/删除/回填）

Goal: 用户消息气泡悬停时显示操作工具条，支持复制、删除（前端隐藏）、回填输入框重发。

Requirements: R14, R15, R16, R17

Dependencies: 无（chatStore 新方法独立于其他单元）

Files:

src/agentkit/server/frontend/src/components/chat/messages/UserBubble.vue（修改）
src/agentkit/server/frontend/src/stores/chatStore.ts（修改 — 新增 deleteMessage / refillText）
src/agentkit/server/frontend/src/components/chat/ChatInput.vue（修改 — watch refillText）
src/agentkit/server/frontend/tests/unit/components/UserBubble.test.ts（新建）

Approach:

UserBubble.vue 根容器加 @mouseenter / @mouseleave 控制 showActions = ref(false)
focus-visible parity：根容器加 @focus / @blur（或 :focus-within）使 Tab 聚焦时也显示工具条（键盘用户可达）；Touch 设备 tap on bubble 切换显示，tap elsewhere 隐藏
悬停时显示工具条（v-if="showActions"）：复制按钮（CopyOutlined）、删除按钮（DeleteOutlined）、回填按钮（EditOutlined）
复制：navigator.clipboard.writeText(content)，成功后按钮短暂变色反馈
删除：弹出 a-popconfirm 二次确认，确认后调 chatStore.deleteMessage(convId, msgId) 从 currentMessages 移除（仅前端隐藏，不删服务端副本）；若有助手回复跟随（thread order 中下一条为 assistant 消息），删除按钮 disabled 并显示 tooltip "该消息已有回复，无法删除"
回填：调 chatStore.setRefillText(content)，ChatInput watch refillText 回填到 inputText，不自动发送
chatStore 新增：refillText = ref('')、deleteMessage(convId, msgId)、setRefillText(text)

Patterns to follow:

chatStore.resendLastUserMessage()（chatStore.ts:449-462）的消息定位模式
chatStore.deleteConversation 的 pending 状态清理模式（见 calendar-capability-and-ui-fixes.md 学习）

Test scenarios:

悬停时显示三个操作按钮
Tab 聚焦用户消息时显示工具条；Enter 触发默认动作（复制）
Touch 设备 tap on bubble 显示工具条，tap elsewhere 隐藏
复制按钮点击后内容写入剪贴板，按钮变色反馈
删除按钮点击后弹出二次确认，确认后消息从列表消失
删除取消后消息不消失
删除有助手回复跟随的用户消息 → 删除按钮 disabled + tooltip "该消息已有回复，无法删除"
回填按钮点击后 ChatInput 输入框显示消息文本，不自动发送
离开悬停后操作工具条消失

Verification: 悬停用户消息可见三个操作，复制/删除/回填功能正常，删除有二次确认。

U7. CalendarGrid token 重设计

Goal: 日历模块统一消费 tokens.css，消除硬编码颜色，.fc-* 元素对齐 Notion 风格。

Requirements: R18, R19, R20, R21, R22

Dependencies: 无（tokens.css 已含全部变量；本期不修改 tokens.css）

Files:

src/agentkit/server/frontend/src/components/calendar/CalendarGrid.vue（修改）
src/agentkit/server/frontend/src/styles/calendar-overrides.css（新建 — .fc-* 覆盖）
src/agentkit/server/frontend/tests/unit/components/CalendarGrid.test.ts（新建）

Approach:

CalendarGrid.vue:38 的 #1677ff 替换为按 event_type 映射到 token（显式映射表）：
- event_type=team → var(--accent-team)
- event_type=board → var(--accent-board)
- event_type=task → var(--color-primary)
- event_type=reminder → var(--color-warning)
- event_type=system → var(--text-tertiary)
- 默认 → var(--color-primary)
- 实施前需从 CalendarGrid.vue 的事件源枚举实际 event_type 值
事件卡片 backgroundColor / borderColor 改为从 token 映射函数返回
新建 calendar-overrides.css 覆盖 .fc-toolbar（按钮风格）、.fc-col-header（表头背景）、.fc-day-today（今日高亮）、.fc-event（事件卡片字体/边框）
覆盖范围最小化：仅覆盖 4 类稳定类名，接受 FC 升级时可能需要维护的成本
侧栏与头部工具栏组件使用 token 重绘

Patterns to follow:

tokens.css 的 Notion 调色板（--color-primary: #1a1a1a、--accent-team、--accent-board）
CalendarGrid.vue 现有的 firstDay: 1 配置（见 jwt-secret-dev-mode-user-id-mismatch.md 学习）

Test scenarios:

日历事件颜色按 event_type 映射到 token，无硬编码颜色值
.fc-toolbar 按钮风格与主界面按钮一致
.fc-day-today 今日高亮使用 token 色
暗色模式（[data-theme="dark"]）下日历正确显示
FullCalendar 视图切换/日期导航/事件拖拽功能不受影响
Calendar 零事件 → 空态 placeholder 文本使用 --text-tertiary token
事件获取失败 → 错误态带 retry CTA（使用 --color-error token）
事件加载中 → skeleton loader 匹配 token 间距（使用 --color-border / --color-fill-quaternary）

Verification: 日历视觉与主界面 Notion 风格一致，无硬编码颜色，FC 既有功能正常。

Scope Boundaries

Deferred for later

思考内容的 markdown 渲染：本期 ThinkingBlock 仍以纯文本呈现（origin 文档 Deferred）
日历事件的拖拽创建、resize 行为变更：仅重绘视觉外壳（origin 文档 Deferred）
专家头像组在线状态指示：仅展示静态头像（origin 文档 Deferred）
路由元信息 tag 的可配置显示规则：固定为"默认隐藏 + 悬停显示"（origin 文档 Deferred）
后端流式推送协议的具体方案（事件变体 vs token 分块）：U3 采用 execute_stream() + token 转发，具体事件命名（expert_result_chunk 等）可在实施时调整

Outside this product's identity

不引入新的 UI 组件库或设计系统（继续基于 Ant Design Vue + token 覆盖）
不替换 FullCalendar 为自建日历组件（保留 FC 核心，仅覆盖外壳与 .fc-* 样式）
不改变 PhaseIndicator 的现有阶段进度语义与展示形式（仅独立保留 + token 化）

Deferred to Follow-Up Work

R16 服务端删除语义：本期仅前端隐藏，服务端删除留待后续迭代（origin OQ4）
交互状态全覆盖（错误态/空态/加载态规范）：origin OQ1，本期在相关单元测试中覆盖核心场景，全面规范留待后续
响应式与无障碍全面策略：origin OQ2，本期在组件中遵循基本 a11y，全面策略留待后续
@team/@board 模式可发现性引导：origin OQ9（FYI 级别）

Risks & Dependencies

风险	影响	缓解
`_phase_executor.py` 流式切换可能影响阶段执行稳定性	expert_result 流式中断或丢失；retry loop 与流式交互导致前端累积乱码	U3 单独测试；遵循 `execute_stream` 入口 `self.reset()` 前置条件；retry+流式合约：重试前广播 `expert_result_chunk_reset` 让前端清空，最终 `expert_result` 覆盖累积（详见 U3 Approach）
FullCalendar `.fc-*` 类名升级时可能破坏	日历样式失效	覆盖范围最小化（4 类稳定类名）；在 `calendar-overrides.css` 顶部注释标注风险
chatStore 新增 `deleteMessage` 可能影响会话状态一致性	消息索引错乱	参考 `deleteConversation` 的 pending 清理模式；单元测试覆盖删除后消息索引
U3/U4 联调依赖	前端流式无法独立验证	U4 可用 mock `expert_result_chunk` 事件开发；U3 完成后联调

System-Wide Impact

前端：ChatView 组件树结构调整（banner 替换为 sticky header）；chatStore 新增方法与状态；chatStream 事件分支改造
后端：_phase_executor.py 执行模式变更（execute → execute_stream）；WS 事件新增 expert_result_chunk / team_synthesis_chunk
测试：新增组件测试文件（ThinkingBlock / StickyModeHeader / AssistantText / UserBubble）；chatStream.test.ts 扩展流式测试
样式：新增 calendar-overrides.css；PhaseIndicator token 化；CalendarGrid token 化

Open Questions

来自 origin 文档的 9 个 Open Questions 处理状态：

OQ	状态	处理方式
OQ1 交互状态覆盖	Deferred	本期测试覆盖核心场景，全面规范留待后续
OQ2 响应式与无障碍	Deferred	本期遵循基本 a11y，全面策略留待后续
OQ3 流式结构	Resolved	U3 采用 `execute_stream()` + token 转发
OQ4 R16 删除作用域	Resolved	前端隐藏，服务端删除留待后续
OQ5 模式切换用户流	Addressed	U2 Approach 中覆盖
OQ6 关键交互细节	Addressed	U2/U6 Approach 中指定（Popover/Popconfirm）
OQ7 .fc-* 兼容性	Noted as Risk	Risks 表中标注
OQ8 Sticky 头部替代	Resolved	brainstorm 已确认 sticky 方案
OQ9 模式可发现性	FYI	Deferred to Follow-Up
OQ10 (NEW) U3 后端协议 scope 声明	Deferred	origin 行 88 显式排除后端流式协议（"不属本文档 scope"），但 U3 已纳入本计划作为实施单元。是否重新分类 U3 为 "Cross-cutting dependency unit"（与 UI/UE 单元分开）或显式标注为 scope 扩展？建议实施前确认。
OQ11 (NEW) PhaseIndicator token 化 R-id 追溯	Deferred	U2 中 PhaseIndicator 颜色 token 化（`#722ed1`/`#52c41a`/`#cf1322` → `--accent-board`/`--color-success`/`--color-error`）无对应 R-id 追溯（origin R7 仅要求"独立保留 + token 化"）。是否新增 R-id 显式覆盖此 token 化工作，或延后到独立 token 化 pass 处理其他组件同类硬编码？

Sources & Research

Origin: docs/brainstorms/2026-07-01-ui-ue-enhancement-requirements.md（ce-brainstorm 产出 + ce-doc-review 审查强化）
docs/solutions/logic-errors/long-horizon-reliability-code-review-fixes.md — execute_stream 入口 reset 前置条件、team_synthesis 综合阶段完整内容读取
docs/solutions/ui-bugs/calendar-agent-create-no-refresh.md — WS 事件链端到端追踪模式、notify_callback 注入
docs/solutions/logic-errors/calendar-capability-and-ui-fixes.md — SystemMonitorPanel flex 方向、deleteConversation pending 清理
docs/solutions/conventions/any-and-except-exception-governance.md — WebSocket 异常分类、CancelledError 守卫
docs/solutions/integration-issues/jwt-secret-dev-mode-user-id-mismatch.md — CalendarGrid firstDay 配置
代码库研究：react.py:1443（execute_stream）、_phase_executor.py:222（流式缺口）、chatStream.ts:526-532（final_answer 累积模式）、tokens.css（Notion 调色板）、configs/experts/*.yaml（专家元数据字段）

30 KiB Raw Blame History Unescape Escape

feat: AgentKit UI/UE 增强 — 聊天流式 + Sticky 头部 + 日历重设计

Summary

Problem Frame

Requirements

需求追溯

成功标准

Key Technical Decisions

High-Level Technical Design

流式事件链路（R8-R11）

组件依赖关系

Implementation Units

U1. ThinkingBlock 流式展示重设计

U2. StickyModeHeader + PhaseIndicator token 化

U3. 后端 _phase_executor.py 流式切换

U4. 前端 expert_result/team_synthesis 流式消费 + 身份标识

U5. AssistantText 路由标签悬停显示

U6. UserBubble 悬停操作（复制/删除/回填）

U7. CalendarGrid token 重设计

Scope Boundaries

Deferred for later

Outside this product's identity

Deferred to Follow-Up Work

Risks & Dependencies

System-Wide Impact

Open Questions

Sources & Research

30 KiB

Raw Blame History