> 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/build/hook/execution-logs.md). # Hook 執行紀錄查看每一次 Hook 攔截或改寫的紀錄、追查附件與工具回傳的檢查來源、控制是否記錄原始訊息內容，以及從對話中追查單筆訊息的 Hook 執行詳情。 Hook 每一次的攔截、改寫、放行都會留下紀錄。對受監管的產業（金融、醫療、政府）來說，**「可追溯」本身就是合規要求**——出了問題要查得到「哪一則訊息、被哪條規則、做了什麼處置、什麼時間」。

Hook 執行紀錄與客製化能力 — 執行紀錄（Audit Log）完整記錄每次處置：命中規則、處置動作、處理結果與時間戳，支援關鍵字搜尋、依 Agent 篩選與匯出報表

## 一、查看執行紀錄從左側選單進入 AgentOps →〈Hook 執行紀錄〉。你可以看到每一筆執行的： * **AI 助理**——哪個 Agent 觸發的 * **Hook 名稱、Hook 類型**——是哪一個 Hook 處理的 * **觸發點**——在哪個時點介入（接收使用者訊息時／AI 回應生成後） * **Hook 動作、結果**——做了什麼（遮罩改寫／攔截封鎖／放行）與處理結果 * **訊息內容、建立時間**——處理了哪則訊息、何時發生你可以用**Agent、規則、類型、動作、動作結果、觸發點、日期區間、關鍵字**篩選，也能**匯出報表**做進一步稽核分析。頁面上方也會顯示**總執行次數、命中次數、命中率**的統計。

Hook 執行紀錄列表 — 執行紀錄列表：每筆顯示 Agent、Hook 名稱、觸發點、動作與結果。可看到個資遮罩把手機改成 [REDACTED_PHONE]、敏感詞與提示注入被封鎖等實際處置

### 查看單筆詳情點開任一筆紀錄，會顯示這次處置的完整脈絡：**基本資訊（Hook 名稱、類型、觸發點、動作、結果）、關聯資訊、訊息內容、Metadata**，讓你清楚知道系統做了什麼。

Hook 執行紀錄單筆詳情 — 單筆詳情：以個資遮罩為例，可看到動作為 modify、訊息內容已遮罩為 [REDACTED_PHONE]

### 追查附件、知識庫與工具回傳的檢查進 AI 前的 Hook 不只檢查使用者打的字，附件內容、知識庫檢索段落、Agent 模式下的工具回傳也會經過同一組 Hook（詳見 [四種來源](/build/hook.md#four-sources)）。這類檢查同樣會留下一筆執行紀錄，觸發點顯示為「接收使用者訊息時」；點開單筆詳情，在 **Metadata** 區塊可以看到： * `path`：`input_context`，代表這筆是「非使用者親自輸入」的內容檢查 * `source`：內容來自哪裡——工具回傳會顯示該工具的名稱，知識庫檢索段落會顯示為檢索內容當你想釐清「模型是從哪個工具、哪份文件讀到敏感內容」時，用 `source` 就能一路追回去；被擋下的內容不會交給模型，對話本身不會中斷。 ### 匯出執行紀錄篩選列右側的「匯出」會依**目前的篩選條件**（Agent、Hook、類型、動作、結果、觸發點、日期區間、關鍵字）建立一筆匯出請求，在背景產生 Excel，並顯示「匯出請求已建立，正在處理中...」後自動切到「匯出請求」子頁（也可從「匯出」旁的「匯出請求」按鈕進入）。匯出請求頁列出每一次匯出的狀態（等待中／處理中／已完成／失敗）、發起匯出的使用者、記錄數、檔案大小、處理時長、建立時間與完成時間。狀態為已完成時，在操作欄點「下載」；失敗時點「查看錯誤詳情」；不再需要的匯出檔可「刪除」。 {% hint style="info" %} 這裡的匯出請求只包含 Hook 執行紀錄，與 AgentOps 左側選單的「匯出請求」（對話紀錄與評測報告的匯出）是分開的兩份清單。 {% endhint %} ## 二、控制是否記錄原始訊息執行紀錄預設**只記錄「處置結果」，不保留原始的敏感內容**——這是為了避免個資或敏感訊息又被留存在紀錄裡。若你在除錯階段需要看到「原始內容長什麼樣」，可以在 Hook 的設定頁把記錄遮罩前原始值開關由 `off` 改成 `on`。開啟後，紀錄會額外保留遮罩前／攔截前的原始內容，方便追查。

記錄遮罩前原始值開關 — 在 Hook 設定頁的「記錄遮罩前原始值」欄位控制：預設 off（只記型別與次數，不留原始個資），需要除錯時才改成 on

{% hint style="warning" %} **隱私權衡：** 開啟「記錄原始值」等於把原始的個資／訊息內容留存在執行紀錄中。**基於資安考量，建議平時維持關閉**，只在需要排查問題時暫時開啟。 {% endhint %} {% hint style="info" %} 「語意個資遮罩」的執行紀錄天然不含原文：偵測服務只回傳個資的位置與型別，紀錄裡只留下遮到的型別與次數。 {% endhint %} ## 三、從對話中查看 Hook 執行詳情除了集中式的執行紀錄，你也可以**從實際對話回頭追查**：進入客服對話 →〈所有對話〉，開啟任一則對話，就能看到該對話中哪些訊息被 Hook 處理過（遮罩或攔截），對應到當下的處置。這讓你在檢視客戶對話時，能直接理解「為什麼這則訊息被遮罩／被擋下」，不必另外比對紀錄。 ## 四、相關頁面 * [Hook 訊息攔截總覽](/build/hook.md)——Hook 是什麼、四種來源、七種標準範本 * [新增與設定 Hook](/build/hook/setup.md)——如何建立、設定參數、關聯 Agent --- # 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/build/hook/execution-logs.md?ask=&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.