企业官网建设流程全解析

• AI 应用
• 人工智能
• 桌面应用
• 本地部署
• 媒体生成

本文以仓库根目录的 CONTRIBUTING.md 为骨架，结合当前仓库的工程配置（Runtimes.Default.props、StabilityMatrix.Avalonia.csproj、.husky/task-runner.json、StabilityMatrix.Avalonia.pupnet.conf等）逐项展开。读完本文，你将掌握 StabilityMatrix 的本地构建与调试方法、Windows/macOS/Linux 三平台单文件发布流程、基于 Husky.Net 的 pre-commit 自动化与 OpenApi 客户端再生成方式，以及该仓库完整的 C# 代码风格约定与目录组织规范，可直接用于日常开发与提交代码。

快速上手：搭建本地构建环境

StabilityMatrix 是基于 Avalonia 的跨平台桌面应用，核心工程为StabilityMatrix.Avalonia（UI 层）与StabilityMatrix.Core（领域/服务层）。开发前请确认本机已安装 .NET SDK：仓库根目录的 global.json 声明了 SDK 版本9.0.0，并允许latestMajor向前滚动（即安装了更高主版本的 SDK 也可以构建）。

{ "sdk": { "version": "9.0.0", "rollForward": "latestMajor", "allowPrerelease": true } }

在仓库根目录执行以下命令即可完成 Debug 构建（以 Windows 运行时为例）：

dotnet build ./StabilityMatrix.Avalonia/StabilityMatrix.Avalonia.csproj -r win-x64 -c Debug

这条命令的核心要点是必须显式传入-r win-x64（即--runtime win-x64）。原因有二：

• 仓库的 Runtimes.Default.props 声明了RuntimeIdentifiers为win-x64;linux-x64;osx-x64;osx-arm64，而StabilityMatrix.Avalonia.csproj中针对不同 RID 条件性地包含不同的运行时资源（见下文“为什么必须显式指定 RuntimeIdentifier”）；
• 若使用 Rider / Visual Studio 等托管 IDE 构建，同样需要保证传给dotnet的参数里带上了有效的--runtime ...，或者对msbuild调用设置了RuntimeIdentifier=...，否则依赖特定运行时（runtime-specific）的资源不会被打进构建产物。

目标框架与输出路径

• 在 Windows 上，工程使用net9.0-windows10.0.17763.0目标框架（见 Runtimes.Default.props 中的条件属性），因此 Debug 构建产物位于StabilityMatrix.Avalonia/bin/Debug/net9.0-windows10.0.17763.0/win-x64；
• 在其他平台（Linux、macOS）使用通用net9.0目标框架，输出路径相应为StabilityMatrix.Avalonia/bin/Debug/net9.0/...。

说明：原 CONTRIBUTING.md 中记载的是net8.0-windows10.0.17763.0，而当前仓库的 Runtimes.Default.props 已升级为net9.0-windows10.0.17763.0，Directory.Build.props 也将默认TargetFramework设为net9.0，实际构建输出目录以仓库当前配置为准。

深入：为什么必须显式指定 RuntimeIdentifier

StabilityMatrix 的发布需要携带各平台专属的运行时资源，这在 StabilityMatrix.Avalonia.csproj 中有非常直观的体现：

• win-x64时，将Assets/win-x64/**作为 Avalonia 资源打进程序集，并启用 Windows 平台 manifest（app.manifest）；
• linux-x64时，引入SkiaSharp.NativeAssets.Linux原生包（见Directory.Packages.props中的集中版本管理），并打包Assets/linux-x64/**；
• osx-arm64时，设置CFBundleName、CFBundleIdentifier（ai.lykos.stabilitymatrix）、CFBundleIconFile等 macOS Bundle 属性，并额外通过EditInfoPlist目标在打包后向Info.plist注入stabilitymatrix://自定义 URL Scheme 注册信息。

同时 Runtimes.Default.props 提供了“未指定 RID 时按当前操作系统自动选择默认 RID”的回退逻辑：

• Windows →win-x64
• Linux →linux-x64
• macOS →osx-arm64

但自动回退只保证“能跑”，无法保证你拿到的是完整产物，因此 CONTRIBUTING 才反复强调要显式传 RID。另外，StabilityMatrix.Avalonia.csproj中InternalsVisibleTo声明了StabilityMatrix.Tests与StabilityMatrix.UITests，意味着两个测试程序集可以直接访问内部成员，这与 StabilityMatrix.Tests / StabilityMatrix.UITests 的测试用例相印证。

发布单文件安装包（Release）

进行正式发布时，需要把$RELEASE_VERSION替换为不带v前缀的 semver 版本号，例如2.10.0、2.11.0-dev.1等。以下分别给出三平台流程。

Windows：dotnet publish单文件自解压

dotnet publish ./StabilityMatrix.Avalonia/StabilityMatrix.Avalonia.csproj -r win-x64 -c Release -p:Version=$env:RELEASE_VERSION -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:PublishReadyToRun=true

参数含义：

• -p:PublishSingleFile=true：把托管程序集与依赖捆绑为单个可执行文件；
• -p:IncludeNativeLibrariesForSelfExtract=true：将原生库一并捆绑，运行时自解压执行；
• -p:PublishReadyToRun=true：启用 ReadyToRun（R2R）预编译，提升启动性能；
• -p:Version=...：把版本号写入程序集版本与文件版本。

注意：$env:RELEASE_VERSION是 PowerShell 环境变量语法；若在 bash 中执行，请改为$RELEASE_VERSION。

macOS：build_macos_app.sh打包 .app

macOS 使用仓库自带的 Build/build_macos_app.sh 脚本，它内部会调用dotnet msbuild ... -t:BundleApp生成标准Stability Matrix.appBundle：

./Build/build_macos_app.sh -v $RELEASE_VERSION

脚本行为要点（与 Build/build_macos_app.sh 源码对照）：

• output_dir环境变量可自定义输出目录，默认./out/osx-arm64/；
• 通过-t:BundleApp与-p:RuntimeIdentifier=osx-arm64、-p:Configuration=Release、-p:SelfContained=true等参数执行 MSBuild 打包，PublishDir指向${output_dir}/bin；
• 打包完成后用plutil -lint校验Info.plist，再把.app从bin目录复制到输出根目录；
• 构建成功后脚本会以超链接形式打印输出目录。

如果需要走正式的签名与公证流程，Build 目录还提供了配套脚本：codesign_macos.sh（逐文件签名并注入 Build/AppEntitlements.entitlements 权限）与notarize_macos.sh（notarytool提交公证并stapler附加票据），二者都支持 CI 环境下的凭据注入。

Linux：AppImage（appimagetool + PupNet）

sudo apt-get -y install fuse3 # 下载 appimagetool（使用静态 type2-runtime；终端用户系统仍需 # fusermount 或 fusermount3 setuid 辅助程序，或可使用 # --appimage-extract-and-run 作为备选运行方式） sudo wget -q https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage -O /usr/local/bin/appimagetool sudo chmod +x /usr/local/bin/appimagetool dotnet tool install -g KuiperZone.PupNet --version 1.9.1 pupnet -r linux-x64 -c Release --kind appimage --app-version $RELEASE_VERSION --clean

流程拆解：

1. fuse3：AppImage 运行时依赖 FUSE，需先安装；
2. appimagetool：把打包产物转换为 AppImage 的工具；
3. KuiperZone.PupNet（版本固定为 1.9.1）：StabilityMatrix 使用的跨平台部署工具，其配置位于仓库根目录的 StabilityMatrix.Avalonia.pupnet.conf，其中声明了AppBaseName = StabilityMatrix.Avalonia、AppFriendlyName = Stability Matrix、AppId = zone.lykos.stabilitymatrix、StartCommand = stabilitymatrix等元信息；
4. pupnet -r linux-x64 -c Release --kind appimage --app-version $RELEASE_VERSION --clean：以 AppImage 形式产出发布包；--clean表示清理旧输出。

值得一提的细节：PupNet 配置文件中的DotnetPublishArgs与 Windows 单文件发布一脉相承，包含-p:PublishReadyToRun=true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true，且默认--self-contained（自包含部署，终端用户无需预装 .NET 运行时）。

工程脚本：Husky.Net 与 pre-commit 钩子

仓库使用 Husky.Net 管理 git 钩子与任务运行器。

安装钩子

构建一次StabilityMatrix.Avalonia工程即可自动安装 Husky.Net，也可以手动执行：

dotnet tool restore && dotnet husky install

这里的自动化其实也写进了工程文件：StabilityMatrix.Avalonia.csproj 中有一个名为husky的 MSBuild Target，挂在Restore;CollectPackageReferences之前，条件是HUSKY=1或（HUSKY != 0且非 CI 环境），其内容就是执行dotnet tool restore与dotnet husky install——这就是“构建一次即装好钩子”的底层原理。

日常新增/更新 pre-commit 钩子时，可单独运行：

dotnet husky install

pre-commit 钩子实际执行什么

钩子入口是 .husky/pre-commit，它会调用dotnet husky run --group "pre-commit"。而具体任务定义在 .husky/task-runner.json 中，当前包含两条 pre-commit 任务：

也就是说，每次提交时，所有暂存的.cs与.axaml文件会被自动格式化。这与仓库的格式配置是配套的：.editorconfig规定max_line_length = 120、dotnet_sort_system_directives_first = true等规则，而 .csharpierrc.yaml 将 CSharpier 的行宽设为110。${staged}是 Husky 对暂存文件列表的模板变量，保证只格式化本次提交涉及的文件。

生成的 OpenApi 客户端：Refitter 再生成流程

仓库的部分 API 客户端是通过Refitter从 OpenApi 文档自动生成的，遵循“接口契约变化后一键重新生成”的维护模式。

• 新客户端应登记到 .husky/task-runner.json 中（即新增一个group: generate-openapi的 refitter 任务）；
• 重新生成全部客户端执行：

dotnet husky run -g generate-openapi

当前 .husky/task-runner.json 中登记了两个生成任务：

1. LykosAuthApi：以 StabilityMatrix.Core/Api/LykosAuthApi/.refitter 为设置文件，输出到StabilityMatrix.Core/Api/LykosAuthApi/Generated，接口命名为LykosAuthApiV2，并通过includePathMatches只保留/api/v2/Accounts/me、/api/v2/oauth/patreon、/api/v2/files/download等路径；
2. PromptGenApi：以 StabilityMatrix.Core/Api/PromptGen/.refitter 为设置文件，生成提示词生成服务客户端。

从源码结构看，StabilityMatrix.Core/Api 目录下还手工维护着大量I*Api.cs接口（如ICivitApi、IComfyApi、IHuggingFaceApi等），说明仓库的策略是：能契约化生成的走 Refitter，其余手工接口保持 Refit 风格——二者的共同点是都位于Api目录，符合 CONTRIBUTING 中“Refit 接口放在Api\文件夹”的约定。

代码风格指南

CONTRIBUTING 的风格章节与官方 C# 风格指南基本一致，少数地方有项目特化。以下逐条给出规则与代码示例。

命名约定（Naming Conventions）

Pascal Case（帕斯卡命名）

• 命名class、record、struct，以及类型的public成员（字段、属性、方法、局部函数）时使用 PascalCase，例如CheckpointManagerViewModel、DownloadPackage；
• 命名interface时，除 PascalCase 外还须加前缀I，例如 StabilityMatrix.Core/Api/ICivitApi.cs、StabilityMatrix.Core/Services/IServiceManager.cs。

Camel Case（驼峰命名）

• private或internal字段使用 camelCase；
• 禁止为它们添加下划线前缀_。这一条与 .editorconfig 中的规则遥相呼应——注意.editorconfig里 ReSharper 侧的resharper_style = aaBb, _ + aaBb是 IDE 内部的兼容映射，而源码层面遵循“无下划线前缀”的规范，阅读仓库代码时可留意各类readonly字段的写法。

using指令

不要提交带有未使用using语句的代码。配合 .editorconfig 的dotnet_sort_system_directives_first = true，System 命名空间应排在首位，IDE/分析器会协助清理。

文件作用域命名空间（File-scoped Namespaces）

一律使用文件作用域命名空间（C# 10+ 语法）：

using System; namespace X.Y.Z; class Foo { }

仓库中几乎所有源文件都遵循此写法，例如 analyzers/StabilityMatrix.Analyzers/ViewModelControlConventionAnalyzer.cs 顶部即为namespace StabilityMatrix.Analyzers;。

隐式类型局部变量（var）

当局部变量的类型能从赋值右侧明显看出、或精确类型并不重要时，使用隐式类型var，例如：

var dialog = new InstallerWindowDialog();

可选花括号（Optional Curly Braces）

只有一种情况下允许省略if的花括号：紧随其后的语句是return。以下写法可接受：

if (alreadyAteBreakfast) return;

其余情况必须带花括号：

if (alreadyAteLunch) { mealsEaten++; }

项目结构（Project Structure）

CONTRIBUTING 明确了目录组织原则，结合当前仓库可以一一对应：

• 模型类放入Models\目录 → 见 StabilityMatrix.Core/Models（282 个模型文件）与 StabilityMatrix.Avalonia/Models；
• ViewModel放入ViewModels\→ 见 StabilityMatrix.Avalonia/ViewModels（含Base/、Dialogs/、Inference/等子目录）；
• 只含扩展方法的静态类放入Extensions\→ 见 StabilityMatrix.Core/Extensions 与 StabilityMatrix.Avalonia/Extensions；
• XAML Designer 用的 Mock 数据放入DesignData\→ 见 StabilityMatrix.Avalonia/DesignData 中的Mock*类；
• XAML 转换器与JSON 转换器分别放入Converters\与Converters\Json\→ 见 StabilityMatrix.Avalonia/Converters 与 StabilityMatrix.Core/Converters/Json；
• Refit 接口放入Api\→ 见 StabilityMatrix.Core/Api；
• Helper\与Services\目录没有硬性规范，可按最佳判断放置 → 对应 StabilityMatrix.Core/Helper、StabilityMatrix.Core/Services。

与仓库工具链的相互印证

CONTRIBUTING 提到的规范与自动化，在当前仓库中都能找到落地证据：

1. 格式一致性：.editorconfig与 .csharpierrc.yaml 是 CSharpier / 编辑器格式化的依据，而 .husky/task-runner.json 在提交前强制运行它们；
2. 自定义 Roslyn 分析器：仓库自带 StabilityMatrix.Analyzers 工程，其中的ViewModelControlConventionAnalyzer会以诊断规则SM0001（控件必须继承UserControlBase/TemplatedControlBase）与SM0002（缺少 View 特性）在编译期约束 ViewModel/View 的命名与继承约定，且这两个分析器通过 StabilityMatrix.Avalonia.csproj 以OutputItemType="Analyzer"的方式挂进 UI 工程；
3. 集中式包管理：Directory.Packages.props 以ManagePackageVersionsCentrally=true统一管理全部 NuGet 版本（Avalonia 11.3.7、Refit 8.0.0、CommunityToolkit.Mvvm 8.4.0 等），新增依赖时应在该文件登记版本，而不是在各个 csproj 里写死；
4. 多平台与测试：Runtimes.Default.props的 RID 清单（win-x64;linux-x64;osx-x64;osx-arm64）与 CONTRIBUTING 声明支持的运行时一致；测试侧由 StabilityMatrix.Tests（核心逻辑单测）与 StabilityMatrix.UITests（Avalonia Headless UI 测试 + 快照）构成，二者均通过InternalsVisibleTo访问内部实现。

小结

围绕 CONTRIBUTING.md，本文完整覆盖了 StabilityMatrix 的开发闭环：本地构建必须显式指定RuntimeIdentifier（三平台 RID 及输出路径）；Release 发布分别走dotnet publish单文件（Windows）、build_macos_app.sh打包 .app（macOS）、appimagetool + PupNet 产出 AppImage（Linux）；工程侧用 Husky.Net 驱动 csharpier / xamlstyler 的 pre-commit 格式化，用 Refitter 一键再生成 OpenApi 客户端；代码侧则需遵循无下划线前缀的 camelCase 私有字段、文件作用域命名空间、var优先与受约束的花括号省略等约定，并按Models、ViewModels、Extensions、DesignData、Converters、Api的目录划分组织新代码。这些规则不仅写在了文档里，也同时被.editorconfig、自定义分析器与 pre-commit 钩子强制保障，是理解该仓库工程化体系的一把钥匙。

• AI 应用
• 人工智能
• 桌面应用
• 本地部署
• 媒体生成