mcpField
C
convex

convex

github.com/justbecauselabs开发1100 次安装8 周前更新
代码仓库

关于 convex

convex 是面向在 Convex 项目中编写和修改代码的 Agent 技能，提供涵盖函数、数据库、验证器、客户端集成等主题的本地指南。它也指出在本地参考缺少内容时查阅 Convex 在线文档。

主要功能

  1. 01按任务查找本地参考指南
  2. 02涵盖函数与数据模型设计
  3. 03说明查询、变更和操作
  4. 04提供集成、测试与部署指导

适用场景

  1. 01编写或修改 Convex 函数
  2. 02设计表、索引和验证器
  3. 03处理搜索、迁移或定时任务
  4. 04配置客户端集成与部署

安装

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

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

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
action-guidelines.md
ai-agents-guidelines.md
auth-guidelines.md
client-integration-guidelines.md
components-guidelines.md
examples.md
file-storage-guidelines.md
full-text-search-guidelines.md
function-guidelines.md
migrations-guidelines.md
mutation-guidelines.md
production-guidelines.md
query-guidelines.md
scheduling-guidelines.md
schema-guidelines.md
testing-guidelines.md
typescript-guidelines.md
validator-guidelines.md
vector-search-guidelines.md

详细介绍

Convex 指南

本技能涵盖当前的 Convex 文档内容。请先阅读下方最相关的本地指南。如果任务涉及尚未镜像到 references/ 中的较新平台领域，请先查阅 https://docs.convex.dev/llms-full.txt 中链接的在线文档，再进行更改。

核心规则

  1. 除非周边代码库已采用其他模式，否则每个文件优先只导出一个 Convex 函数。同一文件中可以有小型私有辅助函数。
  2. 当精确的验证器有助于提高安全性、生成 API 类型、生成 OpenAPI 输出或静态代码生成时，请使用它们。不要声称每个 Convex 函数都必须提供 args 或 returns 验证器；省略时，Convex 会回退到 v.any()。
  3. 将 v.any() 视为真正动态的载荷或可信外部 webhook 载荷的有意后备方案，而不是普通应用数据的默认选择。
  4. 有意识地选择运行时。查询和 mutation 围绕 ctx.db 保持事务性；action 用于外部 I/O 和仅限 Node 的工作；向量搜索只能在 action 中执行。
  5. 优先通过索引和架构设计解决问题，而不是广泛筛选。如果查询形式关系到正确性或扩展能力，请核实相关的索引策略。

优先使用本地参考指南

函数指南

适用场景：编写或修改 Convex 函数、设置 HTTP 端点、定义验证器、注册函数、设计 API 结构、处理分页，或在 query、mutation、action、内部函数和 HTTP action 之间进行选择。

验证器指南

适用场景：定义参数或返回值验证器，尤其是整数、记录、联合类型或动态载荷。请注意，Convex 建议使用验证器以获得更强的类型保障，但并非所有情况下都要求使用。

架构指南

适用场景：创建或修改 convex/schema.ts、添加表、定义索引、处理 _id 和 _creationTime，或设计表之间的关系。

TypeScript 指南

适用场景：使用 Convex TypeScript 类型，尤其是 Id<>、Record、可辨识联合类型、生成的 API 类型、静态代码生成的权衡，或 Node 类型设置。

查询指南

适用场景：编写数据库查询、筛选结果、排序数据、使用分页，或分析由索引支持的访问模式。

Mutation 指南

适用场景：使用 ctx.db 更新、替换、插入或删除文档。

Action 指南

适用场景：编写调用外部 API、使用 Node 模块、执行向量搜索或协调非事务性工作的 action。

调度指南

适用场景：使用计划函数和周期性任务设置 cron 作业或计划任务。

文件存储指南

适用场景：处理上传、下载、生成文件、提供文件服务或管理文件元数据。

全文搜索指南

适用场景：使用 withSearchIndex 实现文本搜索。

迁移指南

适用场景：规划或运行迁移、处理架构演进，或使用此仓库的迁移快捷方式和全量运行工作流。

示例

适用场景：需要更完整的参考实现，包括架构设计、公共/内部函数和后台处理模式。

身份验证指南

适用场景：配置 Convex Auth、Clerk、Auth0、WorkOS/AuthKit、自定义 OIDC 或 JWT 提供方、在 Convex 中存储用户，或在函数中读取身份验证状态。

组件指南

阅读时机：安装、使用或编写 Convex 组件时。

AI 与 Agent 指南

阅读时机：使用 Convex Agent 组件、线程、工具、流式处理、RAG、用量跟踪、工作流、Convex MCP 服务或 AI 代码生成工作流时。

向量搜索指南

阅读时机：定义向量索引、生成嵌入或运行混合／向量检索时。

测试指南

阅读时机：添加后端测试、CI 覆盖率、本地后端测试或 convex-test 模拟时。

生产环境指南

阅读时机：编辑 convex.json、环境变量、预览部署、多仓库、日志流、异常报告或部署／运行时配置时。

客户端集成指南

阅读时机：将 Convex 接入 React、React Native、Next.js App Router、Next.js Pages Router、TanStack Start、Bun、Node.js、Python、Swift、Kotlin 或基于 OpenAPI 的客户端时。

当前文档中的实用指南

  1. 如果任务会影响公共 API 结构、生成的客户端、OpenAPI 输出或静态代码生成，强烈建议显式指定 args 和 returns 验证器。
  2. 如果任务仅涉及内部逻辑，且有意采用宽松的载荷类型，则可以使用有针对性的 v.any()，但应通过周围的辅助函数名称和类型明确标示信任边界。
  3. 如果任务涉及高级搜索，应尽早在全文搜索和向量搜索之间做出选择，因为两者的架构、索引和函数类型各不相同。
  4. 如果任务涉及前端集成，应选择特定框架的客户端文档，不要假设 React 的默认设置适用于所有场景。
  5. 如果任务涉及部署或 AI 工具，应先查阅 convex.json 和 CLI 文档，再制定项目级约定；当前 Convex 文档涵盖了其中的 functions、aiFiles、Node 运行时设置和静态代码生成选项。
  6. 如果本地参考文件缺少某项信息，请查阅 https://docs.convex.dev/llms-full.txt 以及你所用功能对应的具体链接页面。

评论

支持 Markdown