Drizzle ORM v1.0 深度拆解：当 TypeScript ORM 决定「用 JIT 把映射开销压到零」

从 JIT Row Mapper 到 Effect v4 原生集成，一个 35K Star 的无头 ORM 如何用「编译时 Schema + 运行时 JIT」重新定义 TypeScript 数据库访问的终极形态

一、引言：TypeScript ORM 的「不可能三角」

每个 TypeScript 开发者都面临过同一个灵魂拷问：选 Prisma 还是选 Drizzle？

Prisma 有漂亮的 DSL、完善的文档、庞大的社区，但越来越重、迁移成本越来越高、运行时开销让人不安。Drizzle 轻量、类型安全、接近 SQL，但年轻、生态还在追赶。2026 年五一假期，Drizzle ORM 扔出了一颗小炸弹——v1.0.0-rc.1 发布，官方随手贴了一张基准测试图：

• Drizzle + Bun：平均延迟 7.3ms，吞吐 8.8k req/sec
• Go v1.25.5：平均延迟 18.1ms，吞吐 8.2k req/sec

Bun 官方账号转发只配了一句话："faster than Go, uses Bun, Many such cases。" Evan You 也转了，说正好赶在 Void 公测前把依赖版本更新一下。

都 2026 年了，JavaScript 服务端比 Go 还快？这不是标题党，背后是 Drizzle 团队在 ORM 层面做的一次架构级革新。本文将从源码层面深度拆解 Drizzle ORM v1.0 的四大核心变化，特别是那个把 ORM 开销压到接近零的 JIT Row Mapper。

二、Drizzle ORM 的哲学：「无头 ORM」到底是什么

2.1 从「数据框架」到「无头 ORM」

在讨论 v1.0 的变化之前，必须先理解 Drizzle 的设计哲学。传统的 ORM（如 Prisma、TypeORM、Sequelize）本质上是「数据框架」——它们要求你围绕它们的 DSL、它们的迁移系统、它们的项目结构来构建项目。用 Prisma 的人必须用 prisma.schema，必须用 prisma generate，必须用它自己的查询 API。

Drizzle 走了一条完全不同的路：无头 ORM（Headless ORM）。

// Drizzle 的 Schema 定义：纯粹的 TypeScript
import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').unique(),
  fullName: text('full_name'),
  createdAt: timestamp('created_at').defaultNow(),
});

这段代码就是普通的 TypeScript，没有任何魔法。pgTable 返回的是一个类型化的对象，你可以用它来定义 schema、生成迁移、写查询——但你不需要被它绑定。Drizzle 不会强迫你用它的 CLI，不会在你的项目里生成一堆文件，不会要求你改变项目结构。

2.2 SQL-like 查询 API：知道 SQL 就知道 Drizzle

Drizzle 的查询 API 设计核心原则是：如果你知道 SQL，你就知道 Drizzle。

// SQL-like 查询：和写 SQL 几乎一样
const result = await db
  .select()
  .from(users)
  .leftJoin(posts, eq(posts.authorId, users.id))
  .where(eq(users.id, 10));

// 关系查询：更方便的方式
const result = await db.query.users.findMany({
  with: {
    posts: true,
  },
});

SQL-like API 让你用代码写 SQL，类型安全、可重构、可补全。关系查询 API 让你在需要嵌套数据时不用手写 JOIN。两种 API 生成的都是同一条 SQL 查询——Drizzle 保证永远只发出一条 SQL，这对 Serverless 数据库（如 PlanetScale、Neon、Turso）至关重要，因为每次查询都可能有网络往返成本。

2.3 零依赖的设计

Drizzle ORM 的另一个核心卖点是零依赖。在 npm 生态里，这是一个极其罕见的特性。大多数 ORM 都带着一堆运行时依赖，而 Drizzle 的核心包只有 TypeScript 类型和少量运行时代码。这意味着：

• 更小的包体积，更快的安装速度
• 更少的供应链攻击面
• 更容易部署到 Edge 环境（Cloudflare Workers、Deno Deploy、Vercel Edge Functions）
• 更容易 Tree-shake

三、v1.0.0-rc.1 四大核心变化

3.1 JIT Row Mapper：把 ORM 开销压到接近零

这是 v1.0 最核心的变化，也是那张基准测试图的技术来源。

3.1.1 传统 ORM 的开销从哪来

传统 ORM 每次查询完，都要把数据库返回的原始行（通常是数组格式）动态地映射成 JavaScript 对象。这个过程叫做 row mapping。

传统做法大致是这样的（伪代码）：

// 传统 ORM 的 row mapping（简化版）
function mapRow(row, schema) {
  const obj = {};
  for (const field of schema.fields) {
    // 动态查找字段名
    const dbValue = row[field.dbName];
    // 动态类型转换
    obj[field.name] = field.type.deserialize(dbValue);
    // 可能还有嵌套关系处理
    if (field.relation) {
      obj[field.name] = resolveRelation(row, field.relation);
    }
  }
  return obj;
}

每次查询都要循环遍历所有字段、做类型转换、处理关联关系。在高并发场景下，这个过程会积少成多，成为可见的性能损耗。尤其是当你的 Schema 有 20 个字段、每次查询返回 1000 行时，这个循环要执行 20,000 次。

3.1.2 Drizzle 的 JIT 解法

Drizzle 的 JIT Row Mapper 采用了完全不同的策略：在运行时针对你的具体 Schema 编译出一个专用的映射函数。

这个函数只处理你这张表的字段，不做任何通用化的动态判断，直接走最短路径。你可以理解成 JIT 编译器给你的 Schema 量身定制了一条快速通道，省掉了所有通用 ORM 框架里不必要的抽象层。

具体实现原理：

// Drizzle JIT Row Mapper 的工作原理（概念性代码）
// 第一次查询时，Drizzle 会为你的 Schema 生成一个专用函数

// 对于 users 表，生成的函数可能长这样：
function mapUsersRow(row) {
  return {
    id: row[0],           // 直接按索引访问，不用查找字段名
    email: row[1],
    fullName: row[2],
    createdAt: row[3],
  };
}

// 对于 posts 表，生成另一个专用函数：
function mapPostsRow(row) {
  return {
    id: row[0],
    title: row[1],
    content: row[2],
    authorId: row[3],
    createdAt: row[4],
  };
}

关键优化点：

1. 索引访问替代键查找：传统 ORM 用 row[fieldName] 动态查找，JIT 版本直接用 row[0]、row[1] 按索引访问，省掉了哈希查找的开销
2. 消除动态类型检查：传统 ORM 每次都要检查字段类型，JIT 版本在生成函数时就确定了类型转换逻辑
3. 内联化处理：把循环展开成直接赋值，消除了循环控制流的开销
4. Schema 特化：每个表生成一个专用函数，不做任何通用化判断

官方的说法是把 ORM overhead 压到接近 0，性能和手写 raw driver 代码一个量级。

3.1.3 JIT vs 代码生成：为什么选择运行时 JIT

你可能会问：为什么不用代码生成（如 Prisma 的 prisma generate）？代码生成不是也能消除运行时开销吗？

代码生成的方案确实能达到类似的性能，但有几个缺点：

1. 构建步骤：每次修改 Schema 都要重新生成代码，增加了开发循环的复杂度
2. 文件膨胀：生成的代码文件可能很大，增加代码审查和维护成本
3. 类型推导断裂：生成的代码和手写代码之间存在断层，IDE 补全和类型推导可能不够流畅
4. 部署复杂度：在 CI/CD 流程中需要额外的生成步骤

Drizzle 选择运行时 JIT 的原因：

1. 零构建步骤：Schema 就是代码，修改即生效
2. 按需编译：只有实际用到的表才会生成映射函数，不会浪费
3. 类型无缝：TypeScript 类型推导完全基于 Schema 定义，不需要中间生成层
4. 透明性：开发者可以看到完整的类型链路，没有魔法

3.1.4 JIT 的缓存策略

JIT Row Mapper 不是每次查询都重新编译的。Drizzle 内部维护了一个映射函数缓存：

// 概念性缓存策略
const mapperCache = new Map();

function getMapper(tableSchema) {
  const key = tableSchema[Symbol.for('drizzle:schema:hash')];
  if (mapperCache.has(key)) {
    return mapperCache.get(key);
  }
  const mapper = compileMapper(tableSchema);
  mapperCache.set(key, mapper);
  return mapper;
}

首次查询时编译，后续查询直接复用。这个缓存的生命周期和数据库连接绑定，连接断开时缓存自动失效。

3.2 Effect v4 原生集成

Effect 是 TypeScript 生态里的一个函数式编程库，提供类型安全的错误处理、依赖注入和并发管理。Effect v4 在 2026 年 7 月发布，Drizzle 同步跟进，提供了原生集成。

import { PgClient } from '@effect/sql-pg';
import * as PgDrizzle from 'drizzle-orm/effect-postgres';
import * as Effect from 'effect/Effect';

// 创建 Effect化的 Drizzle 实例
const DB = PgDrizzle.make({ relations }).pipe(
  Effect.provide(PgDrizzle.DefaultServices)
);

// 在 Effect 的 gen 函数中使用数据库
const program = Effect.gen(function*() {
  const db = yield* DB;
  const users = yield* db.select().from(usersTable);
  return users;
}).pipe(Effect.provide(PgClientLive));

await Effect.runPromise(program);

这个集成的意义在于：

1. 类型安全的错误处理：数据库查询的错误类型会在 Effect 的类型系统中传播，不需要手动 try/catch
2. 依赖注入：数据库连接可以通过 Effect 的依赖注入系统管理，便于测试和配置切换
3. 并发管理：利用 Effect 的并发原语，可以安全地并行执行多个数据库查询
4. 可观测性：Effect 自带 tracing 支持，可以追踪数据库查询的性能

对没接触 Effect 的人来说这个特性可以先跳过，但如果你的项目已经在用 Effect，这次集成补上了一块重要的缺口。

3.3 Casing API 重构（Breaking Change）

之前 Drizzle 处理字段命名风格转换（camelCase 和 snake_case 互转）的方式比较分散，这次统一了。

// 新的 casing API：在创建 table 时直接声明命名策略
import * as d from "drizzle-orm/pg-core";

// snake_case 策略：fullName 在数据库里存为 full_name
const users = d.snakeCase.table("users", {
  id: d.serial().primaryKey(),
  email: d.text().unique(),
  fullName: d.text(),  // 自动映射为 full_name
  createdAt: d.timestamp().defaultNow(),  // 自动映射为 created_at
});

// 整个 schema 统一用 camelCase
const schema2 = d.camelCase.schema("schema2");
const usersInSchema2 = schema2.table("users", {
  id: d.serial().primaryKey(),
  // ...
});

逻辑更清晰了，但如果你的现有项目用了旧的 casing 配置方式，升级前务必仔细读一遍官方迁移说明。这是一个 breaking change，不能自动迁移。

3.4 Drizzle for LLM Agents（Preview）

这个特性还在预览阶段，目标是让 LLM Agent 可以直接理解和操作 Drizzle 管理的数据库结构。

具体思路是：Drizzle Schema 本身就是类型化的 TypeScript 代码，可以被 LLM 直接解析。通过在 Schema 中添加语义化的注释和元数据，可以让 Agent 理解每个字段的业务含义，从而生成更准确的查询。

// 概念性示例：为 LLM Agent 增强的 Schema
export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').unique()
    .$comment('User login email, must be unique'),
  fullName: text('full_name')
    .$comment('User display name, shown in UI'),
  role: text('role', { enum: ['admin', 'user', 'guest'] })
    .$comment('User permission level: admin has full access'),
  createdAt: timestamp('created_at').defaultNow()
    .$comment('Account creation timestamp'),
});

这个方向很有意思——让 AI Agent 通过理解 Schema 来操作数据库，而不是通过固定的 API。但目前还在 preview 阶段，具体实现细节尚未公开。

四、那张基准测试，到底怎么看

4.1 测试配置分析

官方 benchmark 的配置是：

• JavaScript 侧：Bun v1.3.13 + Bun SQL + Drizzle JIT Row Mapper
• Go 侧：Go v1.25.5 + 数据库驱动（推文里没有明确列出 Go 那侧用的是哪个 ORM 和框架配置）
• 测试场景：完整的 HTTP 服务端场景（从接收请求到返回响应）

结果：

4.2 延迟差距的来源

Drizzle + Bun 的延迟优势主要来自三个方面：

1. JIT Row Mapper：消除了 ORM 层的映射开销，这是 Drizzle 自身的优化
2. Bun SQL：Bun 内置的 SQL 客户端对数据库连接和查询做了底层优化，减少了 JavaScript 和数据库之间的通信开销
3. Bun 运行时：Bun 的 HTTP 服务器和事件循环实现比 Node.js 更高效

4.3 不能忽视的代价

CPU 负载数据揭示了一个重要事实：Drizzle 侧 81.6%，Go 侧 75.5%，Drizzle 多消耗了大约 6 个百分点的 CPU 换来更低的延迟。

换句话说，这不是免费的，是用算力换响应速度。在 CPU 密集型的场景下，这个差距可能会缩小甚至反转。

4.4 Go 那侧的配置不透明

这份 benchmark 是 Drizzle 自己跑的，Go 那侧的具体配置不透明。Go 社区有人指出：

• Go 那侧可能没有做充分的性能调优（如连接池配置、GC 调优）
• 可能没有使用最优的 Go ORM 框架
• 测试的可能是特定场景下的表现，不代表所有场景

拿来当参考可以，直接下"JS 比 Go 快"的结论还是谨慎一点。但不管怎么说，Drizzle + Bun 能跑出这个水平，放在两三年前几乎是不可能的事。

五、Drizzle vs Prisma：2026 年的选择指南

5.1 Prisma 的困境

Prisma 最近处境确实有些尴尬。v7 做了一堆更新，但社区对它的路线出现了分歧：

1. 越来越重：Prisma 的运行时依赖越来越多，包体积越来越大
2. 迁移成本增加：从 v5 到 v6 到 v7，每次大版本升级都有不少 breaking change
3. 性能天花板：Prisma 的查询引擎是 Rust 编写的，但 TypeScript 层的开销仍然可见
4. DSL 的代价：Prisma 的 Schema DSL 和查询 API 虽然优雅，但和 SQL 的差距让习惯 SQL 的开发者感到不适

5.2 Drizzle 的优势

Drizzle 正好踩在了 Prisma 开始失分的地方：

1. 轻量：零依赖，包体积小，部署到 Edge 无障碍
2. 类型安全：基于 TypeScript 的 Schema 定义，类型推导完整
3. 接近 SQL：学习曲线平滑，容易知道最终执行的是什么 SQL
4. 性能：JIT Row Mapper 把 ORM 开销压到接近零

5.3 Prisma 仍然有优势的场景

公平地说，Prisma 在某些方面仍然有优势：

1. 文档和社区：Prisma 的文档更完善，社区更大，遇到问题更容易找到答案
2. 复杂关联关系：Prisma 在处理复杂的关系查询和数据建模上更成熟
3. 数据库迁移工具：Prisma Migrate 是目前最成熟的 TypeScript 数据库迁移工具之一
4. GUI 工具：Prisma Studio 提供了可视化的数据管理界面

5.4 选型建议

六、实战：从零搭建 Drizzle + Bun + Hono 全栈项目

6.1 项目初始化

# 创建项目
mkdir drizzle-bun-hono && cd drizzle-bun-hono
bun init

# 安装依赖
bun add drizzle-orm postgres
bun add -d drizzle-kit @types/bun

6.2 定义 Schema

// src/db/schema.ts
import { pgTable, serial, text, timestamp, integer, boolean } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

// 用户表
export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').unique().notNull(),
  fullName: text('full_name').notNull(),
  avatarUrl: text('avatar_url'),
  isActive: boolean('is_active').default(true),
  createdAt: timestamp('created_at').defaultNow(),
  updatedAt: timestamp('updated_at').defaultNow(),
});

// 文章表
export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
  content: text('content').notNull(),
  published: boolean('published').default(false),
  authorId: integer('author_id').references(() => users.id),
  createdAt: timestamp('created_at').defaultNow(),
  updatedAt: timestamp('updated_at').defaultNow(),
});

// 定义关系
export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, {
    fields: [posts.authorId],
    references: [users.id],
  }),
}));

6.3 配置数据库连接

// src/db/index.ts
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema';

const connectionString = process.env.DATABASE_URL!;

// postgres.js 客户端
const client = postgres(connectionString);

// Drizzle 实例，带 schema 类型信息
export const db = drizzle(client, { schema });

6.4 编写 API 路由

// src/index.ts
import { Hono } from 'hono';
import { db } from './db';
import { users, posts } from './db/schema';
import { eq, desc } from 'drizzle-orm';

const app = new Hono();

// 获取所有用户
app.get('/api/users', async (c) => {
  const allUsers = await db
    .select()
    .from(users)
    .orderBy(desc(users.createdAt));
  return c.json(allUsers);
});

// 获取用户及其文章（关系查询）
app.get('/api/users/:id', async (c) => {
  const id = parseInt(c.req.param('id'));
  const user = await db.query.users.findFirst({
    where: eq(users.id, id),
    with: {
      posts: true,
    },
  });
  if (!user) {
    return c.json({ error: 'User not found' }, 404);
  }
  return c.json(user);
});

// 创建文章
app.post('/api/posts', async (c) => {
  const body = await c.req.json();
  const [post] = await db
    .insert(posts)
    .values({
      title: body.title,
      content: body.content,
      authorId: body.authorId,
    })
    .returning();
  return c.json(post, 201);
});

// 获取所有已发布文章
app.get('/api/posts', async (c) => {
  const allPosts = await db
    .select()
    .from(posts)
    .where(eq(posts.published, true))
    .orderBy(desc(posts.createdAt));
  return c.json(allPosts);
});

export default {
  port: 3000,
  fetch: app.fetch,
};

6.5 数据库迁移

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/db/schema.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

# 生成迁移文件
bunx drizzle-kit generate

# 执行迁移
bunx drizzle-kit migrate

6.6 运行效果

# 启动开发服务器
bun run src/index.ts

# 测试 API
curl http://localhost:3000/api/users
curl http://localhost:3000/api/users/1
curl -X POST http://localhost:3000/api/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello Drizzle","content":"This is a test post","authorId":1}'

七、性能优化实战

7.1 连接池配置

// 优化连接池
const client = postgres(connectionString, {
  max: 20,           // 最大连接数
  idle_timeout: 20,  // 空闲连接超时（秒）
  connect_timeout: 10, // 连接超时（秒）
});

7.2 查询优化

// ❌ 不好的写法：查询所有字段
const allData = await db.select().from(users);

// ✅ 好的写法：只查询需要的字段
const names = await db
  .select({ id: users.id, name: users.fullName })
  .from(users);

// ❌ 不好的写法：N+1 查询问题
const usersList = await db.select().from(users);
for (const user of usersList) {
  const userPosts = await db
    .select()
    .from(posts)
    .where(eq(posts.authorId, user.id));
}

// ✅ 好的写法：使用关系查询（一条 SQL）
const usersWithPosts = await db.query.users.findMany({
  with: { posts: true },
});

7.3 事务处理

// 安全的事务处理
await db.transaction(async (tx) => {
  const [user] = await tx
    .insert(users)
    .values({ email: 'test@example.com', fullName: 'Test User' })
    .returning();
  
  await tx
    .insert(posts)
    .values({
      title: 'First Post',
      content: 'Hello World',
      authorId: user.id,
    });
});

7.4 批量操作

// 批量插入：比逐条插入快很多
await db.insert(users).values([
  { email: 'user1@example.com', fullName: 'User 1' },
  { email: 'user2@example.com', fullName: 'User 2' },
  { email: 'user3@example.com', fullName: 'User 3' },
]);

// 批量更新
await db
  .update(users)
  .set({ isActive: false })
  .where(sql`${users.createdAt} < ${threeMonthsAgo}`);

八、Drizzle Kit：数据库迁移的正确打开方式

8.1 Drizzle Kit 的定位

Drizzle Kit 是 Drizzle ORM 的配套工具，负责数据库 schema 的迁移管理。它在 v1.0 中也走向了开源。

# 初始化 Drizzle Kit
bunx drizzle-kit init

# 生成迁移
bunx drizzle-kit generate

# 查看迁移状态
bunx drizzle-kit migrate

# 推送 schema 到数据库（开发环境用）
bunx drizzle-kit push

# 打开 Drizzle Studio（可视化界面）
bunx drizzle-kit studio

8.2 迁移文件示例

-- drizzle/0000_initial.sql
CREATE TABLE IF NOT EXISTS "users" (
  "id" serial PRIMARY KEY,
  "email" text NOT NULL UNIQUE,
  "full_name" text NOT NULL,
  "avatar_url" text,
  "is_active" boolean DEFAULT true,
  "created_at" timestamp DEFAULT now(),
  "updated_at" timestamp DEFAULT now()
);

CREATE TABLE IF NOT EXISTS "posts" (
  "id" serial PRIMARY KEY,
  "title" text NOT NULL,
  "content" text NOT NULL,
  "published" boolean DEFAULT false,
  "author_id" integer REFERENCES "users"("id"),
  "created_at" timestamp DEFAULT now(),
  "updated_at" timestamp DEFAULT now()
);

九、Drizzle 在 Edge 环境的表现

9.1 为什么 Drizzle 适合 Edge

Drizzle 的零依赖设计让它天然适合 Edge 环境：

• Cloudflare Workers：Drizzle 可以直接在 Workers 中运行，配合 Neon Serverless Driver 或 PlanetScale Serverless Driver
• Vercel Edge Functions：同上
• Deno Deploy：Drizzle 支持 Deno 运行时

// Cloudflare Workers + Drizzle 示例
import { drizzle } from 'drizzle-orm/d1'; // Cloudflare D1
import { users } from './schema';

export default {
  async fetch(request, env) {
    const db = drizzle(env.DB);
    const allUsers = await db.select().from(users);
    return new Response(JSON.stringify(allUsers));
  },
};

9.2 Edge 环境的性能特点

在 Edge 环境中，JIT Row Mapper 的优势更加明显：

1. 冷启动更快：零依赖意味着更小的包体积，冷启动时间更短
2. 内存占用更低：没有运行时依赖的内存开销
3. 映射开销更敏感：Edge 函数的执行时间通常有严格限制，每毫秒都很宝贵

十、总结与展望

10.1 Drizzle v1.0 的意义

Drizzle ORM v1.0 的发布标志着 TypeScript ORM 生态的一个重要转折点：

1. JIT Row Mapper 证明了 TypeScript ORM 的性能可以达到原生驱动的水平
2. Effect v4 集成 展示了函数式编程和 ORM 结合的可能性
3. Drizzle for LLM Agents 预示了 AI 辅助数据库操作的未来

10.2 TypeScript ORM 的未来

展望未来，TypeScript ORM 可能会在以下方向继续演进：

1. 更智能的查询优化：基于 Schema 信息自动优化查询计划
2. 更好的 AI 集成：让 LLM 更深入地理解和操作数据库
3. 跨运行时兼容：在 Node.js、Bun、Deno、Edge 之间无缝切换
4. 实时数据同步：内置的 WebSocket 或 SSE 支持，实现实时数据推送

10.3 给开发者的建议

如果你还在犹豫要不要用 Drizzle：

1. 新项目：强烈推荐试一试，特别是 Bun + Hono 栈
2. 已有 Prisma 项目：不必急着迁移，等 v1.0 正式版发布后再评估
3. 性能敏感场景：JIT Row Mapper 的优势是实打实的，值得一试
4. Edge 部署：Drizzle 的零依赖设计让它成为 Edge 环境的最佳选择之一

Drizzle 用四年做到了一件事：把"轻量"和"不慢"同时贴在自己身上。这次连 Go 的性能对比都敢直接拿出来，底气已经不一样了。

本文基于 Drizzle ORM v1.0.0-rc.1 撰写，部分特性（如 Drizzle for LLM Agents）仍处于 preview 阶段。正式版发布后部分 API 可能有变化，请以官方文档为准。