winui-code-review

用途

winui-code-review 用于在应用构建成功之后、提交代码之前执行代码审查。它针对的是那些不会造成构建错误、也不会在 UI 测试中暴露的质量问题——即能够编译并运行，但写法错误、脆弱或运行缓慢的模式。

主要能力

该技能通过阅读项目的 XAML 与 C# 文件，按以下方面逐项检查：

• MVVM 合规性：ViewModel 是否继承 ObservableObject、是否使用 [ObservableProperty] 分部属性（而非字段）、命令是否使用 [RelayCommand] 特性而非手写 ICommand、ViewModel 中是否混入 UI 类型（如 SolidColorBrush、Visibility、BitmapImage）、代码隐藏中是否包含业务逻辑、异步方法是否使用 async Task（async void 仅限事件处理器）、是否错误替换 ObservableCollection<T>（应使用 .Clear() 后重新添加）。
• x:Bind 与数据绑定：已知源类型优先使用 {x:Bind}；运行时 {Binding} 需要合理来源，AOT 场景还需生成的属性提供程序；动态值需使用有效的 OneWay/TwoWay 模式（显式或继承 x:DefaultBindMode）并配合变更通知；使用编译型 x:Bind 的 DataTemplate 需带 x:DataType（Page 上不需要）；嵌套可空路径（如 ViewModel.Selected.Name）需提供 FallbackValue。
• Native AOT / 裁剪：发布产物需经过测试（Release JIT 运行不能作为 AOT 验证），IL/CsWinRT 警告应修复而非抑制；跨 ABI 类型需为 partial，JSON 与运行时绑定需使用源生成。
• 无障碍：每个交互控件（Button、TextBox、ComboBox、ToggleSwitch、ListView、NavigationViewItem）需有 AutomationProperties.AutomationId；纯图标按钮及无可见文本控件需有 AutomationProperties.Name；使用语义化控件（Button、HyperlinkButton）而非可点击的 Border/TextBlock；不得仅靠颜色传达信息。
• 主题化：颜色使用 {ThemeResource} 画刷，不硬编码颜色值；排版使用内置样式（TitleTextBlockStyle、SubtitleTextBlockStyle、BodyTextBlockStyle、CaptionTextBlockStyle），不写原始 FontSize；间距使用 4px 网格倍数（4、8、12、16、24、32、48）；圆角使用 ControlCornerRadius / OverlayCornerRadius；样式引用使用 {StaticResource}（画刷使用处除外）。
• 安全：源码中不得包含密钥、API key 或令牌；不得用未净化的用户输入调用 Process.Start；外部输入需验证与净化；来自用户输入的文件路径不得未经校验直接用于 File.Delete / File.WriteAllText。
• 性能：长列表或动态列表使用虚拟化的 ListView/GridView，而非 StackPanel 加 foreach；非始终可见内容（如对话框、次级面板）使用 x:Load；重负载通过 Task.Run 或 async/await 移出 UI 线程；禁止 .Result / .Wait() / .GetAwaiter().GetResult()（会死锁 UI 线程）；对可释放对象（Model、Tokenizer、InferenceSession、Generator）使用 using。
• 全球化：面向用户的字符串在 XAML 中使用 x:Uid、在 C# 中使用 ResourceLoader，不硬编码；字符串资源放在 Strings/en-us/Resources.resw（而非 .resx）；日期/数字格式使用 CultureInfo.CurrentCulture；布局支持 RTL（FlowDirection 从根继承，避免在 RTL 下失效的绝对定位）；面向用户的消息不使用字符串拼接，改用 string.Format 或资源字符串插值。

分析器规则

该技能配合的分析器以分类四位数字 ID 捕获一组精选的 WinUI 3 / Windows App SDK 问题：

• WUI0xxx — UWP → WinUI 3 API 兼容性（UwpXamlNamespace、Window.Current、CoreDispatcher、GetForCurrentView）
• WUI1xxx — 迁移表数据驱动提示（UWP API 有 WinAppSDK 等价项、无等价项、功能区域提示）
• WUI2xxx — 运行时 / 布局 / XAML 陷阱（原始 TabView 内容、可空绑定路径、无效绑定模式、null Converter、缺少 AutomationId、附加属性语法）
• WUI3xxx — MVVM 模式（旧的 [ObservableProperty] 字段语法）
• WUI4xxx — 互操作（WebView2 未初始化、已移除的 ONNX Runtime GenAI API WUI4101-WUI4103）

规则详情可参考已安装包中的诊断帮助链接。在将省略的绑定模式视为缺陷前，需检查继承的 x:DefaultBindMode 以及事件/命令/转换器例外。应修复根因；任何有正当理由的误报抑制必须范围狭窄且有文档记录，不能采用一刀切的 NoWarn 策略。同时应保持 IL/CsWinRT 警告开启，WinUI 分析器不能替代 AOT/裁剪分析。

使用方式

在应用构建通过后、提交前运行审查。审查时阅读项目的 XAML 与 C# 文件并逐项检查上述内容。分析器设置参见 winui-dev-workflow；若未安装，应告知用户其检查未运行。在报告 API 不匹配或建议替换之前，需使用 CLI 0.7+ 的 winapp find-api 对照已还原的应用项目引用进行核实，例如：winapp find-api members NavigationView --filter selected --json --project-dir <app-project-dir>。批量属性检查与项目选择参见 winui-design；机器 SDK 的结果不能作为应用包可用性的证明。

审查报告

审查完成后需汇总：

• 发现的问题：逐条列出文件、行号及问题所在
• 严重级别：Error（必须修复）、Warning（应当修复）或 Note（可以改进）
• 建议修复：针对每个问题给出具体代码修改

参考资料

带代码示例的详细规则见 references/quality-rules.md，涵盖性能深入分析（x:Phase、布局优化）、安全（PasswordVault、DPAPI、WebView2 加固）、无障碍（键盘导航、屏幕阅读器）、代码质量（.editorconfig、命名）以及全球化（x:Uid 模式、RTL、复数化）。

适用场景与限制

适用于 WinUI 3 / Windows App SDK 应用的提交前质量把关，尤其适合需要同时检查 MVVM 规范、绑定正确性、无障碍、主题化、安全与性能的团队。限制方面：该技能依赖已安装的分析器与 winui-dev-workflow 等配套技能；分析器不替代 AOT/裁剪分析；机器 SDK 的 API 查询结果不能证明应用包中该 API 可用；资料未提供具体的收费、价格或平台支持信息。