better-chatbot

better-chatbot 贡献与标准技能

状态：已可用于生产 版本：3.0.0（采用渐进式披露进行优化） 上次更新：2025-12-17 依赖项：无（参考 better-chatbot 项目） 最新版本：Next.js 16.0.3、Vercel AI SDK 5.0.98、Better Auth 1.3.34、Drizzle ORM 0.41.0

---

概述

better-chatbot 是一个面向个人和团队的开源 AI 聊天机器人平台，基于 Next.js 15 和 Vercel AI SDK v5 构建。它将多模型 AI 支持（OpenAI、Anthropic、Google、xAI、Ollama、OpenRouter）与 MCP（Model Context Protocol）工具集成、可视化工作流构建器、实时语音助手和团队协作等高级功能相结合。

此技能向 Claude 传授 better-chatbot 中使用的项目特定约定和模式，确保贡献符合既定标准并避免常见问题。

---

快速入门

设置开发环境

# Clone and install
git clone https://github.com/cgoinglove/better-chatbot.git
cd better-chatbot
pnpm install

# Configure environment
cp .env.example .env
# Add your API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
# Add database URL: DATABASE_URL="postgresql://..."
# Add auth secret: BETTER_AUTH_SECRET="your-secret"

# Run development server
pnpm dev

核心命令

• pnpm dev - 启动开发服务器
• pnpm build - 生产构建
• pnpm test - 运行单元测试
• pnpm test:e2e - 运行 E2E 测试（需要数据库和 API 密钥）
• pnpm check - 代码检查 + 类型检查 + 测试（提交 PR 前运行）

仓库结构

better-chatbot/
├── src/
│   ├── app/                # Next.js routes + API
│   ├── components/         # UI components by domain
│   ├── lib/               # Core logic (ai, db, validations)
│   ├── hooks/             # React hooks
│   └── types/             # TypeScript types
├── tests/                 # E2E Playwright tests
└── drizzle/              # Database migrations

---

核心架构

三层工具系统

Better-chatbot 使用三层工具架构来实现 AI 功能：

1. MCP 工具 - 通过 Model Context Protocol 提供的外部工具
2. 工作流工具 - 基于可视化 DAG 的工作流
3. 默认工具 - 内置应用工具（网页搜索、图像生成等）

详情：实现工具或了解工具执行时，加载 references/tool-system.md。

API 模式

路由遵循 RESTful 约定，采用流式优先架构，并通过 safe() 包装器进行防御式编程。

详情：构建 API 路由或实现流式处理时，加载 references/api-architecture.md。

组件理念

组件按功能组织，并采用复合组件模式。工具执行与渲染相分离。

详情：构建 UI 组件时，加载 references/component-patterns.md。

数据库与仓库模式

所有数据库访问均通过使用 Drizzle ORM 的仓库类进行抽象。

详情：实现数据库查询时，加载 references/database-patterns.md。

---

最常见的 5 个错误（必须了解）

错误 #1：忘记在服务器操作中进行身份验证检查

错误：未授权用户访问受保护的操作 原因：手动实现身份验证的方式不一致 预防：使用 validatedActionWithUser 或 validatedActionWithAdminPermission

// ❌ BAD: Manual auth check
export async function updateProfile(data: ProfileData) {
  const session = await getSession()
  if (!session) throw new Error("Unauthorized")
  // ... rest of logic
}

// ✅ GOOD: Use validator
export const updateProfile = validatedActionWithUser(
  profileSchema,
  async (data, formData, user) => {
    // user is guaranteed to exist, auto-error handling
  }
)

错误 #2：工具类型不匹配

错误：执行工具时发生运行时类型错误 原因：执行前未检查工具类型 预防：使用品牌类型标签进行运行时类型缩窄

// ❌ BAD: Assuming tool type
const result = await executeMcpTool(tool)

// ✅ GOOD: Check tool type
if (VercelAIMcpToolTag.isMaybe(tool)) {
  const result = await executeMcpTool(tool)
} else if (VercelAIWorkflowToolTag.isMaybe(tool)) {
  const result = await executeWorkflowTool(tool)
}

错误 #3：FormData 解析错误

错误：表单提交的错误处理不一致 原因：手动解析 FormData 并采用临时验证方式 预防：验证器会自动处理解析

// ❌ BAD: Manual parsing
const name = formData.get("name") as string
if (!name) throw new Error("Name required")

// ✅ GOOD: Validator with Zod
const schema = z.object({ name: z.string().min(1) })
export const action = validatedAction(schema, async (data) => {
  // data.name is validated and typed
})

错误 #4：跨字段验证问题

错误：密码不匹配验证不起作用 原因：分别验证相关字段 预防：使用 Zod superRefine

// ❌ BAD: Separate checks
if (data.password !== data.confirmPassword) { /* error */ }

// ✅ GOOD: Zod superRefine
const schema = z.object({
  password: z.string(),
  confirmPassword: z.string()
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Passwords don't match",
      path: ["confirmPassword"]
    })
  }
})

错误 #5：Zustand 状态变更

错误：状态更新未触发重新渲染 原因：直接修改状态，而不是创建新对象 预防：使用展开运算符进行浅层更新

// ❌ BAD: Direct mutation
set((state) => {
  state.user.name = "New Name" // Mutation!
})

// ✅ GOOD: Shallow update
set((state) => ({
  user: { ...state.user, name: "New Name" }
}))

查看所有错误：排查前 5 个常见错误之外的问题时，加载 references/common-errors.md。

---

关键规则

始终执行

✅ 对服务端操作使用 validatedActionWithUser 或 validatedActionWithAdminPermission ✅ 执行前使用品牌类型标签检查工具类型 ✅ 使用 Zod superRefine 进行跨字段校验 ✅ 添加单元测试（正常路径 + 一种失败情况） ✅ 提交 PR 前运行 pnpm check ✅ UI 有变更时，附上可视化文档 ✅ PR 标题使用 Conventional Commit 格式 ✅ 修改关键流程时运行 E2E 测试

绝不执行

❌ 不使用身份验证校验器就实现服务端操作 ❌ 未经运行时检查就假定工具类型 ❌ 手动解析 FormData（使用校验器） ❌ 直接修改 Zustand 状态（使用浅层更新） ❌ 跳过干净数据库上的首位用户测试 ❌ 未运行 pnpm check 就提交 ❌ UI 有变更时，未附上可视化文档就提交 PR ❌ 使用非 Conventional Commit 格式

---

何时加载参考资料

在处理 better-chatbot 的特定方面时，加载相应的参考文件：

API 架构（references/api-architecture.md）

在以下情况下加载：

• 实现新的 API 路由或端点
• 了解路由处理程序模式
• 处理流式响应
• 使用 safe() 实现防御式编程
• 排查 API 相关问题
• 构建共享业务逻辑

工具系统（references/tool-system.md）

在以下情况下加载：

• 添加新的 MCP 工具
• 创建工作流工具
• 了解工具生命周期
• 调试工具执行
• 实现工具筛选或提及功能
• 处理三层工具架构

组件模式（references/component-patterns.md）

在以下情况下加载：

• 构建新的 UI 组件
• 了解复合组件模式
• 实现状态管理
• 使用 Zustand store
• 设计组件 API
• 将工具执行与渲染分离

数据库模式（references/database-patterns.md）

在以下情况下加载：

• 创建新的 repository 类
• 编写复杂数据库查询
• 实现事务
• 了解 repository 模式
• 排查数据库问题
• 使用 Drizzle ORM

架构原则（references/architectural-principles.md）

在以下情况下加载：

• 做出架构决策
• 了解设计理念
• 实现渐进增强
• 遵循流式优先模式
• 确保防御式编程
• 了解 DRY 原则的应用

扩展点（references/extension-points.md）

在以下情况下加载：

• 使用自定义功能扩展聊天机器人
• 添加新的工具类型
• 自定义现有行为
• 了解插件架构
• 集成外部服务

UX 模式（references/ux-patterns.md）

在以下情况下加载：

• 实现 @mention 功能
• 了解 UX 模式
• 使用多模型支持
• 设计交互流程
• 构建聊天 UI 组件

模板（references/templates.md）

在以下情况下加载：

• 添加新的路由、工具或组件
• 遵循代码模板
• 了解完整的实现示例
• 从头开始开发新功能
• 实现标准模式

服务端操作（references/server-actions.md）

在以下情况下加载：

• 实现服务端操作
• 了解操作校验器
• 遵循服务端校验模式
• 排查服务端操作问题
• 使用 FormData

常见错误（references/common-errors.md）

在以下情况下加载：

• 调试超出前 5 大错误范围的问题
• 遇到特定错误消息
• 了解错误模式
• 查找常见问题的解决方案
• 预防已知问题

仓库指南（references/AGENTS.md）

在以下情况下加载：

• 了解项目结构
• 遵循编码规范
• 设置开发环境
• 运行测试或构建
• 了解提交/PR 指南

贡献指南（references/CONTRIBUTING.md）

在以下情况下加载：

• 准备贡献
• 了解 PR 流程
• 遵循提交消息规范
• 提交拉取请求
• 添加可视化文档

---

使用捆绑资源

此技能包含 12 个参考文件：

技术参考（10 个文件）：

• api-architecture.md - API 模式和路由处理程序
• tool-system.md - 三层工具架构
• component-patterns.md - UI 组件设计
• database-patterns.md - Repository 模式和 Drizzle ORM
• architectural-principles.md - 设计理念
• extension-points.md - 如何扩展系统
• ux-patterns.md - UX 模式和 @mentions
• templates.md - 路由/工具/组件的代码模板
• server-actions.md - 服务端操作验证器
• common-errors.md - 完整错误目录

仓库参考（2 个文件）：

• AGENTS.md - 仓库结构和开发命令
• CONTRIBUTING.md - 贡献工作流和 PR 指南

在需要特定知识时按需加载参考文件。触发条件请参见“何时加载参考文件”部分。

---

依赖项

核心：

• Next.js 15+（App Router）
• Vercel AI SDK 5+
• Better Auth 1.3+
• Drizzle ORM 0.40+
• PostgreSQL

测试：

• Vitest（单元测试）
• Playwright（E2E 测试）

工具：

• TypeScript 5+
• Biome（格式化 + lint）
• pnpm 8+

---

官方文档

• 仓库：https://github.com/cgoinglove/better-chatbot
• Vercel AI SDK：https://sdk.vercel.ai/docs
• Better Auth：https://www.better-auth.com/docs
• Drizzle ORM：https://orm.drizzle.team/docs/overview
• MCP 规范：https://modelcontextprotocol.io/introduction

---

生产示例

此技能基于生产环境中的 better-chatbot 仓库，其中包含 48 个 E2E 测试，涵盖核心功能、活跃开发和不断壮大的社区贡献。

---

最后验证时间：2025-12-17 | 版本：3.0.0