用途
convex-quickstart 是一个用于快速启动 Convex + Web 项目的代理技能。它面向的是从一句话想法出发,在本地搭建一个可运行的极简 Next.js + Convex 模板的场景。该技能的目标是提供一个基础骨架,并附带匿名开发部署,让用户能够立即在浏览器中访问开发中的 Web 应用。
主要能力
- 根据用户提供的想法和模板参数,运行 quickstart-recipe@^2 配方。该配方会拉取并缓存所需内容,并带有固定的离线回退方案。
- 自动创建项目、安装依赖、启动后端(匿名模式)以及启动 Web 开发服务器。
- 打印开发 URL,供用户打开查看运行效果。
- 在模板之上构建更多功能之前,展示简短计划并请求用户确认。
- 遵循大量内置开发规则,涵盖代码组织、数据访问、导入、命名、HTTP 路由以及自我验证等方面。
使用方式
技能的工作流是:运行配方 quickstart-recipe@^2,并传入 {idea, template} 参数。配方负责创建项目、安装依赖、启动后端和前端开发服务器。当开发 URL 打印出来后,打开该地址即可查看运行中的应用。如果用户希望在模板之外继续构建功能,技能会先呈现一个简短的计划并要求确认。技能还包含降级规则:如果脚手架无法运行(例如非交互会话、无网络、沙箱临时目录,或用户只想要代码而非应用),则跳过配方,直接编写标准 Convex 项目。此时所有后端代码必须放在 convex/ 目录下,绝不放在项目根目录,并且除非明确要求,不编写任何脚手架或文档文件。
开发规则与限制
技能内置了多项严格规则:
- 永不重复运行已报告成功的配方。
- 任何位于 convex/ 下的代码都应委托给 convex-expert 能力处理。
- 不添加 Postgres、Redis 或 Express,而是使用 Convex 原生原语。
- 不添加托管、发布或预置身份认证,除非用户明确要求。
- 数据访问方面:禁止对可能增长的表使用无界 .collect(),必须使用 .withIndex(...) 和 .paginate(...)/.take(n)。对于类似 SQL WHERE 的场景,使用索引而非 .filter()。.withIndex(...) 回调仅支持 eq、gt、gte、lt、lte,没有 .range(...) 方法。
- 导入方面:query、mutation、action、internalQuery、internalMutation、internalAction 从 ./_generated/server 导入;api、internal 从 ./_generated/api 导入;绝不在应用代码中从 convex/server 导入。固定字符串或枚举成员使用 v.literal("exact value"),而非裸字符串。"use node" 仅用于仅含 action 的模块顶部,绝不用于同时导出 query 或 mutation 的文件。
- 保留名称:绝不导出 JS 保留字作为 query/mutation/action 的导出名,例如 delete、new、class、function、return,否则 esbuild 解析失败。表名或索引名不得以 _ 开头,例如 _migrations,否则在推送时会报 TableNameReserved 或 IndexNameReserved 错误。
- HTTP 路由:httpRouter 不支持 Express 风格的 :param 路径段,path: "/users/:id" 只会匹配该字面字符串,属于死代码;应使用 pathPrefix 并自行解析尾部段。每个 http.route({...}) 处理函数必须用来自 ./_generated/server 的 httpAction(...) 包装。
- ctx.runQuery/ctx.runMutation/ctx.runAction 需要代码生成后的函数引用,即 api.foo.bar 或 internal.foo.bar,绝不能使用原始导入的模块成员。
- 自我验证:在宣布后端工作完成之前,必须验证其编译并推送。运行 npx tsc --noEmit 并推送到部署。优先使用项目已有的部署;否则在 npx convex whoami 成功时运行 npx convex dev --once,仅在失败时使用 CONVEX_AGENT_MODE=anonymous npx convex dev --once。修复所有报告的错误后再收尾。
适用场景
适用于需要快速启动一个极简 Convex + Next.js 项目骨架,并希望在本地匿名开发部署中立即查看运行效果的场景。也适用于用户明确只想要标准 Convex 项目代码,而不需要运行脚手架的情况。
限制
该技能刻意保持模板最小化,不包含发布步骤和预置身份认证。默认不添加托管或发布能力。如果运行环境不支持交互式会话、没有网络或处于沙箱临时目录,将触发降级规则,跳过配方并直接编写代码。