名称: better-chatbot-patterns 描述: 可重用的更好聊天机器人模式，用于自定义部署。用于服务器动作验证器、工具抽象、多AI提供商，或遇到身份验证验证、FormData解析、工作流执行错误时。关键词: AI聊天机器人模式、服务器动作验证器、工具抽象、多AI提供商、工作流执行、MCP集成、已验证动作、工具类型检查、Vercel AI SDK模式、聊天机器人架构许可证: MIT 元数据: 版本: 1.0.0 作者: Claude Skills Maintainers 基于: https://github.com/cgoinglove/better-chatbot 最后验证: 2025-10-29 技术栈: Next.js 15, Vercel AI SDK 5, Zod, Zustand 令牌节省: ~65% 预防错误: 5

better-chatbot-patterns

状态: 生产就绪 最后更新: 2025-11-21 依赖项: 无 最新版本: next@16.0.3, ai@5.0.98, zod@3.24.2, zustand@5.0.8

概述

此技能从better-chatbot项目中提取可重用的模式，用于自定义AI聊天机器人实现。与better-chatbot技能（教授项目约定）不同，此技能提供可移植的模板，您可以在任何项目中适应。

包含的模式:

服务器动作验证器（身份验证、验证、FormData）
工具抽象系统（多类型工具处理）
多AI提供商设置
工作流执行模式
状态管理约定

模式1: 服务器动作验证器

用于完整实现: 在实现服务器动作验证器、身份验证验证或FormData解析时，加载references/server-action-patterns.md。

解决的问题: 不一致的身份验证检查、重复的FormData解析样板、非标准错误处理，以及服务器动作中的类型安全问题。

三个验证器模式:

validatedAction - 简单验证（无身份验证）
validatedActionWithUser - 带用户上下文（需要身份验证）
validatedActionWithPermission - 带权限检查（基于角色）

快速示例:

// 带自动身份验证 + 验证的服务器动作
export const updateProfile = validatedActionWithUser(
  z.object({ name: z.string(), email: z.string().email() }),
  async (data, formData, user) => {
    // 用户已认证，数据已验证
    await db.update(users).set(data).where(eq(users.id, user.id))
    return { success: true }
  }
)

适应您的身份验证系统: Better Auth、Clerk、Auth.js 或自定义身份验证系统。

模式2: 工具抽象系统

用于完整实现: 在构建多类型工具系统、MCP集成或可扩展工具架构时，加载references/tool-abstraction-patterns.md。

解决的问题: 运行时的类型不匹配、重复的类型检查样板，以及难以添加新工具类型（TypeScript无法在运行时强制类型）。

工作原理: 使用品牌化类型标签实现运行时类型窄化，并保持完整的TypeScript安全性。

快速示例:

// 带品牌化标签的运行时类型检查
async function executeTool(tool: unknown) {
  if (VercelAIMcpToolTag.isMaybe(tool)) {
    return await tool.execute() // TypeScript知道tool是MCPTool
  } else if (VercelAIWorkflowToolTag.isMaybe(tool)) {
    return await executeWorkflow(tool.nodes) // TypeScript知道tool是WorkflowTool
  }
  throw new Error("未知工具类型")
}

// 创建带标签的工具
const mcpTool = VercelAIMcpToolTag.create({
  type: "mcp",
  name: "search",
  execute: async () => { /* ... */ }
})

可扩展性: 添加新工具类型而不破坏现有代码。

模式3: 多AI提供商设置

用于完整实现: 在设置多AI提供商支持、配置Vercel AI SDK或实现提供商回退时，加载references/provider-integration-patterns.md。

解决的问题: 不同的SDK初始化模式、提供商特定配置，以及运行时切换提供商的统一接口。

支持的提供商: OpenAI、Anthropic (Claude)、Google (Gemini)、xAI (Grok)、Groq。

快速示例:

// 提供商注册表在lib/ai/providers.ts中
export const providers = {
  openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  anthropic: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  google: createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_API_KEY })
}

// 带用户提供商选择的API路由
export async function POST(req: Request) {
  const { messages, provider, model } = await req.json()
  const selectedModel = getModel(provider, model)

  return streamText({ model: selectedModel, messages }).toDataStreamResponse()
}

功能: 回退策略、健康检查、成本感知选择。

模式4: 状态管理 (Zustand)

用于完整实现: 在实现Zustand存储、工作流状态或复杂嵌套状态管理时，加载references/state-validation-patterns.md。

解决的问题: 管理复杂嵌套状态而不发生突变，避免重新渲染问题，并防止状态更新错误。

快速示例:

// 带浅更新模式的Zustand存储
export const useWorkflowStore = create<WorkflowStore>((set) => ({
  workflow: null,
  // 浅更新 - 无深度突变
  updateNodeStatus: (nodeId, status) =>
    set(state => ({
      workflow: state.workflow ? {
        ...state.workflow,
        nodes: state.workflow.nodes.map(node =>
          node.id === nodeId ? { ...node, status } : node
        )
      } : null
    }))
}))

包含的模式: 多存储组织、Immer集成、持久化中间件。

模式5: 跨字段验证 (Zod)

用于完整实现: 在实现跨字段验证、密码确认或日期范围时，加载references/state-validation-patterns.md。

解决的问题: 验证相关字段（密码确认、日期范围、条件要求），并提供一致的错误消息和业务规则。

快速示例:

// 用于跨字段验证的Zod superRefine
const passwordSchema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string()
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      path: ["confirmPassword"],
      code: z.ZodIssueCode.custom,
      message: "密码必须匹配"
    })
  }
})

使用案例: 密码匹配、日期范围、条件字段、业务规则、数组验证。

何时加载参考文件

在实现特定聊天机器人模式时加载参考文件：

server-action-patterns.md

加载当：

基于模式: 实现服务器动作验证器、身份验证验证、FormData解析
基于身份验证: 设置身份验证检查、用户上下文、权限系统
基于验证: 构建表单验证、模式验证、错误处理
基于适应: 适应模式到Better Auth、Clerk、Auth.js或自定义身份验证

tool-abstraction-patterns.md

加载当：

基于工具: 构建多类型工具系统、MCP集成、工作流工具
基于类型: 实现运行时类型检查、品牌化类型、类型窄化
基于执行: 创建工具执行器、工具分发器、可扩展工具系统
基于扩展: 向现有系统添加新工具类型

provider-integration-patterns.md

加载当：

基于提供商: 设置多AI提供商支持（OpenAI、Anthropic、Google、xAI、Groq）
基于集成: 配置Vercel AI SDK、提供商SDK、模型注册表
基于切换: 实现提供商回退、用户模型选择、动态模型加载
基于配置: 管理API密钥、基础URL、提供商特定设置

state-validation-patterns.md

加载当：

基于状态: 实现Zustand存储、工作流状态、复杂嵌套状态
基于更新: 构建浅更新模式、无突变更新、状态同步
基于验证: 创建跨字段验证、密码确认、日期范围
基于工作流: 管理工作流执行状态、节点状态跟踪、动态数据更新

关键规则

总是做

✅ 适应模式到您的身份验证系统（Better Auth、Clerk、Auth.js等） ✅ 使用品牌化类型标签进行运行时类型检查 ✅ 使用浅更新处理嵌套Zustand状态 ✅ 使用Zod superRefine进行跨字段验证 ✅ 正确类型化您的工具抽象

永远不要做

❌ 复制代码而不适应到您的身份验证/角色系统 ❌ 未经运行时检查假设工具类型 ❌ 直接突变Zustand状态 ❌ 对相关字段使用单独的验证器 ❌ 跳过可扩展系统的类型品牌化

预防已知问题

此技能预防5个常见问题：

问题 #1: 不一致的身份验证检查

预防: 使用validatedActionWithUser模式（适应到您的身份验证）

问题 #2: 工具类型不匹配

预防: 使用带.isMaybe()检查的品牌化类型标签

问题 #3: 状态突变错误

预防: 使用Zustand浅更新模式

问题 #4: 跨字段验证失败

预防: 使用Zod superRefine处理相关字段

问题 #5: 提供商配置错误

预防: 使用带统一接口的提供商注册表

使用捆绑资源

模板 (templates/)

templates/action-utils.ts - 完整的服务器动作验证器
templates/tool-tags.ts - 完整的工具抽象系统
templates/providers.ts - 多AI提供商设置
templates/workflow-store.ts - Zustand工作流存储

复制到您的项目并适应占位符（getUser()、checkPermission()等）

依赖项

必需:

zod@3.24.2 - 验证（所有模式）
zustand@5.0.3 - 状态管理（模式4）
ai@5.0.82 - Vercel AI SDK（模式3）

可选（基于使用的模式）：

@ai-sdk/openai - OpenAI提供商
@ai-sdk/anthropic - Anthropic提供商
@ai-sdk/google - Google提供商

官方文档

Vercel AI SDK: https://sdk.vercel.ai/docs
Zod: https://zod.dev
Zustand: https://zustand-demo.pmnd.rs
better-chatbot (源代码): https://github.com/cgoinglove/better-chatbot

生产示例

这些模式从better-chatbot中提取：

在线: https://betterchatbot.vercel.app
测试: 48+ E2E测试通过
错误: 0（模式在生产中验证）
验证: ✅ 多用户、多提供商、工作流执行

令牌效率: ~65% 节省 | 预防错误: 5 | 生产验证: 是