mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-29 07:16:33 +08:00
chinboy
9f6ec36645
统一文档目录的入口文件名为 `overview.md`，取代原先的 `index.md`。单 Control 目录本来就用 `overview.md`，此前只有目录级入口用 `index.md`，两套命名并存；现在全库一致。 改名覆盖 42 个入口文件：`docs/` 根、一级分类目录、Architecture 分组与跨模块系统目录、Module 目录、Control 平台与分类目录、Guide 与 Reference 子目录。`docs/AI/generated/index.md` 是手工 维护的导航页，一并改名。 生成产物 `docs/AI/generated/llms/**/index-cn.md` 保持原名，它属于 LLMs Generator 的输出契约。 同步更新 28 个正式文档与 `AGENTS.md` 中的入站链接，以及两处目录树示意图。改名后全部相对链接 可解析，LLMs Generator `verify` 通过（78 控件 / 159 文件），单 Control 四件套文件名契约未变。 新增 `docs/engineering/contributing/documentation-structure-guidelines.md` 承载入口命名、文档 拆分标准、事实所有权和链接规范。此前该规则只写在带日期的设计过程记录里，不适合作为长期来源。 `docs/superpowers/specs/2026-08-10-documentation-information-architecture-design.md` 保留原文 并加取代说明，其余结论继续有效。
134 lines
7.7 KiB
Markdown
134 lines
7.7 KiB
Markdown
# 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 规范](bug-issue-guidelines.md) 收集上下文并描述期望行为；不要在 Issue 中混入实现方案、验收清单或测试计划。
|
||
|
||
执行顺序：
|
||
|
||
1. 复现或从错误栈、日志、截图、用户步骤中还原触发路径。
|
||
2. 追踪坏状态、异常或错误行为的来源，直到能解释为什么会发生。
|
||
3. 搜索同类实现和同类触发入口，判断是否存在同源 bug。
|
||
4. 先补能失败的回归测试；无法自动化时，说明原因并保留可复查的手动验证步骤。
|
||
5. 在源头修复共享逻辑、状态模型、生成器、生命周期或契约，而不是只拦截当前样例。
|
||
6. 修复后重跑回归测试，并根据影响面补跑相邻模块测试。
|
||
|
||
不要把这些行为当作根因修复：
|
||
|
||
- 捕获异常后吞掉。
|
||
- 对当前控件或当前 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，必须先停止实现，并向用户说明：
|
||
|
||
1. 为什么不改 Public API 无法从源头修复。
|
||
2. 具体会新增或变更哪些 API。
|
||
3. 对兼容性、文档、测试和示例的影响。
|
||
4. 是否存在不改 Public API 的替代方案及代价。
|
||
|
||
如果不确定某个类型、成员或 XAML 契约是否属于 Public API，应先询问用户，不要自行决定。
|
||
|
||
## AOT 与动态行为
|
||
|
||
新增功能和修复 bug 默认都要做一次 AOT 兼容判断。具体规则以 [AOT 编程规范](../development/aot-programming-guidelines.md) 为准，不在本文档重复展开。
|
||
|
||
重点约束：
|
||
|
||
- 同一需求有 AOT 友好实现和运行时反射/动态发现实现时，选择 AOT 友好实现。
|
||
- 能用 source generator、显式注册或 descriptor 的路径，不使用反射扫描。
|
||
- 发布路径、source generator 运行时注册、动态数据 path 等风险点按 AOT 文档验证。
|
||
|
||
## Gallery
|
||
|
||
Gallery 页面结构、懒加载、示例组织和旧 API/Token sidecar 禁用规则以 [Gallery ShowCase Design Pattern](../../gallery/authoring/gallery-showcase-design-pattern.md) 为准。
|
||
|
||
Gallery 改动时注意：
|
||
|
||
- 不把已移除的 API/Token sidecar 重新手写成普通布局。
|
||
- 不在页面结构调整中顺手改 Demo 行为。
|
||
- 延迟创建只能改变创建时机，不能改变示例控件树语义。
|
||
- 涉及 NativeAOT 发布或发布脚本时，阅读 [Gallery NativeAOT Release Workflow](../workflows/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 开发规范](../development/scoped-resource-host.md)，不要复制手写 `IResourceHost` / `IThemeVariantHost` 样板代码。
|
||
- 修复内存保留问题时，按同类对象成组审计，不只修 dump 中看到的第一个类型。
|
||
|
||
参考：[Avalonia DynamicResource 内存泄露案例](../case-studies/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/**`。
|
||
|
||
文档应记录“以后怎么做”和“为什么”，不要写成一次性修复记录。
|
||
|
||
长期架构文档和实现维护文档必须以 AtomUI 自身的公共契约、不变量和验证条件为准。不得把外部项目的
|
||
具体版本、tag、commit、本地参考仓库路径或源码行号写成 AtomUI 架构的事实来源。确需保留上游差异或
|
||
调查证据时，应放入带日期的迁移记录、发布记录或问题分析；长期文档只保留验证后的结论和重新验证条件。
|
||
|
||
## 代码改动边界
|
||
|
||
- 遵循当前模块已有风格、命名和文件组织。
|
||
- 不做与用户请求无关的格式化、重排、重命名或清理。
|
||
- 删除只因本次改动变得无用的代码；既有无关遗留先报告，不直接处理。
|
||
- 抽象只在能消除实际重复、降低共享复杂度或匹配既有模式时引入。
|
||
- 生成文件不要手改；改 generator 或输入源，并验证输出。
|
||
|
||
## 控件研发标准
|
||
|
||
控件 C# 实现、AXAML 主题、API 和主题契约变更必须遵循 [AtomUI 控件研发标准规范](../development/control-development-guidelines.md)。优化代码和修复 bug 时，如果涉及控件既有 API、主题契约或可观察行为变化，必须先获得用户明确授权。
|
||
|
||
## Changelog 与发布
|
||
|
||
Changelog 维护规则见 [changelog-guidelines.md](changelog-guidelines.md)。普通修复、功能和内部重构不默认修改 `CHANGELOG.md`，只有用户明确要求准备 changelog、release、版本发布，或变更包含必须提前暴露的兼容性信息时才整理。
|
||
|
||
发布相关改动必须检查对应脚本、workflow、项目属性和产物校验逻辑，不能只看普通 Debug build。
|