管理最终用户记录

通过 Convai Configuration Window 或 EndUsersService 脚本 API 浏览和管理最终用户记录——涵盖编辑器工具、全部四个方法和分页。

Convai Unity SDK 会跟踪每一位连接到启用了记忆的角色的用户，作为一个 终端用户记录。每条记录都会存储用户的稳定标识符、最近活动时间戳，以及你在连接期间发送的任何元数据。你可以从 Unity 编辑器中浏览和删除这些记录，或使用 client.EndUsers.

Beta API。 方法签名是稳定的，但在未来的 SDK 更新中可能会更改。请在生产环境中固定你的 SDK 版本，并在升级前查看更新日志。

---

编辑器工具

从 Unity 菜单栏中打开面板： Convai → 长期记忆.

该面板显示与你的 API 密钥关联的所有终端用户记录。它按每批 200 条记录加载，并在数据量较大时使用基于游标的分页自动获取后续页面。

可用操作：

操作	方式
刷新列表	点击 刷新
选择单个记录	点击一条记录行
全选或取消全选	点击 全选 / 取消全选
删除所选记录	点击 删除

从 Unity 菜单栏打开终端用户管理面板：Convai → 长期记忆。

从编辑器中删除一条终端用户记录会移除 该记录以及该用户在所有角色中的所有记忆记录。此操作无法撤销。删除前会出现确认对话框。

带有名称和会话计数的终端用户记录。

脚本编写

---

EndUserDetails 字段

每条终端用户记录由 EndUserDetails:

属性	类型	说明
EndUserId	string	SDK 在连接时发送的稳定标识符
LastActiveTs	string	上次会话的 ISO 8601 时间戳
LastLtmUsageTs	string	上次 LTM 交互的 ISO 8601 时间戳
Metadata	Dictionary<string, object>	由 IEndUserMetadataProvider
DisplayName	string	计算属性 — 读取 Metadata["name"] ，如果存在且非空；否则 "User {EndUserId[..8]}"，可选地附加相对上次活动时间（例如， "User a1b2c3d4 (3d ago)")
ShortId	string	计算属性 — 截断形式的 EndUserId 用于紧凑显示（例如， "a1b2c3d4...ef01")

DisplayName 和 ShortId 是 C# 计算属性，不是存储字段。它们不会出现在 JSON API 响应中。

---

脚本 API

列出终端用户

使用基于游标的分页检索所有终端用户记录。默认每页限制为 50 条记录。

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

public class EndUserLister : MonoBehaviour
{
    [ContextMenu("List All End Users")]
    private async void ListAllEndUsers()
    {
        using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);

        string cursor = null;
        bool hasMore = true;
        var allUsers = new List<EndUserDetails>();

        while (hasMore)
        {
            var response = await client.EndUsers.ListAsync(limit: 50, cursor: cursor);

            if (response.EndUsers != null)
                allUsers.AddRange(response.EndUsers);

            hasMore = response.HasMore;
            cursor = response.NextCursor;

            if (!hasMore || string.IsNullOrEmpty(cursor))
                break;
        }

        Debug.Log($"Total end users: {allUsers.Count}");
        foreach (var user in allUsers)
            Debug.Log($"  {user.EndUserId} — last active: {user.LastActiveTs}");
    }
}

EndUsersListResponse 字段：

属性	类型	说明
EndUsers	List<EndUserDetails>	本页记录
TotalCount	int	终端用户记录总数
NextCursor	string	下一页的游标令牌； null 当不存在后续页面时
HasMore	bool	是否存在更多页面

你还可以使用 activeAfter 和 activeBefore （ISO 8601 字符串）按活动日期筛选：

var response = await client.EndUsers.ListAsync(
    limit: 50,
    activeAfter: "2025-01-01T00:00:00Z",
    activeBefore: "2025-06-01T00:00:00Z");

---

获取单个终端用户

通过其 endUserId.

检索某个特定用户的详细信息。
Debug.Log($"最后活动：{user.LastActiveTs}");
Debug.Log($"显示名称：{user.DisplayName}");

---

更新用户元数据

为用户更新一个或多个元数据键。补丁操作会保留你未包含的键——它不会替换整个元数据对象。

var patch = new Dictionary<string, object>
{
    { "name", "Jordan Kim" },
    { "department", "Facilities Management" }
};

var updated = await client.EndUsers.UpdateMetadataAsync("target-end-user-id", patch);
Debug.Log($"已更新 {updated.EndUserId} 的元数据。");

---

删除一个终端用户

DeleteAsync 会移除终端用户记录 以及该用户在所有角色中的所有记忆记录。不同于 MemoryService.DeleteAllAsync，后者仅作用于一个角色，此操作会全局移除该用户。此操作无法撤销。

var result = await client.EndUsers.DeleteAsync("target-end-user-id");

if (result.Deleted)
    Debug.Log($"终端用户 {result.EndUserId} 已删除。");
else
    Debug.LogWarning("删除返回 false — 用户可能不存在。");

---

DeleteAllAsync 与 DeleteAsync

操作	范围	移除内容
client.Memory.DeleteAllAsync(characterId, endUserId)	一个用户 + 一个角色	该用户-角色对的所有记忆记录
client.EndUsers.DeleteAsync(endUserId)	一个用户 + 所有角色	该用户记录以及跨所有角色的所有记忆

使用 DeleteAllAsync 当你想重置某个用户在特定角色中的记忆，同时保留其在其他角色中的记录时。使用 EndUsers.DeleteAsync 当你需要将某个用户从系统中完全移除时。

---

下一步

记忆管理 API长期记忆脚本参考