Bitzsoft.Integrations.AI.Conversation 1.1.0

Bitzsoft.Integrations.AI.Conversation

面向企业多租户 AI 对话应用的零 ORM 依赖、零业务词汇会话协议与运行时编排包。统一封装富消息分片与确定性 JSON 落盘预算、前后端流式事件帧协议、推理模型采样防踩坑选项工厂、跨任意分块的思考标签拆分与五维多轮 Token 去重累加投影器、两阶段上下文预算器、非阻断数字事实对账器、幂等请求四态台账与会话互斥租约协调器以及无锁 19 位单调递增主键生成器。

版本与兼容性

dotnet add package Bitzsoft.Integrations.AI.Conversation

• 目标框架：net8.0;net10.0；
• 项目依赖：Bitzsoft.Integrations.AI.Governance、Bitzsoft.Integrations.AI.Skills；
• 第三方依赖：仅复用 Microsoft.Extensions.AI.Abstractions、DI、Options、Logging，零新增第三方 NuGet 包；
• 不依赖 SqlSugar、EntityFrameworkCore、StackExchange.Redis 或 ASP.NET Core Web 框架（HTTP 写出独立位于 Bitzsoft.Integrations.AI.AspNetCore）。

核心模块与设计边界

双宿主流式事件帧对照表

IAIRequestLedgerStore 双 ORM（SqlSugar / EF Core）实现走查

建议在宿主请求台账表建立 (TenantId, SessionId, RequestId) 唯一索引，并在会话租约表建立 (TenantId, SessionId) 主键或唯一索引（或直接使用 Redis SET NX PX + Lua 释放）：

1. 原子插入或回查（CreateOrGetExistingAsync）：直接尝试插入 Version = 1, Status = Pending 新行；若命中唯一索引冲突异常，立即按 (TenantId, SessionId, RequestId) 回查既有行并返回 new AIRequestLedgerCreateResult(CreatedNew: false, existing)。
2. 双条件乐观并发跃迁（TryTransitionAsync）：
   • SqlSugar 宿主：使用 db.CopyNew().Updateable<SysAiRequestLedger>() 并在 WHERE 子句严格限定 TenantId == tenantId && SessionId == sessionId && RequestId == requestId && Status == (int)expectedStatus && Version == expectedVersion，同时将 Version 更新为 expectedVersion + 1、UpdatedAt 更新为 transition.TransitionedAt，仅当受影响行数 == 1 时返回 true；
   • EF Core 宿主：查询侧统一加 .AsNoTracking()，更新侧使用 ExecuteUpdateAsync 在单条 SQL 内匹配 Status == expectedStatus && Version == expectedVersion 并原子递增 Version。
3. 契约测试基类验收：宿主测试项目直接继承 Bitzsoft.Integrations.AI.Testing.AIRequestLedgerStoreContractTestsBase 调用 RunAllContractAssertionsAsync()，一行代码自动验证唯一键幂等、多租户与跨会话隔离、16 路并发抢占单赢家、心跳续期版本保护、会话租约令牌防伪释放与过期自动接管。

完整最小示例

以下示例演示单调 19 位主键生成、推理模型安全选项构建、跨块 <think> 流式投影与数字事实对账以及幂等请求抢占与重放：

using Bitzsoft.Integrations.AI.Conversation;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddBitzsoftAIConversation();
services.AddInMemoryBitzsoftAIConversationStores();

await using var provider = services.BuildServiceProvider(
    new ServiceProviderOptions { ValidateOnBuild = true, ValidateScopes = true });

using var scope = provider.CreateScope();
var idGenerator = scope.ServiceProvider.GetRequiredService<AISequentialIdGenerator>();
var coordinator = scope.ServiceProvider.GetRequiredService<IAIMessageRequestCoordinator>();
var projector = scope.ServiceProvider.GetRequiredService<AIChatResponseProjector>();

// 1. 构建推理模型选项：自动清空不兼容的 Temperature / TopP 并注入 reasoning_effort。
ChatOptions chatOptions = AIChatOptionsFactory.Create(new AIChatSessionRequest
{
    ModelId = "deepseek-flash",
    IsReasoningModel = true,
    ReasoningEffort = "high",
    Temperature = 0.7f,
    TopP = 0.9f,
});

// 2. 计算确定性请求指纹并声明幂等执行权。
string fingerprint = coordinator.ComputeFingerprint(new AIRequestFingerprintInput(
    TenantId: "tenant-demo",
    UserId: "user-01",
    SessionId: "sess-100",
    Prompt: "汇总本月已审结账单金额"));

var claim = await coordinator.TryClaimOrGetExistingAsync(new AIRequestClaimRequest(
    TenantId: "tenant-demo",
    UserId: "user-01",
    SessionId: "sess-100",
    RequestId: "req-20261107-01",
    RequestFingerprint: fingerprint,
    UserMessageId: idGenerator.NextId()));

if (claim.Outcome == AIRequestClaimOutcome.Acquired && claim.Entry is not null)
{
    // 3. 投影跨分块 <think> 流式更新并执行工具结果数字事实对账。
    static async IAsyncEnumerable<ChatResponseUpdate> MockStreamAsync()
    {
        yield return new ChatResponseUpdate(ChatRole.Assistant, [new FunctionCallContent("call-1", "query_bill_summary")]);
        yield return new ChatResponseUpdate(ChatRole.Tool, [new FunctionResultContent("call-1", """{"totalAmount":1200000}""")]);
        yield return new ChatResponseUpdate(ChatRole.Assistant, "<thi");
        yield return new ChatResponseUpdate(ChatRole.Assistant, "nk>核对账单金额 1200000 元</think>本月已审结总额为 120万元。");
        await Task.CompletedTask;
    }

    await foreach (AIStreamFrame frame in projector.ProjectStreamAsync(
        MockStreamAsync(),
        conversationId: "sess-100",
        requestId: "req-20261107-01",
        modelId: chatOptions.ModelId))
    {
        if (frame.Type == AIStreamFrameTypes.Done)
        {
            string? partsJson = AIMessagePartSerializer.Serialize(projector.Parts);
            await coordinator.MarkCompletedAsync(new AIRequestCompletionUpdate(
                TenantId: "tenant-demo",
                SessionId: "sess-100",
                RequestId: "req-20261107-01",
                ExpectedVersion: claim.Entry.Version,
                AssistantMessageId: idGenerator.NextId(),
                ResponseText: projector.PersistenceContent,
                PartsJson: partsJson,
                Usage: projector.Usage));
        }
    }
}

Console.WriteLine($"正文输出：{projector.AssistantText}，思考参数已清理：{chatOptions.Temperature is null}");

var sessionStore = provider.GetRequiredService<IAIConversationSessionStore>();
var createdSession = await sessionStore.CreateSessionAsync(new AIConversationSessionCreateRequest(
    TenantId: "tenant-demo",
    UserId: "user-demo",
    Title: "合规账单复核",
    ModelId: chatOptions.ModelId));

var reducer = provider.GetRequiredService<AICompactingChatReducer>();
var reducedMessages = (await reducer.ReduceAsync(new[]
{
    new ChatMessage(ChatRole.System, "你是严谨的法务财务助手。"),
    new ChatMessage(ChatRole.User, "请核对本月合同总额。"),
    new ChatMessage(ChatRole.Assistant, "本月已审结总额 120 万元。"),
})).ToList();

var jobQueue = provider.GetRequiredService<Bitzsoft.Integrations.AI.Abstractions.IAIBackgroundJobQueue>();
string bgPayloadJson = System.Text.Json.JsonSerializer.Serialize(
    new AIChatContinuationJobPayload(createdSession.SessionId, "输出完整风险报告"),
    AIConversationJsonContext.Default.AIChatContinuationJobPayload);
var bgJob = await jobQueue.EnqueueAsync(new Bitzsoft.Integrations.AI.Abstractions.AIBackgroundJobSubmission(
    TenantId: "tenant-demo",
    UserId: "user-demo",
    JobType: AIBackgroundJobTypes.ChatContinuation,
    PayloadJson: bgPayloadJson,
    SessionId: createdSession.SessionId));

Console.WriteLine($"会话已建档：{createdSession.SessionId}，归约后消息数：{reducedMessages.Count}，后台任务：{bgJob.JobId}");

全域对话持久编排、后台长任务与合规定价扩展

1. 会话仓储、分叉管理与断线回放（IAIConversationSessionStore / InMemoryAIConversationSessionStore / AITurnReplayBuilder）：
   • 提供租户/所有者强隔离的会话 CRUD、工作区载体与焦点实体绑定（BindWorkspaceAsync）、分叉切片克隆（自动重映射压缩游标并将未决审批卡重写为 superseded_by_branch）及断线重连回合快照重建（按 afterSequenceNumber 增量输出标准 AIStreamFrame 回放序列与 SuggestedAction）。
2. 全链路回合编排器（IAIConversationTurnOrchestrator / AIConversationTurnOrchestrator）：
   • 串联会话租约与幂等请求抢占、用户偏好四级求解与单航班纪元缓存、上下文窗口预算与滚动压缩、出站脱敏与驻留政策拦截、有序通道故障转移（复用 OrderedFailoverChatClient 与 AIUpstreamExceptionClassifier）、客户端断流半残消息补偿以及 FinOps 精确扣费。
3. 用户偏好单航班纪元缓存（AIUserPreferenceCache）：
   • 基于 IAICacheEpochCoordinator（AICacheEpochKeys.UserPreferenceEpochScope）与 AITenantSingleFlightEpochCache<AICachedUserPreferenceSnapshot> 提供 L1/L2 单航班防击穿、可配置负缓存与保存/删除自动纪元失效。
4. M.E.AI 对话缩减桥接与后台长任务引擎（AICompactingChatReducer / ChannelAIBackgroundJobQueue / AIBackgroundJobWorker）：
   • 对接 Microsoft.Extensions.AI 内置 MessageCountingChatReducer 与 SummarizingChatReducer，并支持切换回退至确定性数字对账滚动压缩器 DefaultAIConversationCompactor。
   • 完整实现 IAIBackgroundJobStore（InMemoryAIBackgroundJobStore）、IAIBackgroundJobQueue（基于 System.Threading.Channels 的 ChannelAIBackgroundJobQueue）与支持租约认领、心跳续约、乐观 CAS 跃迁、取消信号传播及 ChatOptions.AllowBackgroundResponses / ResponseContinuationToken（AIContinuationTokenCodec）挂起续传的 AIBackgroundJobWorker / AIChatContinuationJobHandler。
5. FinOps 计费、出站脱敏、HITL 协同与 Native AOT：
   • AIConversationFinOpsRecorder 调用 AIFinOpsCostCalculator 精确计算常规输入、缓存命中输入、输出及推理令牌成本，并按 AIOpenTelemetryTagNames 写入遥测标签与度量指标。
   • 出站前强制经 IAIOutboundRedactor + AIDataResidencyPolicy 校验，越权或跨区阻断立即 Fail-Closed 抛出 AIDomainException（AIExecutionErrorCodes.OutboundRedactedBlocked）。
   • 流式投影完整协同 HITL Suspended 挂起检查点与 DryRunMode 试运行预览帧（dry_run）。
   • 工程已启用 <IsAotCompatible>true</IsAotCompatible>（双目标框架 net8.0;net10.0），配合源生成 AIConversationJsonContext 消除反射序列化以支持 Native AOT 与 Trim 编译无警告通过。