Known · 元数据驱动的 .NET 全栈框架

新建应用时，仓库里现成的四个工程就是你的起步骨架。先记住一个分工：KnownApp 是你的"业务程序集"，KnownWasm / KnownWeb / KnownWin 是三种"运行形态"宿主——业务写一次，挂到哪个宿主就变成哪种形态的产品，razor 一行不改（原理见三种运行形态）。

各自是什么

工程	角色	SDK / TFM	引用谁	干什么
`KnownApp`	业务程序集（RCL）	Razor 类库	引用 `Known` 框架	放你的实体、`[Service]` 实现、页面 `@page`、`Login`/后台，并暴露 `AddKnownApp(AppType)` 装配封装
`KnownWasm`	纯前端宿主	`BlazorWebAssembly` / `net10.0`	引用 `KnownApp`	只 `AddKnownClient`，数据经 HTTP 打到外部 API；可离线 / PWA
`KnownWeb`	Server 一体宿主	`Web` / `net10.0`	引用 `KnownWasm`	一个 ASP.NET Core 进程：既 serve 那个 WASM 客户端，又 `AddKnownWeb` 挂接口 + SQLite + Cookie 登录
`KnownWin`	桌面宿主	`Razor` + `WinExe` / `net10.0-windows`	引用 `KnownApp`	`AddKnownDesktop` 把接口进程内直调，本地 SQLite，打原生 exe

注意 KnownWasm 引用的其实是 KnownApp，而 KnownWeb 引用的是 KnownWasm（一体托管里它同时是"前端工程"又是"被托管对象"）；KnownWin 直接引用 KnownApp。

怎么选

想要"一个 dotnet run、一条端口把前后端连库一起跑起来"（单体起步、内网、现场单机）→ 从 KnownWeb 起步。
前端要独立分发 / CDN / 离线，后端已有或另建 → 从 KnownWasm 起步，配一个独立 API。
要离线桌面壳、或调本地硬件（串口/打印/USB/本地文件）→ 从 KnownWin 起步。
无论选哪个宿主，你的业务代码都往 KnownApp 这个位置写（可改名为 MyApp）。

起步怎么做

拉取开源仓库，把最接近你目标的那个宿主工程复制一份、改成你的产品名。
复制 / 改名业务程序集（对标 KnownApp），在里面写实体（继承 EntityBase）、[Service] 实现、页面（带 @page 与 [Menu]）。
在业务程序集里写你自己的装配封装（对标 AddKnownApp，可叫 AddMyApp）：内部 AddKnown(...) → Config.AddModule(你的程序集) → 声明菜单分组。写法见应用装配。
宿主 Program.cs 只留两行：services.AddMyApp(AppType.xxx) + 对应形态入口。
业务程序集的 csproj 引用框架：<ProjectReference Include="..\Known\Known.csproj" />（框架 Known 是唯一 RCL，其余都经它拿到组件与 web.css/web.js）。

各宿主的关键文件

一个最小宿主通常就这几处，照着抄最快：

Program.cs：唯一的装配差异都在这（WASM 用 builder.RootComponents.Add<App>("#app")；Server 用 WebApplication + AddApplication/UseApplication；桌面手动 new ServiceCollection() + MainForm）。
wwwroot/index.html：引 _content/Known/css/web.css、js/web.js、js/libs/echarts.js，末尾引导脚本 WASM/Web 用 _framework/blazor.webassembly.js、桌面用 _framework/blazor.webview.js。
App.razor：三宿主共用同一份，只有 <Router AppAssembly / AdditionalAssemblies> + <Container />，不认宿主。

起步常见的坑

别往 KnownWasm/wwwroot 根路径塞静态资源（如 favicon.png、icon-*.png）：它与被托管它的 KnownWeb 会撞同一目标路径，报 Conflicting assets with the same path。KnownWasm/wwwroot 保持只放 index.html。
桌面 TFM 必须带 -windows：漏了 net10.0-windows 或 UseWindowsForms=false，BlazorWebView / WinForms 类型找不到；WebView.WindowsForms 包在仓库里锁 8.*（节奏独立于主框架），升级留意与 blazor.webview.js 兼容。
忘了给业务程序集 Config.AddModule：路由扫不到，页面显示"未找到该路径"。AddKnown 只扫框架自身程序集。
纯 WASM 单跑没有后端：KnownWasm 自己不带接口，直接跑会接口全 404——要连独立 API，或改用 KnownWeb。

下一步

选定形态后，跟着快速开始与项目结构导览把骨架跑起来；三种形态的完整接入骨架与逐形态坑，都在三种运行形态。