Bitzsoft.Integrations.AI.AspNetCore 1.1.0

Bitzsoft.Integrations.AI.AspNetCore

面向企业多租户 ASP.NET Core AI 宿主的零 ORM 依赖、原生 AOT 兼容 HTTP 传输、错误治理与全业务端点辅助库。统一封装 SSE / NDJSON 零缓冲流式写出、RFC 9457 问题详情脱敏映射、已认证调用者租户 Fail-Closed 绑定、对话/后台长任务/多模态（STT/TTS/图像）Minimal API 与控制器辅助，以及面向存量 MVC 控制器的显式反射候选工具发现承接包。

版本与兼容性

dotnet add package Bitzsoft.Integrations.AI.AspNetCore

• 目标框架：net8.0;net10.0；
• 项目依赖：Bitzsoft.Integrations.AI.Abstractions、Bitzsoft.Integrations.AI.Conversation、Bitzsoft.Integrations.McpServer；
• 框架依赖：FrameworkReference Include="Microsoft.AspNetCore.App"；
• 原生 AOT 策略：工程启用 <IsAotCompatible>true</IsAotCompatible>，核心链路全量采用 AIAspNetCoreJsonContext 源生成序列化与零反射 RequestDelegate；仅存量 MVC 反射扫描扩展类显式标注 [RequiresUnreferencedCode] 与 [RequiresDynamicCode]，不干扰纯原生 AOT 宿主零 IL 警告交付。

核心模块与设计边界

一站式装配与异常中间件

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBitzsoftAIAspNetCore(
    configureStreamWriter: o => o.DefaultFormat = AIStreamFormat.Sse,
    configureCallerResolution: o => o.AllowFallbackTenantZero = false,
    configureProblemDetails: o => o.IncludeExceptionDetails = builder.Environment.IsDevelopment());

// 若存量 MVC 宿主需自动扫描只读控制器动作作为 MCP 候选工具（非 AOT 场景）：
// builder.Services.AddBitzMcpGovernanceCore();
// builder.Services.AddBitzMcpMvcCandidateDiscovery();

var app = builder.Build();
app.UseBitzAIExceptionHandler();
app.MapBitzAIBackgroundJobEndpoints("/api/ai/jobs").RequireAuthorization();
app.MapBitzAIMultimodalEndpoints("/api/ai/multimodal").RequireAuthorization();

完整最小示例

以下独立示例演示注入 ASP.NET Core AI 传输层服务、映射 AIDomainException 为脱敏 RFC 9457 详情、绑定已认证 HTTP 调用者上下文，以及零缓冲输出 HITL 审批、FDE 试运行预览与 FinOps 用量帧：

using System.Security.Claims;
using System.Text;
using System.Text.Json;
using Bitzsoft.Integrations.AI.Abstractions;
using Bitzsoft.Integrations.AI.AspNetCore;
using Bitzsoft.Integrations.AI.Conversation;
using Bitzsoft.Integrations.AI.Governance;
using Bitzsoft.Integrations.Core;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;

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

// 1. 解析并 Fail-Closed 校验已认证调用者租户与身份（免疫 X-Tenant-Id 请求头伪造）。
var httpContext = new DefaultHttpContext
{
    RequestServices = provider,
    TraceIdentifier = "trace-demo-01",
    User = new ClaimsPrincipal(new ClaimsIdentity(
    [
        new Claim(ClaimTypes.NameIdentifier, "lawyer-1001"),
        new Claim("TenantId", "tenant-sh-01"),
        new Claim("permission", "contracts:review"),
    ], "Bearer")),
};
httpContext.Request.Headers["X-Tenant-Id"] = "attacker-tenant";

var callerResolver = provider.GetRequiredService<IBitzAICallerHttpContextResolver>();
BitzAICallerContext caller = callerResolver.Resolve(httpContext);

// 2. 将领域异常统一映射为脱敏 RFC 9457 响应模型（支持 RetryAfter 与 TraceId）。
var problemMapper = provider.GetRequiredService<BitzAIProblemDetailsMapper>();
var rateLimitEx = new AIDomainException(
    errorCode: AIExecutionErrorCodes.RateLimited,
    message: "上游模型限流，请退避后重试",
    suggestedHttpStatusCode: StatusCodes.Status429TooManyRequests,
    provider: "deepseek",
    failureKind: IntegrationFailureKind.RateLimited,
    isRetryable: true,
    retryAfter: TimeSpan.FromSeconds(10));
BitzAIProblemDetailsResponse problem = problemMapper.MapToResponse(rateLimitEx, httpContext);

// 3. 构造 HITL 挂起、DryRun 试运行预览与 FinOps 计费终结帧并零缓冲写出 SSE。
var checkpoint = new AIHitlCheckpointState(
    PendingActionId: "act-demo-1",
    TenantId: caller.TenantId,
    UserId: caller.UserId,
    SessionId: "sess-demo-1",
    RequestId: "req-demo-1",
    TurnId: "turn-1",
    AgentCode: "contract-agent",
    ToolCallId: "call-1",
    ToolName: "seal_contract",
    ArgumentsJson: """{"contractId":"c-01"}""",
    ArgumentsHash: "hash-c01",
    SuspendedStateJson: null,
    Status: AIHitlSuspendStatus.Suspended,
    CreatedAt: DateTimeOffset.UtcNow,
    ExpiresAt: DateTimeOffset.UtcNow.AddMinutes(15));

AIStreamFrame[] frames =
[
    AIStreamResponseWriterExtensions.CreateHitlApprovalFrame(checkpoint),
    AIStreamResponseWriterExtensions.CreateDryRunPreviewFrame("call-2", "update_status", wouldMutate: true, message: "预览：将更新 1 条记录"),
    AIStreamResponseWriterExtensions.CreateFinOpsUsageFrame(new AIFinOpsUsageRecord
    {
        TenantId = caller.TenantId,
        UserId = caller.UserId,
        SessionId = "sess-demo-1",
        RequestId = "req-demo-1",
        ModelId = "deepseek-chat",
        InputTokens = 500,
        OutputTokens = 120,
        EstimatedCost = 0.0042m,
    }),
];

await using var responseStream = new MemoryStream();
httpContext.Response.Body = responseStream;
var writer = provider.GetRequiredService<IAIStreamResponseWriter>();
await writer.WriteStreamWithPrefetchAsync(httpContext, ToAsyncFrames(frames), problemMapper, AIStreamFormat.Sse);

string sseOutput = Encoding.UTF8.GetString(responseStream.ToArray());
string problemJson = JsonSerializer.Serialize(problem, AIAspNetCoreJsonContext.Relaxed.BitzAIProblemDetailsResponse);
Console.WriteLine($"租户={caller.TenantId}，错误码={problem.ErrorCode}，SSE长度={sseOutput.Length}，RFC9457={problemJson}");

static async IAsyncEnumerable<AIStreamFrame> ToAsyncFrames(AIStreamFrame[] items)
{
    foreach (AIStreamFrame item in items)
    {
        yield return item;
        await Task.Yield();
    }
}