@agent-native/core 0.79.1 → 0.79.5

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

@@ -0,0 +1,321 @@
+---
+title: "工作區連線"
+description: "用於 connect-once-use-everywhere 整合的共用提供者元資料、授權和憑證引用。"
+---
+
+# 工作區連線
+
+工作區連線是可重用整合元資料的框架原語。它們使“連線一次、授予應用程式、重複使用憑證”成為可能，而無需假裝每個提供者都是完全通用的。
+
+## 快速入門 {#quickstart}
+
+### 四個概念
+
+- **連線** — 指定提供者帳戶（`team-slack`、`acme-hubspot`）。紀錄提供者 ID、帳戶標籤、狀態、範圍和安全設定。從不存儲秘密值。
+- **授予** — 特定應用程式使用連線的權限。未經授權的應用程式無法檢視連線的憑證。
+- **credentialRef** — 指向保管庫機密 (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`) 的指針。連線表明權杖所在的位置；金庫儲存著價值。
+- **就緒** - 應用程式看到的組合狀態：`connected`（已授予 + 存在憑證）、`needs_grant`、`needs_credentials`、`needs_attention` 或 `not_configured`。
+
+```an-diagram title="連線一次、授予應用程式、重複使用憑證" summary="連線儲存提供者元資料（絕不是秘密）和指向保管庫的 credentialRefs。每個應用程式授予解鎖它。應用程式讀取單個就緒狀態。"
+{
+  "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, 狀態、作用域、設定 &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
+  "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
+}
+```
+
+### 工作範例：Slack
+
+連線 Slack 一次並將其授予 Brain and Analytics：
+
+```ts
+import {
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+await upsertWorkspaceConnection({
+  id: "acme-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "Acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history", "chat:write"],
+  config: {
+    teamDomain: "acme",
+    channelHints: ["product", "dev-fusion", "customer-success"],
+  },
+  credentialRefs: [{ key: "SLACK_BOT_TOKEN", scope: "org" }],
+});
+
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "analytics",
+});
+```
+
+```an-schema title="連線模型" summary="A connection records safe provider metadata and credentialRefs (pointers, not secrets). Each grant unlocks one app — one connection, many grants."
+{
+  "entities": [
+    {
+      "id": "conn",
+      "name": "workspace_connections",
+      "note": "指定的提供者帳戶。從不存儲秘密值。",
+      "fields": [
+        { "name": "id", "type": "string", "pk": true, "note": "e.g. acme-slack" },
+        { "name": "provider", "type": "string", "note": "穩定的提供者 ID，e.g。松弛" },
+        { "name": "label", "type": "string" },
+        { "name": "accountId", "type": "string", "nullable": true },
+        { "name": "accountLabel", "type": "string", "nullable": true },
+        { "name": "status", "type": "string", "note": "e.g. connected" },
+        { "name": "scopes", "type": "string[]", "nullable": true },
+        { "name": "config", "type": "json", "nullable": true, "note": "安全、非秘密設定" },
+        { "name": "credentialRefs", "type": "json", "nullable": true, "note": "pointers to vault keys, e.g. { key, scope }" }
+      ]
+    },
+    {
+      "id": "grant",
+      "name": "workspace_connection_grants",
+      "note": "每個應用程式使用連線的權限。",
+      "fields": [
+        { "name": "connectionId", "type": "string", "fk": "conn.id" },
+        { "name": "appId", "type": "string", "note": "e.g。大腦、分析" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "conn", "to": "grant", "kind": "1-n", "label": "grants apps" }
+  ]
+}
+```
+
+### 調用哪些應用
+
+在要求使用者貼上新金鑰之前，請先檢查準備情況：
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+  provider: "slack",
+  includeConnections: "all",
+});
+
+const slack = catalog.providers[0];
+if (slack.workspaceConnection.grantState === "needs_grant") {
+  // Show "Grant Brain access" instead of asking for a second Slack token.
+}
+if (slack.readiness.status === "needs_credentials") {
+  // Show the missing credential ref names, never a secret value.
+}
+```
+
+## 參考 {#reference}
+
+### 提供者目錄
+
+從`@agent-native/core/connections`匯入目錄：
+
+```ts
+import {
+  getWorkspaceConnectionProvider,
+  listWorkspaceConnectionProvidersForTemplate,
+  workspaceConnectionProviderSupports,
+} from "@agent-native/core/connections";
+
+const brainProviders = listWorkspaceConnectionProvidersForTemplate("brain");
+const slack = getWorkspaceConnectionProvider("slack");
+
+if (workspaceConnectionProviderSupports("slack", "messages")) {
+  // Offer a Slack source, sync check, or onboarding step.
+}
+```
+
+初始提供者 ID 為：
+
+| 提供者         | 能力                     | 常見用途                 |
+| -------------- | ------------------------ | ------------------------ |
+| `slack`        | 搜尋、匯入、訊息         | 大腦、調度、分析         |
+| `github`       | 搜尋、匯入、程式碼、檔案 | 大腦、分析、調度         |
+| `notion`       | 搜尋、匯入、檔案         | 大腦、內容、調度         |
+| `gmail`        | 搜尋、匯入、訊息         | 郵件、大腦、調度         |
+| `google_drive` | 搜尋、匯入、檔案         | 大腦、內容、幻燈片       |
+| `hubspot`      | 搜尋、匯入、crm          | 分析、大腦、郵件         |
+| `granola`      | 搜尋、匯入、會議、檔案   | 大腦、行事曆、調度       |
+| `clips`        | 搜尋、匯入、會議         | 大腦、剪輯、影片         |
+| `generic`      | 搜尋、匯入、檔案         | 自訂 webhooks 和檔案投放 |
+
+憑證金鑰僅為名稱，例如 `SLACK_BOT_TOKEN` 或 `GITHUB_TOKEN`。提供者元資料絕不能包含實際的憑證值。
+
+### 連線存儲API
+
+```ts
+import {
+  listWorkspaceConnectionProviderCatalogForApp,
+  listWorkspaceConnectionGrants,
+  listWorkspaceConnections,
+  summarizeWorkspaceConnectionProviderForApp,
+  summarizeWorkspaceConnectionProviderReadiness,
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+  revokeWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+const connections = await listWorkspaceConnections({ includeDisabled: true });
+const grants = await listWorkspaceConnectionGrants({ appId: "brain" });
+
+const appGrant = summarizeWorkspaceConnectionProviderForApp({
+  providerId: "slack",
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const readiness = summarizeWorkspaceConnectionProviderReadiness({
+  provider: slack!,
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const brainCatalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+});
+```
+
+`credentialRefs` 陣列指向保管庫金鑰；它不是憑證存儲。例如，`{ key: "SLACK_BOT_TOKEN", scope: "org" }` 告訴授權應用程式在需要調用 Slack 時查找名為 `SLACK_BOT_TOKEN` 的組織範圍保管庫機密。連線級引用描述了提供者帳戶；授予級別的引用可以縮小或覆蓋特定應用程式應使用的內容。
+
+當存在活動組織時，連線行的範圍僅限於活動組織。如果沒有組織，它們的範圍僅限於經過驗證的使用者。授予行使用相同的範圍。
+
+**舊版 `allowedApps` 欄位：** `allowedApps: []` 表示同一範圍內的每個應用程式都可以使用該連線； `allowedApps: ["dispatch"]` 通過舊欄位授予存取權限。使用顯式 `workspace_connection_grants` 行進行新設定 - 它們使撤銷、審核和每個應用程式的準備工作變得更容易。 `revokeWorkspaceConnectionGrant(connectionId, appId)` 刪除了顯式授權，但不更改舊版 `allowedApps`。
+
+使用 `summarizeWorkspaceConnectionProviderForApp()` 和 `summarizeWorkspaceConnectionProviderReadiness()` 來獲取面向應用的狀態，而不是手動滾動授權檢查。共用摘要返回 `grantState`、`grantAvailability`、安全憑證引用名稱、每個應用程式連線行以及就緒欄位（例如 `readyConnectionCount` 和 `missingRequiredCredentialKeys`）。
+
+對於新的應用程式設定螢幕，更喜歡 `listWorkspaceConnectionProviderCatalogForApp()` 作為更高級別的邊界 - 它將提供程序目錄、範圍連線、顯式授權、每個應用程式存取摘要和提供程序準備情況結合到一個安全的形狀中。
+
+### 這如何補充金庫
+
+憑證庫回答：“秘密存儲在哪裡，誰可以存取它，以及哪些應用程式被授予它？”
+
+工作區連線提供程序元資料回答：“這是哪個提供程序，它能做什么，可能需要什么憑證金鑰，以及哪些範本應提供它？”
+
+```an-diagram title="連線存儲與保管庫" summary="金庫擁有秘密價值。連線擁有提供者元資料和 credentialRefs（指針）。在執行時，應用程式通過授予的連線解析引用並從保管庫讀取值。"
+{
+  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">連線存儲</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">狀態、作用域、設定</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">應用 action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">絕不返回給代理或 UI</small></div></div></div>",
+  "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+同時使用兩者：
+
+1. Dispatch（或其他工作區設定流程）建立底層保管庫機密或 OAuth 憑證引用。
+2. 工作區連線存儲紀錄提供者帳戶、安全元資料、憑證引用和應用授權。
+3. 每個應用程式從目錄中讀取提供程序元資料，並從共用存儲中讀取連線/授權摘要。
+4. 應用 UI 顯示就緒狀態：已連線、已授予但不健康、需要授予、缺少憑證或僅元資料。
+5. 特定於應用程式的 SQL 僅存儲特定於應用程式的來源 ID、游標、過濾器、同步窗口、指標定義、審核規則和使用者選取。
+6. 應用程式 actions 在執行時通過授予的連線引用和保管庫解析憑證，並且從不返回秘密值。
+
+### 提供者讀取器執行時
+
+提供者-讀取器層首先是一個契約，而不是每個提供者都有一個共用的實時讀取器的承諾。讀者定義描述了支持的操作、憑證要求和實施狀態：`metadata-only`、`template-owned` 或 `shared`。執行時解析應用程式授予的工作區連線和憑證引用，調用註冊的處理程序，並返回規範化的專案而不暴露秘密值。
+
+如今，大多數實時處理程序仍然由範本擁有，這意味著 Brain 仍然擁有 Slack/GitHub 攝取行為，而 Analytics 仍然擁有分析解釋。僅當特定於提供者的 API 調用、分頁面、權限和結果語義真正可跨範本重用時，才將讀者提升為 `shared`。
+
+### 應用準備模式
+
+使用共用提供者憑證的應用程式應公開唯讀準備操作和一個小的設定表面，覆蓋：
+
+- **提供者目錄：**提供者 ID、標籤、功能、推薦的範本用途以及來自 `@agent-native/core/connections` 的所需憑證金鑰名稱。
+- **工作區摘要：**來自 `@agent-native/core/workspace-connections` 的連線計數、活動/授權計數、授權狀態、憑證引用名稱和非秘密帳戶標籤。
+- **提供者準備情況：** `ready`、`needs_credentials`、`needs_attention`、`checking`、`disabled` 或 `not_configured`（通過 `summarizeWorkspaceConnectionProviderReadiness()`）。
+- **來源狀態：**應用程式本機設定的來源、光標、同步狀態和下一步操作。
+
+Brain's Sources 頁面是參考實現。它在 Brain 來源紀錄旁邊顯示可重用的工作區連線提供程序，將授權狀態標記為 `connected`、`granted`、`needs_grant` 或 `not_connected`，並將提供程序的執行狀況顯示為就緒、缺少金鑰、需要授權、需要修複或僅元資料。
+
+### 建置可重複使用的連線器
+
+當新的提供程序應跨多個範本工作時：
+
+1. **提供者元資料：**在 `@agent-native/core/connections` 中新增或重用提供者。這是穩定 ID、顯示標籤、功能列表、推薦範本用途和憑證金鑰名稱。
+2. **工作區連線：** Dispatch 或其他工作區設定介面通過 `@agent-native/core/workspace-connections` 存儲連線帳戶的安全元資料、狀態、範圍、`credentialRefs` 和應用程式授權。
+3. **應用程式本機來源：** Brain、Analytics、Mail 或其他應用程式僅存儲其擁有的特定於應用程式的選取，例如 Slack 通道、GitHub 儲存庫、HubSpot 物件過濾器、同步游標或輪詢節奏。
+
+不要在每個應用程式中重複 OAuth/權杖存儲。連線紀錄顯示“這是 Acme Slack，其代幣位於 `SLACK_BOT_TOKEN`”；應用程式本機訊息來源稱“Brain 可能會從該 Slack 連線中攝取 `#product` 和 `#dev-fusion`。”
+
+### 調度控制平面設定
+
+Dispatch 公開了控制平面 actions，該控制平面編寫應用程式可以直接調用的相同共用存儲函數：
+
+```ts
+// templates/dispatch/actions/upsert-workspace-connection.ts delegates to this.
+await upsertWorkspaceConnection({
+  id: "team-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history"],
+  config: { teamDomain: "acme", preferredChannels: ["product", "dev-fusion"] },
+  credentialRefs: [
+    {
+      key: "SLACK_BOT_TOKEN",
+      scope: "org",
+      provider: "slack",
+      label: "Slack bot token",
+    },
+  ],
+});
+
+// Then grant the apps that should reuse the provider.
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "analytics",
+});
+```
+
+僅當連線應可供同一範圍內的每個應用程式使用時，才使用 `allowedApps: []`。優先選取用於正式環境設定的顯式授權行。
+
+### 憑證解析
+
+應用程式執行程式碼通過活動請求範圍中的保管庫解析來自授予的 `credentialRefs` 的憑證值。 Brain 的 `source-credentials.ts` 是目前的參考實現：它列出了提供者的工作區連線，檢查 `getWorkspaceConnectionAppAccess` 中的 `appId: "brain"`，合並連線級別和授予級別的憑證引用，並讀取第一個匹配的作用域保管庫機密。其他應用程式應遵循該形狀，而不是達到 `process.env`。
+
+## 設計筆記 {#design-notes}
+
+<details>
+<summary>閱讀器-“一次連線，到處使用”的推廣政策和路徑</summary>
+
+### 應用程式本機邊界
+
+共用連線和應用程式本機來源之間的邊界是有意的。如今可重用的是提供者身分、憑證引用解析、每個應用程式授權、提供者準備情況、安全帳戶元資料以及標準化的提供者-讀者合約。尚未通用的是大多數實時提供者 API 讀取、OAuth 流所有權、攝取游標、來源過濾器、同步節奏和域解釋。除非將讀取器實現顯式提升為共用，否則它們將保留在擁有工作流程的應用程式中。
+
+應用程式來源連線器不應讀取部署級環境變數作為使用者/組織來源憑證的後備。環境變數對於部署來說是全域的，並且不表達工作區授權。
+
+代理應遵循一個簡單的規則：如果使用者要求連線 Slack、GitHub、HubSpot、Gmail、Google Drive、Granola 或其他共用提供程序，請首先檢查工作區連線目錄。如果提供者是 `connected`，則使用它。如果是 `needs_grant`，請請求或執行應用程式授權。如果是 `needs_credentials`，請索要丟失的保管庫金鑰。僅當不存在可重用連線時才請求新的原始金鑰。
+
+### “一次連線，隨處使用”之路
+
+提供者目錄和贈款存儲是更廣泛的工作空間層的基礎：
+
+- 共用提供者 ID 和功能名稱使範本保持一致。
+- 工作區級別的清單可以顯示在 Brain、Mail、Analytics、Dispatch 和未來應用程式中設定了哪些提供程序。
+- 連線行紀錄帳戶標籤、狀態、允許的應用、憑證引用和執行狀況檢查，而無需更改面向範本的提供程序 ID。
+- 授予行讓工作區所有者連線一次，然後在工作區采用各個應用程式時啟用它們。
+- 代理可以在應用程式之間路由工作，了解哪些提供者已連線以及哪些應用程式已獲得授權。
+- 聯合搜尋可以請求具有 `search`、`docs`、`messages`、`meetings`、`crm` 或 `code` 功能的提供者，而不是對每個應用的連線器列表進行硬編碼。
+- 特定於提供者的讀取器、OAuth 刷新流、攝取檢查點和應用程式擁有的資料模型可以稍後共用，但今天的工作區連線並不暗示它們。
+
+保持嚴格的邊界：提供者元資料可以安全地顯示；憑證值保留在保管庫中。
+
+</details>

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

@@ -0,0 +1,175 @@
+---
+title: "工作區治理"
+description: "分支、CODEOWNERS、PR 審查以及 Dispatch 如何與 git 級治理一起處理執行時治理。"
+---
+
+# 工作區治理
+
+> **哪個工作區檔案？** 此頁面涵蓋 **治理** - 誰在一個儲存庫中的多個應用程式中審查、批準和擁有內容。對於工作空間*是什么*（定制層），請參閱 [Workspace](/docs/workspace)；對於部署形狀（一個單一儲存庫，許多應用程式），請參閱 [Multi-App Workspaces](/docs/multi-app-workspace)。
+
+本指南涵蓋了執行代理本機工作區的操作方面 - 如何分支、誰審查什么、如何設定程式碼所有權以及 Dispatch 控制平面如何適應您的治理模型。
+
+```an-diagram title="兩個治理平面" summary="Git 管理程式碼； Dispatch 控制執行時。它們是互補的——不要將一個複製到另一個中。"
+{
+  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git 和 GitHub</span><strong>程式碼治理</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR 評審</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
+  "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
+}
+```
+
+## 分支
+
+### 功能分支
+
+對所有工作使用短期功能分支：
+
+```
+main                         ← production
+├── feat/mail-filters        ← single-app change
+├── feat/core-oauth-refresh  ← framework change
+├── fix/analytics-chart      ← targeted bug fix
+└── feat/vault-encryption    ← dispatch/infra change
+```
+
+**命名約定：**
+
+- **單個應用程式更改：** `feat/<app>-<description>` 或 `fix/<app>-<description>` — 例如`feat/mail-thread-search`、`fix/calendar-recurrence-parse`
+- **框架更改：** `feat/core-<description>` 或 `fix/core-<description>` — 例如`feat/core-polling-v2`
+- **調度更改：** `feat/dispatch-<description>` — 例如`feat/dispatch-vault-policies`
+- **跨應用程式更改：**如果框架更改需要範本更新，請在一個分支中執行這兩項操作，以便它們以原子方式發布
+
+保持分支短暫。長期存在的分支與主分支分離，並造成痛苦的合並——尤其是在多個團隊每天推送的單一儲存庫中。
+
+### 非開發人員分支
+
+並不是每個需要進行更改的人都對 git 感到滿意。 [Builder.io](https://www.builder.io) 支持可視化分支模型，可對應到底層的 git 分支 - 對於內容和副本更改、布局調整、設計迭代以及無需開發環境的 A/B 測試非常有用。
+
+## 程式碼所有權
+
+程式碼治理由儲存庫根目錄中的幾個檔案設定：
+
+```an-file-tree title="repo 中的治理設定"
+{
+  "entries": [
+    { "path": ".github/CODEOWNERS", "note": "按變更路徑自動分配 reviewers" },
+    { "path": ".github/labeler.yml", "note": "按 app 自動給 PR 加標籤" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace 級別：寬範圍 review" },
+    { "path": "package.json", "note": "Workspace 級別：平台團隊負責" }
+  ]
+}
+```
+
+GitHub 的 CODEOWNERS 檔案會根據更改的檔案自動將審閱者分配給 PR。在儲存庫根目錄建立 `.github/CODEOWNERS`：
+
+```
+# Framework core — affects every app; platform team reviews all changes
+packages/core/                     @your-org/platform-team
+
+# 調度控制平面——秘密、整合、工作空間資源
+templates/dispatch/                @your-org/platform-team
+
+# 每個應用程式所有權 - 每個團隊都會審查自己的應用程式
+templates/mail/                    @your-org/mail-team
+templates/analytics/               @your-org/analytics-team
+templates/calendar/                @your-org/calendar-team
+# ... add an entry per app
+
+# 工作區級別設定 - 廣泛審查，因為它影響每個人
+.github/                           @your-org/platform-team
+package.json                       @your-org/platform-team
+pnpm-workspace.yaml                @your-org/platform-team
+```
+
+關鍵提示：使用 GitHub 團隊 (`@org/team`)，而不是個人。框架和調度更改應始終需要平台審查。請參閱 [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) 了解 glob 語法和多所有者模式。
+
+要啟用所需的審查：設定 → 分支 → `main` 的分支保護 → **在合並之前需要拉取請求** → **需要程式碼所有者的審查**。
+
+## 公關標籤
+
+通過應用使用 `.github/labeler.yml` 自動標記 PR（摘錄）：
+
+```yaml
+app:mail:
+  - changed-files:
+      - any-glob-to-any-file: templates/mail/**
+app:analytics:
+  - changed-files:
+      - any-glob-to-any-file: templates/analytics/**
+core:
+  - changed-files:
+      - any-glob-to-any-file: packages/core/**
+```
+
+然後新增 [actions/labeler](https://github.com/actions/labeler) 操作 - 請參閱該儲存庫的 README 以了解完整的工作流程 YAML。開啟或更新 PR 時，標籤會自動應用。
+
+## 公關審核指南
+
+| 更改型別                              | 誰評論                          | 要注意什么                                          |
+| ------------------------------------- | ------------------------------- | --------------------------------------------------- |
+| **僅限應用程式** (`templates/<app>/`) | 擁有應用團隊                    | 域正確性、操作模式                                  |
+| **框架**（`packages/core/`）          | 平台團隊 + 一個受影響的應用團隊 | 重大變更、性能、向後兼容性                          |
+| **架構遷移**                          | 平台團隊+高級工程師             | 資料安全、方言不可知論（SQLite + Postgres）         |
+| **Actions**                           | 所屬團隊                        | Actions 都是代理工具 AND HTTP 端點 - 從兩個角度回顧 |
+| **跨應用 A2A**                        | 兩個應用團隊                    | 如果更改A2A介面，調用者需要知道                     |
+| **調度庫/資源**                       | 平台團隊                        | 秘密存取、授予範圍、誰獲得什么                      |
+
+### 並發代理工作
+
+代理本機工作區通常有多個 AI 代理同時在同一分支上工作。這是設計使然——代理共用一個分支並獨立推送。
+
+```an-callout
+{ "tone": "warning", "body": "**The later commit wins.** Two agents touching the same file won't conflict at commit time — the conflict surfaces at review. Run `pnpm run prep` (typecheck + test + format) before pushing, and don't revert changes you didn't make unless they're clearly broken." }
+```
+
+在此環境中審核 PR 時：
+
+- **不要恢復您未進行的更改**除非它們明顯損壞
+- **檔案可能會被同一 PR 中的多個代理修改** - 這是正常的
+- **在推送之前執行 `pnpm run prep`**（型別檢查 + 測試 + 格式）以捕獲代理更改之間的整合問題
+- **如果兩個代理接觸同一個檔案，**較晚的提交獲勝。衝突在審查時出現，而不是在提交時出現
+- **修複 PR 中任何程式碼中的錯誤，**無論是哪個代理編寫的。 PR 會作為一個整體進行審核。
+
+## 調度作為治理
+
+[Dispatch](/docs/dispatch) 應用程式是工作區的執行時控制平面。它通過執行時治理補充了 git 級治理：
+
+| 關注             | Git 和 GitHub           | 調度                                      |
+| ---------------- | ----------------------- | ----------------------------------------- |
+| 誰可以更改程式碼 | CODEOWNERS，分支保護    | —                                         |
+| 誰可以存取機密   | —                       | 保險櫃政策、撥款、請求工作流程            |
+| 代理遵循哪些指示 | —                       | 全域工作區資源（AGENTS.md、說明、skills） |
+| 共用哪些代理     | —                       | 工作區代理設定檔案                        |
+| 整合庫存         | —                       | 工作區連線和整合目錄                      |
+| 執行時變更批準   | —                       | 調度審批流程                              |
+| 審計跟蹤         | `git log` / `git blame` | Vault審核+調度審核記錄                    |
+| 訊息傳遞和路由   | —                       | Slack / Telegram 整合                     |
+
+**Git 處理程式碼治理。 Dispatch 處理執行時治理。** 不要嘗試在 Dispatch 內複製 git 工作流程，反之亦然。
+
+Dispatch 管理：保管庫機密、可重用工作區連線、工作區資源（skills、說明、代理設定檔案、MCP 伺服器）、批準和審核記錄。公開應用路由設定（`workspaceApp.audience` / `publicPaths` / `protectedPaths`）請參見[Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment)。
+
+資源模型和規範路徑請參見[Workspace — Global resources](/docs/workspace#global-resources)。
+
+## 設定清單
+
+對於新工作區，執行 `npx @agent-native/core@latest create` 後：
+
+**Git 和 GitHub:**
+
+- [ ] 建立具有每個應用團隊所有權的 `.github/CODEOWNERS`
+- [ ] 在 `main` 上啟用分支保護並進行必要的程式碼所有者審核
+- [ ] 新增 `.github/labeler.yml` 以通過應用自動標記 PR
+- [ ] 為每個應用和平台團隊建立 GitHub 團隊
+
+**調度：**
+
+- [ ] 將共用機密新增到保管庫（API 金鑰、OAuth 憑證等）
+- [ ] 保留預設的所有應用保管庫策略或切換到手動按應用授予
+- [ ] 同步保管庫機密以將其推送到應用程式
+- [ ] 為共用提供者帳戶註冊可重用工作區連線，然後
+      僅在需要時授予 Brain、Analytics、Mail 或 Dispatch 等應用程式
+      該帳戶
+- [ ] 通過資源頁面新增工作區範圍的 skills、護欄說明和品牌/公司參考資源。請參閱 [Workspace](/docs/workspace#global-resources) 了解完整的資源模型表和推薦的入門包。
+- [ ] 設定審批策略和審批人電子郵件
+- [ ] 設定 SendGrid（`SENDGRID_API_KEY`、`SENDGRID_FROM_EMAIL`）以獲取管理員通知
+- [ ] 連線 Slack 或 Telegram 以進行工作區訊息傳遞
+- [ ] 設定共用 MCP 伺服器 — 在 Dispatch 中新增 `mcp-servers/<name>.json` 工作區資源以用於所有應用程式或選定應用程式授權；使用 `mcp.config.json` 或 [MCP hub mode](/docs/mcp-clients#hub) 進行較低級別的部署