AI Elements 组件目录

Motif 的 Chat / Agent / 文件树等 AI UI 统一使用 AI Elements。
本文档按 elements.ai-sdk.dev/components 的组件目录整理，并标注 Motif 安装与使用状态。

相关：docs/frontend/ui.md · docs/development/technical-plan.md · 官网 Docs · Setup

1. 约定（Motif）

项 说明
落盘 src/components/ai-elements/<name>.tsx
安装 pnpm dlx shadcn@latest add https://elements.ai-sdk.dev/api/registry/<name>.json -y -o
通用 UI 继续 shadcn src/components/ui/（AI Elements 依赖其 peers）
传输层 Motif ACP Client（agent_run_once + 事件流），不是默认 useChat
业务壳 layout/agent-panel（Chat）、layout/file-tree（Vault 树）、layout/backlinks-panel（反链）、layout/graph-panel（图谱）
状态列 ✅ 已装并接线 · 📦 已装未接线 · — 未安装

安装命令中的 <name> 与下表 Registry 名（URL 路径）一致。

# 示例：安装 Message
pnpm dlx shadcn@latest add https://elements.ai-sdk.dev/api/registry/message.json -y -o

2. 组件总表（按官网）

官网组件页：https://elements.ai-sdk.dev/components/<name>。
下表按场景分组；Registry 名 = 安装 URL 与文件名。

2.1 对话核心（Chat）

组件 Registry 说明 Motif
Conversation conversation 消息列表容器；贴底滚动、空状态、滚动按钮 ✅ Chat 列表
Message message 单条消息：from、内容、MessageResponse（Streamdown）、操作/分支 ✅ 用户/助手气泡
Prompt Input prompt-input Composer：输入、附件、提交状态、工具槽 ✅ 底部输入
Sources sources 折叠展示引用来源列表 ✅ Vault 路径引用
Attachments attachments 附件网格/列表/预览 📦（Prompt 已支持，ACP 暂不传文件）
Suggestion suggestion 快捷建议 chip ✅ 空态 / 输入上方
Shimmer shimmer 加载占位闪光文案 ✅ 等待正文
Inline Citation inline-citation 正文内可悬停引用 ✅ 回复末尾徽章 + Hover 轮播
Open in Chat open-in-chat 「在 Chat 中打开」 — 非 Chat 栏入口

2.2 Agent / 推理 / 工具

组件 Registry 说明 Motif
Reasoning reasoning 思考过程折叠展示 ✅ ACP thought 流
Chain of Thought chain-of-thought 思维链步骤 📦（Reasoning + Tool 已覆盖）
Tool tool 工具调用：状态、输入、输出 ✅ agent:tool
Confirmation confirmation 人在环确认 📦（Host 仍自动选第一项）
Task task 任务列表 / 进度折叠 ✅ 工具调用摘要
Plan plan 计划步骤展示 ✅ agent:plan
Queue queue 消息队列、待办 📦
Checkpoint checkpoint 检查点 / 里程碑 ✅ 系统行
Agent agent Agent 身份 UI —
Context context 上下文窗口/用量 ✅ agent:usage
Persona persona Rive 角色动画 📦（依赖 WebGL/外链，未接）
Model Selector model-selector 模型选择 ✅ 输入框旁；列表来自 ACP session config

Motif BYOA：模型列表与能力由 ACP Agent 通过 session config_options（category: model）上报；Motif 不托管 API Key。Header 切换的是 ACP 后端，输入框切换的是 该 Agent 提供的 model。

2.3 代码与工程

组件 Registry 说明 Motif
Code Block code-block 代码块、复制、语言切换 📦（MessageResponse 内已有 streamdown 代码）
File Tree file-tree 可展开文件树 ✅ 侧栏 Vault 树
Terminal terminal 终端输出样式 —
Stack Trace stack-trace 堆栈展示 —
Test Results test-results 测试结果 —
Snippet snippet 短代码片段 —
Commit commit Commit 信息展示 —
Package Info package-info 包信息 —
Schema Display schema-display Schema 结构展示 —
Environment Variables environment-variables 环境变量展示 —

2.4 预览 / Artifact / 沙箱

组件 Registry 说明 Motif
Web Preview web-preview URL / 网页预览框 —
Artifact artifact 生成物（文档/代码等）容器 —
Sandbox sandbox 沙箱运行环境 UI —
JSX Preview jsx-preview JSX 实时预览 —
Image image 图片展示 —

2.5 语音 / 音频

组件 Registry 说明 Motif
Speech Input speech-input 语音输入 —
Mic Selector mic-selector 麦克风设备选择 —
Voice Selector voice-selector 语音/音色选择 —
Audio Player audio-player 音频播放 —
Transcription transcription 转写文本 —

2.6 图 / 工作流画布

组件 Registry 说明 Motif
Canvas canvas 画布根容器 —
Node node 图节点 —
Edge edge 边 —
Connection connection 连接线/连线交互 —
Controls controls 画布控件 —
Panel panel 画布面板 —
Toolbar toolbar 画布工具栏 —

3. Motif 已安装明细

路径：src/components/ai-elements/

文件 主要导出 接线位置
conversation.tsx 列表 / 空态 / 贴底 layout/agent-panel
message.tsx Message + Actions / Response layout/agent-panel
prompt-input.tsx Composer layout/agent-panel
sources.tsx Vault 引用 layout/agent-panel
reasoning.tsx Thought 折叠 layout/agent-panel
tool.tsx ACP tool 调用 layout/agent-panel
plan.tsx ACP plan layout/agent-panel
task.tsx 工具摘要 layout/agent-panel
suggestion.tsx / shimmer.tsx 建议 chip / 加载 layout/agent-panel
checkpoint.tsx 系统切换行 layout/agent-panel
context.tsx Token 用量 layout/agent-panel header
file-tree.tsx Vault 树 layout/file-tree
inline-citation.tsx 正文旁引用徽章 layout/agent-panel
其它已装未接 chain-of-thought, queue, confirmation, persona, attachments, code-block 按需扩展

4. Motif 集成要点

4.1 Chat 组合（已接线）

Conversation
  ConversationContent
    Message from="user" | "assistant"
      MessageContent
        Reasoning → ReasoningTrigger + ReasoningContent   // ACP thought
        MessageResponse                                    // ACP message
    Sources（可选）
  ConversationScrollButton
PromptInput
  PromptInputBody → PromptInputTextarea
  PromptInputFooter → PromptInputTools + PromptInputSubmit

4.2 流式事件映射

ACP 事件 UI
发送成功 追加 user 行 + streaming assistant 行
agent:stream kind=thought 追加到最后一条 agent 的 reasoning，Reasoning isStreaming
agent:stream kind=message（默认） 追加到最后一条 agent 的正文 MessageResponse
agent:completed 定稿正文 / reasoning + sources
agent:failed 去掉未完成 streaming，追加 error

监听需可取消，避免 Strict Mode 双挂载导致重复气泡。

4.3 传输边界

能力 Motif
AI Elements UI ✅
useChat / HTTP DefaultChatTransport ❌ 默认不用
ACP runOnce + events ✅

4.4 推荐 import

import {
  Conversation,
  ConversationContent,
  ConversationEmptyState,
  ConversationScrollButton,
} from "@/components/ai-elements/conversation";
import {
  Message,
  MessageContent,
  MessageResponse,
} from "@/components/ai-elements/message";
import {
  PromptInput,
  PromptInputBody,
  PromptInputFooter,
  PromptInputSubmit,
  PromptInputTextarea,
  PromptInputTools,
} from "@/components/ai-elements/prompt-input";
import {
  Source,
  Sources,
  SourcesContent,
  SourcesTrigger,
} from "@/components/ai-elements/sources";
import {
  FileTree,
  FileTreeFile,
  FileTreeFolder,
} from "@/components/ai-elements/file-tree";

5. 扩展新组件

  1. 在 组件目录 确认名称与文档。
  2. pnpm dlx shadcn@latest add https://elements.ai-sdk.dev/api/registry/<name>.json -y -o
  3. 仅在 layout/* 等业务壳接线；不复制平行实现。
  4. 更新本文 §2 状态列 与 §3。
  5. 传输仍走 ACP，除非产品明确改为 HTTP Agent。

6. 仓库目录（非 AI Elements）

src/components/
├── ui/                  # shadcn 原语
├── ai-elements/         # 本文档对应内容
├── layout/              # 工作台：分栏、文件树、Agent、Backlinks、Graph
├── editor/              # Plate Markdown 编辑器
├── viewer/              # PDF / HTML
└── settings-window.tsx
  • Plate（editor/）：笔记 WYSIWYG，不是 AI Elements。
  • 禁止把 Chat 塞进 ui/ 或与 shadcn Message/Bubble 混用。

7. 参考