Bitzsoft.Integrations.AI.Governance 1.1.0

Bitzsoft.Integrations.AI.Governance

面向企业多租户 AI 应用的零 ORM 依赖、零业务词汇治理基础设施包。封装数据合规分级与模型选型路由（R1–R4）、工具风险与敏感度目录、七步受控工具管线（GuardedAIFunction）、不可信内容围栏与 JSON 感知确定性预算截断、启发式注入信号指标、服务端持久化待办动作协议（参数规范化与 SHA-256 防篡改校验）以及固定窗口限流与 Token 日预算守卫。

版本与兼容性

dotnet add package Bitzsoft.Integrations.AI.Governance

• 目标框架：net8.0;net10.0（使用 .NET 8 内置 TimeProvider，不为 .NET 5 宿主伪造兼容层）；
• 依赖：Bitzsoft.Integrations.AI.Abstractions、Microsoft.Extensions.AI.Abstractions、Microsoft.Extensions.DependencyInjection.Abstractions、Microsoft.Extensions.Options、Microsoft.Extensions.Logging.Abstractions；
• 不依赖 SqlSugar、EntityFrameworkCore、StackExchange.Redis 或任何业务领域模型；
• 不依赖 MCP SDK，可与任意 IChatClient、AIAgent 或进程内/远程工具源组合。

设计边界

本包负责的能力

• 数据合规与模型路由（AIModelRoutePolicy）：三级数据分类（Public / Business / Sensitive）与三类部署区域（OnPrem / CloudCN / CloudOverseas），折叠提供商与模型两层配置，强制执行高敏数据仅驻留 OnPrem、显式指定不合格直拒（不静默换模型）、无合格模型降级限权（MaxMountableLevel）与函数调用能力门禁（MountTools）。
• 工具治理元数据目录（IAIToolCatalog + AIToolReflectionScanner）：五级工具风险（Read / Artifact / Draft / Commit / Destructive，审批严格依据风险等级而非 MCP ReadOnly 提示）、反射扫描器、按前缀或谓词批量规则，且 Sensitive 工具的 ExposeExternally 恒强制为 false。
• 七步受控工具执行管线（GuardedAIFunction）与并发安全工具集（AIConcurrentTurnToolCollection）：按固定顺序执行「数据等级闸 → 宿主授权 → 参数重写与规范化 → 风险审批拦截 → 内层调用与异常收敛 → 结果转换链 → 全量审计」，保证 OperationCanceledException 原样传播且绝不向模型暴露内部堆栈或路径。
• 围栏、预算与注入观测：UntrustedContentFence（防嵌套闭合标签与控制字符逃逸，同时提供工具输出 <tool_result> 围栏与客户端在场页面状态 WrapPageContext / EscapeAngleBrackets <page_context trust="untrusted-client-state"> 围栏）、ToolResultBudgetTransformer（JSON 感知的数组截断与单轮累计字符预算）、IPromptInjectionSignalDetector（仅通过 System.Diagnostics.Metrics 与脱敏日志上报信号，不阻塞请求、不落原文）以及系统提示词安全常量 AIGuardrailPrompts。
• 持久化待办动作协议（IAIPendingActionService）：服务端持有待办动作、规范化参数与 sha256: 哈希，用户点击批准后乐观并发抢占并确定性执行存储参数，绝不采用“重放对话 + 授权白名单”。
• 多维动态限流、高阶模型准入与软硬阈值防抖告警（IAIQuotaGuard v2）：在 100% 向下兼容二元 (tenantId, userId) 签名的基础上，支持 AIQuotaCheckContext（携带 ModelId、IsPremiumModel、UserRoles）、按租户动态策略端口 IAIQuotaPolicyProvider（支持应急总闸 IsEnabled、用户/角色精确豁免、受限角色禁调高阶模型 BlockPremiumModelsForRoles、软阈值百分比与 DayBoundaryOffset 切日偏移）、实时水位查询 GetWatermarksAsync 以及感知 TimeProvider 的有界窗口告警防抖器 AIQuotaAlertDebouncer + IAIQuotaAlertSink。上下文重载为默认接口方法：自定义实现未覆写且上下文携带 IsPremiumModel 或 UserRoles 治理维度时将显式抛出 NotSupportedException，绝不静默放行。
• 端口契约测试基类（Bitzsoft.Integrations.AI.Testing）：位于独立测试包 Bitzsoft.Integrations.AI.Testing 的无测试框架锁定基类 AIPendingActionStoreContractTestsBase 与 AIUsageCounterStoreContractTestsBase，供宿主测试项目验证自身数据库或 Redis 实现。
• 多租户凭据静态加密（IAiCredentialCipher / AesGcmAiCredentialCipher）：基于 HKDF-SHA256(masterKey, info: tenantId ?? "0") 派生租户隔离密钥与 AES-256-GCM（Nonce[12] + Tag[16] + Ciphertext）认证加密；默认输出 v1: 版本前缀消除高熵明文误判，解密同时向下兼容 BitzOrcas 存量无前缀密文，且启动期强制校验主密钥配置（连接器内严禁硬编码默认开发密钥）。
• 服务端确定性十进制聚合引擎（AIDataAggregationEngine）：面向只读分页与列表工具提供自动翻页拉取（上限 200 条/页、最多 100 页 / 20,000 行）、SHA-256 跨页重复内容断路器、内存后置过滤、时间分桶（year/quarter/month/day）与原生 decimal 精确聚合（count/sum/avg/min/max/distinct_count），彻底消除大模型心算财务与业务大表时的算术幻觉。
• 敏感身份入参剥离、会话实体锁参内核与架构感知装饰器（AIIdentityArgumentSanitizer + AIEntityArgumentLocker + AIEntityLockedAIFunction）：递归剥离工具参数字典与反射请求对象树中的 TenantId、IsDeleted、CreateBy、WhereInputs、IsExportRequest 等高危伪造字段，强制夹逼分页参数；AIEntityLockedAIFunction 进一步基于 AIFunction.JsonSchema 自动探查顶层与嵌套请求包装器（input.* / request.* / query.*）的字段及数组形态，支持主实体与级联从属实体（SecondaryBindings）同步覆写、自由过滤入参剔除、工具白名单裁剪及 AIFunctionArguments.Services/Context 无损透传，杜绝提示词注入跨单据越权。
• 渐进式工具发现、中英混合分词评分器与三大元工具（AIToolCatalogSearchScorer + AIProgressiveToolDiscovery）：针对拥有百余个业务工具的宿主，内置零外部依赖的中文连续双字切块（CJK Bigram）+ 英文驼峰/下划线切词器、可配置领域同义词字典与多字段加权评分器，并提供一键生成 tool_search、tool_invoke、data_aggregate 三大标准 AIFunction 元工具的工厂，支持命中工具自动注入当轮 AIConcurrentTurnToolCollection、防元工具递归自调用死循环以及向 AIToolCatalogOptions 批量登记治理描述符。
• 内置正则出站脱敏与 Fail-Closed 数据驻留守卫（RegexAIOutboundRedactor + AIOutboundRedactionOptions）：基于源生成正则表达式对 18/15 位身份证号、银行卡号（含 4 位分组）、手机号、邮箱与 Bearer/JWT/API 密钥执行零反射 PII 与秘钥脱敏；严格依据 AIDataResidencyPolicy 及 AITenantSolutionManifest 执行区域拦截，支持 Fail-Closed 抛出 AI.OutboundRedactedBlocked。
• FDE 试运行演练模式（AIToolPipelineOptions.DryRunMode / AIToolDryRunPreview）：通过 AIToolPipelineOptions、AIToolExecutionPropertyKeys.DryRunMode 或租户清单启用试运行演练后，写操作工具（Commit / Destructive）在完成数据等级闸、鉴权与参数重写后即安全拦截，生成经 AIGovernanceJsonContext 认证的 Native AOT 安全预览回执并落盘 AIToolAuditOutcome.DryRun 审计，绝不触发底层副作用或创建待办动作。
• 人机协同审批挂起与恢复检查点（IAIHitlApprovalCoordinator / DefaultAIHitlApprovalCoordinator + IAIHitlCheckpointStore）：无缝衔接 IAIPendingActionService，支持挂起断点持久化（AIHitlCheckpointState）、参数防篡改哈希与跨用户隔离验证恢复、主动取消与过期终止。
• 纪元缓存配额策略解析与 Fail-Closed 守卫（IAIQuotaPolicyResolver / EpochCachedAIQuotaPolicyResolver + AIEpochSingleFlightCache<TPayload>）：基于 IAICacheEpochCoordinator 实现 L1/L2 多级纪元缓存与单航班并发防击穿合并，支持未失效 LKG 降级兜底并在显式失效或无可用快照时抛出 GovernanceUnavailable（HTTP 503）严格拒发。
• 治理与脱敏异常统一映射器（AIGovernanceExceptionMapper）：将工具结构化拒绝、配额与高阶模型超限、待办审批结果、出站驻留阻断及上游模型异常经秘钥/路径清洗后统一映射为标准化 AIDomainException。

不在本包内的职责

• 数据库表结构、ORM 仓储实现与分布式 Redis 脚本（由宿主实现端口）；
• 角色权限（RBAC）、租户黑名单与业务实体上下文（如案件 ID、账单 ID）锁参规则；
• PII 展示脱敏规则（宿主实现 IAIToolResultTransformer 并按 Order = 100 插入）；
• 敏感词令牌化、模型输出内容合规扫描、PAT 数据等级上限与 RAG 检索接线；
• 主密钥托管来源本身（由宿主通过环境变量、KMS 或配置中心注入 AiCredentialCipherOptions.MasterKey 或自定义 IAiCredentialKeyProvider）。

与 Bitzsoft.Integrations.AgentFramework 的关系

Bitzsoft.Integrations.AgentFramework 默认启用微软官方 ToolApprovalAgent 中间件处理单次 AgentSession 会话内的交互式工具审批队列；而本包的 GuardedAIFunction + IAIPendingActionService + IAIPendingActionStore 负责跨 HTTP 请求、跨端（Web 工作台、钉钉/飞书卡片、移动端审批中心）、可持久化审计且带参数 SHA-256 防篡改复核的确定性待办动作。

两者职责互补，不得互相替代：

• 纯会话内即时确认可继续使用 AgentFramework 的 ToolApprovalAgent；
• 涉及跨通道异步审批、业务实体预览卡片、过期自动回收或“服务端落库锁参后单次确定性执行”的高风险写操作（Commit / Destructive），应在工具外层包裹 GuardedAIFunction 并接入宿主持久化的 IAIPendingActionStore。

结果转换器固定执行顺序

GuardedAIFunction 第 6 步严格按 IAIToolResultTransformer.Order 升序执行所有已注册转换器（常量定义于 AIToolResultTransformOrders）：

宿主端口清单与双 ORM（SqlSugar / EF Core）实现走查

AddBitzsoftAIGovernance() 将依赖外部存储的编排服务（IAIPendingActionService、IAIQuotaGuard）注册为延迟工厂 Transient，因此无论宿主将 Store 注册为 Singleton（Redis / 内存）还是 Scoped（EF Core DbContext / 请求级单元），均不会发生 Scoped 捕获异常；只读宿主即使开启 ValidateOnBuild = true 且不注册 Store 也能正常启动。

IAIPendingActionStore 双宿主实现要点

1. 去重语义（CreateOrGetExistingAsync）：查询条件为 TenantId == candidate.TenantId && UserId == candidate.UserId && SessionId == candidate.SessionId && ToolName == candidate.ToolName && ArgumentsHash == candidate.ArgumentsHash && Status == Pending && ExpiresAt > now（严禁跨用户复用待办记录）。建议在表上建立 (TenantId, UserId, SessionId, ToolName, ArgumentsHash) 复合索引；并发插入撞唯一约束时回查既有 Pending 记录返回 CreatedNew: false。
2. 乐观并发抢占（TryTransitionAsync）：严禁“先查实体再无条件 Save”，必须由数据库执行单条带条件原子更新并判断受影响行数是否为 1：
   • SqlSugar 宿主（如 BitzOrcas）：使用 db.CopyNew() 避免跨异步并发共享连接状态，且对未变更的可选载荷列保留原值（或按非空条件更新）：

     int rows = await db.CopyNew().Updateable<AiPendingActionEntity>()
         .SetColumns(x => x.Status == (int)update.NextStatus)
         .SetColumns(x => x.Version == expectedVersion + 1)
         .SetColumnsIF(update.DecidedBy != null, x => x.DecidedBy == update.DecidedBy)
         .SetColumnsIF(update.DecidedAt != null, x => x.DecidedAt == update.DecidedAt)
         .SetColumnsIF(update.ResultJson != null, x => x.ResultJson == update.ResultJson)
         .SetColumnsIF(update.ErrorCode != null, x => x.ErrorCode == update.ErrorCode)
         .Where(x => x.TenantId == tenantId
                  && x.Id == id
                  && x.Status == (int)expectedStatus
                  && x.Version == expectedVersion)
         .ExecuteCommandAsync(ct);
     return rows == 1;
     

   • EF Core 宿主（如 BitzOrcasVNext）：读取统一加 .AsNoTracking() 防止跟踪缓存返回过期快照；状态转移直接使用 EF Core 8+ ExecuteUpdateAsync 生成原子条件 SQL（对为空的可选属性保留原列值）：

     int rows = await dbContext.AiPendingActions
         .Where(x => x.TenantId == tenantId
                  && x.Id == id
                  && x.Status == expectedStatus
                  && x.Version == expectedVersion)
         .ExecuteUpdateAsync(setters => setters
             .SetProperty(x => x.Status, update.NextStatus)
             .SetProperty(x => x.DecidedBy, x => update.DecidedBy ?? x.DecidedBy)
             .SetProperty(x => x.DecidedAt, x => update.DecidedAt ?? x.DecidedAt)
             .SetProperty(x => x.ResultJson, x => update.ResultJson ?? x.ResultJson)
             .SetProperty(x => x.ErrorCode, x => update.ErrorCode ?? x.ErrorCode)
             .SetProperty(x => x.Version, expectedVersion + 1), ct);
     return rows == 1;
     

IAIUsageCounterStore 生产实现要点

• Redis 宿主：使用单段 Lua 脚本在一次 RTT 内执行 local v = redis.call('INCRBY', KEYS[1], ARGV[1]); if v == tonumber(ARGV[1]) then redis.call('PEXPIRE', KEYS[1], ARGV[2]); end; return v;，保证窗口首次创建与过期时间绑定原子完成。
• 关系库宿主（无 Redis 环境）：按 (CounterKey) 主键建轻量计数表，若当前行 ExpiresAt <= now 则重置为 amount 与 now + window，否则原子 Value = Value + amount（PostgreSQL INSERT ... ON CONFLICT DO UPDATE / MySQL ON DUPLICATE KEY UPDATE / SQL Server MERGE）。

继承端口契约测试套件

宿主测试项目安装 Bitzsoft.Integrations.AI.Testing 后，可直接继承 Bitzsoft.Integrations.AI.Testing 中的无框架基类，自动覆盖去重、跨租户与跨用户隔离、16 路并发抢占仅执行一次、过期批量置位与窗口翻转：

using Bitzsoft.Integrations.AI.Governance;
using Bitzsoft.Integrations.AI.Testing;
using Xunit;

public sealed class SqlSugarPendingActionStoreContractTests : AIPendingActionStoreContractTestsBase
{
    private readonly FakeTimeProvider _clock = new(DateTimeOffset.UtcNow);

    protected override TimeProvider Clock => _clock;

    protected override IAIPendingActionStore CreateStore(TimeProvider timeProvider)
        => new SqlSugarPendingActionStore(TestDbFactory.Create(), timeProvider);

    protected override void AdvanceTime(TimeSpan delta) => _clock.Advance(delta);

    [Fact]
    public Task ContractSuite_PassesAllAssertions() => RunAllContractAssertionsAsync();
}

完整最小示例

以下示例在单进程内完整串联模型合规路由、工具元数据目录、GuardedAIFunction 写操作拦截与待办动作批准执行：

using System.Text.Json;
using Bitzsoft.Integrations.AI.Governance;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddLogging();

// 1. 注册治理核心与开发/测试用进程内参考存储（生产环境替换为数据库与 Redis 端口实现）。
services.AddBitzsoftAIGovernance(
    configureCatalog: catalog =>
    {
        catalog.PublicToolNames.Add("exchange_rate_query");
        catalog.ToolOverrides["invoice_issue"] = new AIToolDescriptor(
            name: "invoice_issue",
            risk: AIToolRiskLevel.Commit,
            dataLevel: AIDataLevel.Business,
            exposeExternally: false);
    },
    configureQuota: quota =>
    {
        quota.RequestsPerMinutePerUser = 30;
        quota.TokensPerDayPerTenant = 2_000_000;
    });
services.AddInMemoryBitzsoftAIGovernanceStores();

// 2. 注册获批待办动作的确定性执行器：读取持久化的规范化参数并跳过审批闸重新执行。
AIFunction rawIssueInvoice = AIFunctionFactory.Create(
    (string customerCode, decimal amount) => new { invoiceNo = "INV-20261107-001", customerCode, amount },
    "invoice_issue",
    "开具增值税电子发票");

services.AddScoped<IAIPendingActionExecutor>(sp => new DemoInvoicePendingActionExecutor(rawIssueInvoice, sp));

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

// 3. 模型路由：根据对话所需数据等级从候选模型中确定性选型。
AIModelRouteDescriptor[] candidates =
[
    new("deepseek-cn", "deepseek-flash", AIModelZone.CloudCN, AIDataLevel.Business, SupportsFunctionCalling: true, IsDefault: true, SortOrder: 10),
    new("local-vllm", "qwen2.5-72b", AIModelZone.OnPrem, AIDataLevel.Sensitive, SupportsFunctionCalling: true, IsDefault: false, SortOrder: 20),
];

AIModelRouteDecision route = AIModelRoutePolicy.Select(
    candidates,
    new AIModelRouteRequest(RequiredLevel: AIDataLevel.Business, RequiresTools: true));

using var scope = provider.CreateScope();
var contextAccessor = scope.ServiceProvider.GetRequiredService<IAIToolExecutionContextAccessor>();
var quotaGuard = scope.ServiceProvider.GetRequiredService<IAIQuotaGuard>();
var pendingService = scope.ServiceProvider.GetRequiredService<IAIPendingActionService>();

var quotaCheck = await quotaGuard.CheckAsync("tenant-demo", "user-01");
if (!quotaCheck.Allowed)
{
    return;
}

using (contextAccessor.Push(new AIToolExecutionContext(
    TenantId: "tenant-demo",
    UserId: "user-01",
    SessionId: "session-1001",
    RequestId: "req-001",
    Channel: "web",
    CurrentModel: route.SelectedModel)))
{
    // 4. 模型首次调用 Commit 级工具：管线自动拦截并生成待办回执，底层业务函数不会执行。
    var guardedInvoiceTool = GuardedAIFunction.Wrap(rawIssueInvoice, scope.ServiceProvider);
    var firstAttempt = await guardedInvoiceTool.InvokeAsync(new AIFunctionArguments
    {
        ["customerCode"] = "CUST-88",
        ["amount"] = 12800.50m,
    });

    if (firstAttempt is AIPendingActionReceipt receipt)
    {
        var saved = await pendingService.GetAsync("tenant-demo", "user-01", receipt.ActionId);

        // 5. 用户在前端卡片核对预览后点击“批准”：校验参数哈希并单次确定性执行。
        var decision = await pendingService.DecideAsync(
            tenantId: "tenant-demo",
            userId: "user-01",
            actionId: receipt.ActionId,
            decision: AIPendingActionDecision.Approve,
            argumentsHash: saved?.ArgumentsHash);

        Console.WriteLine($"路由模型：{route.SelectedModel?.ModelKey}，审批结果：{decision.Outcome}");
    }
}

sealed class DemoInvoicePendingActionExecutor(AIFunction innerTool, IServiceProvider services) : IAIPendingActionExecutor
{
    public async ValueTask<AIPendingActionExecutionResult> ExecuteAsync(
        AIPendingAction action,
        AIToolExecutionContext context,
        CancellationToken ct = default)
    {
        var storedArgs = JsonSerializer.Deserialize<Dictionary<string, object?>>(action.ArgumentsJson)
            ?? new Dictionary<string, object?>();
        var replayTool = GuardedAIFunction.Wrap(innerTool, services, explicitContext: context, bypassApprovalGate: true);
        var output = await replayTool.InvokeAsync(new AIFunctionArguments(storedArgs), ct);
        return new AIPendingActionExecutionResult(
            Succeeded: output is not AIToolStructuredError,
            ResultJson: JsonSerializer.Serialize(output));
    }
}