故障排查与诊断

诊断长期记忆为何未能持久保存，解决身份和 API 错误，并使用内置诊断工具在运行时验证已存储的记忆。

诊断并解决长期记忆问题

大多数长期记忆问题都属于以下三类之一：记忆未在会话之间保留、错误的用户接收到了记忆，或者 API 调用失败。本页提供了一个结构化检查清单、针对最常见失败路径的决策树，以及每个已知问题的参考表。

首要排查

在深入查看具体症状之前，请先按此检查清单逐项排查。大多数问题会在第 1 步或第 2 步得到解决。

1

确认角色已启用记忆

打开 Convai 控制台，选择角色，然后导航到 记忆 → 记忆设置。验证 长期记忆 开关已开启。

记忆是 默认关闭。除非您明确启用，否则不会存储或检索任何内容。这是 LTM 看起来不起作用的最常见原因。

2

验证 end_user_id 在会话之间是否保持稳定

添加一个临时的 Debug.Log 以确认相同的 end_user_id 在每个会话中都会发送：

using Convai.Runtime.Identity;
using UnityEngine;

public class IdentityDebugger : MonoBehaviour
{
    private void Awake()
    {
        string id = new DeviceEndUserIdProvider().GetEndUserId();
        Debug.Log($"[LTM] end_user_id for this session: {id}");
    }
}

运行 Play Mode 两次并比较日志中的 ID。如果 ID 在会话之间发生变化，记忆将不会保留——请参阅 End-User Identity 以了解原因及修复方法。

3

检查会话是否成功连接

长期记忆需要一个处于活动状态的 Convai 会话。如果 ConvaiManager 连接失败——API 密钥错误、没有互联网连接、服务器不可达——则无论后端存储了什么，角色都无法接收记忆上下文。

打开 Unity Console，查找来自 ConvaiManager的连接错误。在排查记忆问题之前先解决这些错误。

记忆未持久保存——决策树

常见问题

症状	可能原因	修复
角色从不回忆任何内容	角色上未启用记忆	在 Convai 控制台中启用： 记忆 → 记忆设置 → 长期记忆
记忆在编辑器中可用，但在玩家构建中不可用	玩家构建中的设备标识符不同	这是预期行为——玩家构建使用 SystemInfo.deviceUniqueIdentifier。请在同一设备上测试。
所有设备共享同一角色记忆	相同的 end_user_id 对所有用户都相同	每个用户都需要一个唯一标识符。实现一个自定义 IEndUserIdentityProvider。请参阅 End-User Identity。
重新安装后，玩家没有记忆	PlayerPrefs 重新安装时 GUID 被清除	这是 GUID 回退的预期行为。若要实现跨安装的持久记忆，请使用由服务器支持的身份（账户 ID）。
来自 Play Mode 的记忆出现在生产构建中	编辑器和生产环境使用相同的角色 ID	为开发/测试使用单独的角色 ID，这样编辑器测试数据就不会污染生产记忆。
角色回忆起本应已删除的旧记忆	DeleteAllAsync 在重新启用之前未被调用	调用 MemoryService.DeleteAllAsync(characterId, endUserId) 以清除该分区。
end_user_id 在日志中为 null	身份提供器返回空字符串	DeviceEndUserIdProvider 会回退为 GUID——它永远不会返回 null。如果您使用的是自定义提供器，请确保 GetEndUserId() 返回非空字符串。
API 调用抛出 401 Unauthorized	API 密钥无效或缺失	请验证 工具 → Convai → 配置。确保 ConvaiSettings.Instance.ApiKey 在运行时不为空。
API 调用抛出 404 Not Found	角色 ID 或 end_user_id 错误	确认来自 ConvaiCharacter Inspector。确认 end_user_id 来自一个 Debug.Log 在调用 API 之前。
AddAsync 返回 Event = "NONE"	事实是现有记忆的重复项	服务器会去重。该事实已存储——无需操作。
ListAsync 返回空列表	尚未存储任何记忆，或者使用了不同的 end_user_id	请验证 end_user_id 与会话发送的值一致。记忆只有在至少进行过一次对话会话后才会创建。
编辑器工具中的最终用户列表为空	尚未有用户连接，或者 API 密钥无效	先在 Play Mode 中与一个已启用记忆的角色对话以创建用户记录，然后点击 Refresh。
禁用记忆后，下一个会话仍返回旧记忆	禁用后记忆仍然保留	禁用记忆会停止新的累积，但不会删除现有记录。调用 DeleteAllAsync 如果需要从头开始，请在禁用前调用。

运行时诊断

验证角色已知内容

列出用户-角色对的所有记忆记录，以确认已存储的内容：

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

public class MemoryDiagnostics : MonoBehaviour
{
    [SerializeField] private string _characterId;

    private ConvaiRestClient _client;

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

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

    [ContextMenu("转储所有记忆")]
    public async void DumpAllMemories()
    {
        string endUserId = new Convai.Runtime.Identity.DeviceEndUserIdProvider().GetEndUserId();
        Debug.Log($"[LTM Diagnostics] end_user_id: {endUserId}");

        try
        {
            int page = 1;
            int total = 0;

            do
            {
                MemoryListResponse response = await _client.Memory.ListAsync(
                    _characterId, endUserId, page, pageSize: 50);

                foreach (MemoryRecord record in response.Memories)
                {
                    Debug.Log($"  [{record.Id[..8]}...] {record.Memory}");
                    total++;
                }

                if (!response.HasMore) break;
                page++;

            } while (true);

            Debug.Log($"[LTM Diagnostics] Total memories: {total}");
        }
        catch (Exception e)
        {
            Debug.LogError($"[LTM Diagnostics] {e.Message}");
        }
    }
}

将此组件添加到场景中的任意 GameObject 上。在 Inspector 中右键单击该组件标题并选择 转储所有记忆 以在不进入 Play Mode 的情况下将每个已存储的事实记录到 Console。

以编程方式检查记忆设置

[ContextMenu("检查记忆是否启用")]
public async void CheckMemoryEnabled()
{
    try
    {
        bool enabled = await _client.Characters.GetMemoryEnabledAsync(_characterId);
        Debug.Log($"[LTM Diagnostics] Memory enabled for {_characterId}: {enabled}");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM Diagnostics] {e.Message}");
    }
}

API 错误参考

HTTP 状态	可能原因	修复
401 未经授权	API 密钥缺失、已过期或不正确	在 工具 → Convai → 配置
403 禁止访问	API 密钥没有权限访问该角色	确保该角色与 API 密钥属于同一个 Convai 账户
404 未找到	characterId 或 memoryId 不存在	在调用 API 之前记录并验证这些 ID
429 请求过多	超出速率限制	退避后重试；避免在紧密循环中调用记忆 API
网络异常	没有互联网连接，或 Convai 后端不可达	检查连接性；在生产环境中实现带指数退避的重试逻辑

结论

从首要检查清单开始——角色已启用记忆并且稳定的 end_user_id 即可解决绝大多数问题。使用 DumpAllMemories 诊断功能来确认服务器实际存储了什么，并对照常见问题表排查任何特定症状。如果在完成本指南后问题仍然存在，API 错误参考提供了从 HTTP 状态码到可操作修复方法的映射。