update-gallery-maintain-docs

SKILL: 根据代码修改同步 Gallery 文档

名称

update-gallery-maintain-docs

触发条件

当 Gallery 项目完成一次重要的代码升级或重构（例如 ReactiveUI 版本升级、架构调整、API 变更）后，需要更新 docs/Gallery 下的维护文档时，使用本 SKILL。

Gallery 项目源码

gallery 项目的源码主要在以下三个地方，非常重要，你务必要仔细分析这三个项目的代码修改，才能正确更新文档！！！！！

• Gallery 基础项目：controlgallery/AtomUIGallery，这个项目包含了大部分的 ViewModel 和 ShowCase 相关代码，是文档更新的重点。
• Gallery 主项目：controlgallery/AtomUIGallery.Desktop，这个项目 Gallery 的主入口，包含了 App.xaml.cs、ViewLocator、依赖注入容器配置等全局相关代码。

Gallery 项目维护文档

Gallery 项目的维护文档主要位于 docs/Maintain/AtomUIGallery 目录下，每次生成维护文档前，你需要认真分析已有的维护文档内容，找出与当前代码库不一致的部分，并根据实际代码修改进行更新。

输入要求

• 本次代码修改的简要描述（例如：“将 ReactiveUI 从旧版本升级到 23.1.8，并重构了 WhenActivated 用法”）
• 修改涉及的文件列表（可由 Git diff 或用户提供）
• 目标文档路径：docs/Maintain/AtomUIGallery
• 如果对应的文档存在，除非大规模修改了文件的内容，尽量在原有文档上修订，而不是创建新文档。

执行步骤

第一步：分析代码修改

1. 请用户提供本次修改的 Git 提交哈希或变更文件列表。如果无法提供，请扫描 Gallery 相关项目项目，对比最近两次提交或最近一次重要提交。
2. 你需要特别注意整体架构的变更，例如新增了哪些核心类、修改了哪些核心类的职责、引入了哪些新的设计模式等，这些都是文档中需要重点更新的内容。
3. 我们底层是基于 ReactiveUI 和 Avalonia 的，所以你需要特别关注与这两个框架相关的变更，尤其是 ReactiveUI 的升级可能会涉及到 WhenActivated、ViewModelActivator、路由机制等方面的变更。
4. 识别变更类型：
   • 全局配置变更（App.xaml.cs、ViewLocator、依赖注入容器等）
   • ViewModel 基类或公共逻辑变更
   • 路由和导航服务的变更
   • 控件演示页面的 ViewModel/View 代码变更（特别是 WhenActivated、ReactiveCommand 等）
   • 包引用升级（.csproj 文件）
5. 提取每个变更的旧写法和新写法，并记录变更原因（例如 API 弃用、性能优化、规范统一）。

第二步：读取现有 Gallery 文档

1. 列出 docs/Maintain/AtomUIGallery 目录下的所有 .md 文件。
2. 对于每个文件，读取其内容并分析其结构（例如章节标题、代码示例、图表等），找出与本次代码修改相关的部分。
3. 如果某些文件不存在，请准备创建它们。

第三步：对比并确定需要更新的文档

对每个现有文档：

• 找出其中与本次代码修改不一致的描述（例如文档中写的是旧的 WhenActivated 签名，但代码已更新为新签名）。
• 找出缺失的内容（例如新引入的 ViewModelActivator 用法未在文档中说明）。
• 标记哪些文档完全过时需要重写，哪些只需局部修改。

第四步：生成或更新文档

遵循以下规则更新文档：

1. 明确标记变更：对于修改的内容，使用 > **【已更新】** 或 [UPDATE: ReactiveUI 23.1.8] 等标记，便于未来追溯。
2. 保留有效旧内容：如果旧文档中某些部分仍然正确（例如项目结构说明、第三方依赖列表），不要删除。
3. 添加迁移指南：如果本次升级涉及破坏性变更，请在 UPGRADE_LOG.md 或单独的 MIGRATION_GUIDE.md 中记录从旧写法到新写法的转换步骤。
4. 更新代码示例：所有代码块中的示例必须与当前代码库中的实际写法一致。
5. 更新架构图：如果架构有变化（例如新增了服务类、改变了数据流），请用 Mermaid 格式更新 ARCHITECTURE.md 中的图表。

第五步：输出文档

将更新后的文档写入以下路径： docs/Maintain/AtomUIGallery 另外，生成一个变更摘要文件：docs/Maintain/AtomUIGallery/CHANGELOG_DOCS.md，内容为表格形式，列出每个文档文件的变更类型（新增/修改/删除/无变更）和简要说明。

第六步：向用户报告

完成后，输出以下信息：

• 本次更新的文档列表
• 每个文档的主要变更点摘要（3-5 条）
• 如果有任何无法自动决策的内容（例如矛盾信息、缺失信息），请明确指出并请求用户提供补充。

注意事项

• 不要凭空捏造：所有文档内容必须基于实际代码修改，不能猜测或加入未实现的设计。
• 保持一致性：文档中的术语、命名规范应与代码保持一致。
• 优先使用官方术语：ReactiveUI 相关概念（如 WhenActivated、ViewModelActivator、RoutableViewModel）应使用官方名称。
• 如果用户提供了额外的参考文档（如 .referenceprojects/ReactiveUI 中的官方指南），应优先参考它们来解释变更。

示例执行流程（供 Agent 参考）

假设本次升级是将 ReactiveUI 从 11.0.10 升级到 23.1.8，主要变化是将所有 WhenActivated 的用法从旧委托形式改为新的 disposables 参数形式，并且 ViewLocator 实现有调整。

Agent 应：

1. 扫描所有 .cs 文件，找出所有 WhenActivated 的旧写法（例如 WhenActivated(d => { ... })）已被改为新写法（WhenActivated(disposables => { ... })）。
2. 扫描 docs/Maintain/AtomUIGallery 路径下已经存在的文档的所有文档，根据扫描代码得到的变更点，找出哪些文档中提到了 WhenActivated 的旧写法，并标记需要更新。
3. 生成 CHANGELOG_DOCS.md，列出上述修改。
4. 向用户报告完成情况。

附：推荐的文档结构（供创建新文档时参考）

如果某个文档不存在，按以下模板创建：

• ARCHITECTURE.md：项目整体架构（Mermaid 图）、模块职责、数据流、外部依赖。
• CODING_STANDARDS.md：命名规范、ReactiveUI 使用规范（WhenActivated、ReactiveCommand、路由）、XAML 规范、异常处理。
• ROUTING.md：路由注册方式、导航服务使用示例、ViewLocator 配置。
• UPGRADE_LOG.md：按时间倒序记录每次升级（包版本、变更摘要、迁移说明）。
• MAINTENANCE.md：常见维护任务（添加新页面、修复 Bug）、调试技巧、验证清单。