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 包含预置的、按插件版本固化的知识——非常适合稳定的惯用写法，但恰恰会在最关键的地方过时：某个组件新增了 export、CLI flag 发生变化，或者 API 在不同版本之间被重命名。该能力在其基础上叠加了时效性规范：锁定项目实际使用的版本，以较低成本将实时页面获取为 Markdown，并且当当前来源只需一次 fetch 即可获得时，绝不凭记忆编写不熟悉的 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/*
```
组件的版本。你信任的文档必须与这些版本匹配——version skew 是错误 Convex 代码的最大来源。
时效性层级（优先采用成本最低且正确的方式，沿用 Supabase 的顺序）： (a) 如果存在可用的文档服务工具 / MCP
```
search_convex_docs
```
，就使用它（它返回限定版本、重新排序且长度适配 context window 的答案）； (b) 否则，将特定文档页面获取为 MARKDOWN——请求
```
docs.convex.dev/<path>
```
，并在站点提供
```
.md
```
/markdown 形式时优先使用（相比 HTML 消耗的 token 少得多），或者使用锁定版本对应的组件 README； (c) 只有在此之后才回退到普通网页搜索，并将其版本视为未经验证。当对时效性存疑时，切勿直接凭记忆编写 API。
在必要时针对已安装的包进行验证：对于不确定是否存在的组件 export，检查
```
node_modules/@convex-dev/<x>/
```
（其
```
package.json
```
中的
```
exports
```
、其
```
.d.ts
```
）——已安装的类型才是此版本的 ground truth，比任何文档都更权威。
限定使用所获取的事实：应用当前的 signature/flag，注明来源（页面 + 版本），并将实际代码交回 convex-expert，让其以惯用方式编写。convex-docs 提供最新事实；convex-expert 提供惯用写法。
遇到版本不匹配导致的构建错误（某个“应该”存在却不存在的 export/flag）时：将其视为时效性问题——锁定版本、获取当前 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.

当对时效性存疑时，绝不要凭模型记忆编写不熟悉或可能已重命名的 Convex/组件 API——先锁定版本并获取当前来源。
```
node_modules
```
中已安装包自身的
```
exports
```
/
```
.d.ts
```
是此版本的 ground truth——比任何文档页面都更权威。
遵循时效性层级：文档服务工具 → 以 Markdown 形式获取页面 / 锁定版本的 README → 普通网页（未经验证）——优先采用成本最低且正确的方式，并使用尽可能少的 token。
优先使用 markdown，而不是 HTML 文档页面——相同内容消耗的 token 少得多。
提供最新事实；将符合惯用写法的代码交回 convex-expert。这是一层时效性机制，而不是对预置知识的替代。
版本不匹配导致的构建错误是时效性问题，而不是拼写猜测——重新锁定版本并重新获取。