用途
该技能用于在 Convex 项目中实现安全身份验证，包含用户管理与访问控制。适合以下场景：
- 首次为 Convex 配置身份验证
- 实现用户管理（users 表、身份映射）
- 创建认证辅助函数
- 接入认证提供方（Convex Auth、Clerk、WorkOS AuthKit、Auth0、自定义 JWT）
第一步：选择认证提供方
Convex 支持多种认证方式，不要假设使用某一种提供方。在编写配置代码之前：
- 询问用户希望使用哪种认证方案，除非仓库已明确表明
- 如果仓库已在使用某提供方，则沿用该提供方，除非用户希望切换
- 如果用户尚未选择且仓库未明确表明，应先询问再继续
常见选项：
- Convex Auth：当用户希望认证直接在 Convex 内处理时的合适默认选择
- Clerk：当应用已使用 Clerk，或用户希望使用 Clerk 的托管认证功能时使用
- WorkOS AuthKit：当应用已使用 WorkOS，或用户明确需要 AuthKit 时使用
- Auth0：当应用已使用 Auth0 时使用
- 自定义 JWT 提供方：当需要集成上述未覆盖的现有认证系统时使用
询问前可先查找仓库中的信号：依赖项（如 @clerk/、@workos-inc/、@auth0/* 或 Convex Auth 包）、现有文件（如 convex/auth.config.ts、认证中间件、provider 包装器或登录组件）、明确指向某提供方的环境变量。
选定提供方之后
阅读该提供方的官方指南及对应的本地参考文件：
- Convex Auth：官方文档，然后是 references/convex-auth.md
- Clerk：官方文档，然后是 references/clerk.md
- WorkOS AuthKit：官方文档，然后是 references/workos-authkit.md
- Auth0：官方文档，然后是 references/auth0.md
本地参考文件包含具体的工作流程、预期文件与环境变量、注意事项和验证检查。使用这些来源处理：包安装、客户端 provider 接线、环境变量、convex/auth.config.ts 配置、登录与登出 UI 模式、面向 React、Vite 或 Next.js 的框架专属配置。
然后阅读 references/common-patterns.md，了解适用于各提供方的 Convex 端通用模式：
- 将 ctx.auth.getUserIdentity() 映射到 users 表
- getCurrentUser 与 getCurrentUserOrNull
- 授权辅助函数，如 requireAdmin
- 所有权检查与团队成员检查
- public、private 与混合查询模式
文档可用时，不要凭记忆编造提供方专属配置。不要假设提供方的初始化命令已完成整个集成，应验证生成的文件并完成提供方参考文件中指明的初始化后接线步骤。
工作流程
- 确定提供方，可询问用户或从仓库推断
- 询问用户现在需要仅本地配置还是生产就绪配置
- 阅读匹配的提供方参考文件
- 遵循官方提供方文档获取当前配置细节
- 套用 references/common-patterns.md 中的共享 Convex 模式
- 仅在应用需要 users 表时，接入 storeUser 或等价的身份同步
- 按需添加所有权、管理员或团队访问的授权检查
- 如被要求，验证登录状态、受保护查询、环境变量与生产配置
如果流程因交互式提供方或部署配置而阻塞，明确向用户询问所需的具体人工步骤，待其完成后继续。对于面向 UI 的认证流程，配置完成后可提议验证真实的注册或登录流程。如果环境具备浏览器自动化工具，可以使用它们；如果没有，则给出一份简短的人工验证清单。
参考文件
提供方参考：
- references/convex-auth.md
- references/clerk.md
- references/workos-authkit.md
- references/auth0.md
共享模式：
- references/common-patterns.md
检查清单
- 在编写配置代码前已选定正确的认证提供方
- 已阅读相关提供方参考文件
- 已询问用户需要仅本地配置还是生产就绪配置
- 使用官方提供方文档进行提供方专属接线
- users 表带 tokenIdentifier 索引
- getCurrentUser 辅助函数
- 用于首次登录的 storeUser mutation
- 所有受保护函数中均有认证检查
- 资源访问有授权检查
- 清晰的错误信息（"Not authenticated"、"Unauthorized"）
- 为所选提供方配置了客户端认证 provider
- 如被要求，生产环境认证配置也已覆盖