从一句话想法快速启动本地 Convex + Web…

在需要极简、本地、匿名后端且不发布、不预置认证的 Convex + Next.js 模板时，从一个想法生成可运行项目并验证后端可 push。

适用场景

解决思路

1. 运行 recipe `quickstart-recipe@^2`，传入 `{idea, template}`；pack 会拉取并缓存该 recipe，并提供固定离线兜底。该步骤创建项目、安装依赖、启动后端（匿名）和 Web dev server。
2. 当 recipe 打印 dev URL 后，为用户打开它。
3. 在模板之外构建功能前，先给出简短计划并让用户确认。
4. 如果 recipe 已报告成功，绝不再重新运行。
5. 将任何位于 `convex/` 下的代码委托给 `convex-expert` capability。
6. 不要添加 Postgres/Redis/Express；使用 Convex primitives。
7. 不要在这里添加 hosting/publish 或预置 auth；除非用户要求更多，否则保持模板最小化。
8. 降级规则：如果 scaffold 无法运行（非交互式会话、无网络、沙盒临时目录，或用户只想要代码而不是应用），跳过 recipe，直接写标准 Convex 项目。
9. 降级时，所有后端代码都放在 `convex/` 下（`schema.ts`、functions）；绝不要放在项目根目录；Convex functions 只能从 `convex/` 目录运行。
10. 降级时，写零个 scaffold/documentation 文件（不要 `START_HERE.md`、`ARCHITECTURE.md`、`MANIFEST.txt`、README 墙），除非明确要求；“Build me a backend” 意味着代码，不是仪式。
11. 在写任何 `convex/*.ts` 之前：绝不要对可能增长的表做无界 `.collect()`；使用 `.withIndex(...)` 和 `.paginate(...)`/`.take(n)`。
12. 对任何相当于 SQL WHERE 的条件使用索引，而不是 `.filter()`。
13. `.withIndex(...)` 回调只有 `eq`/`gt`/`gte`/`lt`/`lte`；没有 `.range(...)` 方法。
14. 导入：`query`/`mutation`/`action`/`internalQuery`/`internalMutation`/`internalAction` 来自 `./_generated/server`；`api`/`internal` 来自 `./_generated/api`；应用代码中绝不要从 `convex/server` 导入。
15. 对固定字符串/enum 成员使用 `v.literal("exact value")`，不要用裸字符串。
16. `"use node"` 只能放在仅 action 的模块顶部；绝不要放在同时导出 `query` 或 `mutation` 的文件中。
17. 绝不要将 Node 内建模块（`crypto`/`fs`/`path`/`http`/`child_process`/`os`，带或不带 `node:` 前缀）导入缺少 `"use node"` 的文件——包括 `http.ts` route handlers；尽可能使用 Web Crypto（`crypto.subtle`）而不是 `import` `crypto`。
18. 保留名：绝不要用 `export const <jsReservedWord> = ...`（例如 `delete`、`new`、`class`、`function`、`return`）作为 query/mutation/action 导出名；esbuild 会解析失败。
19. 绝不要让表名或索引名以 `_` 开头（例如 `_migrations: defineTable(...)`）；`_` 是保留的，push 时会报 `TableNameReserved`/`IndexNameReserved`。
20. HTTP routes：`httpRouter` 没有 Express 风格的 `:param` 段（`path: "/users/:id"` 只匹配该字面字符串，是死代码）；使用 `pathPrefix` 并自行解析尾部段。
21. 每个 `http.route({...})` 的 `handler:` 必须用来自 `./_generated/server` 的 `httpAction(...)` 包装；裸 `async (ctx, request) => {...}` 能通过类型检查但不是有效 HTTP action。
22. `ctx.runQuery`/`ctx.runMutation`/`ctx.runAction` 需要 codegen 后的 function reference（`api.foo.bar`/`internal.foo.bar`），绝不要用原始导入的模块成员（`import * as queries from "./queries"; ctx.runQuery(queries.getX, ...)` 能编译但运行时报错）。
23. 自验证规则：在声明后端工作完成前，验证它可编译并可 push：运行 `npx tsc --noEmit` 并 push 到一个 deployment。
24. 自验证时优先使用项目已有的 deployment；否则当 `npx convex whoami` 成功时运行 `npx convex dev --once`，仅当它不成功时运行 `CONVEX_AGENT_MODE=anonymous npx convex dev --once`。
25. 在已登录用户上强制 anonymous 会重新绑定 `.env.local`，并让其失去所期望的持久、可发布云 deployment。
26. 完成前修复验证报告的所有错误；一轮验证可捕获错误相对导入/重复符号/括号不平衡这类否则会破坏 deploy 的问题。

适用边界 · 注意事项

• recipe 已报告成功时，不要再次运行 recipe。
• 项目不是 Convex + Web/Next.js，或后端必须使用 Postgres/Redis/Express 时。
• 用户明确要求 hosting/publish、预置 auth 或超出极简模板的生产基础设施时。