code-style - SKILL.md Agent Skill

name: code-style description: 工程代码编写风格指引（不含简单的格式化风格）

在重构代码时，不要被既有模式束缚住，直接重构为更合理、更高效的实现。
修改代码时，不要作打补丁式的临时修改，并且不要留下兼容代码或过渡方案，避免新旧逻辑混杂。
在关键处留下注释以表达意图。
优先复用现有包和辅助项目、工具类，避免重复造轮子，优先复用 Pixeval.Utilities 或本项目里已经有的辅助函数和扩展，例如 SelectNotNull、PickMax/PickClosest、FileHelper、MakoHelper 和缓存辅助方法。
保持代码可 AOT 编译，避免使用反射、动态代码，但是若可以用 [DynamicallyAccessedMembers] 避免反射失败则可以使用。
对于相近功能的模型，通过继承、接口、组合等方式复用代码，避免重复代码。
可观测属性优先使用 CommunityToolkit 的 [ObservableProperty] 生成器，并附在部分属性上而不是字段上来生成。
对于难以处理的异常，可以使用 App.AppViewModel.AppServiceProvider.GetRequiredService<FileLogger>() 记录日志，但若频繁抛出的异常（如 OperationCanceledException、TaskCanceledException等）则不记录。

AppManagement：应用状态和生命周期管理。
Controls：模板控件或控件样式，模板控件继承 TemplatedControl，成对的文件命名也使用 .axaml 和 .axaml.cs；资源字典要在 Themes/Controls.axaml 里引用。
Utilities：辅助函数和扩展方法。
Views：普通的用户控件，包括页面等。
ViewModels：视图模型。
Models：数据模型。
i18n：国际化字符串资源。

打开浏览器、复制文本使用 AvaloniaHelper 里封装好的静态属性，参数通过 Tag 属性指定。
通过现有 {I18N ...} 标记扩展指定本地化字符串。
复用主题资源，例如 ControlCornerRadius、TextFillColorSecondaryBrush、SystemAccentColor 等。不要在资源字典外硬编码颜色。
对来自 URL 或可缓存源的图片加载，优先使用已有附加属性，例如 controls:Source.Cache，而不是直接设置 Image.Source。
优先复用现有的 Views.Converters、Views.Markup、Utilities 里已有的转换器和标记扩展，不要临时在 code-behind 里手写格式化。

主项目 UI 中禁止出现硬编码的字符串（除非不需要翻译的名字、专有名词），所有用户可见的字符串都必须通过资源管理。
字符串资源在 i18n 文件夹里以语言划分，包含 JSON 文件和 Markdown 文件两种形式。
编辑完字符串资源后，运行 i18n/Language.tt 来生成对应的 Language.cs，不要手动编辑这个文件。
C# 文件中，使用 I18NManager.GetResource(XXXResources.XXX) 来获取字符串。禁止直接使用常量字符串： I18NManager.GetResource("XXXResources.XXX")。
XAML 文件中，使用 {I18N {x:Static xxx:XXXResources.XXX}} 标记扩展来获取字符串。禁止直接使用常量字符串： {I18N XXXResources.XXX}。
对于自定义枚举，若要给每个枚举值指定一个对应的字符串资源（来给ComboBox等控件使用），则遵循以下步骤：
- 先在 i18n/xx-XX/Enum.json 中定义枚举值对应的字符串资源，并生成 Language.cs。
- 若是项目内定义的枚举，在枚举上提供 [LocalizationMetadata]，并在每个枚举值上提供 [LocalizedResource(EnumResources.XXX)] 来指定资源键，也可以通过 [LocalizedResource(Resource = "XXX")] 直接指定本地化字符串的值，在使用不需要翻译的专有英文名词时会用到（如 "http"）。
- 若是外部库的枚举，则在 Models/Settings/LocalSettingsEntryHelper.cs 的静态构造函数里指定映射，参考已有示例即可。