Chat SDK Playground

BotDojo聊天SDK游乐场

贝塔 -BotDojo聊天SDK的交互式游乐场

通过实时示例和实时调试探索聊天小部件、MCP应用程序和无头集成。

特性

• 🚀 聊天SDK示例：内联、弹出、侧面板和无头聊天模式
• 🎨 漂亮的UI：现代主题，三栏布局
• 🐛 调试面板：所有SDK交互的实时事件记录
• ⚡ 快捷操作：每个示例的预配置测试场景
• 🔧 轻松设置：使用BotDojo CLI自动设置脚本

快速开始

先决条件

1. Node.js 18+ 安装
2. BotDojo命令行界面 安装：

   npm install -g @botdojo/cli

1. BotDojo帐户 - 免费注册

安装

# Clone the repository
git clone https://github.com/botdojo-ai/chat-sdk-playground.git
cd chat-sdk-playground

# Install dependencies
npm install

设置

运行安装脚本以配置您的环境：

npm run setup

这将：

• 使用BotDojo对您进行身份验证（打开浏览器并进行用户确认）
• 使用当前的CLI项目上下文（从不自动切换）
• 将测试代理流克隆到您的项目（或更新现有流）
• 为新克隆的流创建公共API密钥
• 生成 .env.local 所有配置

注： 安装脚本是幂等的，可以多次运行。它将：

• 从源更新现有流，而不是创建重复流
• 保留中的现有API密钥 .env.local
• 仅为新克隆的流创建新的API密钥
• 永远不要自动切换CLI项目上下文

启动开发服务器

npm run dev

打开 http://localhost:3500 在您的浏览器中。

例子

聊天SDK示例

展示的关键模式

这些示例包含解释重要模式的内联JSDoc注释：

• 使用状态引用：工具执行函数通过引用捕获状态，以避免过时的闭包
• resourceUri匹配：工具 _meta.ui.resourceUri 必须与资源完全匹配 uri
• 使用onToolInputPart进行流式传输：在AI生成时接收部分工具参数
• 使用tool.result检测完成情况：工具执行完成时的转换UI
• 使用botdojo/presist保持状态：在页面重新加载时保存MCP应用程序状态
• 使用callTool调用宿主工具：MCP应用程序可以触发主机上的操作
• 尺寸报告：使用 reportSize 用于iframe中的动态内容

项目结构

chat-sdk-playground/
├── pages/                    # Next.js pages
│   ├── index.tsx             # Landing page
│   └── examples/             # Example pages
│       └── chat-sdk/         # Chat SDK examples
│
├── src/
│   ├── components/
│   │   └── layout/
│   │       ├── MainLayout.tsx      # Three-column layout
│   │       ├── ExampleNav.tsx      # Left navigation
│   │       └── DebugPanel.tsx      # Right debug panel
│   │
│   ├── lib/
│   │   └── eventBus.ts            # Centralized event logging
│   │
│   └── styles/
│       └── globals.css            # Global styles and theme
│
├── scripts/
│   └── setup.sh              # Automated setup script
│
├── .env.local               # Generated by setup script (gitignored)
└── package.json

布局

游乐场采用三列布局：

┌─────────────────────────────────────────────────────────────┐
│  [Example Nav]  │  [Main Content]  │  [Debug Panel]         │
│                 │                  │                        │
│  Examples:      │  Example Demo    │  Event Log:            │
│  • Chat Modes   │                  │  🟢 onNewToken         │
│  • Headless UI  │  [Component]     │  🔵 onStepUpdate       │
│  • MCP Apps     │                  │  🟡 toolCall           │
│                 │  Quick Actions:  │  🔴 error              │
└─────────────────────────────────────────────────────────────┘

调试面板

调试面板显示来自SDK交互的实时事件：

• 事件类型：令牌、步骤、工具调用、错误、信息、MCP应用程序
• 过滤器：打开/关闭事件类型
• 自动滚动：自动滚动到最新事件
• 出口：以JSON格式下载事件
• 清除：清除所有事件

环境变量

安装脚本生成 .env.local 对于这些变量：

# User-specific configuration (keep private)
NEXT_PUBLIC_ACCOUNT_ID=
NEXT_PUBLIC_PROJECT_ID=

# Flow IDs (client-side)
NEXT_PUBLIC_BOTDOJO_BASIC_FLOW_ID=
NEXT_PUBLIC_BOTDOJO_MODEL_CONTEXT_FLOW_ID=

# Server-side API key for JWT token generation
# This key is NOT exposed to the browser - tokens are generated server-side
BOTDOJO_MODEL_CONTEXT_API=

脚本

测试

游乐场包括基于Puppeteer的浏览器测试：

# Prerequisites: 
# 1. Install test dependencies (Puppeteer is optional and not installed by default)
npm run install:test-deps

# 2. Dev server must be running
npm run dev  # In one terminal

# 3. Run tests
npm run test  # In another terminal

特殊URL参数：

• ?newsession=true -强制执行新会话（对测试有用）

故障排除

环境变量未加载

Next.js只能读取 .env.local 在启动时。运行安装程序后：

# Restart the dev server
npm run dev

安装脚本失败

确保已安装BotDojo CLI：

npm install -g @botdojo/cli

连接错误

对于本地开发，更新 .env.local 使用本地服务器URL并重新启动开发服务器。

端口3500已在使用中

更改端口 package.json:

"dev": "next dev -p 3600",
"start": "next start -p 3600"

部署

维塞尔

游乐场被配置为在部署过程中跳过可选依赖项（如Puppeteer），通过 vercel.json:

{
  "installCommand": "npm install --no-optional"
}

这使构建时间保持快速，并避免了生产中不必要的依赖关系。

技术栈

• Next.js 13+ -React框架
• TypeScript -类型安全
• @botdojo/聊天sdk -聊天小部件和无头钩子
• @botdojo/sdk -用于流执行的核心SDK
• mcp应用程序视图 -MCP应用程序渲染
• 顺风CSS -造型

贡献

想添加一个新示例吗？

1. 在中创建新页面 pages/examples/chat-sdk/
2. 将路线添加到 EXAMPLES 在 src/components/layout/ExampleNav.tsx
3. 使用事件总线记录事件： eventBus.logInfo(), eventBus.logToken()等等。
4. 包括常见测试场景的快速操作按钮

链接

• BotDojo网站
• 关于代理UI

许可证

MIT© BotDojo