mcpField
C
convex-expert

convex-expert

github.com/get-convex开发6931.5k 次安装1 天前更新
代码仓库

关于 convex-expert

convex-expert 是专注于 Convex 后端实现的开发技能，供修改 convex/ 目录代码时参考。它规定函数、验证器、索引和数据访问模式，并要求类型检查及部署验证。

主要功能

  1. 01先读取 schema 与指南
  2. 02使用对象形式定义函数
  3. 03为注册函数添加参数和返回验证
  4. 04用索引执行读取
  5. 05区分内部与公开函数
  6. 06检查类型并推送部署

适用场景

  1. 01编写 Convex 查询与变更
  2. 02调整数据库模式和索引
  3. 03实现 LLM 或多步骤工作流
  4. 04排查部署与验证错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/get-convex/agent-skills --skill convex-expert

安装后在 Claude Code 中输入/convex-expert确认已加载。

详细介绍

Convex 后端专家

常驻 Convex 后端专家，在触碰 convex/ 目录中的任何代码前调用。熟悉对象形式的函数语法、验证器要求、索引命名规则、内部与公开函数的使用规范、架构演进模式、资源限制、组件生态，以及通用模型经常弄错的运行时错误解码器。

工作流

  1. 准备编写或编辑 convex/ 下的任何文件时：先阅读 convex/schema.ts（如果存在，也要阅读 convex/_generated/ai/guidelines.md）。
  2. 所有 Convex 函数都必须使用对象形式，且每个已注册函数都必须同时提供 args 和 returns 验证器。
  3. 每个读取路径都使用 withIndex(...)——任何可以用 SQL WHERE 子句表达的条件，都绝不要使用 .filter()。
  4. 默认使用 internalQuery/internalMutation/internalAction；只有客户端钩子需要时才将其设为公开函数。
  5. 对于任何 LLM/聊天功能，使用 @convex-dev/agent；对于多步骤流程，使用 @convex-dev/workflow——绝不要自行手动实现。
  6. 编写完成后，确认 convex dev 已成功推送，并就地修复所有 Schema/Returns/Argument 验证错误。

规则

  • 数据访问与导入——编写任何 convex/*.ts 前必须先阅读（提前阅读，而不是事后检查）：
  • 对可能增长的表，绝不要执行无界的 .collect()——改用 .withIndex(...) 和 .paginate(paginationOptsValidator)/.take(n)。这是最常见的 Convex 部署阻塞问题和性能缺陷。
  • 使用索引，不要过滤——在 schema.ts 中为每个读取路径添加 .index(...)，并使用 .withIndex(...) 查询；.filter() 会扫描整张表，绝不能代替 WHERE 子句。
  • 精确的导入表——导入错误会导致应用无法部署：query/mutation/action/internalQuery/internalMutation/internalAction 从 "./_generated/server" 导入；api/internal 从 "./_generated/api" 导入；应用代码中绝不要写 import { query } from "convex/server" 或 import { internal } from "./_generated/server"——这两种写法都会导致部署失败。
  • 对固定字符串/枚举成员使用 v.literal("exact value")（例如 v.union(v.literal("open"), v.literal("closed"))）——当取值集合固定时，不要使用裸的 v.string()。
  • "use node"; 只能放在仅包含 action 的模块顶部——含有 "use node" 的文件绝不能同时导出 query 或 mutation（它们不会在 Node 运行时中运行）；如果两者都需要，请拆分文件。
  • 只能使用对象形式——绝不要使用旧式的位置参数语法 query(args, handler)。
  • 每个已注册函数都必须提供 args 和 returns 验证器，没有例外。
  • ID 使用 v.id(tableName)，绝不要使用 v.string()；undefined 不是 Convex 值（请使用 null）。
  • 绝不要向已有数据的表添加必填字段——先添加 v.optional(...)，完成数据回填后再收紧要求。
  • 自定义索引中绝不要包含 _creationTime 作为列（该字段为保留字段；这样做会导致 IndexNameReserved 错误）。
  • 绝不要在表中存储存储 URL——存储 Id<'_storage'>，并在读取时调用 ctx.storage.getUrl(id)。
  • Mutation 不能进行数据获取——所有外部 I/O 都放在 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。对已登录用户强制使用 anonymous 模式会重新绑定 .env.local，让用户失去他们预期的持久、可发布云端部署。完成前必须修复报告的所有错误——一次验证就能发现错误的相对导入、重复符号、不匹配括号等问题，否则这些问题会导致部署失败。

评论

支持 Markdown