Convex 开发中担心 API 版本过时？

在 Convex 项目中需要写或修正 Convex/组件 API 时，先按已安装版本获取最新文档和 node_modules 类型，避免凭记忆写过时代码。

适用场景

解决思路

1. 固定版本：读取已安装的 `convex` 版本（`node -p "require('./node_modules/convex/package.json').version"` 或 `package.json`），以及涉及的任何 `@convex-dev/*` 组件版本；你信任的文档必须匹配这些版本。
2. 按新鲜度层级选择来源（最便宜且正确优先）：如果可用的 served docs 工具 / MCP `search_convex_docs`，就用它，它会返回按版本限定、重排序、适配上下文窗口的答案。
3. 否则把具体文档页作为 MARKDOWN 获取：请求 `docs.convex.dev/<path>`，站点提供 `.md`/markdown 形式时优先用它，比 HTML token 少得多；或获取固定版本下组件的 README。
4. 只有到那时才退回通用 web 搜索，并把它给出的版本视为未经验证。
5. 当新鲜度存疑时，不要跳过上述来源凭记忆写 API。
6. 在关键处对照已安装包验证：对不确定是否存在的组件导出，检查 `node_modules/@convex-dev/<x>/`，包括它的 `package.json` `exports` 和 `.d.ts`；已安装的类型才是当前版本的 ground truth，比任何文档都权威。
7. 狭义使用取回的事实：应用当前签名/标志，注明来源（页面 + 版本），并把实际代码交回 `convex-expert` 以惯用方式编写；`convex-docs` 提供新鲜事实，`convex-expert` 提供惯用法。
8. 遇到版本不匹配的构建错误（某个导出/标志“本应”存在但不存在）时，把它当作新鲜度问题：重新固定版本、拉取当前 API 并修正，而不是猜测另一种拼写。
9. 当新鲜度存疑时，绝不要凭模型记忆写不熟悉或可能已改名的 Convex/组件 API；先固定版本并拉取当前来源。
10. 已安装包自身在 node_modules 中的 `exports`/`.d.ts` 是当前版本的 ground truth，比任何文档页都权威。
11. 遵循新鲜度层级：served docs 工具 → 页面-as-markdown / 固定版本 README → 通用 web（未验证）；最便宜且正确优先，token 最少优先。
12. 文档页优先用 markdown 而不是 HTML；同样内容 token 少得多。
13. 只提供新鲜事实；把惯用代码交回 `convex-expert`。这是新鲜度层，不替代已有内置知识。
14. 版本不匹配的构建错误是新鲜度问题，不是拼写猜测；重新固定版本并重新拉取。

适用边界 · 注意事项

• 不是 Convex 项目，或不涉及 Convex/`@convex-dev/*` 组件 API 时。
• API 已确定稳定、没有版本疑虑且只是编写成熟惯用法时，不必拉取实时文档。
• 没有安装包或文档访问且无法验证版本时，本技能的版本校验流程不适用。