@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/database.md

@@ -0,0 +1,183 @@
+---
+title: "数据库"
+description: "将便携式 SQL 数据库连接到您的代理本机应用，并编写与提供商无关的 Drizzle 代码。"
+---
+
+# 数据库
+
+代理本机应用程序使用 [Drizzle ORM](https://orm.drizzle.team) 并支持便携式 SQL 后端。对于本地开发之外的任何内容，请通过设置 `DATABASE_URL` 连接持久性 SQL 数据库 - Postgres、libSQL/Turso 或另一个 Drizzle 兼容后端。取消设置该变量后，应用程序将回退到零配置本地 SQLite 文件，以便您可以立即开始开发。
+
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+## 本地默认：SQLite 文件 {#default-sqlite}
+
+当未设置 `DATABASE_URL` 时，应用程序会在 `data/app.db` 处创建 SQLite 数据库。这是本地开发的零配置默认设置 - 无需设置。它仅用于开发；对于生产，将 `DATABASE_URL` 设置为持久 SQL 数据库。
+
+不要依赖该本地文件来部署应用程序。容器、无服务器功能和预览环境可能会重置其文件系统，这意味着本地 SQLite 文件可能会在重新启动之间消失。在生产使用之前将 `DATABASE_URL` 设置为持久托管数据库。
+
+## 连接生产数据库 {#production}
+
+在 `.env` 文件或部署提供程序环境中设置 `DATABASE_URL` 以连接托管数据库。图尔索不是必需的；使用适合您的部署的与 Drizzle 兼容的 SQL 后端：
+
+```bash
+# Neon Postgres
+DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
+
+# Supabase Postgres
+DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Plain Postgres
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+
+# Turso (libSQL)
+DATABASE_URL=libsql://my-db-org.turso.io
+DATABASE_AUTH_TOKEN=your-token
+```
+
+框架自动检测 URL 的方言并相应地配置 Drizzle。内置适配器涵盖 Postgres URL、libSQL/Turso URL、SQLite 文件 URL 和 Cloudflare D1 绑定。常见的生产选择包括 Neon、Supabase、Turso/libSQL、普通 Postgres、持久 SQLite 和 Builder.io 托管环境（如果可用）。
+
+## Builder.io托管数据库 {#builder-managed}
+
+*计划（尚不可用）：*连接到 Builder.io 时，您的应用将能够使用自动配置的托管数据库，无需连接字符串。
+
+## 数据库客户端所在的位置 {#db-client}
+
+每个模板通过从 `@agent-native/core/db` 调用 `createGetDb(schema)` 来创建一个惰性的单例 Drizzle 客户端。规范位置是 `server/db/index.ts`：
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+从此模板本地路径导入 `getDb` - 路由中的 `../../server/db/index.js`，actions 中的 `../server/db/index.js` - 而不是直接从 `@agent-native/core` 导入。核心导出返回一个通用的无类型实例；模板的 `getDb()` 包含您的架构类型。请参阅 [Server](/docs/server#request-context) 了解 actions 和自定义路由如何导入它。
+
+## 与方言无关的架构和查询 {#schema}
+
+应用程序数据库代码应使用 Drizzle 的架构并查询 DSL，以便它可以跨提供程序运行。切勿在产品代码中编写仅 SQLite 语法（`INSERT OR REPLACE`、`AUTOINCREMENT`、`datetime('now')`）或仅 Postgres 语法。
+
+使用 `@agent-native/core/db/schema` 中的框架架构助手：
+
+```ts
+import { table, text, integer, real, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  priority: integer("priority").notNull().default(0),
+  weight: real("weight"),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| 帮手      | 目的                                                          |
+| --------- | ------------------------------------------------------------- |
+| `table`   | 定义一个表——委托给`pgTable`或`sqliteTable`                    |
+| `text`    | 文本栏，支持`{ enum: [...] }`                                 |
+| `integer` | 整数列，`{ mode: "boolean" }` 映射到 Postgres 布尔值          |
+| `real`    | 浮动列 - SQLite 上的 `real`、Postgres 上的 `double precision` |
+| `now`     | `.default(now())` 与方言无关的当前时间戳                      |
+
+上面的 `tasks` 表在每个后端定义了相同的列：
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
+切勿直接从 `drizzle-orm/sqlite-core` 或 `drizzle-orm/pg-core` 导入。始终使用 `@agent-native/core/db/schema`。
+
+存储面向用户的数据的表必须包含 `owner_email` 列，以便框架的 SQL 级别范围可以筛选经过身份验证的用户的行 - 请参阅 [Security](/docs/security#data-scoping)。还支持与其他用户或组织共享的表应改为传播 `...ownableColumns()`，这会在一次调用中添加 `owner_email`、`org_id` 和 `visibility` — 请参阅 [Sharing](/docs/sharing#building)。
+
+对于读取和写入，请使用 Drizzle 的查询生成器和 `drizzle-orm` 中的可移植运算符：
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+import { getDb } from "../server/db/index.js";
+import { tasks } from "../server/db/schema.js";
+
+const db = getDb();
+
+const openTasks = await db
+  .select()
+  .from(tasks)
+  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
+  .orderBy(desc(tasks.createdAt));
+
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## 原始 SQL 逃生舱口 {#raw-sql}
+
+原始 SQL 不是默认的应用代码 API。仅将其用于附加迁移、运行状况检查、仔细审查 Drizzle 无法表达的高级查询或一次性维护。保持参数化且与方言无关。对于 Drizzle 模式中的时间戳，优先选择 `.default(now())`；对于迁移 SQL，请使用 `runMigrations()`，以便框架支持的兼容性重写和方言门控语句保持集中。
+
+对于您确实需要 Drizzle 查询之外的原始 SQL 的情况：
+
+- `getDbExec()` — 将 `?` 参数自动转换为 Postgres 的 `$1`
+- `isPostgres()` — 运行时方言检查
+- `intType()` — 返回当前方言的正确整数类型
+
+## 迁移和架构更新 {#migrations}
+
+在托管环境中，多个部署预览、分支和生产服务器共享相同的底层数据库。因此，数据库架构更新必须遵循严格的约束，以避免数据丢失和服务中断。
+
+### “零破坏性改变”规则
+
+所有数据库架构更新都必须**严格附加**。
+
+- **不要删除表或列。**
+- **不要重命名表或列。**重命名列或表看起来像是 Drizzle 的 drop + create 序列，这将永久删除您现有的生产数据。
+- 如果需要重命名或替换某一列，请在旧列旁边添加新列，更新应用程序代码以读取/写入两者，迁移数据，并且仅在没有活动部署引用旧列时才在后续版本中停用旧列。
+
+> [!WARNING]
+> **切勿针对生产数据库运行 `drizzle-kit push`。**
+> 模板数据库模式仅定义特定于应用程序的域表；它们没有定义中央框架表（`user`、`session`、`application_state` 等）。如果您在生产环境中运行 `drizzle-kit push`，Drizzle 会将这些框架表检测为“不在架构中”并尝试删除它们，从而立即导致系统范围内的故障和数据丢失。
+
+### 安全迁移路径
+
+不应直接推送，而应通过在应用程序启动时执行的 SQL 迁移来应用架构更改。通过调用框架的 `runMigrations()` 帮助程序，在服务器插件（例如 `server/plugins/db.ts`）中实现附加迁移：
+
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
+```
+
+## 环境变量 {#environment-variables}
+
+| 变量                  | 目的                                                       |
+| --------------------- | ---------------------------------------------------------- |
+| `DATABASE_URL`        | 持久化SQL连接字符串（未设置=本地SQLite，仅对本地开发持久） |
+| `DATABASE_AUTH_TOKEN` | 需要单独令牌的提供商的身份验证令牌，例如 Turso/libSQL      |

package/docs/content/locales/zh-CN/deployment.md

@@ -0,0 +1,349 @@
+---
+title: "部署"
+description: "将代理原生应用部署到具有 Nitro 预设的任何平台 - Node.js、Vercel、Netlify、Cloudflare、AWS 等。"
+---
+
+# 部署
+
+代理本机应用程序在底层使用 [Nitro](https://nitro.build)，这意味着您可以部署到任何平台，无需进行零配置更改 - 只需设置预设即可。
+
+## 部署之前：选择持久数据库 {#persistent-database}
+
+每个部署的应用程序都需要一个持久的 SQL 数据库。在本地开发中，agent-native 回退到 `data/app.db` 处的 SQLite 文件；这在您的计算机上很方便，但在可以重置文件系统的容器、预览或无服务器环境中并不持久。
+
+在将应用推广到生产环境之前，在部署提供程序中设置 `DATABASE_URL`。 Agent-native 使用 Drizzle 进行架构和查询，因此数据层可跨 Drizzle 兼容的 SQL 后端移植，并且框架会自动检测 URL 的方言。有关适配器列表和方言详细信息，请参阅 [Database](/docs/database#production)。
+
+仅当您的数据库提供程序需要单独的令牌（例如 Turso/libSQL）时才使用 `DATABASE_AUTH_TOKEN`。对于工作区，所有应用默认继承根`DATABASE_URL`；当一个应用程序应使用不同的数据库时设置 `<APP_NAME>_DATABASE_URL`。
+
+## 工作区部署：一个源，多个应用 {#workspace-deploy}
+
+如果您的项目是 [workspace](/docs/multi-app-workspace)，您可以使用一个命令将其中的每个应用程序发送到单个源：
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+每个应用程序均使用 `APP_BASE_PATH=/<name>` 和 `VITE_APP_BASE_PATH=/<name>` 构建，然后打包为目标 Nitro 预设。 Cloudflare Pages 是默认预设，并使用 `dist/_worker.js` 生成的调度程序工作人员； Netlify 在 `.netlify/functions-internal/<app>-server` 中为每个应用程序使用一个函数以及生成的重定向； Vercel 使用构建输出 API 编写工作区级 `.vercel/output`。
+
+```an-diagram title="One origin, many apps" summary="Each workspace app is built with its own base path and mounted under a path prefix on a single origin — so login and cross-app A2A are same-origin and free."
+{
+  "html": "<div class=\"diagram-ws\"><div class=\"diagram-panel\" data-rough><strong>https://your-agents.com</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/mail/*</span><small class=\"diagram-muted\">apps/mail</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/calendar/*</span><small class=\"diagram-muted\">apps/calendar</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/forms/*</span><small class=\"diagram-muted\">apps/forms</small></div></div><div class=\"diagram-col wins\"><span class=\"diagram-pill ok\">shared login session</span><span class=\"diagram-pill ok\">zero-config cross-app A2A</span></div></div>",
+  "css": ".diagram-ws{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-ws .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-ws .diagram-row{display:flex;align-items:center;gap:8px}.diagram-ws .wins{display:flex;flex-direction:column;gap:8px;align-items:flex-start}"
+}
+```
+
+同源部署免费为您带来两大胜利：
+
+- **共享登录会话** — 登录任何应用程序，每个应用程序都会登录。
+- **零配置跨应用程序 A2A** — 从邮件中标记 `@calendar` 是同源获取；兄弟姐妹之间没有 CORS、JWT 签名。
+
+发布输出：
+
+```bash
+wrangler pages deploy dist
+```
+
+对于 Netlify 统一部署，请使用 Netlify 预设：
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+对于 Vercel 统一部署，请使用 Vercel 预设：
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+配置提供程序构建命令时，请使用与 `--build-only` 相同的命令。 Vercel 应运行 `npx @agent-native/core@latest deploy --preset vercel --build-only`；该命令直接写入 `.vercel/output`，因此工作区路由不需要 `vercel.json`。
+
+托管工作区构建需要部署提供程序环境中的 `A2A_SECRET`。
+这使得 Slack、入站 webhooks 和跨应用 A2A 通过签名恢复工作
+后台处理器。本地 `--build-only` 工件检查在没有它的情况下仍然可以运行。
+
+仍然支持每个应用程序独立部署 - 只是 `cd apps/<name> && npx @agent-native/core@latest build` 就像独立的脚手架。
+
+## 它是如何工作的 {#how-it-works}
+
+当您运行`npx @agent-native/core@latest build`时，Nitro将客户端SPA和服务器API构建为`.output/`：
+
+```an-file-tree title="Build output"
+{
+  "entries": [
+    { "path": ".output/", "note": "self-contained — copy to any environment and run" },
+    { "path": ".output/public/", "note": "built SPA (static assets)" },
+    { "path": ".output/server/index.mjs", "note": "server entry point" },
+    { "path": ".output/server/chunks/", "note": "server code chunks" }
+  ]
+}
+```
+
+输出是独立的 - 将 `.output/` 复制到任何环境并运行它。
+
+```an-diagram title="Build to deploy" summary="One source tree builds to a Nitro preset; the same self-contained output runs on Node, Vercel, Netlify, Cloudflare, AWS, or Deno. Every instance points at the same persistent DATABASE_URL."
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>App source</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">build</span><small class=\"diagram-muted\">Nitro preset</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Node.js</span><span class=\"diagram-pill\">Vercel</span><span class=\"diagram-pill\">Netlify</span><span class=\"diagram-pill\">Cloudflare</span><span class=\"diagram-pill\">AWS Lambda</span><span class=\"diagram-pill\">Deno</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Persistent DATABASE_URL<br><small class=\"diagram-muted\">shared by every instance</small></div></div>",
+  "css": ".diagram-deploy{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-deploy .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-deploy .diagram-arrow{font-size:22px;line-height:1}.diagram-deploy .diagram-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}"
+}
+```
+
+## 设置预设 {#setting-the-preset}
+
+默认情况下，Nitro 为 Node.js 构建。要针对不同的平台，请在 `vite.config.ts` 中设置预设：
+
+```ts
+import { defineConfig } from "@agent-native/core/vite";
+
+export default defineConfig({
+  nitro: {
+    preset: "vercel",
+  },
+});
+```
+
+或者在构建时使用 `NITRO_PRESET` 环境变量：
+
+```bash
+NITRO_PRESET=netlify npx @agent-native/core@latest build
+```
+
+## Node.js（默认） {#nodejs}
+
+默认预设。构建并运行：
+
+```bash
+npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+设置`PORT`配置监听端口（默认：`3000`）。
+
+使用当前的 Node.js LTS 系列进行生产部署。截至 2026 年 5 月，
+是Node.js 24； Node.js 20 已于 2026 年 4 月 30 日达到使用寿命，不再适用
+接收上游安全更新。
+
+### Docker {#docker}
+
+```dockerfile
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-slim
+WORKDIR /app
+COPY --from=build /app/.output .output
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## 韦尔塞尔 {#vercel}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "vercel" },
+});
+```
+
+通过 Vercel CLI 或 git Push 进行部署：
+
+```bash
+vercel deploy
+```
+
+对于工作区，将每个应用程序构建到一个 Vercel Build Output API 捆绑包中：
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+对于 Vercel Git 部署，将构建命令设置为：
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+工作区构建将每个应用程序的 Nitro `vercel` 输出复制到根 `.vercel/output` 中，为每个函数提供自己的挂载路径环境，并编写为 `/<app-id>` 处的应用程序提供服务的路由配置。
+
+## Netlify {#netlify}
+
+Nitro `netlify` 预设运行良好，在实践中，对于与外部 Postgres (Neon) 通信的模板，它比 Cloudflare Pages 更快地冷启动（TTFB 与 ~9 秒相比约为 200 毫秒）。在 `vite.config.ts` 中设置预设：
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "netlify" },
+});
+```
+
+...或在构建时设置 `NITRO_PRESET=netlify`。
+
+对于工作区，通过运行以下命令从一个 Netlify 站点部署每个应用：
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+工作区构建在 `dist/_workspace_static/` 下写入静态资产，并将每个应用程序路由到自己的 Netlify 函数，而无需强制资产重定向，因此像 `/mail/assets/...` 这样的文件会在服务器函数处理应用程序路由之前静态提供服务。
+
+## Cloudflare 页面 {#cloudflare-pages}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "cloudflare_pages" },
+});
+```
+
+## AWS 拉姆达 {#aws-lambda}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "aws_lambda" },
+});
+```
+
+## 德诺部署 {#deno-deploy}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "deno_deploy" },
+});
+```
+
+## 环境变量 {#environment-variables}
+
+### 构建/运行时 {#env-runtime}
+
+| 变量                        | 描述                                                                                                                           |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `PORT`                      | 服务器端口（仅限Node.js）                                                                                                      |
+| `NITRO_PRESET`              | 在构建时覆盖构建预设                                                                                                           |
+| `APP_BASE_PATH`             | 将应用程序安装在前缀下（例如 `/mail`）。由`npx @agent-native/core@latest deploy`自动设置；保持未设置为独立。                   |
+| `AGENT_PROD_CODE_EXECUTION` | 可选的生产代码执行模式：`off`（默认）、`sandboxed` 或 `trusted`。参见[Production Code Execution](#production-code-execution)。 |
+
+数据库连接变量（`DATABASE_URL`、`DATABASE_AUTH_TOKEN`、每个应用程序 `<APP_NAME>_DATABASE_URL`）位于 [Database](/docs/database#production) 中。
+
+### 生产中需要 {#env-required-prod}
+
+这些必须在将应用程序升级到真正的产品部署之前设置。缺失值要么失败关闭（框架拒绝启动/拒绝处理请求），要么回退到较弱的行为并发出响亮的警告。
+
+| 变量                     | 描述                                                                                                                                                                                      |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`     | 32+ 字符随机字符串。签署会话 cookies AND 是 `OAUTH_STATE_SECRET` 和 `SECRETS_ENCRYPTION_KEY` 的后备 HMAC。硬性要求：如果在生产中缺失，框架将在启动时抛出异常。                            |
+| `BETTER_AUTH_URL`        | 此应用程序的公共来源（例如 `https://mail.example.com`）。用于cookie域和OAuth重定向构造。                                                                                                  |
+| `ANTHROPIC_API_KEY`      | API 嵌入式生产代理密钥。 **在多租户部署中**，当用户没有每用户密钥时，框架拒绝回退到此 - 需要自带密钥。单租户自托管安装将其用作全局密钥。                                                  |
+| `OAUTH_STATE_SECRET`     | 用于 OAuth 状态信封（Google、Atlassian、Zoom）的专用 HMAC 密钥。未设置时回落到 `BETTER_AUTH_SECRET`，但建议使用专用值，以便旋转一个值不会使另一个值无效。通过`openssl rand -hex 32`生成。 |
+| `A2A_SECRET`             | 为应用程序间 A2A JSON-RPC 共享 HMAC。如果没有它，每个 A2A 端点和 `/_agent-native/integrations/process-task` 自发射端点在生产中都会返回 503。                                              |
+| `SECRETS_ENCRYPTION_KEY` | AES-256-GCM 静态加密机密保管库的密钥。回落至 `BETTER_AUTH_SECRET`。当两者都未设置时，生产中会发生硬故障。                                                                                 |
+
+### 身份验证和身份 {#env-auth}
+
+OAuth 提供商凭证（Google、GitHub）、静态 MCP 承载后备（`ACCESS_TOKEN` / `ACCESS_TOKENS`）和电子邮件验证切换记录在 [Authentication](/docs/authentication) 中。根据您选择的身份验证模式将它们设置在那里。
+
+### 入站Webhooks {#env-webhooks}
+
+每个消息集成在生产中都需要自己的签名密钥（当密钥丢失时，处理程序会因伪造请求而失败关闭）。每个积分变量列在 [Messaging](/docs/messaging) 和 [Security](/docs/security) 中。仅对于本地开发，`AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` 选择返回“警告并接受”——永远不要在产品中设置它。
+
+### 安全配置（选择加入） {#security-config}
+
+默认值是严格的。一些选择加入标志放松了行为（调试堆栈跟踪、未经验证的 webhooks、工作区范围的密钥回退、MCP 集线器多组织切换、运行时 env-var 写入）。它们的安全权衡记录在 [Security](/docs/security) 中。除非您特别想要宽松的路径，否则不要设置它们。
+
+### 工作区.env继承 {#env-inheritance}
+
+在工作空间内，根 `.env` 会自动加载到每个应用程序中，因此 `ANTHROPIC_API_KEY`、`A2A_SECRET`、`BETTER_AUTH_SECRET` 和 `OAUTH_STATE_SECRET` 等共享密钥只需设置一次。每个应用 `apps/<name>/.env` 在冲突中获胜。
+
+### 生成强大的秘密 {#env-generate-secrets}
+
+对于任何标记为“32+ char random”的密钥（`BETTER_AUTH_SECRET`、`OAUTH_STATE_SECRET`、`A2A_SECRET`、`SECRETS_ENCRYPTION_KEY`），请使用以下命令生成新值：
+
+```bash
+openssl rand -hex 32
+```
+
+通过替换每个实例上的环境变量并重新部署来轮换它们 — 使用旧密钥签名的会话/OAuth 状态信封将变得无效，因此用户可能需要再次登录。
+
+## 生产代理工具 {#production-agent-tools}
+
+生产代理从
+代理聊天插件。默认情况下启用数据库写入，因为原始数据库
+工具的范围仅限于经过身份验证的用户/组织，但应用程序所有者可以缩小范围
+何时部署应该更加固执己见：
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  // Default: "write" (also true)
+  databaseTools: "read", // "write" | "read" | "off"
+  extensionTools: false,
+});
+```
+
+- `databaseTools: "write"` — 默认。寄存器`db-schema`、`db-query`、
+  `db-exec` 和 `db-patch`。写入范围仅限于当前用户/组织和
+  架构更改被阻止。
+- `databaseTools: "read"` — 仅注册 `db-schema` 和 `db-query`；代理
+  使用 SQL 检查数据，但必须使用类型化应用程序 actions 进行写入。
+- `databaseTools: "off"` 或 `false` — 从
+  代理表面，因此应用程序的 actions 是唯一的数据访问路径。
+- `extensionTools: false` — 删除框架扩展管理 actions 和
+  针对以下应用的提示指导（`create-extension`、`update-extension` 等）
+  不希望代理创建沙盒迷你应用程序。
+
+## 生产代码执行 {#production-code-execution}
+
+默认情况下，生产代理在没有代码执行工具的情况下运行。他们可以调用应用程序 actions、数据库工具、MCP 工具、浏览器/会话工具和其他已注册的框架工具，但他们无法获得 shell 或文件系统访问权限。
+
+节点兼容的部署可以通过代理聊天插件或环境覆盖选择生产代码执行：
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+可用模式有：
+
+- `off` — 默认值。生产环境中未注册任何代码执行工具。
+- `sandboxed` — 注册 `run-code`，一个隔离的 Node.js JavaScript 运行器，具有清理环境、新的临时目录、输出/时间限制以及本地主机桥，以连接到允许列入名单的注册工具，例如 `provider-api-request`、`provider-api-docs`、`provider-api-catalog`、`web-request` 以及使用的资源支持的工作区文件桥作者：`workspaceRead` / `workspaceWrite`。
+- `trusted` — 注册 `run-code` 以及完整的编码工具注册表（`bash`、`read`、`edit`、`write`）。仅将其用于单租户或操作员控制的部署，其中有意对主机进行完全 shell 访问。
+
+设置 `AGENT_PROD_CODE_EXECUTION=sandboxed` 或 `AGENT_PROD_CODE_EXECUTION=trusted` 以覆盖特定部署的插件选项，而无需更改代码。即使插件选项启用了它，`AGENT_PROD_CODE_EXECUTION=off` 也会强制代码执行。
+
+`run-code` 沙箱是进程级隔离，而不是操作系统容器。它从子进程环境中剥离应用程序机密，并在可用时使用 Node 权限模型，但出站网络不会被 Node 本身阻止；经过身份验证的调用应通过该工具公开的桥接助手。
+
+## 在生产中更新 UI {#updating-ui-in-production}
+
+agent-native 的核心功能之一是代理可以修改应用程序的源代码 - 组件、路由、样式、actions。在本地开发期间，这可以无缝工作，因为代理具有完整的文件系统访问权限。
+
+在 [production code execution](#production-code-execution) 关闭的标准生产部署中，代理可以访问应用程序工具（actions、数据库、MCP），但不能访问文件系统。这意味着代理可以读取和写入数据、运行 actions 以及与外部服务交互 - 但它无法编辑 React 组件或在已部署的实例上添加新路由。
+
+### Builder.io：制作中的可视化编辑 {#builderio}
+
+[Builder.io](https://www.builder.io) 通过提供托管云环境来解决此问题，在该环境中，代理保留在生产中修改应用程序的 UI 的能力。将您的存储库连接到 Builder.io 并直接提示 UI 更改 - 无需重新部署。
+
+**工作原理：**
+
+1. 将您的代理本机存储库连接到 Builder.io
+2. Builder.io提供具有代理、可视化编辑和实时协作的云框架
+3. 提示代理进行 UI 更改 - 它会实时编辑您的组件、路线和样式
+4. 更改将提交回您的存储库
+
+有关嵌入式代理面板与云框架选项的更多信息，请参阅 [Frames](/docs/frames)。
+
+## 多实例部署 {#multi-instance}
+
+代理本机应用程序通过 Drizzle 将所有状态存储在 SQL 中，并通过 [polling](/docs/key-concepts#polling-sync) 与数据库同步 UI — 无文件系统状态、无粘性会话、无内存缓存。这意味着多实例和无服务器部署开箱即用：将每个实例指向同一个 `DATABASE_URL`，它们会自动聚合。请参阅 [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) 和 [Portability](/docs/key-concepts#hosting-agnostic)。