convex-runtime

实现 Convex 运行时功能：HTTP 操作、文件存储、搜索（全文搜索 + 向量搜索）和调度。 - **HTTP 操作**：https://docs.convex.dev/functions/http-actions - **文件存储**：https://docs.convex.dev/file-storage - **上传文件**：https://docs.convex.dev/file-storage/upload-files - **提供文件**：https://docs.convex.dev/file-storage/serve-files - **文件元数据**：https://docs.convex.dev/file-storage/file-metadata - **全文搜索**：https://docs.convex.dev/search/text-search - **向量搜索**：https://docs.convex.dev/search/vector-search - **调度**：https://docs.convex.dev/scheduling - **已调度函数**：https://docs.convex.dev/scheduling/scheduled-functions - **Cron 作业**：https://docs.convex.dev/scheduling/cron-jobs - 全文搜索：使用 `searchIndex`，配合 `searchField` 和可选的 `filterFields`；按相关性排序；对最后一个词进行前缀匹配；模糊匹配已弃用；限制为 16 个词、8 个筛选条件、扫描 1024 条。 - 向量搜索：使用 `vectorIndex`，配合 `vectorField` 和 `dimensions`（2-4096）；向量字段为 `v.array(v.float64())`；仅限操作中使用；限制为 256 条结果、64 个筛选条件、每个表 4 个向量索引。 - 调度：已调度函数具有持久性并存储在数据库中；Cron 作业按固定计划运行；身份验证不会传递，你必须显式传递身份。 - 文件存储：大文件使用上传 URL；通过 HTTP 操作上传的文件大小限制为 20MB；元数据存储在 `_storage` 中。

运行时操作

• HTTP 操作：使用 httpAction 定义处理程序，并通过 httpRouter 在 convex/http.ts 中注册（必须使用默认导出）。
• HTTP 语法：

  http.route({
    path: "/api/echo", // Exact path
    method: "POST",
    handler: httpAction(async (ctx, req) => {
      const body = await req.bytes();
      return new Response(body, { status: 200 });
    }),
  });
  

• HTTP 操作必须公开在 https://<deployment>.convex.site 上。
• 上传 URL 流程：生成 URL 的 mutation → 客户端 POST → 存储 storageId；URL 在 1 小时后过期。
• HTTP 上传流程：先调用 ctx.storage.store(blob)，再调用 mutation。通过 HTTP 操作上传的文件大小限制为 20MB。
• 提供文件：在查询或 mutation 中调用 ctx.storage.getUrl(storageId)；返回签名 URL 或 null。
• 文件元数据：使用 ctx.db.system.get("_storage", id) 或 query("_storage")；storage.getMetadata() 已弃用。
• 调度：使用 ctx.scheduler.runAfter/runAt；在 convex/crons.ts 中使用 cronJobs() 定义 Cron 作业。
• Cron 调度：必须使用 crons.interval 或 crons.cron。不得使用 crons.hourly、crons.daily 或 crons.weekly 等已弃用的辅助函数。
• Cron 内部调用：如果 Cron 调用内部函数，即使该函数定义在同一文件中，也必须从 _generated/api 导入 internal 对象来引用它。

核心规则

• HTTP 操作只能通过 convex/http.ts 的默认导出进行路由。
• HTTP 操作不支持验证器，因此必须手动解析 Request。
• 搜索示例：

  const messages = await ctx.db.query("messages")
    .withSearchIndex("search_body", (q) =>
      q.search("body", "hello hi").eq("channel", "#general")
    ).take(10);
  

• 向量搜索只能在操作中使用；结果不具备响应式。
• 搜索行为：全文搜索按相关性排序，并对最后一个词进行前缀匹配；模糊匹配已弃用。
• 应优先在索引定义和查询筛选条件中使用搜索/向量筛选器。
• 已调度函数的参数必须保持向后兼容。