# better-chatbot 贡献和标准技能 **状态**：生产就绪 **最后更新**：2025-11-04（v2.1.0 - 添加扩展点 + UX 模式） **依赖项**：无（引用 better-chatbot 项目） **最新版本**：Next.js 15.3.2、Vercel AI SDK 5.0.82、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 在更好的聊天机器人中使用的特定于项目的约定和模式**，以确保贡献遵循既定标准并避免常见陷阱。 ** ** ## 项目架构 ### 目录结构更好的聊天机器人/ ├── src/ │ ├── app/ # Next.js App Router + API 路由 │ │ ├── api/[resource]/ # 按域组织的 RESTful API │ │ ├── (auth)/ # 认证路由组 │ │ ├── (聊天)/ # 聊天UI路由组 │ │ └── 商店/ # Zustand 商店 │ ├── Components/ # 按领域划分的 UI 组件 │ │ ├── 布局/ │ │ ├── 代理/ │ │ ├── 聊天/ │ │ └── 出口/ │ ├── lib/ # 核心逻辑和实用程序 │ │ ├── action-utils.ts # 服务器动作验证器（关键） │ │ ├── ai/ # AI 集成（模型、工具、MCP、语音） │ │ ├── db/ # 数据库（Drizzle ORM + 存储库） │ │ ├── 验证/ # Zod 模式 │ │ └── [domain]/ # 特定于域的助手 │ ├── hooks/ # 自定义 React 钩子 │ │ ├── requests/ # 数据获取钩子 │ │ └── 使用-*.ts │ └── types/ # 按域划分的 TypeScript 类型 ├── 测试/ # E2E 测试（剧作家） ├── docs/ # 设置指南和提示 ├── docker/ # Docker 配置 └── drizzle/ # 数据库迁移 ** ** ## API 架构和设计模式 ### 路线结构理念 **约定**：具有 Next.js App Router 约定的 RESTful 资源 /api/[resource]/route.ts → GET/POST 收集端点 /api/[resource]/[id]/route.ts → GET/PUT/DELETE 项目端点 /api/[resource]/actions.ts → 服务器操作（突变） ### 标准路由处理程序模式 **位置**：`src/app/api/` **模板结构**：导出异步函数 POST(request: Request) { 尝试{ // 1. 使用 Zod 解析并验证请求体 const json = 等待 request.json(); const 解析 = zodSchema.parse(json); // 2. 检查身份验证 const 会话 = 等待 getSession(); if (!session?.user.id) return new Response("未经授权", { status: 401 }); // 3. 检查授权（所有权/权限） if (resource.userId !== session.user.id) return new Response("Forbidden", { status: 403 }); // 4. 加载/组合依赖项（工具、上下文等） const 工具 = 等待 loadMcpTools({ 提及, allowedMcpServers }); // 5. 如果适用，使用流式执行 const Stream = createUIMessageStream({ 执行: async ({ writer }) => { ... } }); // 6. 返回响应返回 createUIMessageStreamResponse({ 流 }); } 捕获（错误）{ 记录器.错误（错误）；返回 Response.json({ 消息: error.message }, { 状态: 500 }); } } ### 共享业务逻辑模式 **关键见解**：将复杂的编排逻辑提取到共享实用程序中 **示例**：`src/app/api/chat/shared.chat.ts` 该文件演示了如何处理： * 工具加载（`loadMcpTools`、`loadWorkFlowTools`、`loadAppDefaultTools`） * 过滤和组合（`filterMCPToolsByMentions`、`excludeToolExecution`） * 系统提示构建(`mergeSystemPrompt`) * 手动工具执行处理 **图案**： // 共享实用函数导出常量 loadMcpTools = (opt?) => 安全(() => mcpClientsManager.tools()) .map((工具) => { if (opt?.mentions?.length) { 返回filterMCPToolsByMentions（工具，opt.mentions）； } 返回filterMCPToolsByAllowedMCPServers(tools, opt?.allowedMcpServers); }) .orElse({} as Record); // 在多个路由中使用 // - /api/chat/route.ts // - /api/chat/temporary/route.ts // - /api/workflow/[id]/execute/route.ts **为什么**：DRY 原则、单一事实来源、一致的行为 ### 使用 safe() 进行防御性编程 **库**：用于功能错误处理的“ts-safe” **理念**：永远不要让聊天崩溃 - 优雅地降级功能 // 失败时返回空对象，聊天继续 const MCP_TOOLS = 等待安全() .map(errorIf(() => !isToolCallAllowed && "不允许")) .map(() => loadMcpTools({ 提及, allowedMcpServers })) .orElse({}); // 优雅的回退 ### 流优先架构 **模式**：使用 Vercel AI SDK 流实用程序 // 在路由处理程序中 const 流 = createUIMessageStream({ 执行： async ({ writer }) => { // 流式传输中间结果 writer.write({ type: "text", content: "正在处理..." }); // 使用流式执行常量结果=等待streamText({ 模型, 消息，工具， onChunk: (chunk) => writer.write({ type: "text-delta", delta: chunk }) }); 返回{输出：结果}； } }); 返回 createUIMessageStreamResponse({ 流 }); **为什么**：实时反馈、更好的用户体验、处理长时间运行的操作 ** ** ## 工具系统深入探讨 ### 三层工具架构 **设计目标**：平衡可扩展性（MCP）、可组合性（工作流程）和包含电池（默认工具）第 1 层：MCP 工具（外部） ↓ 可用于第 2 层：工作流程工具（用户创建） ↓ 可用于第 3 层：默认工具（内置） ### 第 1 层：MCP 工具（外部集成） **位置**：`src/lib/ai/mcp/` **理念**：模型上下文协议服务器成为一流的工具 **经理模式**： // mcp-manager.ts - 所有 MCP 客户端的单例导出 const mcpClientsManager = globalThis.__mcpClientsManager__; // API: mcpClientsManager.init() // 初始化配置的服务器 mcpClientsManager.getClients() // 获取连接的客户端 mcpClientsManager.tools() // 获取所有工具作为 Vercel AI SDK 工具 mcpClientsManager.toolCall(serverId, toolName, args) // 执行工具 **为什么选择全局单例？** * Next.js 开发热重载 → 每次更改时重新连接 MCP 服务器的成本很高 * 在 HMR 更新中持续存在 * 生产：只需要一个实例 **工具包装**： // MCP 工具用元数据标记以进行过滤类型 VercelAIMcpTool = 工具 & { _mcpServerId：字符串； _originToolName：字符串； _工具名称：字符串； // 转化为AI SDK }; // 用于运行时检查的品牌类型 VercelAIMcpToolTag.create(工具) ### 第 2 层：工作流程工具（视觉合成） **位置**：`src/lib/ai/workflow/` **理念**：可视化工作流程通过“@workflow_name”成为可调用工具 **节点类型**：枚举 NodeKind { input = "输入", // 入口点 LLM = "llm", // 人工智能推理 Tool = "tool", // 调用 MCP/默认工具 Http = "http", // HTTP 请求 Template = "模板",//文本处理 Condition = "condition", // 分支逻辑 Output = "output", // 退出点 } **使用流式执行**： // 工作流传输中间结果执行者.subscribe((e) => { if (e.eventType == "NODE_START") { 数据流.write({ 类型：“工具输出可用”，工具调用Id, 输出：{ 状态：“正在运行”，节点：e.nodeId } }); } if (e.eventType == "NODE_END") { 数据流.write({ 类型：“工具输出可用”，工具调用Id, 输出：{ 状态：“完成”，结果：e.result } }); } }); **主要功能**：聊天 UI 中实时更新进度 ### 第 3 层：默认工具（内置功能） **位置**：`src/lib/ai/tools/` **类别**：导出常量 APP_DEFAULT_TOOL_KIT = { [AppDefaultToolkit.Visualization]：{ 创建饼图、创建条形图、创建折线图、创建表、创建时间线 }, [AppDefaultToolkit.WebSearch]：{ 网络搜索、网络内容 }, [AppDefaultToolkit.Http]: { HTTP }, [AppDefaultToolkit.Code]: { Javascript执行、Python执行 }, }; **工具实现模式**： // 执行返回“成功”，渲染发生在客户端导出 const createTableTool = createTool({ 描述：“创建一个交互式表格...”，输入模式： z.object({ 标题: z.string(), 列： z.array(...), 数据：z.array(...) }), 执行：async() =>“成功” }); // 在组件/工具调用/中进行客户端渲染导出函数 InteractiveTable({ 部分 }) { const args = 部分.输入；返回 ; } **为什么要分开？** * 服务器：纯数据/业务逻辑 * 客户端：丰富的可视化/交互 * 更简单的测试，更好的性能 ### 工具生命周期 1. 请求 → /api/chat/route.ts 2. 解析提及（@tool、@workflow、@agent） 3. 根据提及/权限加载工具： - loadMcpTools() → 按提及或 allowedMcpServers 进行过滤 - loadWorkFlowTools() → 将工作流程转换为工具 - loadAppDefaultTools() → 过滤默认工具包 4. 将所有工具合并为单个 Record 5.处理工具选择方式： - “手册”→LLM提出，用户确认 - “自动”→ 完全执行 - “无”→ 未加载工具 6. 将工具传递给streamText() 7. 返回结果 ### 基于约定的扩展 **添加新工具类型很简单**： 1. 将枚举添加到`AppDefaultToolkit` 2. 使用`createTool()`实现工具 3. 添加“APP_DEFAULT_TOOL_KIT” 4. 通过“@toolname”自动提供工具 ** ** ## 组件和设计理念 ### 按功能组织 **位置**：`src/components/` 组件/ ├── ui/ → shadcn/ui 原语 ├── 布局/ → 应用程序结构 ├── 代理/ → 代理特定 ├── 工作流程/ → 工作流程编辑器 ├── 工具调用/ → 工具结果渲染 └── *.tsx → 共享组件 **原则**：按功能分组，而不是按类型分组 ### 复合组件模式 **示例** : `message.tsx` \+ `message-parts.tsx` **哲学**：将复杂的组件分解为可组合的部分 // message.tsx 导出多个相关组件导出函数 PreviewMessage({ message }) { ... } 导出函数 ErrorMessage({ 错误 }) { ... } // message-parts.tsx 处理多态内容导出函数 MessageParts({ parts }) { 返回 parts.map(part => { if (isToolUIPart(part)) return ; if (part.type === 'text') return ; // ...其他类型 }); } ### 客户端组件包装模式 **示例**：`chat-bot.tsx` **结构**：导出默认函数 ChatBot({ threadId, initialMessages }) { // 1. 状态管理（Zustand） const [模型，toolChoice] = appStore(useShallow(state => [...])); // 2. Vercel AI SDK 挂钩 const { 消息、附加、状态 } = useChat({ id：线程ID，初始消息， body: { chatModel: 模型, toolChoice }, }); // 3. 渲染编排返回（ <> <聊天问候语/> ）； } **为什么**：顶级编排，将渲染委托给专门的组件 ### 工具结果渲染分离 **关键架构决策**： * 工具 **执行** 位于 `lib/ai/tools/` * 工具 **渲染** 位于 `components/tool-incalling/` 中 **示例**： // 服务器端 (lib/ai/tools/create-table.ts) 执行：异步（参数）=>“成功” // 客户端 (组件/工具调用/interactive-table.tsx) 导出函数 InteractiveTable({ 部分 }) { const { 列，数据 } = 部分.输入；返回 ; } **好处**： * 清晰的关注点分离 * 更容易测试 * 客户端可以是丰富的/交互式的，而不需要服务器的复杂性 ** ** ## 数据库和存储库模式 ### 存储库模式架构 **位置**：`src/lib/db/` **结构**：分贝/ ├──repository.ts→单一导入点 ├── pg/ │ ├── db.pg.ts → 细雨连接 │ ├── schema.pg.ts → 表定义 │ └── 存储库/ → 特征查询 └── 迁徙/ → 毛毛雨迁徙 **哲学**：存储库接口背后的抽象数据库 ### 界面优先设计 **图案**： // 1. 在 src/types/[domain].ts 中定义接口导出类型 ChatRepository = { insertThread(线程: 省略 ): Promise; selectThread(id: 字符串): Promise; selectThreadDetails(id: 字符串): Promise; }; // 2. 在 src/lib/db/pg/repositories/[domain]-repository.pg.ts 中实现导出 const pgChatRepository: ChatRepository = { selectThreadDetails: async (id: string) => { const [线程] = 等待数据库 .select() .from(聊天线程表) .leftJoin(UserTable, eq(ChatThreadTable.userId, UserTable.id)) .where(eq(ChatThreadTable.id, id)); if (!thread) 返回 null； const messages =等待 pgChatRepository.selectMessagesByThreadId(id); 返回{ id：thread.chat_thread.id，标题：thread.chat_thread.title， userId：thread.chat_thread.userId，创建时间：thread.chat_thread.createdAt， userPreferences: thread.user?.preferences, 消息， }; }, }; // 3. 从 src/lib/db/repository.ts 导出导出 const chatRepository = pgChatRepository; **为什么**： * 易于交换实现（pg→sqlite） * 无需数据库即可测试 * 跨代码库的一致 API ### 查询优化策略 **1\.外键索引**：导出 const ChatThreadTable = pgTable("chat_thread", { id: uuid("id").primaryKey(), userId: uuid("user_id").references(() => UserTable.id), }, (表) => ({ userIdIdx: index("chat_thread_user_id_idx").on(table.userId), })); **2\.选择性加载**： // 加载最少的数据 selectThread(id) → { id, title, userId, createAt } // 需要时加载完整数据 selectThreadDetails(id) → { ...线程、消息、用户首选项 } **3\. SQL 聚合**： // 获取具有最后消息时间戳的线程 constthreadsWithActivity = 等待数据库 .选择({ threadId：ChatThreadTable.id， lastMessageAt: sql`MAX(${ChatMessageTable.createdAt})`, }) .from(聊天线程表) .leftJoin(ChatMessageTable, eq(ChatThreadTable.id, ChatMessageTable.threadId)) .groupBy(ChatThreadTable.id) .orderBy(desc(sql`last_message_at`)); ### 模式演化工作流程 # 1.修改src/lib/db/pg/schema.pg.ts中的模式导出 const NewTable = pgTable("new_table", { ... }); # 2. 生成迁移 pnpm 数据库：生成 # 3. 在 drizzle/migrations/ 中查看生成的 SQL # 4. 应用迁移 pnpm 数据库：迁移 # 5. 可选：可视化数据库探索 pnpm 数据库：工作室 ** ** ## 架构原则 ### 1\.渐进增强功能分层构建：基础层：聊天+法学硕士 ↓ 工具层：默认+MCP ↓ 组合层：工作流程（工具作为节点） ↓ 个性化层：代理（工作流程+提示） **证据**： * 代理可以有“instructions.mentions”（注入工具/工作流程） * 工作流程可调用MCP+默认工具 * 聊天 API 构成所有三个层 **用户旅程**： 1.使用默认工具启动（无需设置） 2.添加MCP服务器以满足特殊需求 3. 合并到自动化工作流程中 4. 封装成角色的代理 ### 2\.约定优于配置 **新工具？** * 添加到 `AppDefaultToolkit` 枚举 → 自动可用 **新工作流程节点？** * 添加到 `NodeKind` 枚举 → 执行器处理它 **新的 MCP 服务器？** * 只需通过 UI 配置 → 管理器处理生命周期 ### 3\.防御性编程 **到处使用`safe()`： const 工具 = 等待安全(() => loadMcpTools()) .orElse({}); // 失败时返回默认值 **哲学**：永远不要让聊天崩溃 - 优雅地降级 ### 4\.流媒体优先 **证据**： * 聊天API使用`createUIMessageStream()` * 工作流执行流中间步骤 * 工具调用流进度更新 **为什么**：实时反馈、更好的用户体验、处理长时间操作 ### 5\.类型驱动开发 **图案**： // Zod 定义运行时验证和 TypeScript 类型 const schema = z.object({ name: z.string() }); type SchemaType = z.infer<模式类型>; // 多态数据的可区分联合输入工作流节点数据= | { 种类：“输入”； ... } | { 种类：“llm”； ... } | { 种类：“工具”； ... }; // 用于运行时检查的品牌类型 VercelAIMcpToolTag.isMaybe(工具) ** ** ## 扩展点参考 **快速查找：“我要添加X”→“修改Y文件”** 想要添加... |扩展/修改... |文件位置 |注释 ---|---|---|--- **新的默认工具** | `AppDefaultToolkit` 枚举 + `APP_DEFAULT_TOOL_KIT` | `lib/ai/tools/tool-kit.ts` |在 `lib/ai/tools/[category]/` 中添加工具实现 \+ 在 `components/tool-inspiration/` 中渲染 **新工具类别** | `AppDefaultToolkit` 枚举 | `lib/ai/tools/index.ts` |创建新的工具包组（例如可视化、WebSearch） **新工作流程节点类型** | `NodeKind` 枚举 + 执行器 + 验证器 | `lib/ai/workflow/workflow.interface.ts` \+ `executor/node-executor.ts` \+ `validator/node-validate.ts` |还要在`components/workflow/node-config/`中添加UI配置 **新 API 端点** |创建路由处理程序 | `src/app/api/[资源]/route.ts` |遵循标准模式：身份验证→验证→存储库→响应 **新服务器操作** |使用“validatedActionWithUser” | `src/app/api/[资源]/actions.ts` |从 `lib/action-utils.ts` 导入 **新数据库表** |添加到架构 + 存储库 | `lib/db/pg/schema.pg.ts` \+ `lib/db/pg/repositories/[name]-repository.pg.ts` |然后`pnpm db:generate`和`pnpm db:migrate` **新的 UI 组件** |在域文件夹中创建 | `src/components/[域]/[名称].tsx` |使用 `components/ui/` 中的 shadcn/ui 原语 **新的 React 钩子** |使用 `use-` 前缀创建 | `src/hooks/use-[name].ts` 或 `src/hooks/queries/use-[name].ts` |数据获取挂钩位于“queries/”子文件夹中 **新 Zod 架构** |添加到验证 | `src/lib/validations/[domain].ts` |对 TypeScript 类型使用 `z.infer` **新的人工智能提供商** |添加到提供商注册表 | `lib/ai/providers.ts` |使用 AI SDK 中的 `createOpenAI`、`createAnthropic` 等 **新的 MCP 服务器** |通过 UI 配置 |设置 → MCP 服务器 |无需更改代码（文件或数据库存储） **新代理模板** |通过 UI 创建 |代理页面 |组合工具/工作流程/提示 **新权限类型** |添加到权限枚举 | `lib/auth/permissions.ts` |在 `validatedActionWithAdminPermission` 中使用 **新的端到端测试** |添加测试文件 | `tests/[feature].spec.ts` |使用剧作家，遵循现有模式 **新系统提示** |添加到提示 | `lib/ai/prompts.ts` |使用 `mergeSystemPrompt` 进行组合 ### 通用开发流程 **端到端添加功能**： 1.定义类型(src/types/[domain].ts) 2. 创建 Zod 架构 (lib/validations/[domain].ts) 3.添加DB表+存储库(lib/db/pg/) 4.创建API路由(app/api/[resource]/route.ts) 5.创建UI组件(components/[domain]/) 6.创建数据钩子(hooks/queries/use-[resource].ts) 7.添加端到端测试（tests/[feature].spec.ts） 8. 运行：pnpm check && pnpm test:e2e **端到端添加工具**： 1.实现工具(lib/ai/tools/[类别]/[名称].ts) 2. 添加到工具包（lib/ai/tools/tool-kit.ts） 3. 创建渲染组件(components/tool-inspiration/[name].tsx) 4. 添加工具调用开关(components/tool-inspiration/index.tsx) 5. 在聊天中使用@toolname 进行测试 **端到端添加工作流节点**： 1. 添加 NodeKind 枚举 (lib/ai/workflow/workflow.interface.ts) 2.定义节点数据类型（同一文件） 3.添加执行器（lib/ai/workflow/executor/node-executor.ts） 4.添加验证器(lib/ai/workflow/validator/node-validate.ts) 5. 创建 UI 配置（components/workflow/node-config/[name]-node.tsx） 6. 在工作流构建器中进行测试 ** ** ## 用户体验模式和@提及系统 ### @提及哲学 **核心设计原则**：每个功能都可以通过“@mentions”立即访问 - 无需深入菜单。 **为什么这很重要**：用户可以即时编写功能，而无需上下文切换。 ### @提及的三种类型 #### 1\. @tool（默认工具） **格式** : `@tool("工具名称")` **示例**： @tool("web-search") 查找最近的人工智能论文 @tool("create-table") 显示销售数据 @tool("python-execution") 计算斐波那契 **它是如何工作的**： * 从服务器上的消息解析 * 从`APP_DEFAULT_TOOL_KIT`加载相应的工具 * LLM根据提示决定何时调用 **用例**：内置功能（搜索、可视化、代码执行） #### 2\. @mcp（MCP 服务器工具） **格式** : `@mcp("server_name")` 或特定工具 `@mcp("server_name:tool_name")` **示例**： @mcp("github") 在我的存储库中创建一个问题 @mcp("playwright") 导航至 google.com @mcp("slack:send-message") 发布更新到 #general **它是如何工作的**： * 提及过滤要加载的 MCP 服务器/工具 * 减少代币使用（仅发送给 LLM 的相关工具） * MCP管理器处理连接和执行 **用例**：外部集成（GitHub、Slack、数据库等） #### 3\. @workflow（自定义工作流程） **格式** : `@workflow("workflow_name")` **示例**： @workflow("customer-onboarding") 处理新注册 @workflow("data-pipeline") 转换和分析 CSV **它是如何工作的**： * 工作流程转换为可调用工具 * 法学硕士将工作流程视为带有描述的单一工具 * 执行流中间节点结果 **用例**：多步骤自动化、业务流程 #### 4\. @agent（特工角色） **格式**：从下拉列表中选择代理（不在消息中输入） **它是如何工作的**： * 代理的“instructions.mentions”自动注入工具/工作流程 * 对话前添加系统提示 * 预设可以覆盖模型/温度 **用例**：特定于角色的上下文（编码助理、数据分析师等） ### 工具选择模式 **上下文**：用户从下拉列表中选择模式 #### 自动模式（默认） * LLM可以自主调用工具 * 每条消息调用多个工具 * 最适合：自动化、工作流程、探索 **流程示例**：用户：@tool("web-search")查找AI新闻，然后@tool("create-table")总结 → LLM 搜索 → 格式化结果 → 创建表格 → 返回消息 #### 手动模式 * LLM提出工具调用，等待用户批准 * 用户看到带有参数的“工具：网络搜索”，单击“执行” * 最适合：敏感操作、学习、调试 **流程示例**：用户：@mcp("github") 创建问题 → LLM 建议：create_issue(repo="...", title="...", body="...") → 用户审核并点击“执行” → 工具运行 → 显示结果 #### 无模式 * 未加载工具（纯文本对话） * 减少延迟和令牌使用 * 最适合：头脑风暴、解释、简单查询 ### 预设系统 **什么是预设？** * 常见场景快速配置 * 按用户存储 * 可以覆盖：型号、温度、工具选择、允许的 MCP 服务器 **用例示例**：预设：“快速聊天” - 型号：GPT-4o-mini（快速） - 工具：无 - 用于：快速问答预设：“研究助理” - 型号：克劳德十四行诗 4.5 - 工具：@tool(“网络搜索”)、@mcp(“维基百科”) - 用于：深入研究预设：“代码审查” - 型号：GPT-5 - 工具：@mcp("github")、@tool("python-execution") - 用于：通过测试审查 PR **如何创建**： 1.配置聊天（模型、工具、设置） 2. 单击“另存为预设” 3. 命名 4. 在以后的聊天中从下拉列表中选择 ### 用户旅程示例 #### 初学者：初次用户 1. 开始聊天（无@提及）→ 默认工具可用 2. 询问：“搜索有关AI的新闻” 3.LLM自动使用@tool("web-search") 4. 用户看到：搜索结果→格式化答案 5.学习：工具在自动模式下自动工作 #### 中级：使用工作流程 1. 在 Workflow Builder 中创建工作流：输入 → 网络搜索 → LLM 摘要 → 输出 2.另存为“研究工作流程” 3. 在聊天中：“@workflow('research-workflow') 2025 年人工智能趋势” 4.查看：每个节点的实时进度 5. 获取：格式化的研究报告 #### 高级：代理 + MCP + 工作流程 1.创建代理“DevOps Assistant” 2. Agent指令包括：@mcp("github")、@workflow("deploy-pipeline") 3. 从下拉列表中选择代理 4. 聊天：“将最新提交部署到暂存” 5. 代理：使用 GitHub MCP → 触发部署工作流程 → 监控 → 报告 ### 开发人员应遵循的设计模式 **1\.可发现性** * 每个工具都应该有清晰的描述（在LLM上下文中显示） * 使用语义名称（`create-table` 而不是 `tool-42`） **2\.可组合性** * 工具应该是单一用途的 * 工作流程撰写工具 * 代理组成工作流程+工具+上下文 **3\.渐进式披露** * 初学者：自动模式，无@提及（使用默认值） * 中级：明确的@tool/@mcp 提及 * 高级：工作流程、代理、预设 **4\.反馈** * 长时间操作的流式传输 * 工作流程的进度更新 * 清除错误消息并提供解决方案 ** ** ## 实用模板 ### 模板：添加新的默认工具 // 1. 在lib/ai/tools/[category]/[tool-name].ts中定义从“ai”导入{工具作为createTool}；从“zod”导入{z}；导出 const myNewTool = createTool({ 描述：“LLM 的清晰描述，以了解何时使用它”，输入模式： z.object({ param: z.string().describe("这个参数的作用"), }), 执行：异步（参数）=> { // 对于可视化工具：返回“Success” // 对于数据工具：返回实际数据返回“成功”； }, }); // 2. 添加到lib/ai/tools/tool-kit.ts 从“./index”导入{DefaultToolName}； import { myNewTool } from "./[类别]/[工具名称]"; 导出枚举默认工具名称{ // ... 现有的 MyNewTool = "my_new_tool", } 导出常量 APP_DEFAULT_TOOL_KIT = { [AppDefaultToolkit.MyCategory]：{ [DefaultToolName.MyNewTool]：myNewTool， }, }; // 3. 在components/tool-inspiration/my-tool-inspiration.tsx中创建渲染导出函数 MyToolInitation({ 部分 }: { 部分: ToolUIPart }) { const args = part.input as z.infer; return

{/* 根据args渲染*/}

; } // 4. 添加到 Components/tool-inspiration/index.tsx 开关 if (工具名称 === DefaultToolName.MyTool) { 返回<我的工具调用部分= {部分} />; } ### 模板：添加新的 API 路由 // src/app/api/[资源]/route.ts 从“auth/server”导入{ getSession }；从“lib/db/repository”导入{ [resource]Repository }；从“zod”导入{z}； const querySchema = z.object({ 限制：z.coerce.number().default(10), }); 导出异步函数 GET(请求: 请求) { // 1. 验证检查 const 会话 = 等待 getSession(); if (!session?.user.id) { return new Response("未经授权", { status: 401 }); } // 2. 解析&验证尝试{ const url = 新 URL(request.url); const params = querySchema.parse(Object.fromEntries(url.searchParams)); // 3. 使用存储库 const data =等待[资源]Repository.selectByUserId( 会话.用户.id, 参数限制）；返回 Response.json(数据); } 捕获（错误）{ if (z.ZodError 错误实例) { 返回响应.json( { 错误：“无效参数”，详细信息：error.message }， { 状态：400 } ）； } console.error("失败：", error); return new Response("内部服务器错误", { status: 500 }); } } 导出异步函数 POST(request: Request) { const 会话 = 等待 getSession(); if (!session?.user.id) { return new Response("未经授权", { status: 401 }); } 尝试{ const body =等待request.json(); const data = createSchema.parse(body); const item =等待[资源]Repository.insert({ ...数据，用户Id：会话.用户.id， }); 返回 Response.json(item); } 捕获（错误）{ if (z.ZodError 错误实例) { return Response.json({ error: "无效输入" }, { status: 400 }); } return Response.json({ error: "内部错误" }, { status: 500 }); } } ### 模板：添加新存储库 // 1. 在 src/types/[domain].ts 中定义接口导出类型 MyRepository = { selectById(id: 字符串): Promise; selectByUserId(userId: string, limit?: number): Promise; 插入（数据：InsertType）：Promise ； update(id: string, data: Partial): Promise; 删除（id：字符串）：Promise； }; // 2. 将表添加到 src/lib/db/pg/schema.pg.ts 导出 const MyTable = pgTable("my_table", { id: uuid("id").primaryKey().defaultRandom(), userId: uuid("user_id").references(() => UserTable.id).notNull(), 名称：文本（“名称”）.notNull（），创建时间：时间戳(“created_at”).defaultNow().notNull(), }, (表) => ({ userIdIdx: 索引("my_table_user_id_idx").on(table.userId), })); // 3. 在 src/lib/db/pg/repositories/my-repository.pg.ts 中实现从“../db.pg”导入{ pgDb as db }；从“../schema.pg”导入{MyTable}；从“drizzle-orm”导入 { eq, desc }; 导出 const pgMyRepository: MyRepository = { selectById: async (id) => { const [结果] = 等待数据库 .select() .from(我的表) .where(eq(MyTable.id, id)); 返回结果？？无效的; }, selectByUserId: async (userId, limit = 10) => { 返回等待数据库 .select() .from(我的表) .where(eq(MyTable.userId, userId)) .orderBy(desc(MyTable.createdAt)) .limit(限制); }, 插入：异步（数据）=> { const [结果] = 等待数据库 .insert(我的表) .值（数据） .return(); 返回结果； }, 更新：异步（id，数据）=> { const [结果] = 等待数据库 .update(我的表) .set(数据) .where(eq(MyTable.id, id)) .return(); 返回结果； }, 删除：异步（id）=> { 等待 db.delete(MyTable).where(eq(MyTable.id, id)); }, }; // 4. 从 src/lib/db/repository.ts 导出从“./pg/repositories/my-repository.pg”导出{ pgMyRepository as myRepository }； // 5. 生成并运行迁移 // pnpm db:生成 // pnpm 数据库：迁移 ** ** ## 服务器操作验证器和编码标准 ### 服务器操作验证器 (`lib/action-utils.ts`) 用于经过验证、权限控制的服务器操作的集中模式： // 模式 1：简单验证 validatedAction（架构，异步（数据，formData）=> { ... }） // 模式 2：使用用户上下文（自动身份验证、自动错误处理） validatedActionWithUser（架构，异步（数据，formData，用户）=> { ... }） // 模式 3：基于权限（管理员、用户管理） validatedActionWithAdminPermission（架构，异步（数据，formData，会话）=> { ... }） **预防**： * 忘记身份验证检查 ✓ * 验证不一致 ✓ * FormData 解析错误 ✓ * 非标准错误响应 ✓ **2\.工具抽象系统** 使用品牌类型标签的多种工具类型的统一接口： // 用于运行时类型缩小的品牌类型 VercelAIMcpToolTag.create(tool) // 品牌为 MCP 工具 VercelAIWorkflowToolTag.isMaybe(tool) // 检查是否是工作流工具 // 多个工具类型的单个处理程序 if (VercelAIWorkflowToolTag.isMaybe(工具)) { // 特定于工作流的逻辑 } else if (VercelAIMcpToolTag.isMaybe(工具)) { // MCP 特定逻辑 } **工具类型**： * **MCP 工具**：模型上下文协议集成 * **工作流程工具**：基于可视化 DAG 的工作流程 * **默认工具**：内置功能（搜索、代码执行等） **3\.工作流执行引擎** 基于 DAG 的工作流系统，具有实时流： * 通过 dataStream.write() 流式传输节点执行进度 * 跟踪：状态、输入/输出、错误、计时 * 令牌优化：存储历史记录，但没有详细结果 **4\.状态管理** Zustand 存储对工作流程和应用程序配置进行浅层比较。 ** ** ## 编码标准 ### 命名约定类型 |大会|示例 ---|---|--- 组件|帕斯卡案例 | `ChatBot.tsx`、`WorkflowBuilder.tsx` 组件文件| kebab-case 或 PascalCase | `chat-bot.tsx`、`ChatBot.tsx` 挂钩|带 `use-` 前缀的驼峰式命名法 | `use-chat-bot.ts`、`use-workflow.ts` 公用事业 |驼峰式 | `action-utils.ts`、`shared.chat.ts` API 路线 | Next.js 约定 | `src/app/api/[资源]/route.ts` 类型 |域名后缀| `chat.ts`、`mcp.ts`、`workflow.ts` ### TypeScript 标准 * **严格的 TypeScript** 自始至终（没有任何隐含的） * **Zod 用于验证和类型推断** : const schema = z.object({ name: z.string() }) type SchemaType = z.infer<架构类型> * **自定义类型标签**用于运行时类型缩小（请参阅工具抽象） * **在 `src/types/` 中按域组织的类型** ### 代码质量 * **线宽**：80 个字符 * **缩进**：2 个空格 * **格式化程序**：生物群系 1.9.4 * **Linter** ：生物群落（无 ESLint） * **验证** ：Zod 无处不在（表单、API、动态配置） ### 错误处理 * **针对特定错误的枚举错误类型**：枚举更新用户密码错误{ INVALID_CURRENT_PASSWORD = "当前密码无效", PASSWORD_MISMATCH = "密码不匹配" } * **使用 Zod `superRefine` 进行跨领域验证**： .superRefine((数据, ctx) => { if (data.password !== data.confirmPassword) { ctx.addIssue({ path: ["confirmPassword"], message: "密码必须匹配" }) } }) ** ** ## 开发工作流程 ### 核心命令 # 开发 pnpm dev # 启动开发服务器 pnpm build # 生产版本 pnpm start # 启动生产服务器 pnpm lint:fix # 自动修复 linting 问题 # 数据库（Drizzle ORM） pnpm db:generate # 生成迁移 pnpm db:migrate # 运行迁移 pnpm db:push # 推送架构更改 pnpm db:studio # 打开 Drizzle Studio # 测试 pnpm test # 运行 Vitest 单元测试 pnpm test:e2e # 完整的 Playwright E2E 套件 pnpm test:e2e:first-user # 第一用户注册 + 管理员角色测试 pnpm test:e2e:standard # 标准测试（跳过第一个用户） pnpm test:e2e:ui # 交互式剧作家 UI # 质量检查 pnpm check # 运行 lint + 类型检查 + 测试 ### 环境设置 * 将`.env.example`复制到`.env`（在`pnpm i`上自动生成） * 必需：PostgreSQL 连接，至少一个 LLM API 密钥 * 可选：OAuth 提供商（Google、GitHub、Microsoft）、Redis、Vercel Blob ### 分支策略 * **主要** ：生产就绪代码 * **功能分支** : `feat/feature-name` 或 `fix/bug-name` * **挤压合并** ：每个 PR 一次提交以获取干净的历史记录 ** ** ## 测试模式 ### 单元测试 (Vitest) * **与源代码并置** (`*.test.ts`) * **覆盖率**：快乐路径+最少一种故障模式 * **示例**： // src/lib/utils.test.ts 从 'vitest' 导入 { 描述、它、期望 } 从 './utils' 导入 { formatDate } 描述（'格式日期'，（）=> { it('正确格式化 ISO 日期', () => { Expect(formatDate('2025-01-01')).toBe('2025 年 1 月 1 日') }) it('处理无效日期', () => { Expect(formatDate('无效')).toBe('无效日期') }) }) ### E2E 测试（剧作家） **针对多用户和第一用户场景的特殊编排**： # 第一用户测试（清理数据库 → 注册 → 验证管理员角色） pnpm 测试：e2e：第一个用户 # 标准测试（假设第一个用户存在） pnpm 测试：e2e：标准 # 全套（第一用户→标准） pnpm 测试：e2e **测试项目依赖关系**确保顺序执行： 1. 清理数据库 2. 运行首次用户注册+角色验证 3. 运行标准多用户测试 **跨测试运行共享身份验证状态**以避免重新登录。 **用于确定性测试的种子/清理脚本**。 ** ** ## 贡献指南 ### 开始之前 **重大变更需要首先讨论**： * 新的用户界面组件 * 新的API端点 * 外部服务集成 * 重大变更 **无需事先批准**： * 错误修复 * 文档改进 * 小重构 ### 拉取请求标准 **标题格式**（常规提交）：功能：添加实时语音聊天修复：解决MCP工具流错误杂务：更新依赖项文档：添加 OAuth 设置指南 **前缀**：`feat:`、`fix:`、`chore:`、`docs:`、`style:`、`refactor:`、`test:`、`perf:`、`build:` **需要视觉文档**： * UI 更改之前/之后的屏幕截图 * 交互式功能的屏幕录制 * 移动+桌面视图以实现响应式更新 **描述应该解释**： 1. 发生了什么变化 2. 为什么改变 3. 你是如何测试的 ### 预提交清单 # 必须在 PR 之前通过： pnpm check # Lint + 类型检查 + 测试 pnpm test:e2e # E2E 测试（如果适用） * 添加了新功能/错误修复的测试 * 包括可视化文档（如果 UI 发生变化） * 常规提交标题 * 描述解释了什么、为什么、测试 ** ** ## 关键规则 ### 总是这样做 ✅ 使用 `validatedActionWithUser` 或 `validatedActionWithAdminPermission` 进行服务器操作 ✅ 在执行前使用品牌类型标签检查工具类型 ✅ 使用 Zod `superRefine` 进行跨字段验证 ✅ 添加单元测试（快乐路径 + 一种失败模式） ✅ 在 PR 提交之前运行 `pnpm check` ✅ 包含 UI 更改的可视化文档 ✅ 对 PR 标题使用常规提交格式 ✅ 在触及关键流程时运行 E2E 测试 ### 永远不要这样做 ❌ 在没有身份验证验证器的情况下实现服务器操作 ❌ 在没有运行时检查的情况下假设工具类型 ❌ 手动解析 FormData（使用验证器） ❌ 直接改变 Zustand 状态（使用浅层更新） ❌ 跳过干净数据库上的第一用户测试 ❌ 提交而不运行 `pnpm check` ❌ 提交 PR 而不使用可视文档（如果 UI 更改） ❌ 使用非常规提交格式 ** ** ## 已知问题预防此技能可防止 **8** 已记录的问题： ### 问题#1：忘记服务器操作中的身份验证检查 **错误**：未经授权的用户访问受保护的操作**为什么会发生**：手动身份验证实现不一致**预防**：使用`validatedActionWithUser`或`validatedActionWithAdminPermission` // ❌ 不好：手动身份验证检查导出异步函数 updateProfile(data: ProfileData) { const 会话 = 等待 getSession() if (!session) 抛出新错误("未经授权") // ...其余逻辑 } // ✅ 好：使用验证器导出常量 updateProfile = validActionWithUser( 概要文件架构，异步（数据，formData，用户）=> { // 保证用户存在，自动错误处理 } ） ### 问题#2：工具类型不匹配 **错误**：执行工具时出现运行时类型错误 **为什么会发生**：执行前未检查工具类型 **预防**：使用品牌类型标签来缩小运行时范围 // ❌ 不好：假设工具类型 const 结果 = 等待executeMcpTool(工具) // ✅ 好：检查工具类型 if (VercelAIMcpToolTag.isMaybe(工具)) { const 结果 = 等待executeMcpTool(工具) } else if (VercelAIWorkflowToolTag.isMaybe(工具)) { const 结果 = 等待executeWorkflowTool(工具) } ### 问题 #3：FormData 解析错误 **错误**：表单提交的错误处理不一致**为什么会发生**：使用临时验证进行手动 FormData 解析 **预防**：验证器自动处理解析 // ❌ 不好：手动解析 const name = formData.get("name") 作为字符串 if (!name) throw new Error("需要名称") // ✅ 好：使用 Zod 进行验证 const schema = z.object({ name: z.string().min(1) }) 导出常量操作= validatedAction（架构，异步（数据）=> { // data.name 已验证并输入 }) ### 问题#4：跨领域验证问题 **错误**：密码不匹配验证不起作用 **为什么会发生**：对相关字段进行单独验证 **预防**：使用 Zod `superRefine` // ❌ 不好：单独检查 if (data.password !== data.confirmPassword) { /* 错误 */ } // ✅ 好：Zod superRefine const 架构 = z.object({ 密码：z.string(), 确认密码：z.string() }).superRefine((数据, ctx) => { if (data.password !== data.confirmPassword) { ctx.addIssue({ 路径：[“确认密码”]，消息：“密码必须匹配” }) } }) ### 问题#5：工作流程状态不一致 **错误**：Zustand 状态更新不触发重新渲染 **为什么会发生**：嵌套工作流状态的深度突变 **预防**：使用浅层更新 // ❌ 不好：深度突变 store.workflow.nodes[0].status = "完成" // ✅ 好：浅更新设置（状态=>（{ 工作流程：{ ...状态.工作流程，节点：state.workflow.nodes.map((node, i) => 我 === 0 ? { ...节点，状态：“完成” } ：节点） } }）） ### 问题#6：缺少 E2E 测试设置 **错误**：E2E 测试在干净的数据库上失败 **为什么会发生**：在第一个用户设置之前运行标准测试 **预防**：使用正确的测试命令 # ❌ 不好：在干净的数据库上运行标准测试 pnpm 测试：e2e：标准 # ✅ 好：带有第一用户设置的全套套件 pnpm 测试：e2e ### 问题#7：环境配置错误 **错误**：缺少所需的环境变量导致崩溃**为什么会发生**：未将`.env.example`复制到`.env` **预防**：在`pnpm i`上自动生成`.env` # 安装时自动生成 .env PNPM我 # 验证所有必需的变量是否存在 # 必填：DATABASE_URL，至少一个LLM_API_KEY ### 问题 #8：提交消息格式不正确 **错误**：由于非常规提交格式导致 CI/CD 失败 **为什么会发生**：不遵循常规提交标准 **预防**：使用前缀 + 冒号格式 # ❌ 不好： git commit -m“添加功能” git commit -m“修复错误” # ✅ 好： git commit -m“壮举：添加 MCP 工具流” git commit -m“修复：解决身份验证重定向循环” ** ** ## 常见模式 ### 模式 1：带有用户上下文的服务器操作从“@/lib/action-utils”导入{validatedActionWithUser} 从“zod”导入{z} const updateProfileSchema = z.object({ 名称：z.string().min(1), 电子邮件：z.string().email() }) 导出常量 updateProfile = validActionWithUser( 更新配置文件架构，异步（数据，formData，用户）=> { // 保证用户已通过身份验证 // 数据经过验证并输入等待 db.update(users).set(data).where(eq(users.id, user.id)) 返回 { 成功：真 } } ） **何时使用** ：任何需要身份验证的服务器操作 ### 模式 2：工具类型检查从“@/lib/ai/tools”导入 { VercelAIMcpToolTag, VercelAIWorkflowToolTag } 异步函数executeTool（工具：未知）{ if (VercelAIMcpToolTag.isMaybe(工具)) { 返回等待executeMcpTool（工具） } else if (VercelAIWorkflowToolTag.isMaybe(工具)) { 返回等待执行工作流工具（工具） } 否则{ 返回等待执行默认工具（工具） } } **何时使用** ：在统一界面中处理多种工具类型 ### 模式 3：工作流程状态更新从“@/app/store/workflow”导入{ useWorkflowStore } // 在组件中： const updateNodeStatus = useWorkflowStore(state => state.updateNodeStatus) // 店内： updateNodeStatus: (nodeId, 状态) => 设置（状态=>（{ 工作流程：{ ...状态.工作流程，节点：state.workflow.nodes.map（节点=> 节点.id === 节点Id ？ { ...节点，状态 } ：节点） } }）） **何时使用** ：更新嵌套的 Zustand 状态而不发生突变 ** ** ## 使用捆绑资源 ### 参考文献（参考文献/） * `references/AGENTS.md` \- 完整的存储库指南（出现详细结构问题时加载） * `references/CONTRIBUTING.md` \- 完整的贡献流程（出现 PR 标准问题时加载） **当克劳德应该加载这些**：当用户询问详细的更好的聊天机器人约定，询问“完整的指南是什么？”，或者需要全面的贡献工作流程详细信息时。 ** ** ## 依赖关系 **必填**： * next@15.3.2 - 框架 * ai@5.0.82 - Vercel AI SDK * better-auth@1.3.34 - 身份验证 * drizzle-orm@0.41.0 - 数据库 ORM * @modelcontextprotocol/sdk@1.20.2 - MCP 支持 * zod@3.24.2 - 验证 * zustand@5.0.3 - 状态管理 **测试**： * vitest@3.2.4 - 单元测试 * @playwright/test@1.56.1 - E2E 测试 ** ** ## 官方文档 * **更好的聊天机器人**： * **Next.js** : * **Vercel AI SDK** ： * **更好的身份验证**： * **Drizzle ORM** ： * **剧作家**： * **现场演示**： ** ** ## 制作示例该技能基于 **better-chatbot** 生产标准： * **直播**： * **测试**：48+ E2E 测试通过 * **错误**：0（已阻止所有 8 个已知问题） * **验证** : ✅ 多用户场景、工作流程执行、MCP 工具 ** ** ## 完整设置清单在为更好的聊天机器人做出贡献时： * 分叉和克隆存储库 * 运行 `pnpm i` （自动生成 `.env`） * 配置所需的环境变量（DATABASE_URL、LLM_API_KEY） * 运行 `pnpm dev` 并验证它是否启动 * 创建功能分支 * 添加新功能的单元测试 * 在 PR 之前运行 `pnpm check` * 如果触及关键流程，请运行“pnpm test:e2e” * 包括视觉文档（屏幕截图/录音） * 使用常规提交标题 * 获得批准后合并 ** ** **有问题吗？问题？** 1. 查看 `references/AGENTS.md` 了解详细指南 2. PR流程查看`references/CONTRIBUTING.md` 3.查看官方文档： 4. 确保配置了 PostgreSQL 和 LLM API 密钥 ** ** **代币效率**：节省约 60% | **防止错误**：8 | **生产验证**：是

更好的聊天机器人

包含技能