convex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex

Convex backend skill with a bias toward safety, observability, and index-backed queries.

Convex后端技能，侧重安全性、可观测性和基于索引的查询。

Docs-First Rule (Blocking)

文档优先规则（强制）

Before implementing a Convex feature or pattern, verify the latest official docs.

Primary sources:

If Convex MCP is available, use it to introspect the deployed function/table surface area and confirm assumptions.

在实现任何Convex功能或模式之前，请查阅最新的官方文档。

主要来源：

如果Convex MCP可用，使用它来检视已部署的函数/表的表面范围并验证假设。

Environments (Dev / Preview / Prod)

环境（开发/预览/生产）

Convex projects typically have:

Dev deployments (your local
```
npx convex dev
```
sync target)
Preview deployments (branch/PR deployments, beta feature)
Production deployment

Use MCP

status

(if available) or the CLI to confirm which deployment you are connected to before making changes.

Convex项目通常包含：

开发部署（本地
```
npx convex dev
```
同步目标）
预览部署（分支/PR部署，用于beta功能）
生产部署

在进行更改之前，使用MCP的

status

命令（如果可用）或CLI确认当前连接的部署环境。

Components-First Rule

组件优先规则

Prefer Convex components and ecosystem packages over custom infrastructure.

Start at:

https://docs.convex.dev/components
```
references/ecosystem.md
```

优先使用Convex组件和生态系统包，而非自定义基础设施。

参考起点：

https://docs.convex.dev/components
```
references/ecosystem.md
```

Core Rule (Blocking)

核心规则（强制）

Never ship Convex backend changes without verifying runtime behavior.

Preferred verification order:

Convex MCP logs (structured, diffable)
```
npx convex dev
```
terminal logs
Convex Dashboard logs

永远不要在未验证运行时行为的情况下发布Convex后端变更。

推荐的验证顺序：

Convex MCP日志（结构化、可对比）
```
npx convex dev
```
终端日志
Convex Dashboard日志

Project Conventions (Preferred)

项目约定（推荐）

Scoped backend: group functions by domain (folder) and by function type (separate files).
Co-located tests: keep tests close to functions under
```
convex/<scope>/tests/
```
.
Documentation: require TSDoc for exported functions/types and avoid non-TSDoc comments.

See

references/style.md

and

references/testing.md

作用域化后端：按领域（文件夹）和函数类型（单独文件）对函数进行分组。
测试代码同目录存放：将测试代码放在
```
convex/<scope>/tests/
```
目录下，与对应函数靠近。
文档规范：导出的函数/类型必须添加TSDoc注释，避免使用非TSDoc注释。

详情请见

references/style.md

和

references/testing.md

。

Router

路由规则

User says	Load reference	Do
help / cli help / usage	`references/cli-help.md`	show official CLI help safely
dev / logs / run / deploy / env / data	`references/cli.md`	common CLI workflows
mcp / tools / introspect / logs	`references/mcp.md`	use Convex MCP tools
tsdoc / docs / style	`references/style.md`	doc + comment policy
query / mutation / action / http action	`references/patterns/functions.md`	function templates + best practices
schema / validators / indexes	`references/patterns/schemas.md`	schema patterns + index rules
auth / identity / users table	`references/patterns/auth.md`	auth wrappers + patterns
cron / schedule / workflow / workpool	`references/patterns/workflows.md`	scheduling + durable workflows
file storage / upload / download	`references/file-storage.md`	file storage patterns
http / webhook	`references/patterns/http.md`	httpRouter/httpAction patterns
testing	`references/testing.md`	testing patterns
ecosystem / components	`references/ecosystem.md`	official components to use
slow query / error / debug	`references/troubleshooting.md`	troubleshooting + anti-patterns
validate / checklist	`checklists/validation.md`	blocking checks before shipping

用户输入	加载参考文档	执行操作
help / cli help / usage	`references/cli-help.md`	安全展示官方CLI帮助文档
dev / logs / run / deploy / env / data	`references/cli.md`	常见CLI工作流
mcp / tools / introspect / logs	`references/mcp.md`	使用Convex MCP工具
tsdoc / docs / style	`references/style.md`	文档与注释规范
query / mutation / action / http action	`references/patterns/functions.md`	函数模板与最佳实践
schema / validators / indexes	`references/patterns/schemas.md`	模式设计与索引规则
auth / identity / users table	`references/patterns/auth.md`	认证封装与模式
cron / schedule / workflow / workpool	`references/patterns/workflows.md`	调度与持久化工作流
file storage / upload / download	`references/file-storage.md`	文件存储模式
http / webhook	`references/patterns/http.md`	httpRouter/httpAction模式
testing	`references/testing.md`	测试模式
ecosystem / components	`references/ecosystem.md`	官方可用组件
slow query / error / debug	`references/troubleshooting.md`	故障排查与反模式
validate / checklist	`checklists/validation.md`	发布前的强制检查项

MCP Integration (Recommended)

MCP集成（推荐）

If Convex MCP is available, use it first.

If Convex MCP is not available, this skill still works:

Use the Convex CLI (
```
npx convex ...
```
) and the dashboard.
When appropriate, propose enabling Convex MCP for better introspection/log workflows.
Discover deployments:
```
convex_status({ projectDir })
```

Inspect functions:

convex_functionSpec({ deploymentSelector })

Inspect tables:
```
convex_tables({ deploymentSelector })
```

Read data:

convex_data({ deploymentSelector, tableName, ... })

Run functions:

convex_run({ deploymentSelector, functionName, args })

Run safe ad-hoc reads:

convex_runOneoffQuery({ deploymentSelector, query })

Verify logs:

convex_logs({ deploymentSelector, ... })

Full workflow:

references/mcp.md

如果Convex MCP可用，优先使用它。

如果Convex MCP不可用，本技能仍然有效：

使用Convex CLI（
```
npx convex ...
```
）和控制台。
适当时，建议启用Convex MCP以获得更好的检视/日志工作流。
发现部署环境：
```
convex_status({ projectDir })
```

检视函数：

convex_functionSpec({ deploymentSelector })

检视表：
```
convex_tables({ deploymentSelector })
```

读取数据：

convex_data({ deploymentSelector, tableName, ... })

运行函数：

convex_run({ deploymentSelector, functionName, args })

运行安全的临时查询：

convex_runOneoffQuery({ deploymentSelector, query })

验证日志：

convex_logs({ deploymentSelector, ... })

完整工作流请见：

references/mcp.md

。

Critical Rules (7)

关键规则（7条）

Always use validators (
```
args
```
+
```
returns
```
) for functions.
Always use explicit table names with
```
ctx.db.get/patch/replace
```
.
Prefer index-backed queries (
```
withIndex
```
) and bounded reads (
```
take
```
/pagination).
User identity comes from
```
ctx.auth
```
, never from args.
Use
```
internal*
```
functions for sensitive operations.
Schedule only internal functions.
Use
```
v.null()
```
for void returns (return
```
null
```
).

始终为函数使用验证器（
```
args
```
+
```
returns
```
）。
在使用
```
ctx.db.get/patch/replace
```
时始终使用明确的表名。
优先使用基于索引的查询（
```
withIndex
```
）和有限读取（
```
take
```
/分页）。
用户身份信息来自
```
ctx.auth
```
，绝不能来自参数。
对敏感操作使用
```
internal*
```
函数。
仅调度内部函数。
无返回值时使用
```
v.null()
```
（返回
```
null
```
）。

References

参考文档

Patterns:

```
references/patterns/schemas.md
```
```
references/patterns/functions.md
```
```
references/patterns/auth.md
```
```
references/patterns/workflows.md
```
```
references/patterns/http.md
```

Other:

```
references/mcp.md
```
```
references/cli.md
```
```
references/cli-help.md
```
```
references/style.md
```
```
references/file-storage.md
```
```
references/testing.md
```
```
references/ecosystem.md
```
```
references/troubleshooting.md
```

Checklist:
- ```
checklists/validation.md
```

模式相关：

```
references/patterns/schemas.md
```
```
references/patterns/functions.md
```
```
references/patterns/auth.md
```
```
references/patterns/workflows.md
```
```
references/patterns/http.md
```

其他：

```
references/mcp.md
```
```
references/cli.md
```
```
references/cli-help.md
```
```
references/style.md
```
```
references/file-storage.md
```
```
references/testing.md
```
```
references/ecosystem.md
```
```
references/troubleshooting.md
```

检查清单：
- ```
checklists/validation.md
```