包总览
XiHan Framework 由一组可以独立引用的 NuGet 包组成，按环层组织。本册是参考手册，每个包一页，列出它提供的能力、配置节、主要类型、限制与错误码；要完成某件事时先读开发指南。
先看指南还是先看这里
| 问题 | 去处 |
|---|---|
| 要做某件事：装配特性、写操作、接数据库、做授权、发消息 | 开发指南 |
| 某个包有什么：能力 ID、配置键、主要类型、AOT 与限制 | 本册 |
当前是预览版，全部包共享一条版本线，取得方式见快速上手。
命名规则
包 ID 由术语表与文法推出：XiHan.Framework.<领域>[.<角色>]。
| 后缀 | 角色 | 示例 |
|---|---|---|
.Abstractions | 抽象包：接口、契约、阶段中间件，零第三方依赖 | Caching.Abstractions |
| 机制名 | 默认实现：零外部设施、容量有界，清单角色为 default | Caching.InMemory、ObjectStorage.FileSystem |
.Database | 经持久化子系统的仓储读写的 Provider，数据库由应用选中的持久化 Provider 决定 | Security.Database |
| 技术名 | 接外部设施的 Provider | Caching.Redis、Persistence.EntityFrameworkCore |
.Conformance | 一致性套件：实现必须通过的 xUnit 测试 | Caching.Conformance |
.Generators / .Analyzers | 源生成器与分析器，开发期依赖 | Kernel.Generators |
默认是清单里的 role，不是包名：没有显式 Provider 时默认实现被选中，加入 Provider 后自动让位。
怎样选包
- 先选组合包：
Profiles.Minimal（内核、ASP.NET Core 宿主、内存本地化）、Profiles.Standard（再加持久化、缓存、多租户、安全、消息的内存默认实现）、Profiles.Full（再加对象存储、调度、审计、工作流、AI 工具目录、OpenTelemetry、运行信息与四种协议适配器）。 - 按对外暴露的方式加协议适配器：
Protocols.Http、Protocols.Grpc、Protocols.Mcp、Protocols.CloudEvents，或换成命令行宿主Hosting.CommandLine。 - 按生产环境的外部设施加 Provider：
Persistence.EntityFrameworkCore/Persistence.SqlSugar、Caching.Redis、Messaging.RabbitMQ/Messaging.Kafka、Security.Jwt/Security.OpenIdConnect、ObjectStorage.S3等，每个都要UseFeature加入。 - 开发期依赖：
Kernel.Generators（操作契约）与Persistence.Generators（仓储登记）。
Ring 0–1 原语与内核
| 包 | 说明 |
|---|---|
| Primitives | 原语与契约：Result、Error、Maybe、InvocationContext、清单模型、管道阶段、生命周期状态、消息键；只增不改 |
| Kernel | 微内核：应用构建、能力图谱、管道与内置中间件、操作契约与调用器、安全原语、健康、插件抽象 |
Ring 2 领域与抽象
| 包 | 说明 |
|---|---|
| Domain | 实体协议接口、值对象、领域事件缓冲、规约；纯契约 |
| Persistence.Abstractions | 仓储、查询、工作单元与 Transaction 阶段、标识生成、领域事件派发 |
| Caching.Abstractions | 字节存储、类型化缓存、序列化器、分布式锁、Idempotency 阶段、IDistributedCache 适配、键管理 |
| MultiTenancy.Abstractions | 租户信息与存储、租户解析器与 Tenant 阶段、租户分片 |
| Security.Abstractions | 凭据与认证处理器、权限与策略、RBAC 授予、Authenticate / Authorize 阶段、条件引擎、IP 归属地契约 |
| Messaging.Abstractions | CloudEvents 信封、发布与订阅、经管道的派发、发件箱、领域事件映射 |
| Localization.Abstractions | 区域、消息目录、显式区域的本地化接口 |
| ObjectStorage.Abstractions | 对象存储契约：批量写入与删除、按前缀列举、范围读取、分片上传、预签名 |
| Scheduling.Abstractions | 作业、触发器、计划、调度引擎与作业存储契约、领导选举 |
| Configuration.Abstractions | 远程配置与密钥契约、接入 IConfigurationBuilder 的配置源 |
| Auditing.Abstractions | Observe 阶段审计中间件、审计扩展与查询契约 |
| Observability.Abstractions | 进程与主机运行信息的契约 |
| Workflow.Abstractions | 工作流定义模型、目录、引擎、内置活动、用户任务、存储契约 |
| AI.Abstractions | 基于 Microsoft.Extensions.AI 的 Provider 目录、IAIChat、护栏、工具目录、知识库 |
Ring 3 默认实现与 Provider
| 领域 | 默认实现 | Provider |
|---|---|---|
| 持久化 | Persistence.InMemory | EntityFrameworkCore、SqlSugar |
| 缓存 | Caching.InMemory | Redis、Hybrid、Remote（Experimental） |
| 多租户 | MultiTenancy.InMemory | Database |
| 安全 | Security.InMemory | Database、Jwt、OpenIdConnect、Ip2Region |
| 消息 | Messaging.InMemory | RabbitMQ、Kafka |
| 本地化 | Localization.InMemory | Database |
| 对象存储 | ObjectStorage.FileSystem | S3 |
| 调度 | Scheduling.InMemory | Database、Kubernetes |
| 配置 | .NET 原生的文件与环境变量，无包 | Nacos |
| 审计 | Auditing.InMemory | Database |
| 可观测性 | Observability.Host（运行信息） | OpenTelemetry（导出） |
| 工作流 | Workflow.InMemory | Database |
| AI | 工具目录由 AI.Abstractions 的 AIToolsFeature 提供 | OpenAI、VectorData |
插件协议的 .NET 类型 Plugins.Protocol 也在 Ring 3，由各隔离级别的插件宿主共用。
Ring 4 宿主
| 包 | 说明 |
|---|---|
| Hosting.AspNetCore | HTTP 请求桥接进管道、Accept-Language 协商、探针端点、本地化的 Problem Details、XiHan 认证方案 |
| Hosting.CommandLine | 命令行宿主：help / graph / pipeline / operations / invoke，按错误 KIND 的退出码 |
Ring 5 协议与插件
| 包 | 说明 |
|---|---|
| Protocols.Http | 操作 ID 推导路由、载荷绑定、OpenAPI 3.1 |
| Protocols.Grpc | 操作成为一元方法，protobuf 由 JSON Schema 推出，发布 /operations.proto |
| Protocols.Mcp | 操作成为 MCP tool，Streamable HTTP 与 stdio 传输 |
| Protocols.CloudEvents | CloudEvents 1.0 HTTP 绑定：入站 /events 与出站 Webhook |
| Plugins.InProcess | 可收集 AssemblyLoadContext 的进程内插件宿主 |
| Plugins.OutOfProcess | 按 xihan.plugin.v1 启动与监视子进程的插件宿主，插件可用任意语言编写 |
| Plugins.Wasm | wasmtime 沙箱里的 Wasm 插件宿主（Experimental） |
Ring 6 组合包
| 包 | 内容 |
|---|---|
| Profiles.Minimal | Primitives + Kernel + Hosting.AspNetCore + Localization.InMemory，UseMinimalProfile() |
| Profiles.Standard | Minimal + Domain + 五个子系统的抽象与内存默认实现，UseStandardProfile() |
| Profiles.Full | Standard + 对象存储、调度、审计、工作流、AI 工具、OpenTelemetry、运行信息与四种协议适配器，UseFullProfile() |
工具链
| 包 | 说明 |
|---|---|
| Kernel.Generators | 源生成器：[Operation] → 登记代码与请求 / 响应 JSON Schema（XHG001–XHG006） |
| Kernel.Analyzers | Roslyn 分析器：ApiLevel、命名、Internal 引用、零反射 |
| Persistence.Generators | 源生成器：实体 → 仓储登记、EF Core 实体登记、软删除与租户过滤规约 |
| Cli | 命令行工具 xihan：pack 生成部署产物，转发 graph / pipeline / operations / invoke |
| Testing | 测试宿主、特性桩、清单与上下文构造 |
| Conformance | 各领域的一致性套件与插件协议黑盒套件 |
工具链包可以引用任何环；源生成器与分析器只在编译期运行，不进入应用的运行时依赖。