better-chatbot-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

better-chatbot-patterns

better-chatbot-patterns

Status: Production Ready Last Updated: 2025-11-21 Dependencies: None Latest Versions: next@16.0.3, ai@5.0.98, zod@3.24.2, zustand@5.0.8

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

Overview

概述

This skill extracts reusable patterns from the better-chatbot project for use in custom AI chatbot implementations. Unlike the
better-chatbot
skill (which teaches project conventions), this skill provides portable templates you can adapt to any project.
Patterns included:
  1. Server action validators (auth, validation, FormData)
  2. Tool abstraction system (multi-type tool handling)
  3. Multi-AI provider setup
  4. Workflow execution patterns
  5. State management conventions

本技能从better-chatbot项目中提取可复用模式,用于自定义AI聊天机器人实现。与
better-chatbot
技能(教授项目规范)不同,本技能提供可移植模板,可适配任意项目。
包含的模式
  1. 服务器动作验证器(身份验证、数据校验、FormData处理)
  2. 工具抽象系统(多类型工具处理)
  3. 多AI提供商配置
  4. 工作流执行模式
  5. 状态管理规范

Pattern 1: Server Action Validators

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

For complete implementation: Load
references/server-action-patterns.md
when implementing server action validators, auth validation, or FormData parsing.
What it solves: Inconsistent auth checks, repeated FormData parsing boilerplate, non-standard error handling, and type safety issues in server actions.
Three validator patterns:
  1. validatedAction
    - Simple validation (no auth)
  2. validatedActionWithUser
    - With user context (auth required)
  3. validatedActionWithPermission
    - With permission checks (role-based)
Quick example:
typescript
// Server action with automatic auth + validation
export const updateProfile = validatedActionWithUser(
  z.object({ name: z.string(), email: z.string().email() }),
  async (data, formData, user) => {
    // user is authenticated, data is validated
    await db.update(users).set(data).where(eq(users.id, user.id))
    return { success: true }
  }
)
Adapt to your auth: Better Auth, Clerk, Auth.js, or custom auth system.

完整实现参考:当实现服务器动作验证器、身份验证或FormData解析时,加载
references/server-action-patterns.md
解决的问题:服务器动作中身份验证检查不一致、重复的FormData解析样板代码、非标准错误处理以及类型安全问题。
三种验证器模式
  1. validatedAction
    - 简单验证(无需身份验证)
  2. validatedActionWithUser
    - 包含用户上下文(需身份验证)
  3. validatedActionWithPermission
    - 包含权限检查(基于角色)
快速示例
typescript
// 自动集成身份验证+验证的服务器动作
export const updateProfile = validatedActionWithUser(
  z.object({ name: z.string(), email: z.string().email() }),
  async (data, formData, user) => {
    // user已通过身份验证,data已校验完成
    await db.update(users).set(data).where(eq(users.id, user.id))
    return { success: true }
  }
)
适配你的身份验证系统:支持Better Auth、Clerk、Auth.js或自定义身份验证系统。

Pattern 2: Tool Abstraction System

模式2:工具抽象系统

For complete implementation: Load
references/tool-abstraction-patterns.md
when building multi-type tool systems, MCP integration, or extensible tool architectures.
What it solves: Type mismatches at runtime, repeated type checking boilerplate, and difficulty adding new tool types (TypeScript can't enforce runtime types).
How it works: Branded type tags enable runtime type narrowing with full TypeScript safety.
Quick example:
typescript
// Runtime type checking with branded tags
async function executeTool(tool: unknown) {
  if (VercelAIMcpToolTag.isMaybe(tool)) {
    return await tool.execute() // TypeScript knows tool is MCPTool
  } else if (VercelAIWorkflowToolTag.isMaybe(tool)) {
    return await executeWorkflow(tool.nodes) // TypeScript knows tool is WorkflowTool
  }
  throw new Error("Unknown tool type")
}

// Create tagged tools
const mcpTool = VercelAIMcpToolTag.create({
  type: "mcp",
  name: "search",
  execute: async () => { /* ... */ }
})
Extensible: Add new tool types without breaking existing code.

完整实现参考:当构建多类型工具系统、MCP集成或可扩展工具架构时,加载
references/tool-abstraction-patterns.md
解决的问题:运行时类型不匹配、重复的类型检查样板代码,以及添加新工具类型的困难(TypeScript无法强制运行时类型)。
实现原理:通过标记类型标签实现运行时类型收窄,同时保持完整的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("Unknown tool type")
}

// 创建带标记的工具
const mcpTool = VercelAIMcpToolTag.create({
  type: "mcp",
  name: "search",
  execute: async () => { /* ... */ }
})
可扩展性:添加新工具类型无需修改现有代码。

Pattern 3: Multi-AI Provider Setup

模式3:多AI提供商配置

For complete implementation: Load
references/provider-integration-patterns.md
when setting up multi-AI provider support, configuring Vercel AI SDK, or implementing provider fallbacks.
What it solves: Different SDK initialization patterns, provider-specific configurations, and unified interface for switching providers at runtime.
Supported providers: OpenAI, Anthropic (Claude), Google (Gemini), xAI (Grok), Groq.
Quick example:
typescript
// Provider registry in 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 route with user provider selection
export async function POST(req: Request) {
  const { messages, provider, model } = await req.json()
  const selectedModel = getModel(provider, model)

  return streamText({ model: selectedModel, messages }).toDataStreamResponse()
}
Features: Fallback strategies, health checks, cost-aware selection.

完整实现参考:当配置多AI提供商支持、Vercel AI SDK或实现提供商降级策略时,加载
references/provider-integration-patterns.md
解决的问题:不同SDK的初始化模式差异、提供商特定配置,以及运行时切换提供商的统一接口问题。
支持的提供商:OpenAI、Anthropic(Claude)、Google(Gemini)、xAI(Grok)、Groq。
快速示例
typescript
// 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()
}
特性:降级策略、健康检查、成本感知选择。

Pattern 4: State Management (Zustand)

模式4:状态管理(Zustand)

For complete implementation: Load
references/state-validation-patterns.md
when implementing Zustand stores, workflow state, or complex nested state management.
What it solves: Managing complex nested state without mutations, avoiding re-render issues, and preventing state update bugs.
Quick example:
typescript
// Zustand store with shallow update pattern
export const useWorkflowStore = create<WorkflowStore>((set) => ({
  workflow: null,
  // Shallow update - no deep mutation
  updateNodeStatus: (nodeId, status) =>
    set(state => ({
      workflow: state.workflow ? {
        ...state.workflow,
        nodes: state.workflow.nodes.map(node =>
          node.id === nodeId ? { ...node, status } : node
        )
      } : null
    }))
}))
Patterns included: Multi-store organization, Immer integration, persist middleware.

完整实现参考:当实现Zustand存储、工作流状态或复杂嵌套状态管理时,加载
references/state-validation-patterns.md
解决的问题:无需突变即可管理复杂嵌套状态、避免重渲染问题、防止状态更新错误。
快速示例
typescript
// 带浅更新模式的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集成、持久化中间件。

Pattern 5: Cross-Field Validation (Zod)

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

For complete implementation: Load
references/state-validation-patterns.md
when implementing cross-field validation, password confirmation, or date ranges.
What it solves: Validating related fields (password confirmation, date ranges, conditional requirements) with consistent error messages and business rules.
Quick example:
typescript
// Zod superRefine for cross-field validation
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: "Passwords must match"
    })
  }
})
Use cases: Password match, date ranges, conditional fields, business rules, array validation.

完整实现参考:当实现跨字段验证、密码确认或日期范围校验时,加载
references/state-validation-patterns.md
解决的问题:校验关联字段(密码确认、日期范围、条件要求),并提供一致的错误信息和业务规则。
快速示例
typescript
// 使用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: "Passwords must match"
    })
  }
})
适用场景:密码匹配、日期范围、条件字段、业务规则、数组验证。

When to Load References

何时加载参考文档

Load reference files when implementing specific chatbot patterns:
在实现特定聊天机器人模式时加载参考文件:

server-action-patterns.md

server-action-patterns.md

Load when:
  • Pattern-based: Implementing server action validators, auth validation, FormData parsing
  • Auth-based: Setting up authentication checks, user context, permission systems
  • Validation-based: Building form validation, schema validation, error handling
  • Adaptation-based: Adapting patterns to Better Auth, Clerk, Auth.js, or custom auth
加载场景:
  • 模式相关:实现服务器动作验证器、身份验证、FormData解析
  • 身份验证相关:设置身份验证检查、用户上下文、权限系统
  • 验证相关:构建表单验证、Schema校验、错误处理
  • 适配相关:将模式适配到Better Auth、Clerk、Auth.js或自定义身份验证系统

tool-abstraction-patterns.md

tool-abstraction-patterns.md

Load when:
  • Tool-based: Building multi-type tool systems, MCP integration, workflow tools
  • Type-based: Implementing runtime type checking, branded types, type narrowing
  • Execution-based: Creating tool executors, tool dispatchers, extensible tool systems
  • Extension-based: Adding new tool types to existing systems
加载场景:
  • 工具相关:构建多类型工具系统、MCP集成、工作流工具
  • 类型相关:实现运行时类型检查、标记类型、类型收窄
  • 执行相关:创建工具执行器、工具调度器、可扩展工具系统
  • 扩展相关:向现有系统添加新工具类型

provider-integration-patterns.md

provider-integration-patterns.md

Load when:
  • Provider-based: Setting up multi-AI provider support (OpenAI, Anthropic, Google, xAI, Groq)
  • Integration-based: Configuring Vercel AI SDK, provider SDKs, model registries
  • Switching-based: Implementing provider fallbacks, user model selection, dynamic model loading
  • Configuration-based: Managing API keys, base URLs, provider-specific settings
加载场景:
  • 提供商相关:设置多AI提供商支持(OpenAI、Anthropic、Google、xAI、Groq)
  • 集成相关:配置Vercel AI SDK、提供商SDK、模型注册表
  • 切换相关:实现提供商降级、用户模型选择、动态模型加载
  • 配置相关:管理API密钥、基础URL、提供商特定设置

state-validation-patterns.md

state-validation-patterns.md

Load when:
  • State-based: Implementing Zustand stores, workflow state, complex nested state
  • Update-based: Building shallow update patterns, mutation-free updates, state synchronization
  • Validation-based: Creating cross-field validation, password confirmation, date ranges
  • Workflow-based: Managing workflow execution state, node status tracking, dynamic data updates

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

Critical Rules

关键规则

Always Do

必须遵守

✅ Adapt patterns to your auth system (Better Auth, Clerk, Auth.js, etc.) ✅ Use branded type tags for runtime type checking ✅ Use shallow updates for nested Zustand state ✅ Use Zod
superRefine
for cross-field validation ✅ Type your tool abstractions properly
✅ 根据你的身份验证系统(Better Auth、Clerk、Auth.js等)适配模式 ✅ 使用标记类型标签进行运行时类型检查 ✅ 对嵌套Zustand状态使用浅更新 ✅ 使用Zod
superRefine
进行跨字段验证 ✅ 正确为工具抽象添加类型

Never Do

禁止操作

❌ Copy code without adapting to your auth/role system ❌ Assume tool type without runtime check ❌ Mutate Zustand state directly ❌ Use separate validators for related fields ❌ Skip type branding for extensible systems

❌ 未适配你的身份验证/角色系统就直接复制代码 ❌ 未进行运行时检查就假设工具类型 ❌ 直接修改Zustand状态 ❌ 对关联字段使用单独的验证器 ❌ 可扩展系统跳过类型标记

Known Issues Prevention

已知问题预防

This skill prevents 5 common issues:
本技能可预防5种常见问题:

Issue #1: Inconsistent Auth Checks

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

Prevention: Use
validatedActionWithUser
pattern (adapt to your auth)
预防方案:使用
validatedActionWithUser
模式(适配你的身份验证系统)

Issue #2: Tool Type Mismatches

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

Prevention: Use branded type tags with
.isMaybe()
checks
预防方案:使用带
.isMaybe()
检查的标记类型标签

Issue #3: State Mutation Bugs

问题#3:状态突变错误

Prevention: Use shallow Zustand update pattern
预防方案:使用Zustand浅更新模式

Issue #4: Cross-Field Validation Failures

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

Prevention: Use Zod
superRefine
for related fields
预防方案:对关联字段使用Zod
superRefine

Issue #5: Provider Configuration Errors

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

Prevention: Use provider registry with unified interface

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

Using Bundled Resources

使用捆绑资源

Templates (templates/)

模板(templates/)

  • templates/action-utils.ts
    - Complete server action validators
  • templates/tool-tags.ts
    - Complete tool abstraction system
  • templates/providers.ts
    - Multi-AI provider setup
  • templates/workflow-store.ts
    - Zustand workflow store
Copy to your project and adapt placeholders (
getUser()
,
checkPermission()
, etc.)

  • templates/action-utils.ts
    - 完整的服务器动作验证器
  • templates/tool-tags.ts
    - 完整的工具抽象系统
  • templates/providers.ts
    - 多AI提供商配置
  • templates/workflow-store.ts
    - Zustand工作流存储
复制到你的项目中并适配占位符(
getUser()
checkPermission()
等)

Dependencies

依赖项

Required:
  • zod@3.24.2 - Validation (all patterns)
  • zustand@5.0.3 - State management (Pattern 4)
  • ai@5.0.82 - Vercel AI SDK (Pattern 3)
Optional (based on patterns used):
  • @ai-sdk/openai - OpenAI provider
  • @ai-sdk/anthropic - Anthropic provider
  • @ai-sdk/google - Google provider

必需
  • 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提供商

Official Documentation

官方文档

Production Example

生产示例

These patterns are extracted from better-chatbot:
  • Live: https://betterchatbot.vercel.app
  • Tests: 48+ E2E tests passing
  • Errors: 0 (patterns proven in production)
  • Validation: ✅ Multi-user, multi-provider, workflow execution

Token Efficiency: ~65% savings | Errors Prevented: 5 | Production Verified: Yes
这些模式提取自better-chatbot
  • 在线演示https://betterchatbot.vercel.app
  • 测试:48+个端到端测试通过
  • 错误:0(模式已在生产环境验证)
  • 验证:✅ 多用户、多提供商、工作流执行

Token效率:约65%节省 | 预防错误数:5 | 生产验证:是