添加agents指引文件

.agents/Shared/架构分析.md

@@ -0,0 +1,88 @@
+# MeloongCore 项目架构
+
+[返回 MeloongCore 仓库指示](../仓库指示.md)
+
+## 1. 项目定位
+
+`MeloongCore/Shared/MeloongCore.csproj` 是通用 C# 基础库，目标框架为 .NET Standard 2.0，使用 C# 13、Nullable、Implicit Usings 和 PolySharp。
+
+它属于独立 Git 仓库，不应依赖具体上层应用或 WPF。其目标是为 Windows、macOS 及不同上层应用提供一致的基础能力。
+
+## 2. 目录结构
+
+```text
+MeloongCore/Shared/
+├─ Main.cs                  # 库初始化与应用名
+├─ Extensions/             # 集合、字符串、异常、任务和网络扩展
+├─ General/
+│  ├─ Config.cs            # JSON 配置抽象
+│  ├─ Logger.cs            # 日志抽象
+│  ├─ Progress.cs          # 进度模型
+│  ├─ Worker/              # 限流与可重做 Worker
+│  └─ 其他通用数据结构
+└─ Utils/                  # 文件、目录、路径、任务、网络、加密等工具
+```
+
+## 3. 主要能力
+
+### 3.1 文件与路径
+
+`FileUtils`、`DirectoryUtils` 和 `PathUtils` 封装文件读写、压缩包、目录遍历、路径标准化和父子关系判断，供不同上层应用复用。
+
+### 3.2 异步与 Worker
+
+- `TaskUtils` 提供程序执行、并发遍历、聚合等待等通用任务能力；
+- `ProgressProvider` 支持切分与聚合子进度；
+- `RateLimitedWorker` 合并或限制高频调用；
+- `RedoableWorker` 管理可重做的异步工作。
+
+上层应用可以按需使用这些抽象组织异步任务与进度。
+
+### 3.3 配置
+
+`IConfigProvider` 定义读、写、删除、缓存丢弃等能力。默认 `JsonConfigProvider`：
+
+- 从 JSON 文件惰性读取；
+- 缓存反序列化后的值；
+- 通过 Worker 延迟 500 ms 合并写盘；
+- 使用 `ConfigEntry<T>` 提供固定 provider 的强类型配置；
+- 使用 `DynamicConfigEntry<T>` 支持运行时选择 provider。
+
+默认配置位于应用数据目录的 `config.json`，敏感配置 provider 指向 `secret.json`。加密写入目前仍有未实现分支，使用前需要核对现状。
+
+### 3.4 日志与通用类型
+
+库提供可替换的 Logger、并发列表、OneOf、值范围、数学和字符串工具等。上层应用可以替换 Logger 实例，将底层日志接入自身日志系统。
+
+## 4. 依赖
+
+- `Microsoft.Win32.Registry`：跨目标框架暴露注册表能力；
+- `Newtonsoft.Json`：配置与 JSON 工具；
+- `ThrottleDebounce`：限流/防抖基础；
+- `PolySharp`：为旧运行目标补足现代 C# 编译支持。
+
+## 5. 架构边界
+
+适合放入 MeloongCore 的代码应满足：
+
+- 不依赖具体上层应用的页面、全局状态或业务领域；
+- 不直接依赖 WPF 类型；
+- API 对其他 .NET 应用也有合理含义；
+- Windows 专属能力被清楚隔离，不阻塞 macOS 使用通用部分。
+
+WPF 特有实现应进入 `MeloongCore.Wpf`，上层应用特有实现应保留在对应应用仓库中。
+
+## 6. 优势与风险
+
+优势：
+
+- 目标框架和依赖方向支持跨项目复用；
+- 工具与配置已有对应测试；
+- 现代 C# API 提高了新代码的类型安全和可读性。
+
+风险：
+
+- 通用工具类较多，新增 API 时容易形成重复或过宽的职责；
+- 注册表等 Windows 能力出现在 Shared 中，需要保持调用层面的平台防护；
+- `JsonConfigProvider` 加密写入尚未实现完整；
+- 作为公共依赖修改时，需要考虑已有引用方的兼容性和独立发布节奏。

.agents/Tests/架构分析.md

@@ -0,0 +1,43 @@
+# MeloongCore.Tests 项目架构
+
+[返回 MeloongCore 仓库指示](../仓库指示.md)
+
+## 1. 项目定位
+
+`MeloongCore/Tests/MeloongCore.Tests.csproj` 是基于 TUnit 的 .NET Framework 4.8 测试程序，同时引用 `MeloongCore` 与 `MeloongCore.Wpf`。
+
+它主要保护通用基础库，不覆盖引用本库的上层应用业务。
+
+## 2. 测试范围
+
+| 测试文件 | 覆盖能力 |
+| --- | --- |
+| `General/ConfigTest.cs` | JSON 配置读写、默认值与缓存 |
+| `General/ProgressTest.cs` | 进度切分与聚合 |
+| `General/WorkerTest.cs` | Worker 调度、限流或重做语义 |
+| `Utils/CryptographyUtilsTest.cs` | 加密工具 |
+| `Utils/DirectoryUtilsTest.cs` | 目录操作 |
+| `Utils/FileUtilsTest.cs` | 文件与压缩包处理 |
+| `Utils/PathUtilsTest.cs` | 路径规范化和关系判断 |
+| `Utils/TaskUtilsTest.cs` | 异步任务与进程能力 |
+| `TestUtils.cs` | 测试公共支持 |
+
+`TestFiles/FileUtils` 中包含正常、损坏、不同编码和恶意路径的压缩包样本，用于验证 Zip Slip 等边界。
+
+## 3. 项目特点
+
+- 输出类型为 `Exe`，由 TUnit 测试运行机制执行；
+- 测试资源复制到输出目录；
+- 同时引用 WPF 层，因此可以覆盖少量 WPF 相关基础能力。
+
+## 4. 测试缺口
+
+当前测试主要集中于 Shared 的通用工具、配置、进度与 Worker，Wpf 层的平台行为覆盖仍较少。
+
+## 5. 建议
+
+测试范围应保持在 MeloongCore 的公共行为内：
+
+1. 保持本项目只测试 MeloongCore 与 WPF 适配层；
+2. 上层应用的业务测试由对应应用仓库维护；
+3. 新增公共能力时，优先补充与其行为和平台边界相对应的测试。

.agents/Wpf/架构分析.md

@@ -0,0 +1,51 @@
+# MeloongCore.Wpf 项目架构
+
+[返回 MeloongCore 仓库指示](../仓库指示.md)
+
+## 1. 项目定位
+
+`MeloongCore/Wpf/MeloongCore.Wpf.csproj` 是 MeloongCore 的 WPF/Windows 适配层，面向 .NET Framework 4.8，依赖 `MeloongCore`。
+
+它的存在使 Shared 项目无需引用 WPF，同时让多个上层 WPF 应用复用窗口、对话框、转换器与 Windows API 封装。
+
+## 2. 源码组成
+
+| 文件 | 职责 |
+| --- | --- |
+| `Main.cs` | WPF 层初始化 |
+| `Controls/ModernTooltipService.cs` | 现代化 ToolTip 行为 |
+| `Extensions/WpfExtensions.cs` | WPF 对象和控件扩展 |
+| `General/Dialogs.cs` | 文件、文件夹和消息对话框封装 |
+| `General/ValueConverters.cs` | WPF Binding 值转换器 |
+| `Utils/WindowsUtils.cs` | Windows 权限、窗口和系统相关工具 |
+
+## 3. 依赖
+
+- `MeloongCore`；
+- WPF 的 `PresentationCore`、`PresentationFramework`、`System.Xaml`；
+- `System.Windows.Forms`，用于部分 Windows UI 互操作；
+- `Ookii.Dialogs.Wpf`；
+- `Newtonsoft.Json` 与 PolySharp。
+
+## 4. 架构边界
+
+此项目适合承载“可被多个 WPF 应用复用”的平台代码，例如：
+
+- WPF 控件扩展和附加行为；
+- 通用值转换器；
+- Windows 窗口与权限操作；
+- 文件夹选择等系统对话框。
+
+它不适合承载：
+
+- 特定上层应用的控件外观或页面逻辑；
+- 具体应用的领域业务；
+- 只被一个调用点使用的小型包装；
+- 可以留在 Shared 的纯 .NET 逻辑。
+
+## 5. 维护关注点
+
+- 本项目承载 Windows/WPF 特有能力，而 Shared 仍需考虑 macOS；平台 API 必须留在本项目或明确受保护的代码路径中。
+- `System.Windows.Forms` 与 WPF 混用时要注意 DPI、窗口句柄和线程模型。
+- 该项目由多个上层应用和 Tests 引用，公共 API 变更影响面较大。
+- 应避免把具体上层应用的全局日志、设置或窗口实例反向引入本项目。

.agents/仓库指示.md

@@ -0,0 +1,33 @@
+# MeloongCore 仓库指示
+
+## 沟通与环境
+
+- 使用中文沟通。
+- 开发环境可以是 Windows；通用代码需要同时考虑 Windows 与 macOS。
+- 文本文件统一使用 UTF-8 无 BOM；PowerShell 读写文本时显式指定 `-Encoding UTF8`。
+
+## 技术栈
+
+- 使用 C# 13、Nullable、Implicit Usings 和 PolySharp。
+- `Shared` 面向 .NET Standard 2.0，不依赖 WPF。
+- `Wpf` 与 `Tests` 面向 .NET Framework 4.8。
+- 保持现代、清晰的 C# 写法，但不做过度抽象、优化或防御性检查。
+- 简化类结构，少留空行，但保留必要的注释。
+- 修改已有代码时优先保持最小改动，并删除修改后确定无用的内容。
+- 不添加只有一两行的小型辅助方法；仅有一个引用的方法或变量应积极考虑内联。
+
+## 项目边界
+
+- `Shared` 只存放可跨产品复用的通用能力，不得依赖具体上层应用的业务领域或 UI 页面。
+- Windows 与 WPF 特有功能优先放入 `Wpf`，避免破坏 Shared 的 macOS 可用性。
+- `Tests` 负责保护 Shared 与 Wpf 的公共行为，不应反向依赖引用本库的上层应用项目。
+- 新增工具前先检查现有 Extensions、General 和 Utils，避免重复实现。
+- 公共 API 会影响所有引用方，修改签名或语义前应检查兼容性。
+
+## 仓库安全
+
+- MeloongCore 是独立 Git 仓库，提交内容不得依赖特定引用方的私有目录结构或开发流程。
+- 在受控工作区中操作文件或执行构建命令时，使用环境要求的受控权限。
+- 构建 WPF 工程时使用 Visual Studio 2022 的 `MSBuild.exe`。
+- 保留用户已有的未提交修改，不覆盖或清理无关文件。
+- 不提交密钥、访问令牌、构建产物、测试结果或本地环境文件。

AGENTS.md

@@ -0,0 +1,9 @@
+# Agents 指南
+
+本仓库的详细开发指示保存在 `.agents` 目录中。
+
+处理本仓库内容前，必须完整读取并遵循：
+
+- [MeloongCore 仓库指示](.agents/仓库指示.md)
+
+该文件是本仓库规则的组成部分，不是可选参考资料。若指示文件无法读取，应先向用户说明，不得自行猜测或忽略缺失的规则。