convex-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pull version-current Convex docs

获取对应版本的Convex文档

convex-expert carries baked, plugin-versioned knowledge — excellent for stable idioms, but it goes stale exactly where it hurts: a component that gained a new export, a CLI flag that changed, an API renamed between versions. This capability is the freshness discipline layered on top: pin to the project's real version, fetch the live page cheaply as markdown, and never write an unfamiliar API from memory when the current source is one fetch away.

convex-expert 内置了与插件版本绑定的知识——这对于稳定的编程范式来说非常好用，但在关键场景下会过时：比如某个组件新增了导出项、CLI参数发生变更、不同版本间API重命名。本能力在此基础上增加了新鲜度管控机制：固定项目实际使用的版本，以低成本获取实时的markdown格式文档页面，再也不用凭记忆编写不熟悉的API，因为最新的资源只需一次请求就能获取。

Workflow

工作流程

PIN the version: read the installed
```
convex
```
version (
```
node -p "require('./node_modules/convex/package.json').version"
```
or
```
package.json
```
), and the versions of any
```
@convex-dev/*
```
components in play. The docs you trust must match THESE versions — version skew is the single largest source of wrong Convex code.
FRESHNESS HIERARCHY (cheapest-correct first, the Supabase-taught order): (a) if a served docs tool / MCP
```
search_convex_docs
```
is available, use it (it returns version-scoped, reranked answers sized to the context window); (b) else fetch the specific docs page as MARKDOWN — request
```
docs.convex.dev/<path>
```
and prefer a
```
.md
```
/markdown form when the site serves one (far fewer tokens than HTML), or the component's README at the pinned version; (c) only then fall back to a general web search, and treat its version as unverified. Do NOT skip to writing the API from memory when currentness is in doubt.
VERIFY against the installed package when it matters: for a component export you're unsure exists, check
```
node_modules/@convex-dev/<x>/
```
(its
```
package.json
```
```
exports
```
, its
```
.d.ts
```
) — the installed types are the ground truth for THIS version, more authoritative than any doc.
USE the fetched fact narrowly: apply the current signature/flag, cite where it came from (page + version), and hand the actual code back to convex-expert to write idiomatically. convex-docs supplies the fresh fact; convex-expert supplies the idiom.
On a version-mismatch build error (an export/flag that 'should' exist but doesn't): treat it as a currentness question — pin the version, fetch the current API, and correct — rather than guessing a different spelling.

固定版本：读取已安装的
```
convex
```
版本（使用
```
node -p "require('./node_modules/convex/package.json').version"
```
命令或查看
```
package.json
```
），以及当前使用的所有
```
@convex-dev/*
```
组件的版本。你信任的文档必须与这些版本匹配——版本偏差是导致Convex代码出错的最大单一原因。
新鲜度层级（遵循成本最低且最准确的顺序，由Supabase实践总结）： (a) 若有可用的文档服务工具/MCP
```
search_convex_docs
```
，优先使用（它会返回与版本绑定、重新排序后的结果，适配上下文窗口大小）； (b) 否则，获取特定文档页面的MARKDOWN格式——请求
```
docs.convex.dev/<path>
```
，优先选择网站提供的
```
.md
```
/markdown格式（相比HTML，所需token数量少得多），或对应固定版本组件的README； (c) 仅当以上方式都不可用时，才退而求其次使用通用网络搜索，并将搜索结果的版本视为未验证。当对API的时效性存疑时，绝不要直接凭记忆编写API。
关键场景下验证已安装包：若不确定某个组件导出是否存在，检查
```
node_modules/@convex-dev/<x>/
```
（查看其
```
package.json
```
中的
```
exports
```
字段或
```
.d.ts
```
类型文件）——已安装的类型是当前版本的最权威依据，比任何文档都可靠。
精准使用获取到的信息：应用当前的签名/参数，注明信息来源（页面+版本），然后将实际代码交给convex-expert以符合范式的方式编写。convex-docs提供最新信息；convex-expert提供符合规范的代码写法。
遇到版本不匹配的构建错误（某个“应该”存在的导出/参数实际不存在）：将其视为时效性问题——重新固定版本、获取当前API并修正，而非猜测其他拼写。

Rules

规则

Never write an unfamiliar or possibly-renamed Convex/component API from model memory when currentness is in doubt — pin the version and fetch the current source first.
The installed package's own
```
exports
```
/
```
.d.ts
```
in node_modules is the ground truth for this version — more authoritative than any doc page.
Follow the freshness hierarchy: served docs tool → page-as-markdown / pinned README → general web (unverified) — cheapest-correct first, fewest tokens.
Prefer markdown over HTML doc pages — far fewer tokens for the same content.
Supply the fresh FACT; hand idiomatic code back to convex-expert. This is a freshness layer, not a replacement for the baked knowledge.
A version-mismatch build error is a currentness question, not a spelling guess — re-pin and re-fetch.

当对API的时效性存疑时，绝不要凭模型记忆编写不熟悉或可能已重命名的Convex/组件API——先固定版本并获取最新资源。
已安装包在node_modules中的
```
exports
```
/
```
.d.ts
```
文件是当前版本的最权威依据——比任何文档页面都可靠。
遵循新鲜度层级：文档服务工具 → markdown格式页面/固定版本README → 通用网络搜索（未验证）——优先选择成本最低且最准确的方式，使用最少的token。
优先选择markdown格式而非HTML格式的文档页面——相同内容所需的token数量少得多。
提供最新信息；将符合范式的代码编写工作交给convex-expert。这是一个新鲜度管控层，而非内置知识的替代方案。
版本不匹配的构建错误是时效性问题，而非拼写猜测问题——重新固定版本并重新获取资源。