⚡

better-chatbot贡献标准技能 better-chatbot

此技能用于教导Claude better-chatbot项目的具体惯例和模式，帮助贡献代码、遵循三层工具系统（MCP/工作流/默认工具）、避免常见错误如服务器动作验证器和仓库模式错误。关键词：better-chatbot, chatbot贡献, AI聊天机器人, Next.js, Vercel AI SDK, MCP工具, 工作流构建器, 架构设计, 防御性编程, 流式优先。

架构设计 0 次安装 0 次浏览 更新于 3/8/2026

name: better-chatbot description: better-chatbot项目惯例和标准。用于贡献代码、遵循三层工具系统（MCP/工作流/默认工具），或遇到服务器动作验证器、仓库模式、组件设计错误。

关键词：better-chatbot, chatbot贡献, better-chatbot标准, chatbot开发, AI聊天机器人模式, API架构, 三层工具系统, 仓库模式, 渐进增强, 防御性编程, 流式优先, 复合组件模式, Next.js聊天机器人, Vercel AI SDK聊天机器人, MCP工具, 工作流构建器, 服务器动作验证器, 工具抽象, DAG工作流, 共享业务逻辑, safe()包装器, 工具生命周期 license: MIT metadata: version: 3.0.0 author: Claude Skills Maintainers upstream: https://github.com/cgoinglove/better-chatbot last_verified: 2025-12-17 tech_stack: Next.js 15, Vercel AI SDK 5, Better Auth, Drizzle ORM, PostgreSQL, Playwright token_savings: ~75% errors_prevented: 8 optimization_date: 2025-12-17

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（模型上下文协议）工具集成、可视化工作流构建器、实时语音助手和团队协作。

此技能教导Claude项目特定的惯例和模式，用于确保贡献遵循既定标准并避免常见陷阱。

快速开始

设置开发环境

# 克隆并安装
git clone https://github.com/cgoinglove/better-chatbot.git
cd better-chatbot
pnpm install

# 配置环境
cp .env.example .env
# 添加您的API密钥：OPENAI_API_KEY, ANTHROPIC_API_KEY等。
# 添加数据库URL：DATABASE_URL="postgresql://..."
# 添加认证密钥：BETTER_AUTH_SECRET="your-secret"

# 运行开发服务器
pnpm dev

核心命令

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

仓库结构

better-chatbot/
├── src/
│   ├── app/                # Next.js路由和API
│   ├── components/         # 按领域的UI组件
│   ├── lib/               # 核心逻辑（AI、数据库、验证）
│   ├── hooks/             # React钩子
│   └── types/             # TypeScript类型
├── tests/                 # E2E Playwright测试
└── drizzle/              # 数据库迁移

核心架构

三层工具系统

Better-chatbot使用三层工具架构用于AI能力：

  1. MCP工具 - 通过模型上下文协议的外部工具
  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。

前五大错误（必须知道）

错误 #1: 服务器动作中忘记认证检查

错误: 未经授权的用户访问受保护的动作 原因: 手动认证实现不一致 预防: 使用 validatedActionWithUser 或 validatedActionWithAdminPermission

// ❌ 错误: 手动认证检查
export async function updateProfile(data: ProfileData) {
  const session = await getSession()
  if (!session) throw new Error("Unauthorized")
  // ... 其余逻辑
}

// ✅ 正确: 使用验证器
export const updateProfile = validatedActionWithUser(
  profileSchema,
  async (data, formData, user) => {
    // user保证存在，自动错误处理
  }
)

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

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

// ❌ 错误: 假设工具类型
const result = await executeMcpTool(tool)

// ✅ 正确: 检查工具类型
if (VercelAIMcpToolTag.isMaybe(tool)) {
  const result = await executeMcpTool(tool)
} else if (VercelAIWorkflowToolTag.isMaybe(tool)) {
  const result = await executeWorkflowTool(tool)
}

错误 #3: FormData解析错误

错误: 表单提交的错误处理不一致 原因: 手动FormData解析和临时验证 预防: 验证器自动处理解析

// ❌ 错误: 手动解析
const name = formData.get("name") as string
if (!name) throw new Error("Name required")

// ✅ 正确: 使用Zod验证器
const schema = z.object({ name: z.string().min(1) })
export const action = validatedAction(schema, async (data) => {
  // data.name已验证和类型化
})

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

错误: 密码不匹配验证不起作用 原因: 相关字段的单独验证 预防: 使用Zod superRefine

// ❌ 错误: 单独检查
if (data.password !== data.confirmPassword) { /* error */ }

// ✅ 正确: 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: "密码不匹配",
      path: ["confirmPassword"]
    })
  }
})

错误 #5: Zustand状态突变

错误: 状态更新未触发重新渲染 原因: 直接突变状态而非创建新对象 预防: 使用扩展运算符进行浅层更新

// ❌ 错误: 直接突变
set((state) => {
  state.user.name = "New Name" // 突变！
})

// ✅ 正确: 浅层更新
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 就提交 ❌ 提交PR无可视化文档（如果是UI更改） ❌ 使用非Conventional Commit格式

何时加载参考文献

在better-chatbot的特定方面工作时加载参考文献：

API架构 (references/api-architecture.md)

加载时机：

  • 实现新的API路由或端点
  • 理解路由处理器模式
  • 处理流式响应
  • 实现防御性编程与safe()
  • 故障排除API相关问题
  • 构建共享业务逻辑

工具系统 (references/tool-system.md)

加载时机：

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

组件模式 (references/component-patterns.md)

加载时机：

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

数据库模式 (references/database-patterns.md)

加载时机：

  • 创建新的仓库类
  • 编写复杂数据库查询
  • 实现事务
  • 理解仓库模式
  • 故障排除数据库问题
  • 处理Drizzle ORM

架构原则 (references/architectural-principles.md)

加载时机：

  • 进行架构决策
  • 理解设计哲学
  • 实现渐进增强
  • 遵循流式优先模式
  • 确保防御性编程
  • 理解DRY原则应用

扩展点 (references/extension-points.md)

加载时机：

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

UX模式 (references/ux-patterns.md)

加载时机：

  • 实现@提及功能
  • 理解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 - 仓库模式和Drizzle ORM
  • architectural-principles.md - 设计哲学
  • extension-points.md - 如何扩展系统
  • ux-patterns.md - UX模式和@提及
  • 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（格式化和代码检查）
  • pnpm 8+

官方文档

生产示例

此技能基于生产better-chatbot仓库，包含48个E2E测试覆盖核心功能、积极开发和不断增长的社区贡献。

最后验证: 2025-12-17 | 版本: 3.0.0