agent-ui

agent-ui

带有模型的界面多了一种其他界面都没有的状态：正在进行，已有部分输出，长度未知。这里的每种模式都源于如何如实处理这种状态。

原则

1. 展示过程，但默认折叠。 推理、工具调用和来源均可按需查看，既不隐藏，也不强制展开。
2. 用户随时可以停止。 每次生成都有一个固定位置的停止控件，按 Escape 即可触发。
3. 绝不伪造进度。 不要使用毫无意义的旋转动画，不要用计时器假装“思考”，也不要让打字机效果慢于实际输出流。
4. 输入框始终可用。 当前回复输出期间起草下一条消息是很正常的。
5. 输出是文档，不是日志。 渲染 Markdown，使用真正的代码块，保持布局稳定。

输入框

• 默认支持多行，最多增长到 6–8 行，然后滚动。模型输入框绝不能是单行。
• 桌面端按 Enter 发送，按 Shift+Enter 换行；手机端使用发送按钮，按 Enter 换行。
• 附件、模型或模式选择以及斜杠命令放在文本下方同一输入框内的一行中，不要散布在各处。
• 输出流式传输时，发送按钮变为停止按钮。位置不变，大小不变。
• 草稿在重新加载和切换路由后仍会保留。
• 发送后、停止后以及对话框关闭后，焦点返回输入框。
• 仅当字符数或令牌数达到限制的 10% 以内时，才显示限制。

流式文本

• 令牌到达时将其追加到 DOM；不要每个令牌都重新渲染整条消息。如果输出流速度更快，则按动画帧批量处理（约 16ms）。
• 不要逐个字符动画显示。当前行末尾显示一个淡色光标块，足以表明“仍在输出”。
• 使用能容忍未闭合区块的解析器增量渲染 Markdown。未闭合的代码围栏应渲染为代码块，而不是一段反引号。
• 不预留空间：消息随内容增长。但容器不得因滚动而突然跳动（见“滚动”）。
• 长输出：代码超过约 40 行后，仅在输出流结束后折叠，并显示“显示更多”，绝不要在输出过程中折叠。

思考与推理

• 思考过程中只显示一行折叠内容：“思考中…”，2 秒后显示已用时间。不要显示一段闪烁的文字。
• 可展开查看推理文本，使用等宽字体或弱化样式，字号小于答案。
• 答案开始输出时，思考区块折叠为一行并显示耗时（“思考了 8s”），之后保持此状态。
• 如果模型没有返回可显示的内容，绝不要播放虚假的“思考”动画；使用简单的已用时间指示器。

工具调用

每次调用都以紧凑行的形式显示在消息流中：

▸ Read  src/components/Button.tsx                         120ms ✓
▸ Search  "focus-visible" in src/                          3 hits ✓
▸ Edit  src/components/Button.tsx                         running…

• 图标或动词、目标以及状态：运行中、已完成（附结果摘要）、失败（附错误，可展开）。
• 使用标签或行，而不是卡片。将连续调用分组；十次读取折叠为“读取了 10 个文件 ▸”。
• 展开后以等宽字体显示原始输入和输出，内容可滚动，并提供复制功能。
• 正在运行的调用在其自身行中显示小型确定或不确定进度指示器；整条消息不应旋转。
• 失败不会破坏布局；失败项保留原位并标记出来，模型会在下一条消息中解释。

审批

当 Agent 想要执行有影响的操作时（写入文件、发送电子邮件、运行命令、花钱）：

• 在消息流中放置区块，而不是弹出模态框；区块显示要执行的操作、确切目标，以及“允许 / 拒绝”。可选显示：“允许本次会话期间执行”。
• 键盘操作：区块获得焦点时，按 Enter 表示允许，按 Escape 表示拒绝。区块出现时，焦点移至该区块。
• 决定后，区块折叠为一行：“已允许：运行 npm test”。
• 用户反应较慢时绝不要自动批准。超时则拒绝。
• 文件写入时显示差异；发送消息时显示收件人；消费金额时显示金额。

来源和引用

• 行内标记（[1]）链接到消息末尾的来源列表；将鼠标悬停在标记上可预览来源。
• 来源列表显示网站图标、标题和主机名。点击后会在新标签页中打开。
• 来源引文会以不同样式呈现（左侧边框、弱化颜色），且内容简短。
• 没有来源，就不要声称有来源。文本没有依据时，不要呈现引用 UI。

消息操作

悬停时（触屏设备上则始终显示）：复制、重新生成、编辑并重新发送（用户消息）、点赞/点踩。小型图标按钮排列在消息下方，点击区域为 28px，显示时不改变布局（预留该行高度）。

复制的是 Markdown 源码，而非渲染后的文本，并通过图标切换确认。

滚动

• 仅当用户原本就在底部时，才在流式输出期间固定在底部。用户一旦向上滚动，就停止固定。
• 取消固定且有新内容到达时，显示“↓ 跳转到最新内容”提示条。
• 用户发送新消息时，将该消息滚动到视口顶部，为下方逐渐增长的回复留出空间。
• 使用 overflow-anchor，并确保视口上方的内容高度稳定，避免图片和代码块渲染时导致旧内容移位。

延迟

• 首个 Token 超过 400ms 才到达：立即显示带光标的空白助手气泡。不要等到有内容才显示对话已开始。
• 工具繁多的轮次：工具行本身就是进度指示器。
• 遇到速率限制和排队时，应明确告知；如有预计时间，也应说明。“排队中，约 20 秒”胜过只显示加载动画。

错误和中断

• 用户停止时：保留部分消息，并标记为“已停止”。可以继续生成。
• 流式输出中途失败时：保留部分消息，在下方显示错误，并提供“重试”按钮，以相同提示词重新发送。
• 上下文限制：提前警告，而不是事后告知。提供总结或重新开始的选项。
• 失败时绝不要清除用户的最后一条消息。

Markdown 渲染

• 代码块：显示语言标签和复制按钮；支持水平滚动，不换行；使用 12.5–13px 等宽字体；流式输出结束后，超过约 30 行时折叠。
• 表格：窄屏上支持水平滚动；表头行样式应有区别；数字使用等宽数字。
• 回复中的标题应比应用标题小一到两个级别；回复不是页面。
• 链接在新标签页中打开，并显示外部链接标记。
• 清理内容。渲染后的输出不可信。

多 Agent 和长时间运行

• 每次运行都有一个标题栏：状态、已用时间、停止按钮。步骤即上方的工具调用行，并按阶段分组。
• 后台运行时，应显示一个小型常驻指示器（导航项上的圆点），并在完成时发送通知，而不是弹出模态框。
• 历史记录以运行列表形式呈现，包含状态和一行摘要，并支持搜索。

诚实

• 标明正在使用的模型和模式。显示消息是否经过编辑或重新生成。
• 区分 Agent 实际做了什么与声称做了什么：工具行是事实依据；文字说明只是文字说明。
• 如果“正在处理……”持续 30 秒却没有任何进展，这是一个错误。要么显示正在发生的事情，要么说明流程卡住了。

检查清单

• 始终显示“停止”按钮，且 Escape 键有效
• 输入框可自动增长、保留内容并重新获得焦点
• 流式输出按帧批量更新；不逐字符播放动画
• 思考过程折叠为一行时长
• 工具调用以带状态的行显示；分组可折叠
• 审批以内嵌形式呈现，支持键盘操作，超时后默认拒绝
• 仅在位于底部时固定滚动；否则显示跳转提示条
• 停止或失败后仍保留部分输出
• Markdown 经过清理；代码块可复制；表格可滚动
• 不会无缘无故显示加载动画

来自目录

• Beautiful UI — 将轨迹、工具标签和审批作为基础组件。
• AI Elements — 来自 AI SDK 的聊天、推理和来源组件。
• assistant-ui、prompt-kit — 可组合的聊天基础组件。
• AICSS — 在 React、Vue 和 Svelte 中呈现思考状态、工具调用和引用。
• Amelia Wattenberger — 探讨聊天框之外的 AI 界面。
• 更多内容见 stealth.pm/components。