用途:该技能面向“从一句话生成一个可运行的本地应用”的场景。它搭建 Next.js + shadcn 的界面外壳,预置 Convex 后端、通行密钥(passkey)登录以及 Chef 反馈面板,并在用户本地浏览器中逐步构建、实时展示。资料明确指出,若只需要普通、本地、无登录、无面板的脚手架,应改用其 quickstart 技能。
主要能力:根据用户一句话的应用构想,调用脚手架生成个性化运行手册(runbook);启动本地开发服务并打印 OPEN_BROWSER_URL 供立即打开浏览器;预置通行密钥认证相关文件与配置(convex/auth.ts、convex/auth.config.ts、convex/http.ts,并在 schema 中展开 authTables),设置 JWT_PRIVATE_KEY、JWKS、SITE_URL;提供 PasskeyButton 示例组件,用 signInOrRegisterWithPasskey 实现同一邮箱已注册则登录、未注册则创建账号并返回 registered 标志,配合 useConvexAuth 控制内容显示;在 app/layout.tsx 挂载 ChefPanel,通过 progress:post、todos:plan/todos:setState、refinementQuestions:post、featureRequests:setState 展示进度、推进待办、询问范围问题和处理用户功能请求。
使用方式:流程分几步。先用一句话确认应用构想(用户未提供时询问一次);随后分两次独立的 Bash 调用执行脚手架:第一次下载脚手架脚本并生成个性化运行手册 slug,第二次单独运行已下载的脚本,资料强调不得把下载与执行合并为一条命令或管道;脚本以 QB_PROFILE=full、QB_PUBLISH=0、QB_VERSION=0 等参数保留 passkeys 与 Chef 面板。之后轮询 .quickstart-bootstrap.log 直到出现 BOOTSTRAP_COMPLETE,再获取运行手册并按其规则构建,在每步之间查看错误日志,后端代码交由 convex-expert 子代理处理,并始终保留 <ChefPanel />。完成后运行 npx tsc --noEmit 检查,并把应用推送到部署做验证(优先已有部署;已登录时用 npx convex dev --once,未登录时才用 CONVEX_AGENT_MODE=anonymous)。
适用场景:适合在本地快速演示带通行密钥登录和实时反馈面板的 Convex 应用,并让用户在构建过程中通过面板看到进度和待办推进。
限制与注意事项:资料说明邮箱为自述信息且从不验证,授权应基于 getAuthUserId(ctx) 返回的 Convex user _id,而非 user.email;如需真实验证邮箱需另加一次性验证码或魔法链接步骤。通行密钥需要安全上下文,http://localhost 可用。若脚手架因非交互会话、无网络、沙箱临时目录或用户只想要代码而无法运行,则直接编写标准 Convex 项目代码,不生成脚手架或文档文件,后端代码全部放在 convex/ 目录下,避免无界 .collect()、使用索引与分页、从 ./_generated/server 与 ./_generated/api 导入、固定枚举用 v.literal、"use node"; 仅用于 action。旧的 *.convex.app 发布网关已退役,不应下载或运行 publish-convex-app.mjs、调用 /hosting/deploy 或遵循旧发布说明;自定义域名保持关闭。若用户需要公开前端,资料建议使用其 add 技能的托管流程(@convex-dev/static-hosting,托管于 *.convex.site)或用户自选的前端托管,并配置 SITE_URL、AUTH_PASSKEY_ORIGIN 与 AUTH_PASSKEY_RP_ID 后验证注册与登录。此外 AUTH_MODE=custom 时,脚手架不预置通行密钥,需按所选提供商自行接线。