convex-components

使用 Convex Components 添加隔离的后端功能，并组合组件 API。 - **组件概览**：https://docs.convex.dev/components - **了解组件**：https://docs.convex.dev/components/understanding - **使用组件**：https://docs.convex.dev/components/using - **编写组件**：https://docs.convex.dev/components/authoring - **目录**：https://convex.dev/components 你应该查阅这些参考文件，了解特定组件的知识： - `references/agent.md` — Agent 组件：线程／消息、流式传输、工具、上下文、调试、用量跟踪和安装／设置。 - `references/rag.md` — RAG 组件：命名空间、add/search/generateText、筛选器、分块、提示词 RAG 与工具 RAG。 - `references/workpool.md` — Workpool 组件：入队、重试、onComplete、并行度、批处理、监控。 - `references/workflow.md` — Workflow 组件：持久化步骤、事件、重试、状态、取消／清理、限制。

心智模型

• 组件是相互隔离的微型后端，拥有自己的 schema、表、文件存储和函数。
• 除非显式传入，否则组件不得访问应用表、函数或环境变量。
• 对组件的调用与调用方处于同一事务中，但组件的变更属于子事务。

安装组件

• 安装软件包：npm i @convex-dev/<component>。
• 添加 convex/convex.config.ts：
  • import { defineApp } from "convex/server";
  • app.use(component)；若要使用多个实例，请使用 app.use(component, { name: "custom" })。
• 必须运行 npx convex dev 以生成组件代码。
• 通过 convex/_generated/api 中的 components.<name> 访问组件。

调用组件 API

• 使用 ctx.runQuery/Mutation/Action 和 components.<name>.<fn>。
• 不得从客户端直接调用组件的公开函数（它们是内部引用）。
• 查询仍具有响应性；变更仍具有事务性。

事务语义

• 顶层变更会将所有组件中的写入一并提交。
• 如果组件变更抛出异常，则只回滚该组件的写入；调用方可以捕获异常并继续执行。

组件 API 差异

• components.<name> 仅公开组件的公开函数。
• Id 类型跨越边界时会变为 string；不得对外部表使用 v.id("table")。
• 每个组件都有自己的 _generated 目录；必须使用应用的 components 引用。

环境变量

• 组件不得直接访问 process.env。
• 必须由应用将环境变量值作为参数传入，或将配置存储在组件表中。

HTTP Actions

• 组件不得直接公开路由；应用必须在 convex/http.ts 中挂载处理程序。

组件中的身份验证

• 组件函数中无法使用 ctx.auth。
• 必须在应用中进行身份验证，并将标识符（userId）传递给组件函数。

分页

• 组件中不支持内置的 .paginate()。
• 如有需要，应该使用 convex-helpers 分页器以及来自 convex-helpers 的 usePaginatedQuery。

编写组件

• 组件文件夹必须包含 convex.config.ts、schema.ts、函数和 _generated。
• defineComponent("name") 用于定义组件；使用 component.use(...) 添加子组件。
• 本地组件可以放在 convex/components/ 或任意文件夹中。
• NPM 组件应该导出：
  • @pkg/convex.config.js
  • @pkg/_generated/component.js
  • @pkg/test 测试辅助工具

函数句柄

• 应该使用 createFunctionHandle(api.foo.bar) 在边界间传递回调。
• 句柄是字符串；使用 v.string() 验证器，并将其转换回 FunctionHandle。

测试组件

• 应该使用组件 schema／模块或提供的测试辅助工具，通过 convex-test 注册组件。
• 对于组件软件包，应该使用 @pkg/test 注册辅助工具。

### 最佳实践 - 你 MUST 始终验证公开组件函数的参数和返回值。 - 重新导出组件 API 时，你 SHOULD 优先使用应用级封装来添加身份验证／速率限制。 - 对于静态配置，你 SHOULD 使用单行全局变量／配置表。