框架定位
这一页回答一个问题：XiHan Framework 到底是什么，适合谁，又明确不做什么。读完它，你能判断自己的项目该不该用这个框架；要看它与同类框架的差别，再读为什么是曦寒。
一句话定位
XiHan Framework 是一套语言中立的应用框架规范（XiHan Spec）及其 .NET 参考实现，以「微内核、能力图谱、管道执行」为核心范式，通过能力包、插件、协议三条扩展轴组合能力，适用于 B2B SaaS、企业中后台、微服务与边缘服务。
这句话里的每个词都对应一组具体的工程约束，后面的章节逐一展开。这里先把三个关键词讲清楚：
| 关键词 | 含义 |
|---|---|
| 微内核 | 内核只定义宿主、能力图谱、执行管道、诊断、安全原语、操作契约与插件抽象，不含任何子系统实现；内核公开类型有预算上限，第三方依赖为零 |
| 能力图谱 | 每个特性在清单里按能力 ID 声明「我提供什么、我依赖什么」，内核在启动前求解整张图，缺失、循环、版本冲突与多候选都在启动期报错 |
| 管道执行 | 每次调用都经过固定十一个阶段的管道，认证、租户、授权、校验、幂等、事务是各阶段里的中间件，顺序确定、可打印、可测试 |
三层定位
框架在三个层面各有一个定位，对标的参照物也不同：
| 层 | 定位 | 对标参照 |
|---|---|---|
| 原语与内核 | 十年不变的原语层，加大版本内稳定的微内核 | Linux 系统调用 ABI、Rust 的 core、XNU 微内核 |
| 子系统能力 | 通用企业能力标准化：持久化、缓存、消息、安全、多租户、调度、工作流等，每个都是「抽象 + 默认实现 + Provider」 | Dapr Building Blocks、Android Treble |
| 协议与工具链 | 一份操作契约多协议暴露（HTTP、gRPC、MCP、命令行），打包与编排，分析器与生成器 | FastAPI、ASGI、OCI、Service Binding |
原语层只增不改；内核在大版本内不破坏；子系统之上各自演进，通过同一套一致性测试即视为兼容。这就是我在设计哲学里讲的「三易」。
适用场景
| 场景 | 特征 | 框架给什么 |
|---|---|---|
| 多租户 SaaS 平台 | 租户隔离、数据分片、订阅计划 | Tenant 阶段解析租户，持久化层自动过滤，按租户分片选连接 |
| 企业后台管理系统 | 复杂权限、审批流、组织架构 | RBAC 授予、条件引擎、工作流引擎、审计 |
| 行业垂直应用 | CRM、ERP、WMS、HRM 等定制 | 能力包组织业务模块，默认实现让开发期不依赖外部设施 |
| 微服务后端 | 每个服务只装所需能力 | Minimal 组合起步，远程能力经协议接入 |
| 开放 API 与 AI 工具平台 | 同一业务同时暴露为 REST、gRPC、MCP tool | 操作契约一次声明，协议适配器各自翻译 |
| 边缘与轻量服务 | 冷启动敏感、资源受限 | Minimal 组合 + Native AOT 发布 |
| 插件化平台 | 第三方扩展、任意语言、崩溃不拖垮宿主 | 进程内、Wasm、进程外三级隔离的插件宿主 |
不是什么
明确说「不是」比说「是」更能帮你选型：
| 不是 | 原因 |
|---|---|
| 不是 ABP 的替代品或分支 | 架构哲学不同：特性组合与管道阶段，而不是强制模块基类与生命周期钩子 |
| 不是 Spring Boot 的 .NET 移植 | .NET 有自己的最佳实践：Generic Host、源生成器、Native AOT |
| 不是微服务框架 | 不绑定部署形态，单体、模块化单体、微服务都可以 |
| 不是 Sidecar 平台 | 能力在进程内组合，远程能力只是可选的 Provider |
| 不是低代码平台 | 面向开发者，不面向拖拽配置 |
| 不是 ORM | 持久化走端口与 Provider，EF Core 与 SqlSugar 各有适配包 |
| 不是 UI 组件库 | 前后端分离，前端由 XiHan.UI 独立演进 |
是什么
| 是 | 具体含义 |
|---|---|
| 规范与参考实现 | XiHan Spec 定义原语、清单、上下文、管道、插件协议与协议映射；.NET 是参考实现，其他语言按规范实现并通过同一套一致性向量 |
| 开发效率基础设施 | 企业级通用能力开箱即用，每个抽象都有零外部依赖的默认实现 |
| 架构共识载体 | 统一的环层、依赖方向、术语表、命名文法与代码规范，由架构测试与分析器执行 |
| 能力集成平台 | 能力图谱协调多技术栈，而不是基类继承绑定 |
| 质量保障体系 | 内置可观测性、审计、错误模型、API 稳定性分级与一致性测试 |
| 可扩展宿主 | 微内核 + 能力包 + 插件 + 协议，按需组合，渐进增长 |
版本与兼容
- 全部包共享一条版本线，大版本每三年一次并对齐一个 .NET LTS，小版本约每六个月，补丁随时。
- 公开类型都带稳定性标记：
Stable、Preview、Experimental、Internal、Deprecated。原语层在Stable之上再加「冻结」承诺。 - 破坏性变更走三阶段弃用：先标
Deprecated并给出迁移说明，至少保留两个小版本；下一个大版本前升级为编译错误；大版本移除并提供代码修复。 - 当前是预览版，公开面多数标为
Preview或Experimental，正式版前仍可能调整。
与 BasicApp 的关系
XiHan.BasicApp 是基于本框架的参考应用，覆盖 SaaS 管理、组织架构、权限管理等业务场景，用能力包与操作契约实现。框架正式版的门槛之一，就是 BasicApp 全量跑在框架上。它同时是新项目的起点模板。