智能体权限

智能体可以做什么、由谁决定，以及运行智能体的人提供了什么。

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

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

Agent 是執行操作的主體

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

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

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

Beeuni 權限 — 由資訊清單決定

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

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。請參閱資訊清單參考。

權限上限 — 由管理員決定

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

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

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

`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 在自己的專案中永遠持有此權限。

執行 Agent 會授予其權限

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

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

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

個人資源仍屬個人

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

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

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

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

Apps

只有當 Agent 的 apps: 授權列出 App 的 slug，或為 all，且其有效權限包含 project.app.read 時，Agent 才能開啟受限或私人App。

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 功能旗標時，才會顯示 Apps 頁面。

後端

專案可以擁有託管的專案後端。兩項權限用於管理這些後端。其規則與 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。

變更 Agent 和觸發條件

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

合併變更請求需要 project.gitops.merge。
會變更 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 無法擴大自己的權限。
Agent 只能授予自己持有的權限。當 Agent 編輯任何 Agent 的授權時（透過 Agent 編輯器、範圍和密鑰授權路由，或它所合併的變更請求），新增的每項權限、連接器、密鑰和 App 都必須包含在執行寫入的 Agent 自己的有效授權中。授予 all 需要具備每一項。縮小或移除授權一律允許。拒絕時會以 code: "agent_grant_escalation" 回應 403。
直接推送至預設分支會略過變更請求。Agent 工作階段需要 project.gitops.ref.any 和第 2 點中的每項權限。由於推送的資訊清單在合併前無法檢查，因此 Agent 還必須持有授予的所有項目（all 權限、連接器、密鑰和 Apps）。否則會開啟變更請求。
拒絕時會回應 403，並附上 code: "agent_scope_insufficient"（Agent）或 "project_role_insufficient"（使用者）以及缺少的 action。如果無法讀取資訊清單，合併會以 code: "CR_GOVERNANCE_UNVERIFIED" 和 Retry-After 回應 503。請重試。
權限上限是僅限管理員使用的 IAM 狀態。資訊清單絕不會超出此上限。

解讀拒絕訊息

每個授權檢查產生的 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`	變更其專案角色

稽核

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

在控制面板中查看

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

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

適用範圍

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