# Avalonia > Avalonia UI AI workflow for project setup, migration prompts, MCP-assisted debugging, and safe code generation. Use for Avalonia XAML/MVVM tasks with Copilot/AI assistants. Use when this capability is needed. - Skill: `tomevault-io/avalonia` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/avalonia` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/avalonia/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/avalonia --- # Avalonia AI Playbook ## When to use - 新建 Avalonia 项目并建立 AI 协作规范 - 从 MAUI/WPF/WinForms 迁移到 Avalonia - 生成复杂 XAML + MVVM 代码时降低幻觉概率 - 借助 MCP 做 UI 树诊断、样式定位、打包自动化 ## Procedure 1. **先规划后编码** - 明确目标（新建/迁移/重构/打包/调试） - 列出实施步骤（5-8 步），每步聚焦一个小目标 - 代码全部完成后，通过构建验证代码正确性 2. **先复用现有模式，后扩展新模式** - 优先沿用项目已有命名、目录结构、DI 注册方式。 - 若需要新模式（如 `ReactiveUI`、`CommunityToolkit.Mvvm`），先说明引入理由与影响范围。 3. **遇到不确定 API：先查证再生成** - 优先官方文档 + 当前仓库已有示例。 - 避免杜撰 Avalonia 控件属性、附加属性或样式键。 ## Best Practices（最佳实践） ### 1) 架构与分层 - 保持 MVVM 纯度：业务逻辑放 ViewModel/Service，不放 code-behind。 - ViewModel 不直接依赖具体 UI 控件类型，避免 UI 反向侵入。 - 将状态与副作用分离：状态可测试，副作用（弹窗/文件系统/网络）通过服务抽象。 ### 2) XAML 与绑定 - 优先使用强类型/编译期友好的绑定写法（可用时启用 compiled bindings）。 - 控件模板和 DataTemplate 复用到 `Styles`/资源字典，减少重复 XAML。 - 对列表项与复杂布局优先定义清晰的数据模型，而不是在 XAML 内堆复杂表达式。 ### 3) 命令与异步 - 用户动作统一走 `ICommand`（或异步命令）并处理禁用态/忙碌态。 - 异步命令必须处理异常与取消（`CancellationToken`），避免吞异常。 - 避免在 UI 线程执行重 I/O 或长计算；必要时下沉到后台服务。 ### 4) 样式与主题 - 统一主题变量与资源命名，避免页面级“魔法色值”散落。 - 同步覆盖亮色/暗色与高对比度场景。 - 样式覆盖优先小范围、可追踪，避免全局样式误伤。 ### 5) 可维护性与可测试性 - ViewModel 层新增行为时同步补充测试（至少 happy path + error path）。 - 对关键交互输出可回归清单：空状态、加载态、错误态、长文本、窄窗口。 - 大改优先拆成多个小 PR/小提交，保证每步可编译可回滚。 ## Coding Conventions（常见规范） - 文件组织建议： - `Views/`：`.axaml` + 极薄 code-behind - `ViewModels/`：状态与命令 - `Services/`：I/O、平台能力、外部依赖 - `Resources/`：主题、样式、字典、本地化 - 命名建议： - View: `XxxView.axaml` - ViewModel: `XxxViewModel.cs` - Command: `SaveCommand` / `LoadCommand` - 绑定建议： - 避免深层级链式绑定（可读性差且难排错） - 避免在 Binding Converter 里塞业务规则 ## Common Mistakes to Avoid（常见错误与规避） ### 错误 1：把业务逻辑写进 code-behind - 症状：页面事件处理函数越来越重，难测且难复用。 - 规避：事件只做转发，逻辑迁移至 ViewModel 命令。 ### 错误 2：AI 生成了不存在的 Avalonia API - 症状：编译报“属性/类型不存在”。 - 规避：先查官方文档或项目现有写法，再落地代码；对新 API 做最小编译验证。 ### 错误 3：一次性重写整页导致回归不可控 - 症状：UI 看似完成但行为缺失、样式错乱。 - 规避：拆批次迁移（布局 → 绑定 → 命令 → 样式），每批构建+手测。 ### 错误 4：异步命令未处理并发与取消 - 症状：重复点击导致重入、状态错乱。 - 规避：加入 Busy 状态与并发保护；提供取消路径。 ### 错误 5：资源字典混乱、样式命名冲突 - 症状：跨页面样式互相污染，难以定位来源。 - 规避：建立资源命名前缀与分层策略（全局/模块/页面）。 ### 错误 6：只在一个主题下验收 - 症状：暗色主题或高 DPI 下 UI 崩坏。 - 规避：至少验证亮/暗主题、不同缩放、不同窗口宽度。 ## Debug Checklist（调试检查单） - 绑定异常：先看输出日志与 DataContext 链路，再看属性名与可见性。 - 样式异常：检查选择器命中、资源覆盖顺序、主题字典加载顺序。 - 交互异常：检查命令 CanExecute、异步重入、导航/状态同步。 - 性能异常：检查大列表虚拟化、频繁 PropertyChanged、重绘热点。 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/aterdev) — claim your Tome and manage your conversions.