版本与升级指引

Known 当前版本 4.0.0，目标框架 .NET 10（TFM net10.0，桌面为 net10.0-windows），NuGet 包依赖统一锁 10.*。本页说清版本号怎么读、什么算破坏性变更、以及把项目升到新版本时该走一遍的检查清单。完整的历史交付见更新日志，趋势见路线图。

版本号约定

采用语义化版本 主.次.修订：

• 主版本（如 3.x → 4.0）：可能含破坏性变更——公开签名删除或改义、必需装配步骤变化、默认行为反转。升级前务必对照从旧版本迁移。
• 次版本（如 4.0 → 4.1）：向后兼容地新增能力（新组件、新扩展点、新可选项）。老代码不改也能编过。
• 修订号（如 4.0.0 → 4.0.1）：缺陷修复与内部重构，不动公开契约。

一个实际经验：框架以源码 / 项目引用形态随你的解决方案走（开源仓库里各工程 ProjectReference 到 Known/Known.csproj），不是从 NuGet 拉定版二进制。所以"升级"通常是拉取上游更新后重编，破坏性变更会在编译期直接暴露——这是好事，改没改干净编译器替你把关。

什么算破坏性变更

Known 对破坏性变更格外谨慎，尤其守住一条数据红线：EnsureSchemaAsync 做的自动建表 / 增列是非破坏性的——它只会新增表、新增列，绝不会删列、改列类型或清空数据。任何可能损坏既有库的 schema 变更都必须走显式迁移、由你手动确认，不会藏在一次启动里悄悄发生。

其余常见破坏面包括：AddKnown 家族的签名或调用顺序要求变化、IAuthProvider 契约新增必须实现的成员、BaseComponent 公共参数语义调整、以及 Config.* 装配门面的方法重命名。这些都会在主版本里集中发生，并配套迁移说明。

升级前检查清单

1. 先备份，或在版本控制干净的工作区上操作（git status 无未提交改动），方便 diff 与回滚。
2. 通读目标版本的更新日志 / 迁移说明，标出涉及你用到 API 的条目。
3. 对齐宿主 TFM 与包版本：net10.0 / net10.0-windows，包引用 10.*；确认本地已装对应 .NET SDK。
4. 升级 Known 引用（更新被引用的框架程序集），全解决方案重编，把编译错误当作"待办清单"逐条修，别硬压。
5. 守住零警告：以 Release 配置构建，目标是 0 error / 0 warning；历史遗留警告先记录基线数量，只关注"新增的"那几条。
6. 跑一遍集成/冒烟测试：至少把三种运行形态各起一次（WASM、Web、桌面），走核心增删改查与登录闭环。
7. 确认数据层无碍：启动时 EnsureSchemaAsync 只做增列；核对 schema.Warnings 有无告警，业务表数据应原样保留。
8. 回归界面偏好与词条：主题 / 语言 / 密度切换正常；主版本若动过语言包格式，按国际化核对你的 {tag}.json。

升级后

改动的装配入口、覆写的鉴权方法、用到的服务，都对照API 一览与全表再确认一遍签名。若你之前踩到过从某版本升上来的具体坑，欢迎按从旧版本迁移的格式补充，让升级路径越走越平。