@agent-native/core 0.79.2 → 0.79.6

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

@@ -0,0 +1,411 @@
+---
+title: "建立範本"
+description: "如何建立和發布您自己的代理本機應用範本。"
+---
+
+# 建立範本
+
+範本是完整的、可分叉的代理本機應用程式，可解決實際工作流程。第一方範本使用您使用的相同框架表面建置：用於 UI 的 React 路由、用於資料的 Drizzle SQL、用於操作的 actions、用於代理行為的工作區資源以及輪詢同步，以便代理和 UI 保持一致。
+
+一個好的範本：
+
+- 使用有用的種子資料或空狀態流端對端地解決一個工作流。
+- 將持久狀態存儲在 SQL 中，而不是 JSON 檔案中。
+- 將應用操作定義為 `defineAction()` actions。
+- 通過應用程式狀態公開導覽和選取。
+- 為不明顯的工作流程提供清晰的 `AGENTS.md` 和重點 skills。
+- 註冊所需提供者和機密的加入步驟。
+- 作為獨立應用和多應用工作區的一部分工作。
+
+## 從聊天開始 {#start-from-chat}
+
+當您想要一個框架連線已就位的最小應用程式時，請使用聊天範本：
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+對於具有多個應用程式的工作區，執行選取器並包含與您想要的任何域範本的聊天：
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+聊天為您提供驗證、持久聊天線程、SQL 支持的資源、工具、應用程式狀態、actions 和輪詢同步。您新增域模型和產品 UI。
+
+如果您尚未建置可重複使用的 UI 範本，請使用 [Getting Started](/docs/getting-started#1-create-your-app) 中的無頭入口：定義一個操作，使用 `pnpm agent` 執行它，並在工作流程需要耐用表面時新增 UI。
+
+## 專案結構 {#project-structure}
+
+每個範本都遵循相同的廣泛布局：
+
+```an-file-tree title="範本專案結構"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React 前端" },
+    { "path": "app/root.tsx", "note": "HTML shell 和 providers" },
+    { "path": "app/routes/", "note": "React Router 檔案路由" },
+    { "path": "app/components/", "note": "範本 UI" },
+    { "path": "app/hooks/", "note": "UI 狀態和資料 hooks" },
+    { "path": "actions/", "note": "defineAction 操作：唯一事實來源" },
+    { "path": "server/db/schema.ts", "note": "Drizzle 架構" },
+    { "path": "server/plugins/db.ts", "note": "增量 migrations" },
+    { "path": "server/plugins/", "note": "啟動 integrations" },
+    { "path": "server/routes/api/", "note": "僅在 actions 不夠時使用自訂路由" },
+    { "path": "shared/types.ts", "note": "共用的 client/server 型別" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md：複雜工作流的代理指南" },
+    { "path": "AGENTS.md", "note": "範本專用代理指令" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+不要為應用程式狀態新增 `data/` 目錄。持久應用資料屬於 SQL，UI 通過 actions 或型別化伺服器處理程序讀取它。
+
+每個範本的四個區域通過一個共用操作介面和一個 SQL 資料庫連線在一起 - 代理和 UI 是執行相同操作的平等合作伙伴：
+
+```an-diagram title="範本的四個區域如何連線" summary="UI 和代理都通過相同的操作到達 SQL；應用程式狀態和輪詢同步使它們保持一致。"
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React 介面<br><small class=\"diagram-muted\">app/routes · 元件</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">行動</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>通過 Drizzle 使用 SQL<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">輪詢ing sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## SQL中的模型資料 {#data-models}
+
+使用框架 Drizzle 幫助程序定義域表，以便架構在 SQLite、Postgres、D1、Turso、Supabase、Neon 和其他支持的後端之間保持可移植性：
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+架構更改必須是附加的。 `server/plugins/db.ts`中通過`runMigrations()`新增表和列；切勿使用破壞性的 SQL、`drizzle-kit push`、表重命名或列刪除。
+
+對於應用程式讀取和寫入，請使用 Drizzle 的查詢生成器和 `drizzle-orm` 的可移植運算符。當Drizzle可以表達查詢時，不要使用原始SQL編寫產品程式碼，並且不要在範本中從`drizzle-orm/sqlite-core`或`drizzle-orm/pg-core`匯入。
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+在新增儲存使用者或組織資料的架構之前，請使用 [Database](/docs/database) 和 [Security](/docs/security) 檔案。
+
+## 將操作定義為行動 {#actions}
+
+行動 是應用行為的單一事實來源。代理將它們作為工具調用，前端通過鉤子調用它們，其他應用程式可以通過 MCP/A2A 存取它們。
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "工具表面", "note": "`description` 是代理讀取的內容，以決定何時將此操作作為工具調用。" },
+    { "lines": "9-11", "label": "型別化契約", "note": "一個 zod `schema` 會驗證來自代理、UI、HTTP、MCP 和 A2A 的輸入。" },
+    { "lines": "18-19", "label": "範圍寫入", "note": "從 `ctx` 標記 `ownerEmail` / `orgId`，以便該行正確地確定共用和存取檢查的範圍。" }
+  ]
+}
+```
+
+使用 `http: { method: "GET" }` 或 `readOnly: true` 表示唯讀 actions。僅將 `parallelSafe: true` 用於變異 actions，這些 actions 可以安全地與同輪工具調用同時執行。將 `toolCallable: false` 用於不應從沙盒工具執行的高爆炸半徑 actions。
+
+## 建置 UI {#ui}
+
+路由位於 `app/routes/` 中並使用 React Router v8 檔案路由。通過actions或API處理程序查詢資料，並預設使突變樂觀。
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+在應用程式 shell 附近連線一次實時同步，以便在代理、另一個分頁或操作更改資料時刷新 React 查詢快取：
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**代理原生承諾：代理寫入顯示在 UI 中，無需手動刷新。** `useActionQuery` 是簡單路徑 - 當變異操作發出 `source: "action"` 時，每個鉤子都會重新獲取。如果您使用自訂金鑰（例如，讀取整合狀態的低級用戶端幫助程序）獲取原始 `useQuery`，請將每個來源計數器折疊到 queryKey 中以進行有針對性的刷新：
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+常見來源：`"action"`（每個成功的代理操作 - 可靠的後備）、`"app-state"`、`"settings"`，以及您的商店通過 `recordChange` 發出的任何自訂資源來源。完整模式請參見 `real-time-sync` 技能。
+
+## 新增應用程式狀態 {#application-state}
+
+應用程式狀態是代理如何了解使用者所看到的內容。至少新增：
+
+- 一個 UI 鉤子，當路由、所選紀錄、活動分頁或編輯器選取發生更改時，它會寫入語義 `navigation` 狀態。
+- 讀取該狀態並返回目前螢幕快照的 `view-screen` 操作。
+- 一個 `navigate` 操作，寫入一次性 `navigate` 指令以供 UI 使用。
+
+使用 `useAgentRouteState` 作為 UI 掛鉤，以便應用程式狀態寫入、分頁範圍指令讀取、讀取後刪除和重複指令保護保持一致：
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+在 URL 查詢參數中保留可共用過濾器。框架將它們公開為 `<current-url>` 代理，內置代理可以使用 `set-search-params` 更改它們； `navigation` 應儲存語義 ID 和別名，而不是完整查詢字串的第二個副本。
+
+對於應用導覽，首選包含同來源的 `navigate` 指令
+`path`（當 URL 已知時）。同一動作不要寫為 `__set_url__`；
+該金鑰是為框架 URL 工具和僅 URL 過濾器更改保留的。
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+請參閱 [Context Awareness](/docs/context-awareness) 了解完整模式。
+
+## 謹慎使用 API 路由 {#api-routes}
+
+首選 actions 進行應用操作。僅為無法幹淨地成為 actions 的表面建立自訂 Nitro 路線：
+
+- 檔案上傳或二進制流。
+- 公開匿名頁面和webhooks。
+- OAuth 回呼和特定於提供者的協議處理程序。
+- 伺服器渲染的公開內容。
+
+在使用存取助手之前，接觸可擁有資料的自訂路由必須調用 `getSession(event)` 並將資料庫工作包裝在 `runWithRequestContext({ userEmail, orgId }, fn)` 中。
+
+## 編寫代理指令 {#write-agents-md}
+
+`AGENTS.md` 是您的應用程式的代理地圖 - 一個可瀏覽的小檔案，帶有
+目的行、核心規則、應用程式狀態鍵、操作表和 skills
+索引：
+
+```markdown
+# 我的範本
+
+One workspace for projects, tasks, and notes.
+
+## 核心規則
+
+- Data lives in 通過 Drizzle 使用 SQL. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## 應用狀態
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## 行動
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+每當新增新操作、路線、狀態鍵或重複操作時更新 `AGENTS.md`
+工作流程。 [Writing Agent Instructions](/docs/writing-agent-instructions) 是
+完整指南 - 如何保持 `AGENTS.md` 可略讀，這四個分別屬於什么
+指導面，以及如何表達技能和工具描述，以便代理
+可靠地觸發它們。
+
+## 新增Skills {#skills}
+
+使用 skills 來獲取會使 `AGENTS.md` 膨脹的詳細模式：特定於提供者的 API、匯入/匯出格式、複雜的編輯流程或域術語。
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# 專案進口
+
+Use this skill when the user uploads a legacy project CSV.
+
+## 規則
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+將範本 skills 存儲在 `.agents/skills/<name>/SKILL.md` 中。如果使用者應該能夠在執行時編輯指南，也可以通過工作區資源來顯示它。
+
+## 註冊設定步驟 {#onboarding}
+
+如果範本需要 API 金鑰、OAuth 連線或提供者帳戶，請註冊入門步驟，而不是將要求隱藏在 README 中。
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+參見[Onboarding & API Keys](/docs/onboarding)。
+
+## 使其適合工作空間 {#workspace-ready}
+
+範本應自然地適合 [Multi-App Workspaces](/docs/multi-app-workspace)，通常由 [Dispatch](/docs/dispatch) 協調。
+
+清單：
+
+- 通過框架代理聊天外掛或 `mountA2A()` 掛載 A2A，以便同級應用程式可以調用您的代理。
+- 保持代理卡描述足夠具體，以便 Dispatch 準確地安排工作。
+- 註冊所需的機密/加入，以便設定出現在側欄中，並且 Dispatch 可以管理共用憑證。
+- 將橫切指令保留在工作區 `AGENTS.md` 或工作區資源中，而不是複製到每個應用程式中。
+- 對所有可擁有的資源使用共用/存取幫助程序，以便組織範圍內的工作空間保持隔離。
+
+## 發布範本 {#publishing}
+
+分享之前：
+
+1. 執行 `pnpm install`、`pnpm typecheck` 和範本的測試。
+2. 驗證其是否可以在未設定可選提供程序金鑰的情況下正常工作。
+3. 檢查驗證、共用和兩個使用者資料隔離。
+4. 紀錄所需的環境變數和入門步驟。
+5. 通過附加遷移包含範例或種子行，而不是跟蹤的執行時資料檔案。
+
+可以從 GitHub 儲存庫建立社區範本：
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## 為框架 monorepo 做出貢獻 {#contributing}
+
+### 測試未發布的框架更改 {#test-unpublished-framework-changes}
+
+當您在框架 monorepo 中工作並需要生成時
+工作區使用未發布的包或範本更改，使用
+本機包標志：
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+生成的工作空間連結本機`@agent-native/core`和
+`@agent-native/dispatch` 軟件包，因此更改為 Core API、Dispatch 工作區
+可以在發布之前測試行為或第一方範本。包裹
+`prepack` 腳本在連結之前建置 `dist`，這會保留生成的
+工作空間指向目前建置輸出。

package/corpus/core/docs/content/locales/zh-TW/cross-app-sso.md

@@ -0,0 +1,188 @@
+---
+title: "跨應用SSO"
+description: "使用 Dispatch 作為身分授權，通過身分聯合在每個託管代理本機應用程式中登入一次 - 每個應用程式選取加入，可通過單個環境變數進行逆轉。"
+---
+
+# 跨應用SSO
+
+`*.agent-native.com` 上的每個託管應用程式都使用其**自己的獨立使用者存儲**執行自己的部署。 `mail.agent-native.com`和`calendar.agent-native.com`不共用資料庫、工作階段表或cookie域。因此，“登入一次，使用每個應用程式”不能是共用 cookie — 它必須是**身分聯合**，其中 [Dispatch](/docs/dispatch) 充當工作區的身分授權機構。
+
+這與 [A2A](/docs/a2a-protocol) 和 [External Agents](/docs/external-agents) 已經使用的信任原語相同 - 在請求邊界驗證的 `A2A_SECRET` 簽名的 JWT - 應用於人工登入路徑，而不是代理到代理的調用。
+
+> **統一部署與每個域部署。** 如果您在一個來源（`your-agents.com/mail`、`your-agents.com/calendar`）託管所有應用程式，您已經通過單個 cookie 域獲得共用登入 - 無需聯合。僅當應用程式在不同的域上執行時，才需要跨應用程式 SSO。參見[Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment)。
+
+## 什么以及為什么 {#what-why}
+
+每個應用程式的使用者存儲意味著瀏覽器 cookie 沒有一個可以被每個應用程式信任的地方。相反，聯合模型將一個應用程式命名為 **Dispatch** 作為身分授權機構。任何其他應用程式都可以委托“這個人是誰？”要調度，取回使用者已驗證電子郵件的短暫簽名斷言，然後**通過電子郵件將其連結到其自己的本機帳戶**。
+
+連結規則故意狹窄和附加：
+
+- **現有同一電子郵件使用者→連結。**本機帳戶與經過驗證的電子郵件匹配並按原樣重複使用。它**永遠不會被修改、重命名或刪除** - 聯合層只會讀取它並為其建立一個工作階段。
+- **新電子郵件 → 建立。** 為該經過驗證的電子郵件建立一個新的本機帳戶，然後建立一個正常的本機工作階段。
+
+這使得部署安全，即使它會導致人們退出。 **預計會登出。** 當應用程式開啟此功能時，現有工作階段將結束，並且使用者通過 Dispatch 重新進行驗證。但他們總是重新登入**同一個電子郵件匹配帳戶，所有資料都完好無損**，因為身分行只會*新增到* — 永遠不會被銷毀、重命名或重新指向。
+
+## 它是如何工作的 {#how-it-works}
+
+該流程是標準授權 → 簽名權杖 → 回調重新導向，其中電子郵件是唯一跨越信任邊界的內容。
+
+```an-diagram title="身分聯合流程" summary="Dispatch 對人員進行驗證，並返回一件事的短暫簽名斷言 - 經過驗證的電子郵件。該應用程式通過電子郵件連結並建立自己的本機工作階段。"
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>用戶端應用</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>應用回調</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">通過郵箱即時關聯</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **應用程式→調度（授權）。**應用程式將使用者發送到身分授權機構：
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &狀態=<csrf-state>
+   ```
+
+   ``an-api title="身分授權端點"
+{
+  “方法”：“GET”，
+  “路徑”：“/_agent-native/identity/authorize”，
+  “summary”：“Dispatch（身分授權）對人員進行驗證並使用簽名的身分權杖重新導向回來”，
+  "auth": "調度工作階段（如果沒有則互動式登入）",
+  “參數”：[
+    { "name": "app", "in": "query", "type": "string", "required": true, "description": "請求的應用程式標識符。" },
+    { "name": "redirect_uri", "in": "query", "type": "string", "required": true, "description": "應用程式回調 URL。根據嚴格的允許清單進行驗證（預設為 `\*.agent-native.com`或 localhost）。" },
+    { "name": "state", "in": "query", "type": "string", "required": true, "description": "CSRF 狀態在重新導向上回顯。" }
+  ],
+  “回應”：[
+    { "status": "302", "description": "重新導向到`redirect_uri`，攜帶短暫的 `A2A_SECRET` 簽名身分 JWT（`scope: \"identity\"`、`exp`≤ 2 分鐘）加上原始`state`。" },
+    { "status": "400", "description": "`redirect_uri`未通過允許清單驗證（跨來源、方案相關`//host` 或未列出的後綴）。" }
+   ]
+   }
+
+   ```
+
+   ```
+
+2. **Dispatch 對人員進行驗證。** 如果使用者已有 Dispatch 工作階段，則這是透明的。如果沒有，Dispatch 將顯示其自己的正常登入資訊（電子郵件/密碼、Google 等 — 請參閱 [Authentication](/docs/authentication)）。 Dispatch 只是一個常規的代理原生應用程式；它沒有執行特殊的驗證模式。
+
+3. **調度→應用程式（簽名身分權杖）。**調度根據嚴格的允許清單驗證`redirect_uri`，並302重新導向回應用程式的`redirect_uri`，攜帶短暫的**`A2A_SECRET`簽名身分JWT**。權杖的聲明故意最小化：
+
+   | 聲明         | 含義                                        |
+   | ------------ | ------------------------------------------- |
+   | `sub`        | 身分機構的穩定使用者ID                      |
+   | `email`      | 使用者的**已驗證**電子郵件 - 唯一的加入金鑰 |
+   | `name`       | 顯示名稱（非權威，僅適用於UI）              |
+   | `org_domain` | 工作空間/組織域（如果存在）                 |
+   | `scope`      | 始終為 `"identity"` — 此權杖僅授權登入      |
+   | `exp`        | **≤ 2 分鐘** 距問題                         |
+
+4. **應用程式通過電子郵件驗證和 JIT 連結。**應用程式使用自己的 `A2A_SECRET` 驗證權杖簽名，檢查 `scope: "identity"` 和 `exp`，然後嚴格通過經過驗證的電子郵件執行**即時連結**：
+   - 如果具有該電子郵件地址的本機使用者存在 → 不加修改地重新使用它。
+   - 如果沒有 → 為該電子郵件建立本機使用者。
+
+5. **應用程式建立一個普通的本機工作階段。**從這裡開始，使用者在該應用程式自己的商店中擁有一個普通的本機工作階段 - 每個現有的存取檢查、組織範圍和操作防護都與以前完全相同。聯邦只發生在前門。
+
+### 選取加入 {#opt-in}
+
+應用**僅**在其部署中設定此環境變數時參與：
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **設定** → 應用程式顯示執行上述流程的**“使用 Agent-Native 登入”**選項。直接本機登入（電子郵件/密碼、Google）仍然可以與它一起使用。
+- **取消設定（預設）** → **零行為改變。** 應用程式的驗證與之前完全相同；聯合程式碼路徑處於休眠狀態。沒有架構更改，也沒有任何需要遷移的內容，因此開啟或關閉變數在任何時候都是完全可逆的。
+
+## 安全 {#security}
+
+整個模型依賴於一些故意的小保證：
+
+- **短暫的簽名權杖。**身分斷言是 `A2A_SECRET` 簽名的 JWT，具有 **≤ 2 分鐘** 到期時間和 `scope: "identity"`。它授權單次登入，並且不能長時間重播或重新用於 API/A2A 存取。
+- **嚴格的 `redirect_uri` 允許清單。** 預設情況下，調度僅重新導向到 `*.agent-native.com` 或本機主機。任意、方案相關 (`//host`) 和跨域重新導向目標都會被拒絕，因此權限無法轉變為開放重新導向或權杖滲透預言機。
+- **從經過驗證的權杖僅通過電子郵件加入。** 跨越信任邊界的*唯一*事物是簽名權杖中經過驗證的電子郵件。該應用程式不接受來自線路的使用者 ID、角色、組織成員資格或任何特權狀態 - 它從匹配的帳戶在本機派生所有內容。
+- **僅新增身分寫入。**連結可以不受影響地重複使用現有的同一電子郵件帳戶，也可以插入一個新帳戶。此路徑上不會發生任何身分行的更新、重命名、重新指向或刪除。
+- **預設情況下關閉。**如果取消設定 `AGENT_NATIVE_IDENTITY_HUB_URL`，則整個功能將處於惰性狀態。
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**啟用安全，恢復安全。**身分寫入**僅可新增**- 現有的同一電子郵件帳戶將不受影響地重複使用，而新電子郵件只需插入新行。沒有架構更改，也沒有任何需要遷移的內容，因此每個應用程式都可以隨時完全可逆地開啟或關閉 `AGENT_NATIVE_IDENTITY_HUB_URL`。"
+}
+```
+
+即時連結是完全基於經過驗證的電子郵件的單一決策：
+
+```an-diagram title="JIT-link 決定" summary="連結以經過驗證的電子郵件為關鍵，並且僅是附加的 - 現有帳戶不變地重複使用，新電子郵件建立新的本機使用者。"
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>已驗證郵箱<br><small class=\"diagram-muted\">來自已簽名身分 JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>簽發普通本機工作階段</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 自託管 {#self-hosting}
+
+任何 Dispatch 部署都可以充當身分中心 - 您不限於 `dispatch.agent-native.com`。在每個用戶端應用程式上設定 `AGENT_NATIVE_IDENTITY_HUB_URL` 以指向您的 Dispatch 執行個體：
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**重新導向允許列表。** 集線器（調度）在發出權杖之前驗證授權端點上的 `redirect_uri`。允許名單在`templates/dispatch/server/lib/identity-sso.ts`中設定：
+
+- **預設值：** 僅 `*.agent-native.com` 和 localhost（`DEFAULT_ALLOWED_HOST_SUFFIXES` 常量）。
+- **擴充功能它：**在 Dispatch 部署上設定 `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` 環境變數，並使用逗號分隔的其他主機後綴列表：
+
+  ```bash
+  # 除預設值外還允許 yourcompany.com 子域
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
+  ```
+
+  每個條目都被標準化為點前綴後綴 (`.yourcompany.com`)，因此後綴檢查既足夠又最不容易發生 — 無需按應用程式列表保持同步。與所有內容匹配的條目（空或只是 `.`）將被過濾掉。
+
+- 無論 `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` 為何，**Localhost** 始終允許本機開發用戶端應用程式。
+
+如果沒有 `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`，自託管 Dispatch 只能向 `*.agent-native.com` 上的應用程式頒發權杖。在 Dispatch 部署上設定環境變數以解鎖其他域。
+
+## 金絲雀推出執行手冊 {#canary-rollout}
+
+切換和回滾是**每個應用程式部署的單個環境變數**。一次推出一個應用程式，驗證，然後擴充功能。不要同時在每個應用程式上設定變數。
+
+**1。部署程式碼——沒有行為改變。**
+使用 `AGENT_NATIVE_IDENTITY_HUB_URL` **將版本發布到每個應用程式**到處都未設定\*\*。確認正常登入在幾個應用程式上仍然有效。
+
+**2。一次在 ONE 應用程式上啟用金絲雀。**
+僅在一次部署上設定：
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+保留所有其他應用程式的環境未設定。重新部署/重新啟動，以便它獲取變數。
+
+**3。驗證金絲雀（清單）。**
+
+- 登出應用程式。
+- 登入螢幕現在顯示**“使用 Agent-Native 登入”**。點選它。
+- 您將進入 **Dispatch** 並完成登入（如果已經登入，則直接通過）。
+- 您將被重新導向**返回應用程式並登入** — 並且它是您之前擁有的**相同的現有帳戶**（同一電子郵件），而不是新帳戶。
+- **應用資料完好無損** — 您的現有紀錄、設定和組織範圍與原來完全相同。
+- **現有的直接登入仍然有效** - 電子郵件/密碼和 Google 登入繼續與 SSO 一起使用。
+
+如果任何檢查失敗，請直接進入步驟 4（回滾）——這是即時且資料安全的。
+
+**4。逐個應用程式展開。**
+驗證一個應用程式後，對下一個應用程式重複步驟 2-3 - 一次在一個部署上設定 `AGENT_NATIVE_IDENTITY_HUB_URL`。切勿批量啟用。
+
+**5。回滾 = 取消設定該應用程式部署上的環境變數。**
+要恢復任何應用程式，**從該應用程式的環境中刪除 `AGENT_NATIVE_IDENTITY_HUB_URL` 並重新部署/重新啟動它。**應用程式立即返回到其之前的驗證行為。 **沒有資料更改可以撤消** - 僅新增了標識行，取消設定變數只會使聯合路徑再次休眠。每個應用的割接和回滾都是獨立且可逆的。
+
+> 啟用每個應用程式時，Rollout 會將使用者登出（他們通過 Dispatch 重新進行驗證），但他們始終會重新登入到**相同的電子郵件匹配帳戶，並且資料完好無損**，因為身分行永遠不會被銷毀或重命名 - 只是新增。
+
+## 相關 {#related}
+
+- [Authentication](/docs/authentication) — 本機驗證模式、工作階段、組織、`A2A_SECRET` 環境變數。
+- [A2A Protocol](/docs/a2a-protocol) — 已簽名的 JWT，它重用的邊界驗證信任模型。
+- [External Agents](/docs/external-agents) — 應用於代理連線和深層連結的相同 `A2A_SECRET` 簽名身分模式。
+- [Dispatch](/docs/dispatch) — 工作區身分授權和路由中心。
+- [Security & Data Scoping](/docs/security) - 僅附加資料寫入和每個帳戶範圍。
+- [Multi-App Workspaces](/docs/multi-app-workspace) — 統一的單來源部署，完全避免跨域 SSO。