自定义持久化提供程序

通过实现 IKeyValueStore 或 IPersistenceProvider，将 PlayerPrefs 会话存储替换为云后端、加密文件存储或内存实现。

Convai Unity SDK 将会话数据——连接状态、会话 ID、恢复令牌以及编辑器端最终用户 GUID——存储在 PlayerPrefs 默认通过 PlayerPrefsKeyValueStore。如果 PlayerPrefs 如果这适合您的部署，您就不需要本页。若您需要云端保存、加密存储、服务端会话管理，或用于自动化测试和 CI 的隔离存储，请替换持久化提供器。

SDK 写入存储的内容

键前缀	内容	重要性
convai.session.*	会话 ID 和恢复令牌	允许 SDK 在不重启 AI 回合的情况下恢复断开的会话
convai.end_user_id	仅限编辑器的设备 GUID（回退）	由……使用 DeviceEndUserIdProvider 在 Unity 编辑器中，当硬件 ID 不可用时
convai.prefs.*	用户偏好（例如静音状态）	在应用启动之间持久化 SDK 级设置

替换持久化提供器也就替换了这些内容的读写位置。你的实现必须处理 SDK 涉及的每个键——下面的适配器模式可确保不会遗漏任何内容。

持久化接口

IKeyValueStore——简单存储

namespace Convai.Domain.Abstractions
{
    public interface IKeyValueStore
    {
        string GetString(string key, string defaultValue = null);
        void   SetString(string key, string value);
        bool   HasKey(string key);
        void   DeleteKey(string key);
        void   Save();
    }
}

Save() 在写入操作后调用。对于内存存储而言它是无操作；对于基于文件的存储，它会刷新到磁盘。请在不需要异步操作的本地存储场景中实现此接口。

IPersistenceProvider——完整功能存储

namespace Convai.Runtime.Core.Providers
{
    public interface IPersistenceProvider
    {
        // 同步读取
        string GetString(string key, string defaultValue = null);
        int    GetInt(string key, int defaultValue = 0);
        float  GetFloat(string key, float defaultValue = 0f);
        bool   GetBool(string key, bool defaultValue = false);
        bool   HasKey(string key);

        // 同步写入
        PersistenceResult SetString(string key, string value, PersistenceOptions options = default);
        PersistenceResult SetInt(string key, int value, PersistenceOptions options = default);
        PersistenceResult SetFloat(string key, float value, PersistenceOptions options = default);
        PersistenceResult SetBool(string key, bool value, PersistenceOptions options = default);
        PersistenceResult Delete(string key);
        PersistenceResult DeleteAll(string prefix);

        void Save();

        // 异步操作
        IConvaiOperation<PersistenceResult>   SyncAsync(CancellationToken ct = default);
        IConvaiOperation<PersistenceResult>   SaveVersionedAsync<T>(VersionedKey key, T value,
                                                  ConflictResolutionStrategy strategy = ConflictResolutionStrategy.LastWriteWins,
                                                  CancellationToken ct = default);
        IConvaiOperation<VersionedValue<T>>   LoadVersionedAsync<T>(string ns, string key, CancellationToken ct = default);
        IConvaiOperation<PersistenceResult>   MigrateAsync(int fromVersion, int toVersion, CancellationToken ct = default);
    }
}

builder.UsePersistence() 接受 IPersistenceProvider. 如果你的实现是 IKeyValueStore，请将其包装在适配器中（见 适配器模式 下文）。异步操作（SyncAsync, SaveVersionedAsync）如果你的后端是同步的，可以返回占位结果。

应实现哪个接口：

场景	实现
本地文件、加密 SQLite、内存	IKeyValueStore
云端保存、服务端存储、多设备同步	IPersistenceProvider
现有 IKeyValueStore 并在其上添加云同步	两者都要——将同步/版本化操作委托给云客户端

支持类型

PersistenceResult

成员	类型	说明
Success	bool	操作是否成功。
错误消息	string	错误描述，如果 Success 为 false.
时间戳	DateTime	操作完成时的时间。
版本	long	操作后的版本号（适用于版本化操作）。
PersistenceResult.Succeeded(version)	static	创建成功结果。
PersistenceResult.Failed(error)	static	创建失败结果。

ConflictResolutionStrategy

由……使用 SaveVersionedAsync 用于在异步/云场景中解决写入冲突。

值	行为
LastWriteWins	基于时间戳，最近写入的值获胜。
HighestVersionWins	版本号更高的值获胜。
LocalWins	本地数据始终覆盖远程数据。
RemoteWins	远程数据始终覆盖本地数据。
Manual	向调用方返回冲突信息，以便显式解决。

PersistenceOptions

var options = new PersistenceOptions(
    conflictPolicy:  ConflictResolutionPolicy.LastWriteWins,
    createIfMissing: true,
    maxRetries:      3
);

实现示例

内存存储（测试 / CI）

适用于自动化测试和 CI 运行，在这些场景下，运行之间的持久状态会破坏结果。

// InMemoryKeyValueStore.cs
using System.Collections.Generic;
using Convai.Domain.Abstractions;

public class InMemoryKeyValueStore : IKeyValueStore
{
    private readonly Dictionary<string, string> _store = new();

    public string GetString(string key, string defaultValue = null)
        => _store.TryGetValue(key, out string v) ? v : defaultValue;

    public void SetString(string key, string value)
        => _store[key] = value;

    public bool HasKey(string key)
        => _store.ContainsKey(key);

    public void DeleteKey(string key)
        => _store.Remove(key);

    public void Save() { /* 内存中无操作 */ }
}

加密文件存储

满足禁止明文的合规要求 PlayerPrefs 用于会话数据。

// EncryptedFileKeyValueStore.cs
using System.Collections.Generic;
using System.IO;
using Convai.Domain.Abstractions;
using UnityEngine;

public class EncryptedFileKeyValueStore : IKeyValueStore
{
    private readonly string _filePath;
    private readonly IEncryptionService _encryption;
    private Dictionary<string, string> _cache = new();

    public EncryptedFileKeyValueStore(string fileName, IEncryptionService encryption)
    {
        _filePath   = Path.Combine(Application.persistentDataPath, fileName);
        _encryption = encryption;
        Load();
    }

    public string GetString(string key, string defaultValue = null)
        => _cache.TryGetValue(key, out string v) ? v : defaultValue;

    public void SetString(string key, string value) => _cache[key] = value;
    public bool HasKey(string key)                  => _cache.ContainsKey(key);
    public void DeleteKey(string key)               => _cache.Remove(key);

    public void Save()
    {
        string json      = JsonUtility.ToJson(new SerializableDictionary(_cache));
        string encrypted = _encryption.Encrypt(json);
        File.WriteAllText(_filePath, encrypted);
    }

    private void Load()
    {
        if (!File.Exists(_filePath)) return;
        string encrypted = File.ReadAllText(_filePath);
        string json      = _encryption.Decrypt(encrypted);
        _cache           = JsonUtility.FromJson<SerializableDictionary>(json)?.ToDictionary()
                           ?? new Dictionary<string, string>();
    }
    // 为简洁起见，SerializableDictionary 辅助代码省略。
}

调用 Save() 在每次写入后，或定期刷新。写入会缓冲在内存中——自上次写入以来的数据 Save() 会在崩溃时丢失。

IKeyValueStore 实现的适配器模式

builder.UsePersistence() 需要 IPersistenceProvider. 使用此适配器包装任何 IKeyValueStore:

// KeyValueStorePersistenceAdapter.cs
using System.Threading;
using Convai.Domain.Abstractions;
using Convai.Runtime.Core.Async;
using Convai.Runtime.Core.Providers;

public class KeyValueStorePersistenceAdapter : IPersistenceProvider
{
    private readonly IKeyValueStore _store;

    public KeyValueStorePersistenceAdapter(IKeyValueStore store) => _store = store;

    public string GetString(string key, string defaultValue = null)
        => _store.GetString(key, defaultValue);

    public int GetInt(string key, int defaultValue = 0)
    {
        string raw = _store.GetString(key);
        return raw != null && int.TryParse(raw, out int v) ? v : defaultValue;
    }

    public float GetFloat(string key, float defaultValue = 0f)
    {
        string raw = _store.GetString(key);
        return raw != null && float.TryParse(raw, out float v) ? v : defaultValue;
    }

    public bool GetBool(string key, bool defaultValue = false)
    {
        string raw = _store.GetString(key);
        return raw != null && bool.TryParse(raw, out bool v) ? v : defaultValue;
    }

    public bool HasKey(string key) => _store.HasKey(key);

    public PersistenceResult SetString(string key, string value, PersistenceOptions options = default)
    { _store.SetString(key, value); return PersistenceResult.Succeeded(); }

    public PersistenceResult SetInt(string key, int value, PersistenceOptions options = default)
    { _store.SetString(key, value.ToString()); return PersistenceResult.Succeeded(); }

    public PersistenceResult SetFloat(string key, float value, PersistenceOptions options = default)
    { _store.SetString(key, value.ToString("G")); return PersistenceResult.Succeeded(); }

    public PersistenceResult SetBool(string key, bool value, PersistenceOptions options = default)
    { _store.SetString(key, value.ToString()); return PersistenceResult.Succeeded(); }

    public PersistenceResult Delete(string key)
    { _store.DeleteKey(key); return PersistenceResult.Succeeded(); }

    public PersistenceResult DeleteAll(string prefix)
        => PersistenceResult.Failed("此后端不支持 DeleteAll。");

    public void Save() => _store.Save();

    // 异步存根——同步后端返回即时结果。
    public IConvaiOperation<PersistenceResult> SyncAsync(CancellationToken ct = default)
        => ConvaiOperation.Succeeded(PersistenceResult.Succeeded());

    public IConvaiOperation<PersistenceResult> SaveVersionedAsync<T>(VersionedKey key, T value,
        ConflictResolutionStrategy strategy = ConflictResolutionStrategy.LastWriteWins,
        CancellationToken ct = default)
        => ConvaiOperation.Succeeded(PersistenceResult.Failed("此后端不支持版本化操作。"));

    public IConvaiOperation<VersionedValue<T>> LoadVersionedAsync<T>(string ns, string key, CancellationToken ct = default)
        => ConvaiOperation.Succeeded(VersionedValue<T>.NotFound);

    public IConvaiOperation<PersistenceResult> MigrateAsync(int fromVersion, int toVersion, CancellationToken ct = default)
        => ConvaiOperation.Succeeded(PersistenceResult.Succeeded());
}

DeleteAll(string prefix) 在此适配器中返回失败结果。SDK 会在 DeleteAll 会话重置操作期间调用。若您的部署需要完整的会话重置，请实现 DeleteAll 通过遍历存储的键并移除与前缀匹配的项。

注册提供器

// CustomPersistenceManager.cs
using Convai.Runtime.Components;
using Convai.Runtime.Core;

public class CustomPersistenceManager : ConvaiManager
{
    [SerializeField] private bool _useEncryptedStorage = true;

    protected override ConvaiRuntimeBuilder CreateRuntimeBuilder()
    {
        ConvaiRuntimeBuilder builder = base.CreateRuntimeBuilder();

        如果
        {
            IEncryptionService encryption = new AesEncryptionService();
            var store = new EncryptedFileKeyValueStore("convai_session.dat", encryption);
            builder.UsePersistence(new KeyValueStorePersistenceAdapter(store));
        }

        return builder;
    }
}

故障排查

症状	可能原因	修复
重启后会话未恢复	GetString 返回 null 用于重新加载会话键	确保 Save() 在应用退出前同步调用。订阅 Application.quitting 。
NullReferenceException 内部 IPersistenceProvider 实现	在存储初始化之前调用异步方法	在提供器的构造函数中初始化后端存储，在 UsePersistence() 被调用。
崩溃时的数据丢失	SetString 写入会缓冲在内存中，并且 Save() 未被调用	调用 Save() 在每次写入后，或通过定时器刷新。
会话重置无法清除所有 SDK 数据	DeleteAll(prefix) 在适配器中返回失败结果	实现 DeleteAll 通过遍历存储的键集合并移除前缀匹配项。

下一步

凭据、身份与存储运行时模块系统实现自定义模块