Add scoped agent guidelines for Snap Hutao repo

AGENTS.md

@@ -0,0 +1,26 @@
+# Snap Hutao repository instructions
+
+## 项目定位
+- Snap Hutao 是基于 WinUI 3 的现代化 .NET 桌面应用，使用最新稳定或预览的 .NET SDK 与 Windows App SDK。任何改动都必须维持现有的目标框架、语言版本与 MSIX 打包设置。
+- 核心目标是在不修改原神客户端的前提下提供工具能力。避免引入破坏性或违反用户隐私的功能。
+
+## 全局开发规范
+- **依赖管理**：优先使用内置 BCL、Windows App SDK 与既有依赖。除非经过维护者确认，不要新增第三方包；如必须添加，请解释原因并确认符合自带签名与 MSIX 发布策略。
+- **代码风格**：遵循 `.editorconfig`、`stylecop.json`、`BannedSymbols.txt` 与分析器要求。严禁通过禁用规则绕过告警；修复或调整实现以满足规则。
+- **语言特性**：保持 `LangVersion=preview`，充分利用现代 C# 特性（例如 required 成员、泛型 math、Span）。禁止退回旧语言模式或关闭 nullable。
+- **异步与并发**：UI 线程保持响应；IO、网络、数据库操作应使用异步 API 并正确处理取消与异常。
+- **错误处理与日志**：使用既有的 `Core.ExceptionService`、`Validation` 与 `Microsoft.Extensions.Logging` 管线。记录的信息需避免泄露凭据或敏感数据。
+- **本地化**：所有用户可见文字必须通过资源实现本地化，且至少提供中文（简体）翻译；可选提供英文。新增字符串时只修改 `Resource/Localization/SH.resx`，不要直接写死文字或修改其他语言资源，这些资源将由 Crowdin 在 PR 合并后同步。
+
+## 工作流
+1. 恢复依赖：`dotnet restore src/Snap.Hutao/Snap.Hutao.sln`
+2. 构建：`dotnet build src/Snap.Hutao/Snap.Hutao.sln -c Debug`
+3. Visual Studio 发布或 CI 打包时不要调整证书、版本策略或安装通道，除非需求明确。
+
+## PR 与提交
+- 所有开发工作必须从 `develop` 分支拉取最新代码并创建功能分支，除非需求明确指定其他基线。
+- 功能与修复需以 `develop` 为目标分支，并附带清晰的变更说明与验证步骤。
+- 提交消息保持简洁、陈述式；避免无意义的“update”或 “fix”。
+- 每次修改仅触及必要文件，保持 PR 易于审查。
+
+本文件适用于整个仓库。若某子目录存在更细的说明，请以就近目录的 `AGENTS.md` 为准。

res/AGENTS.md

@@ -0,0 +1,8 @@
+# res 目录使用说明
+
+适用于仓库根目录下的 `res` 文件夹。
+
+- `res` 用于存放设计稿、宣传图、商店素材等非打包资源。不要从应用运行时代码中直接引用此处的文件。
+- 新增素材需注明来源、分辨率与版权状态，可在提交信息或素材旁的 README 中补充说明。
+- 文件命名采用 `PascalCase` 或 `kebab-case`，避免空格。对于多尺寸版本使用后缀（例如 `_1080p`, `_512px`）。
+- 尽量使用无损压缩格式 (PNG, SVG)。对于体积较大的 PSD/AI，请考虑存储于外部仓库，仅在此保留导出文件。

src/Snap.Hutao/AGENTS.md

@@ -0,0 +1,20 @@
+# Snap Hutao solution guidelines
+
+适用于 `src/Snap.Hutao` 目录及其子目录，除非更深层的 `AGENTS.md` 另有说明。
+
+## 解决方案结构
+- `Snap.Hutao.sln` 是唯一需要维护的顶层解决方案；不要新增额外的解决方案文件，除非经架构评审同意。
+- WinUI 3 主项目位于 `Snap.Hutao/`。保持项目文件中的 `TargetFramework`、`LangVersion` 与 `Nullable` 设置不变。
+- 更新 NuGet 引用时仅提升版本或移除不用的包，禁止降低版本，也不要引入与现有功能重叠的库。
+
+## 构建与配置
+- 所有项目必须能通过 `dotnet build Snap.Hutao.sln -c Debug` 编译。提交前确保解决方案在 Release 模式同样无警告。
+- 需要添加新项目或更改现有项目属性时，确保 CI 可在无 GUI 环境下运行（不要依赖手工步骤）。
+- `.slnx` 与 `ResXManager.config.xml` 由工具生成，除非同步更新配置，否则不要手动编辑。
+
+## 文件组织
+- 代码文件应放入与功能相匹配的项目与命名空间，命名空间必须与文件夹结构保持一致。
+- 所有新增的公共 API 必须在 XML 文档注释中说明用途，并在需要时补充示例或使用说明。
+
+## Git 约定
+- 不要提交临时生成文件（例如 `bin/`、`obj/`、`*.user`）；如遇生成工具创建的新配置文件，请在 `.gitignore` 之前确认是否需要版本控制。

src/Snap.Hutao/Snap.Hutao.Test/AGENTS.md

@@ -0,0 +1,18 @@
+# Snap.Hutao.Test 项目规范
+
+适用于 `Snap.Hutao/Snap.Hutao.Test`。
+
+## 测试框架
+- 使用 MSTest (`[TestClass]`, `[TestMethod]`, `[DataTestMethod]`)。不要混用 xUnit 或 NUnit。
+- 保持 `LangVersion=preview`，可以使用最新 C# 语法，但需确保测试对旧环境无副作用。
+
+## 结构
+- 依照命名空间组织文件，例如 `RuntimeBehavior`, `PlatformExtensions`。新增测试时放入相应子目录或创建新目录，并保持命名清晰。
+- 共用的测试工具、假实现放在 `BaseClassLibrary` 或新的 `Helpers` 文件夹，并避免依赖生产代码中的 UI 组件。
+
+## 编写测试
+- 避免测试之间的状态耦合。使用 `TestInitialize`/`TestCleanup` 或 `ClassInitialize` 进行资源准备与释放。
+- 涉及异步调用的测试使用 `async Task` 并在断言前等待操作完成。对外部依赖要使用 stub/mocks，禁止真实 HTTP 调用。
+
+## 覆盖率
+- 关键业务逻辑的变更须增加测试覆盖，并在 PR 描述中记录测试范围。必要时通过 `Assert.ThrowsException` 验证异常路径。

src/Snap.Hutao/Snap.Hutao/AGENTS.md

@@ -0,0 +1,31 @@
+# Snap Hutao app project instructions
+
+本文件覆盖 WinUI 主项目 `Snap.Hutao` 目录下的所有文件，除非子目录另有 `AGENTS.md`。
+
+## 架构原则
+- 采用 MVVM：视图 (`UI`) 仅负责布局与绑定，`ViewModel` 处理呈现逻辑，`Service` 封装业务与外部依赖，`Model` 描述领域对象，`Core` 与 `Extension` 提供基础设施。
+- 通过 `Microsoft.Extensions.DependencyInjection` 进行依赖注入。新增服务时在 `Core.DependencyInjection` 的配置扩展中注册，保持生命周期与线程安全。
+- 不要引入新的全局单例或静态状态，除非已有模式（例如 `HutaoRuntime`）明确需要。
+- 优先复用现有帮助类、缓存策略与 telemetry。必要的新工具请放入最贴近的命名空间，并补充使用说明或示例。
+
+## WinUI / XAML
+- 所有 `XAML` 文件需配套 `partial` 代码隐藏或 ViewModel，避免在 `x:Code` 中编写逻辑。
+- 使用现有资源字典与样式；新增资源前确认没有重复。对于主题色、图标、动画等公共元素，放入 `Resource` 对应文件夹并在资源字典中引用。
+- 用户可见的文字必须通过资源键绑定；新增时至少提供中文条目，可选补充英文。不要在 XAML 或代码中写死字符串。
+- 避免阻塞 UI 线程；长耗时操作使用 `async` 与 `Task`，必要时借助 `DispatcherQueue` 切回 UI 线程。
+
+## 可维护性
+- 新增公共或内部 API 时补充 XML 注释，并确保名称含义清晰。避免过度缩写。
+- 使用 `partial` 或 `file-scoped namespace` 维持一致的代码风格。保持 `#nullable enable`，不要使用 `#pragma warning disable` 覆盖全局规则。
+- 对于需要非托管互操作的代码，请优先查看 `Win32` 目录的现有封装，并确保 `AllowUnsafeBlocks` 下的代码经过审慎审查。
+
+## 性能与内存
+- 对性能敏感路径使用 `Span<T>`、`Memory<T>` 等现代 API；当需要池化时复用项目中现有的 `ObjectPool` 或 `RecyclableMemoryStream`。
+- 使用 `ValueTask` 与结构体枚举器时注意可重入与重用；避免产生额外装箱或 `LINQ` 分配。
+
+## 资源与本地化
+- 新增图片或二进制资源时应在 `Snap.Hutao.csproj` 中声明，并确保尺寸、缩放级别符合 Fluent 设计指南。
+- 字符串使用 `Resource.Localization` 的 `SH` 资源键，并通过 `XAML` 绑定或 `SH.GetString` 获取。
+
+## 验证
+- 手动验证 UI 变更时需在 PR 描述中说明操作路径与结果。

src/Snap.Hutao/Snap.Hutao/Core/AGENTS.md

@@ -0,0 +1,21 @@
+# Core 层开发规范
+
+适用于 `Snap.Hutao/Core` 目录。
+
+## 角色定位
+- 提供跨领域的基础设施（缓存、IO、并发、序列化、依赖注入扩展等）。任何业务逻辑、UI 逻辑或网络协议实现都不应放在此处。
+- Core 以及整个项目的类型默认保持 `internal`。仅 `Bootstrap`、`App`、Protobuf 自动生成类型以及 XAML 附加属性辅助类可公开为 `public`。
+
+## 编码约定
+- 使用文件作用域命名空间与 `sealed`/`readonly` 修饰符提升性能；对值类型考虑 `readonly struct`。
+- 所有 `unsafe` 代码都必须附带明确注释解释其必要性，并确保运行在 x64。
+- 资源释放采用 `IDisposable`，优先使用 `using` 声明确保确定性清理。
+- 不要在 Core 中直接引用 WinUI 或 ViewModel；若需要与 UI 交互，请通过接口与事件回调在上层实现。
+
+## 性能与诊断
+- 性能敏感操作需避免临时分配；使用 `ArrayPool`, `MemoryPool`, `Span<T>` 等优化。提交前在调试日志中留有诊断入口（如 `ILogger` 扩展）。
+- 对并发工具类需记录线程安全约束，并通过日志或调试开关提供诊断入口。
+
+## 依赖策略
+- 禁止在 Core 中引入新的第三方依赖；若确需使用外部库，请先在更高层封装或使用 BCL 替代方案。
+- 当 Core 类型需要访问配置或运行时参数时，优先使用 `Options` 模式或现有的 `Core.Setting` API。

src/Snap.Hutao/Snap.Hutao/Extension/AGENTS.md

@@ -0,0 +1,17 @@
+# Extension 目录规范
+
+适用于 `Snap.Hutao/Extension`。
+
+## 目的
+- 提供对 .NET BCL、WinUI 控件或项目内部类型的扩展方法。扩展方法必须具备通用性与高可读性，不得包含业务专用逻辑。
+
+## 编码要求
+- 每个文件聚焦在一个扩展目标（例如 `ListExtension`、`StringExtension`），避免杂糅。新增扩展时优先查找是否已有同类实现。
+- 扩展方法应标记为 `static` 且归于 `internal static partial class`，必要时使用 `AggressiveInlining` 提升性能。
+- 对可能引起分配的操作（如 `ToList()`）需在注释中标明成本，并在调用站点考虑替代方案。
+
+## 文档
+- 为每个公开的扩展方法编写 XML 注释，说明行为、输入限制与异常。涉及复杂算法的扩展需记录性能与边界情况，必要时提供使用示例。
+
+## 依赖限制
+- 不得在扩展中引用业务层命名空间（`Service`, `ViewModel`, `Web` 等）。若需要共享逻辑，请将实现拆分到 `Core` 后在此转调。