@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/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="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+不要为应用程序状态添加 `data/` 目录。持久应用数据属于 SQL，UI 通过 actions 或类型化服务器处理程序读取它。
+
+每个模板的四个区域通过一个共享操作界面和一个 SQL 数据库连接在一起 - 代理和 UI 是执行相同操作的平等合作伙伴：
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</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\">Actions</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>SQL via Drizzle<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\">Polling 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 {#actions}
+
+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": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "类型化契约", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+使用 `http: { method: "GET" }` 或 `readOnly: true` 表示只读 actions。仅将 `parallelSafe: true` 用于变异 actions，这些 actions 可以安全地与同轮工具调用同时运行。将 `toolCallable: false` 用于不应从沙盒工具运行的高爆炸半径 actions。
+
+## 构建 UI {#ui}
+
+路由位于 `app/routes/` 中并使用 React Router v7 文件路由。通过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
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| 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.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- 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/docs/content/locales/zh-CN/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="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</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>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</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": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+即时链接是完全基于经过验证的电子邮件的单一决策：
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity 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>Mint normal local session</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。