> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/org/roles/role-batch-permissions.md).

# 批次設定角色權限

把同一份權限設定一次套用到多個自訂角色，套用前逐一預覽每個角色會新增、收回哪些項目，也可以同時建立新角色。

組織裡有十幾個部門角色時，要替每個角色加上同一個新 Agent、或收掉同一項功能，過去得一個一個進角色編輯頁修改。<mark style="color:blue;">批次設定權限</mark> 讓您先編好一份權限設定，再勾選要套用的角色一次寫入；按下套用前，每個角色會列出套用後「新增幾項、收回幾項」，展開還能看到明細。

## 使用前須知 <a href="#before-you-start" id="before-you-start"></a>

* **誰可以使用**：需有組織概覽權限，也就是能進入 <mark style="color:blue;">編輯角色權限</mark> 頁的管理者。
* **整份覆蓋**：勾選的角色，所有分頁的設定都會變成與這份設定完全一致。角色原本有、這份設定沒有的權限與資源分配會被收回，不是只「加上去」。
* **可以套用的角色**：只有自訂角色。擁有者與預設角色不在套用清單內，不會被覆蓋。
* **一次最多 50 個角色**：已勾選的既有角色加上新增的角色，合計最多 50 個。
* **全部成功才寫入**：任一個角色寫入失敗，整批都不會變動。
* **涵蓋的分頁**：<mark style="color:blue;">角色權限</mark>、<mark style="color:blue;">分配 MaiGPT 使用權限</mark>，以及 <mark style="color:blue;">分配 AI 助理</mark>、<mark style="color:blue;">分配團隊</mark>、<mark style="color:blue;">分配知識庫</mark>、<mark style="color:blue;">分配資料庫</mark>、<mark style="color:blue;">分配工具</mark>、<mark style="color:blue;">分配 Agent UI 工具</mark>、<mark style="color:blue;">分配技能</mark>、<mark style="color:blue;">分配對話平台</mark> 八個資源分頁。角色的成員與 Credit 額度不受影響。
* **官方內建 Agent 不受影響**：鎖定的官方內建 Agent 及其對話平台不會被批次設定改動。

## 使用情境 <a href="#scenario" id="scenario"></a>

人資部上線了「內部規章問答」Agent，組織管理員要讓全公司 12 個部門角色都能使用；這些部門角色當初都照同一份公版設定。她在角色列表點 <mark style="color:blue;">批次設定權限</mark>，選 <mark style="color:blue;">取用現有角色權限</mark> 並以「業務部」當起點，在 <mark style="color:blue;">分配 AI 助理</mark> 分頁加入這個 Agent，它的對話平台也跟著帶進來。到了 <mark style="color:blue;">套用到哪些角色</mark>，她勾選 12 個部門角色，大部分角色只有新增、收回是「−0」，只有「客服部」顯示「−2 收回」；展開一看，是客服部後來多分配了兩個公版沒有的知識庫，整份覆蓋會把它們收回。她取消勾選客服部，另外到客服部的角色編輯頁單獨加上這個 Agent，其餘 11 個角色一次套用完成。

## 操作步驟 <a href="#steps" id="steps"></a>

{% stepper %}
{% step %}

### 1. 開啟批次設定權限 <a href="#open-batch-permissions" id="open-batch-permissions"></a>

前往 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">組織概覽</mark>，在 <mark style="color:blue;">管理操作</mark> 區點選 <mark style="color:blue;">編輯角色權限</mark>，再點角色列表右上方的 <mark style="color:blue;">批次設定權限</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-288b2e260222c37bc1837a1447ef6314b72898bc%2Frole-batch-permissions-entry.png?alt=media" alt="角色列表右上方的批次設定權限按鈕"><figcaption><p>角色列表右上方的批次設定權限入口</p></figcaption></figure>

頁面上方的步驟列依序是 <mark style="color:blue;">設定方式</mark>、<mark style="color:blue;">設定權限</mark>、<mark style="color:blue;">套用到哪些角色</mark>。
{% endstep %}

{% step %}

### 2. 選擇設定方式 <a href="#choose-method" id="choose-method"></a>

| 設定方式                                      | 說明                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| <mark style="color:blue;">新權限規則</mark>    | 從空白開始，所有分頁都沒有任何設定；<mark style="color:blue;">角色權限</mark> 至少要勾一項功能權限才能進入下一步 |
| <mark style="color:blue;">取用現有角色權限</mark> | 從下方表格選一個角色，取用它目前所有分頁的設定當起點；不會改到該角色本身                                      |

取用時，表格列出組織所有角色（含擁有者與預設角色），可用角色名稱或 ID 搜尋。選定後下方會顯示「已取用 … 的設定當起點」，點 <mark style="color:blue;">下一步</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-23daa1cb3a8bf431c0b5dce79913154ddb069a79%2Frole-batch-permissions-copy-source.png?alt=media" alt="設定方式選取用現有角色權限，表格列出組織角色，選定後下方顯示已取用的角色"><figcaption><p>取用現有角色權限：選一個角色當起點</p></figcaption></figure>

{% hint style="warning" %}
以擁有者角色當起點，會帶入所有功能權限與組織目前所有可分配的資源。套用前請確認目標角色真的需要這麼大的權限。
{% endhint %}
{% endstep %}

{% step %}

### 3. 設定權限 <a href="#edit-settings" id="edit-settings"></a>

這一步的分頁與操作和角色編輯頁相同，詳細說明見 [角色權限管理](https://docs.maiagent.ai/org/roles/role-permission.md#edit-role-permissions)。差別在於這裡改的是一份草稿，要到 <mark style="color:blue;">套用到哪些角色</mark> 這一步按下套用才會寫入。

* 若是取用現有角色，改動過的項目會標上 <mark style="color:blue;">與起點相比：新增</mark> 或 <mark style="color:blue;">與起點相比：收回</mark>（資源表格內顯示為 <mark style="color:blue;">新增</mark>／<mark style="color:blue;">收回</mark>），表示與起點角色相比的差異。
* 在 <mark style="color:blue;">分配 AI 助理</mark> 加入 Agent 時，會一併帶入該 Agent 的對話平台，與角色編輯頁的行為相同。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2461cabd095cf788caf18881d12508e9e1d9963d%2Frole-batch-permissions-compared-mark.png?alt=media" alt="第二步的十個分頁，勾選權限後右側標示與起點相比：新增"><figcaption><p>改動過的項目標示與起點相比的差異</p></figcaption></figure>

設定完成後點 <mark style="color:blue;">下一步</mark>。
{% endstep %}

{% step %}

### 4. 選擇要套用的角色並預覽差異 <a href="#choose-targets" id="choose-targets"></a>

表格列出所有自訂角色，可用角色名稱搜尋，勾選要套用的角色。<mark style="color:blue;">套用後的差異</mark> 欄顯示每個角色套用後的變化：

| 顯示          | 意思                          |
| ----------- | --------------------------- |
| ＋N 新增、−N 收回 | 這個角色套用後會多出、失去的項目數           |
| 與這份設定相同     | 這個角色目前的設定已經和這份設定一致，套用後不會有變化 |
| 起點角色 · …    | 在設定方式取用的起點角色本身              |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0d36978c5ebaa05da1015252ee6ffac6741e8417%2Frole-batch-permissions-targets.png?alt=media" alt="第三步勾選角色後，每列顯示新增與收回的項目數，底部提示整份覆蓋"><figcaption><p>勾選的角色會列出套用後新增與收回的項目數，可展開看明細</p></figcaption></figure>

點一列的 <mark style="color:blue;">展開</mark> 可以看明細：

* <mark style="color:blue;">會新增 N 項</mark>、<mark style="color:blue;">會收回 N 項</mark>，依分頁列出每一項；對話平台會標出頻道類型，方便分辨同一個 Agent 的不同平台。
* 有收回項目時，會提示這個角色有幾位成員：他們若沒有其他角色提供被收回的項目，套用後就會失去。
* 某一區功能的入口會因這次套用開啟或關閉時，會另外提示「這一區的入口也會開啟／關閉（不另計筆數）」。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-fe67acb259067ea21aa9a310597d136cd2c8c142%2Frole-batch-permissions-expand.png?alt=media" alt="展開角色後，依分頁列出會新增與會收回的項目"><figcaption><p>展開明細依分頁列出會新增與會收回的項目</p></figcaption></figure>

**同時新增角色**：點表格上方的 <mark style="color:blue;">新增角色</mark>，表格會多出一列標著 <mark style="color:blue;">新角色</mark> 的空白列，輸入角色名稱即可。新角色會在套用時建立，權限就是這份設定。名稱不能空白，也不能與既有角色或同批其他新角色重名；與既有角色重名時，可以改名，或直接勾選那個既有角色。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5ce52e32b86c147956f8c1cfa57dd8ab1408413f%2Frole-batch-permissions-new-role.png?alt=media" alt="表格最上方多出一列新角色，輸入名稱後會在套用時建立"><figcaption><p>新增角色時，表格會多出一列新角色</p></figcaption></figure>
{% endstep %}

{% step %}

### 5. 套用 <a href="#apply" id="apply"></a>

確認底部的提醒「整份覆蓋」後，點 <mark style="color:blue;">套用到 N 個角色</mark>。成功後會顯示「已套用到 N 個角色」並回到角色列表。

* 套用期間無法修改勾選、回上一步或離開頁面，以免變更只套用一半。
* 若在您檢視差異之後，有人修改了其中某個角色，畫面會顯示「角色在你檢視差異之後被修改，已重新計算」並更新預覽，請重新確認差異後再套用。
  {% endstep %}
  {% endstepper %}

{% hint style="warning" %}
套用後的變更不會自動還原。要改回，請再做一次批次設定，或到各角色的編輯頁逐一調整。尚未套用前離開頁面，畫面會提醒「尚未套用的設定會遺失」。
{% endhint %}

## 套用後怎麼確認 <a href="#verify" id="verify"></a>

想確認某位成員在套用後實際擁有哪些權限、每一項來自哪個角色，請到成員列表點該成員的 <mark style="color:blue;">檢視有效權限</mark>，說明見 [成員管理：檢視成員的有效權限](https://docs.maiagent.ai/org/overview/member.md#effective-permissions)。

## 常見問題 <a href="#faq" id="faq"></a>

### Q：為什麼套用清單裡沒有擁有者和預設角色？ <a href="#faq-owner-default-not-listed" id="faq-owner-default-not-listed"></a>

擁有者角色固定擁有所有權限，預設角色會自動套用到所有成員，兩者都不適合整份覆蓋，所以不在套用清單內。它們仍可以在 <mark style="color:blue;">設定方式</mark> 被取用當作起點。要調整預設角色，請到它的角色編輯頁修改。

### Q：和「複製角色」有什麼不同？ <a href="#faq-vs-duplicate-role" id="faq-vs-duplicate-role"></a>

[複製角色](https://docs.maiagent.ai/org/roles/role-permission.md#duplicate-role) 會建立一個新角色，帶上來源角色的權限與資源分配，不帶成員。批次設定權限同樣不帶成員，但可以一次套用到多個既有角色。

### Q：一次要改超過 50 個角色怎麼辦？ <a href="#faq-over-limit" id="faq-over-limit"></a>

超過時，底部會顯示「一次最多套用到 50 個角色」，套用按鈕無法點選。請分成多批套用；每一批可以從同一個起點角色取用相同設定。清單超過 50 個時，先用角色名稱關鍵字縮小範圍，再用表頭勾選框全選；換關鍵字時先前勾選的角色會保留。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/org/roles/role-batch-permissions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
