building-with-tambo

使用 Tambo 构建

检测技术栈，并在保留现有模式的同时集成 Tambo。

参考指南

在进入相关步骤或需要更深入的实现细节时，加载以下指南：

• 组件 - 在步骤 5 加载。 生成式组件与可交互组件、propsSchema、ComponentRenderer。
• 组件渲染 - 流式 props、加载状态、持久状态。构建自定义消息渲染时加载。
• 会话与输入 - 构建自定义聊天 UI 时加载。 useTambo()、useTamboThreadInput()、userKey/userToken 身份验证、建议、语音。
• 工具与上下文 - 接入宿主应用 API 时加载。 defineTool()、MCP 服务、contextHelpers。
• CLI 参考 - 在步骤 6 加载。 tambo add 组件库、tambo init 标志、非交互模式。
• 技能 - 设置完成后将其作为后续步骤提及。 通过 CLI 和控制面板使用项目范围的 Agent 技能。
• 将组件添加到注册表 - 注册现有应用组件时加载。 分析 props、生成 Zod 模式、编写描述。

共享参考文档（组件、渲染、会话、工具与上下文、CLI、技能）也会复制到 generative-ui 中，以便每项技能都能独立使用。add-components-to-registry 是此技能独有的。

工作流

1. 检测技术栈 - 分析 package.json、锁文件、项目结构和 monorepo 布局
2. 与用户确认 - 呈现检查结果，并询问偏好
3. 安装依赖项 - 使用项目的包管理器添加 @tambo-ai/react 和 zod
4. 创建 Provider 设置 - 配置 TamboProvider，并提供 apiKey、userKey、components
5. 创建组件注册表 - 设置 lib/tambo.ts
6. 添加聊天 UI - 通过 CLI 安装预构建的 Tambo 组件，设置路径别名和 globals.css

步骤 1：检测技术栈

检查以下文件以了解项目：

# Key files to read
package.json           # Dependencies, scripts, AND package manager
tsconfig.json          # TypeScript config, path aliases
next.config.*          # Next.js
vite.config.*          # Vite
tailwind.config.*      # Tailwind CSS
postcss.config.*       # PostCSS
src/index.* or app/    # Entry points
yarn.lock / pnpm-lock.yaml / package-lock.json  # Which package manager

检测清单

技术	检测方式
Next.js	依赖项中有 next，且存在 next.config.*
Vite	devDependencies 中有 vite，且存在 vite.config.*
Create React App	依赖项中有 react-scripts
TypeScript	deps 中有 typescript，且存在 tsconfig.json
Tailwind	deps 中有 tailwindcss，且存在配置文件
Plain CSS	未使用 Tailwind，src/ 中有 CSS 文件
Zod	依赖项中有 zod
其他验证库	deps 中有 yup、joi、superstruct

包管理器检测

始终检测并使用项目的包管理器。 不要默认使用 npm。

锁文件	管理器	安装命令
package-lock.json	npm	npm install @tambo-ai/react
yarn.lock	Yarn	yarn add @tambo-ai/react
pnpm-lock.yaml	pnpm	pnpm add @tambo-ai/react

对于 monorepo，请在正确的工作区中安装：

• Yarn：yarn workspace <app-name> add @tambo-ai/react
• pnpm：pnpm --filter <app-name> add @tambo-ai/react
• npm：npm install @tambo-ai/react -w <app-name>

Monorepo 检测

检查以下 monorepo 标志：

• 根目录 package.json 中的 workspaces 字段
• pnpm-workspace.yaml
• turbo.json 或 nx.json
• apps/ 或 packages/ 中的多个 package.json 文件

如果检测到 monorepo，请确定哪个包是将使用 Tambo 的 Web 应用（通常位于 apps/web、apps/frontend 或类似目录中）。

全局键盘快捷键检测

检查应用是否会全局捕获键盘事件（常见于绘图工具、编辑器和 IDE）。查找：

• 代码库中是否有 document.addEventListener("keydown", ...)
• 基于 Canvas 的应用（Excalidraw、类似 Figma 的应用、代码编辑器）
• 键盘快捷键库（hotkeys-js、mousetrap 等）

如果存在，Tambo 聊天 UI 包装器必须阻止事件传播（见步骤 6）。

步骤 2：与用户确认

提供调查结果，包括包管理器和任何特殊注意事项：

I detected your project uses:
- Framework: Next.js 14 (App Router)
- Package manager: Yarn
- Styling: Tailwind CSS
- Validation: No Zod (will need to add)
- TypeScript: Yes
- Monorepo: No
- Global keyboard shortcuts: No

Should I:
1. Install Tambo with these settings?
2. Use plain CSS instead of Tailwind for Tambo components?
3. Something else?

步骤 3：安装依赖

使用项目的包管理器（在步骤 1 中检测）：

# npm
npm install @tambo-ai/react
npm install zod  # if no Zod installed

# yarn
yarn add @tambo-ai/react
yarn add zod

# pnpm
pnpm add @tambo-ai/react
pnpm add zod

# Monorepo (install in the correct workspace)
yarn workspace <app-name> add @tambo-ai/react zod
pnpm --filter <app-name> add @tambo-ai/react zod
npm install @tambo-ai/react zod -w <app-name>

步骤 4：创建 Provider 设置

Next.js App Router

// app/providers.tsx
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { components } from "@/lib/tambo";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TamboProvider
      apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY}
      userKey="default-user"
      components={components}
    >
      {children}
    </TamboProvider>
  );
}

重要： userKey 是身份验证所必需的。如果没有它，提交消息会在运行时失败，并显示 “authentication is not ready”。注意：在 TypeScript 中，userKey 的类型被标记为可选（userKey?: string），因此编译器不会发现此问题——该故障只会在运行时发生。在生产环境中，请使用真实的用户标识符（例如，会话 ID、身份验证系统中的用户 ID）。在开发或演示环境中，使用 "default-user" 这样的静态字符串即可。

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Next.js Pages Router

// pages/_app.tsx
import { TamboProvider } from "@tambo-ai/react";
import { components } from "@/lib/tambo";

export default function App({ Component, pageProps }) {
  return (
    <TamboProvider
      apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY}
      userKey="default-user"
      components={components}
    >
      <Component {...pageProps} />
    </TamboProvider>
  );
}

Vite / CRA

// src/main.tsx
import { TamboProvider } from "@tambo-ai/react";
import { components } from "./lib/tambo";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <TamboProvider
    apiKey={import.meta.env.VITE_TAMBO_API_KEY}
    userKey="default-user"
    components={components}
  >
    <App />
  </TamboProvider>,
);

步骤 5：创建组件注册表

// lib/tambo.ts (or src/lib/tambo.ts)
import { TamboComponent } from "@tambo-ai/react";

export const components: TamboComponent[] = [
  // Components will be registered here
];

步骤 6：添加聊天 UI

根据应用选择合适的聊天布局：

组件	最适用场景	呈现方式
message-thread-collapsible	覆盖在现有 UI 上方（绘图工具、简单应用）	固定位置的浮动面板，位于右下角，可切换打开或关闭
message-thread-panel	采用侧边栏布局的应用（仪表盘、管理面板、SaaS 应用）	带线程历史记录的侧边面板，可调整大小
message-thread-full	专用聊天页面或全屏聊天体验	具有全部功能的全高度聊天线程

根据应用的布局进行选择。如果应用采用侧边栏或仪表盘布局，请使用 panel。如果聊天应浮动在现有内容上方，请使用 collapsible。如果整个页面都是聊天界面，请使用 full。

npx tambo add message-thread-panel --yes
# Or: npx tambo add message-thread-collapsible --yes
# Or: npx tambo add message-thread-full --yes

# With other package managers:
# yarn dlx tambo add <component> --yes
# pnpm dlx tambo add <component> --yes

执行 tambo add 后，完成以下设置：

1. CSS 设置 — tambo add 会将 Tailwind 指令和 CSS 变量添加到项目的 CSS 入口文件中。它修改的文件取决于所用框架：

   • Next.js：app/globals.css（或 src/app/globals.css）——默认已在 layout 中导入。
   • Vite：src/index.css（或 index.css）——默认已在 main.tsx 中导入。

   如果入口文件已经导入了 CSS 文件，tambo add 会直接修改该文件。无需新增导入。

2. 路径别名 — Tambo 组件使用 @/ 导入。检查项目的 tsconfig 中的 paths 是否已包含 @/*。许多使用 create-next-app 创建的 Next.js 项目都已配置，但并非全部如此（例如，Cal.com 使用 ~/* 和 @components/*）。

   如果缺少 @/*，请将其添加到应用的 tsconfig 中（如果存在 tsconfig.app.json，则使用该文件，否则使用 tsconfig.json）：

   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   

   如果项目没有 src/ 目录，且组件放在项目根目录，请使用 ["./*"]，而不是 ["./src/*"]。检查 tambo add 将组件放在何处，以确定正确路径。

   对于 Vite 项目，还需将别名添加到 vite.config.ts：

   // vite.config.ts
   import path from "path";
   
   export default defineConfig({
     resolve: {
       alias: {
         "@": path.resolve(__dirname, "src"),
       },
     },
   });
   

键盘事件隔离

对于使用全局键盘快捷键的应用（绘图工具、编辑器、类终端应用）至关重要。 否则，在 Tambo 聊天输入框中打字会触发宿主应用的快捷键。

将 Tambo 聊天 UI 包装在一个会阻止键盘事件传播的 div 中：

<div
  onKeyDown={(e) => e.stopPropagation()}
  onKeyUp={(e) => e.stopPropagation()}
>
  {/* Use whichever component you installed */}
  <MessageThreadCollapsible />{" "}
  {/* or <MessageThreadPanel /> or <MessageThreadFull /> */}
</div>

全屏应用的 Z-Index

带有全屏画布或叠加层的应用可能会渲染在 Tambo 聊天界面上方。MessageThreadCollapsible 组件使用 position: fixed，但宿主应用的画布可能具有更高的堆叠上下文。请使用一个固定定位的容器将其包裹起来，使其位于所有内容上方：

<div
  style={{ position: "fixed", inset: 0, zIndex: 9999, pointerEvents: "none" }}
>
  <div style={{ pointerEvents: "auto" }}>
    {/* Use whichever component you installed */}
    <MessageThreadCollapsible />{" "}
    {/* or <MessageThreadPanel /> or <MessageThreadFull /> */}
  </div>
</div>

外层 div 会创建一个位于画布上方的堆叠上下文，而 pointerEvents: none/auto 可确保只有聊天面板可以点击，屏幕其余部分的点击事件则会传递给画布。

你可以在同一个包装器中同时实现键盘隔离和 z-index。

适配现有模式

不使用 Tailwind？使用纯 CSS

如果项目不使用 Tailwind，tambo add 会通过 PostCSS 安装 Tailwind v4，同时保留现有样式。这是增量式添加，不会破坏现有的 CSS/SCSS。Tambo 组件使用 Tailwind，但应用的其余部分仍保留原有样式。

如果你希望完全避免使用 Tailwind：

# Skip --yes flag to customize styling during add
npx tambo add message-thread-full
# Select "CSS Modules" or "Plain CSS" when prompted

已有校验库？

如果使用的是 Yup/Joi 而不是 Zod，用户可以：

1. 仅为 Tambo 架构添加 Zod（推荐，改动较小）
2. 转换架构（工作量较大，不推荐）

Monorepo？

请在 Web 应用包中运行命令，而不是在 monorepo 根目录中运行。

在 Web 应用目录中运行 npx tambo init --project-name=<app-name>。这会打开浏览器进行身份验证，并持续轮询，直到用户完成身份验证（最长 15 分钟）。请设置较长的超时时间。身份验证完成后，CLI 会创建项目并将 API 密钥写入 .env.local。

Monorepo 注意事项：

• 环境变量：tambo init 会在当前目录中创建 .env.local。Vite 会从 envDir 加载环境变量（请检查 vite.config.*）。确保环境文件位于 Vite 查找的位置。
• 依赖提升：某些包管理器会将依赖提升至 monorepo 根目录。如果 Vite 无法解析 Tambo 依赖，也请在根目录级别安装（例如，yarn add -W @tambo-ai/react）。
• 路径别名：Vite 会从 vite.config.* 所在目录解析路径。@/ 别名必须指向工作区内正确的 src/ 目录，而不是 monorepo 根目录。

环境变量

npx tambo init --project-name=<name> 会打开浏览器并持续轮询，直到用户完成身份验证（最长 15 分钟）。请设置较长的超时时间。身份验证完成后，它会创建项目并写入 .env.local。

如果需要手动设置（例如 monorepo 或只读文件系统），请添加相应的变量：

框架	变量
Next.js	NEXT_PUBLIC_TAMBO_API_KEY
Vite	VITE_TAMBO_API_KEY
CRA	REACT_APP_TAMBO_API_KEY

验证

设置完成后，创建一个简单的测试进行验证：

import { useTambo } from "@tambo-ai/react";

function TestComponent() {
  const { thread, isIdle } = useTambo();
  console.log("Tambo connected:", isIdle);
  return <div>Tambo is set up!</div>;
}

报告 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，并附上复现步骤和环境详情吗？

提交前务必先等待用户确认。