@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/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="Connect once, grant apps, reuse credentials" summary="A Connection holds provider metadata (never secrets) and credentialRefs that point at the vault. Per-app Grants unlock it. Apps read a single Readiness status."
+{
+  "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, status, scopes, config &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="The connection model" 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": "Named provider account. Never stores secret values.",
+      "fields": [
+        { "name": "id", "type": "string", "pk": true, "note": "e.g. acme-slack" },
+        { "name": "provider", "type": "string", "note": "stable provider id, e.g. slack" },
+        { "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": "safe, non-secret config" },
+        { "name": "credentialRefs", "type": "json", "nullable": true, "note": "pointers to vault keys, e.g. { key, scope }" }
+      ]
+    },
+    {
+      "id": "grant",
+      "name": "workspace_connection_grants",
+      "note": "Per-app permission to use a connection.",
+      "fields": [
+        { "name": "connectionId", "type": "string", "fk": "conn.id" },
+        { "name": "appId", "type": "string", "note": "e.g. brain, analytics" }
+      ]
+    }
+  ],
+  "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="Connection store vs. vault" summary="The vault owns the secret value. The connection owns provider metadata plus credentialRefs (pointers). At execution time the app resolves the ref through a granted connection and reads the value from the vault."
+{
+  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection store</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, scopes, config</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\">App 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\">never returned to the agent or 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/docs/content/locales/zh-CN/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="Two governance planes" summary="Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."
+{
+  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git / GitHub</span><strong>Code governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR review</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="Governance config in the repo"
+{
+  "entries": [
+    { "path": ".github/CODEOWNERS", "note": "Auto-assigns reviewers per changed path" },
+    { "path": ".github/labeler.yml", "note": "Auto-labels PRs by app" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace-level — broad review" },
+    { "path": "package.json", "note": "Workspace-level — platform team owns" }
+  ]
+}
+```
+
+GitHub 的 CODEOWNERS 文件会根据更改的文件自动将审阅者分配给 PR。在存储库根目录创建 `.github/CODEOWNERS`：
+
+```
+# Framework core — affects every app; platform team reviews all changes
+packages/core/                     @your-org/platform-team
+
+# Dispatch control plane — secrets, integrations, workspace resources
+templates/dispatch/                @your-org/platform-team
+
+# Per-app ownership — each team reviews their own app
+templates/mail/                    @your-org/mail-team
+templates/analytics/               @your-org/analytics-team
+templates/calendar/                @your-org/calendar-team
+# ... add an entry per app
+
+# Workspace-level config — broad review since it affects everyone
+.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) 进行较低级别的部署