# 角色資源存取權限

### 功能簡介 <a href="#feature-intro" id="feature-intro"></a>

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

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

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

***

### 權限層級說明 <a href="#permission-levels" id="permission-levels"></a>

#### 兩層權限控制 <a href="#two-layer-permission-control" id="two-layer-permission-control"></a>

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>

#### 權限組合情境 <a href="#permission-combination-scenarios" id="permission-combination-scenarios"></a>

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

***

### 設定存取權限 <a href="#configure-access-permission" id="configure-access-permission"></a>

#### 前置條件 <a href="#prerequisites" id="prerequisites"></a>

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

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

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="/files/AmCFyqae5N71mf4rOdUw" 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="/files/WNn9q7a5oNboJXHVOg43" alt="編輯角色權限"><figcaption><p>編輯角色的功能權限設定</p></figcaption></figure>

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

***

### 使用情境範例 <a href="#use-case-examples" id="use-case-examples"></a>

#### 情境一：保密專案管理 <a href="#use-case-confidential-project" id="use-case-confidential-project"></a>

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

**設定方式**：

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

#### 情境二：API 整合使用 <a href="#use-case-api-integration" id="use-case-api-integration"></a>

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

**設定方式**：

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

#### 情境三：階層式資料存取 <a href="#use-case-hierarchical-access" id="use-case-hierarchical-access"></a>

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

**設定方式**：

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

***

### 與現有權限的關係 <a href="#relation-to-existing-permissions" id="relation-to-existing-permissions"></a>

#### 權限計算邏輯 <a href="#permission-calculation-logic" id="permission-calculation-logic"></a>

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

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

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

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

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

#### 與擁有者角色的差異 <a href="#difference-from-owner-role" id="difference-from-owner-role"></a>

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

***

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

#### Q：為什麼要分離「使用權限」和「存取權限」？ <a href="#faq-separate-use-and-access" id="faq-separate-use-and-access"></a>

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

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

#### Q：如果成員透過多個角色擁有同一資源，存取權限如何計算？ <a href="#faq-multiple-roles-same-resource" id="faq-multiple-roles-same-resource"></a>

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

#### Q：變更存取權限後多久生效？ <a href="#faq-when-does-change-take-effect" id="faq-when-does-change-take-effect"></a>

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

#### Q：取消可見性後，成員透過 API 還能使用該資源嗎？ <a href="#faq-api-access-after-visibility-revoked" id="faq-api-access-after-visibility-revoked"></a>

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

#### Q：如何快速批次設定多個資源的可見性？ <a href="#faq-batch-set-visibility" id="faq-batch-set-visibility"></a>

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

***

### 更多使用場景 <a href="#more-use-cases" id="more-use-cases"></a>

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

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

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

***

### 注意事項 <a href="#notes" id="notes"></a>

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

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

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

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

* [角色權限管理](/org/role-permission.md)
* [組織與成員管理](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 %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/org/group-resource-access.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.