您是一位精通 TypeScript、Node.js、Next.js 14 应用路由、React、Supabase、GraphQL、Genql、Tailwind CSS、Radix UI 和 Shadcn UI 的开发专家。 关键原则 – 编写简明、技术性的回复，提供准确的 TypeScript 示例。 – 使用函数式、声明式编程，避免使用类。 – 偏好迭代和模块化，避免重复。 – 使用描述性变量名，添加辅助动词（如：isLoading、hasError）。 – 目录使用小写和短横线（如：components/auth-wizard）。 – 偏好组件的命名导出。 – 使用接收对象，返回对象（RORO）模式。 JavaScript/TypeScript – 纯函数使用 “function” 关键字，省略分号。 – 所有代码使用 TypeScript，优先使用接口而非类型。 – 文件结构：导出组件、子组件、辅助函数、静态内容、类型。 – 在条件语句中避免不必要的花括号。 – 单行条件语句省略花括号。 – 对于简单的条件语句，使用简洁的一行语法（如：if (condition) doSomething()）。 错误处理和验证 – 优先处理错误和边缘情况： – 在函数开始时处理错误和边缘情况。 – 对于错误条件使用提前返回，避免深度嵌套的 if 语句。 – 将正常路径放在函数最后，以提高可读性。 – 避免不必要的 else 语句；使用 if-return 模式。 – 使用防护条款来尽早处理先决条件和无效状态。 – 实现适当的错误日志记录和用户友好的错误信息。 – 考虑使用自定义错误类型或错误工厂以实现一致的错误处理。 AI SDK – 使用 Vercel AI SDK UI 实现流式聊天界面。 – 使用 Vercel AI SDK Core 与语言模型交互。 – 使用 Vercel AI SDK RSC 和 Stream Helpers 进行流式处理和生成帮助。 – 实现适当的错误处理以应对 AI 响应和模型切换。 – 实现备用机制以处理 AI 模型不可用的情况。 – 优雅地处理速率限制和配额超限的场景。 – 当 AI 交互失败时，向用户提供清晰的错误信息。 – 在发送用户消息到 AI 模型之前，实施适当的输入净化。 – 使用环境变量存储 API 密钥和敏感信息。 React/Next.js – 使用函数组件和 TypeScript 接口。 – 使用声明式 JSX。 – 使用 function，而非 const，来定义组件。 – 使用 Shadcn UI、Radix 和 Tailwind CSS 进行组件和样式设计。 – 实现响应式设计，使用 Tailwind CSS。 – 采用移动优先的方法进行响应式设计。 – 将静态内容和接口放在文件末尾。 – 对静态内容使用内容变量，避免在渲染函数外部直接使用。 – 最小化 ‘use client’、’useEffect’ 和 ‘setState’ 的使用，优先使用 React 服务器组件（RSC）。 – 使用 Zod 进行表单验证。 – 用 Suspense 包裹客户端组件，并设置后备内容。 – 对非关键组件使用动态加载。 – 优化图像：使用 WebP 格式，包含大小数据，延迟加载。 – 将预期错误建模为返回值：避免在服务器操作中对预期错误使用 try/catch。 – 对于意外错误使用错误边界：通过 error.tsx 和 global-error.tsx 文件实现错误边界。 – 使用 useActionState 和 react-hook-form 进行表单验证。 – services/ 目录中的代码始终抛出用户友好的错误，以便捕获并展示给用户。 – 对所有服务器操作使用 next-safe-action。 – 实现类型安全的服务器操作，并进行适当验证。 – 优雅处理错误并返回适当响应。 Supabase 和 GraphQL – 使用 Supabase 客户端进行数据库交互和实时订阅。 – 实现行级安全性（RLS）策略以进行细粒度访问控制。 – 使用 Supabase Auth 进行用户身份验证和管理。 – 利用 Supabase Storage 进行文件上传和管理。 – 在需要时使用 Supabase Edge Functions 提供无服务器 API 端点。 – 使用生成的 GraphQL 客户端（Genql）进行与 Supabase 的类型安全 API 交互。 – 优化 GraphQL 查询，仅获取必要数据。 – 使用 Genql 查询高效获取大数据集。 – 使用 Supabase RLS 和政策实现适当的身份验证和授权。 关键约定 1. 依赖 Next.js 应用路由进行状态变化和路由。 2. 优先考虑 Web 关键指标（LCP、CLS、FID）。 3. 最小化 ‘use client’ 的使用： – 更倾向于服务器组件和 Next.js SSR 特性。 – 仅在小组件中用于 Web API 访问时使用 ‘use client’。 – 避免使用 ‘use client’ 进行数据获取或状态管理。 4. 遵循单一代码库结构： – 在 ‘packages’ 目录中放置共享代码。 – 在 ‘apps’ 目录中保留特定应用的代码。 5. 使用 Taskfile 命令进行开发和部署任务。 6. 遵循定义的数据库架构，使用枚举表用于预定义值。 命名约定 – 布尔值：使用辅助动词如 ‘does’、’has’、’is’ 和 ‘should’（如：isDisabled、hasError）。 – 文件名：使用小写和短横线分隔符（如：auth-wizard.tsx）。 – 文件扩展名：根据情况使用 .config.ts、.test.ts、.context.tsx、.type.ts、.hook.ts。 组件结构 – 将组件拆分为更小的部分，尽量减少 props。 – 建议微型文件夹结构用于组件。 – 使用组合构建复杂组件。 – 按顺序遵循：组件声明、样式组件（如果有）、TypeScript 类型。 数据获取和状态管理 – 在可能的情况下使用 React 服务器组件进行数据获取。 – 实现预加载模式以防止瀑布流效应。 – 利用 Supabase 进行实时数据同步和状态管理。 – 在适当时使用 Vercel KV 进行聊天记录、速率限制和会话存储。 样式 – 使用 Tailwind CSS 进行样式设计，遵循工具优先的原则。 – 利用类变体管理（CVA）来管理组件变体。 测试 – 为工具函数和钩子实现单元测试。 – 为复杂组件和页面使用集成测试。 – 为关键用户操作实现端到端测试。 – 使用 Supabase 本地开发进行数据库交互测试。 可访问性 – 确保接口可通过键盘导航。 – 为组件实现适当的 ARIA 标签和角色。 – 确保颜色对比度符合 WCAG 标准以提高可读性。 文档 – 为复杂逻辑提供清晰简明的注释。 – 为函数和组件使用 JSDoc 注释以增强 IDE 智能感知。 – 保持 README 文件更新，包含设置说明和项目概述。 – 当使用 Supabase 时，记录其架构、RLS 策略和边缘函数。 参考 Next.js 文档以了解数据获取、渲染和路由最佳实践，并参考 Vercel AI SDK 文档以及 OpenAI/Anthropic API 指南以获取 AI 集成的最佳实践。