一、功能概覽

「用戶列表」是單個 Bot（智能體）維度下的用戶畫像中心，用於營運和開發者查看：

• 哪些終端用戶與該 Bot 發生過有意義的互動；
• 每個用戶的身份標識（userId / 匿名 ID）；
• 每個用戶已產生的關鍵事件數量；
• 每個用戶的活躍時間（首次接觸、最後活躍）。
• 更多用戶體系的資訊可查看：用戶概述。

入口：開發者控制台 → 進入某個 Bot → 用戶管理（User Manage） → 用戶（Users）。

二、用戶列規則

核心規則：只有在該 Bot 內產生過至少一條「關鍵事件」的用戶，才會出現在用戶列表裡。

2.1 用戶列表的產生方式

系統中存在「用戶列表」，進入用戶列表的觸發點有兩類：

也就是說，單純發了訊息但沒有觸發任何關鍵事件的訪客，不會出現在用戶列表中；只有當大模型從對話中抽取出至少一條關鍵事件、或透過 API/UI 手動建立了一條關鍵事件，該用戶才會被「曝光」到營運視圖。

2.2 為什麼要按關鍵事件入列

關鍵事件是系統對會話內容做語義抽取後，認定具備業務價值的事實片段（例如「取款」「投訴」「爭議」「開戶成功」等）。以「產生過關鍵事件」作為入列標準，可以保證：

• 列表聚焦真正有業務價值的用戶，避免被一次性試探的訪客噪聲淹沒；
• 用戶行的「關鍵事件數」「最後活躍」等列具備可比性；
• 後續的營運動作（標記處理、外呼跟進）有明確的事件錨點。

2.3 關鍵事件的產生方式

關鍵事件來自三種觸發：

• REALTIME（即時）：每次會話有新訊息後自動觸發抽取；
• SCHEDULED（定時）：按計畫週期對歷史會話補抽；
• MANUAL（手動）：在會話詳情頁手動點擊「抽取」。

抽取過程由 LLM 按當前 Bot 配置的「事件類型字典」和業務規則進行分類，輸出 CREATE / UPDATE / MERGE / DELETE 四類操作。

因此，如果你期望某個 Bot 的用戶列表能顯示更多用戶，應當先確認：
① 該 Bot 是否啟用了關鍵事件抽取；
② 事件類型字典是否覆蓋了你關心的業務場景。

三、身份標識：userId 與匿名 ID

3.1 欄位定義

3.2 優先級規則

系統在定位「同一個用戶」時遵循：

有 userId 時，以 userId 為準；無 userId 時，回退到 AnonymousId。

UI 上「用戶身份」列的呈現同樣遵循這一規則：優先展示 userId，否則展示 AnonymousId，並把 displayName（暱稱）作為副標題。

3.3 兩者關係：從匿名到登入的升級

終端用戶常見的生命週期是：

                      
                      訪客（僅有 anonymousId）  ──登入/註冊──▶  註冊用戶（帶 userId）

                    

平台提供 bindUserId(botId, anonymousId, userId) 用於身份升級：

• 若該 userId 在該 Bot 下尚不存在：
  • 直接在原匿名畫像上寫入 userId；
  • 原 primaryAnonymousId 與匿名 ID 列表保留，歷史關鍵事件繼續歸屬同一畫像。
• 若該 userId 在該 Bot 下已存在：
  • 把當前匿名畫像的所有 anonymousIds 合併到已登入用戶畫像中；
  • 刪除匿名畫像；
  • 實現「先匿名訪問 → 再登入到舊帳號 → 歷史合併」的體驗。

因此，列表裡看到的某個用戶行可能歷經過：① 多個匿名 ID（多次清理 cookie / 跨裝置），② 最終被綁定到同一個 userId。「匿名 ID」列上的數量提示就是 anonymousIds.length。

3.4 關鍵事件如何歸屬用戶

關鍵事件實體（c_bot_event）上同樣存有 userId 與 anonymousId 欄位。在用戶詳情抽屜裡查詢事件時，匹配規則為：

• 當用戶已有 userId：只查詢 event.userId == userId 的事件；
• 當用戶僅有匿名 ID：查詢 event.userId 不存在 且 event.anonymousId == primaryAnonymousId 的事件。

這樣可以確保：升級後的註冊用戶能看到 userId 名下的全部事件；尚未升級的匿名用戶只看到自身匿名維度下的事件，不會被錯誤聚合。

四、時間欄位：首次接觸 vs 最後活躍

4.1 欄位定義

4.2 寫入規則

• 首次接觸：只在用戶列表首次建立時寫一次，之後永遠不變。可以理解為「該用戶與本 Bot 的認識起點」。
• 最後活躍：每次以下事件都會刷新為當前時間：
  • 用戶在該 Bot 內發送了一條訊息；
  • 該用戶產生了一條新的關鍵事件；
  • 關鍵事件狀態發生變更；
  • 聯絡資訊（手機號/暱稱）被補錄。

4.3 業務含義

4.4 列表預設排序

用戶列表預設按 最後活躍時間倒序展示——最新有動靜的用戶排最前面。
兩個時間列均支援點擊列頭按數值排序。

五、列表欄位一覽

六、使用指南

6.1 檢索用戶

頁面頂部的關鍵字搜尋框支援四類匹配（任一命中即可）：

注意：userId / 匿名 ID 不支援模糊查詢，必須輸入完整值。
顯示名和手機號支援模糊查詢。

6.2 查看用戶的關鍵事件

在用戶行點擊「關鍵事件」列的數字（或行末「查看」），右側抽屜會按以下條件分頁拉取事件：

• 用戶範圍：按 3.4 節規則按 userId 或匿名 ID 過濾；
• 支援二級過濾：事件分類、狀態、關鍵字（基於事件摘要的正則）；
• 預設按事件時間倒序展示；

事件抽屜中的列：事件分類、事件摘要、狀態、優先級、置信度、更新時間。

6.3 狀態、優先級、置信度的取值

6.4 常見營運動作

• 新用戶跟進：篩選近 N 天首次接觸的用戶；
• 沉睡喚回：配合關鍵事件分類篩出有過高價值動作但已不活躍的用戶；
• 未處理事件清單：進入用戶詳情抽屜後用「狀態 = 待處理 / 處理中」篩選，再批量跟進。

七、常見問題（FAQ）

Q1：我看到一個用戶在前端發了很多訊息，但用戶列表裡搜不到他？
A：用戶列表只展示「產生過關鍵事件的用戶」。若該 Agent 未啟用關鍵事件抽取，或抽取結果為空（訊息內容不命中任何已配置的事件類型），則該用戶不會進入列表。請檢查 Agent 的「關鍵事件抽取」開關與事件類型字典。在開發空間-Debug 的對話，也不會被用來提取關鍵事件，也不會展示在用戶列表中。

Q2：同一個真實用戶為什麼有時是匿名 ID、有時是 userId？
A：終端用戶在登入前，由 SDK 產生匿名 ID 進行會話；登入後接入方需把業務側的 userId 傳入。系統會透過 bindUserId 把匿名畫像合併到 userId 畫像，列表中後續看到的是 userId 那一行；原匿名 ID 會保留在 anonymousIds 列表裡，便於追溯。

Q3：「最後活躍」和會話/訊息表的最近時間不一致？
A：以畫像為準。最後活躍時間在訊息到達、事件建立、事件狀態變更、聯絡方式更新這四類時點會被刷新；如出現差異，多半是因為某次操作走了非標準路徑（例如離線匯入）。

Q4：「首次接觸」可以修改嗎？
A：不可以。該欄位僅在首次建立時落庫，之後任何更新都不會改寫它。

Q5：用戶列表與會話列表是什麼關係？
A：會話列表（conversationId 維度）記錄每一次對話；用戶列表（userId / anonymousId 維度）是會話之上的人維度聚合。一個用戶可對應多條會話；一條關鍵事件必然歸屬一個會話，也必然歸屬一個用戶畫像。