> 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/activity-log.md).

# 活動日誌

查看組織內誰在什麼時間新增、更新、刪除了哪些資料，以及成員的登入紀錄，並可匯出成 Excel 留存稽核。

<mark style="color:blue;">活動日誌</mark> 記錄組織內資料的每一次新增、更新、刪除，以及成員的登入，每筆紀錄都包含操作時間、操作的成員、來源 IP 位址與變更內容。組織管理員可以用它追查「是誰、在什麼時候改了這個 Agent 的設定」；資安稽核人員可以依期間匯出成 Excel，作為稽核留存。

{% hint style="info" %}
頁面上方會提示「活動日誌採用定時同步機制，資料更新週期為 10 分鐘」。剛完成的操作，最多約 10 分鐘後才會出現在列表與匯出檔中。
{% endhint %}

## 誰可以使用 <a href="#who-can-use" id="who-can-use"></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> 也使用同一個權限；沒有此權限的成員即使透過 API 讀取事件詳情、匯出紀錄或下載連結，也會被拒絕。
* 角色若具備上層的 <mark style="color:blue;">組織權限</mark>，會一併取得 <mark style="color:blue;">活動日誌權限</mark>。
* 組織擁有者預設具備此權限。

權限的設定方式請見 [角色權限管理](/org/roles/role-permission.md)。

## 進入方式 <a href="#how-to-access" id="how-to-access"></a>

從左側選單點選 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">活動日誌</mark>。

## 記錄哪些事件 <a href="#what-is-recorded" id="what-is-recorded"></a>

每筆紀錄都標示「操作類型」與「資源類型」。例如操作類型為「更新」、資源類型為「AI 助理」，代表有成員修改了某個 Agent 的設定。

### 操作類型 <a href="#operation-types" id="operation-types"></a>

| 操作類型                                | 何時產生                      |
| ----------------------------------- | ------------------------- |
| <mark style="color:blue;">新增</mark> | 建立一筆資料，例如新增 Agent、知識庫或角色  |
| <mark style="color:blue;">更新</mark> | 修改既有資料的內容或設定              |
| <mark style="color:blue;">刪除</mark> | 刪除資料                      |
| <mark style="color:blue;">登入</mark> | 成員登入後台並進入這個組織，或在後台切換到這個組織 |

活動日誌只記錄會改變資料的操作與登入，單純開啟頁面或查看資料不會產生紀錄。

### 資源類型 <a href="#resource-types" id="resource-types"></a>

資源類型代表被操作的資料種類。篩選用的下拉選單只會列出這個組織實際出現過的資源類型，常見的有：

| 類別     | 資源類型                                              |
| ------ | ------------------------------------------------- |
| AI 助理  | AI 助理、AI 助理工具、AI 助理連接器、AI 助理技能、AI 助理知識庫           |
| 知識庫    | 知識庫、知識庫檔案、知識庫檔案標籤、常見問題、常見問題標籤                     |
| 對話與聯絡人 | 對話平台、聯絡人、聯絡人對話平台                                  |
| 組織與成員  | 組織、成員、成員排休時段、登入記錄                                 |
| 角色     | 角色、角色成員、角色權限、角色 AI 助理、角色知識庫、角色對話平台、角色資料庫、角色可用 LLM |
| 工具與資料  | 工具、連接器、技能、SQL 資料庫、服務帳戶                            |

## 查看與篩選紀錄 <a href="#view-and-filter" id="view-and-filter"></a>

列表依時間由新到舊排列，各欄位說明如下：

| 欄位                                      | 說明                                                                                                                     |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| <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>   | 「更新」事件會以「欄位: 新值」列出變更內容（最多 300 字，滑鼠移上去可看完整文字）；知識庫檔案的刪除事件會在最前面顯示「檔案名稱: 檔名」（詳見 [追查已刪除的知識庫檔案](#deleted-kb-file)）；其他事件顯示「-」 |
| <mark style="color:blue;">IP 位址</mark>  | 發出這次操作的來源 IP                                                                                                           |

### 篩選條件 <a href="#filters" id="filters"></a>

列表上方提供四個篩選條件，變更任一條件後列表會立即更新：

* <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> 可一次清除所有條件。

### 查看單筆事件詳情 <a href="#event-detail" id="event-detail"></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>（以英文代碼顯示，例如 `UPDATE`）、<mark style="color:blue;">物件模型</mark>、<mark style="color:blue;">物件 ID</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;">IP 位址</mark>、<mark style="color:blue;">請求方法</mark>、<mark style="color:blue;">API 路徑</mark>；登入事件則顯示 <mark style="color:blue;">使用者</mark>、<mark style="color:blue;">組織</mark>、<mark style="color:blue;">IP 位址</mark> 與 <mark style="color:blue;">登入方式</mark>（帳號所屬的認證來源代碼，例如 `maiagent`、`saml`） |
| <mark style="color:blue;">變更詳情</mark>  | 只有「更新」事件會顯示：逐一列出變更的欄位（以欄位代碼顯示）及其 <mark style="color:blue;">舊值</mark> 與 <mark style="color:blue;">新值</mark>                                                                                                                                                                                                                                                                                      |

## 追查已刪除的知識庫檔案 <a href="#deleted-kb-file" id="deleted-kb-file"></a>

知識庫裡的檔案被刪除後，活動日誌會在那筆刪除事件上顯示刪除當下的檔名。檔案已經不在知識庫裡、無法再用 ID 回查時，仍能從活動日誌看出「誰、在什麼時候、刪了哪個檔案」。

### 使用情境 <a href="#deleted-kb-file-scenario" id="deleted-kb-file-scenario"></a>

知識庫管理員發現 AI 助理突然答不出新方案的價格，懷疑價目表被刪了。他開啟 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">活動日誌</mark>，把資源類型篩成「知識庫檔案」、操作類型篩成「更新」，在 <mark style="color:blue;">詳細資訊</mark> 欄看到一筆「檔案名稱: 2026Q3 價目表.pdf, 刪除時間: …」，同一列就有執行刪除的成員與時間。他據此找到同事確認原因，再把檔案重新上傳——不用請工程師翻資料庫。

依下列步驟查詢：

{% stepper %}
{% step %}

### 篩選知識庫檔案的事件 <a href="#deleted-kb-file-step-filter" id="deleted-kb-file-step-filter"></a>

在 <mark style="color:blue;">選擇資源類型</mark> 選「知識庫檔案」，在 <mark style="color:blue;">選擇操作類型</mark> 選「更新」，再用 <mark style="color:blue;">開始日期</mark>／<mark style="color:blue;">結束日期</mark> 縮小到可能刪除的期間。

{% hint style="info" %}
在知識庫刪除檔案時，活動日誌記錄的操作類型是「更新」而不是「刪除」：系統會先把檔案標記為已刪除並保留一段時間，之後才永久清除。要找刪除事件，請篩選「更新」。
{% endhint %}

{% hint style="warning" %} <mark style="color:blue;">選擇資源類型</mark> 的下拉選單可能出現兩個「知識庫檔案」，分別對應不同時期的紀錄。選了其中一個找不到近期的紀錄時，請改選另一個。
{% endhint %}
{% endstep %}

{% step %}

### 在詳細資訊欄找檔名 <a href="#deleted-kb-file-step-list" id="deleted-kb-file-step-list"></a>

刪除事件的 <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-15067842d8fb765a407abf676ec35e4ae20e1845%2Factivity-log-deleted-file-list.png?alt=media" alt="活動日誌列表中，知識庫檔案刪除事件的詳細資訊欄顯示檔案名稱"><figcaption><p>刪除事件的詳細資訊欄最前面顯示檔案名稱</p></figcaption></figure>
{% endstep %}

{% step %}

### 開啟事件詳情確認 <a href="#deleted-kb-file-step-detail" id="deleted-kb-file-step-detail"></a>

點該列 <mark style="color:blue;">操作</mark> 欄的眼睛圖示開啟 <mark style="color:blue;">活動日誌詳情</mark>，<mark style="color:blue;">基本資訊</mark> 會同時顯示 <mark style="color:blue;">物件 ID</mark> 與 <mark style="color:blue;">檔案名稱</mark>；<mark style="color:blue;">上下文資訊</mark> 可看到執行刪除的成員與來源 IP。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-74e3fd929c61ff7ade47214d27f28468ed75ff99%2Factivity-log-deleted-file-detail.png?alt=media" alt="活動日誌詳情的基本資訊同時顯示物件 ID 與檔案名稱"><figcaption><p>活動日誌詳情的基本資訊同時顯示物件 ID 與檔案名稱</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 注意事項 <a href="#deleted-kb-file-notes" id="deleted-kb-file-notes"></a>

* **同名檔案**：知識庫裡可能有多個同名檔案，請以 <mark style="color:blue;">物件 ID</mark> 搭配 <mark style="color:blue;">操作時間紀錄</mark> 區分是哪一個。
* **取不到檔名時不猜測**：如果事件當下的紀錄沒有保存檔名，會顯示「檔案名稱: 無法取得檔案名稱」，系統不會用其他資料推測。
* **適用範圍**：目前只有「知識庫檔案」的刪除事件會顯示檔名；其他資源類型的刪除事件維持原本的顯示方式。
* **同步時間**：活動日誌每 10 分鐘同步一次，剛刪除的檔案最多約 10 分鐘後才會出現。
* **已存在的紀錄也適用**：檔名取自事件當下保存的資料，功能上線前發生的刪除事件同樣會顯示檔名。

## 匯出活動日誌 <a href="#export" id="export"></a>

匯出在背景處理，建立後可以繼續操作其他頁面，完成後到 <mark style="color:blue;">匯出記錄</mark> 下載 Excel 檔。

{% stepper %}
{% step %}

### 設定要匯出的範圍 <a href="#export-step-filter" id="export-step-filter"></a>

匯出會套用畫面上目前的篩選條件（日期、使用者、資源類型、操作類型）；沒有設定任何條件時，匯出全部紀錄。
{% endstep %}

{% step %}

### 建立匯出 <a href="#export-step-create" id="export-step-create"></a>

點右上角的 <mark style="color:blue;">匯出</mark>（滑鼠移到按鈕上會提示「單次匯出上限 50,000 筆」）。建立成功時會出現「匯出任務已建立」。
{% endstep %}

{% step %}

### 下載檔案 <a href="#export-step-download" id="export-step-download"></a>

點 <mark style="color:blue;">匯出記錄</mark> 進入匯出清單，待 <mark style="color:blue;">狀態</mark> 變成 <mark style="color:blue;">已完成</mark>，點該列的 <mark style="color:blue;">下載</mark> 圖示取得檔案。
{% endstep %}
{% endstepper %}

### 匯出狀態 <a href="#export-status" id="export-status"></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> 與 <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>  | 處理時發生錯誤（系統會先自動重試），或處理超過 2 小時仍未完成；點 <mark style="color:blue;">查看錯誤詳情</mark> 可看原因 |

停留在 <mark style="color:blue;">匯出記錄</mark> 頁面時，自己建立的匯出一完成，畫面會提示「匯出請求已完成，可以下載檔案了」，並送出「匯出完成」的瀏覽器通知（需允許瀏覽器通知）；失敗時則提示「匯出請求失敗，請查看錯誤詳情」。

{% hint style="warning" %} <mark style="color:blue;">匯出記錄</mark> 列出的是整個組織的活動日誌匯出，不只自己建立的；具備 <mark style="color:blue;">活動日誌權限</mark> 的成員都看得到並可下載。匯出檔含有成員 Email、IP 位址與資料內容，請依公司的資安規範保管。
{% endhint %}

### 匯出檔內容 <a href="#export-file" id="export-file"></a>

* 格式為 Excel（`.xlsx`），檔名為 `events_export_<組織 ID>_<日期時間>.xlsx`。
* 每列一筆事件，依時間由新到舊排列；符合條件的紀錄超過 50,000 筆時，只會包含最新的 50,000 筆。
* 欄位名稱為英文，主要欄位如下：

| 欄位               | 內容                                        |
| ---------------- | ----------------------------------------- |
| `ID`             | 事件編號                                      |
| `Timestamp`      | 事件時間，ISO 8601 格式的 UTC 時間（結尾為 `+00:00`）    |
| `User`           | 操作成員的 Email                               |
| `Resource Type`  | 資源類型的系統代碼，例如 `chatbots.Chatbot`           |
| `Object ID`      | 被操作資料的 ID                                 |
| `Operation`      | 操作類型代碼：`create`、`update`、`delete`、`login` |
| `Diff Preview`   | 事件當下該筆資料的完整內容（JSON 格式）；登入事件留白             |
| `Request Method` | 請求方法，例如 `POST`、`PATCH`                    |
| `Login Method`   | 登入事件的認證來源代碼                               |
| `IP Address`     | 來源 IP 位址                                  |

## 資料保存 <a href="#data-retention" id="data-retention"></a>

活動日誌只會持續累加：後台沒有刪除或編輯活動日誌的功能，系統也在資料庫層阻擋刪除紀錄，組織擁有者同樣無法移除任何一筆。紀錄不會因時間經過而自動清除，需要留存特定期間的資料時，用日期篩選後匯出即可。

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

### 剛修改的設定，為什麼在活動日誌找不到？ <a href="#faq-not-yet-shown" id="faq-not-yet-shown"></a>

活動日誌每 10 分鐘同步一次，請稍候再重新整理。匯出檔也來自同一份資料，剛完成的操作同樣要等同步後才會出現在匯出檔中。

### 刪除了知識庫檔案，為什麼操作類型顯示「更新」？ <a href="#faq-kb-file-delete-as-update" id="faq-kb-file-delete-as-update"></a>

在知識庫刪除檔案時，系統會先把檔案標記為已刪除並保留一段時間，之後才永久清除，因此活動日誌當下記錄的是一筆「更新」。這筆紀錄的 <mark style="color:blue;">詳細資訊</mark> 最前面會顯示「檔案名稱: 檔名」，可以和一般的更新事件區分。查詢方式見 [追查已刪除的知識庫檔案](#deleted-kb-file)。

### 要匯出的紀錄超過 50,000 筆怎麼辦？ <a href="#faq-over-export-limit" id="faq-over-export-limit"></a>

單次匯出最多 50,000 筆，超過時只會保留最新的 50,000 筆。請縮小日期範圍（例如逐月）分批匯出。

### 匯出檔裡的時間為什麼和畫面上差了幾個小時？ <a href="#faq-timezone" id="faq-timezone"></a>

匯出檔的 `Timestamp` 是 UTC 時間，畫面上則依瀏覽器所在時區顯示。以台灣時間（UTC+8）為例，匯出檔的時間加 8 小時即為畫面上的時間。

### 匯出一直失敗怎麼辦？ <a href="#faq-export-failed" id="faq-export-failed"></a>

在 <mark style="color:blue;">匯出記錄</mark> 點 <mark style="color:blue;">查看錯誤詳情</mark> 確認原因。處理超過 2 小時仍未完成的匯出會被標為 <mark style="color:blue;">失敗</mark>，這時可縮小日期範圍後重新匯出；若仍持續失敗，請將錯誤詳情提供給客服協助排查。


---

# 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/activity-log.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.