mcpField
C
convex-expert

convex-expert

github.com/growthx-club开发0171 次安装5 周前更新
代码仓库

关于 convex-expert

convex-expert 是专用于 Convex 后端目录开发的常驻技能，提供函数、架构、数据访问及部署约束方面的实现与验证指导。

主要功能

  1. 01编辑前读取架构与指南
  2. 02使用对象形式函数并添加验证器
  3. 03通过索引读取而非扫描整表
  4. 04规范区分公开与内部函数
  5. 05编译和部署验证

适用场景

  1. 01实现 Convex 查询与变更函数
  2. 02在不破坏已有数据的情况下演进架构
  3. 03部署前检查后端改动

安装

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

$npx skills add https://github.com/growthx-club/build-sprint-skills --skill convex-expert

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

附带文件UPSTREAM-LICENSEUPSTREAM-THIRD_PARTY_NOTICES.md

详细介绍

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