@agent-native/core 0.79.1 → 0.79.5

package/docs/content/locales/zh-TW/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="一個模式，多個後端" summary="應用程式程式碼使用框架的與方言無關的幫助程序。執行時從 DATABASE_URL 自動檢測方言； unset 表示本機 SQLite 檔案。"
+{
+  "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
+
+# 普通 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="工作表" 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="附加遷移外掛"
+{
+  "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": "僅新增劑", "note": "`ADD COLUMN IF NOT EXISTS` 可以安全地重新執行並且永遠不會丟失資料。重命名看起來像 drop+create 為 Drizzle，所以改為新增然後遷移。" },
+    { "lines": "13-16", "label": "方言門控", "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": "每個應用程式版本表", "note": "每個應用程式都會跟蹤自己的應用版本，因此遷移在重新啟動和執行個體之間是冪等的。" }
+  ]
+}
+```
+
+## 環境變數 {#environment-variables}
+
+| 變數                  | 目的                                                     |
+| --------------------- | -------------------------------------------------------- |
+| `DATABASE_URL`        | 持久化SQL連線字串（未設定=本機SQLite，僅對本機開發持久） |
+| `DATABASE_AUTH_TOKEN` | 需要單獨權杖的提供者的驗證權杖，例如 Turso/libSQL        |

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

@@ -0,0 +1,348 @@
+---
+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="一個來源，多個應用程式" summary="每個工作區應用程式都使用自己的基本路徑建置，並安裝在單個來源的路徑前綴下 - 因此登入和跨應用程式 A2A 是同來源且免費的。"
+{
+  "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\">跨應用 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="建置輸出"
+{
+  "entries": [
+    { "path": ".output/", "note": "自包含：複製到任何環境即可執行" },
+    { "path": ".output/public/", "note": "建置後的 SPA（靜態 assets）" },
+    { "path": ".output/server/index.mjs", "note": "伺服器入口點" },
+    { "path": ".output/server/chunks/", "note": "伺服器程式碼 chunks" }
+  ]
+}
+```
+
+輸出是獨立的 - 將 `.output/` 複製到任何環境並執行它。
+
+```an-diagram title="建置部署" summary="一棵來源樹建置為 Nitro 預設；相同的獨立輸出在 Node、Vercel、Netlify、Cloudflare、AWS 或 Deno 上執行。每個執行個體都指向同一個持久的 DATABASE_URL。"
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>應用來源碼</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>持久 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 { agentNative } from "@agent-native/core/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [agentNative({ 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/ 是執行時建立的 SQLite 目錄 - 不要將開發資料庫複製到產品中。
+# 對於正式環境，將 DATABASE_URL 設定為託管的 Postgres 或 Turso 執行個體。
+RUN mkdir -p /app/data
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## 韋爾塞爾 {#vercel}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [agentNative({ 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({
+  plugins: [agentNative({ 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({
+  plugins: [agentNative({ nitro: { preset: "cloudflare_pages" } })],
+});
+```
+
+## AWS 拉姆達 {#aws-lambda}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "aws_lambda" } })],
+});
+```
+
+## 德諾部署 {#deno-deploy}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [agentNative({ 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)。