AI 域拥有一套自有的抽象栈，独立于其他功能域的三层包模式。它建立在 Microsoft.Extensions.AI 之上，为多租户 AI 调用、嵌入生成、检索增强和智能体编排提供统一入口。所有 AI 包仅目标 net8.0;net10.0。

架构总览

AI.Abstractions

包：Bitzsoft.Integrations.AI.Abstractions

共享契约层。定义 Provider Profile、模型能力标志、聊天/嵌入工厂和目录接口。

核心类型：

// Provider 能力描述
public sealed class AIProviderProfile
{
    public string ProfileId { get; }
    public string DisplayName { get; }
    public string Protocol { get; }            // "openai" / "anthropic"
    public Uri DefaultEndpoint { get; }        // 必须是 HTTPS 或 loopback
    public AIModelCapabilities Capabilities { get; }
    public IReadOnlyCollection<string> Limitations { get; }
}

// 工厂接口
public interface IAIChatClientFactory
{
    IChatClient CreateClient(AIChatClientCreationContext context);
}

public interface IAIEmbeddingGeneratorFactory
{
    IEmbeddingGenerator<string, Embedding<float>> CreateGenerator(...);
}

// 目录接口（按 ID 查找 Profile）
public interface IAIProviderProfileCatalog { ... }

AIModelCapabilities 是标志枚举，标注 Provider 已通过契约确认的模型能力：

[Flags]
public enum AIModelCapabilities
{
    None = 0,
    Chat = 1 << 0,              // 文本聊天
    Streaming = 1 << 1,         // 流式输出
    FunctionCalling = 1 << 2,   // 函数/工具调用
    StructuredOutput = 1 << 3,  // 结构化输出
    Vision = 1 << 4,            // 图像输入
    Reasoning = 1 << 5,         // 推理控制
    HostedTools = 1 << 6,       // Provider 托管工具
    RemoteMcp = 1 << 7,         // Provider 原生 MCP 工具
    Embeddings = 1 << 8,        // 文本向量嵌入
}

AI

包：Bitzsoft.Integrations.AI

通用接口封装层。内置 OpenAI 协议适配器，兼容 OpenAI / 智谱 / Kimi / 通义 / DeepSeek 五家。RequestLoggingChatClient 包装 M.E.AI 客户端，自动接入审计日志。

注册入口：

// ① 注册聊天客户端（默认或命名）
builder.Services.AddBitzChatClient(configure);
builder.Services.AddBitzChatClient("primary", configure);

// ② 注册嵌入生成器
builder.Services.AddBitzEmbeddingGenerator(configure);

// ③ 注册内置 Provider Profile
builder.Services.AddBitzAIProviderProfile(profile);

AI.Anthropic

包：Bitzsoft.Integrations.AI.Anthropic

Claude 原生 Messages API 适配器。不走 OpenAI 兼容层，直接调用 Anthropic Messages 端点，保留完整的 thinking、tool_use、stop_reason 语义。

SemanticKernel

包：Bitzsoft.Integrations.SemanticKernel

Scoped Semantic Kernel 插件兼容层。让基于 Semantic Kernel 编写的插件复用本库的安全 IChatClient，无需改造即可获得租户感知能力。

RAG

包：Bitzsoft.Integrations.RAG

检索增强生成。集成 Qdrant 向量数据库：

能力	说明
访问控制	租户/角色过滤，确保检索结果不越权
混合检索	向量 + 关键词，由 `HybridReranker` 重排
引用追踪	标注回答来源的文档片段
Prompt Injection 边界	检索内容与系统提示之间设防护边界

核心抽象：IKnowledgeStore（知识库存储）和 IRAGService（检索增强服务）。

AgentFramework

包：Bitzsoft.Integrations.AgentFramework

Microsoft Agent Framework 封装。提供：

工具审批：敏感工具调用需人工确认后才执行
租户会话持久化：IAgentSessionStore 接口，内置 InMemoryAgentSessionStore
并发协调：IAgentSessionCoordinator 确保同一会话的消息串行化，避免竞态

McpServer

包：Bitzsoft.Integrations.McpServer

安全的 MCP（Model Context Protocol）HTTP/stdio Client 与 Server。IMcpClientFactory 创建连接外部 MCP Server 的客户端；本库自身也可作为 MCP Server 暴露工具供其他 Agent 消费。

net8+ 限制

所有 AI 包仅目标 net8.0;net10.0。因为 Microsoft.Extensions.AI.Abstractions、Qdrant 客户端、Microsoft Agent Framework 和 MCP 协议 SDK 均要求 net8+。这是全库唯一被文档化的 TFM 例外。

注册示例

var builder = WebApplication.CreateBuilder(args);

// ① 注册聊天客户端（OpenAI 协议，指向智谱端点）
builder.Services.AddBitzChatClient(options =>
{
    options.Endpoint = new Uri("https://open.bigmodel.cn/api/paas/v4/");
    options.ApiKey = builder.Configuration["Zhipu:ApiKey"];
    options.ModelId = "glm-4";
});

// ② 注册嵌入生成器
builder.Services.AddBitzEmbeddingGenerator(options =>
{
    options.Endpoint = new Uri("https://open.bigmodel.cn/api/paas/v4/");
    options.ApiKey = builder.Configuration["Zhipu:ApiKey"];
    options.ModelId = "embedding-3";
});

// ③ RAG（接 Qdrant）
builder.Services.AddBitzRAG(builder.Configuration.GetSection("RAG"));

聊天客户端使用

public class ChatService(IAIChatClientFactory factory)
{
    public async Task<string> AskAsync(string tenantId, string question)
    {
        // ① 按租户上下文创建客户端
        var client = factory.CreateClient(new AIChatClientCreationContext
        {
            TenantId = tenantId,
        });

        var messages = new List<ChatMessage>
        {
            new(ChatRole.System, "你是企业知识助手，只回答公司内部文档相关的问题。"),
            new(ChatRole.User, question),
        };

        // ② 同步获取完整回复（RequestLoggingChatClient 自动审计）
        var response = await client.GetResponseAsync(messages);
        return response.Text;
    }
}

流式输出用 GetStreamingResponseAsync，调用前检查 AIProviderProfile.Capabilities 是否含 Streaming 标志。