最终用户管理

使用配置窗口或 EndUsersService API 浏览和管理最终用户记录。包括分页、元数据编辑和安全删除。

浏览和管理终端用户记录

当用户与启用记忆的角色交互时，Convai 后端会为每个唯一的终端用户创建一条终端用户记录 end_user_id。这些记录包含用户的显示名称、元数据，以及其最后活动和最后一次记忆交互的时间戳。本页介绍两种处理这些记录的方法：用于开发期间进行可视化管理的内置编辑器工具，以及 EndUsersService 用于运行时或工具使用的脚本 API。

Beta API 注意： Convai 后端上的所有终端用户管理端点都使用 beta API 标志。就目前而言，方法签名和响应结构是稳定的，但在未来的 SDK 或后端更新中可能会发生变化。

编辑器工具：长期记忆选项卡

配置窗口包含一个 长期记忆 选项卡，允许你无需编写任何代码即可浏览和删除终端用户记录。在开发过程中，它可用于查看哪些用户已经积累了记忆，以及清理测试数据。

打开工具

前往 Convai 并选择 长期记忆 选项卡。

界面概览

控件	函数
刷新	从服务器获取当前终端用户列表。列表不会自动加载——首次打开后或更改后请点击“刷新”。
终端用户列表	一个可滚动的列表，显示你账户中的所有终端用户记录。每一项显示显示名称（来自元数据的 "name" 键）以及用户 ID 的简写形式。
全选	切换所有可见条目的选中状态。再次点击可取消全部选中。
删除	永久删除所有选中的终端用户记录及其关联记忆。删除前需要进行确认。
状态 / 重试	加载失败时显示。点击 重试 以再次尝试获取。

理解终端用户列表

每个条目代表一个唯一的 end_user_id 已连接过至少一个角色的用户。显示名称来自用户元数据字典中的 "name" 键。如果未设置名称，该条目会显示用户 ID 的截断形式（ShortId).

该列表每次请求获取 200 项。基于游标的分页会自动处理更大的数据集——在显示列表之前，所有页面都会被获取并合并。

在编辑器工具中删除终端用户记录会移除该记录 以及该用户在所有角色中的所有记忆记录 。此操作无法撤销。

EndUserDetails 字段

以下字段可在每条终端用户记录上使用，无论是在编辑器工具中还是通过脚本 API：

字段	类型	说明
EndUserId	string	完整的 end_user_id 由 SDK 发送的字符串。
DisplayName	string	根据 metadata["name"] （如果存在）计算得出；否则根据用户 ID 生成。
ShortId	string	用于紧凑显示的 ID 截断形式。
LastActiveTs	string	用户最近一次会话的 ISO 8601 时间戳。
LastLtmUsageTs	string	该用户最近一次记忆读取或写入的 ISO 8601 时间戳。
Metadata	Dictionary<string, object>	通过以下方式提交的任意键值数据： IEndUserMetadataProvider 在连接时，或通过以下方式更新： UpdateMetadataAsync.

脚本 API：EndUsersService

ConvaiRestClient.EndUsers 公开 EndUsersService，它提供与编辑器工具相同的功能，并额外支持元数据编辑。可将其用于运行时管理工具、自动清理任务或集成测试。

设置 ConvaiRestClient

using System;
using Convai.RestAPI;
using UnityEngine;

public class EndUserManager : MonoBehaviour
{
    private ConvaiRestClient _client;

    private void Awake()
    {
        _client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);
    }

    private void OnDestroy()
    {
        _client?.Dispose();
    }
}

ConvaiSettings 是用于存储你的 API 密钥的 ScriptableObject，配置在 工具 → Convai → 配置. ConvaiRestClient 实现 IDisposable ——用完后务必释放它。

本页中的所有示例都使用 async void 以兼容 Unity。务必如图所示将异步调用包装在 try/catch 如图所示。

列出终端用户

通过基于游标的分页遍历所有终端用户记录。

using System;
using System.Threading;
using Convai.RestAPI.Internal;
using UnityEngine;

public async void ListAllEndUsers(CancellationToken cancellationToken = default)
{
    try
    {
        string cursor = null;
        const int limit = 50;

        do
        {
            EndUsersListResponse response = await _client.EndUsers.ListAsync(
                limit: limit,
                cursor: cursor,
                cancellationToken: cancellationToken);

            foreach (EndUserDetails user in response.EndUsers)
            {
                Debug.Log($"{user.DisplayName} ({user.ShortId}) — 最后活动时间：{user.LastActiveTs}");
            }

            cursor = response.HasMore ? response.NextCursor : null;

        } while (cursor != null);
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] 列出终端用户失败：{e.Message}");
    }
}

ListAsync 参数

参数	类型	默认值	说明
limit	int	50	每页记录数。
cursor	string?	null	上一条响应中的分页游标 NextCursor时会被忽略。请 null 用于第一页。
activeAfter	string?	null	ISO 8601 字符串。仅返回在此时间戳之后活跃的用户。
activeBefore	string?	null	ISO 8601 字符串。仅返回在此时间戳之前活跃的用户。
cancellationToken	CancellationToken	默认	可选的取消支持。

EndUsersListResponse 字段

字段	类型	说明
EndUsers	List<EndUserDetails>	当前页上的记录。
TotalCount	int	跨所有页面的终端用户记录总数。
NextCursor	string	下一页的游标。 null 当不再有更多页面时。
HasMore	bool	是否存在更多页面。

获取单个终端用户

public async void GetUser(string endUserId, CancellationToken cancellationToken = default)
{
    try
    {
        EndUserDetails user = await _client.EndUsers.GetAsync(endUserId, cancellationToken);
        Debug.Log($"名称：{user.DisplayName} — 最后一次 LTM：{user.LastLtmUsageTs}");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] 获取终端用户失败：{e.Message}");
    }
}

更新终端用户元数据

元数据可随时更新——并不局限于连接时。请使用只包含你想更改的键的补丁字典；补丁中未包含的现有键会被保留。

using System;
using System.Collections.Generic;
using System.Threading;
using Convai.RestAPI.Internal;
using UnityEngine;

public async void UpdateUserRole(
    string endUserId,
    string newRole,
    CancellationToken cancellationToken = default)
{
    try
    {
        var patch = new Dictionary<string, object>
        {
            { "role", newRole }
        };

        EndUserUpdateResponse updated = await _client.EndUsers.UpdateMetadataAsync(
            endUserId,
            patch,
            cancellationToken);

        Debug.Log($"已更新 {updated.DisplayName}：角色现在为 {newRole}");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] 更新元数据失败：{e.Message}");
    }
}

删除终端用户

public async void DeleteUser(string endUserId, CancellationToken cancellationToken = default)
{
    try
    {
        EndUserDeleteResponse response = await _client.EndUsers.DeleteAsync(endUserId, cancellationToken);
        Debug.Log($"已删除：{response.Deleted} — 用户 ID：{response.EndUserId}");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] 删除终端用户失败：{e.Message}");
    }
}

EndUsersService.DeleteAsync 会永久移除终端用户记录 以及该用户在所有角色中的所有关联记忆记录。这比 MemoryService.DeleteAllAsync更广，它只会清除某一个角色的记忆，同时保留用户记录。请仅在彻底停用某个用户账户时使用 DeleteAsync 。此操作无法撤销。

完整 API 参考

所有方法都在 ConvaiRestClient.EndUsers (EndUsersService）。所有 CancellationToken 参数都默认为 默认.

方法	签名	返回
ListAsync	(int limit, string? cursor, string? activeAfter, string? activeBefore, CancellationToken ct)	Task<EndUsersListResponse>
GetAsync	(string endUserId, CancellationToken ct)	Task<EndUserDetails>
UpdateMetadataAsync	(string endUserId, IReadOnlyDictionary<string, object> metadataPatch, CancellationToken ct)	Task<EndUserUpdateResponse>
DeleteAsync	(string endUserId, CancellationToken ct)	Task<EndUserDeleteResponse>

结论

终端用户记录会在用户与您的角色交互时自动创建。编辑器工具可在开发期间为您提供可视化概览； EndUsersService API 可通过代码提供相同的功能。有关将身份、记忆和终端用户 API 结合在一起的完整示例，请参见 使用示例.