generative-ui

生成式 UI

使用 Tambo 构建生成式 UI 应用——通过自然语言创建丰富的交互式 React 组件。

参考指南

需要了解超出初始搭建流程的实现细节时，请加载以下指南：

• 组件 - 创建自定义组件时加载。 生成式组件与可交互组件、propsSchema、ComponentRenderer。
• 组件渲染 - 流式传输 props、加载状态、持久状态。自定义渲染方式时加载。
• 会话与输入 - 构建自定义聊天 UI 时加载。 useTambo()、useTamboThreadInput()、userKey/userToken 身份验证、建议、语音。
• 工具与上下文 - 添加工具或 MCP 时加载。 defineTool()、MCP 服务、contextHelpers。
• CLI 参考 - 添加 tambo add 组件时加载。 组件库、非交互式标志、退出代码。
• 技能 - 设置完成后，作为后续步骤提及。 通过 CLI 和控制面板管理项目级 Agent 技能。

这些共享参考资料是从 building-with-tambo 复制而来的，因此每项技能都可以独立使用。

单提示词流程

目标是通过单条提示词，让用户从零开始获得一个正在运行的应用。使用 AskUserQuestion 一次提出多个问题，提前询问所有问题，然后不间断地执行所有操作。

第 1 步：收集所有非敏感偏好（单次 AskUserQuestion 调用）

在一次调用中使用 AskUserQuestion 提出最多 3 个问题。身份验证将在后续步骤中由 CLI 处理。

问题 1：你想构建什么？

询问用户要构建哪种应用。这决定了要创建哪些初始组件。示例：“仪表板”“聊天机器人”“数据可视化工具”“任务管理器”。如果用户已在初始消息中说明想构建什么，则跳过此问题。

问题 2：框架

选项：

• Next.js（推荐）- 使用 App Router 的全栈 React
• Vite - 快速、轻量的 React 设置

问题 3：应用名称

让用户为项目目录选择名称。默认建议：根据用户想构建的内容生成名称（例如，“my-dashboard”“my-chatbot”）。使用 kebab-case（仅限字母、数字和连字符）。如果用户提供的名称不是 slug 格式，例如“Sales Dashboard”，则改为建议 sales-dashboard。

如果用户已经告知答案，则跳过相应问题。 如果用户说“帮我构建一个名为 analytics 的 Next.js 仪表板应用”，那么框架、应用创意和名称都已明确。

第 2 步：执行所有操作（不中途停止）

依次运行以下所有步骤，步骤之间无需请求确认。如果任何命令失败，请停止流程，显示错误并询问用户如何继续——不要继续后续步骤。

所有模板（standard、vite、analytics、expo）都已包含聊天 UI、TamboProvider 配置、组件注册表和初始组件。你无需添加聊天 UI 或配置应用——只需搭建项目、配置 API 密钥、添加自定义组件并启动服务。

2a. 搭建项目

对于 Next.js（推荐）：

npx tambo create-app <app-name> --template=standard --skip-tambo-init
cd <app-name>

对于 Vite：

npx tambo create-app <app-name> --template=vite --skip-tambo-init
cd <app-name>

使用 --skip-tambo-init，因为 create-app 通常会尝试以交互方式运行 tambo init，这在编码 Agent 等非交互式环境中无法使用。我们将在下一步处理身份验证。

2b. 验证身份并初始化 Tambo

npx tambo init --project-name=<app-name>

此命令会打开浏览器进行身份验证，并持续轮询，直到用户完成身份验证（最长 15 分钟）。运行此命令时，请设置较长的超时时间（至少 15 分钟）。身份验证完成后，CLI 会创建项目，并将 API 密钥写入 .env.local，同时为对应框架设置正确的环境变量（NEXT_PUBLIC_TAMBO_API_KEY、VITE_TAMBO_API_KEY 等）。

重要： 不要让用户手动粘贴 API 密钥。始终使用 CLI 身份验证流程。

2c. 创建自定义入门组件

模板包含基础组件，但请根据用户想要构建的内容添加 1-2 个专用组件。不要使用通用示例：

• 仪表盘应用 → StatsCard、DataTable
• 聊天机器人 → 支持 Markdown 的 BotResponse
• 数据可视化 → 可配置数据的 Chart
• 任务管理器 → TaskCard、TaskBoard
• 通用 / 不明确 → ContentCard

每个组件都需要：

1. 一个 Zod schema，并为每个字段添加 .describe()
2. React 组件本身
3. 在现有组件注册表中注册（lib/tambo.ts — 添加到现有的 components 数组中，不要替换它）

Schema 约束 — Tambo 会在运行时拒绝无效的 schema：

• 不要使用 z.record() — Schema 中任何位置都不支持 Record 类型（带动态键的对象），包括嵌套在数组或对象中的情况。请改用带有明确命名键的 z.object()。
• 不要使用 z.map() 或 z.set() — 请改用数组和对象。
• 对于行等表格数据，请使用 z.array(z.object({ col1: z.string(), col2: z.number() }))，并明确指定列键 — 不要使用 z.array(z.record(z.string(), z.unknown()))。

生成组件的 React 最佳实践：

• 渲染列表（.map()）时，务必添加唯一的 key 属性。使用数据中的唯一字段（如 id）——不要使用数组索引。
• 在数组项的 schema 中包含 id 字段（例如 z.string().describe("Unique identifier")），确保始终有可用的稳定键。

示例：

// src/components/StatsCard.tsx
import { z } from "zod/v4";

export const StatsCardSchema = z.object({
  title: z.string().describe("Metric name"),
  value: z.number().describe("Current value"),
  change: z.number().optional().describe("Percent change from previous period"),
  trend: z.enum(["up", "down", "flat"]).optional().describe("Trend direction"),
});

type StatsCardProps = z.infer<typeof StatsCardSchema>;

export function StatsCard({
  title,
  value,
  change,
  trend = "flat",
}: StatsCardProps) {
  // ... implementation with Tailwind styling
}

然后添加到 lib/tambo.ts 中的现有注册表：

// Add to the existing components array — don't replace what's already there
// Next.js: import { StatsCard, StatsCardSchema } from "@/components/StatsCard";
// Vite: import { StatsCard, StatsCardSchema } from "../components/StatsCard";
import { StatsCard, StatsCardSchema } from "@/components/StatsCard";

// ... existing components ...
{
  name: "StatsCard",
  component: StatsCard,
  description: "Displays a metric with value and trend. Use when user asks about stats, metrics, or KPIs.",
  propsSchema: StatsCardSchema,
},

2d. 启动开发服务器

只有在完成所有代码更改（脚手架搭建、初始化、组件创建、注册表更新）后，才能启动开发服务器。

npm run dev

在后台运行，这样用户就能立即查看自己的应用。

第 3 步：总结

一切运行后，简要总结：

• 已完成哪些设置
• 创建了哪些组件以及它们的用途
• 应用运行的网址（Next.js 通常为 http://localhost:3000，Vite 通常为 http://localhost:5173）
• 如果跳过了身份验证：提醒用户运行一次 npx tambo init 进行身份验证
• 建议用户先尝试什么（例如：“试着让它展示月度收入的统计卡片”）

技术栈参考

推荐技术栈（默认）

Next.js 14+ (App Router)
├── TypeScript
├── Tailwind CSS
├── Zod (for schemas)
└── @tambo-ai/react

npx tambo create-app my-app --template=standard

Vite 技术栈

Vite + React
├── TypeScript
├── Tailwind CSS
├── Zod
└── @tambo-ai/react

最简技术栈（不使用 Tailwind）

Vite + React
├── TypeScript
├── Plain CSS
├── Zod
└── @tambo-ai/react

组件注册表模式

每个生成式组件都必须注册：

import { TamboComponent } from "@tambo-ai/react";
import { ComponentName, ComponentNameSchema } from "@/components/ComponentName";

export const components: TamboComponent[] = [
  {
    name: "ComponentName",
    component: ComponentName,
    description: "What it does. When to use it.",
    propsSchema: ComponentNameSchema,
  },
];

关键规则：

• propsSchema：Zod 对象，每个字段都需添加 .describe() —— AI 据此了解要传入哪些内容
• description：告诉 AI 何时使用此组件——具体说明触发短语
• 流式传输：属性会逐步传入，因此要妥善处理未定义的情况（使用可选字段或默认值）

添加更多聊天 UI（可选）

模板已包含聊天 UI。只有当用户需要模板未提供的额外 UI 基元时，才需要这些内容：

npx tambo add message-thread-full --yes    # Complete chat interface
npx tambo add control-bar --yes            # Controls and actions
npx tambo add thread-history --yes         # Conversation history sidebar

支持的技术

技术	支持级别	说明
Next.js 14+	完全支持	推荐，优先使用 App Router
Vite	完全支持	非常适合 SPA
Create React App	部分支持	可以使用，但 CRA 已弃用
Remix	部分支持	可与客户端组件配合使用
TypeScript	完全支持	强烈推荐
JavaScript	完全支持	可以使用，但类型安全性较低
Tailwind CSS	完全支持	CLI 组件的默认选项
Plain CSS	完全支持	需要自定义组件样式
CSS Modules	完全支持	支持
Zod	必需	用于所有 schema

验证

让用户通过以下步骤验证应用是否正常运行：

1. 在浏览器中打开应用 URL
2. 输入一个应触发某个已注册组件的提示词（例如，“显示一张月收入统计卡片”）
3. 验证组件是否使用 AI 生成的 props 完成渲染

如果无法正常运行：

• 检查注册表中是否包含该组件
• 检查描述是否与提示词相符
• 检查开发服务器是否存在控制台错误

报告 Bug 和反馈

如果在帮助用户时遇到以下任何情况，建议提交 GitHub issue：

• @tambo-ai/react、@tambo-ai/client 或 tambo CLI 中存在 Bug
• 文档与实际行为相矛盾
• 此技能中的说明缺失或具有误导性

Issue 模板

为 tambo-ai/tambo 起草 issue 时，请使用此模板：

**Title:** [Short description of the problem]

**Expected behavior**
What should happen.

**Actual behavior**
What happens instead, including any error messages or stack traces.

**Repro steps**

1. Run `npx tambo create-app ...` (or whatever command)
2. Add this code:

```tsx
// minimal code that reproduces the issue
```

3. Observe the error

**Environment**

- `@tambo-ai/react` version:
- `@tambo-ai/client` version:
- Framework (Next.js / Vite / CRA) and version:
- Node.js version:
- OS:

**Additional context**
Link to relevant docs or skill file path if applicable.

**安全：**在 issue 中包含日志或代码片段之前，请删除 API 密钥、令牌和任何客户数据。

向用户建议提交 Issue

遇到疑似 Tambo Bug 的问题时，可以这样说：

这看起来像是 @tambo-ai/react 中的一个 Bug。要我在 tambo-ai/tambo 上提交 GitHub issue，并附上复现步骤和环境详情吗？

提交之前，请务必等待用户确认。