---
title: "智能体权限"
description: "智能体可以做什么、由谁决定，以及运行智能体的人提供了什么。"
---

Agent 會透過 CLI、API、git、連接器和
Apps 操作你的專案。本頁說明 Beeuni 如何決定 Agent 可以做什麼。

**Agent 以自己的身分行動，而不是以啟動它的人的身分行動。** 它的權限是
Beeuni 權限 ∩ 權限上限角色。權限本身決定一切，和使用者的情況相同。沒有人
會把自己的角色借給 Agent，因此無論由誰執行，Agent 的行為都相同。

<a id="the-agent-is-the-acting-principal"></a>

## Agent 是執行操作的主體

每個 Agent 工作階段都有兩種身分：

| 身分 | 決定事項 |
|---|---|
| **執行主體 — Agent** | 所有共用資源：專案權限、共用連接器帳戶、專案密鑰、Apps、git。 |
| **代表 — 使用者** | 僅限該使用者自己的資源，且僅限該使用者自己的私人工作階段。 |

每個 Agent 在每個專案中都有一個身分：由 Beeuni 為它建立的服務帳戶。你永遠不會持有它的憑證。

<a id="beeuni-permissions--the-manifest-decides"></a>

## Beeuni 權限 — 由資訊清單決定

每個 Agent 都會在 `beeuni.yaml` 的 `agents.<name>.beeuni_permissions` 中宣告 Beeuni 權限。預設分支上的資訊清單是
權威來源。

```yaml
agents:
  report-writer:
    beeuni_permissions: [project.file.read, project.connector.read, project.app.read]
    connectors: [reports-dashboard-api]
    secrets: [REPORTS_API_KEY]
    apps: [reports-dashboard]
```

- 預設拒絕清單中未列出的權限。沒有 `beeuni_permissions` 的 Agent 不會取得任何權限。
- `all` 會授予所有專案權限，但仍受權限上限限制。
- `beeuni_cli` 是已棄用的寫法。仍可通過驗證，但會顯示警告。同一個 Agent 同時使用兩個值不同的鍵會導致驗證錯誤。

在 **Customize → Agents → the agent → Beeuni permissions** 編輯清單。儲存會提交 `beeuni.yaml`。請參閱[資訊清單參考](/docs/zh/project/manifest)。

<a id="the-ceiling--an-admin-decides"></a>

## 權限上限 — 由管理員決定

權限上限是管理員綁定至 Agent 服務帳戶的專案角色。Agent 的 Beeuni 權限絕不會超過此上限。

- **未綁定角色：**套用預設 Agent 權限上限。包含除 `project.credentials.issue` 以外的所有專案權限。
- **已綁定角色：**內建的 `member` 或 `manager`，或自訂角色。Agent 只會保留角色同樣授予的 Beeuni 權限。
- 權限上限不會新增權限。`manager` 權限上限不會授予 Agent 未在資訊清單中列出的權限。

在 **Access hub → Projects → the project → Add** 設定權限上限。在 **Agents** 下選取 Agent，然後選擇角色。只有管理角色的管理員會在選擇器中看到 Agent。專案的存取清單會以 **Agent** 標記顯示每個 Agent 的權限上限。

<a id="all-means-every-permission"></a>

## `all` 表示所有權限

`beeuni_permissions: all`、`"*"`，以及任何包含 `"*"` 的清單，都表示所有專案權限。這包含 `project.members.manage`（新增、更改或移除專案成員與授權）和 `project.delete`。

有一項權限僅限使用者使用：`project.credentials.issue`（建立專案權杖或專案範圍的 PAT）。Agent 建立的權杖不會帶有任何 Agent 權限，因此會在權限範圍之外行動。拒絕時會以 `code: "agent_human_only_action"` 回應 `403`。

執行階段會忽略未授予的權限項目，清單中的其他項目仍會生效。`beeuni validate` 和變更請求合併則會將其回報為錯誤。

`project.read` 則相反：Agent 在自己的專案中永遠持有此權限。

<a id="running-an-agent-lends-its-authority"></a>

## 執行 Agent 會授予其權限

執行 Agent 的人不會限制 Agent 的權限。因此，能否執行 Agent 就是授權。Beeuni 會在每個入口點檢查「此人是否可以執行此 Agent」：

| 入口點 | 必要條件 |
|---|---|
| 建立、啟動或提示工作階段；切換其 Agent | 此人可以執行該 Agent |
| 手動觸發觸發條件 | 觸發者可以執行該觸發條件所屬的 Agent |
| 從 Agent 工作階段啟動子工作階段 | 父工作階段背後的使用者可以執行子工作階段的 Agent。若背後沒有使用者，則只能執行同一個 Agent。 |

在 Agent 的 **People** 索引標籤或 Access hub 中授予「可以執行」權限。Agent 預設為關閉：只有指派對象明確指定某位成員或其群組時，該成員才能執行 Agent。

<a id="personal-resources-stay-personal"></a>

## 個人資源仍屬個人

Agent 工作階段只有在以下兩個條件都成立時，才能存取某人擁有的資源：

1. 工作階段代表該人執行。
2. 工作階段是私人工作階段。

個人資源包括成員擁有的連接器連線、個人專案密鑰、個人提供者金鑰，以及該成員自己的電腦。共用工作階段、觸發條件或頻道工作階段，以及無人值守執行都無法存取這些資源。

當其他人提示私人工作階段時（例如可以開啟成員私人工作階段的帳戶管理員），該工作階段便會永久停止代表建立者執行。Agent 仍保留自己的權限。提示工作階段的人絕不會透過他人的帳戶行動。

## Apps

只有當 Agent 的 `apps:` 授權列出 App 的 slug，或為 `all`，且其有效權限包含 `project.app.read` 時，Agent 才能開啟受限或私人[App](/docs/zh/feature-flags/apps)。

| App 存取模式 | Agent 獲准存取的條件 |
|---|---|
| 公開 | 一律允許 |
| 專案 | `project.app.read` 有效 |
| 受限或私人 | `apps:` 中列有該 slug，且 `project.app.read` 有效 |
| 密碼 | 永不允許 |

App 的 **Access** 對話方塊會列出可存取的 Agent，資料讀取自 `agents.<name>.apps`。你可以在 Agent 的 **Apps** 頁面（Customize → Agents → the agent → Apps）透過 `beeuni agents scope <agent> --apps <slug,slug>` 修改清單，或提交變更請求至 `beeuni.yaml`。只有在專案啟用 [Apps](/docs/zh/feature-flags/apps) 功能旗標時，才會顯示 Apps 頁面。

<a id="backends"></a>

## 後端

專案可以擁有託管的專案後端。兩項權限用於管理這些後端。其規則與 Apps 權限相同：持有 `project.app.read` 或 `project.app.write` 的角色，也會持有相應的 Backend 權限。

| 權限 | 允許操作 |
|---|---|
| `project.backend.read` | 列出並檢視專案的 Backends：名稱、狀態和 URL |
| `project.backend.write` | 建立和刪除 Backends，並讀取 Backend 的管理憑證。包含 `project.backend.read` |

管理金鑰可完全控制 Backend 的資料和程式碼，因此讀取它需要 `project.backend.write`。內建的 Manager 角色持有這兩項權限。內建的 Member 角色持有 `project.backend.read`。

<a id="changing-agents-and-triggers"></a>

## 變更 Agent 和觸發條件

`beeuni.yaml` 會影響 Agent 可以做什麼，因此，將變更合併至預設分支的人會影響 Agent。對 Agent 和使用者而言，判定依據相同：

1. 合併變更請求需要 `project.gitops.merge`。
2. 會變更 `beeuni.yaml` 的合併，同時需要該變更直接操作路徑所需的權限：`agents.*` → `project.agent.write`；`triggers` → `project.trigger.create`、`.update` 或 `.delete`；`default_agent` → `project.agent.write`。Manager 角色持有這些權限，而角色編輯器會將它們加入任何取得 `project.gitops.merge` 的角色。Agent 的 `beeuni_permissions` 必須列出這些權限，或設為 `all`。因此，只能合併變更的 Agent 無法擴大自己的權限。
3. Agent 只能授予自己持有的權限。當 Agent 編輯任何 Agent 的授權時（透過 Agent 編輯器、範圍和密鑰授權路由，或它所合併的變更請求），新增的每項權限、連接器、密鑰和 App 都必須包含在執行寫入的 Agent 自己的有效授權中。授予 `all` 需要具備每一項。縮小或移除授權一律允許。拒絕時會以 `code: "agent_grant_escalation"` 回應 `403`。
4. 直接推送至預設分支會略過變更請求。Agent 工作階段需要 `project.gitops.ref.any` 和第 2 點中的每項權限。由於推送的資訊清單在合併前無法檢查，因此 Agent 還必須持有授予的所有項目（`all` 權限、連接器、密鑰和 Apps）。否則會開啟變更請求。
5. 拒絕時會回應 `403`，並附上 `code: "agent_scope_insufficient"`（Agent）或 `"project_role_insufficient"`（使用者）以及缺少的 `action`。如果無法讀取資訊清單，合併會以 `code: "CR_GOVERNANCE_UNVERIFIED"` 和 `Retry-After` 回應 `503`。請重試。
6. 權限上限是僅限管理員使用的 IAM 狀態。資訊清單絕不會超出此上限。

<a id="read-a-denial"></a>

## 解讀拒絕訊息

每個授權檢查產生的 `403` 都會附帶 `code` 和 `action`：

| `code` | 含義 | 修正方式 |
|---|---|---|
| `agent_scope_insufficient` | Agent 的 Beeuni 權限中沒有 `action` | 將其加入 `agents.<name>.beeuni_permissions` |
| `agent_ceiling_insufficient` | `action` 超出 Agent 的權限上限角色 | 由管理員提高權限上限 |
| `agent_not_accessible` | 此人無權執行該 Agent | 將 Agent 授予此人 |
| `agent_grant_escalation` | 寫入操作將某項 Agent 權限授予執行寫入的 Agent 並未持有的內容 | 只授予執行寫入者持有的權限，或由使用者進行變更 |
| `project_role_insufficient` | 此人的角色不允許 `action` | 變更其專案角色 |

<a id="audit"></a>

## 稽核

每個 Agent 操作都會記錄三個欄位：`actor` 是 Agent，`on_behalf_of` 是使用者或 `null`，而 `initiator` 是 `human`、`trigger` 或 `channel`。觸發條件執行不會記錄使用者。

<a id="see-it-in-the-dashboard"></a>

## 在控制面板中查看

開啟 **Customize → Agents → the agent → Beeuni permissions**。**What this agent can do** 面板會顯示：

- 在 `beeuni.yaml` 中宣告的 Beeuni 權限，
- 權限上限角色，或 **Default agent ceiling**，
- 僅限使用者的權限 `project.credentials.issue`，
- 有效權限：「可以執行此 Agent 的使用者會使用這些權限行動。」

<a id="scope"></a>

## 適用範圍

本頁適用於專案在 `beeuni.yaml` 的 `agents:` 下宣告的所有 Agent。沒有 `agents:` 對應表的專案不會宣告受此規則管理的 Agent，因此不需要啟用任何功能。無法切換回舊版啟動器角色模式。