来源：https://framework.docs.xihanfun.com/changelog

# 更新日志 · XiHan Framework

本页记录 XiHan Framework 各版本中使用者可感知的变更，每条标注 **新增 / 修复 / 优化 / 调整 / 移除** 类别；仓库自身的 CI、测试工程与构建脚本不列入。

## v5.0.0-preview.2（2026-11-06）

::: warning 预览须知
- 这是预览版，安装要带 `--prerelease`；公开面多数标为 `Preview` 或 `Experimental`，正式版前仍可能调整
:::

### 宿主、协议与插件

- **修复** `invoke` 的字段选项按操作的请求 Schema 写成布尔、数字与数组，`--times 2` 进载荷是 `"times":2`；操作没有 Schema 时值仍是字符串（见[命令行](./guide/command-line)）

### 包

- **优化** 全部包的描述与 README 重写，NuGet 包恢复图标并附更新日志链接

## v5.0.0-preview.1（2026-11-05）

::: warning 预览须知
- 这是预览版，安装要带 `--prerelease`；公开面多数标为 `Preview` 或 `Experimental`，正式版前仍可能调整
:::

### 原语与内核

- **新增** 原语层 `Primitives`：`Result` / `Result<T>`、`Error` 与错误码文法、`Maybe<T>`、`TypedId`、`InvocationContext`、清单模型、`PipelineStage`、`LifecycleState`、`Stability` 与 `[ApiLevel]`，只增不改
- **新增** 内核 `Kernel`：`AddXiHan` + `UseFeature<T>()` 装配特性，按能力 ID 求解能力图谱，`XiHan:Providers:<能力 ID>` 或 `UseProvider` 选择 Provider，启动日志打印图谱与管道
- **新增** 十一个阶段的执行管道与内置中间件：截止时间、按操作 ID 的熔断 / 限流 / 并发上限（`XiHan:Kernel:Resilience`）、按 JSON Schema 与 `IValidatableObject` 的契约校验
- **新增** 操作契约与调用器：`[Operation]`、`IOperation<TRequest, TResponse>`、`OperationRegistry`、`IOperationInvoker`；`Kernel.Generators` 生成登记代码与请求 / 响应 JSON Schema（`XHG001`–`XHG006`），程序集级 `OperationDefaults` 与只读声明
- **新增** 九态生命周期、`/health/startup|ready|live` 探针、`IHealthContributor` 与周期探测的 `PeriodicHealthContributor`，健康条目带说明、检查时刻、耗时与标量数据
- **新增** 资源绑定（`XiHan:Bindings`、`SERVICE_BINDING_ROOT`）与配置目录 `XIHAN_CONFIG_PATH` 热更新
- **新增** `IInvocationAccessor` 与调用来源 `InvocationOrigin`（协议、请求目标、远端地址、User-Agent、端点路由与名字）
- **新增** 分析器 `Kernel.Analyzers`（XH0001–XH0005）与测试基座 `Testing`
- **新增** `OutboundAddressPolicy.ConnectAsync(host, port, ct)`：不是 HTTP 但地址来自用户的连接（SMTP）用同样的规则，返回连好的 `Socket`
- **修复** `MapXiHanBlobs` 的响应带 `X-Content-Type-Options: nosniff`，写出内容时除 PDF 外带沙箱的 `Content-Security-Policy`，用户上传的 HTML、SVG 不能在应用的源上运行脚本
- **修复** 载荷解码错误的 `reason` 只写 JSON 路径，不再把请求类型的全名回给调用方
- **修复** SqlSugar 的数据库健康项与运行时数据源探测走一次数据库往返并按配置超时：连接池里有空闲连接时不再在库宕了之后报健康，服务器不回话时不再卡住启动；`persistence.sqlsugar.database` 的错误码由 `PERSISTENCE_UNAVAILABLE_003` 变成 `KERNEL_UNAVAILABLE_005`；`TestAsync` 单次上限是运行时数据源的 `HealthProbeIntervalSeconds`
- **修复** 配了从库时授予与租户目录读主库，撤销授予、停用租户的生效时间不再多出复制延迟；新增 `UnitOfWorkOptions.ReadsPrimary`
- **调整** HTTP、gRPC、MCP 入站丢弃 Baggage 里的 `xihan.tenant` 与 `xihan.principal`，这些调用方的租户只来自认证（CloudEvents 入站不变，端点权限由宿主自己加）；要按主机名或请求头选租户时登记自己的 `ITenantResolver`
- **新增** 出站地址策略 `OutboundAddressPolicy`：工作流 `Http` 活动、CloudEvents Webhook 与 S3 命名实例缺省只能连公网地址，连接时按实际 IP 判定；连本机或内网要在 `XiHan:Security:Outbound` 放行，本地开发写 `AllowLoopback: true`（见[出站地址策略](./guide/outbound)）

### 子系统

- **新增** 本地化：消息键与 `key.L()`、每种语言一个 `Localization/<区域>.json`、内置 10 种区域（默认 `en-US`）、宿主按 `Accept-Language` 翻译 Problem Details；`Localization.InMemory` 与 `Localization.Database`
- **新增** 领域模型 `Domain`：实体协议接口、值对象、领域事件缓冲与规约
- **新增** 持久化：仓储、查询、工作单元与 Transaction 阶段、批量方法、雪花标识生成器；`Persistence.InMemory`、`Persistence.EntityFrameworkCore`、`Persistence.SqlSugar`（多库、分表、差异日志）与 `Persistence.Generators`
- **新增** SqlSugar 读写分离：只读工作单元读从库，其余读写走主库；从库权重归一化与周期探测，不可读的自动摘除、全部不可读时读回到主库，健康项 `persistence.sqlsugar.replicas`（见[持久化](./guide/persistence#读写分离)）
- **新增** 缓存：字节存储、类型化缓存、分布式锁、Idempotency 阶段、`IDistributedCache` 适配、键管理；`Caching.InMemory`、`Caching.Redis`、`Caching.Hybrid`、`Caching.Remote`（Experimental）
- **新增** 多租户：租户解析与 Tenant 阶段、租户分片与管道外的 `TenantShardScope`；`MultiTenancy.InMemory`、`MultiTenancy.Database`
- **新增** 安全：认证处理器与 Authenticate 阶段、权限与策略、RBAC 授予、权限收窄过滤器、授予来源、条件引擎、IP 归属地；`Security.InMemory`、`Security.Database`、`Security.Jwt`、`Security.OpenIdConnect`、`Security.Ip2Region`
- **新增** 消息：CloudEvents 信封、发布与订阅（竞争消费与每个实例都收到的广播订阅）、经管道的派发、重试与死信、事务性发件箱、领域事件到消息的登记；`Messaging.InMemory`、`Messaging.RabbitMQ`、`Messaging.Kafka`（流与按时刻重放）
- **新增** 对象存储：批量写入与删除、按前缀列举、范围读取、分片上传、预签名、命名存储实例；`ObjectStorage.FileSystem`、`ObjectStorage.S3`
- **新增** 调度：作业与触发器、间隔 / cron / 一次 / 手动计划、日历、misfire、集群分发与失联恢复、领导选举、重试与执行时限；`Scheduling.InMemory`、`Scheduling.Database`、`Scheduling.Kubernetes`
- **新增** 远程配置与密钥：`Configuration.Abstractions` 的配置源（轮询重载、失败保留最后一份）与 `Configuration.Nacos`
- **新增** 审计：Observe 阶段审计中间件与查询契约；`Auditing.InMemory`、`Auditing.Database`
- **新增** 可观测性：`Observability.OpenTelemetry` 导出追踪、指标与日志，`Observability.Host` 读取进程与主机运行信息
- **新增** 工作流：JSON 定义模型、定义目录、引擎、内置活动、用户任务、补偿与事件；`Workflow.InMemory`、`Workflow.Database`
- **新增** AI：基于 `Microsoft.Extensions.AI` 的 Provider 目录、`IAIChat`、护栏、操作桥接成模型工具、知识库流水线；`AI.OpenAI`、`AI.VectorData`
- **新增** 每个领域的一致性套件 `<领域>.Conformance`，默认实现与 Provider 通过同一套用例

### 宿主、协议与插件

- **新增** 宿主 `Hosting.AspNetCore`（请求桥接、探针、本地化的 Problem Details、绕过管道端点的 `XiHan` 认证方案）与 `Hosting.CommandLine`（`help` / `graph` / `pipeline` / `operations` / `invoke`，按错误 KIND 的退出码）
- **新增** 协议适配器 `Protocols.Http`（路由推导、OpenAPI 3.1 与权限扩展）、`Protocols.Grpc`（由 Schema 推出 protobuf、`/operations.proto`）、`Protocols.Mcp`（Streamable HTTP 与 stdio）、`Protocols.CloudEvents`（入站 `/events` 与出站 Webhook）
- **新增** 插件协议 `xihan.plugin.v1` 与三种宿主：`Plugins.InProcess`、`Plugins.OutOfProcess`、`Plugins.Wasm`（Experimental），黑盒套件 `Plugins.Conformance`
- **新增** 组合包 `Profiles.Minimal`、`Profiles.Standard`、`Profiles.Full`
- **新增** 命令行工具 `xihan`：`pack` 从 `xihan.app.json` 生成 Dockerfile、Kustomize、Compose 与 Aspire 产物，`graph` / `pipeline` / `operations` / `invoke` 转发给应用