convex-docs

拉取与当前版本匹配的 Convex 文档

convex-expert 内置了按插件版本管理的知识——稳定惯用法方面表现出色，但在最关键的地方会过时：组件新增了导出项、CLI 标志发生变化，或 API 在不同版本间更名。本能力是在此基础上增加的新鲜度保障：锁定项目实际使用的版本，以低成本获取实时页面的 Markdown 内容；只要当前源代码只需一次获取就能查到，就绝不凭记忆编写不熟悉的 API。

工作流

1. 锁定版本：读取已安装的 convex 版本（node -p "require('./node_modules/convex/package.json').version" 或 package.json），以及正在使用的任何 @convex-dev/* 组件的版本。你信任的文档必须与这些版本一致——版本不匹配是 Convex 代码出错的最大来源。
2. 新鲜度优先级（先选成本最低且正确的方式，遵循从 Supabase 总结出的顺序）： (a) 如果有可用的文档工具或 MCP search_convex_docs，就使用它（它会返回限定版本范围、经重新排序且适配上下文窗口大小的答案）； (b) 否则，以 Markdown 格式获取特定文档页面——请求 docs.convex.dev/<path>，如果网站提供 .md/Markdown 格式，优先使用这种格式（比 HTML 消耗的令牌少得多）；也可以获取锁定版本的组件 README； (c) 只有在此之后才使用通用网页搜索，并将搜索结果的版本视为未经验证。 当前性存疑时，不要跳过上述步骤，凭记忆编写 API。
3. 必要时对照已安装的包进行验证：如果不确定某个组件导出项是否存在，请检查 node_modules/@convex-dev/<x>/（其中的 package.json exports、.d.ts）——已安装的类型才是此版本的事实依据，比任何文档都更权威。
4. 有针对性地使用获取到的信息：应用当前的签名/标志，注明信息来源（页面 + 版本），并将实际代码交给 convex-expert，以便它按惯用方式编写。convex-docs 提供最新信息；convex-expert 提供惯用法。
5. 如果因版本不匹配而导致构建错误（某个导出项/标志“应该”存在但实际不存在）：将其视为当前性问题——锁定版本、获取当前 API 并修正，而不是猜测另一种拼写。

规则

• 当前性存疑时，绝不凭模型记忆编写不熟悉或可能已更名的 Convex/组件 API——先锁定版本并获取当前源代码。
• 已安装包在 node_modules 中自带的 exports/.d.ts 是此版本的事实依据，比任何文档页面都更权威。
• 遵循新鲜度优先级：可用的文档工具 → 页面 Markdown / 锁定版本的 README → 通用网页（未经验证）——先选成本最低且正确的方式，尽量减少令牌消耗。
• 优先使用 Markdown，而非 HTML 文档页面——相同内容所需的令牌少得多。
• 提供最新的事实；将惯用代码交给 convex-expert。这里是新鲜度保障层，并非对内置知识的替代。
• 版本不匹配导致的构建错误属于当前性问题，而不是拼写猜测——重新锁定版本并重新获取。