来源：https://framework.docs.xihanfun.com/appendix/milestones

# 发展大事记

这一页按时间讲 XiHan Framework 是怎么走到今天的：从一个给自己项目用的基础库，到四个大版本的全家桶式框架，再到 2026 年秋天推倒重来的 5.0。写它的目的不是怀旧，而是让你知道当前这套设计是从哪些教训里长出来的。完整的版本变更见[更新日志](/changelog)。

## 2024 年：建仓

2024 年 8 月我建了这个仓库。最初只有一个解决方案骨架和一个基础库，目的很单纯：把我在业务项目里反复写的工具方法、扩展方法、序列化与日志封装收拢到一处，让曦寒懿生态下的几个应用共用一份代码。那时它还谈不上框架，只是「我的公共库」。

## 2025 年：1.x，从工具库长成框架

| 时间 | 事件 |
| --- | --- |
| 2025 年 8 月 | 发布 1.0.0-alpha。重构工具库，重写序列化器，整理模块命名；恢复机器人、脚本、虚拟文件系统等包 |
| 2025 年 9 月 | 1.1 到 1.3：初始化 Domain 与 Data 两个包，实体与仓储成形；加入命令行、后台服务、计划任务、高性能文件日志、gRPC 支持 |
| 2025 年 10 月 | 1.4：加入动态 WebAPI，应用服务直接变成接口；仓储、分页、审计字段统一 |
| 2025 年 11 月 | 1.4.5：分布式 ID 生成库成形，命名空间整理 |

这一年的路线很像所有「全家桶」框架走过的路：业务里缺什么就往框架里加什么。好处是开发速度快，坏处是包之间的依赖越来越像一张网。

## 2026 年上半年：2.x 与 3.x，能力补齐

| 时间 | 事件 |
| --- | --- |
| 2026 年 1 月 | 发布 2.0.0。认证授权、数据库初始化与种子数据、基于 SignalR 的实时通信、流量治理、可观测性、对象存储（本地、阿里云 OSS、腾讯云 COS、MinIO）一起进来 |
| 2026 年 2 月 | 2.2：多租户实体基类、租户数据隔离与解析透传、通用响应信封 |
| 2026 年 3 月到 5 月 | 2.3 到 2.5：分页、种子、租户字段、OpenAPI 标签等持续打磨 |
| 2026 年 6 月 | 发布 3.0.0。国际化机制（请求文化中间件、可本地化异常、响应本地化）、异常统一输出、分布式锁与延迟队列 |
| 2026 年 7 月 | 3.x 密集迭代：AI 子系统分五个里程碑落地（OpenAI 兼容 Provider、嵌入与 RAG、Agent 与技能注册、护栏与遥测）；RabbitMQ、Kafka、Redis 三种事件总线 Broker；后台作业管理器；会话状态闸门；行版本乐观锁；动态连接注册器；工作流引擎；MCP Server 端下沉到框架 |
| 2026 年 8 月 | 搜索引擎抽象与 Elasticsearch 实现；OpenID Connect 协议层；八家 OAuth 提供商全部自研，新增微信、企业微信、飞书、钉钉登录 |

到 3.14，框架已经覆盖了企业应用需要的大多数横切能力。也是在这个阶段，我开始感到不安：包的数量和它们之间的隐式依赖已经让「换一个实现」变得困难，很多能力靠基类和拦截器实现，运行期反射到处都是，Native AOT 几乎不可能。

## 2026 年 8 月到 10 月：4.x，收口与反思

| 时间 | 事件 |
| --- | --- |
| 2026 年 8 月 28 日 | 发布 4.0.0。整理命名空间与解决方案结构；库隔离租户按约定自带整套模块库 |
| 2026 年 9 月 | 平台成为 0 号租户，无租户上下文不再「看全部、写全部」；实体可声明固定落平台库；默认内存实现重命名并约束用途；MCP 工具暴露支持允许与拒绝清单 |
| 2026 年 10 月 | 4.7 与 4.8：命令行工具 `XiHan.Framework.Cli` 提供包、模块、配置节与文档的离线知识库；工作流按受理人规则解析审批人；权限判定带请求上下文并记录拒绝原因；可配置条件的求值器；IP 归属地抽象 |

4.x 是 1.x 到 3.x 这条路线的终点。它能用，也在生产里跑着，但我已经清楚地看到几件靠修修补补解决不了的事：

- 依赖写在模块特性和基类上，关系要到运行时才知道；换 ORM、换缓存要改业务代码。
- 横切逻辑散在拦截器、过滤器和基类虚方法里，顺序靠约定，没人能一眼说出一次请求经过了什么。
- 同一个业务要同时提供 REST、gRPC 与 MCP，得写三份胶水。
- 反射与动态代理让 Native AOT 和启动性能无从谈起。
- 命名随手取，`Core`、`Common`、`Manager` 满天飞，包名推不出它的职责。

## 2026 年 10 月：5.0，从零重写

2026 年 10 月 20 日前后，我决定不再在 4.x 上改，而是在一个独立分支上从零开始写第五代。先写方案，再定边界，再写代码。这次的顺序是：总体方案、架构定位与设计哲学、代码规范、功能扁平化定义、开发计划；然后把公共契约先写进语言中立的规范 XiHan Spec，每条决策落成一份架构决策记录；最后才是实现。

八项关键决策在重写第一天就定下来：所有包共享一条版本线；原语层与内核分包，原语层冻结；内核只做一个包；第二语言 Go 先行；持久化以 EF Core 优先；进程外 gRPC 插件协议进 5.0，Wasm 标实验；规范先放仓库内、公开时拆出；4.x 继续维护 24 个月。

之后的进度按门槛推进，不按日期排期：

| 时间 | 阶段 | 事件 |
| --- | --- | --- |
| 10 月 21 日 | P0 定边界 | 目录骨架、构建属性、CI 门禁、架构测试、规范草案（原语、清单、上下文、管道阶段、术语表）、首批架构决策 |
| 10 月 21 日 | P1 内核 | 原语层按规范落地；内核实现特性装配与生命周期状态机、能力图谱求解、阶段化管道、诊断薄桥、安全原语与插件抽象；ASP.NET Core 宿主、进程内插件宿主、测试基座、Roslyn 分析器、Native AOT 示例 |
| 10 月 21 日 | P2 子系统 | Domain 与持久化、缓存、消息、安全、多租户五个子系统的抽象、内存默认实现与一致性套件；EF Core、Redis、RabbitMQ、JWT 四个 Provider；Minimal 与 Standard 组合包；本地化模型定稿：文案不写在代码里，每种语言一个文件 |
| 10 月 22 日 | P3 协议与宿主 | 操作契约与调用器；源生成器产出登记代码与 JSON Schema；HTTP 适配器与 OpenAPI；MCP 适配器 |
| 10 月 23 日 | P3 收尾 | gRPC 与 CloudEvents 适配器；命令行宿主与 MCP stdio；对象存储、调度、远程配置、审计四个子系统；OpenTelemetry 导出；持久化生成器；`xihan pack`；Kubernetes 示例；Full 组合包；OpenID Connect Provider |
| 10 月 23 日 | P4 插件与跨语言 | 进程外插件协议 `xihan.plugin.v1` 进入规范；进程外插件宿主；Wasm 插件宿主与 Rust 示例；插件协议一致性套件；规范拆为独立仓库并公开；Go SDK 发布，Go 写的插件在 .NET 宿主里服务操作，Go 写的缓存经远程 Provider 通过一致性套件 |
| 10 月 23 日起 | P5 走向正式版 | 批量优先审查：所有对集合的操作都有一次调用完成的批量方法；SqlSugar Provider |
| 10 月 26 日 | P5 | 租户分片、`IDistributedCache` 适配、S3 对象存储；Kafka 流、两级缓存、Nacos 远程配置；调度子系统重做并加入数据库 Provider；工作流子系统与数据库 Provider；AI 子系统：以 `Microsoft.Extensions.AI` 为线格式，操作契约可直接成为模型工具 |
| 10 月 27 日到 31 日 | P5 | 十项能力补齐：SqlSugar 多库与分表、Validate 阶段契约校验、领域事件派发、多租户与安全与审计的数据库 Provider、Resilience 阶段、Provider 健康项、OpenAPI 权限扩展；雪花标识；OpenAPI 文案与分组；调用来源；条件引擎；IP 归属地；对象存储范围读取、分片上传、预签名与命名实例；绕过管道的端点认证；运行信息；作业重试与执行时限 |
| 11 月 4 日 | P5 | SqlSugar 读写分离与命令超时；出站地址策略；网络入站不接受自报的租户与主体 |
| 11 月 5 日 | 5.0.0-preview.1 | 开发分支切到 `dev`，第一个预览版发布到 nuget.org；4.x 转入维护 |
| 11 月 6 日 | 5.0.0-preview.2 | 全部包的描述与 README 重写，命令行字段选项按请求 Schema 写类型 |

## 现在

5.0 仍是预览版，公开面多数标为 `Preview` 或 `Experimental`。接下来的门槛是 BasicApp 全量跑在框架上、公开 API 审查与冻结、包验证基线与性能基准，然后发布 5.0.0 并声明 LTS。路线见[路线图](/appendix/roadmap)。

## 下一步

- [路线图](/appendix/roadmap)：每个阶段的退出条件与当前状态
- [框架定位](/appendix/positioning)：5.0 是什么、不是什么