# 角色資源存取權限

### 功能簡介

角色資源存取權限是 MaiAgent 進階權限管理功能，讓組織管理員能夠精細控制角色成員對 AI 助理、知識庫、對話平台等資源的「可見性」與「使用權限」。透過這項功能，您可以實現更細緻的權限控管，確保敏感資源只對特定角色可見。

{% hint style="info" %}
此功能基於 RBAC（角色基礎存取控制）概念，提供兩層權限控制：

* **使用權限**：能否使用該資源
* **存取權限**：能否在資源列表中看見該資源
  {% endhint %}

***

### 權限層級說明

#### 兩層權限控制

MaiAgent 的資源權限分為兩個層級：

<table><thead><tr><th width="180">權限類型</th><th width="200">說明</th><th>影響範圍</th></tr></thead><tbody><tr><td><strong>使用權限</strong></td><td>決定是否能使用資源</td><td>執行操作、發送訊息、修改設定</td></tr><tr><td><strong>存取權限（可見性）</strong></td><td>決定是否能在列表中看見資源</td><td>資源選單、下拉列表、搜尋結果</td></tr></tbody></table>

#### 權限組合情境

| 使用權限 | 存取權限 | 結果說明                     |
| ---- | ---- | ------------------------ |
| ✅ 有  | ✅ 有  | 可以看見並使用資源（最高權限）          |
| ✅ 有  | ❌ 無  | 可以使用但看不見資源（適用於 API 整合場景） |
| ❌ 無  | ✅ 有  | 可以看見但無法使用（唯讀權限）          |
| ❌ 無  | ❌ 無  | 完全無法存取（預設狀態）             |

***

### 設定存取權限

#### 前置條件

1. 您必須是組織擁有者或具有角色權限管理權限的成員
2. 已建立角色並分配相關資源（AI 助理、知識庫或對話平台）

#### 操作步驟

1. **進入角色管理頁面**
   * 點選左側選單「<mark style="color:blue;">組織設定</mark>」
   * 點選「<mark style="color:blue;">角色權限管理</mark>」
   * 選擇要編輯的角色
2. **選擇資源類型頁籤**
   * 點選「<mark style="color:blue;">分配 AI 助理</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-a0090948ba2b5d674abdb6f81b3fe6f28aaa3b6a%2Forg-role-assign-chatbots.png?alt=media" alt="分配 AI 助理頁籤"><figcaption><p>在角色設定中分配 AI 助理、知識庫等資源</p></figcaption></figure>

3. **編輯存取權限**
   * 在已分配的資源列表中，找到要編輯的資源
   * 點選該資源右側的「<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-11fe71d77a08c35aa521ce205d12adc88a0e2032%2Forg-role-edit-permissions.png?alt=media" alt="編輯角色權限"><figcaption><p>編輯角色的功能權限設定</p></figcaption></figure>

{% hint style="warning" %}
變更存取權限後，受影響的成員需要重新登入或重新整理頁面才會看到變更。
{% endhint %}

***

### 使用情境範例

#### 情境一：保密專案管理

**需求**：研發部門有一個機密專案的 AI 助理，只希望專案成員看見

**設定方式**：

* 創建「研發專案組」角色
* 分配機密 AI 助理給此角色
* ✅ 開啟「可見性」權限
* 其他角色即使有 AI 助理使用權限，也看不到此機密助理

#### 情境二：API 整合使用

**需求**：某個 AI 助理僅供外部系統透過 API 呼叫，不希望內部員工在介面上看見

**設定方式**：

* 為 API 整合角色分配該 AI 助理
* ✅ 給予使用權限（讓 API 可以呼叫）
* ❌ 關閉「可見性」權限（不顯示在介面列表中）

#### 情境三：階層式資料存取

**需求**：讓基層員工只看見公開知識庫，主管可以看見所有知識庫

**設定方式**：

* 「一般員工」角色：只分配公開知識庫，並開啟可見性
* 「主管」角色：分配所有知識庫，全部開啟可見性
* 「財務專員」角色：分配財務知識庫，開啟可見性

***

### 與現有權限的關係

#### 權限計算邏輯

成員的最終資源存取權限 = **角色權限** + **資源分配** + **存取權限設定**

```
範例：成員小王同時擁有兩個角色

角色 A：
- AI 功能權限：✅
- 分配 AI 助理 X：✅ 使用權限、✅ 可見性

角色 B：
- AI 功能權限：✅
- 分配 AI 助理 Y：✅ 使用權限、❌ 可見性

→ 小王的實際權限：
- 可以看見並使用 AI 助理 X
- 可以使用 AI 助理 Y（透過 API 或直接連結），但在介面列表中看不到
```

#### 與擁有者角色的差異

{% hint style="info" %}
**擁有者角色**自動擁有所有資源的完整存取權限（包含使用權限與可見性），無需手動設定。
{% endhint %}

***

### 常見問題

#### Q：為什麼要分離「使用權限」和「存取權限」？

**A**：這種設計提供更靈活的權限控管：

* **簡化介面**：避免成員看到過多不相關的資源，提升使用體驗
* **資料安全**：敏感資源可以完全隱藏，降低資訊洩漏風險
* **API 整合**：支援系統間整合，無需在使用者介面顯示技術性資源

#### Q：如果成員透過多個角色擁有同一資源，存取權限如何計算？

**A**：採用「聯集」原則，只要任一角色開啟可見性，該成員就能看見該資源。

#### Q：變更存取權限後多久生效？

**A**：立即生效，但受影響的成員需要重新整理頁面或重新登入才能看到變更。

#### Q：取消可見性後，成員透過 API 還能使用該資源嗎？

**A**：可以。只要成員擁有該資源的使用權限，就能透過 API 或直接連結使用，即使在介面上看不見。

#### Q：如何快速批次設定多個資源的可見性？

**A**：目前需要逐一編輯。建議在分配資源時就規劃好可見性策略，避免後續大量調整。

***

### 更多使用場景

除了上述情境，資源可見性控制在以下場景也特別實用：

* **多部門協作**：行銷部門只需看到行銷相關的 AI 助理和知識庫，客服部門只需看到客服相關資源，避免成員被無關資源干擾
* **專案分組**：為不同專案團隊設定獨立的資源可見範圍，避免專案間的資源混淆
* **權限測試**：在測試新功能時，可以先隱藏測試用的資源，不讓一般成員看到
* **新手引導**：為新進成員設定較少的可見資源，降低學習曲線
* **外包團隊管理**：讓外包人員只看到其負責專案的相關資源，保護其他專案資訊

{% hint style="warning" %}
建議將「可見性」和「使用權限」保持一致，避免成員看到卻無法使用的資源，造成操作困惑。
{% endhint %}

***

### 注意事項

{% hint style="warning" %}
**權限設定建議**

* 預設角色應謹慎設定存取權限，避免所有成員都看見不必要的資源
* 定期檢視資源的可見性設定，確保符合組織安全政策
* 重要或敏感資源建議限制可見性，僅開放給特定角色
  {% endhint %}

{% hint style="info" %}
若資源被刪除或停用，即使仍在可見清單中，成員也無法看到或使用該資源。
{% endhint %}

{% hint style="info" %}
**相關文檔**

* [角色權限管理](https://docs.maiagent.ai/org/role-permission)
* [組織與成員管理](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/zh-tw/org/rbac.md)
* [批次成員與權限管理](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/zh-tw/org/bulk-role-permission.md)
  {% endhint %}