用途：Convex Components 用于在 Convex 应用中添加隔离的后端功能，并组合组件 API，适用于安装组件、调用组件 API 和编写组件。
主要能力与心智模型：组件是隔离的迷你后端，拥有自己的 schema、表、文件存储和函数。除非显式传入，组件不得访问应用的表、函数或环境变量。对组件的调用与调用方处于同一事务，但组件内的 mutation 属于子事务。
安装：安装包使用 npm i @convex-dev/<component>。在 convex/convex.config.ts 中通过 defineApp 与 app.use(component) 注册；多实例可用 app.use(component, { name: "custom" })。必须运行 npx convex dev 生成组件代码，之后通过 convex/_generated/api 中的 components.<name> 访问。
调用：使用 ctx.runQuery/Mutation/Action 配合 components.<name>.<fn>。组件的公开函数不得由客户端直接调用（它们是内部引用）。查询保持响应式，mutation 具有事务性。顶层 mutation 会一起提交跨组件的所有写入；若组件 mutation 抛错，仅回滚其自身写入，调用方可以捕获并继续。
差异与限制：components.<name> 只暴露组件的公开函数；Id 类型跨边界以字符串传递，外部表不得使用 v.id("table")；每个组件有自己的 _generated 目录，必须使用应用的 components 引用。组件不得直接访问 process.env，需由应用传参或存入组件表。组件不得直接暴露路由，需由应用在 convex/http.ts 挂载处理器。组件函数内没有 ctx.auth，需在应用内认证后把 userId 等标识传入。组件内不支持内置 .paginate()，如有需要应使用 convex-helpers 的 paginator 与 usePaginatedQuery。
编写组件：组件文件夹必须包含 convex.config.ts、schema.ts、函数和 _generated。用 defineComponent("name") 定义组件，子组件用 component.use(...)。本地组件可放在 convex/components/ 或任意文件夹。NPM 组件应导出 @pkg/convex.config.js、@pkg/_generated/component.js 及测试辅助。跨边界回调应使用 createFunctionHandle(api.foo.bar)，句柄是字符串，用 v.string() 校验后再转回 FunctionHandle。测试可用 convex-test 注册组件 schema/模块或提供的测试辅助；组件包应使用 @pkg/test 注册辅助。
最佳实践：公开组件函数必须校验参数与返回值；重新导出组件 API 时，建议在应用层包装以添加认证与限流；静态配置建议使用单行 globals/config 表。