agent-ui-design

Agent-UI-Design

聊天界面、Agent 用户体验、流式 UI 和工具可视化的设计模式。基于 21st.dev Agents SDK 和屡获殊荣的 Agent 产品。

范围

在以下情况下使用此技能：

• 为 AI 应用设计聊天界面
• 需要直观呈现 Agent 工具调用
• 实现实时文本输出的流式渲染
• 可视化沙盒状态和执行环境
• 为 Agent 仪表板设计三栏布局

原则

1. 面向 Agent 的设计

组件必须原生支持流式内容、工具调用和异步状态转换。聊天 UI 是核心模式，而非附加功能。

2. 透明胜于神秘

用户必须始终知道系统正在做什么。不要在后台静默工作——每个 Agent 步骤都应可见。

3. 渐进式复杂度

默认视图展示基本信息。详细信息（工具参数、原始数据、日志）可按需查看。

4. 将流式输出作为体验设计

实时文本输出不是技术细节，而是经过精心设计的用户体验元素。文本出现的速度会影响用户对智能程度的感知。

5. 将错误视为设计场景

工具错误、超时和意外结果都是常见状态，并非例外。它们需要专门的视觉设计。

规则

聊天架构

• 应当：采用遵循 21st.dev 模式的三栏聊天架构：
  • 对话侧边栏（左侧）：可滚动的历史对话列表，并提供搜索功能。
  • 聊天面板（中间）：包含输入框的消息流，是主要交互区域。
  • 上下文面板（右侧）：可选，用于展示结果、预览和表单。
• 应当：延迟加载消息历史记录。初始仅加载最近的 N 条消息，较早的消息在向上滚动时加载。
• 不要：将完整消息历史记录保存在客户端状态中。应使用服务端持久化。
• 不要：让聊天面板没有可见的输入框。必须始终明确输入位置。

消息类型

• 应当：按角色区分消息：
  • 用户消息：右对齐，使用强调色，布局紧凑。
  • 助手消息：左对齐，使用中性色，可展开查看工具结果。
  • 系统消息：居中，样式低调，用于提供信息。
  • 工具调用：通过状态指示器在视觉上加以区分。
• 应当：在助手消息中渲染 Markdown（标题、列表、代码块）。
• 应当：为代码块提供语法高亮和复制按钮。
• 不要：对所有消息类型使用相同样式。视觉区分有助于用户定位。

流式渲染

• 应当：逐字符或逐词显示文本，并显示光标指示器。
• 应当：使用 AI SDK useChat hook 或 SSE 流式传输实现实时渲染。
• 应当：流式传输期间自动滚动到底部，并显示停止按钮。
• 不要：在生成期间阻止渲染。用户必须随时能够滚动。
• 不要：在流式传输时不显示可视光标。用户必须知道还有更多文本即将出现。

工具可视化

• 应当：在聊天流中显示工具调用：
  • 工具名称：在结果之前显示为标签或徽章。
  • 输入参数：可折叠，供高级用户查看。
  • 结果：按类型格式化（文本、表格、代码、图像）。
  • 状态：加载旋转指示器 > 成功勾选标记 > 错误图标。
• 应当：将工具结果作为嵌入卡片显示在消息流中。
• 应当：明确显示错误状态，包括错误原因和用户可采取的操作。
• 不要：让工具调用没有可视反馈。禁止静默执行。
• 不要：直接输出原始 JSON。始终以便于人类阅读的形式呈现。

沙盒 UI

• 应该：直观呈现沙盒状态：
  • 已创建：显示环境已就绪的指示器。
  • 运行中：绿色状态点。
  • 执行中：带进度指示的动画状态。
  • 已终止：最终状态及结果摘要。
• 应该：将文件树设计成交互式树状结构，并支持文件预览。
• 不应该：在默认视图中显示沙盒详情。采用渐进式披露。

扩展规则和示例：请参见 references/implementation.md

模式

模式	用途	核心思路
流式聊天消息	所有 AI 聊天应用	SSE 流、光标、Markdown 渲染
工具执行卡片	Agent 执行操作时	徽标 + 可折叠参数 + 状态
三栏布局	Agent 仪表板	会话 + 聊天 + 上下文
表单与 Agent 混合模式	表单助手	表单 + 聊天，由 Agent 填写字段
实时状态仪表板	监控 Agent	实时更新、按颜色区分的磁贴

详细模式：请参见 references/patterns.md

反模式

1. 没有上下文面板的聊天机器人 -- 结果只以内联形式显示在聊天中。复杂输出需要独立空间。
2. 将工具结果作为 JSON 转储 -- 原始 API 响应。始终以易于理解的格式呈现。
3. Agent 工作过程不可见 -- 工具执行期间没有反馈。用户会以为系统卡住了。
4. 所有消息样式相同 -- 所有消息的样式都相同。必须区分不同角色。
5. 无限流式输出且无法停止 -- 生成期间没有取消按钮。
6. 以模态框显示工具结果 -- 用模态框而不是内联方式显示工具输出，会打断对话流程。
7. 会话侧边栏没有搜索功能 -- 对话超过 10 个时，搜索和筛选必不可少。
8. 缺少重试选项 -- 工具出错时无法重试。

检查清单

• 按角色区分聊天消息（用户、助手、系统、工具）
• 实现带有可见光标的流式渲染
• 生成期间显示停止按钮
• 工具调用具有加载、成功和错误状态
• 工具结果经过格式化，而不是原始 JSON 输出
• 工具参数可折叠查看
• 三栏布局：会话 + 聊天 + 上下文
• 消息历史按需加载（不全部加载到客户端）
• 代码块支持语法高亮和复制按钮
• 助手消息支持 Markdown 渲染
• 直观呈现沙盒状态
• 工具出错时显示重试按钮
• 移动端：聊天面板全屏显示，侧边栏作为抽屉
• 键盘快捷键：按 Enter 发送，按 Shift+Enter 换行

交叉引用

• component-patterns -- 基础组件架构和令牌系统
• design-trends -- AI 原生界面作为当前趋势
• ui-patterns -- 命令面板和通用 UI 模式
• visual-direction -- Agent 界面的调色板和排版
• usability -- 聊天界面的可用性基础
• accessibility -- 聊天 UI 的屏幕阅读器兼容性
• responsive-design -- 三栏布局的移动端策略