用途:在 Convex 项目的 convex/ 目录中编写或审查后端代码,涵盖 schema、query、mutation、action 与 HTTP 端点,目标是第一次就能通过部署与类型检查。
主要能力与规则:
- 导入与函数语法:query、mutation、action、internalQuery 等从 "./_generated/server" 导入,api、internal 从 "./_generated/api" 导入;一律使用对象形式并带 args 与 returns 校验器,ID 用 v.id(tableName)。
- 数据访问:用 .withIndex(...) 加 .paginate(paginationOpts) 或 .take(n),避免无界 .collect();不要在 schema 索引中包含 _creationTime,表名与索引名不能以下划线开头。
- 参数安全:对作为增量使用的数值参数设上界,拒绝 NaN、Infinity 与越界值;HTTP 路径参数转 v.id 要包 try/catch。
- HTTP 与幂等:http.route 的 handler 必须用 httpAction 包裹,路由无 Express 风格 :param,需用 pathPrefix 自行解析;有副作用的变更路由需幂等键,重试应为无操作。
- 鉴权:每个公开函数独立调用 ctx.auth.getUserIdentity() 并做归属校验,不能只校验调用者身份;引入鉴权前需确认已有 auth.config.ts 与关联用户表。
- 限制:函数读取约 16000 文档、写入约 8000 文档、单文档 1 MiB、查询 CPU 约 1 秒、action 运行 10 分钟;触限应重新设计而非重试。
使用方式:被调用后先读 convex/schema.ts(如存在再读 convex/_generated/ai/guidelines.md),再实现或审查;完成后运行 npx tsc --noEmit 并推送验证(npx convex dev --once;仅在未登录时用 CONVEX_AGENT_MODE=anonymous)。
适用场景:用 Codex 等 AI 工具生成或维护 Convex 后端、排查部署失败与性能与安全缺陷。
限制:资料未提供具体收费、价格与平台信息;部分内容为规则说明,未给出完整项目示例。