> 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-design-guide.md).

# 角色權限規劃指南

當同仁會自建 AI 助理、而分享需要受控時，用「個人 → 部門 → 全公司」三個上架層級來規劃角色。

[角色權限管理](/org/roles/role-permission.md) 說明角色有哪些設定，[角色資源存取權限](/org/roles/group-resource-access.md) 說明每筆資源的存取開關。本頁往上一層：**當組織裡同時有「會建助理的人」與「只用助理的人」，角色該怎麼切，分享才受控。**

{% hint style="info" %}
**簡單理解：**

把公司想成一棟大樓。每位建構者有自己的工作室（個人角色），做好的東西不會自動放到部門走廊（部門角色）或大廳（全公司角色）。要放出去，得填單、由總務（擁有者）搬過去，而且搬出去的是**影本**，原稿留在工作室。
{% endhint %}

這套規劃適合的情況：

* 同仁會自己建 AI 助理，但建好的東西不該一開始就讓別人看到
* 助理要經過內部申請，才上架給部門或全公司使用
* 上架後要鎖定，不能被建立者隨手改掉正式版

全部靠平台既有的角色機制做到，不需要客製程式。

***

## 平台怎麼判定「誰看得到」 <a href="#how-visibility-works" id="how-visibility-works"></a>

平台判定「這位成員看不看得到這支助理」只有一條規則：

> **助理綁定的角色，與成員隸屬的角色有交集，才看得到。**

平台**不看建立者是誰**。很多人以為「我建的助理只有我看得到」，這在平台上不成立：助理綁到哪些角色，那些角色的成員就看得到。

{% hint style="info" %}
**簡單理解：**

助理沒有「主人」，只有「放在哪個房間」。你在哪幾個房間有鑰匙，就看得到那幾個房間裡的助理。要讓一支助理只有你看得到，唯一的方法是它放在一個只有你有鑰匙的房間，也就是**一人一個角色**。
{% endhint %}

由此延伸出三個會決定設計走向的事實：

<table><thead><tr><th width="230">事實</th><th>對規劃的影響</th></tr></thead><tbody><tr><td><strong>建構者可以把助理綁到自己隸屬的任何角色</strong></td><td>系統只要求「所選角色裡至少一個有 AI 助理權限」，其餘只要是他隸屬的角色就能綁。建構者若同時在部門角色裡，他就能自己把助理分享給部門，不需要任何人核准。</td></tr><tr><td><strong>預設角色是全體成員自動隸屬的</strong></td><td>任何資源綁到預設角色，等於對全公司公開；建構者建助理時也選得到它。</td></tr><tr><td><strong>複製助理會連角色綁定一起複製</strong></td><td>看得到就能複製，複製出來的那一份會帶著原版的全部綁定，出現在原本所有觀眾面前。</td></tr></tbody></table>

***

## 三種角色，三個上架層級 <a href="#three-tiers" id="three-tiers"></a>

把「個人 → 部門 → 全公司」切成三個上架層級，各用一種角色承接。助理每往上一層都要申請一次。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-80e5dc0875d39d08efd2c146e3107ff99d174f5c%2Frole-design-three-tiers.png?alt=media" alt="三個上架層級：個人、部門、全公司"><figcaption><p>角色名稱的前半是能力，後半是範圍。助理從左往右走，每往右一格都要申請一次</p></figcaption></figure>

### 角色一覽 <a href="#role-list" id="role-list"></a>

<table><thead><tr><th width="190">角色</th><th width="190">誰</th><th>能做什麼、綁什麼</th></tr></thead><tbody><tr><td><strong>建構者-部門-姓名</strong></td><td>每位建構者一個（一人一角色）</td><td>看得到 AI 助理、知識庫、Agent 市集、MaiGPT；能建助理與知識庫。綁自己建的助理，讀取／編輯／刪除。</td></tr><tr><td><strong>開發者</strong></td><td>技術種子，附加在個人角色上</td><td>再加工具、技能、資料庫、爬蟲；能建資料庫。不綁任何資源。</td></tr><tr><td><strong>使用者-範圍</strong></td><td>該範圍的同仁，<strong>不含建構者</strong></td><td>只看得到 Agent 市集，不能建。綁核准上架的助理，唯讀。</td></tr><tr><td><strong>一般員工</strong></td><td>所有非建構者同仁</td><td>看得到 Agent 市集與 MaiGPT，不能建。綁全公司共通助理，唯讀。</td></tr><tr><td><strong>擁有者</strong></td><td>平台管理員</td><td>全部。負責執行上架與維護。</td></tr></tbody></table>

{% hint style="info" %}
**命名與範圍**

* 角色名稱的前半是能力（建構者／使用者），後半是範圍（部門、事業群、專案都可以）
* 「使用者-範圍」不用預建，第一次有助理核准上架到那個範圍時再建
* 「一般員工」是底層，「使用者-範圍」疊在上面：部門同仁兩個角色都掛，權限取聯集
  {% endhint %}

{% hint style="warning" %}
個人角色**不給「客服對話 → 對話平台」權限**，並關閉「允許新增對話平台」與「允許新增資料庫」。建構者測試走助理頁的測試視窗與 Agent 市集即可；拿掉後就取不到對外網址與嵌入碼，助理不會在未經核准的情況下被分享到組織外。
{% endhint %}

***

## 唯一一條鐵律 <a href="#iron-rule" id="iron-rule"></a>

> **建構者不隸屬任何「使用者-範圍」或「一般員工」角色。**

建構者建助理時，「權限設定」列出的是他隸屬的全部角色。他不在部門角色裡，清單上就沒有部門這個選項，想分享也選不到。「不能自行分享」是機制擋住的，不是靠規定。

反過來說，只要建構者在部門角色裡，他就能自己把助理勾給部門，不需要任何人核准。平台沒有「隸屬但不能綁」的設定，要做到申請制，只能靠隸屬關係。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ef0556adf247f88c87f255c6139f79f01dff16b1%2Frole-design-create-permission.png?alt=media" alt="建立 AI 助理的權限設定"><figcaption><p>建助理時的「權限設定」：三個快速選擇之外，「自訂選擇角色」列出的就是他隸屬的全部角色</p></figcaption></figure>

{% hint style="info" %}
**簡單理解：**

建構者手上只有自己工作室的鑰匙。他想把東西放到部門走廊，得請總務來搬，因為他根本進不了走廊。
{% endhint %}

{% hint style="warning" %}
**代價與補法**

建構者因此在 Agent 市集看不到部門與全公司的正式助理。若希望建構者也能使用正式助理，由擁有者在上架時一併把正式助理**唯讀**綁到建構者的個人角色。

但要知道另一個代價：建構者看得到就能複製，複製品會帶著原版的全部綁定。要不要讓建構者看到公版，是導入時要決定的事。
{% endhint %}

***

## 上架流程：兩級上架，複製後鎖定 <a href="#publish-flow" id="publish-flow"></a>

申請與核准在平台外進行（表單或信件），平台上只有擁有者做綁定。上架的動作只有一個：**複製一份，鎖起來。**

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-204129ff54ab4e8a59597760db457a29c9783293%2Frole-design-publish-flow.png?alt=media" alt="兩級上架流程"><figcaption><p>原版留在建構者的個人角色，上架版只綁範圍角色</p></figcaption></figure>

### 1. 建構者建好 <a href="#step-build" id="step-build"></a>

助理落在自己的個人角色，只有自己看得到，可以隨時修改。測試走助理頁的測試視窗與 Agent 市集。

### 2. 部門級：複製一份，綁「使用者-範圍」 <a href="#step-department" id="step-department"></a>

申請核准後，擁有者在 AI 助理列表找到原版，點<mark style="color:blue;">複製</mark>，命名為「部門版-」開頭。

1. 開複製品的<mark style="color:blue;">權限設定</mark>，點<mark style="color:blue;">自訂選擇角色</mark>，移除建構者的個人角色、加上「使用者-範圍」，**存檔**
2. 到<mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">角色權限管理</mark> → 該角色 → <mark style="color:blue;">分配 AI 助理</mark>，把這支助理的編輯與刪除取消，只留讀取

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-35a58fc73f8a7799cbbf9f69149587f18c42bdc1%2Frole-design-assign-chatbots.png?alt=media" alt="角色的分配 AI 助理分頁"><figcaption><p>唯讀要在這裡設：角色 → 分配 AI 助理，每支助理各有讀取、編輯、刪除三個勾</p></figcaption></figure>

### 3. 全公司級：再複製一份，綁「一般員工」 <a href="#step-company" id="step-company"></a>

同樣的動作再做一次，命名為「公版-」開頭，角色改成「一般員工」，到角色頁設唯讀。

**為什麼上架一定是複製一份**：原版留在建構者手上，隨時可改可測；上架版只綁範圍角色，建構者碰不到，「上架後鎖定編輯」自然成立。改版就是再申請、再複製一次，正式版永遠是核准過的。

{% hint style="danger" %}
**兩個一定要做對的動作**

1. 複製會把原版的角色綁定一起帶過來，複製後必須改成只剩目標角色
2. 助理的<mark style="color:blue;">權限設定</mark>沒有讀取／編輯／刪除的勾選，從助理端加上的角色預設**可改可刪**。設唯讀要到角色頁的<mark style="color:blue;">分配 AI 助理</mark>取消編輯與刪除。綁角色一律先在助理的權限設定存檔再到角色頁調整；只在角色頁加的助理不會同步 Web Chat 收件匣，Agent 市集不會出現
   {% endhint %}

***

## 全公司層怎麼給 <a href="#company-tier" id="company-tier"></a>

這是導入時唯一要拍板的結構決定。兩條路都做得到，代價不同。

### 做法 A：保留預設角色當全公司層 <a href="#company-tier-default-role" id="company-tier-default-role"></a>

新員工登入即自動隸屬預設角色，名單不用維護。把預設角色的權限收斂到只剩 Agent 市集與 MaiGPT，公版助理唯讀綁到它。

* **代價**：建構者建助理時選得到預設角色，快速選擇「全部角色」會一併選入，等於一鍵公開給全公司。要靠教育訓練引導建構者用「自訂選擇角色」
* **適合**：組織裡沒有建構者、助理全由管理員建立的情況。有建構者時，鐵律守不住

### 做法 B：移除預設角色，改用自訂的「一般員工」 <a href="#company-tier-custom-role" id="company-tier-custom-role"></a>

沒有任何一鍵公開的路徑，鐵律成立。

* **代價**：新員工（含 SSO 登入）進組織後沒有角色，什麼都看不到，要由管理員指派「一般員工」，名單同步要列入 IT 例行作業
* **怎麼指派**：[Email 邀請或批次匯入](/org/member.md)（既有帳號只掛角色，不會重建）、組織邀請連結帶角色（只對用連結**新註冊**的帳號有效）、成員列表 → 編輯角色（既有帳號用這條）

{% hint style="warning" %}
移除預設角色需由 MaiAgent 協助處理。移除前必須先建好「一般員工」並指派全員、確認 MaiGPT 打得開，否則移除當下全公司立即失去 MaiGPT 與 Agent 市集；移除後不會自動重建。
{% endhint %}

***

## 六個常見誤區 <a href="#common-pitfalls" id="common-pitfalls"></a>

<table><thead><tr><th width="220">以為</th><th>實際上</th></tr></thead><tbody><tr><td>在助理的權限設定就能設唯讀</td><td>助理的權限設定沒有讀寫刪勾選，從助理端加的角色預設可改可刪。要到角色頁「分配 AI 助理」取消編輯與刪除。</td></tr><tr><td>在角色頁「分配 AI 助理」加助理就好</td><td>不會同步 Web Chat 收件匣，Agent 市集不會出現。先在助理的權限設定存檔，再到角色頁調旗標。</td></tr><tr><td>建助理時直接存檔就只綁自己</td><td>權限設定的快速選擇預設是「排除預設角色」，會把非預設角色全部勾進去。要點「自訂選擇角色」再挑；擁有者不點，助理會綁到全部角色。</td></tr><tr><td>複製同仁的角色來補人最快</td><td>複製角色會複製成員與綁定，但讀取／編輯／刪除旗標重設為全開，公版會變成可改可刪。一律從空的範本角色複製。</td></tr><tr><td>用邀請連結給既有帳號掛角色</td><td>連結帶的角色只在註冊當下掛上，已登入過的帳號無效。既有帳號用成員列表編輯角色或批次匯入。</td></tr><tr><td>用擁有者帳號驗證就夠了</td><td>擁有者建助理可以不掛角色，建構者會被系統擋下。任何驗證一律用非擁有者帳號登入。</td></tr></tbody></table>


---

# 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 dynamically by asking a question.

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

```
GET https://docs.maiagent.ai/org/roles/role-design-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.