代码约定
这套约定不是审美偏好，每一条都对应一个真实踩过的坑。
版本号只有一个来源
Starcloud.App.csproj：
<!-- 启动器自身版本（0.3.9）：标题栏版本标识与安装包/更新清单命名的唯一来源 -->
<Version>0.3.9</Version>打包脚本不硬编版本，直接读 XML；NSIS 编译时通过 /DPRODUCT_VERSION= 传进去；latest.json 也从同一个值生成。改版本只改 csproj 一处。
Core 程序集自身的版本和启动器版本无关——SelfUpdateService.CurrentVersion() 读的是入口程序集（Starcloud.App）的 AssemblyInformationalVersion。
设计令牌也只有一个来源
App.xaml 的 Application.Resources 里是全部视觉常量：圆角（ControlCornerRadius=12、CardCornerRadius=20、OverlayCornerRadius=16）、字体（ScUiFontFamily = HarmonyOS Sans SC）、按钮模板、卡片样式、品牌色。浅色 / 深色两套值在 ResourceDictionary.ThemeDictionaries 里，键名相同、值不同。
别在页面里写死颜色和圆角
页面里写 CornerRadius="8" 会和 ScCard 的 16 打架——同一个界面出现三种圆角。改样式去 App.xaml，它同时管控件模板和主题字典。
还有个反直觉的点：ScText 基样式故意不设 Foreground。强调色按钮模板里的白字是靠 ContentPresenter 继承下来的，基样式一旦写死前景色，按钮里的文字会变成黑色，图标却还是白的。
日志一律走 LauncherLog
LauncherLog.Write(category, message) 是唯一的日志出口，文件在 <数据根>/logs/launcher.log，跨天滚动成 launcher-2026-10-22.log。
它有几条自我保护：内存缓冲只留 500 行；单文件超 5 MB 就截断，保留尾部 2 MB；落盘失败一律静默——写不了日志不该让启动器起不来。
构建要求：0 错 0 警
dotnet build dotnet/Starcloud.slnx 必须 0 warning 0 error。警告不是装饰——NSIS 里少写一个 VIAddVersionKey 就是 warning 9100，版本资源里会缺字段。
脚本注释必须纯 ASCII
Windows PowerShell 5.1 把无 BOM 的 .ps1 按 ANSI 代码页读。文件里有一行中文注释，下一行可能被吞掉——ANSI 解码把多字节序列吃成了行尾符的一部分。
所以 tools/*.ps1 一律纯 ASCII。反过来，需要中文的 PowerShell 脚本必须带 BOM：tools/pack-plugin.ps1 是仓库里唯一刻意用 UTF-8 BOM 的 .ps1。
NSIS 的字符集是另一回事
tools/installer.nsi 是 UTF-8 无 BOM，但 NSIS 3 默认也按 ANSI 解析，所以编译必须显式加 /INPUTCHARSET UTF8。验证方式：产出的 setup.exe 版本资源里 FileDescription 显示为「Starcloud Minecraft Launcher 安装程序」。
HLSL 必须纯 ASCII
SkinGpuRenderer.cs 里的着色器源码交给 Vortice 的 D3DCompile，Vortice 按 ANSI 传源码——中文注释会被截断，着色器直接编译失败。这条有单测守着（SkinGpuTests.GPU_着色器源码保持纯ASCII）。
一段逻辑该放 Core 还是 UI
判断题只有一句：这段逻辑换到 Linux 端还需不需要？
需要 → 放 Starcloud.Core（Bridge 和 Android 端要复用它）。不需要 → 放 Starcloud.App。
具体到例：Forge 构建号判定（47.4.5 vs 10.13.4.1614-1.7.10）在 Core，因为 Linux 端也要装 Forge；而「安装后要不要弹窗提示重启」在 App。
常见入口表
| 想改什么 | 去哪个文件 |
|---|---|
| 加一个下载镜像源 | Core/Services/DownloadSource.cs 的 SourceKind + DownloadSourceRegistry.Rewrite() |
| 改下载并发 / 分片策略 | Core/Services/ChunkedFileDownloader.cs（MaxWorkersPerFile=8、GlobalWorkerBudget=32、Threshold=4MiB） |
| 改启动参数 | Core/Services/GameLauncher.cs 的 BuildArgsCore |
| 改版本隔离的内容目录 | Core/Services/InstanceSettings.cs 的 InstanceLayout.ContentDirs |
| 加一个界面页面 | App/Shell/BuiltinShellPlugin.cs 的 Entries 加一条 |
| 改插件挂载点 | Core/Kernel/ContributionRegistry.cs 的 ContributionKind |
| 改设置项 | Core/Services/LauncherPaths.cs 的 LauncherSettings |
加页面必须走贡献点登记
以前外壳里写死了两处：MainWindow.xaml 的 NavigationViewItem 列表，和 MainWindow.xaml.cs 里 tag → Page 类型的 switch。加一页要改两处，插件想挂页面还得另走一条路。现在外壳只认贡献点——直接改 XAML 的话，插件页和导航会不一致。