Files

home-PC 26a22eef1c feat: 统一项目命名并补充路径失效报告

将内部项目目录、命名空间、配置目录、自启注册表值和设计/开发文档统一为 PersonalToolbox。

扩展路径校验服务，输出失效工具、字段、原因和路径，并在启动日志、设置页路径检查与导入配置流程中展示明细报告。

验证：dotnet build PersonalToolbox.sln

2026-05-27 14:20:19 +08:00

49 KiB

Raw Permalink Blame History

Windows 个人工具箱软件开发设计文档

本文档用于指导 Codex 或其他代码生成工具进行开发。
目标是开发一款轻量、稳定、常驻托盘、支持系统工具、本地工具、网址、组合、自动运行和全局快捷键的 Windows 平台个人工具箱软件。
本软件不是软件管家、不是任务调度器、不是插件平台、不是进程监控器，而是一个面向个人高频使用场景的本地工具启动与组合管理器。

1. 产品概述

1.1 产品名称

暂定名：个人工具箱 / Personal Toolbox

实际开发时可使用临时代号：

PersonalToolbox

1.2 产品定位

本软件是一款 Windows 平台个人工具箱应用，主要用于集中管理和快速启动用户常用的系统工具、本地程序、本地文件、文件夹、脚本、网址，以及由多个工具组成的组合。

软件常驻系统托盘，可设置开机自启。用户可以通过托盘图标显示或隐藏主界面，也可以通过全局快捷键直接启动某个工具或组合。

1.3 核心价值

本软件要解决的问题不是“发现软件”，而是“整理和快速启动用户已经知道自己需要的东西”。

核心价值包括：

集中管理
将系统工具、本地工具、网址、组合集中在一个统一界面中。
快速启动
用户通过双击卡片、快捷键、组合、启动时自动运行等方式快速打开目标。
组合启动
用户可以把多个工具打包为组合，例如“一键打开剪辑环境”“一键打开开发环境”。
托盘常驻
软件长期隐藏在托盘，不占用任务栏空间，随时可唤出。
开机自动运行
工具箱可设置开机自启，并在启动后按用户设置自动运行指定工具或组合。
轻量可控
不做自动扫描，不做云同步，不做复杂插件系统，不做过度功能。

2. 设计原则

2.1 轻量优先

软件应保持轻量。功能服务于“启动和组合启动工具”，不要扩展成软件管家、脚本平台或自动化平台。

2.2 本地优先

所有数据保存在本地配置文件中。第一版不做账号、不做云同步、不依赖远程服务。

2.3 用户可理解优先

用户界面上不应暴露过多技术概念。
例如 exe、lnk、bat、cmd、mp4、docx、文件夹等，在用户侧统一称为“本地工具”。软件内部可自动判断子类型，但用户添加时不需要理解这些差异。

2.4 避免误操作

工具卡片采用：

单击 = 选中
双击 = 启动

不要单击即启动，避免用户误触导致程序、组合或多个工具被打开。

2.5 组合使用引用，不自包含

组合内部只保存工具或组合的 ID 引用，不复制工具内容。
这样工具改名、换路径、换图标后，所有引用该工具的组合都会同步生效。

2.6 不弹窗打断用户

普通启动信息、组合执行进度、自动运行结果、错误提示，统一输出到主界面底部的信息输出区。
除删除确认、重大破坏性操作、必要系统权限提示外，尽量不弹窗。

2.7 所有启动入口行为一致

无论用户通过双击卡片、全局快捷键、组合、启动时自动运行触发工具，都必须统一走同一个启动服务。

建议核心服务命名：

ToolLaunchService

3. MVP 范围

3.1 第一版必须包含

第一版必须实现以下功能。

3.1.1 托盘常驻

软件可以常驻系统托盘。
支持设置开机自启。
启动后可默认隐藏到托盘。
单击托盘图标显示 / 隐藏主界面。
关闭主窗口时隐藏到托盘，不退出软件。
真正退出只能通过托盘右键菜单中的“退出”。
托盘菜单保持极简：
- 显示 / 隐藏主界面
- 全局快捷键开启 / 关闭
- 设置
- 退出

3.1.2 主界面

主界面采用：

顶部搜索与操作按钮
左侧一级分类
右侧卡片网格
底部信息输出区

主界面必须支持：

搜索工具。
显示分类。
显示工具卡片。
单击卡片选中。
双击卡片启动。
右键卡片管理。
底部信息输出。
基础键盘操作。

3.1.3 工具类型

用户侧只暴露四类：

系统工具
本地工具
网址
组合

其中：

exe、lnk、bat、cmd、普通文件、文件夹都统一归为本地工具。
Microsoft Store 应用第一版建议通过快捷方式 .lnk 添加，也归为本地工具。
组合也是一种工具，也以卡片形式展示。

3.1.4 系统工具

软件首次启动时默认创建“系统工具”分类。
常见 Windows 系统工具默认全部显示在该分类中。
用户可以改名、换图标、移动分类、设置快捷键、设置是否自动运行。
用户可以删除或隐藏默认系统工具。
设置界面提供“一键恢复默认系统工具”。
恢复默认系统工具时，只补回缺失项，不重复创建已有项。

3.1.5 本地工具

本地工具包括：

exe 程序
lnk 快捷方式
bat / cmd 脚本
普通文件
文件夹
Microsoft Store 应用快捷方式
其他可由 Windows Shell 打开的目标

本地工具第一版尽量使用 Windows Shell 打开，由 Windows 决定具体打开方式。

3.1.6 网址工具

用户可以添加 URL。
启动时使用系统默认浏览器打开。
第一版不需要支持指定浏览器打开。

3.1.7 组合工具

组合工具必须支持：

引用已有工具或组合。
允许嵌套组合。
检测循环引用。
检测展开后重复工具。
设置成员顺序。
设置成员之间的时间间隔。
临时启用 / 禁用某个成员。
设置失败处理方式：
- 失败后继续执行后续成员。
- 失败后停止整个组合。
组合本身可设置全局快捷键。
组合本身可加入工具箱启动时自动运行。

3.1.8 工具箱启动时自动运行

每个工具或组合自身可设置：

工具箱启动时自动运行：是 / 否

设置界面动态汇总所有启用自动运行的工具和组合，形成自动运行列表。

自动运行列表支持：

调整执行顺序。
设置每项之间的时间间隔。
临时启用 / 禁用。
从自动运行中移除。

自动运行列表不提供失败中断功能。
某项失败后，记录到底部信息区，然后继续执行下一项。
如果某项是组合，则组合内部是否中断由组合自身的失败处理规则决定。

3.1.9 全局快捷键

每个工具和组合都可以设置一个全局快捷键。

要求：

快捷键仅在工具箱运行时生效。
支持设置界面统一管理快捷键。
支持工具编辑界面单独设置快捷键。
托盘菜单和设置界面都提供全局快捷键总开关。
关闭总开关时，所有快捷键临时失效，但不删除配置。
开启总开关时重新注册快捷键。
必须检测软件内部快捷键冲突。
必须处理系统注册失败，例如被其他软件占用。
第一版不支持单键快捷键，要求至少包含一个修饰键。

建议支持的修饰键：

Ctrl
Alt
Shift
Win

3.1.10 数据保存

使用本地 JSON 文件保存。
不做数据库。
不做账号。
不做云同步。
图标文件单独保存在 icons 目录。
支持导入配置。
支持导出配置。
支持重置配置。
支持打开配置目录。
导入配置后检测路径失效。

3.1.11 图标

默认自动获取图标。
exe 尽量提取程序图标。
lnk 尽量读取快捷方式图标或目标图标。
文件使用系统默认文件类型图标。
文件夹使用文件夹图标。
网址使用默认链接图标，后续可扩展 favicon。
组合使用内置组合图标。
系统工具使用内置系统工具图标。
提供轻量内置图标库。
用户可以从图标库选择图标。
用户可以选择本地图片或 ico 作为图标。
分类也可以设置图标。

3.2 第一版明确不做

第一版不做以下功能：

插件系统。
账号系统。
云同步。
自动扫描已安装软件。
自动扫描开始菜单。
复杂脚本命令编辑器。
直接输入命令作为工具。
多级分类。
托盘菜单中的最近使用工具。
托盘菜单中的常用工具。
复杂历史日志管理。
进程监控。
判断目标程序运行后是否崩溃。
判断脚本业务执行是否成功。
对工具启动结果做深度跟踪。
插件市场。
图标素材市场。
多用户权限系统。

4. 技术方向

4.1 推荐技术栈

建议使用：

WPF + .NET

开发语言：

C#

架构模式建议：

MVVM

UI 风格建议：

现代 Fluent 风格

可以使用成熟 WPF UI 控件库，但不应让控件库决定业务结构。业务层应保持独立。

4.2 为什么选择 WPF / .NET

原因：

与 Windows 系统集成自然。
托盘图标、自启、快捷键、进程启动、文件路径处理都方便。
比 Electron 更轻量。
适合个人工具箱这种常驻桌面软件。
后续维护成本低。

4.3 权限策略

工具箱自身默认以普通权限运行。

每个工具可以单独配置：

以管理员身份运行：是 / 否

组合执行时，每个成员按自己的权限配置启动。
组合本身不统一提权。

如果用户启动某个需要管理员权限的工具，则由 Windows 弹出 UAC。
用户取消 UAC 时，启动失败信息写入底部信息区。

5. 用户界面设计

5.1 主界面总体结构

主界面结构：

┌────────────────────────────────────────────┐
│ 顶部：搜索框 + 操作按钮                     │
├──────────────┬─────────────────────────────┤
│ 左侧分类列表  │ 右侧工具 / 组合卡片网格       │
│              │                             │
├──────────────┴─────────────────────────────┤
│ 底部信息输出区                              │
└────────────────────────────────────────────┘

5.1.1 顶部区域

顶部包含：

搜索框
添加工具
添加组合
启动
编辑
删除
设置

建议布局：

[搜索工具...]                         [添加工具] [添加组合] [启动] [编辑] [删除] [设置]

按钮行为：

未选中卡片时，“启动 / 编辑 / 删除”禁用。
选中卡片后，“启动 / 编辑 / 删除”启用。
搜索框支持 Ctrl + F 聚焦。

5.1.2 左侧分类列表

分类只支持一级分类。

分类功能：

新建分类。
重命名分类。
删除分类。
拖拽排序。
设置分类图标。
每个工具或组合只能属于一个分类。

默认分类：

系统工具
未分类

规则：

“未分类”固定存在，不允许删除。
“系统工具”首次启动时创建。
“系统工具”可以改名，可以调整排序。
如果恢复默认系统工具时“系统工具”分类不存在，则自动重新创建。

删除分类时：

不直接删除其中工具。
应提示用户：该分类中的工具将移动到“未分类”。
用户确认后执行移动。

5.1.3 右侧卡片网格

卡片显示内容：

图标
名称
简短说明
类型标记
状态标记

类型标记包括：

系统
本地
网址
组合

状态标记包括：

路径失效
已设快捷键
自动运行
管理员

卡片交互：

单击：选中
双击：启动
右键：打开菜单
拖拽：排序或移动分类

右键菜单建议：

启动
编辑
重命名
复制
移动到分类
加入 / 取消工具箱启动时自动运行
删除

5.1.4 底部信息输出区

底部信息区常驻主界面底部。

用途：

显示普通工具启动结果。
显示组合执行进度。
显示自动运行执行结果。
显示启动失败原因。
显示快捷键注册失败。
显示导入导出结果。
显示路径失效检查结果。
显示系统工具恢复结果。

信息格式建议：

[10:21:03] 启动组合：剪辑工作区
[10:21:03] ✓ 打开：素材文件夹
[10:21:04] ✓ 打开：剪映
[10:21:07] ✕ 打开失败：音乐素材库，路径不存在
[10:21:07] 继续执行后续工具
[10:21:08] ✓ 打开：浏览器参考页
[10:21:08] 组合执行完成：成功 3 项，失败 1 项

底部信息区功能：

清空。
复制。
折叠 / 展开。
默认只保存本次运行日志。

第一版不需要复杂历史日志系统。

5.2 工具编辑弹窗

工具编辑弹窗用于编辑：

系统工具
本地工具
网址工具

组合工具使用单独的组合编辑界面。

5.2.1 基础字段

所有普通工具都包含：

名称
图标
所属分类
说明 / 备注
快捷键
是否工具箱启动时自动运行

快捷键区域：

快捷键：未设置
[录入快捷键] [清除]

自动运行区域：

□ 工具箱启动时自动运行

注意：普通工具编辑界面不设置自动运行延迟。
自动运行顺序与间隔统一在设置界面的自动运行列表中管理。

5.2.2 系统工具字段

系统工具显示：

系统工具标识
内置启动方式
是否管理员运行

系统工具的启动标识可以显示，但默认不建议用户修改。

允许用户修改：

名称
图标
分类
说明
快捷键
是否自动运行
是否管理员运行

5.2.3 本地工具字段

本地工具显示：

目标路径
工作目录
启动参数
是否以管理员身份运行

高级设置默认折叠。

建议显示逻辑：

exe / bat / cmd / lnk：显示启动参数、工作目录、管理员运行。
普通文件：隐藏或折叠启动参数、工作目录。
文件夹：隐藏启动参数。
未知类型：优先交给 Windows Shell 打开。

5.2.4 网址工具字段

网址工具显示：

网址

第一版只使用默认浏览器打开，不做指定浏览器。

5.3 组合编辑界面

组合编辑界面建议使用较大的独立窗口，不建议塞进普通工具编辑弹窗。

5.3.1 组合基础字段

组合包含：

组合名称
图标
所属分类
说明 / 备注
快捷键
是否工具箱启动时自动运行

5.3.2 组合成员列表

组合成员只能从已有工具或组合中选择。

组合成员字段：

成员工具 ID
是否启用
排序
当前成员执行后等待间隔

界面上建议显示：

启用 | 图标 | 名称 | 类型 | 间隔 | 操作

支持：

添加成员。
移除成员。
启用 / 禁用成员。
拖拽调整顺序。
设置成员执行后的等待间隔。

5.3.3 组合失败处理

组合级设置：

失败处理方式：
○ 某项失败后继续执行后续工具
○ 某项失败后停止执行整个组合

默认建议：

失败后继续执行

5.3.4 组合校验

保存组合前必须校验：

是否存在循环引用。
展开后是否存在重复工具。
成员引用是否有效。
成员是否引用已删除工具。

如果校验失败，不允许保存，并提示具体原因。

提示示例：

无法保存组合“开发环境”，因为它会导致重复工具：
- VS Code
- 项目文件夹

无法保存组合“日常工作区”，因为它会导致循环引用：
日常工作区 -> 文档工作区 -> 日常工作区

5.4 设置界面

设置界面建议按左侧导航或顶部 Tab 分组。

5.4.1 常规设置

包含：

启动后是否默认隐藏到托盘。
关闭窗口时隐藏到托盘。
是否显示退出确认。
主界面默认宽高。
底部信息区默认展开 / 折叠。

5.4.2 启动与托盘

包含：

是否开机自启。
托盘单击行为：显示 / 隐藏主界面。
托盘菜单配置。

托盘菜单固定保持极简：

显示 / 隐藏主界面
全局快捷键：开启 / 关闭
设置
退出

5.4.3 自动运行列表

自动运行列表不是独立任务编排器，而是自动汇总所有设置为“工具箱启动时自动运行”的工具和组合。

显示字段：

启用
顺序
工具名称
工具类型
间隔
操作

支持：

调整顺序。
设置间隔。
临时启用 / 禁用。
从自动运行中移除。

注意：

从自动运行中移除，等价于把该工具的 autoRunEnabled 设置为 false。
自动运行列表不提供失败中断功能。
某项失败后继续执行下一项。

5.4.4 快捷键管理

显示所有已设置快捷键的工具和组合。

字段：

快捷键
工具名称
工具类型
状态
操作

支持：

修改快捷键。
清除快捷键。
检测冲突。
全局启用 / 禁用快捷键。

快捷键状态包括：

正常
内部冲突
系统注册失败
已禁用

5.4.5 数据与备份

包含：

打开配置目录。
导出全部配置。
导入配置。
重置配置。
检查路径失效。

导入配置后应自动检查路径失效。
路径失效的工具不删除，只标记。

5.4.6 外观设置

第一版支持：

主题：跟随系统 / 浅色 / 深色。
卡片大小：小 / 中 / 大。
界面缩放。
是否显示工具说明。

5.4.7 系统工具恢复

提供按钮：

恢复默认系统工具

恢复规则：

不清空用户现有工具。
不覆盖用户自定义工具。
不重复添加已有默认系统工具。
只补回缺失的默认系统工具。
恢复后默认放入“系统工具”分类。
如果“系统工具”分类不存在，则自动重新创建。

5.5 图标选择器

图标选择器用于：

工具图标。
组合图标。
分类图标。

支持：

自动获取
从内置图标库选择
选择本地图片 / ico
恢复默认图标

5.5.1 内置图标库分类

建议内置图标库分组：

系统
- 设置
- 终端
- 任务管理器
- 控制面板
- 注册表
- 磁盘
- 服务
文件
- 文档
- 图片
- 视频
- 音乐
- 压缩包
- 代码
- 文件夹
工作区
- 工作
- 学习
- 剪辑
- 设计
- 开发
- 游戏
- 资料
- AI
操作
- 启动
- 组合
- 脚本
- 链接
- 收藏
- 常用
- 临时
通用符号
- 星标
- 闪电
- 工具箱
- 齿轮
- 火箭
- 网格
- 标签

5.5.2 图标原则

默认自动获取，避免用户必须手动设置。
内置图标库用于补充，不要变成复杂素材管理器。
不做图标市场。
不做在线下载图标。

6. 交互规则

6.1 主界面鼠标交互

6.1.1 卡片单击

单击卡片只选中，不启动。

选中后：

卡片显示选中状态。
顶部“启动 / 编辑 / 删除”按钮启用。
用户可按 Enter 启动。

6.1.2 卡片双击

双击卡片启动工具或组合。

如果是组合，则按组合规则执行。

6.1.3 卡片右键

右键打开菜单。

菜单包含：

启动
编辑
重命名
复制
移动到分类
加入 / 取消工具箱启动时自动运行
删除

6.1.4 拖拽

支持：

当前分类内拖拽排序。
拖到左侧分类上移动分类。
组合编辑界面中拖拽调整成员顺序。

6.2 主界面键盘操作

第一版支持：

快捷键	行为
方向键	在卡片之间移动选中
Enter	启动当前选中工具 / 组合
Delete	删除当前选中项，需确认
F2	重命名当前选中项
Ctrl + F	聚焦搜索框
Esc	清空搜索，或取消当前选中 / 关闭搜索焦点
Ctrl + N	新建工具
Ctrl + G	新建组合
Ctrl + ,	打开设置

其中最重要的是：

方向键选择
Enter 启动
Ctrl + F 搜索

6.3 托盘交互

6.3.1 单击托盘图标

显示 / 隐藏主界面。

6.3.2 右键托盘图标

打开极简菜单：

显示 / 隐藏主界面
全局快捷键：开启 / 关闭
设置
退出

6.3.3 关闭主窗口

关闭主窗口时隐藏到托盘，不退出程序。

7. 数据模型设计

7.1 总体原则

所有能显示为卡片的对象都统一抽象为：

Tool

也就是说：

系统工具是 Tool。
本地工具是 Tool。
网址是 Tool。
组合也是 Tool。

区别只在于 type 和配置字段不同。

组合成员不复制工具内容，只保存 Tool ID 引用。
自动运行列表也不复制工具内容，只保存 Tool ID 引用。

7.2 数据文件建议

默认配置目录：

%AppData%\PersonalToolbox\

建议文件结构：

PersonalToolbox
├─ appsettings.json        // 软件设置
├─ categories.json         // 分类列表
├─ tools.json              // 工具列表，包含组合
├─ autorun.json            // 自动运行排序、间隔、临时启用状态
├─ hotkeys.json            // 可选，也可并入 tools.json
├─ icons\                  // 用户自定义图标
├─ backups\                // 导出或自动备份
└─ logs\                   // 可选，第一版可不持久化日志

也可以把 hotkey 存在 tools.json 中。
第一版推荐将工具核心配置集中在 tools.json 中，避免过度拆分。

7.3 Category 模型

{
  "id": "cat_system",
  "name": "系统工具",
  "icon": {
    "kind": "BuiltIn",
    "value": "icon.system.settings"
  },
  "sortOrder": 0,
  "isBuiltIn": true,
  "createdAt": "2026-01-01T00:00:00",
  "updatedAt": "2026-01-01T00:00:00"
}

字段说明：

字段	说明
id	分类唯一 ID
name	分类名称
icon	分类图标
sortOrder	排序
isBuiltIn	是否内置分类
createdAt	创建时间
updatedAt	更新时间

特殊分类：

cat_system：系统工具
cat_uncategorized：未分类

cat_uncategorized 不允许删除。

7.4 Tool 模型

{
  "id": "tool_001",
  "type": "Local",
  "name": "示例工具",
  "categoryId": "cat_uncategorized",
  "description": "这是一个示例本地工具",
  "icon": {
    "kind": "Auto",
    "value": null
  },
  "hotkey": {
    "enabled": true,
    "modifiers": ["Ctrl", "Alt"],
    "key": "T"
  },
  "autoRunEnabled": false,
  "sortOrder": 0,
  "isBuiltIn": false,
  "launchConfig": {},
  "combinationConfig": null,
  "state": {
    "isPathMissing": false,
    "lastLaunchAt": null,
    "lastLaunchResult": null
  },
  "metadata": {},
  "createdAt": "2026-01-01T00:00:00",
  "updatedAt": "2026-01-01T00:00:00"
}

字段说明：

字段	说明
id	工具唯一 ID
type	工具类型：System / Local / Url / Combination
name	工具名称
categoryId	所属分类 ID
description	说明
icon	图标引用
hotkey	快捷键配置
autoRunEnabled	是否加入工具箱启动时自动运行
sortOrder	当前分类中的排序
isBuiltIn	是否内置工具
launchConfig	启动配置
combinationConfig	组合配置，仅组合使用
state	运行时或检查状态
metadata	预留扩展字段
createdAt	创建时间
updatedAt	更新时间

7.5 ToolType 枚举

public enum ToolType
{
    System,
    Local,
    Url,
    Combination
}

7.6 IconRef 模型

{
  "kind": "BuiltIn",
  "value": "icon.system.task_manager",
  "color": "#4F7FFF"
}

图标类型：

Auto
BuiltIn
Extracted
LocalFile
SystemFileType

字段说明：

kind	说明
Auto	自动获取
BuiltIn	内置图标库
Extracted	从 exe 或 lnk 提取后缓存
LocalFile	用户选择的本地图标或图片
SystemFileType	系统文件类型图标

7.7 Hotkey 模型

{
  "enabled": true,
  "modifiers": ["Ctrl", "Alt"],
  "key": "T"
}

规则：

至少包含一个修饰键。
不允许多个工具使用完全相同的快捷键。
注册失败时不删除配置，只标记状态。

7.8 SystemLaunchConfig 模型

{
  "systemId": "system.task_manager",
  "launchTarget": "taskmgr.exe",
  "launchMethod": "ShellExecute",
  "runAsAdmin": false
}

字段说明：

字段	说明
systemId	固定系统工具 ID
launchTarget	启动目标
launchMethod	启动方式
runAsAdmin	是否管理员运行

系统工具必须有固定 ID。恢复默认系统工具时根据固定 ID 判断是否缺失。

7.9 LocalLaunchConfig 模型

{
  "path": "D:\\Tools\\Example\\Example.exe",
  "arguments": "",
  "workingDirectory": "D:\\Tools\\Example",
  "runAsAdmin": false,
  "subType": "Executable",
  "useShellExecute": true
}

LocalSubType 建议：

Executable
Shortcut
Script
File
Folder
StoreAppShortcut
Unknown

注意：用户侧不需要看到这些子类型，只在软件内部用于处理逻辑和显示只读状态。

7.10 UrlLaunchConfig 模型

{
  "url": "https://example.com",
  "openWithDefaultBrowser": true
}

第一版不需要指定浏览器。

7.11 CombinationConfig 模型

{
  "failurePolicy": "ContinueOnError",
  "members": [
    {
      "toolId": "tool_001",
      "enabled": true,
      "sortOrder": 0,
      "intervalAfterMs": 1000
    },
    {
      "toolId": "tool_002",
      "enabled": true,
      "sortOrder": 1,
      "intervalAfterMs": 3000
    }
  ]
}

failurePolicy 可选值：

ContinueOnError
StopOnError

成员字段：

字段	说明
toolId	引用的 Tool ID
enabled	是否启用该成员
sortOrder	成员顺序
intervalAfterMs	当前成员执行后的等待时间

7.12 AutoRunItem 模型

{
  "toolId": "tool_001",
  "enabled": true,
  "sortOrder": 0,
  "intervalAfterMs": 1000
}

自动运行列表由所有 autoRunEnabled = true 的工具和组合动态汇总而成。

autorun.json 只保存自动运行列表中的附加配置：

顺序。
间隔。
临时启用状态。

不要在 autorun.json 中复制工具名称、路径、图标等内容。

7.13 AppSettings 模型

{
  "startWithWindows": false,
  "startHiddenToTray": true,
  "closeToTray": true,
  "hotkeysGlobalEnabled": true,
  "theme": "System",
  "cardSize": "Medium",
  "showToolDescription": true,
  "bottomLogPanelExpanded": true,
  "window": {
    "width": 1100,
    "height": 720,
    "left": null,
    "top": null
  },
  "dataVersion": 1
}

8. 系统工具设计

8.1 默认系统工具列表建议

第一版建议内置：

设置
控制面板
文件资源管理器
任务管理器
命令提示符
PowerShell
Windows Terminal
运行
注册表编辑器
服务
设备管理器
磁盘管理
计算器
记事本
画图
截图工具
Windows 安全中心
网络连接
环境变量
卸载程序 / 应用管理
事件查看器
资源监视器
系统信息
任务计划程序
远程桌面连接

8.1.1 示例默认系统工具定义

{
  "id": "system.task_manager",
  "name": "任务管理器",
  "launchTarget": "taskmgr.exe",
  "launchMethod": "ShellExecute",
  "suggestRunAsAdmin": false,
  "icon": "icon.system.task_manager"
}

{
  "id": "system.regedit",
  "name": "注册表编辑器",
  "launchTarget": "regedit.exe",
  "launchMethod": "ShellExecute",
  "suggestRunAsAdmin": true,
  "icon": "icon.system.registry"
}

{
  "id": "system.windows_update",
  "name": "Windows 更新",
  "launchTarget": "ms-settings:windowsupdate",
  "launchMethod": "ShellExecute",
  "suggestRunAsAdmin": false,
  "icon": "icon.system.update"
}

8.2 恢复默认系统工具规则

恢复默认系统工具时：

读取内置系统工具定义。
检查当前 tools.json 中是否存在相同 systemId 的工具。
已存在则跳过，不重复创建。
不存在则创建。
新创建工具放入“系统工具”分类。
如果“系统工具”分类不存在，则先创建。
恢复完成后输出日志。

日志示例：

[10:00:01] 开始恢复默认系统工具
[10:00:01] 已存在：任务管理器，跳过
[10:00:01] 已恢复：注册表编辑器
[10:00:01] 已恢复：磁盘管理
[10:00:01] 默认系统工具恢复完成：新增 2 项，跳过 18 项

9. 本地工具设计

9.1 用户侧概念

用户不需要区分：

自定义程序
文件
文件夹
脚本
快捷方式

统一称为：

本地工具

用户添加时选择一个路径即可。

9.2 内部识别

软件内部根据路径判断子类型：

目标	子类型	处理方式
.exe	Executable	ShellExecute 启动
.lnk	Shortcut	ShellExecute 打开快捷方式
.bat / .cmd	Script	ShellExecute 启动
.ps1	File 或高级脚本	第一版不重点支持
普通文件	File	默认软件打开
文件夹	Folder	资源管理器打开
未知扩展名	Unknown	ShellExecute 尝试打开

9.3 ShellExecute 优先

第一版原则：

优先交给 Windows Shell 打开

好处：

文件自动用默认软件打开。
文件夹自动用资源管理器打开。
快捷方式自动解析。
Store 应用快捷方式也可被打开。
复杂度低。

9.4 PowerShell 脚本策略

.ps1 比较特殊，因为 Windows 默认可能不是执行，而是打开编辑器，并且涉及执行策略。

第一版建议：

不把直接执行 .ps1 作为核心能力。
.ps1 可以按普通文件打开。
后续可增加“高级脚本工具”能力。

第一版重点支持：

.bat
.cmd
.exe
.lnk
普通文件
文件夹

9.5 Microsoft Store 应用策略

第一版建议：

通过 .lnk 快捷方式添加 Microsoft Store 应用

用户可以通过：

Win + R -> shell:AppsFolder

找到 Store 应用，并创建快捷方式，然后作为本地工具添加。

增强版可增加：

StoreApp 子类型
AUMID / AppUserModelID 启动

但第一版不强制实现。

10. 网址工具设计

网址工具字段：

名称
图标
分类
说明
网址
快捷键
是否自动运行

启动方式：

使用默认浏览器打开

URL 校验：

如果没有协议，可自动补全 https://，或提示用户确认。
明显非法 URL 不允许保存。

第一版不做：

指定浏览器。
多浏览器配置。
favicon 自动下载。

11. 组合工具设计

11.1 组合核心规则

组合是一种 Tool。

组合的成员只能引用已有 Tool。

组合可以包含：

系统工具
本地工具
网址
其他组合

组合不复制成员内容，只保存成员 Tool ID。

11.2 组合嵌套规则

允许组合嵌套组合。
但必须满足两个约束：

不允许循环引用。
展开后的最终普通工具集合不能重复。

这里的“普通工具”指非组合工具：

System
Local
Url

组合本身是结构节点，不是最终启动目标。

11.3 循环引用示例

禁止：

组合 A 包含 组合 B
组合 B 包含 组合 C
组合 C 包含 组合 A

11.4 重复工具示例

禁止：

组合 A
├─ 工具 1
├─ 工具 2
└─ 组合 B
   ├─ 工具 2
   └─ 工具 3

因为组合 A 展开后，工具 2 出现了两次。

11.5 组合执行规则

执行组合时：

校验组合引用是否有效。
校验是否循环引用。
校验展开后是否重复工具。
按成员顺序执行。
跳过禁用成员。
每个成员执行后等待其配置的间隔。
如果成员是组合，递归执行该组合。
如果成员失败，根据组合的 failurePolicy 决定继续或停止。
所有过程输出到底部信息区。

11.6 组合展开算法建议

伪代码：

FlattenResult FlattenCombination(string combinationId)
{
    var visitedCombinations = new Stack<string>();
    var finalTools = new List<Tool>();
    var finalToolIds = new HashSet<string>();

    void Visit(string toolId)
    {
        var tool = toolRepository.Get(toolId);

        if (tool.Type != ToolType.Combination)
        {
            if (finalToolIds.Contains(tool.Id))
                throw new DuplicateToolException(tool.Id);

            finalToolIds.Add(tool.Id);
            finalTools.Add(tool);
            return;
        }

        if (visitedCombinations.Contains(tool.Id))
            throw new CircularReferenceException(visitedCombinations, tool.Id);

        visitedCombinations.Push(tool.Id);

        foreach (var member in tool.CombinationConfig.Members.OrderBy(x => x.SortOrder))
        {
            if (!member.Enabled)
                continue;

            Visit(member.ToolId);
        }

        visitedCombinations.Pop();
    }

    Visit(combinationId);

    return new FlattenResult(finalTools);
}

注意：实际执行时不能只展开成扁平列表，因为还需要尊重嵌套组合自己的失败策略和间隔。
因此建议保存两种能力：

校验时可展平，用于检测重复工具。
执行时按树结构递归执行，用于保留组合级失败策略。

12. 自动运行设计

12.1 自动运行来源

自动运行列表不是用户手动创建的独立任务列表。
它来自每个工具或组合的设置：

autoRunEnabled = true

设置界面只是动态汇总这些项目。

12.2 自动运行列表配置

自动运行列表保存附加执行信息：

toolId
enabled
sortOrder
intervalAfterMs

不保存工具名称、路径、图标等数据。

12.3 自动运行执行规则

工具箱启动后：

读取所有 autoRunEnabled = true 的工具和组合。
合并 autorun.json 中的排序、间隔、启用状态。
按 sortOrder 排序。
逐项执行。
某项失败后，记录日志，继续下一项。
如果某项是组合，则由组合自己的失败策略控制其内部执行。
自动运行完成后输出汇总。

自动运行不提供全局失败中断。

12.4 自动运行示例日志

[09:00:01] 开始执行启动时自动运行
[09:00:01] ✓ 启动：Everything
[09:00:02] ✕ 启动失败：某个本地工具，路径不存在
[09:00:03] 启动组合：剪辑工作区
[09:00:03] ✓ 打开：素材文件夹
[09:00:05] ✓ 打开：剪辑软件
[09:00:05] 完成组合：剪辑工作区
[09:00:06] 启动时自动运行完成：成功 3 项，失败 1 项

13. 快捷键设计

13.1 全局快捷键原则

每个工具和组合可设置一个全局快捷键。
快捷键仅在工具箱运行时生效。
关闭全局快捷键总开关后，所有快捷键失效。
再次开启后重新注册所有快捷键。
不删除原快捷键配置。

13.2 快捷键限制

第一版要求：

必须包含至少一个修饰键。
不支持纯单键快捷键。
不允许两个工具使用完全相同快捷键。

合法示例：

Ctrl + Alt + T
Ctrl + Shift + S
Alt + Shift + V
Win + Alt + C

不建议允许：

A
F1
Enter
Space

13.3 快捷键冲突

需要处理两类冲突：

13.3.1 软件内部冲突

两个工具不能设置相同快捷键。

13.3.2 系统注册失败

如果快捷键被 Windows 或其他软件占用，注册可能失败。
此时应：

不删除配置。
标记状态为注册失败。
在底部信息区输出提示。
在设置界面快捷键管理中显示状态。

13.4 快捷键触发行为

快捷键触发后：

HotkeyService -> ToolLaunchService.Launch(toolId)

不能在快捷键模块中直接写启动逻辑。

14. 启动执行服务设计

14.1 核心服务

建议核心服务：

ToolLaunchService

所有启动入口都调用它。

入口包括：

双击卡片。
点击启动按钮。
按 Enter。
全局快捷键。
组合成员执行。
启动时自动运行。

14.2 启动前校验

普通工具启动前检查：

工具是否存在。
工具是否被删除。
本地路径是否存在。
网址是否有效。
启动配置是否完整。

组合启动前检查：

成员引用是否存在。
是否循环引用。
展开后是否重复工具。

14.3 启动结果定义

第一版只判断：

是否成功发起启动

不判断：

目标程序是否持续运行。
目标程序是否崩溃。
脚本业务逻辑是否成功。
网页是否加载成功。

14.4 LaunchResult 模型

public class LaunchResult
{
    public string ToolId { get; set; }
    public string ToolName { get; set; }
    public bool Success { get; set; }
    public string? ErrorMessage { get; set; }
    public LaunchResultKind Kind { get; set; }
}

LaunchResultKind：

Success
PathMissing
InvalidUrl
AccessDenied
UserCancelledElevation
ProcessStartFailed
CircularReference
DuplicateTool
UnknownError
Skipped

14.5 本地工具启动建议

C# 思路：

var startInfo = new ProcessStartInfo
{
    FileName = target,
    Arguments = arguments,
    WorkingDirectory = workingDirectory,
    UseShellExecute = true
};

if (runAsAdmin)
{
    startInfo.Verb = "runas";
}

Process.Start(startInfo);

注意：

普通文件、文件夹、快捷方式需要 UseShellExecute = true。
管理员运行需要 Verb = "runas"。
用户取消 UAC 时要捕获异常并输出日志。

14.6 网址启动建议

Process.Start(new ProcessStartInfo
{
    FileName = url,
    UseShellExecute = true
});

14.7 系统工具启动建议

系统工具也使用统一启动流程。
系统工具的 launchTarget 可以是：

notepad.exe
calc.exe
taskmgr.exe
control
regedit.exe
services.msc
devmgmt.msc
diskmgmt.msc
ms-settings:
ms-settings:windowsupdate
ncpa.cpl
shell:AppsFolder

使用 UseShellExecute = true。

15. 数据存储与导入导出

15.1 保存策略

建议采用：

启动时读取全部 JSON。
运行时在内存中维护状态。
修改后立即保存或短延迟防抖保存。
保存前写入临时文件，再替换正式文件，避免写坏配置。

保存流程：

写入 tools.json.tmp
写入成功后替换 tools.json
失败则保留旧文件

15.2 数据版本

配置中应包含：

dataVersion

未来升级时可以做迁移。

15.3 导出配置

导出应包含：

appsettings.json
categories.json
tools.json
autorun.json
icons 目录

建议导出为 zip。

15.4 导入配置

导入流程：

用户选择导出的 zip 或配置目录。
解压或读取配置。
校验数据版本。
备份当前配置。
导入新配置。
检查路径失效。
输出导入结果。

15.5 路径失效检测

检测对象：

本地工具路径。
本地图标路径。
工作目录。

路径失效时：

不删除工具。
卡片显示“路径失效”标记。
双击启动时输出错误。
右键提供“修改路径”。

日志示例：

[11:12:00] 路径检查完成：发现 3 个失效工具
[11:12:00] 路径失效：旧版剪辑工具，D:\OldTools\Editor.exe

16. 模块划分

第一版建议分为六个核心模块。

16.1 托盘与窗口模块

职责：

托盘图标。
显示 / 隐藏主窗口。
关闭窗口隐藏到托盘。
托盘菜单。
开机自启。

建议服务：

TrayService
WindowStateService
StartupService

16.2 数据存储模块

职责：

配置目录管理。
JSON 读取保存。
导入导出。
数据版本迁移。
路径失效检测。

建议服务：

ConfigurationService
ToolRepository
CategoryRepository
BackupService
PathValidationService

16.3 工具管理模块

职责：

工具增删改查。
分类管理。
图标管理。
系统工具恢复。
搜索过滤。
卡片排序。

建议服务：

ToolManager
CategoryManager
SystemToolService
IconService
SearchService

16.4 启动执行模块

职责：

启动系统工具。
启动本地工具。
启动网址。
执行组合。
执行自动运行。
失败处理。
输出日志。

建议服务：

ToolLaunchService
CombinationLaunchService
AutoRunService
LaunchValidationService
LogOutputService

16.5 快捷键模块

职责：

注册全局快捷键。
注销全局快捷键。
检测内部冲突。
处理系统注册失败。
全局启用 / 禁用。
快捷键触发工具启动。

建议服务：

HotkeyService
HotkeyRegistry
HotkeyConflictDetector

16.6 UI 模块

职责：

主界面。
工具编辑弹窗。
组合编辑界面。
设置界面。
图标选择器。
底部信息输出区。

建议 ViewModel：

MainWindowViewModel
ToolCardViewModel
CategoryListViewModel
ToolEditorViewModel
CombinationEditorViewModel
SettingsViewModel
IconPickerViewModel
LogPanelViewModel

17. 搜索设计

搜索框位于主界面顶部。

搜索范围：

工具名称。
工具说明。
分类名称。
本地路径。
网址。

搜索行为：

实时过滤。
搜索结果跨分类显示。
卡片上标注所属分类。
搜索状态下仍可双击启动、右键管理。
清空搜索框后回到当前分类。

18. 图标处理设计

18.1 图标来源优先级

建议优先级：

用户手动选择的图标。
内置图标库图标。
从目标文件自动提取的图标。
系统文件类型图标。
默认通用图标。

18.2 图标缓存

从 exe、lnk 提取的图标可以缓存到：

%AppData%\PersonalToolbox\icons\cache\

用户手动选择的图标可以复制到：

%AppData%\PersonalToolbox\icons\custom\

避免原文件移动后图标丢失。

18.3 图标库

内置图标库可以使用：

XAML Geometry。
SVG 资源。
字体图标。
PNG 资源。

建议统一封装为 IconRef，不要让 UI 直接依赖某种具体图标实现。

19. 错误处理与信息输出

19.1 错误处理原则

普通错误不弹窗。
输出到底部信息区。
删除、重置、导入覆盖等破坏性操作需要确认。
UAC 由系统处理。

19.2 常见错误

需要处理：

路径不存在。
工作目录不存在。
URL 格式错误。
工具引用不存在。
组合循环引用。
组合重复工具。
快捷键内部冲突。
快捷键系统注册失败。
用户取消管理员权限。
配置文件读取失败。
配置文件写入失败。
导入配置失败。
图标加载失败。

19.3 日志级别

底部信息区日志建议分级：

Info
Success
Warning
Error

示例：

[Info] 开始启动工具：任务管理器
[Success] 启动成功：任务管理器
[Warning] 路径失效：旧工具
[Error] 启动失败：用户取消管理员权限

20. 开机自启设计

第一版可使用注册表 CurrentUser 启动项。

建议位置：

HKCU\Software\Microsoft\Windows\CurrentVersion\Run

启动项指向当前程序路径。

注意：

只设置当前用户自启。
不需要管理员权限。
设置失败要输出日志。
如果程序路径变化，需更新启动项。

21. 安全与边界

21.1 不做危险自动化平台

本软件支持启动脚本文件，但第一版不提供直接输入命令并执行的能力。
避免软件变成复杂脚本执行器。

21.2 管理员权限最小化

工具箱自身不默认管理员运行。
只有用户明确设置某个工具管理员运行时，才触发 UAC。

21.3 导入配置安全提示

导入配置可能包含本地脚本和程序路径。
导入后应提示用户检查自动运行和快捷键。

建议导入完成后输出：

配置导入完成。建议检查自动运行列表和快捷键，确认其中没有不需要启动的工具。

22. Codex 开发建议

22.1 开发顺序建议

建议按以下顺序开发：

阶段 1：基础框架

创建 WPF 项目。
建立 MVVM 基础结构。
建立配置目录。
实现 JSON 读写。
实现基础数据模型。

阶段 2：主界面

实现主窗口布局。
实现分类列表。
实现卡片网格。
实现卡片选中。
实现底部信息输出区。

阶段 3：工具管理

实现添加本地工具。
实现添加网址工具。
实现编辑工具。
实现删除工具。
实现分类管理。
实现搜索。

阶段 4：系统工具

内置默认系统工具定义。
首次启动创建系统工具分类和工具。
实现恢复默认系统工具。

阶段 5：启动执行

实现 ToolLaunchService。
实现系统工具启动。
实现本地工具启动。
实现网址启动。
实现日志输出。

阶段 6：组合

实现组合编辑界面。
实现组合成员引用。
实现循环引用检测。
实现重复工具检测。
实现组合执行。
实现失败策略。

阶段 7：自动运行

实现 autoRunEnabled。
实现设置界面自动运行列表。
实现排序、间隔、启用状态。
实现工具箱启动后自动执行。

阶段 8：托盘与自启

实现托盘图标。
实现显示 / 隐藏主界面。
实现关闭隐藏到托盘。
实现托盘菜单。
实现开机自启设置。

阶段 9：快捷键

实现快捷键录入。
实现内部冲突检测。
实现系统注册。
实现全局开关。
实现托盘菜单快捷键开关。
实现快捷键触发 ToolLaunchService。

阶段 10：图标与外观

实现自动图标。
实现内置图标库。
实现图标选择器。
实现主题和卡片大小设置。

阶段 11：导入导出与打磨

实现导出配置。
实现导入配置。
实现路径失效检查。
完善错误处理。
完善键盘操作。
完成整体测试。

23. 验收标准

23.1 基础验收

软件能正常启动。
软件能隐藏到托盘。
关闭窗口不会退出。
托盘菜单能显示 / 隐藏主界面。
托盘菜单能退出软件。
可设置开机自启。

23.2 工具验收

能添加本地工具。
能添加网址工具。
能启动系统工具。
能启动本地 exe。
能打开文件夹。
能打开普通文件。
能打开网址。
路径失效时不崩溃，并显示提示。

23.3 分类验收

能新增分类。
能重命名分类。
能删除分类。
删除分类时工具移动到未分类。
分类只能一级。
工具能移动分类。

23.4 组合验收

能创建组合。
能添加工具成员。
能添加组合成员。
能调整顺序。
能设置间隔。
能禁用成员。
能检测循环引用。
能检测重复工具。
能按失败策略继续或停止。

23.5 自动运行验收

工具可设置启动时自动运行。
组合可设置启动时自动运行。
设置界面自动汇总自动运行列表。
能调整自动运行顺序。
能设置自动运行间隔。
某项失败后继续执行下一项。

23.6 快捷键验收

工具可设置快捷键。
组合可设置快捷键。
快捷键能触发启动。
内部冲突能检测。
系统注册失败能提示。
设置界面可统一管理快捷键。
托盘菜单可开启 / 关闭全局快捷键。

23.7 数据验收

配置能保存。
重启后配置仍存在。
能导出配置。
能导入配置。
导入后能检查路径失效。
能恢复默认系统工具。

24. 最终产品边界总结

本软件第一版应专注于：

工具管理
工具启动
组合启动
托盘常驻
开机自启
全局快捷键
本地配置

不要扩展成：

软件管家
自动化平台
插件平台
脚本 IDE
任务调度器
进程监控器
云同步服务

最重要的设计基准是：

用户能用非常低的成本，把自己常用的系统功能、软件、文件夹、文件、网址整理成卡片，并能通过双击、快捷键、组合或启动时自动运行快速打开它们。

如果后续开发中出现功能取舍，应优先保证：

启动稳定。
数据安全。
交互简单。
不误触。
不过度复杂。

25. 一句话规格

这是一款 WPF / .NET 开发的 Windows 个人工具箱软件，常驻托盘，支持系统工具、本地工具、网址和组合的卡片化管理，支持一级分类、搜索、全局快捷键、工具箱启动时自动运行、组合嵌套、组合执行顺序和间隔、本地 JSON 配置、导入导出、图标自动获取与轻量图标库；其第一版目标是轻量稳定地完成个人工具集中启动，而不是成为复杂自动化平台。

49 KiB Raw Permalink Blame History Unescape Escape

Windows 个人工具箱软件开发设计文档

1. 产品概述

1.1 产品名称

1.2 产品定位

1.3 核心价值

2. 设计原则

2.1 轻量优先

2.2 本地优先

2.3 用户可理解优先

2.4 避免误操作

2.5 组合使用引用，不自包含

2.6 不弹窗打断用户

2.7 所有启动入口行为一致

3. MVP 范围

3.1 第一版必须包含

3.1.1 托盘常驻

3.1.2 主界面

3.1.3 工具类型

3.1.4 系统工具

3.1.5 本地工具

3.1.6 网址工具

3.1.7 组合工具

3.1.8 工具箱启动时自动运行

3.1.9 全局快捷键

3.1.10 数据保存

3.1.11 图标

3.2 第一版明确不做

4. 技术方向

4.1 推荐技术栈

4.2 为什么选择 WPF / .NET

4.3 权限策略

5. 用户界面设计

5.1 主界面总体结构

5.1.1 顶部区域

5.1.2 左侧分类列表

5.1.3 右侧卡片网格

5.1.4 底部信息输出区

5.2 工具编辑弹窗

5.2.1 基础字段

5.2.2 系统工具字段

5.2.3 本地工具字段

5.2.4 网址工具字段

5.3 组合编辑界面

5.3.1 组合基础字段

5.3.2 组合成员列表

5.3.3 组合失败处理

5.3.4 组合校验

5.4 设置界面

5.4.1 常规设置

5.4.2 启动与托盘

5.4.3 自动运行列表

5.4.4 快捷键管理

5.4.5 数据与备份

5.4.6 外观设置

5.4.7 系统工具恢复

5.5 图标选择器

5.5.1 内置图标库分类

5.5.2 图标原则

6. 交互规则

6.1 主界面鼠标交互

6.1.1 卡片单击

6.1.2 卡片双击

6.1.3 卡片右键

6.1.4 拖拽

6.2 主界面键盘操作

6.3 托盘交互

6.3.1 单击托盘图标

6.3.2 右键托盘图标

6.3.3 关闭主窗口

7. 数据模型设计

7.1 总体原则

7.2 数据文件建议

7.3 Category 模型

7.4 Tool 模型

7.5 ToolType 枚举

7.6 IconRef 模型

7.7 Hotkey 模型

7.8 SystemLaunchConfig 模型

7.9 LocalLaunchConfig 模型

49 KiB

Raw Permalink Blame History