SuperAPI AI 工具集

convex-expert

编程与开发

查看项目

更新于 10-16 16:04

技能介绍

Convex 后端专家是一个始终启用的技能,专门用于处理 convex/ 目录内的代码。它适用于函数定义、schema、索引、查询、mutation、action、HTTP 端点等后端开发任务,目标是在接触 convex/ 目录下任何代码之前提供符合 Convex 规范的做法。

用途 该技能面向 Convex 后端开发,帮助避免通用模型经常出错的细节,包括对象形式的函数语法、validator 要求、索引命名规则、内部与公开函数的区分、schema 演进模式、资源限制、组件生态以及运行时错误排查。

主要能力与规则

  • 工作流:在编写或编辑 convex/ 下任何文件前,先读取 convex/schema.ts,如存在也读取 convex/_generated/ai/guidelines.md。所有 Convex 函数使用对象形式,并为每个注册函数提供 args 与 returns validator。读取路径使用 withIndex(...),不要用 .filter() 替代 SQL WHERE 类查询。默认使用 internalQuery/internalMutation/internalAction,仅在客户端 hook 需要时提升为公开函数。涉及 LLM/聊天功能使用 @convex-dev/agent,多步骤流程使用 @convex-dev/workflow。完成后确认 convex dev 推送成功,并就地修复 Schema/Returns/Argument 校验错误。
  • 数据访问与导入:不要在可能增长的表上使用无界 .collect(),应使用 .withIndex(...) 与 .paginate(paginationOptsValidator)/.take(n)。为每个读取路径在 schema.ts 中添加 .index(...),并用 .withIndex(...) 查询;.filter() 是全表扫描,不能替代 WHERE。导入路径必须准确:query/mutation/action/internalQuery/internalMutation/internalAction 来自 "./_generated/server";api/internal 来自 "./_generated/api";不要从 "convex/server" 导入 query,也不要从 "./_generated/server" 导入 internal。固定字符串或枚举成员使用 v.literal("exact value"),例如 v.union(v.literal("open"), v.literal("closed")),而不是裸 v.string()。"use node"; 只能放在仅含 action 的模块顶部,带 "use node" 的文件不能同时导出 query 或 mutation。只使用对象形式,不要使用旧的位置参数 query(args, handler) 语法。每个注册函数都必须有 args 和 returns validator。ID 使用 v.id(tableName),不要用 v.string();undefined 不是 Convex 值,应使用 null。不要向已有数据的表添加必填字段,先加 v.optional(...),回填后再收紧。自定义索引中不要包含 _creationTime 作为列,它是保留字段,会导致 IndexNameReserved 错误。不要在表中存储 storage URL,应存储 Id<'_storage'> 并在读取时调用 ctx.storage.getUrl(id)。mutation 不能发起 fetch,所有外部 IO 放在 action 中,并通过 ctx.runMutation(internal.x.y) 持久化。不要添加并行的数据库、缓存、实时服务、API 服务器、任务队列或对象存储,Convex 就是后端。Convex 函数只能从 convex/ 目录运行,不要在项目根目录编写 schema.ts/queries/mutations/actions。
  • 自验证规则:在声明后端工作完成前,验证其可编译并推送。运行 npx tsc --noEmit 并推送到部署。优先使用项目已有的部署;否则在 npx convex whoami 成功时运行 npx convex dev --once,仅在失败时使用 CONVEX_AGENT_MODE=anonymous npx convex dev --once。对已登录用户强制匿名会重新绑定 .env.local,并使其失去预期的持久、可发布云部署。完成前修复所有报告的错误,一轮验证可捕获错误相对导入、重复符号、括号不匹配等问题。

适用场景 适用于任何在 convex/ 目录内编写或修改后端代码的场景,包括定义函数、设计 schema、添加索引、编写查询与 mutation、实现 action、处理 HTTP 端点、集成 LLM/聊天功能或多步骤工作流。

限制 该技能仅覆盖 Convex 后端开发规范,不涉及前端、部署运维或其他平台。具体收费、价格、平台支持范围等信息暂未提供。