chinboy
7.3 KiB
AtomUI AI 协作规范
这份文档承载面向 AI 编程助手的具体工程约束。AGENTS.md 只引用它；后续如果某条约束属于 AOT、Gallery、资源生命周期、发布流程等更具体领域，应移动到对应专项文档，并在这里保留简短索引或原则。
约束放置原则
- 根目录
AGENTS.md只写项目入口、文档路由和稳定协作原则。 - 具体、可执行、会增长的规则放到
docs/engineering/、docs/gallery/、docs/modules/或控件文档中。 - 新增规则前先判断归属：跨项目协作放本文档；AOT 放
aot-programming-guidelines.md；Gallery 页面放gallery-showcase-design-pattern.md；发布放 release workflow 文档。 - 当一个规则只适用于某个子系统，不要为了可见性塞进
AGENTS.md，应在该子系统文档中写清楚并从相关入口引用。
Bug 修复
修复 bug 时必须优先寻找从根源杜绝问题的方案，而不是只在触发点打补丁。
编写 BUG 类型 Issue 时，按 BUG Issue 规范 收集上下文并描述期望行为；不要在 Issue 中混入实现方案、验收清单或测试计划。
执行顺序：
- 复现或从错误栈、日志、截图、用户步骤中还原触发路径。
- 追踪坏状态、异常或错误行为的来源，直到能解释为什么会发生。
- 搜索同类实现和同类触发入口，判断是否存在同源 bug。
- 先补能失败的回归测试；无法自动化时，说明原因并保留可复查的手动验证步骤。
- 在源头修复共享逻辑、状态模型、生成器、生命周期或契约，而不是只拦截当前样例。
- 修复后重跑回归测试，并根据影响面补跑相邻模块测试。
不要把这些行为当作根因修复：
- 捕获异常后吞掉。
- 对当前控件或当前 Demo 写特殊判断，但共享路径仍然会失败。
- 加延时、重试或强制刷新来掩盖状态同步问题。
- 用
UnconditionalSuppressMessage或条件编译隐藏 AOT/trim warning，但没有改变运行时动态行为。
Public API 变更约束
修复 bug 时，默认不得引入新的 Public API，除非已经得到用户明确允许。
Public API 包括但不限于 public / protected 类型、成员、构造函数、Avalonia 属性、事件、公开接口、可被 XAML 引用的公开控件类型、主题资源 key、ControlTheme key、TemplatePart、伪类等对外契约。
修复应优先复用现有公开契约、private / internal 实现、模板内部结构或已有共享基础设施。不得为了当前 bug 修复方便，新增空的 public 类型、包装类、属性、事件或临时公开扩展点。
如果判断根因修复确实需要新增或调整 Public API，必须先停止实现，并向用户说明：
- 为什么不改 Public API 无法从源头修复。
- 具体会新增或变更哪些 API。
- 对兼容性、文档、测试和示例的影响。
- 是否存在不改 Public API 的替代方案及代价。
如果不确定某个类型、成员或 XAML 契约是否属于 Public API，应先询问用户，不要自行决定。
AOT 与动态行为
新增功能和修复 bug 默认都要做一次 AOT 兼容判断。具体规则以 aot-programming-guidelines.md 为准，不在本文档重复展开。
重点约束：
- 同一需求有 AOT 友好实现和运行时反射/动态发现实现时，选择 AOT 友好实现。
- 能用 source generator、显式注册或 descriptor 的路径，不使用反射扫描。
- 发布路径、source generator 运行时注册、动态数据 path 等风险点按 AOT 文档验证。
Gallery
Gallery 页面结构、懒加载、API DataGrid、Design Token DataGrid 和示例组织规则以 gallery-showcase-design-pattern.md 为准。
Gallery 改动时注意：
- 不把 API/Token 表格重新手写成普通布局。
- 不在页面结构调整中顺手改 Demo 行为。
- 延迟创建只能改变创建时机，不能改变示例控件树语义。
- 涉及 NativeAOT 发布或发布脚本时，阅读 gallery-aot-release-workflow.md。
资源与生命周期
涉及 DynamicResource、非 Visual AvaloniaObject、template part、event handler、binding、subscription、cache 时，必须能说明释放或失效位置。
典型检查：
OnApplyTemplate重新应用时释放旧 part 绑定。- detach、owner 变更、container recycle 时解绑事件和资源宿主。
- 非 Visual 对象使用动态资源时，需要明确资源宿主生命周期。
- owner-managed 非 Visual
AvaloniaObject需要 scoped resource host 时，默认遵循 Scoped Resource Host Source Generator 范式，不要复制手写IResourceHost/IThemeVariantHost样板代码。 - 修复内存保留问题时，按同类对象成组审计，不只修 dump 中看到的第一个类型。
参考：avalonia-dynamic-resource-memory-leak-case-study.md。
测试与验证
选择验证命令时按风险扩大范围：
- 纯共享数据结构：先跑对应 shared tests。
- Desktop 控件行为：跑对应
AtomUI.Desktop.Controls.Tests。 - DataGrid：跑
AtomUI.Desktop.Controls.DataGrid.Tests。 - Gallery 页面或 ViewModel：跑
AtomUIGallery.Tests。 - AOT、trim、发布配置、source generator 运行时注册：跑真实 NativeAOT publish。
- 每次收尾都运行
git diff --check。
不要在没有最新验证输出时声称“已修复”“测试通过”或“发布可用”。
文档更新
当一次改动形成可复用规则时，更新对应文档：
- 跨项目 AI 工作约束：本文档。
- AOT、trim、source generator：
aot-programming-guidelines.md。 - Gallery 页面结构：
gallery-showcase-design-pattern.md。 - Gallery AOT 发布：
gallery-aot-release-workflow.md。 - 控件研发标准：
control-development-guidelines.md。 - 模块架构：
docs/modules/**/overview.md。 - 控件用户文档：
docs/controls/**。
文档应记录“以后怎么做”和“为什么”，不要写成一次性修复记录。
代码改动边界
- 遵循当前模块已有风格、命名和文件组织。
- 不做与用户请求无关的格式化、重排、重命名或清理。
- 删除只因本次改动变得无用的代码；既有无关遗留先报告，不直接处理。
- 抽象只在能消除实际重复、降低共享复杂度或匹配既有模式时引入。
- 生成文件不要手改；改 generator 或输入源，并验证输出。
控件研发标准
控件 C# 实现、AXAML 主题、API 和主题契约变更必须遵循 AtomUI 控件研发标准规范。优化代码和修复 bug 时，如果涉及控件既有 API、主题契约或可观察行为变化，必须先获得用户明确授权。
Changelog 与发布
Changelog 维护规则见 changelog-guidelines.md。普通修复、功能和内部重构不默认修改 CHANGELOG.md，只有用户明确要求准备 changelog、release、版本发布，或变更包含必须提前暴露的兼容性信息时才整理。
发布相关改动必须检查对应脚本、workflow、项目属性和产物校验逻辑，不能只看普通 Debug build。