> 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/overview/member.md).

# 成員管理

成員管理：成員與角色的關係、Email 邀請（已有帳號直接加入）、組織邀請連結、成員列表操作、修改成員名稱、刪除成員與分配角色，以及批次新增成員、角色成員與成員 Metadata 的進階操作。

## 什麼是成員？ <a href="#what-is-member" id="what-is-member"></a>

**成員**(Member)是組織內的使用者，透過被分配到不同的角色來獲得相應的權限和資源。

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

成員就像是「公司的員工」，每位員工可以加入不同的部門（角色），並根據所屬部門獲得對應的工作權限。
{% endhint %}

***

## 成員類型說明 <a href="#member-types" id="member-types"></a>

<table><thead><tr><th>成員類型</th><th width="215">說明</th><th>權限範圍</th></tr></thead><tbody><tr><td>擁有者</td><td>預設為組織的創建者</td><td>擁有所有資源的完整存取權限<br>可以管理組織設定與角色權限</td></tr><tr><td>一般成員</td><td>角色內的成員</td><td>擁有所屬角色的權限與資源，如問答、對話權限等</td></tr></tbody></table>

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

* **擁有者** = 公司的總經理或系統管理員，可以管理所有事情
* **一般成員** = 公司的員工，根據所屬部門（角色）擁有不同權限
  {% endhint %}

{% hint style="info" %}
角色權限的詳細設定請參閱 [角色權限管理](/org/roles/role-permission.md)。
{% endhint %}

***

## 基礎操作 <a href="#basic-operations" id="basic-operations"></a>

### 進入成員管理介面 <a href="#enter-member-management" id="enter-member-management"></a>

1. 登入 MaiAgent 平台
2. 從左側選單點擊 「<mark style="color:blue;">組織設定</mark>」
3. 點擊 「<mark style="color:blue;">組織概覽</mark>」
4. 點擊 「<mark style="color:blue;">編輯成員</mark>」按鈕進入成員管理頁面

### 如何選擇加入成員的方式？ <a href="#how-to-choose-add-method" id="how-to-choose-add-method"></a>

加入成員都從成員管理頁右上角的「<mark style="color:blue;">邀請新成員</mark>」按鈕開始，視窗裡有兩個頁籤，請依情境選擇：

{% hint style="info" %}
**快速判斷**

* 你有對方的 Email 名單（不論對方有沒有 MaiAgent 帳號）→ 使用「**透過 Email 邀請**」：已有帳號的人會直接加入組織，沒有帳號的人會收到邀請信
* 想讓大家自助註冊 → 使用「**生成邀請連結**」，把連結分享出去
  {% endhint %}

{% hint style="success" %}
**情境範例：企業批次開通 30 位員工帳號**

**情況 A：你有員工名單** → 使用「透過 Email 邀請」的批量導入功能，一次貼上 30 個 Email。送出後系統會分別顯示直接加入、已發送邀請與已跳過（已是成員）的人數，不必事先分辨誰有帳號

**情況 B：想讓大家自助註冊** → 使用「生成邀請連結」，將連結透過公告或群組分享給員工

**情況 C：人數更多、或要同時指派角色** → 使用右上角「批次功能」的 Excel 匯入，見 [進階操作：批次成員與權限管理](#batch-member-permission-management)
{% endhint %}

***

### 已有 MaiAgent 帳號的人：Email 邀請直接加入 <a href="#add-member-existing-account" id="add-member-existing-account"></a>

要加入的成員**已經擁有 MaiAgent 帳號**時，同樣使用「<mark style="color:blue;">透過 Email 邀請</mark>」：

1. 在成員管理頁面點擊右上角「<mark style="color:blue;">邀請新成員</mark>」
2. 在「<mark style="color:blue;">透過 Email 邀請</mark>」頁籤選擇角色，輸入對方的 Email 後點「<mark style="color:blue;">新增</mark>」
3. 點擊「<mark style="color:blue;">發送邀請</mark>」

系統依 Email 判斷對方已有帳號，會**直接把對方加入組織並套用所選角色**，不需要對方做任何操作；完成訊息顯示「直接加入：N 人」，對方立即出現在成員列表。已經是組織成員的 Email 會被跳過，顯示「已跳過（已是成員）：N 人」。

{% hint style="info" %}
邀請連結只在**註冊當下**掛上角色，已有帳號的人用邀請連結無法加入。要替既有成員補角色，請在成員列表用 <mark style="color:blue;">編輯成員角色</mark>，或用 [批次新增角色成員](#batch-add-role-members)。
{% endhint %}

***

### Email 邀請（沒有帳號，有名單） <a href="#email-invite" id="email-invite"></a>

當您要邀請的成員**尚未擁有 MaiAgent 帳號**，且您已有對方的 Email 名單時，可透過 Email 邀請功能發送邀請信。

**步驟 1：進入邀請功能**

1. 從左側選單點擊「<mark style="color:blue;">組織設定</mark>」>「<mark style="color:blue;">組織概覽</mark>」
2. 在 <mark style="color:blue;">管理操作</mark> 區點擊「<mark style="color:blue;">編輯成員</mark>」進入成員管理頁
3. 點擊右上角「<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-1b2afc2271ee2b61312a979bfe06abf6292fec9e%2Finvitation-email-step1.png?alt=media" alt=""><figcaption></figcaption></figure>

**步驟 2：設定邀請內容**

1. 選擇「<mark style="color:blue;">透過 Email 邀請</mark>」頁籤
2. 選擇角色（可多選）：設定受邀者加入組織後的預設角色
3. 「<mark style="color:blue;">Credits 額度</mark>」區塊（採 Credits 計費且具 Credit 管理權限時顯示）會顯示受邀者加入時會套用的組織預設額度；要讓這批受邀者拿到不同的額度，開啟「<mark style="color:blue;">為這批邀請另設額度</mark>」，詳見 [成員 Credits 額度管理：邀請時另設額度](/others/credits/member-credit-quota.md#invitation-quota-override)
4. 「<mark style="color:blue;">邀請有效期</mark>」只套用在邀請連結；Email 邀請沒有到期日，在受邀者加入或你撤銷前都有效

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6fb0392320dbcfc35d474e7af316c1dde8a0da39%2Finvitation-email-step2.png?alt=media" alt=""><figcaption></figcaption></figure>

**步驟 3：輸入受邀者 Email**

在 Email 地址欄位輸入受邀者的電子郵件，點擊「<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-b591785ccda985c6cd125e1836c030d09216c44e%2Finvitation-email-step3.png?alt=media" alt=""><figcaption></figcaption></figure>

新增後，Email 會顯示在「已添加」清單中。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f35ffe90f895073f0ad1e23e4c88cb7aa153d40f%2Finvitation-email-step4.png?alt=media" alt=""><figcaption></figcaption></figure>

**步驟 4：批量輸入多個 Email（選用）**

若需要一次邀請多位成員，點擊「<mark style="color:blue;">批量導入</mark>」切換至批量輸入模式，可直接貼上多個 Email（以逗號、分號或換行分隔）。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3ef32100f74f9b47a4dc20ffa5263edb18096df6%2Finvitation-email-step5.png?alt=media" alt=""><figcaption></figcaption></figure>

**步驟 5：發送邀請**

確認邀請清單無誤後，點擊「<mark style="color:blue;">發送邀請</mark>」。系統會依每個 Email 的狀況分別處理，完成訊息會列出三種結果的人數：

| 結果訊息          | 代表                                                        |
| ------------- | --------------------------------------------------------- |
| 直接加入：N 人      | 已有 MaiAgent 帳號，已直接加入組織並套用角色，出現在成員列表                       |
| 已發送邀請：N 人     | 尚無帳號，已寄出邀請信，可在「<mark style="color:blue;">邀請狀態</mark>」頁籤追蹤 |
| 已跳過（已是成員）：N 人 | 已經在組織內，不重複處理                                              |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-04c4ce9fc34718da4c6db26df836d4dcdb438c1c%2Finvitation-email-step6.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**受邀者流程**

受邀者點信中的連結完成註冊後，系統會依**收到邀請的信箱**自動把對方加入組織並套用指定角色。Email 邀請沒有到期日，在對方加入或你撤銷前都有效；信件沒收到時，可在「<mark style="color:blue;">邀請狀態</mark>」按「<mark style="color:blue;">重新發送</mark>」（同一筆邀請連同第一次最多寄 3 次，間隔至少 5 分鐘）。
{% endhint %}

#### 受邀者註冊教學 <a href="#invitee-registration-guide" id="invitee-registration-guide"></a>

受邀者端的完整步驟（註冊、登入、邀請期限、公司使用 SSO 時的登入方式、切換組織）請見 [收到邀請：加入組織](/start/invitation.md)，可以直接把該頁連結轉給受邀者。

***

### 組織邀請連結（沒有帳號，自助註冊） <a href="#organization-invite-link" id="organization-invite-link"></a>

當您要邀請的成員**尚未擁有 MaiAgent 帳號**，且希望讓大家自行註冊時，可生成一個邀請連結分享給受邀者。

**步驟 1：生成邀請連結**

1. 點擊「<mark style="color:blue;">邀請新成員</mark>」按鈕
2. 選擇「<mark style="color:blue;">生成邀請連結</mark>」頁籤
3. 選擇角色（可多選）：設定透過此連結註冊者的預設角色
4. （Credits 計費組織）在「<mark style="color:blue;">Credits 額度</mark>」區塊確認透過此連結加入者會套用的額度；要另設時開啟「<mark style="color:blue;">為這批邀請另設額度</mark>」，每位加入者各拿一份，詳見 [成員 Credits 額度管理：邀請時另設額度](/others/credits/member-credit-quota.md#invitation-quota-override)
5. 設定邀請有效期
6. （選填）輸入連結描述，方便後續辨識管理
7. 點擊「<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-efc0cd4f67c5596ddec3226d7f0a889707906393%2Finvitation-link-step1.png?alt=media" alt=""><figcaption></figcaption></figure>

**步驟 2：複製並分享連結**

連結生成後，點擊「<mark style="color:blue;">複製連結</mark>」即可將邀請連結複製到剪貼簿，透過 Email、通訊軟體或內部公告分享給受邀者。摘要卡會列出角色、有效期與「加入時額度」。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-fa5ee2189a5768d85a2584be0627e35bbad6e62a%2Finvitation-link-step2.png?alt=media" alt=""><figcaption></figcaption></figure>

**步驟 3：受邀者完成註冊**

受邀者點擊連結後會進入 MaiAgent 註冊頁面，填寫基本資料並完成註冊後，即自動加入您的組織。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-134ca4280b7bf2616f4dd7c48a49b11702bab8de%2Finvitation-link-step3.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**注意事項**

* 邀請連結有使用期限，過期後將無法使用
* 同一連結可供多人使用註冊
* 已有帳號的人無法用邀請連結加入，請改用 Email 邀請
  {% endhint %}

#### 管理已建立的邀請連結 <a href="#invite-link-tab" id="invite-link-tab"></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>                                        | 建立連結時填的描述，沒填顯示「-」                                                                              |
| <mark style="color:blue;">邀請角色</mark>                                      | 透過此連結註冊的人會拿到的角色；超過兩個時收合成「+N」，滑過可展開                                                             |
| <mark style="color:blue;">邀請時間</mark>、<mark style="color:blue;">邀請人</mark> | 連結建立的時間與建立者                                                                                    |
| <mark style="color:blue;">過期時間</mark>                                      | 連結失效時間                                                                                         |
| <mark style="color:blue;">加入人數</mark>                                      | 透過此連結註冊加入的人數。大於 0 時可點開「<mark style="color:blue;">已加入使用者列表</mark>」視窗，列出每位使用者與加入時間，並可搜尋姓名或 Email |
| <mark style="color:blue;">狀態</mark>                                        | 左側開關可隨時停用或重新啟用連結；已過期的連結無法再啟用，請重新生成                                                             |
| <mark style="color:blue;">操作</mark>                                        | <mark style="color:blue;">複製連結</mark>                                                          |

***

### 成員列表的操作 <a href="#member-list-actions" id="member-list-actions"></a>

「<mark style="color:blue;">成員列表</mark>」頁籤可用姓名、ID 或 Email 搜尋，也可用角色下拉篩選出某個角色的成員（詳見 [角色成員篩選](/org/roles/group-member-filtering.md)）。每位成員的操作欄有三個圖示：

| 圖示                                      | 功能                                                                                                                                                                   |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">編輯成員角色</mark> | 調整這位成員所屬的角色，見 [為成員分配角色](#assign-role-to-member)                                                                                                                      |
| <mark style="color:blue;">編輯成員資訊</mark> | 修改成員在本組織的名稱（限組織擁有者），以及替成員設定個人偏好與自訂屬性（部門、職稱、分機等），見下方 [修改成員名稱](#edit-member-name) 與 [個人資料：自訂屬性—管理員代為設定](/org/overview/custom-attributes.md#admin-edit-member-metadata) |
| <mark style="color:blue;">刪除</mark>     | 將成員移出組織，見下方 [刪除成員](#delete-member)                                                                                                                                   |

### 修改成員名稱 <a href="#edit-member-name" id="edit-member-name"></a>

組織擁有者可以修改成員在**本組織**顯示的名稱，例如更正人名，或把公司代建帳號的名稱改成員工本名。改的是成員在這個組織裡的名稱，成員的帳號名稱不會被改到。

1. 在「<mark style="color:blue;">成員列表</mark>」找到該成員，點操作欄的「<mark style="color:blue;">編輯成員資訊</mark>」圖示
2. 視窗最上方的「<mark style="color:blue;">名稱</mark>」欄位會帶入該成員目前在本組織顯示的名稱，改成新名稱
3. 點「<mark style="color:blue;">確認</mark>」：視窗關閉並顯示成功提示，成員列表的「<mark style="color:blue;">成員</mark>」欄立即變成新名稱

名稱和同一個視窗裡的個人偏好、自訂屬性用同一顆「<mark style="color:blue;">確認</mark>」一起儲存；儲存失敗時視窗不會關閉，並顯示失敗原因。

| 規則        | 說明                                                                                                                                                 |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 誰可以改      | 只有**組織擁有者**，可以改任何成員的名稱，包括自己和其他擁有者。其他角色（包括有成員管理相關權限的角色）打開「<mark style="color:blue;">編輯成員資訊</mark>」時，名稱欄位看得到但唯讀，並提示「只有組織擁有者可以修改名稱」；個人偏好與自訂屬性照原本的權限編輯 |
| 影響範圍      | 只影響本組織。成員列表、成員搜尋、角色成員列表、對話指派對象的成員選單都會顯示新名稱；搜尋時用新名稱搜得到、用舊名稱搜不到，用 Email 仍搜得到                                                                         |
| 不影響的地方    | 成員的帳號名稱（成員本人在「<mark style="color:blue;">帳號</mark> → <mark style="color:blue;">個人資料</mark>」看到的名稱）不變；同一位成員所在的其他組織，看到的名稱也不受影響                         |
| 恢復顯示帳號名稱  | 把名稱清空（或只填空白）後按「<mark style="color:blue;">確認</mark>」，該成員在本組織改回顯示他的帳號名稱。清空時，欄位下方會提示將顯示的帳號名稱                                                          |
| 名稱格式      | 前後空白會自動去除；最多 255 字，超過時欄位下方顯示錯誤、不會儲存；名稱不需唯一。輸入的名稱與目前顯示的名稱相同時，視為沒有變更                                                                                 |
| 成員本人改帳號名稱 | 擁有者設定過的名稱仍然有效；沒有另外設定名稱的組織，會改顯示成員新的帳號名稱                                                                                                             |
| 變更紀錄      | 每次改名都會記在 [活動日誌](/org/activity-log.md)：操作者、時間、哪位成員、舊名稱與新名稱                                                                                          |

{% hint style="warning" %}
**由 SCIM 同步管理的成員不能手動改名**

透過 [SCIM 身分同步](/org/identity-sync.md#scim-member-behavior) 由身分提供者佈建的成員，名稱欄位會唯讀，並提示「此成員的名稱由身分提供者（SCIM）同步管理」；用 API 修改也會被拒絕。這類成員的名稱由身分提供者管理，請改在貴公司的身分提供者（例如 Azure AD）修改。
{% endhint %}

{% hint style="info" %}
要一次修改很多位成員的名稱，可用 Excel 批次匯入，見 [批次更新既有成員的名稱](#batch-update-member-names)。也可以透過 API 修改，見 API 文件 [修改成員名稱](https://docs.maiagent.ai/api/api-reference/zu-zhi-he-cheng-yuan#organizations-members-display-name-partial-update)。
{% endhint %}

### 刪除成員 <a href="#delete-member" id="delete-member"></a>

透過 「<mark style="color:blue;">刪除</mark>」 按鈕可將成員從組織中移除。

### 為成員分配角色 <a href="#assign-role-to-member" id="assign-role-to-member"></a>

成員加入組織後，您可以賦予每位成員不同的角色，根據角色給予其對應的權限。詳細設定請參閱 [角色權限管理](/org/roles/role-permission.md)。

***

## 進階操作：批次成員與權限管理 <a href="#batch-member-permission-management" id="batch-member-permission-management"></a>

{% hint style="info" %}
**什麼時候需要批次操作？**

當您需要一次新增大量成員（例如：50 位新員工）或為多位員工分配角色時，使用批次功能可以節省大量時間。
{% endhint %}

MaiAgent 提供強大的批次管理功能，適合需要大量新增或管理成員的情境。透過 Excel 檔案匯入，可一次完成多位成員的新增與角色分配，大幅提升管理效率。

### 批次功能入口 <a href="#batch-feature-entry" id="batch-feature-entry"></a>

在成員管理頁面，點擊右上角的 「<mark style="color:blue;">批次功能</mark>」按鈕，下拉選單中有三個選項：

| 選項                                               | 用途                                                                           |
| ------------------------------------------------ | ---------------------------------------------------------------------------- |
| <mark style="color:blue;">批次新增成員至組織</mark>       | 用 Email 名單一次把多人加入組織，見 [批次新增成員至組織](#batch-add-members)                        |
| <mark style="color:blue;">批次新增角色成員</mark>        | 一次為多位成員指派角色，見 [批次新增角色成員](#batch-add-role-members)                            |
| <mark style="color:blue;">批次匯入成員 Metadata</mark> | 一次更新多位成員的自訂屬性（部門、職稱、員編等），見 [批次匯入成員 Metadata](#batch-import-members-metadata) |

***

### 批次新增成員至組織 <a href="#batch-add-members" id="batch-add-members"></a>

此功能可透過 Excel 檔案一次新增多位成員到組織；組織擁有者也可以用同一份範本，批次更新既有成員在本組織的名稱（見 [批次更新既有成員的名稱](#batch-update-member-names)）。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-d8c0aefc5e89ab4cf1d0e34e6eb02053e12edb2e%2F%E6%88%AA%E5%9C%96%202025-12-10%20%E4%B8%8B%E5%8D%883.24.55.png?alt=media" alt=""><figcaption></figcaption></figure>

**操作步驟：**

1. **下載範本**：點擊「下載範本」取得 Excel 範本檔案
2. **編輯範本**：在範本中填入成員的 Email（必填欄位）
3. **上傳檔案**：將編輯好的檔案拖放或點擊上傳
4. **執行匯入**：點擊「上傳並執行」完成批次新增；成功時會跳出提示，列出這次處理的筆數（見 [匯入完成的提示](#batch-import-result)）

#### Excel 檔案格式 <a href="#excel-file-format" id="excel-file-format"></a>

| 欄位名稱                | 必填   | 說明                                                                                                             |
| ------------------- | ---- | -------------------------------------------------------------------------------------------------------------- |
| **Name**            | 選填   | 成員名稱，最多 255 字。這次才加入組織的人，Name 會成為他在本組織的名稱；其中帳號是這次才建立的，Name 也會成為帳號名稱，未填則自動使用 Email 前綴。已是成員的人，組織擁有者匯入時會用來更新本組織的名稱 |
| **Email(required)** | ✅ 必填 | 成員的電子郵件地址                                                                                                      |

#### 範例檔案內容 <a href="#excel-file-example" id="excel-file-example"></a>

| Name | Email(required)           |
| ---- | ------------------------- |
| 王小明  | <ming.wang@company.com>   |
| 李小華  | <hua.li@company.com>      |
| 張大偉  | <david.zhang@company.com> |
|      | <john@company.com>        |

{% hint style="info" %}
**案例說明**

某企業需要將 50 位新進員工加入 MaiAgent 組織：

1. IT 管理員從人資系統匯出員工名單（含姓名、Email）
2. 將資料整理成上述格式的 Excel 檔案
3. 上傳執行後，系統會：
   * 為已有 MaiAgent 帳號的員工：直接加入組織
   * 為尚無帳號的員工：自動建立帳號並加入組織
4. 所有新成員自動獲得「預設角色」權限
   {% endhint %}

{% hint style="warning" %}
**檔案格式說明**

* 僅支援 .xlsx 格式
* 檔案大小限制 10 MB；單次最多 25,000 列（不含標題列），超過時整份不匯入並提示「單次最多 25,000 列，請分檔匯入」，請拆成多個檔案分次匯入
* Email 為必填欄位；Name 最多 255 字
* 任一列有錯（例如 Email 空白或格式錯誤、Name 超過 255 字，新成員的列也算），整份檔案都不會匯入，錯誤訊息會列出有問題的列
* 同一個 Email 出現多次時，只處理第一筆
* 已是組織成員的 Email 不會重複加入：組織擁有者匯入時會依 Name 更新名稱，其他角色匯入時略過，見下方說明
  {% endhint %}

#### 批次更新既有成員的名稱 <a href="#batch-update-member-names" id="batch-update-member-names"></a>

由**組織擁有者**匯入時，檔案中 Email 已是本組織成員的列，會依 Name 處理該成員在本組織的名稱，範本欄位不變：

| 情況                             | 結果                                                       |
| ------------------------------ | -------------------------------------------------------- |
| Name 與目前顯示的名稱不同                | 更新為 Name，計入「更新名稱」                                        |
| Name 空白，或與目前顯示的名稱相同            | 不變更，計入「未變更」                                              |
| Name 與目前顯示的名稱不同，但成員由 SCIM 同步管理 | 不更新，計入「由 SCIM 同步管理，未更新」（理由見 [修改成員名稱](#edit-member-name)） |

* 只會更新成員在本組織的名稱，不會改既有成員的帳號名稱，也不影響成員所在的其他組織
* Name 空白不會清除已設定的名稱；要恢復顯示帳號名稱，請在「<mark style="color:blue;">編輯成員資訊</mark>」把名稱清空
* 每一筆實際的改名都會記在 [活動日誌](/org/activity-log.md)
* 擁有者以外的角色匯入時，既有成員照舊略過，不會更新名稱

#### 匯入完成的提示 <a href="#batch-import-result" id="batch-import-result"></a>

匯入成功時，畫面會跳出約 3 秒的成功提示，文字依匯入者身分不同：

| 匯入者   | 提示文字                                                                  |
| ----- | --------------------------------------------------------------------- |
| 組織擁有者 | 「新增 X 筆、更新名稱 Y 筆、未變更 Z 筆」；有 SCIM 同步管理的成員沒更新時，再加上「，N 筆由 SCIM 同步管理，未更新」 |
| 其他角色  | 維持原本的「新增 X 筆成員、已存在 Y 筆（已略過）」                                          |

{% hint style="info" %}
組織擁有者匯入時，已是成員的人不再顯示為「已存在（已略過）」，而是計入「更新名稱」或「未變更」。
{% endhint %}

***

### 批次新增角色成員 <a href="#batch-add-role-members" id="batch-add-role-members"></a>

此功能可批次為多位成員指派角色，實現自動分配權限。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3f7fc3207029981126f6c4ca0ab68e442ea4b3ce%2F%E6%88%AA%E5%9C%96%202025-12-10%20%E4%B8%8B%E5%8D%883.25.37.png?alt=media" alt=""><figcaption></figcaption></figure>

**操作步驟：**

1. **下載範本**：點擊「下載上傳範本」取得 Excel 範本
2. **下載參考資料**（選用）：點擊「下載目前成員角色分配」查看現有配置
3. **編輯範本**：
   * 填入成員 Email
   * 填入要分配的角色 ID
4. **上傳檔案**：將編輯好的檔案拖放或點擊上傳
5. **執行匯入**：點擊「上傳並執行」完成批次角色分配

#### Excel 檔案格式 <a href="#excel-file-format-role" id="excel-file-format-role"></a>

| 欄位名稱                    | 必填   | 說明                          |
| ----------------------- | ---- | --------------------------- |
| **Name**                | 選填   | 成員顯示名稱，若未填則自動使用 Email 前綴    |
| **Email(required)**     | ✅ 必填 | 成員的電子郵件地址                   |
| **Group\_id(required)** | ✅ 必填 | 要分配的角色 ID（UUID 格式）          |
| **Group\_name**         | 選填   | 角色名稱（僅供參考，系統以 Group\_id 為準） |

{% hint style="info" %}
**如何取得角色 ID？**

點擊「下載目前成員角色分配」可匯出包含所有角色 ID 的參考檔案，或至 [角色權限管理](/org/roles/role-permission.md) 頁面查看各角色的 ID。
{% endhint %}

#### 範例檔案內容 <a href="#excel-file-example-role" id="excel-file-example-role"></a>

| Name | Email(required)            | Group\_id(required)                  | Group\_name |
| ---- | -------------------------- | ------------------------------------ | ----------- |
| 王小明  | <ming.wang@company.com>    | 4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61 | 產品部門        |
| 王小明  | <ming.wang@company.com>    | 7a2b3c4d-e5f6-7890-abcd-ef1234567890 | Agent 管理員   |
| 李小華  | <hua.li@company.com>       | 4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61 | 產品部門        |
| 張大偉  | <david.zhang@company.com>  | 8b9c0d1e-f2a3-4567-89ab-cdef01234567 | 研發部門        |
| 新員工  | <new.employee@company.com> | 4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61 | 產品部門        |

{% hint style="success" %}
**案例說明：部門權限批次設定**

某企業完成 Azure AD 串接後，需要為 100 位員工依部門分配不同的資源存取權限（關於 Azure AD 設定，請參閱 [第三方登入（SSO）](/org/sso.md)）：

**步驟 1：準備角色**

* 在 MaiAgent 建立部門角色：「產品部門」「研發部門」「業務部門」
* 為各角色設定對應的功能權限（詳見 [角色權限管理](/org/roles/role-permission.md)）
* 為各角色分配可存取的 Agent、知識庫、對話平台

**步驟 2：準備 Excel**

* 從人資系統匯出員工名單（含部門資訊）
* 對照部門名稱填入對應的角色 ID
* 同一位員工可出現多列（例如王小明同時屬於產品部門和 Agent 管理員）

**步驟 3：執行匯入**

* 上傳 Excel 後，系統會：
  * 已在組織的成員：直接分配角色
  * 尚未加入組織的 Email：自動邀請加入並分配角色
  * 成員立即獲得角色對應的權限

**成果**

* 100 位員工在 5 分鐘內完成權限設定
* 各部門員工僅能存取與其業務相關的 Agent、知識庫、對話平台
  {% endhint %}

{% hint style="warning" %}
**檔案格式說明**

* 僅支援 .xlsx 格式
* 檔案大小限制 10 MB
* Email 和角色 ID 為必填欄位
* 同一 Email 可出現在多列（一人可擁有多個角色）
* 不存在組織的 Email 將自動建立帳號並邀請至組織
* **預設角色（DEFAULT）不可透過 Excel 批次分配**
* **擁有者角色（OWNER）不可透過 Excel 批次分配**
  {% endhint %}

***

### 批次匯入成員 Metadata <a href="#batch-import-members-metadata" id="batch-import-members-metadata"></a>

此功能可透過 Excel 一次更新多位成員的**自訂屬性**（metadata），例如把人資系統的部門、職稱、員工編號整批寫進成員資料。寫入的內容和成員在 [個人資料](/org/overview/custom-attributes.md) 自己填的、或管理員用 [編輯成員資訊](/org/overview/custom-attributes.md#admin-edit-member-metadata) 填的是同一份資料。

**操作步驟：**

1. **下載範本**：點擊「<mark style="color:blue;">下載範本</mark>」取得 Excel 範本
2. **編輯範本**：每一列填一位成員的一個屬性（Email、屬性名稱、值）；同一位成員有多個屬性就填多列
3. **上傳檔案**：將編輯好的檔案拖放或點擊上傳
4. **執行匯入**：點擊「<mark style="color:blue;">上傳並執行</mark>」，完成後顯示「已更新 N 筆 metadata」（N 為更新的成員數）

#### Excel 檔案格式 <a href="#excel-file-format-metadata" id="excel-file-format-metadata"></a>

| 欄位名稱                | 必填   | 說明               |
| ------------------- | ---- | ---------------- |
| **Email(required)** | ✅ 必填 | 成員的電子郵件，必須已是組織成員 |
| **Key**             | ✅ 必填 | 屬性名稱，例如 `部門`     |
| **Value**           | ✅ 必填 | 屬性的值，例如 `產品開發部`  |

#### 範例檔案內容 <a href="#excel-file-example-metadata" id="excel-file-example-metadata"></a>

| Email(required)         | Key | Value |
| ----------------------- | --- | ----- |
| <ming.wang@company.com> | 部門  | 產品開發部 |
| <ming.wang@company.com> | 職稱  | 工程師   |
| <hua.li@company.com>    | 部門  | 業務部   |

{% hint style="warning" %}
**整批成功或整批失敗，不會部分套用**

* 僅支援 .xlsx 格式，檔案大小限制 10 MB
* Email、Key、Value 三欄都必填；任一格空白、同一位成員出現重複的 Key、或 Email 不是組織成員，整份檔案都不會寫入，錯誤訊息會指出有問題的列
* 檔案裡有列出的成員，自訂屬性會**整份換成檔案的內容**：原本有、但檔案沒列的屬性會被清掉，包含「個人偏好」。要保留既有屬性，請把它們一起填進檔案
* 檔案沒列到的成員不受影響
  {% endhint %}

***

## 延伸閱讀 <a href="#further-reading" id="further-reading"></a>

* 角色與權限的詳細設定，請參閱 [角色權限管理](/org/roles/role-permission.md)
* EIP 登入的自動角色同步機制，請參閱 [第三方登入（SSO）](/org/sso.md)


---

# 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/overview/member.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.