tomevault-io Avalonia AI Playbook
When to use
- 新建 Avalonia 项目并建立 AI 协作规范
- 从 MAUI/WPF/WinForms 迁移到 Avalonia
- 生成复杂 XAML + MVVM 代码时降低幻觉概率
- 借助 MCP 做 UI 树诊断、样式定位、打包自动化
Procedure
先规划后编码
- 明确目标（新建/迁移/重构/打包/调试）
- 列出实施步骤（5-8 步），每步聚焦一个小目标
- 代码全部完成后，通过构建验证代码正确性
先复用现有模式，后扩展新模式
- 优先沿用项目已有命名、目录结构、DI 注册方式。
- 若需要新模式（如
ReactiveUI、CommunityToolkit.Mvvm），先说明引入理由与影响范围。
遇到不确定 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-behindViewModels/：状态与命令Services/：I/O、平台能力、外部依赖Resources/：主题、样式、字典、本地化
- 命名建议：
- View:
XxxView.axaml - ViewModel:
XxxViewModel.cs - Command:
SaveCommand/LoadCommand
- View:
- 绑定建议：
- 避免深层级链式绑定（可读性差且难排错）
- 避免在 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 — claim your Tome and manage your conversions.