Galosys.Foundation.Agents.AI.EntityFrameworkCore 26.8.13.2

Galosys.Foundation.Agents.AI.EntityFrameworkCore

MAF 消息级聊天历史 EF Core 存储模块。为 Galosys.Foundation.Agents.AI 的 ChatClientAgent 提供聊天历史的持久化与还原（ChatHistoryProvider 实现），提供程序无关、不依赖 Hosting（仅依赖 MAF 核心与 EF Core 抽象）。

会话级存储（AgentSessionStore）在独立模块 Galosys.Foundation.Agents.AI.Hosting.EntityFrameworkCore 中。

安装

<PackageReference Include="Galosys.Foundation.Agents.AI.EntityFrameworkCore" />

存储设计

主键 long Id 使用 [SnowflakeId]（Galosys DbContext<T> 基类保存时自动填充）；两实体实现 IMultiTenancy，租户填充与全局过滤由基类完成。

注册

using Microsoft.Extensions.DependencyInjection;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddDbContext<MyDbContext>(options => options.UseSqlite("Data Source=agents.db"));
builder.Services.AddEfCoreChatHistoryProvider<MyDbContext>(options =>
{
    // 可选：上下文窗口压缩器（IChatReducer）
    options.ChatReducer = new LastNChatReducer(20);
});

AddEfCoreChatHistoryProvider<TDbContext>() 幂等注册 EfCoreChatHistoryProvider<TDbContext> 与 ChatHistoryProvider（Transient，工厂经 IServiceScopeFactory 按操作解析 TDbContext，每次操作新建作用域、用完即弃）。

配置到 Agent

using Microsoft.Agents.AI;

var agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    Name = "assistant",
    ChatOptions = new ChatOptions { Instructions = "You are a helpful assistant." },
    ChatHistoryProvider = provider // 解析 ChatHistoryProvider 注入
});

Options（EfCoreChatHistoryProviderOptions）

• StateKey — 存入 AgentSession.StateBag 的状态键，默认 Provider 类型名
• JsonSerializerOptions — ChatMessage 序列化选项，默认模块自带 Web 默认
• ChatReducer — IChatReducer，Provide 返回前裁剪上下文窗口
• StorageInputRequestMessageFilter / StorageInputResponseMessageFilter / ProvideOutputMessageFilter — 存储/检索过滤
• StateInitializer — 会话状态初始化器，默认随机会话键
• SigningKey / SigningKeyProvider — 消息完整性密钥（HMAC-SHA256）；任一提供即启用写入签名 + 读取校验，篡改拒载；未配置不校验（兼容存量）

客户端/服务端生命周期两种姿势

• 客户端（单进程）：Sqlite + 单例 DbContext；ChatHistoryProvider Transient 按需创建。
• 服务端（多实例）：DbContext 每请求 Scoped；Provider 不缓存会话之外状态；使用 SQL Server / Npgsql（Sqlite 仅单写进程）。

生命周期安全：Provider 提供 IServiceScopeFactory 构造，按操作新建作用域解析 TDbContext，因此 agent 无论注册为 Singleton 还是 Scoped 都能安全使用，不会因「单例 agent 在根容器解析 Scoped DbContext」触发 Cannot resolve scoped service from root provider 异常（与 EfCoreAgentSessionStore 同模式）。直接传 TDbContext 的构造仍保留，用于客户端单例/测试。

MAF 硬规则

Provider 实例字段只持有 DbContext 与 ProviderSessionState，会话特定状态（会话键、消息计数）一律存入 AgentSession.StateBag，单实例服务多会话不串数据。

消息完整性

MAF 存储层加载的消息原样接受、不做校验，存储被攻破时攻击者可篡改消息角色经间接 prompt injection 影响 LLM。本模块支持为 RawPayload 计算 HMAC-SHA256 签名：

• 写入时签名存入 SignatureHash/SignatureAlgorithm。
• 读取时校验，签名不匹配的消息被拒载（跳过），不抛异常终止会话。
• 密钥经配置或保险库注入，勿硬编码；未配置密钥或读取到无签名的存量数据时按未启用处理，向后兼容。

using System.Security.Cryptography;
using Microsoft.Extensions.DependencyInjection;

builder.Services.AddEfCoreChatHistoryProvider<MyDbContext>(options =>
{
    // 从配置/保险库读取密钥（示例仅演示字节来源，勿硬编码真实密钥）
    options.SigningKey = Convert.FromBase64String(
        builder.Configuration["Agents:ChatIntegrityKey"]!);
});

依赖

• Galosys.Foundation.Agents.AI — Agent 核心（ChatHistoryProvider 抽象）
• Galosys.Foundation.EntityFrameworkCore — Galosys DbContext<T> 基类（租户填充/全局过滤）
• Microsoft.Agents.AI — MAF 核心（1.13）