> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/end-user-management.md).

# 管理终端用户记录

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

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

***

{% tabs %}
{% tab title="编辑器工具" %}
从 Unity 菜单栏中打开面板： **Convai → 长期记忆**.

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

**可用操作：**

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

<figure><img src="/files/7562581514fe67609170ba9b8b83d8140546942b" alt="Unity menu bar showing Convai → Long Term Memory navigation path"><figcaption><p>从 Unity 菜单栏打开终端用户管理面板：Convai → 长期记忆。</p></figcaption></figure>

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

<figure><img src="/files/0102113dc2b5fe44586f74bceb0ebec284b3ad99" alt="End-user records with name and session count"><figcaption><p>带有名称和会话计数的终端用户记录。</p></figcaption></figure>
{% endtab %}

{% tab title="脚本编写" %}
通过 `client.EndUsers` 在一个 `ConvaiRestClient` 实例上访问终端用户操作。

```csharp
using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);
```

完整示例请参见下面的每个方法。
{% endtab %}
{% endtabs %}

***

### `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 条记录。

```csharp
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 字符串）按活动日期筛选：

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

***

#### 获取单个终端用户

通过其 `endUserId`.

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

***

#### 更新用户元数据

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

```csharp
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} 的元数据。");
```

***

#### 删除一个终端用户

{% hint style="danger" %}
`DeleteAsync` 会移除终端用户记录 **以及该用户在所有角色中的所有记忆记录**。不同于 `MemoryService.DeleteAllAsync`，后者仅作用于一个角色，此操作会全局移除该用户。此操作无法撤销。
{% endhint %}

```csharp
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` 当你需要将某个用户从系统中完全移除时。

***

### 下一步

{% content-ref url="/pages/0b7e1084a14c3bcf13fec179ad83b458f07ecff4" %}
[记忆管理 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/memory-management-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/9c55a31cd790424665e521972bff5affc2dbe7f9" %}
[长期记忆脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/long-term-memory-scripting-reference.md)
{% endcontent-ref %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/end-user-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.