@agent-native/core 0.79.2 → 0.79.5

package/corpus/core/docs/content/locales/zh-TW/authentication.md

@@ -0,0 +1,332 @@
+---
+title: "驗證"
+description: "與電子郵件/密碼、社交提供者、組織和 MCP 持有者憑證更好的驗證整合。"
+---
+
+# 驗證
+
+代理本機應用程式使用 [Better Auth](https://better-auth.com) 進行帳戶優先設計的驗證。使用者在第一次存取時建立一個帳戶，並從第一天起就獲得真實身分。
+
+## 概述 {#overview}
+
+Auth 是通過 auth 伺服器外掛中的 `autoMountAuth(app)` 自動設定的。共有三種模式：
+
+- **預設：**使用電子郵件/密碼+社交提供者進行更好的驗證。首次存取時顯示的入門頁面。
+- **遠端 MCP OAuth：** 適用於 MCP 主機的標準 OAuth 2.1，例如 Claude 程式碼和 ChatGPT 連線器。
+- **自訂：**通過 `getSession` 回調帶來您自己的驗證。
+
+```an-diagram title="三種方式，一次會議" summary="瀏覽器訪客、編程 MCP 用戶端和自訂提供程序都解析為下游作用域讀取的同一 AuthSession。"
+{
+  "html": "<div class=\"auth-modes\"><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default</span><strong>Better Auth</strong><small class=\"diagram-muted\">email/password &middot; Google &middot; GitHub</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Remote MCP OAuth</span><strong>OAuth 2.1 + PKCE</strong><small class=\"diagram-muted\">Claude Code、ChatGPT 連線器</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Custom</span><strong>getSession callback</strong><small class=\"diagram-muted\">Clerk &middot; Auth0 &middot; Firebase</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill ok\">AuthSession</span><small class=\"diagram-muted\">email &middot; orgId &middot; orgRole</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Request context &amp; data scoping</div></div>",
+  "css": ".auth-modes{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.auth-modes .diagram-col{display:flex;flex-direction:column;gap:10px}.auth-modes .diagram-card{display:flex;flex-direction:column;gap:4px;padding:10px 12px}.auth-modes .diagram-arrow{font-size:22px;line-height:1}.auth-modes .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+瀏覽器流程在任何地方都是相同的更好的驗證流程 - **沒有開發驗證繞過**，並且 `getSession()` 永遠不會退回到 `local@localhost` 哨兵。環境之間的變化是註冊摩擦，而不是登入牆：
+
+| 環境              | 首次載入行為                                           | 電子郵件驗證                               |
+| ----------------- | ------------------------------------------------------ | ------------------------------------------ |
+| **本機開發**      | 自動建立一次性開發帳戶並讓您登入（無登入牆）           | 預設跳過（當沒有電子郵件提供者時）         |
+| **品質檢查/預覽** | 正常註冊，但可以跳過驗證，因此測試人員無需等待電子郵件 | 使用 `AUTH_SKIP_EMAIL_VERIFICATION=1` 跳過 |
+| **正式環境**      | 正常更好的驗證註冊/登入                                | 必需（設定電子郵件提供者時）               |
+
+一些標志對此進行了調整；完整詳細資訊位於 [Environment Variables](#environment-variables) 表中：
+
+- `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` — 使用本機開發中的普通註冊頁面而不是自動開發帳戶。
+- `AUTH_DISABLED=true` — 完全跳過登入/註冊，並以一個共用使用者身分執行每個請求（僅限本機開發/預覽/演示，切勿與真實使用者一起進行正式環境）。
+- `AUTH_MODE=local` — 僅影響 CLI/代理身分（開發使用者 `pnpm action` 執行時的身分）；它**不是**瀏覽器登入繞過。
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "`AUTH_DISABLED=true` runs **every request as one shared user**. Use it only for local dev, previews, or demos — never in production with real users, where it would expose all data to anyone."
+}
+```
+
+## 更好的驗證（預設） {#better-auth}
+
+預設情況下，Better Auth 支持驗證。它提供：
+
+- 電子郵件/密碼註冊和登入
+- 社交提供者（Google、GitHub 和 35 多個其他提供者）
+- 具有角色和邀請的組織
+- 用於 API 和 A2A 存取的 JWT 權杖
+- 對程序化用戶端的不記名權杖支持
+
+Better Auth 路由安裝在 `/_agent-native/auth/ba/*`。該框架還提供向後兼容的端點：
+
+- `GET /_agent-native/auth/session` — 獲取目前工作階段
+- `POST /_agent-native/auth/login` — 電子郵件/密碼登入
+- `POST /_agent-native/auth/register` — 建立帳戶
+- `POST /_agent-native/auth/logout` — 退出
+
+## Cookie 領域 {#cookie-realms}
+
+工作階段 cookie 的領域遵循部署形狀，因此共用的應用程式
+資料庫/來源共用登入和不保持隔離的應用：
+
+| 部署形狀                                 | Cookie 領域                                                                                                      |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 獨立應用                                 | 通過 slug（`APP_NAME`，或本機開發中的包名稱）隔離每個應用程式；正式環境中穩定的 `an` 前綴                        |
+| 工作區模式（`AGENT_NATIVE_WORKSPACE=1`） | 一個共用領域 - 工作區應用程式共用來源和資料庫                                                                    |
+| 自訂同資料庫子域                         | 選取與 `COOKIE_DOMAIN` 共用 Cookie                                                                               |
+| 第一方託管 (`*.agent-native.com`)        | 每個應用程式的獨立命名空間（每個應用程式都有自己的驗證資料庫）；預設情況下忽略 `COOKIE_DOMAIN=.agent-native.com` |
+
+第一方託管應用程式都有自己的驗證資料庫，因此可以跨應用程式登入
+通過 [Cross-App SSO](/docs/cross-app-sso) 而不是共用 cookie。
+這些部署必須提供 `APP_NAME` 或可派生應用 URL（`APP_URL`、`URL`，
+`DEPLOY_PRIME_URL`，或`DEPLOY_URL`）；否則啟動失敗而不是下降
+返回共用的 `an_session` 名稱。有意共用一個驗證資料庫
+跨子域，將 `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` 並排設定
+`COOKIE_DOMAIN`.
+
+## 品質檢查帳戶 {#qa-accounts}
+
+本機開發和測試預設跳過註冊電子郵件驗證，因此您
+可以建立真實的電子郵件/密碼帳戶，而無需等待收件箱。強制
+在測試該流程時進行本機驗證，設定 `AUTH_SKIP_EMAIL_VERIFICATION=0`。
+
+對於測試人員需要真實帳戶但不應等待的託管 QA 環境
+在電子郵件傳送時，設定：
+
+```bash
+AUTH_SKIP_EMAIL_VERIFICATION=1
+```
+
+設定此標志後，電子郵件/密碼註冊不需要電子郵件
+驗證和註冊驗證電子郵件未發送。僅將其用於品質檢查
+或預覽環境，並使用 `+qa` 地址命名測試帳戶
+(`name+qa@example.com`)，因此很容易識別。
+
+## 社交提供者 {#social-providers}
+
+設定環境變數以啟用社交登入。 Better Auth 自動檢測它們：
+
+```bash
+# GoogleOAuth
+GOOGLE_SIGN_IN_CLIENT_ID=your-low-scope-sign-in-client-id
+GOOGLE_SIGN_IN_CLIENT_SECRET=your-low-scope-sign-in-client-secret
+
+# 向後兼容的回退以及範本的提供者 OAuth 憑證
+# 連線到 Google APIs，例如 Gmail 或行事曆。
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# GitHub OAuth
+GITHUB_CLIENT_ID=your-client-id
+GITHUB_CLIENT_SECRET=your-client-secret
+```
+
+使用 `createGoogleAuthPlugin()` 的範本顯示“使用 Google 登入”頁面。 GoogleOAuth 回呼自動處理本機應用的行動深度連結。
+
+普通情況下優先選取 `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET`
+應用程式登入。該用戶端應該僅請求身分範圍。保留
+`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` 適用於需要的產品整合
+Google API 範圍，或作為部署未拆分時的舊後備
+還沒有。郵件和行事曆樣式的應用程式應該使用自己的提供者 OAuth 用戶端，因此
+高範圍同意螢幕不會影響通用應用登入。
+
+### OAuth 狀態簽名 {#oauth-state-secret}
+
+在正式環境中將 `OAUTH_STATE_SECRET` 設定為隨機的 32+ 字符值，以便 OAuth 狀態信封（Google、Atlassian、Zoom）使用獨立於任何第三方機密的專用金鑰進行 HMAC 簽名。請參閱 [Security — OAuth State Signing](/docs/security#oauth-state) 了解完整的要求和威脅模型。
+
+## 組織 {#organizations}
+
+該框架提供了內置的組織系統。這是框架自己的 `org/` 模塊（由 `organizations` 和 `org_members` 表支持），而不是 Better Auth 的組織外掛，該外掛故意未註冊。每個應用程式都支持：
+
+- 建立組織
+- 邀請具有角色的成員（`owner`、`admin`、`member`）
+- 切換活動組織
+- 通過 `org_id` 列確定每個組織的資料範圍
+
+活動組織在工作階段中被跟蹤為 `session.orgId`，切換組織會更改使用者和代理看到的資料。資料作用域本身發生在堆堆疊的更下方——有關完整的 `session.orgId → AGENT_ORG_ID → SQL` 管道和存取防護，請參閱 [Security & Data Scoping](/docs/security#data-scoping)。 [Multi-Tenancy](/docs/multi-tenancy) 檔案涵蓋了組織管理層面。
+
+## 靜態MCP不記名權杖 {#access-tokens}
+
+`ACCESS_TOKEN` 和 `ACCESS_TOKENS` 不是瀏覽器驗證，並且不會將應用程式設為私人。它們僅保留為無法使用 OAuth 流的 MCP/連線用戶端的靜態承載憑證。
+
+```bash
+# 單一代幣
+ACCESS_TOKEN=my-secret-token
+
+# 多個代幣
+ACCESS_TOKENS=token1,token2,token3
+```
+
+設定這些變數永遠不會為訪客呈現權杖登入頁面。 Web 登入保留在 Better Auth 或您的自訂 `getSession` 提供者上。
+
+## 遠端MCP OAuth {#remote-mcp-oauth}
+
+每個應用程式的 MCP 端點都可以充當標準受保護的 MCP 資源。支持 OAuth 的用戶端只能設定遠端 MCP URL：
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+```
+
+未經驗證的 MCP 請求返回指向 `/.well-known/oauth-protected-resource` 的 `WWW-Authenticate` 質詢。然後，用戶端發現應用程式的 OAuth 元資料，動態註冊公開用戶端，開啟應用程式的授權頁面，並與 PKCE 交換授權程式碼以獲取存取和刷新權杖。
+
+```an-diagram title="遠端 MCP OAuth 握手" summary="具有 OAuth 功能的用戶端僅從 MCP URL 引導 — 挑战、發現、動態註冊，然後是 PKCE 程式碼交換。"
+{
+  "html": "<div class=\"mcp-flow\"><div class=\"diagram-node\">1 &middot; MCP request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node warn\">2 &middot; 401 challenge<br><small class=\"diagram-muted\">WWW-Authenticate</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">3 &middot; Discover metadata<br><small class=\"diagram-muted\">.well-known</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">4 &middot; Register client<br><small class=\"diagram-muted\">動態、公開</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">5 &middot; Authorize + PKCE<br><small class=\"diagram-muted\">code exchange</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">6 &middot; Access + refresh<br><small class=\"diagram-muted\">audience-bound</small></div></div>",
+  "css": ".mcp-flow{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.mcp-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.mcp-flow .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+設定時存取權杖使用 `A2A_SECRET` 進行簽名，否則使用 `BETTER_AUTH_SECRET` 進行簽名。它們攜帶簽名的使用者/組織身分和 `mcp:read`、`mcp:write` 和/或 `mcp:apps` 範圍，並且受眾綁定到確切的 MCP 資源 URL。刷新權杖僅存儲為哈希值並在每次刷新時輪換。工具調用和 MCP Apps 資源讀取在與登入使用者相同的請求上下文中執行；嵌入式 MCP 應用程式 iframe 永遠不會接收原始 OAuth 權杖。
+
+`npx @agent-native/core@latest connect <url> --client claude-code` 為此標準流程寫入僅 URL 的 MCP 條目。對於無法執行遠端 MCP OAuth 的用戶端，請使用“連線”頁面或 `npx @agent-native/core@latest connect --token <token>` 回退來寫入顯式不記名權杖條目。
+
+## 自帶驗證 {#byoa}
+
+傳遞自訂 `getSession` 回調以使用任何驗證提供程序（Clerk、Auth0、Firebase 等）：
+
+```ts
+// server/plugins/auth.ts
+import { createAuthPlugin } from "@agent-native/core/server";
+
+export default createAuthPlugin({
+  getSession: async (event) => {
+    // Your custom auth logic here
+    const session = await myAuthProvider.verify(event);
+    if (!session) return null;
+    return { email: session.email };
+  },
+  publicPaths: ["/api/webhooks"],
+});
+```
+
+## 公開工作區應用 {#public-workspace-apps}
+
+工作區應用程式預設為內部應用程式。讓匿名訪客載入公開
+站點同時將管理頁面保留在驗證之後，在
+`apps/<id>/package.json`:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+對於相反的形狀，保留預設的內部受眾並僅公開
+特定公開頁面：
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+`publicPaths`和`protectedPaths`使用前綴匹配，所以`"/admin"`也
+覆蓋 `"/admin/users"`。這些設定僅開啟頁面導覽。框架
+路由（`/_agent-native/*`）和自訂API路由（`/api/*`）仍然需要驗證
+除非應用明確新增這些前綴
+`createAuthPlugin({ publicPaths: [...] })`.
+
+## 工作階段 API {#session-api}
+
+`getSession(event)` 返回的工作階段物件具有以下形狀：
+
+```ts
+interface AuthSession {
+  email: string; // User's email (primary identifier)
+  userId?: string; // Better Auth user ID
+  token?: string; // Session token
+  name?: string; // Display name from the auth provider, when available
+  image?: string; // Profile image from the auth provider, when available
+  orgId?: string; // Active organization ID
+  orgRole?: string; // Role in active org (owner/admin/member)
+}
+```
+
+在用戶端上，使用 `useSession()` 掛鉤：
+
+```ts
+import { useSession } from "@agent-native/core/client";
+
+function MyComponent() {
+  const { session, isLoading } = useSession();
+  if (isLoading) return <p>Loading...</p>;
+  if (!session) return <p>Not signed in</p>;
+  return <p>Hello, {session.email}</p>;
+}
+```
+
+## 登入並返回URL {#sign-in-return-url}
+
+具有**公開頁面**（共用連結、嵌入、營銷頁面）的範本通常需要一個頁面內 CTA 來要求匿名檢視者登入並將他們帶回到他們所在的頁面。該框架為此提供了一個入口點：
+
+```
+/_agent-native/sign-in?return=<same-origin-path>
+```
+
+當匿名檢視者點擊此 URL 時，將提供框架的登入頁面。成功登入（任何流程 - 權杖、電子郵件/密碼或 GoogleOAuth）後，檢視者將 302 轉至 `return`。
+
+`return` 參數被驗證為**同來源路徑**。網路路徑引用 (`//evil.com/...`)、絕對 URL、`data:` / `javascript:` 方案和嵌入式控制字符都回退到 `/`。驗證的路徑是從 URL 解析器重建的，而不是從輸入中回顯。
+
+**來自 React 元件：**
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+function SignInCta() {
+  const onClick = () => {
+    const ret = window.location.pathname + window.location.search;
+    window.location.href =
+      "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+  };
+  return <Button onClick={onClick}>Sign in</Button>;
+}
+```
+
+### 已新增書簽的私人路徑
+
+當匿名使用者直接導覽到 `/dashboard` 等私人路徑時，框架已經在該 URL 處提供登入頁面 - 成功登入後，頁面重新載入並且使用者登陸 `/dashboard`。無需特殊處理；這適用於權杖、電子郵件/密碼、**和** GoogleOAuth。
+
+### 幕後花絮：GoogleOAuth
+
+兩個流（顯式 `/_agent-native/sign-in` 入口點和書簽路徑情況）都將返回 URL 線程穿過 OAuth 狀態。該狀態是 HMAC 簽名的，因此在運輸過程中無法偽造。在回調中，返回的 URL 在重新導向之前被重新驗證為同來源 - 因此泄漏的簽名金鑰仍然無法轉換為開放重新導向預言機。
+
+如果您的範本直接包裝 `/_agent-native/google/auth-url`（例如郵件和行事曆範本這樣做，以擴大範圍），則接受 `?return=<path>` 查詢並通過 `encodeOAuthState` 的選項物件形式轉發它：
+
+```ts
+const returnUrl = getQuery(event).return;
+const state = encodeOAuthState({
+  redirectUri,
+  desktop,
+  returnUrl: typeof returnUrl === "string" ? returnUrl : undefined,
+});
+```
+
+預設的 `/_agent-native/google/auth-url` 路由會自動執行此操作 - 僅當您的範本需要自訂 OAuth 處理時才覆蓋。
+
+## 環境變數 {#environment-variables}
+
+| 變數                                    | 目的                                                                                                                 |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`                    | 更好的驗證簽名金鑰（如果未設定，則自動生成）                                                                         |
+| `AUTH_SKIP_EMAIL_VERIFICATION`          | 在 QA/預覽環境中設定為 `1`，讓電子郵件/密碼註冊無需驗證即可繼續進行；預設情況下跳過本機開發/測試                     |
+| `AUTH_DISABLED`                         | 設定為`true`或`1`跳過登入/註冊；所有請求都作為一個共用使用者執行（僅限本機開發/預覽 - 不適用於真實使用者的正式環境） |
+| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | 設定為 `1` 以在新的開發資料庫上停用本機主機自動登入                                                                  |
+| `AUTH_MODE`                             | `local` 僅解析 CLI/代理身分（開發使用者 `pnpm action` 作為其執行）；絕不繞過瀏覽器登入                               |
+| `COOKIE_DOMAIN`                         | 選取跨同一資料庫子域共用工作階段 Cookie（請參閱 [Cookie Realms](#cookie-realms)）                                    |
+| `AGENT_NATIVE_WORKSPACE`                | `1` 在工作區模式下執行 - 跨工作區應用的一個共用工作階段領域                                                          |
+| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | 使用 `COOKIE_DOMAIN` 設定以跨第一方子域共用一個驗證資料庫                                                            |
+| `OAUTH_STATE_SECRET`                    | 用於 OAuth 狀態包絡的專用 HMAC 金鑰（請參閱 [Security — OAuth State Signing](/docs/security#oauth-state)）           |
+| `GOOGLE_SIGN_IN_CLIENT_ID`              | 用於應用登入的首選低範圍 GoogleOAuth 用戶端 ID                                                                       |
+| `GOOGLE_SIGN_IN_CLIENT_SECRET`          | 用於應用登入的首選低範圍 GoogleOAuth 金鑰                                                                            |
+| `GOOGLE_CLIENT_ID`                      | 舊版 Google 登入回退以及用於 Google API 整合的提供者 OAuth 用戶端 ID                                                 |
+| `GOOGLE_CLIENT_SECRET`                  | 舊版 Google 登入回退以及 Google API 整合的提供者 OAuth 金鑰                                                          |
+| `GITHUB_CLIENT_ID`                      | 啟用GitHub OAuth                                                                                                     |
+| `GITHUB_CLIENT_SECRET`                  | GitHub OAuth秘密                                                                                                     |
+| `ACCESS_TOKEN`                          | MCP/連線用戶端的靜態承載回退；不是瀏覽器驗證                                                                         |
+| `ACCESS_TOKENS`                         | MCP/connect 用戶端的逗號分隔靜態承載回退；不是瀏覽器驗證                                                             |
+| `A2A_SECRET`                            | JWT 簽名的 A2A 跨應用驗證的共用金鑰，以及 MCP OAuth 存取權杖簽名（如果存在）                                         |

package/corpus/core/docs/content/locales/zh-TW/automations.md

@@ -0,0 +1,268 @@
+---
+title: "自動化"
+description: "具有自然語言條件的事件觸發和計畫自動化"
+---
+
+# 自動化
+
+**自動化**是一條規則：_當 X 發生時，執行 Y_ — 用自然語言描述。代理執行指令，因此自動化可以存取代理可以在互動式聊天中使用的每個操作、工具和 MCP 伺服器。
+
+自動化通過 `web-request` 工具使用**事件觸發器**、**自然語言條件**和**出站 HTTP** 擴充功能 [recurring jobs](/docs/recurring-jobs)。它們使用與重複作業相同的 `jobs/<name>.md` 檔案格式、存儲和“建立三種方式”工作流程 - 請參閱 [Recurring Jobs](/docs/recurring-jobs#job-file) 了解共用格式。本頁面僅涵蓋事件驅動自動化的新增內容。
+
+```an-diagram title="當X發生時，做Y" summary="總線上觸發事件，可選的自然語言條件對其進行門控，代理執行具有完整工具存取權限的自動化主體。"
+{
+  "html": "<div class=\"auto-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Event</span><small class=\"diagram-muted\"><code>calendar.booking.created</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Condition</span><small class=\"diagram-muted\">Haiku checks: &ldquo;email ends with @builder.io&rdquo;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">代理執行 body</span><small class=\"diagram-muted\">actions &middot; web-request &middot; MCP &middot; sub-agents</small></div></div>",
+  "css": ".auto-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.auto-flow .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.auto-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## 兩種觸發器型別 {#trigger-types}
+
+| 型別       | 觸發時                            | 關鍵欄位           |
+| ---------- | --------------------------------- | ------------------ |
+| `schedule` | cron 表達式匹配（與重複作業相同） | `schedule`（cron） |
+| `event`    | 框架事件總線上發出匹配的事件      | `event`（姓名）    |
+
+事件觸發器可以包含 `condition`——Haiku 在調度之前根據事件負載評估的自然語言字串。如果條件不匹配，則自動跳過自動化。
+
+## 建立自動化 {#creating}
+
+### 通過詢問代理
+
+> “當有人使用 @builder.io 電子郵件預訂會議時，請通過 Slack 向我發送訊息。”
+
+代理發現可用事件，確認計畫，並為您編寫自動化。
+
+### 來自設定UI
+
+自動化出現在設定面板中。使用者可以在那裡檢視、啟用/停用和刪除它們。
+
+第三條路徑 - 通過 `resourcePut` 手動寫入 `jobs/<name>.md` 檔案 - 與 [recurring jobs](/docs/recurring-jobs#creating) 的工作方式完全相同。對於事件驅動的自動化，您可以將下面的事件觸發 frontmatter 新增到同一檔案中。事件觸發作業設定 `schedule: ""` 並提供 `triggerType: event`、`event` 名稱和可選的 `condition`：
+
+```an-annotated-code title="事件觸發的自動化"
+{
+  "filename": "jobs/slack-on-builder-booking.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"\"\nenabled: true\ntriggerType: event\nevent: calendar.booking.created\ncondition: \"attendee email ends with @builder.io\"\nmode: agentic\ndomain: calendar\nrunAs: creator\n---\nSend a Slack message to #sales with the booking details.\nUse the web-request tool to POST to ${keys.SLACK_WEBHOOK}.",
+  "annotations": [
+    { "lines": "2", "label": "沒有計畫工作", "note": "Event triggers set `schedule` to `\"\"` — the cron field stays empty." },
+    { "lines": "4-5", "label": "觸發器", "note": "`triggerType: event` 加上 `event` 名稱將此自動化訂閱到總線。" },
+    { "lines": "6", "label": "門", "note": "可選的自然語言 `condition`，由 Haiku 在調度之前根據有效負載進行評估。" },
+    { "lines": "12", "label": "伺服器端秘密", "note": "`${keys.SLACK_WEBHOOK}` is resolved server-side — the raw value never enters the agent's context." }
+  ]
+}
+```
+
+## 自動化前沿 {#frontmatter}
+
+自動化共用 [recurring-jobs frontmatter table](/docs/recurring-jobs#frontmatter) 中的每個欄位。這些附加欄位控制事件觸發器、條件和執行模式：
+
+| 欄位          | 型別                             | 預設         | 描述                                                                                                                   |
+| ------------- | -------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `triggerType` | `"schedule"` \| `"event"`        | `"schedule"` | 自動化如何啟動                                                                                                         |
+| `event`       | 字串                             | _（可選）_   | 要訂閱的事件名稱（僅限事件觸發器）                                                                                     |
+| `condition`   | 字串                             | _（可選）_   | 在調度之前評估自然語言條件                                                                                             |
+| `mode`        | `"agentic"` \| `"deterministic"` | `"agentic"`  | 完整的代理循環。 （`"deterministic"` 已保留，但尚未實現 - 設定它的自動化將被跳過。對所有目前自動化使用 `"agentic"`。） |
+| `domain`      | 字串                             | _（可選）_   | 分組標籤（郵件、行事曆、剪輯等）                                                                                       |
+
+對於事件觸發器，`schedule`為`""`（空）；對於計畫觸發器，它帶有 cron 表達式。調度程序還寫入與調度程序相同的託管 `lastRun` / `lastStatus` / `lastError` 欄位，以及當條件評估為 false 時的 `"skipped"` 狀態。
+
+## 事件總線 {#event-bus}
+
+整合在模塊載入時註冊事件。總線根據 [Standard Schema](https://standardschema.dev) 定義驗證有效負載並將其分派給訂閱者。
+
+### 內置事件 {#built-in-events}
+
+| 活動                   | 來源                                       |
+| ---------------------- | ------------------------------------------ |
+| `test.event.fired`     | 手動/`manage-automations` action=fire-test |
+| `agent.turn.completed` | 代理聊天                                   |
+| `calendar.*`           | 行事曆整合                                 |
+| `clip.*`               | 剪輯整合                                   |
+| `mail.*`               | 郵件整合                                   |
+
+從代理中使用 `action=list-events` 調用 `manage-automations`，以檢視所有已註冊事件以及目前範本的描述和負載模式。
+
+### 發出自訂事件 {#emitting-events}
+
+在伺服器外掛中註冊事件型別，然後從 actions 或 webhook 處理程序發出它：
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register the event type (once, at module load)
+registerEvent({
+  name: "order.completed",
+  description: "A customer completed an order",
+  payloadSchema: z.object({
+    orderId: z.string(),
+    customerEmail: z.string(),
+    total: z.number(),
+  }),
+  example: {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit(
+  "order.completed",
+  {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+  { owner: "steve@builder.io" },
+);
+```
+
+自動化觸發的發出元資料範圍中的 `owner` - 僅評估同一使用者擁有的自動化（或共用自動化）。
+
+## 條件 {#conditions}
+
+條件是 Claude Haiku 針對事件負載評估的自然語言字串。這是一個是/否分類，而不是生成工作。
+
+- **空或缺失條件** = 無條件（始終觸發）。
+- 結果通過 5 分鐘 TTL 和 500 個條目的 LRU 快取進行記憶（條件 + 負載的 SHA-256）。
+- 有效負載在發送到 Haiku 之前被截斷為 4000 個字符。
+- 在 API 失敗時，條件評估為 `false`（安全預設值 - 跳過自動化）。
+
+條件範例：
+
+- `"attendee email ends with @builder.io"`
+- `"the order total is greater than $100"`
+- `"the message contains the word 'urgent'"`
+
+## 網路請求工具 {#web-request}
+
+自動化使用 `web-request` 工具進行出站 HTTP。它支持 URL、標頭和內文中的 `${keys.NAME}` 預留位置：
+
+```
+POST to ${keys.SLACK_WEBHOOK}
+
+Headers: {"Authorization": "Bearer ${keys.API_TOKEN}"}
+
+Body: {"text": "New booking from ${attendeeEmail}"}
+```
+
+在代理發出工具調用後，預留位置在**伺服器端**解析 - 原始秘密值永遠不會進入代理的上下文。
+
+### 參數 {#web-request-params}
+
+| 參數         | 型別 | 預設  | 描述                                               |
+| ------------ | ---- | ----- | -------------------------------------------------- |
+| `url`        | 字串 | —     | 完整的URL。可能包含 `${keys.NAME}` 引用。          |
+| `method`     | 字串 | `GET` | HTTP 方法（GET、POST、PUT、PATCH、DELETE、HEAD）。 |
+| `headers`    | 字串 | `{}`  | JSON 標頭物件。可能包含 `${keys.NAME}`。           |
+| `body`       | 字串 | —     | 請求內文。可能包含 `${keys.NAME}`。                |
+| `timeout_ms` | 數字 | 15000 | 超時（以毫秒為單位）（最大 30000）。               |
+
+## 按鍵 {#keys}
+
+金鑰是由使用者或代理建立的用於自動化使用的臨時秘密（例如 `SLACK_WEBHOOK`、`HUBSPOT_API_KEY`）。它們與註冊機密 (`registerRequiredSecret`) 的不同之處在於它們沒有範本定義的元資料或入門步驟。
+
+- 通過設定 UI 或 `/_agent-native/secrets/adhoc` API 建立。
+- 每個金鑰都可以有一個 **URL 允許清單**，用於限制金鑰可以發送到哪些來源（來源級別匹配）。
+- 原始值永遠不會暴露給 AI - 只有 `${keys.NAME}` 預留位置出現在代理的上下文中。
+- 分辨率從使用者範圍回退到工作區範圍，因此使用者可以覆蓋共用金鑰。
+
+## 代理工具 {#agent-tools}
+
+所有自動化操作均通過帶有 `action` 參數的單個 `manage-automations` 工具存取：
+
+| 行動          | 目的                                                 |
+| ------------- | ---------------------------------------------------- |
+| `list-events` | 發現所有已註冊事件及其描述和負載模式                 |
+| `list`        | 列出所有自動化的狀態；按域或啟用過濾                 |
+| `define`      | 建立新的自動化（名稱、觸發器型別、事件、條件、內文） |
+| `update`      | 更新現有自動化（已啟用、條件、內文）                 |
+| `delete`      | 刪除自動化（始終先與使用者確認）                     |
+| `fire-test`   | 發出 `test.event.fired` 事件來驗證自動化             |
+
+附加工具：`web-request` — 出站 HTTP 替換為 `${keys.NAME}`。
+
+## API端點 {#api}
+
+| 端點                                   | 方法   | 描述                         |
+| -------------------------------------- | ------ | ---------------------------- |
+| `/_agent-native/automations`           | GET    | 列出所有自動化（已解析）     |
+| `/_agent-native/automations/fire-test` | POST   | 發出 `test.event.fired` 事件 |
+| `/_agent-native/secrets/adhoc`         | GET    | 列出臨時鍵（無值）           |
+| `/_agent-native/secrets/adhoc`         | POST   | 建立或更新臨時金鑰           |
+| `/_agent-native/secrets/adhoc/:name`   | DELETE | 刪除臨時金鑰                 |
+
+```an-api title="觸發測試事件"
+{
+  "method": "POST",
+  "path": "/_agent-native/automations/fire-test",
+  "summary": "發出 test.event.fired 事件以驗證事件觸發的自動化",
+  "description": "Confirm an automation's wiring and condition without waiting for a real provider event. Equivalent to the `manage-automations` action `fire-test`.",
+  "responses": [
+    { "status": "200", "description": "Event emitted; matching automations are dispatched through the normal condition + ownership path." }
+  ]
+}
+```
+
+## 調度如何運作 {#dispatch}
+
+```an-diagram title="調度路徑" summary="從觸發事件到完成代理執行，由所有權範圍和自然語言條件控制。"
+{
+  "html": "<div class=\"disp\"><div class=\"diagram-box accent\">event fired on the bus</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">match</span><small class=\"diagram-muted\">load enabled automations subscribed to this event name</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">scope</span><small class=\"diagram-muted\">keep only those owned by the event's owner (or shared)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">condition</span><small class=\"diagram-muted\">Haiku yes/no on the payload &mdash; false &rarr; <code>skipped</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">run</span><small class=\"diagram-muted\"><code>runAgentLoop</code> body 作為提示、payload 作為上下文，5 分鐘超時</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code></small></div></div>",
+  "css": ".disp{display:flex;flex-direction:column;gap:6px;max-width:540px}.disp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.disp .diagram-box{align-self:flex-start}.disp .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+## 範例 {#example}
+
+**使用者：**“當有人使用 @builder.io 電子郵件預訂時，請在 Slack 中給我發訊息。”
+
+**代理流程：**
+
+1. 使用 `action=list-events` 調用 `manage-automations` — 找到 `calendar.booking.created`。
+2. 與使用者確認計畫。
+3. 使用 `action=define` 調用 `manage-automations`：
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @builder.io`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+4. 自動化儲存為 `jobs/slack-on-builder-booking.md` 並立即開始監听。
+
+## 更多範例 {#more-examples}
+
+### 當計畫被評論時通過 webhook 通知
+
+詢問計畫代理：_“當有人對計畫新增人工評論時，POST a
+向我的 webhook 發出通知。"_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+將 `NOTIFY_WEBHOOK` 設定為任何 HTTP 端點 - Slack 傳入 Webhook，通用
+通知服務，或自訂接收器。 `web-request`工具解決
+`${keys.NOTIFY_WEBHOOK}` 伺服器端；原始的 URL 永遠不會出現在代理的
+上下文。見[Visual Plans — Events and notifications](/docs/template-plan#events)
+完整的 `plan.commented` 有效負載參考和所有四個計畫事件。
+
+## 下一步是什么
+
+- [**Recurring Jobs**](/docs/recurring-jobs) - 計畫觸發的自動化重用相同的計畫程序
+- [**Actions**](/docs/actions) - 自動化可以通過代理循環調用任何註冊的操作
+- [**Security**](/docs/security) - 輸入驗證和秘密處理
+- [**Visual Plans — Events**](/docs/template-plan#events) - 計畫事件參考和自動化秘訣