一、功能概览
「用户列表」是单个 Agent 维度下的用户画像中心，用于运营和开发者查看：
- 哪些终端用户与该 Agent 发生过有意义的交互；
- 每个用户的身份标识（userId / 匿名 ID）；
- 每个用户已产生的关键事件数量；
- 每个用户的活跃时间（首次接触、最后活跃）。
- 更多用户体系的信息可查看：用户概述。
入口：开发者控制台 → 进入某个 Agent → 用户管理（User Manage） → 用户（Users）。
二、用户列规则
核心规则：只有在该 Agent 内产生过至少一条「关键事件」的用户，才会出现在用户列表里。
2.1 用户列表的产生方式
系统中存在「用户列表」，进入用户列表的触发点有两类：
| 触发点 | 是否会让用户出现在列表 | 说明 |
|---|---|---|
| 终端用户在该 Agent 中发送消息 | 否 | 仅保证后续如有事件可被关联；不会单独让此用户在列表可见 |
| 关键事件抽取后写入新事件 | 是，画像中的事件计数 +1，用户进入列表 | 同时更新最后活跃时间等字段 |
| 事件状态变更 | 已在列表中的用户更新 | — |
| 联系方式补录 | 已在列表中的用户补录手机号、显示名等 | — |
也就是说，单纯发了消息但没有触发任何关键事件的访客，不会出现在用户列表中；只有当大模型从对话中抽取出至少一条关键事件、或通过 API/UI 手动创建了一条关键事件，该用户才会被「曝光」到运营视图。
2.2 为什么要按关键事件入列
关键事件是系统对会话内容做语义抽取后，认定具备业务价值的事实片段（例如「取款」「投诉」「争议」「开户成功」等）。以「产生过关键事件」作为入列标准，可以保证：
- 列表聚焦真正有业务价值的用户，避免被一次性试探的访客噪声淹没；
- 用户行的「关键事件数」「最后活跃」等列具备可比性；
- 后续的运营动作（标记处理、外呼跟进）有明确的事件锚点。
2.3 关键事件的产生方式
关键事件来自三种触发：
- REALTIME（实时）：每次会话有新消息后自动触发抽取；
- SCHEDULED（定时）：按计划周期对历史会话补抽；
- MANUAL（手动）：在会话详情页手动点击「抽取」。
抽取过程由 LLM 按当前 Agent 配置的「事件类型字典」和业务规则进行分类，输出 CREATE / UPDATE / MERGE / DELETE 四类操作。
因此，如果你期望某个 Agent 的用户列表能显示更多用户，应当先确认：
① 该 Agent 是否启用了关键事件抽取；
② 事件类型字典是否覆盖了你关心的业务场景。
三、身份标识：userId 与匿名 ID
3.1 字段定义
| 字段名 | 含义 | 由谁产生 |
|---|---|---|
userId |
用户 ID，最高级标识，由接入方（开发者）从自己的业务系统（账号体系 / CRM）传入 | 开发者侧 |
anonymousIds |
该用户关联过的所有匿名 ID 列表，用于跨设备 / 升级合并 | 系统维护 |
3.2 优先级规则
系统在定位「同一个用户」时遵循：
有
userId时，以userId为准；无userId时，回退到AnonymousId。
UI 上「用户身份」列的渲染同样遵循这一规则：优先展示 userId，否则展示 AnonymousId，并把 displayName（昵称）作为副标题。
3.3 两者关系：从匿名到登录的升级
终端用户常见的生命周期是：
访客（仅有 anonymousId） ──登录/注册──▶ 注册用户（带 userId）
平台提供 bindUserId(botId, anonymousId, userId) 用于身份升级：
- 若该
userId在该 Agent 下尚不存在：- 直接在原匿名画像上写入
userId； - 原
primaryAnonymousId与匿名 ID 列表保留，历史关键事件继续归属同一画像。
- 直接在原匿名画像上写入
- 若该
userId在该 Agent 下已存在：- 把当前匿名画像的所有
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 字段定义
| 中文 | 类型 | 含义 |
|---|---|---|
| 首次接触 | 毫秒时间戳 | 该用户画像在本 Agent 中首次被创建的时间 |
| 最后活跃 | 毫秒时间戳 | 该用户画像最近一次被触达/变更的时间 |
4.2 写入规则
- 首次接触：只在用户列表首次创建时写一次，之后永远不变。可以理解为「该用户与本 Agent 的认识起点」。
- 最后活跃：每次以下事件都会刷新为当前时间：
- 用户在该 Agent 内发送了一条消息；
- 该用户产生了一条新的关键事件；
- 关键事件状态发生变更；
- 联系信息（手机号/昵称）被补录。
4.3 业务含义
| 场景 | 应该看哪个字段 |
|---|---|
| 用户获取/新用户分析、留存队列划分 | 首次接触 |
| 活跃度排序、跟进优先级、清单刷新 | 最后活跃 |
| 长期未来访的「沉睡用户」筛选 | 最后活跃（按升序或时间窗筛选） |
4.4 列表默认排序
用户列表默认按 最后活跃时间倒序展示——最新有动静的用户排最前面。
两个时间列均支持点击列头按数值排序。
五、列表字段一览
| 列 | 取值字段 | 说明 |
|---|---|---|
| 用户身份 | userId 或 AnonymousId（优先 userId） + displayName 副标题 |
行标题；点击后弹出关键事件抽屉 |
| 匿名 ID | anonymousIds（数量徽标 + 鼠标悬浮列出） |
反映该用户绑定/合并过的匿名 ID 数 |
| 关键事件 | totalEventCount |
累计事件数；点击进入事件视图 |
| 最后活跃 | lastActiveTime |
见第四章 |
| 首次接触 | firstContactTime |
见第四章 |
六、使用指南
6.1 检索用户
页面顶部的关键字搜索框支持四类匹配（任一命中即可）：
| 字段 | 匹配方式 |
|---|---|
userId |
完全匹配 |
anonymousId |
完全匹配 |
displayName |
正则模糊匹配 |
phone |
正则模糊匹配 |
注意：userId / 匿名 ID 不支持模糊查询，必须输入完整值。
显示名和手机号支持模糊查询。
6.2 查看用户的关键事件
在用户行点击「关键事件」列的数字（或行末「查看」），右侧抽屉会按以下条件分页拉取事件：
- 用户范围：按 3.4 节规则按
userId或匿名 ID 过滤； - 支持二级过滤：事件分类、状态、关键字（基于事件摘要的正则）；
- 默认按事件时间倒序展示；
事件抽屉中的列：事件分类、事件摘要、状态、优先级、置信度、更新时间。
6.3 状态、优先级、置信度的取值
| 维度 | 可选值 |
|---|---|
状态 (status) |
待处理 PENDING / 处理中 IN_PROGRESS / 已解决 RESOLVED / 已关闭 CLOSED |
优先级 (priority) |
低 LOW / 中 MEDIUM / 高 HIGH / 紧急 CRITICAL |
置信度 (confidence) |
低 LOW / 中 MEDIUM / 高 HIGH |
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 维度）是会话之上的人维度聚合。一个用户可对应多条会话；一条关键事件必然归属一个会话，也必然归属一个用户画像。