Files

home-PC bbc183cef6 test: 增加工具箱本地验证覆盖

新增不依赖外部 NuGet 的测试项目，覆盖快捷键解析、组合校验、路径和网址校验，以及配置读写、导出和数据版本策略。

同步维护 development.md，记录本轮完成情况、后续可选打磨点和最新验证命令。

2026-05-27 14:59:07 +08:00

8.4 KiB

Raw Permalink Blame History

个人工具箱开发文档

当前项目状态

项目名称：Personal Toolbox / PersonalToolbox
技术栈：WPF + .NET 8 + C#
架构方向：MVVM 分层，UI 层通过 ViewModel 调用服务层
当前阶段：MVP 主要能力已补齐，可编译运行并具备本地测试覆盖
主要入口：src/PersonalToolbox/MainWindow.xaml
配置目录：%AppData%\PersonalToolbox

已实现能力

基础工程
- PersonalToolbox.sln
- src/PersonalToolbox/PersonalToolbox.csproj
- WPF 桌面应用，启用 WinForms 托盘能力
- 内部命名空间、项目路径、启动项名称和配置目录已统一为 PersonalToolbox
数据与配置
- 本地 JSON 配置读写
- 原子写入：先写 .tmp，再替换正式文件
- dataVersion 当前为 2，加载和导入时会拒绝高于当前支持版本的配置
- 配置文件：
  - appsettings.json
  - categories.json
  - tools.json
  - autorun.json
  - icons/
- 导入、导出、重置配置基础能力
- 导出配置只打包目标配置文件和 icons 目录，不包含 backups 等运行期备份目录
- 路径失效检查会输出具体工具、字段、原因和路径
工具模型
- 系统工具
- 本地工具
- 网址工具
- 组合工具
- 一级分类
- 自动运行项
- 快捷键配置和状态
默认系统工具
- 首次创建系统工具分类和未分类
- 内置记事本、计算器、任务管理器、控制面板、设置、Windows 更新、设备管理器、磁盘管理、服务、注册表、网络连接和应用列表
- 设置页支持补回缺失默认系统工具
启动服务
- 所有入口统一走 ToolLaunchService
- 本地工具使用 Windows Shell 打开
- 网址使用默认浏览器打开
- 系统工具使用内置启动目标
- 支持管理员启动配置
- 启动结果输出到底部信息区
组合与自动运行
- 组合成员引用已有工具或组合
- 支持成员启用、禁用、排序、间隔
- 支持失败后继续或停止
- 保存前检测循环引用和展开后重复工具
- 自动运行列表从工具自身 AutoRunEnabled 动态汇总
托盘、自启和快捷键
- 托盘常驻服务
- 托盘菜单：显示/隐藏主界面、全局快捷键开关、设置、退出
- 关闭窗口时隐藏到托盘
- 当前用户开机自启，注册表值名为 PersonalToolbox
- 全局快捷键注册、注销、内部冲突和注册失败提示
界面
- 顶部搜索和操作按钮
- 左侧一级分类
- 右侧工具卡片网格
- 底部信息输出区
- 工具编辑窗口
- 组合编辑窗口
- 设置窗口
- 外观设置页：主题、卡片大小、界面缩放、是否显示工具说明
- 轻量图标库、图标选择器、本地图标导入、自定义图标目录和本地工具关联图标缓存
- 工具和组合编辑窗口支持捕获式快捷键录入与清除
- 主界面卡片右键菜单支持启动、编辑、重命名、复制、移动分类、切换自动运行、修改路径和删除
- 分类支持图标编辑；分类和卡片支持拖拽排序，工具可拖拽移动到分类
- 主要 UI 元素均提供 ToolTip 悬浮说明

与产品设计文档对照后的完成情况

以下内容来自 windows_personal_toolbox_product_design.md 与当前项目实现之间的对照结果。

图标系统
- 已提供轻量内置图标库、工具/组合/分类图标选择器、本地图片 / ico 导入和 icons/custom 存储。
- 本地工具会尽量从目标文件提取关联图标并缓存到 icons/cache；提取失败时按文件类型回退到内置图标。
- 第一版不做 favicon 下载和在线图标市场。
外观设置
- 设置页已接入跟随系统 / 浅色 / 深色主题、卡片大小、界面缩放和是否显示工具说明。
- 主界面保存设置后即时应用外观变化。
拖拽与卡片管理
- 分类支持拖拽排序。
- 工具卡片支持拖拽排序，也可拖到左侧分类完成移动。
- 卡片右键菜单已补齐启动、编辑、重命名、复制、移动分类、切换启动时自动运行、修改路径和删除。
快捷键录入
- 工具编辑、组合编辑和设置页快捷键管理均支持捕获式录入和清除。
- 仍保留文本校验，便于用户直接粘贴或手动修正快捷键。
导入导出和数据版本
- dataVersion 已升级为 2。
- 加载和导入时会校验数据版本，拒绝当前应用不支持的更高版本。
- 导出配置仅包含设计文档要求的配置文件和 icons 目录，不导出 backups。
测试覆盖
- 新增 tests/PersonalToolbox.Tests 本地测试项目，不依赖外部 NuGet 包。
- 已覆盖快捷键解析、组合校验、路径/网址校验、配置读写、导出排除备份目录和数据版本拒绝策略。

后续可选打磨：

为组合成员和自动运行列表补充原生拖拽排序，目前仍保留稳定的上移 / 下移按钮。
继续细化图标提取策略，例如快捷方式目标图标和更多系统文件类型图标。
增加 UI 自动化或截图验收，覆盖托盘、弹窗和拖拽等桌面交互。

运行与验证

构建：

dotnet build PersonalToolbox.sln

运行：

dotnet run --project src\PersonalToolbox\PersonalToolbox.csproj

当前验证结果：

dotnet build PersonalToolbox.sln
0 个警告
0 个错误

dotnet run --project tests\PersonalToolbox.Tests\PersonalToolbox.Tests.csproj
PASS 快捷键解析和捕获格式化
PASS 组合校验覆盖循环、重复和缺失引用
PASS 路径和网址校验
PASS 配置读写、导出和数据版本校验

目录说明

src/PersonalToolbox
├─ Commands       命令封装
├─ Models         工具、分类、组合、配置、日志等模型
├─ Services       配置、启动、托盘、自启、快捷键、路径校验等服务
├─ ViewModels     主界面和卡片视图模型
└─ Views          编辑、组合、设置和提示窗口

tests/PersonalToolbox.Tests
└─ Program.cs     轻量本地测试入口，不依赖外部测试框架

开发需知

不要绕过 ToolLaunchService 写启动逻辑。
组合只保存成员工具 ID，不复制工具内容。
普通错误优先输出到底部信息区，只有删除、导入覆盖、重置、退出等操作使用确认弹窗。
默认系统工具只在首次配置创建或用户主动恢复时补回，避免覆盖用户删除/隐藏意图。
所有新增可交互 UI 控件都应提供 ToolTip。
配置写入必须保持原子写入策略，避免中途失败写坏 JSON。
快捷键必须包含至少一个修饰键，不支持纯单键快捷键。
开机自启只写当前用户注册表，不要求管理员权限。
本项目尚未投入使用，不需要维护旧临时代号对应配置目录的兼容迁移。

Git 记录约定

提交信息使用 Conventional Commits 格式，并使用中文说明标题和正文：

feat: 添加某项用户能力

说明本次变更做了什么、为什么这样做，以及是否影响数据结构或用户行为。

常用类型：

feat: 新功能
fix: 修复问题
docs: 文档
chore: 构建、仓库、维护类变更
refactor: 不改变行为的重构
test: 测试相关

8.4 KiB Raw Permalink Blame History Unescape Escape

个人工具箱开发文档

当前项目状态

已实现能力

与产品设计文档对照后的完成情况

最近开发记录

2026-05-27

运行与验证

目录说明

开发需知

Git 记录约定

8.4 KiB

Raw Permalink Blame History