Pixora AGENTS.md

Pixora 接手维护说明

这份文件给后续接手项目的人和 AI 编程助手使用。修改前请先读完本文件、README.md、docs/ARCHITECTURE.md 和 docs/RELEASE.md，再开始动代码。

基本约定

• 用户可见的软件名是 Pixora。
• 源码项目、命名空间、解决方案和发布包统一使用 Pixora，例如 Pixora.sln、src\Pixora、namespace Pixora。
• Pic-O 和 PureView 只作为旧版本兼容名称保留，用于本地数据迁移、历史 Git 记录和必要的发布说明。
• 默认用简体中文写面向用户的说明、错误提示、发布说明和维护文档。
• 代码、类型名、文件名、注册表项、命令和配置键保持原文。
• 项目可以说明“由 AI 辅助编程完成”，但不要写具体 AI 工具、模型、账号、本机用户名、绝对工作目录、测试素材私有路径或访问令牌。
• 不要提交构建产物和本地测试产物：bin/、obj/、publish/、test-output/、.artifacts*/。
• tools\SetUserFTA.exe 是用户自行放置的可选外部工具，不能提交到仓库，也不能默认内置到发布包。

快速命令

dotnet build Pixora.sln
dotnet run --project tests\Pixora.SmokeTests\Pixora.SmokeTests.csproj
.\publish.ps1 -Zip

带外部样本目录的压力测试示例：

dotnet run --project tests\Pixora.SmokeTests\Pixora.SmokeTests.csproj -- --media-folder "D:\Samples" --sample-count 50 --video-sample-count 5

检查仓库状态：

git status --short --branch

接手时先看哪里

• README.md：面向普通用户和开源仓库首页。
• docs\ARCHITECTURE.md：工程结构、核心流程、服务职责、设置文件和技术债。
• docs\RELEASE.md：版本号、构建、测试、发布包检查、GitHub Release 和隐私扫描。
• docs\HANDOFF.md：当前版本状态、接手检查、发布步骤和可安全清理的目录。
• src\Pixora\AppInfo.cs：品牌名、数据目录、文件关联 ProgId、图标路径、旧数据迁移。
• src\Pixora\MainWindow.xaml 和 src\Pixora\MainWindow.xaml.cs：主窗口、打开图片、目录补齐、缩略图栏、快捷键入口、收藏、裁剪、压缩、壁纸、批量删除等大部分用户工作流。
• src\Pixora\Services：图片加载、视频封面、缓存、目录索引、设置、快捷键、文件关联、收藏、压缩和错误日志。
• tests\Pixora.SmokeTests\Program.cs：当前自动测试覆盖面，也是改动后最先跑的回归入口。

重要数据和配置

应用数据目录：

%LOCALAPPDATA%\Pixora

当前会写入或读取的主要文件：

• viewer-settings.json：主设置、缩略图栏、排序、缓存、设置窗口位置、上次目录等。
• shortcuts.json：快捷键配置。
• favorites.json：收藏路径。
• batch-compression-settings.json：批量压缩窗口上次输入和参数。
• error.log：异常日志。
• thumbnail-cache\：可选缩略图磁盘缓存。

旧版本数据目录是：

%LOCALAPPDATA%\Pic-O
%LOCALAPPDATA%\PureView

启动时 App.OnStartup 会调用 AppInfo.EnsureLocalDataMigrated()，只在目标文件不存在时把旧目录里的设置、快捷键、收藏和批量压缩设置复制到新目录。这个迁移是 best-effort，失败不能阻止启动。

修改功能时的检查点

图片或视频格式相关改动：

• 同步检查 ImageCatalog 的扩展名列表。
• 同步检查 FileAssociationService 的扩展名列表。
• 如果是图片解码能力，检查 ImageLoader 的 WIC / Magick.NET 路径。
• 如果是视频封面，检查 VideoThumbnailLoader 和 Shell 缩略图 fallback。
• 更新 README.md 的限制说明和 smoke test。