# 个人工具箱开发文档 ## 当前项目状态 - 项目名称：Personal Toolbox / PersonalToolbox - 技术栈：WPF + .NET 8 + C# - 架构方向：MVVM 分层，UI 层通过 ViewModel 调用服务层 - 当前阶段：MVP 主要能力已补齐，可编译运行并具备本地测试覆盖 - 主要入口：`src/PersonalToolbox/MainWindow.xaml` - 配置目录：`%AppData%\PersonalToolbox` ## 已实现能力 1. 基础工程 - `PersonalToolbox.sln` - `src/PersonalToolbox/PersonalToolbox.csproj` - WPF 桌面应用，启用 WinForms 托盘能力 - 内部命名空间、项目路径、启动项名称和配置目录已统一为 `PersonalToolbox` 2. 数据与配置 - 本地 JSON 配置读写 - 原子写入：先写 `.tmp`，再替换正式文件 - `dataVersion` 当前为 2，加载和导入时会拒绝高于当前支持版本的配置 - 配置文件： - `appsettings.json` - `categories.json` - `tools.json` - `autorun.json` - `icons/` - 导入、导出、重置配置基础能力 - 导出配置只打包目标配置文件和 `icons` 目录，不包含 `backups` 等运行期备份目录 - 路径失效检查会输出具体工具、字段、原因和路径 3. 工具模型 - 系统工具 - 本地工具 - 网址工具 - 组合工具 - 一级分类 - 自动运行项 - 快捷键配置和状态 4. 默认系统工具 - 首次创建系统工具分类和未分类 - 内置记事本、计算器、任务管理器、控制面板、设置、Windows 更新、设备管理器、磁盘管理、服务、注册表、网络连接和应用列表 - 设置页支持补回缺失默认系统工具 5. 启动服务 - 所有入口统一走 `ToolLaunchService` - 本地工具使用 Windows Shell 打开 - 网址使用默认浏览器打开 - 系统工具使用内置启动目标 - 支持管理员启动配置 - 启动结果输出到底部信息区 6. 组合与自动运行 - 组合成员引用已有工具或组合 - 支持成员启用、禁用、排序、间隔 - 支持失败后继续或停止 - 保存前检测循环引用和展开后重复工具 - 自动运行列表从工具自身 `AutoRunEnabled` 动态汇总 7. 托盘、自启和快捷键 - 托盘常驻服务 - 托盘菜单：显示/隐藏主界面、全局快捷键开关、设置、退出 - 关闭窗口时隐藏到托盘 - 当前用户开机自启，注册表值名为 `PersonalToolbox` - 全局快捷键注册、注销、内部冲突和注册失败提示 8. 界面 - 顶部搜索和操作按钮 - 左侧一级分类 - 右侧工具卡片网格 - 底部信息输出区 - 工具编辑窗口 - 组合编辑窗口 - 设置窗口 - 外观设置页：主题、卡片大小、界面缩放、是否显示工具说明 - 轻量图标库、图标选择器、本地图标导入、自定义图标目录和本地工具关联图标缓存 - 工具和组合编辑窗口支持捕获式快捷键录入与清除 - 主界面卡片右键菜单支持启动、编辑、重命名、复制、移动分类、切换自动运行、修改路径和删除 - 分类支持图标编辑；分类和卡片支持拖拽排序，工具可拖拽移动到分类 - 主要 UI 元素均提供 `ToolTip` 悬浮说明 ## 与产品设计文档对照后的完成情况 以下内容来自 `windows_personal_toolbox_product_design.md` 与当前项目实现之间的对照结果。 1. 图标系统 - 已提供轻量内置图标库、工具/组合/分类图标选择器、本地图片 / ico 导入和 `icons/custom` 存储。 - 本地工具会尽量从目标文件提取关联图标并缓存到 `icons/cache`；提取失败时按文件类型回退到内置图标。 - 第一版不做 favicon 下载和在线图标市场。 2. 外观设置 - 设置页已接入跟随系统 / 浅色 / 深色主题、卡片大小、界面缩放和是否显示工具说明。 - 主界面保存设置后即时应用外观变化。 3. 拖拽与卡片管理 - 分类支持拖拽排序。 - 工具卡片支持拖拽排序，也可拖到左侧分类完成移动。 - 卡片右键菜单已补齐启动、编辑、重命名、复制、移动分类、切换启动时自动运行、修改路径和删除。 4. 快捷键录入 - 工具编辑、组合编辑和设置页快捷键管理均支持捕获式录入和清除。 - 仍保留文本校验，便于用户直接粘贴或手动修正快捷键。 5. 导入导出和数据版本 - `dataVersion` 已升级为 2。 - 加载和导入时会校验数据版本，拒绝当前应用不支持的更高版本。 - 导出配置仅包含设计文档要求的配置文件和 `icons` 目录，不导出 `backups`。 6. 测试覆盖 - 新增 `tests/PersonalToolbox.Tests` 本地测试项目，不依赖外部 NuGet 包。 - 已覆盖快捷键解析、组合校验、路径/网址校验、配置读写、导出排除备份目录和数据版本拒绝策略。 后续可选打磨： 1. 为组合成员和自动运行列表补充原生拖拽排序，目前仍保留稳定的上移 / 下移按钮。 2. 继续细化图标提取策略，例如快捷方式目标图标和更多系统文件类型图标。 3. 增加 UI 自动化或截图验收，覆盖托盘、弹窗和拖拽等桌面交互。 ## 最近开发记录 ### 2026-05-27 - 补齐图标系统、外观设置、快捷键捕获、卡片右键菜单、分类图标编辑和主界面拖拽排序。 - `dataVersion` 升级为 2，导入和加载会拒绝更高版本配置；导出配置排除 `backups` 运行期备份目录。 - 新增 `tests/PersonalToolbox.Tests` 本地测试项目，覆盖快捷键、组合校验、路径校验和配置读写/导出/版本策略。 - 验证命令：`dotnet build PersonalToolbox.sln`，结果为 0 警告、0 错误；`dotnet run --project tests\PersonalToolbox.Tests\PersonalToolbox.Tests.csproj`，结果为 4 组测试全部通过。 - 将项目内部名从旧临时代号统一更改为 `PersonalToolbox`，包括目录、项目文件、命名空间、XAML 类名、配置目录、自启注册表值和导出文件名。 - 设计文档中的临时代号和 AppData 路径同步改为 `PersonalToolbox`。 - 路径失效检查从单纯数量扩展为明细报告，设置页导入配置后也会提示具体失效工具。 - 验证命令：`dotnet build PersonalToolbox.sln`，结果为 0 警告、0 错误。 ## 运行与验证 构建： ```powershell dotnet build PersonalToolbox.sln ``` 运行： ```powershell dotnet run --project src\PersonalToolbox\PersonalToolbox.csproj ``` 当前验证结果： ```text dotnet build PersonalToolbox.sln 0 个警告 0 个错误 dotnet run --project tests\PersonalToolbox.Tests\PersonalToolbox.Tests.csproj PASS 快捷键解析和捕获格式化 PASS 组合校验覆盖循环、重复和缺失引用 PASS 路径和网址校验 PASS 配置读写、导出和数据版本校验 ``` ## 目录说明 ```text src/PersonalToolbox ├─ Commands 命令封装 ├─ Models 工具、分类、组合、配置、日志等模型 ├─ Services 配置、启动、托盘、自启、快捷键、路径校验等服务 ├─ ViewModels 主界面和卡片视图模型 └─ Views 编辑、组合、设置和提示窗口 tests/PersonalToolbox.Tests └─ Program.cs 轻量本地测试入口，不依赖外部测试框架 ``` ## 开发需知 - 不要绕过 `ToolLaunchService` 写启动逻辑。 - 组合只保存成员工具 ID，不复制工具内容。 - 普通错误优先输出到底部信息区，只有删除、导入覆盖、重置、退出等操作使用确认弹窗。 - 默认系统工具只在首次配置创建或用户主动恢复时补回，避免覆盖用户删除/隐藏意图。 - 所有新增可交互 UI 控件都应提供 `ToolTip`。 - 配置写入必须保持原子写入策略，避免中途失败写坏 JSON。 - 快捷键必须包含至少一个修饰键，不支持纯单键快捷键。 - 开机自启只写当前用户注册表，不要求管理员权限。 - 本项目尚未投入使用，不需要维护旧临时代号对应配置目录的兼容迁移。 ## Git 记录约定 提交信息使用 Conventional Commits 格式，并使用中文说明标题和正文： ```text feat: 添加某项用户能力 说明本次变更做了什么、为什么这样做，以及是否影响数据结构或用户行为。 ``` 常用类型： - `feat`: 新功能 - `fix`: 修复问题 - `docs`: 文档 - `chore`: 构建、仓库、维护类变更 - `refactor`: 不改变行为的重构 - `test`: 测试相关