@agent-native/core 0.79.2 → 0.79.6

package/docs/content/locales/zh-TW/multi-app-workspace.md

@@ -0,0 +1,312 @@
+---
+title: "多應用工作區"
+description: "在一個單一儲存庫中託管許多代理本機應用程式，並具有共用驗證、RBAC、指令、skills、元件和憑證。"
+---
+
+# 多應用工作區
+
+> **哪個工作區檔案？** 此頁面涵蓋 **部署形狀** - 一個單一儲存庫、許多應用程式、共用驗證和統一部署。對於工作空間*是什么*（自訂層：`AGENTS.md`、`LEARNINGS.md`、個人內存、skills、自訂代理），請參閱 [Workspace](/docs/workspace)；有關治理（誰審查、批準和擁有什么），請參閱 [Workspace Governance](/docs/workspace-management)。
+
+當對內部工具進行振動編碼需要一個下午時，您不會停下來。一個團隊最終得到了一個 CRM、一個支持收件箱、一個儀表板、一個操作控制台——十個小應用程式，每個應用程式都是獨立搭建的。這很好，直到您需要更改所有內容為止。
+
+那時，每個應用程式都有自己的 `AGENTS.md`、自己的驗證外掛、自己的複製貼上布局元件、自己的硬編碼 Slack 權杖、自己關於“組織”是什么的想法。合規規則的變更意味著十個 PR。輪換 API 金鑰意味著十次重新部署。品牌刷新意味著十個不同的標題變得不同步。原本讓建置它們變得容易的事情現在卻讓它們變得難以管理。
+
+**多應用程式工作區**模式是代理本機解決此問題的方式。您可以將所有應用程式與私人 `packages/shared` 包一起託管在一個單一儲存庫中。該框架擁有通用的預設值； `packages/shared` 僅適用於真正針對您的工作區定制的程式碼、指令、skills、元件或外掛覆蓋。每個應用程式都縮小到少數幾個螢幕和 actions，這使其獨一無二。
+
+## 分享什么內容 {#what-gets-shared}
+
+您組織中的每個應用都應同意的任何內容都可以存在於 `packages/shared` 中：
+
+| 共用的東西      | 它居住的地方                                       |
+| --------------- | -------------------------------------------------- |
+| 驗證/SSO覆蓋    | 從 `src/server/index.ts` 匯出 `authPlugin`         |
+| 組織/RBAC規則   | 更好的驗證組織，可選地由 `authPlugin` 包裝         |
+| 代理聊天覆蓋    | 從 `src/server/index.ts` 匯出 `agentChatPlugin`    |
+| 企業代理說明    | `AGENTS.md`                                        |
+| 特工skills      | `.agents/skills/<skill-name>/SKILL.md`             |
+| 共用代理actions | `actions/*.ts`                                     |
+| 共用React元件   | 從`src/client/index.ts`匯出                        |
+| 設計代幣/品牌   | 新增共用的 CSS 檔案並從每個應用匯入                |
+| 共用 API 憑證   | 更喜歡框架範圍的憑證；僅當需要命名空間時才新增助手 |
+
+每個單獨的應用程式都變成*只是一組螢幕* — 路線、儀表板、視圖、特定於域的 actions。框架預設值涵蓋其餘部分，直到您新增真正的工作區自訂。
+
+當您的應用想要使用另一個第一方應用時，同樣的邊界也適用。需要電子郵件、行事曆、分析和公司內存上下文的新工作區儀表板應使用現有的郵件、行事曆、分析和大腦應用程式作為通過連結或 A2A 連線的鄰居。它不應該克隆這些範本，建立嵌套它們的包裝應用程式，或者在其內部搭建子應用程式只是為了存取其資料或代理。僅當您明確想要自訂該應用程式時，才分叉或搭建副本。
+
+## 開始使用 {#getting-started}
+
+工作區是代理本機專案的預設形狀。腳手架一具有：
+
+```bash
+npx @agent-native/core@latest create my-company-platform
+```
+
+CLI 顯示每個第一方範本的多選選取器。選取任意數量的郵件 + 行事曆 + 表單，例如，它們都會被搭建到同一個工作區中，共用驗證和資料庫預設值。
+
+您將獲得一個包含私人共用包的 pnpm monorepo、一個連線工作區發現的根 `package.json`、一個共用 `.env` 以及您選取的每個應用程式的一個子目錄：
+
+```an-file-tree title="一個腳手架生成的 workspace"
+{
+  "entries": [
+    { "path": "package.json", "note": "聲明 agent-native.workspaceCore" },
+    { "path": "pnpm-workspace.yaml", "note": "packages: [\"packages/*\", \"apps/*\"]" },
+    { "path": ".env.example", "note": "共用的 ANTHROPIC_API_KEY、A2A_SECRET、DATABASE_URL、..." },
+    { "path": "packages/shared/", "note": "@my-company-platform/shared" },
+    { "path": "packages/shared/src/server/", "note": "僅在需要時使用 plugin overrides" },
+    { "path": "packages/shared/src/client/", "note": "僅在需要時共用 React 程式碼" },
+    { "path": "packages/shared/AGENTS.md", "note": "整個 workspace 的指令" },
+    { "path": "apps/mail/" },
+    { "path": "apps/calendar/" },
+    { "path": "apps/forms/" }
+  ]
+}
+```
+
+然後啟動它：
+
+```bash
+cd my-company-platform
+cp .env.example .env             # 填寫ANTHROPIC_API_KEY、BETTER_AUTH_SECRET、...
+pnpm install
+pnpm dev                         # opens Dispatch; other apps start on first visit
+```
+
+每個應用程式都已經知道如何登入、共用相同的資料庫以及載入工作區 `AGENTS.md`。您沒有連線任何這些 - 框架通過根 `package.json` 中的 `agent-native.workspaceCore` 欄位自動發現共用包：
+
+```json
+{
+  "name": "my-company-platform",
+  "agent-native": {
+    "workspaceCore": "@my-company-platform/shared"
+  }
+}
+```
+
+## 新增另一個應用 {#adding-a-new-app}
+
+從工作區內的任何位置：
+
+```bash
+npx @agent-native/core@latest add-app
+```
+
+CLI 再次顯示範本選取器，其中已過濾掉您已安裝的應用程式。選取一個或多個，它們就會被搭建在 `apps/` 下。非互動式變體：
+
+```bash
+npx @agent-native/core@latest add-app crm --template content
+```
+
+任何第一方範本都可以用作工作區應用程式 - CLI 在範本上執行一個小型 **workspacify** 轉換，將共用包新增為 dep 並解析 `workspace:*` 引用。無需維護並行的“工作空間應用程式”腳手架。
+
+```bash
+pnpm install                     # at the workspace root
+pnpm dev
+```
+
+就是這樣。新應用程式具有與其他應用程式相同的登入和工作區說明。僅在工作區實際需要時新增共用品牌、actions 或憑證。
+
+## 您在何處覆蓋內容 {#layering}
+
+工作區中的代理本機應用程式按以下順序從三個位置解析橫切行為：
+
+1. **應用程式本機** — `apps/<name>/` 內的檔案（最高優先級）
+2. **工作空間共用** — `packages/shared/`（共用中間層）內的檔案
+3. **框架預設** — `@agent-native/core`（最低）
+
+合並按檔案名進行。如果應用程式提供的本機檔案也存在於上游，則本機檔案獲勝。如果沒有，則應用工作區共用版本。如果共用也沒有提供，則框架預設啟動。這適用於外掛、skills、actions 和 `AGENTS.md`。
+
+```an-diagram title="三層，按檔案名合並" summary="每個應用程式首先從應用程式本機解析外掛、技能、操作和 AGENTS.md，然後是共用包，然後是框架預設值。"
+{
+  "html": "<div class=\"layer\"><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">1 &middot; App local</span><small class=\"diagram-muted\"><code>apps/&lt;name&gt;/</code> &mdash; highest priority</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; Workspace shared</span><small class=\"diagram-muted\"><code>packages/shared/</code> &mdash; the mid-layer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">3 &middot; Framework default</span><small class=\"diagram-muted\"><code>@agent-native/core</code> &mdash; lowest</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box ok\">first match wins</div></div>",
+  "css": ".layer{display:flex;flex-direction:column;align-items:center;gap:6px}.layer .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 16px;width:320px}.layer .diagram-arrow{font-size:18px;line-height:1}.layer .diagram-box{margin-top:2px}"
+}
+```
+
+當一個應用需要不同的東西時，刪除本機檔案：
+
+| 要覆蓋的內容 | 要在應用程式內建立的檔案                           |
+| ------------ | -------------------------------------------------- |
+| 驗證外掛     | `apps/<name>/server/plugins/auth.ts`               |
+| 代理聊天外掛 | `apps/<name>/server/plugins/agent-chat.ts`         |
+| 特定技能     | `apps/<name>/.agents/skills/<skill-name>/SKILL.md` |
+| 特定操作     | `apps/<name>/actions/<action-name>.ts`             |
+| 其他代理說明 | `apps/<name>/AGENTS.md`（與工作區一合並）          |
+
+無需接線，無需設定。建立檔案並接管。
+
+## 編輯共用行為 {#editing-shared-behavior}
+
+您自訂的所有橫切內容都位於 `packages/shared/` 中。從 `src/server/index.ts` 匯出 `authPlugin`，每個應用程式都會在下次開發重新載入時拾取它。在 `.agents/skills/` 下新增一項技能，每個應用程式的代理都會看到它。向`actions/`新增一個動作，每個應用程式的代理都可以調用它。
+
+由於共用包是 `workspace:*` 依賴項，因此 pnpm 將其符號連結到每個應用程式的 `node_modules/` 中。您永遠不會建置或發布它 - 應用程式會在建置時捆綁它們需要的任何內容。
+
+## 執行時全域資源 {#runtime-global-resources}
+
+使用 `packages/shared` 作為應隨儲存庫附帶的程式碼級預設值：外掛、共用 actions、共用 React 程式碼、檔案系統 `AGENTS.md` 和檔案系統 skills。將 Dispatch 工作區資源用於管理員希望在不更改程式碼的情況下進行管理的執行時可編輯全域上下文。
+
+調度資源的範圍為**所有應用程式**（每個應用程式在執行時繼承它們，沒有複製或同步步驟）或**選定的應用程式**（為每個應用程式授予特定於應用程式的上下文）。請參閱 [Workspace](/docs/workspace#global-resources) 了解完整的資源模型表、路徑約定和推薦的入門包。
+
+## 驗證和RBAC {#auth-and-rbac}
+
+每個代理本機應用程式都已附帶 [Better Auth](/docs/authentication) 以及框架的內置組織系統。在工作區中，您可以在每個應用程式中免費獲得該功能，並由同一資料庫支持。有關完整的多租戶模型（組織、角色、資料隔離），請參閱 [Multi-Tenancy](/docs/multi-tenancy)。
+
+對於特定於企業的規則（允許列表域、SSO 強制執行、額外角色檢查），請從 `packages/shared/src/server/index.ts` 匯出 `authPlugin`。現在，工作區中的每個應用程式都會強制執行這些規則。
+
+活動組織自動流動：`session.orgId` → `AGENT_ORG_ID` → SQL 行範圍，因此用 `org_id` 標記的資料對於其他組織甚至代理來說都是不可見的。完整模型請參見 [Security & Data Scoping](/docs/security)。
+
+## 共用MCP伺服器 {#shared-mcp}
+
+跨工作區應用共用 MCP 伺服器的推薦選項（按優先順序排列）：
+
+1. **調度工作區 MCP 資源** — 在 Dispatch 中的 **所有應用程式** 範圍內新增 `mcp-servers/<name>.json` 資源。工作區中的每個應用程式在執行時都會繼承 MCP 伺服器，無需進行檔案編輯或重新部署。僅當伺服器特定於應用程式時才授予選定的應用程式。代幣存在於 Dispatch 保險庫中；從資源 JSON 和 `${keys.NAME}` 中引用它們。
+
+2. **根 `mcp.config.json`** — 在工作區根目錄中放置一個檔案，工作區中的每個應用程式都會連線到相同的 MCP 伺服器。各個應用程式可以使用自己的 `mcp.config.json` 進行覆蓋（應用程式根獲勝）。將此用於不需要每使用者保管庫憑證的本機/檔案系統 MCP 伺服器（`@modelcontextprotocol/server-filesystem`、`claude-in-chrome`、Playwright）。
+
+3. **設定 UI（個人/組織範圍）** — 對於遠端 HTTP MCP 伺服器，使用者可以從個人或團隊（組織）範圍的設定 UI 新增它們 — 無需檔案編輯，熱重新載入到正在執行的代理中。
+
+請參閱 [MCP Clients](/docs/mcp-clients) 了解設定架構、優先級規則和集線器設定。
+
+## 共用環境變數 {#shared-env}
+
+工作區根 `.env` 會自動載入到每個應用程式中。將共用金鑰放在根目錄中一次（`ANTHROPIC_API_KEY`、`A2A_SECRET`、`BETTER_AUTH_SECRET`、`DATABASE_URL`、`BUILDER_PRIVATE_KEY` 等），每個應用程式都會獲取它們。每個應用程式覆蓋進入 `apps/<name>/.env` 並在衝突時獲勝。
+
+對於執行時應用程式憑證，與手動編輯 `.env` 檔案相比，更喜歡使用 DispatchVault。保管庫預設為所有應用程式存取，因此每個儲存的保管庫金鑰可供每個工作區應用程式使用，並且可以使用 `sync-vault-to-app` 推送。僅當應用程式需要顯式的每金鑰授權時，才將保管庫切換到手動模式。
+
+```text
+my-company-platform/
+├── .env                           # shared: ANTHROPIC_API_KEY=... , A2A_SECRET=... , ...
+└── apps/
+    └── mail/
+        └── .env                   # optional overrides just for mail
+```
+
+一些入門流程是開箱即用的工作區感知型：
+
+- **Builder `/cli-auth`**：從任何應用程式中點選“連線 Builder”會將 `BUILDER_PRIVATE_KEY` 和朋友寫入 **工作區根目錄** `.env`，因此每個應用程式都會立即獲得瀏覽器存取權限。
+- **環境變數設定路由** (`POST /_agent-native/env-vars`)：在工作空間內時，預設寫入工作空間根 `.env`。在內文中傳遞 `scope: "app"` 以覆蓋一個應用程式。
+
+## 共用憑證 {#shared-credentials}
+
+預設情況下，同一工作區中的應用程式指向同一 `DATABASE_URL`，因此框架憑證存儲可以使憑證可供每個應用程式使用，而無需每個應用程式設定。直接使用 `@agent-native/core/credentials`，或者如果您的工作區需要更嚴格的命名約定，則在 `packages/shared` 中新增瘦助手。
+
+## 共用設計權杖 {#design-tokens}
+
+該框架基於 Tailwind v4。僅當工作區有真正的品牌權杖可供共用時，才將共用的 CSS 檔案新增到 `packages/shared`，然後從每個應用程式的 `app/global.css` 匯入它：
+
+```css
+@import "tailwindcss";
+@import "@my-company-platform/shared/styles/tokens.css";
+@source "./**/*.{ts,tsx}";
+
+:root {
+  --background: 0 0% 100%; /* ...brand tokens... */
+}
+.dark {
+  --background: 220 6% 6%; /* ... */
+}
+```
+
+品牌顏色、版式、間距比例和任何共用元件類都可以存在於該一個 CSS 檔案中。在 `packages/shared` 中更新它，每個應用程式都會在下一個版本中重新命名。
+
+## 部署 {#deployment}
+
+您有兩個選取：**統一部署**（工作區的預設設定）或每個應用程式獨立部署。
+
+### 統一部署（推薦）
+
+一個指令建置工作區中的每個應用程式，並將它們發送到單個來源，每個應用程式一個路徑：
+
+```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` 和 `_routes.json` 的調度程序工作人員。 `npx @agent-native/core@latest deploy --preset netlify` 支持 Netlify；它在 `.netlify/functions-internal/<app>-server` 下發出應用程式功能，並生成重新導向，使靜態資產不受強制，因此 CDN 首先提供檔案。 `npx @agent-native/core@latest deploy --preset vercel` 支持 Vercel；它使用 Vercel 的建置輸出 API 編寫根 `.vercel/output` 包。
+
+```an-diagram title="統一部署：一個來源，每個應用一個路徑" summary="每個應用程式都遵循單一來源，因此登入工作階段和跨應用程式 A2A 是免費的。"
+{
+  "html": "<div class=\"deploy\"><div class=\"diagram-box accent\">your-agents.com<br><small class=\"diagram-muted\">one DNS record &middot; one cert &middot; one CDN</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"deploy-apps\"><div class=\"diagram-box\">/mail/*</div><div class=\"diagram-box\">/calendar/*</div><div class=\"diagram-box\">/forms/*</div></div><div class=\"diagram-pill ok\">shared login cookie on the apex &bull; same-origin A2A, no CORS</div></div>",
+  "css": ".deploy{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.deploy .deploy-apps{display:flex;flex-direction:column;gap:8px}.deploy .diagram-arrow{font-size:24px}.deploy .diagram-pill{flex-basis:100%}"
+}
+```
+
+同來源\*\*才是真正的回報所在：
+
+- **共用登入工作階段。** Better Auth 在頂點域上設定其 cookie，因此登入任何應用程式都會登入到每個應用程式。沒有跨域SSO舞蹈。
+- **零設定跨應用程式 A2A。** `@mail` 標記 `@calendar` 成為同來源獲取 - 兄弟之間沒有 CORS，沒有 JWT 簽名。外部A2A仍沿用至今的JWT。
+- **一條 DNS 紀錄，一個證書，一個 CDN 快取。**
+
+發布 `dist/` 輸出：
+
+```bash
+wrangler pages deploy dist
+```
+
+對於 Netlify：
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify --build-only
+```
+
+對於 Vercel Git 部署，將建置指令設定為：
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+### 公開應用路由
+
+工作區應用程式預設為內部應用程式。對於具有僅登入管理頁面的公開網站，設定公開受眾並保護該應用程式的 `package.json` 中的管理前綴：
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+對於大多數帶有一些公開頁面的內部應用程式，請保留受眾內部和列表頁面前綴：
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+這些設定僅影響唯讀頁面導覽。框架工具、代理聊天、A2A、保管庫存取和任意 API 保持驗證，除非應用程式顯式聲明帶有 `createAuthPlugin({ publicPaths: [...] })` 的公開前綴。
+
+### 每個應用獨立部署
+
+更喜歡每個應用程式在自己的域中（`mail.company.com`、`calendar.company.com`）？工作區中的每個應用程式仍然是獨立可部署的 - `cd apps/mail && npx @agent-native/core@latest build` 的行為與獨立腳手架完全相同。然後，跨應用程式 A2A 通過具有共用 `A2A_SECRET` 的標準 JWT 簽名路徑。單獨部署的應用程式之間的跨域 SSO 由以 Dispatch 作為中心的身分聯合處理 - 請參閱 [Cross-App SSO](/docs/cross-app-sso)；統一的單來源部署避免了需要它。
+
+### 共用資料庫、共用憑證
+
+無論您選取什么，都將每個應用程式指向相同的 `DATABASE_URL` 以獲得開箱即用的跨應用程式狀態：一組使用者帳戶、一組組織、一組共用設定。如果每個應用程式都有自己的資料庫，那么工作區模式仍然有效 - 您只是失去了共用狀態的故事。
+
+共用包本身永遠不會獨立部署。這是一個 `workspace:*` 依賴項，pnpm 符號連結到每個應用程式的 `node_modules/`，因此每個應用程式在建置時透明地捆綁它需要的任何內容。
+
+## 超出範圍（目前） {#out-of-scope}
+
+工作區圖案故意變窄。它故意不處理一些事情：
+
+- **加密憑證保管庫。**首選調度保管庫來獲取執行時應用程式憑證（請參閱 [Shared environment variables](#shared-env)）。非保管庫回退路徑（直接寫入框架 `settings` 表的共用憑證）現在將它們存儲為純文本，因此當您依賴它時，請負責任地輪換。
+- **將共用程式碼發布到私人npm。**共用包僅限`workspace:*`；通過私人註冊表進行多儲存庫共用是可行的，但無法搭建。
+- **固定元件庫。** `packages/shared` 是您放置共用元件的位置。該框架不會強制 shadcn/ui 或任何其他系統進入該插槽。
+
+## 另請參閱 {#see-also}
+
+- [Workspace](/docs/workspace) - 工作區中每個應用共用的自訂層（`AGENTS.md`、`LEARNINGS.md`、個人內存、skills、自訂代理）。
+- [Workspace Governance](/docs/workspace-management) — 分支、CODEOWNERS、一個儲存庫中多個應用的 PR 審核。
+- [Multi-Tenancy](/docs/multi-tenancy) — 組織、角色和每個組織的資料隔離。
+- [Cross-App SSO](/docs/cross-app-sso) — 用於單獨域部署的身分聯合。
+- [Dispatch](/docs/dispatch) - 執行時控制平面，通常位於多應用工作區中，作為機密庫、整合目錄和審批中心。

package/docs/content/locales/zh-TW/multi-tenancy.md

@@ -0,0 +1,52 @@
+---
+title: "多租戶"
+description: "每個代理本機應用程式都是開箱即用的多租戶 - 組織、團隊成員、角色和每個組織的資料隔離，且零設定。"
+---
+
+# 多租戶
+
+每個代理本機應用程式都是開箱即用的多租戶。組織、團隊成員、基於角色的存取和每個組織的資料隔離均內置於框架中，零設定。
+
+## 您免費獲得的東西 {#free}
+
+新的 `npx @agent-native/core@latest create` 腳手架已附帶：
+
+- **使用者註冊和登入** — 參見 [Authentication](/docs/authentication)。
+- **組織** — 使用者建立組織並通過電子郵件邀請成員。每個組織都是一個完全隔離的租戶。
+- **角色** — 每個成員都是 `owner`、`admin` 或 `member`； actions可以檢視角色是否授權。
+- **組織切換** — 工作階段跟蹤活動組織 (`session.orgId`)，切換它會更改使用者和代理看到的資料。
+- **每組織資料隔離** — 每個查詢都會自動限定到活動組織。
+
+如果您正在評估 CRM、專案跟蹤器、支持收件箱或任何團隊工具的原生代理，那么多租戶基礎已經存在。所有第一方範本都是多租戶的 - 請參閱 [Cloneable SaaS templates](/docs/cloneable-saas) 獲取列表。
+
+```an-diagram title="組織成員資格和隔離" summary="使用者以 owner/admin/member 身分加入組織。每個可擁有的行都帶有擁有它的租戶的 org_id ，並且沒有行跨越邊界泄漏。"
+{
+  "html": "<div class=\"mt-grid\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">組織 A</span><small class=\"diagram-muted\">members: alice (owner), bob (member)</small><div class=\"diagram-box\">rows where org_id = A</div></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">組織 B</span><small class=\"diagram-muted\">members: carol (owner)</small><div class=\"diagram-box\">rows where org_id = B</div></div></div><div class=\"mt-wall\" aria-hidden=\"true\"><span class=\"diagram-pill warn\">no cross-org reads</span></div>",
+  "css": ".mt-grid{display:flex;gap:16px;flex-wrap:wrap}.mt-grid .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px;flex:1;min-width:200px}.mt-wall{display:flex;justify-content:center;margin-top:12px}"
+}
+```
+
+## 組織切換者 UI {#org-switcher}
+
+組織切換者和成員 UI 在每個範本中呈現，無需額外程式碼。他們在 `/_agent-native/org/*` 下驅動核心組織 REST 路由（建立組織、切換組織、列出/邀請/刪除成員、更改角色、設定允許的電子郵件域）。使用者從切換器中選取活動組織；成員面板處理邀請和角色變更。
+
+這是框架自己的`org/`模塊，而不是Better Auth的組織外掛（故意不註冊）。完整的組織管理介面——`createOrganization`、REST 路由和範本編寫的 `defineAction` 包裝器（如 `invite-member`）——紀錄在 [Authentication → Organizations](/docs/authentication#organizations) 中。
+
+## 隔離的工作原理 {#isolation}
+
+租戶資料由 `org_id` 列（由 `ownableColumns()` 新增）隔離，框架自動將每個查詢範圍限定為活動組織：`session.orgId → AGENT_ORG_ID → SQL`。當使用者切換組織時，UI、actions 和代理都只能看到該組織的資料 - 代理無法存取使用者不是其成員的組織的資料。
+
+```an-diagram title="從工作階段到作用域 SQL" summary="工作階段中的活動組織變為 AGENT_ORG_ID，框架將其折疊到每個查詢的 WHERE 子句中。"
+{
+  "html": "<div class=\"mt-pipe\"><div class=\"diagram-node\">session.orgId<br><small class=\"diagram-muted\">active org on session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">AGENT_ORG_ID<br><small class=\"diagram-muted\">request context</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL row scoping<br><small class=\"diagram-muted\">WHERE owner_email = ? AND org_id = ?</small></div></div>",
+  "css": ".mt-pipe{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mt-pipe .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.mt-pipe .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+這與用於每使用者範圍的管道相同。對於 SQL 級別的機制、`ownableColumns()` 合約和 `accessFilter` / `resolveAccess` / `assertAccess` 防護，請參閱 [Security → Data Scoping](/docs/security#data-scoping) — 範圍界定管道的單一事實來源。
+
+## 相關檔案 {#related}
+
+- [Authentication](/docs/authentication#organizations) — 工作階段、社交提供者和組織管理介面
+- [Security → Data Scoping](/docs/security#data-scoping) - SQL 級隔離、`ownableColumns()` 合約和存取防護
+- [Multi-App Workspace](/docs/multi-app-workspace) — 在具有共用驗證和 RBAC 的單一儲存庫中託管多個代理本機應用程式