From e04f73bb6af59019d15d833a2dcae357fc198126 Mon Sep 17 00:00:00 2001
From: home-PC <gamewhale@163.com>
Date: Wed, 27 May 2026 13:33:44 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E9=A1=B9?=
 =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3=E5=9F=BA=E7=BA=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

提交产品设计文档和基础忽略规则。

后续开发以该文档作为 Windows 个人工具箱 MVP 的需求来源，并持续维护开发文档与阶段提交。
---
 .gitignore                                 |   29 +
 windows_personal_toolbox_product_design.md | 2557 ++++++++++++++++++++
 2 files changed, 2586 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 windows_personal_toolbox_product_design.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..64b4344
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,29 @@
+# Build outputs
+bin/
+obj/
+out/
+publish/
+
+# IDE and local user files
+.vs/
+.vscode/
+*.user
+*.suo
+*.rsuser
+*.userosscache
+*.sln.docstates
+
+# Test and coverage output
+TestResults/
+coverage/
+*.coverage
+*.coveragexml
+
+# Logs and temporary files
+*.log
+*.tmp
+*.temp
+
+# OS metadata
+Thumbs.db
+Desktop.ini
diff --git a/windows_personal_toolbox_product_design.md b/windows_personal_toolbox_product_design.md
new file mode 100644
index 0000000..7ea44a3
--- /dev/null
+++ b/windows_personal_toolbox_product_design.md
@@ -0,0 +1,2557 @@
+# Windows 个人工具箱软件开发设计文档
+
+> 本文档用于指导 Codex 或其他代码生成工具进行开发。  
+> 目标是开发一款轻量、稳定、常驻托盘、支持系统工具、本地工具、网址、组合、自动运行和全局快捷键的 Windows 平台个人工具箱软件。  
+> 本软件不是软件管家、不是任务调度器、不是插件平台、不是进程监控器，而是一个面向个人高频使用场景的本地工具启动与组合管理器。
+
+---
+
+## 1. 产品概述
+
+### 1.1 产品名称
+
+暂定名：**个人工具箱** / **Personal Toolbox**
+
+实际开发时可使用临时代号：
+
+```text
+ToolboxApp
+```
+
+### 1.2 产品定位
+
+本软件是一款 Windows 平台个人工具箱应用，主要用于集中管理和快速启动用户常用的系统工具、本地程序、本地文件、文件夹、脚本、网址，以及由多个工具组成的组合。
+
+软件常驻系统托盘，可设置开机自启。用户可以通过托盘图标显示或隐藏主界面，也可以通过全局快捷键直接启动某个工具或组合。
+
+### 1.3 核心价值
+
+本软件要解决的问题不是“发现软件”，而是“整理和快速启动用户已经知道自己需要的东西”。
+
+核心价值包括：
+
+1. **集中管理**  
+   将系统工具、本地工具、网址、组合集中在一个统一界面中。
+
+2. **快速启动**  
+   用户通过双击卡片、快捷键、组合、启动时自动运行等方式快速打开目标。
+
+3. **组合启动**  
+   用户可以把多个工具打包为组合，例如“一键打开剪辑环境”“一键打开开发环境”。
+
+4. **托盘常驻**  
+   软件长期隐藏在托盘，不占用任务栏空间，随时可唤出。
+
+5. **开机自动运行**  
+   工具箱可设置开机自启，并在启动后按用户设置自动运行指定工具或组合。
+
+6. **轻量可控**  
+   不做自动扫描，不做云同步，不做复杂插件系统，不做过度功能。
+
+---
+
+## 2. 设计原则
+
+### 2.1 轻量优先
+
+软件应保持轻量。功能服务于“启动和组合启动工具”，不要扩展成软件管家、脚本平台或自动化平台。
+
+### 2.2 本地优先
+
+所有数据保存在本地配置文件中。第一版不做账号、不做云同步、不依赖远程服务。
+
+### 2.3 用户可理解优先
+
+用户界面上不应暴露过多技术概念。  
+例如 exe、lnk、bat、cmd、mp4、docx、文件夹等，在用户侧统一称为“本地工具”。软件内部可自动判断子类型，但用户添加时不需要理解这些差异。
+
+### 2.4 避免误操作
+
+工具卡片采用：
+
+```text
+单击 = 选中
+双击 = 启动
+```
+
+不要单击即启动，避免用户误触导致程序、组合或多个工具被打开。
+
+### 2.5 组合使用引用，不自包含
+
+组合内部只保存工具或组合的 ID 引用，不复制工具内容。  
+这样工具改名、换路径、换图标后，所有引用该工具的组合都会同步生效。
+
+### 2.6 不弹窗打断用户
+
+普通启动信息、组合执行进度、自动运行结果、错误提示，统一输出到主界面底部的信息输出区。  
+除删除确认、重大破坏性操作、必要系统权限提示外，尽量不弹窗。
+
+### 2.7 所有启动入口行为一致
+
+无论用户通过双击卡片、全局快捷键、组合、启动时自动运行触发工具，都必须统一走同一个启动服务。
+
+建议核心服务命名：
+
+```text
+ToolLaunchService
+```
+
+---
+
+## 3. MVP 范围
+
+### 3.1 第一版必须包含
+
+第一版必须实现以下功能。
+
+#### 3.1.1 托盘常驻
+
+- 软件可以常驻系统托盘。
+- 支持设置开机自启。
+- 启动后可默认隐藏到托盘。
+- 单击托盘图标显示 / 隐藏主界面。
+- 关闭主窗口时隐藏到托盘，不退出软件。
+- 真正退出只能通过托盘右键菜单中的“退出”。
+- 托盘菜单保持极简：
+  - 显示 / 隐藏主界面
+  - 全局快捷键开启 / 关闭
+  - 设置
+  - 退出
+
+#### 3.1.2 主界面
+
+主界面采用：
+
+```text
+顶部搜索与操作按钮
+左侧一级分类
+右侧卡片网格
+底部信息输出区
+```
+
+主界面必须支持：
+
+- 搜索工具。
+- 显示分类。
+- 显示工具卡片。
+- 单击卡片选中。
+- 双击卡片启动。
+- 右键卡片管理。
+- 底部信息输出。
+- 基础键盘操作。
+
+#### 3.1.3 工具类型
+
+用户侧只暴露四类：
+
+1. 系统工具
+2. 本地工具
+3. 网址
+4. 组合
+
+其中：
+
+- 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 工具箱启动时自动运行
+
+每个工具或组合自身可设置：
+
+```text
+工具箱启动时自动运行：是 / 否
+```
+
+设置界面动态汇总所有启用自动运行的工具和组合，形成自动运行列表。
+
+自动运行列表支持：
+
+- 调整执行顺序。
+- 设置每项之间的时间间隔。
+- 临时启用 / 禁用。
+- 从自动运行中移除。
+
+自动运行列表不提供失败中断功能。  
+某项失败后，记录到底部信息区，然后继续执行下一项。  
+如果某项是组合，则组合内部是否中断由组合自身的失败处理规则决定。
+
+#### 3.1.9 全局快捷键
+
+每个工具和组合都可以设置一个全局快捷键。
+
+要求：
+
+- 快捷键仅在工具箱运行时生效。
+- 支持设置界面统一管理快捷键。
+- 支持工具编辑界面单独设置快捷键。
+- 托盘菜单和设置界面都提供全局快捷键总开关。
+- 关闭总开关时，所有快捷键临时失效，但不删除配置。
+- 开启总开关时重新注册快捷键。
+- 必须检测软件内部快捷键冲突。
+- 必须处理系统注册失败，例如被其他软件占用。
+- 第一版不支持单键快捷键，要求至少包含一个修饰键。
+
+建议支持的修饰键：
+
+```text
+Ctrl
+Alt
+Shift
+Win
+```
+
+#### 3.1.10 数据保存
+
+- 使用本地 JSON 文件保存。
+- 不做数据库。
+- 不做账号。
+- 不做云同步。
+- 图标文件单独保存在 icons 目录。
+- 支持导入配置。
+- 支持导出配置。
+- 支持重置配置。
+- 支持打开配置目录。
+- 导入配置后检测路径失效。
+
+#### 3.1.11 图标
+
+- 默认自动获取图标。
+- exe 尽量提取程序图标。
+- lnk 尽量读取快捷方式图标或目标图标。
+- 文件使用系统默认文件类型图标。
+- 文件夹使用文件夹图标。
+- 网址使用默认链接图标，后续可扩展 favicon。
+- 组合使用内置组合图标。
+- 系统工具使用内置系统工具图标。
+- 提供轻量内置图标库。
+- 用户可以从图标库选择图标。
+- 用户可以选择本地图片或 ico 作为图标。
+- 分类也可以设置图标。
+
+### 3.2 第一版明确不做
+
+第一版不做以下功能：
+
+- 插件系统。
+- 账号系统。
+- 云同步。
+- 自动扫描已安装软件。
+- 自动扫描开始菜单。
+- 复杂脚本命令编辑器。
+- 直接输入命令作为工具。
+- 多级分类。
+- 托盘菜单中的最近使用工具。
+- 托盘菜单中的常用工具。
+- 复杂历史日志管理。
+- 进程监控。
+- 判断目标程序运行后是否崩溃。
+- 判断脚本业务执行是否成功。
+- 对工具启动结果做深度跟踪。
+- 插件市场。
+- 图标素材市场。
+- 多用户权限系统。
+
+---
+
+## 4. 技术方向
+
+### 4.1 推荐技术栈
+
+建议使用：
+
+```text
+WPF + .NET
+```
+
+开发语言：
+
+```text
+C#
+```
+
+架构模式建议：
+
+```text
+MVVM
+```
+
+UI 风格建议：
+
+```text
+现代 Fluent 风格
+```
+
+可以使用成熟 WPF UI 控件库，但不应让控件库决定业务结构。业务层应保持独立。
+
+### 4.2 为什么选择 WPF / .NET
+
+原因：
+
+1. 与 Windows 系统集成自然。
+2. 托盘图标、自启、快捷键、进程启动、文件路径处理都方便。
+3. 比 Electron 更轻量。
+4. 适合个人工具箱这种常驻桌面软件。
+5. 后续维护成本低。
+
+### 4.3 权限策略
+
+工具箱自身默认以普通权限运行。
+
+每个工具可以单独配置：
+
+```text
+以管理员身份运行：是 / 否
+```
+
+组合执行时，每个成员按自己的权限配置启动。  
+组合本身不统一提权。
+
+如果用户启动某个需要管理员权限的工具，则由 Windows 弹出 UAC。  
+用户取消 UAC 时，启动失败信息写入底部信息区。
+
+---
+
+## 5. 用户界面设计
+
+## 5.1 主界面总体结构
+
+主界面结构：
+
+```text
+┌────────────────────────────────────────────┐
+│ 顶部：搜索框 + 操作按钮                     │
+├──────────────┬─────────────────────────────┤
+│ 左侧分类列表  │ 右侧工具 / 组合卡片网格       │
+│              │                             │
+├──────────────┴─────────────────────────────┤
+│ 底部信息输出区                              │
+└────────────────────────────────────────────┘
+```
+
+### 5.1.1 顶部区域
+
+顶部包含：
+
+- 搜索框
+- 添加工具
+- 添加组合
+- 启动
+- 编辑
+- 删除
+- 设置
+
+建议布局：
+
+```text
+[搜索工具...]                         [添加工具] [添加组合] [启动] [编辑] [删除] [设置]
+```
+
+按钮行为：
+
+- 未选中卡片时，“启动 / 编辑 / 删除”禁用。
+- 选中卡片后，“启动 / 编辑 / 删除”启用。
+- 搜索框支持 Ctrl + F 聚焦。
+
+### 5.1.2 左侧分类列表
+
+分类只支持一级分类。
+
+分类功能：
+
+- 新建分类。
+- 重命名分类。
+- 删除分类。
+- 拖拽排序。
+- 设置分类图标。
+- 每个工具或组合只能属于一个分类。
+
+默认分类：
+
+```text
+系统工具
+未分类
+```
+
+规则：
+
+- “未分类”固定存在，不允许删除。
+- “系统工具”首次启动时创建。
+- “系统工具”可以改名，可以调整排序。
+- 如果恢复默认系统工具时“系统工具”分类不存在，则自动重新创建。
+
+删除分类时：
+
+- 不直接删除其中工具。
+- 应提示用户：该分类中的工具将移动到“未分类”。
+- 用户确认后执行移动。
+
+### 5.1.3 右侧卡片网格
+
+卡片显示内容：
+
+- 图标
+- 名称
+- 简短说明
+- 类型标记
+- 状态标记
+
+类型标记包括：
+
+```text
+系统
+本地
+网址
+组合
+```
+
+状态标记包括：
+
+```text
+路径失效
+已设快捷键
+自动运行
+管理员
+```
+
+卡片交互：
+
+```text
+单击：选中
+双击：启动
+右键：打开菜单
+拖拽：排序或移动分类
+```
+
+右键菜单建议：
+
+```text
+启动
+编辑
+重命名
+复制
+移动到分类
+加入 / 取消工具箱启动时自动运行
+删除
+```
+
+### 5.1.4 底部信息输出区
+
+底部信息区常驻主界面底部。
+
+用途：
+
+- 显示普通工具启动结果。
+- 显示组合执行进度。
+- 显示自动运行执行结果。
+- 显示启动失败原因。
+- 显示快捷键注册失败。
+- 显示导入导出结果。
+- 显示路径失效检查结果。
+- 显示系统工具恢复结果。
+
+信息格式建议：
+
+```text
+[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 基础字段
+
+所有普通工具都包含：
+
+```text
+名称
+图标
+所属分类
+说明 / 备注
+快捷键
+是否工具箱启动时自动运行
+```
+
+快捷键区域：
+
+```text
+快捷键：未设置
+[录入快捷键] [清除]
+```
+
+自动运行区域：
+
+```text
+□ 工具箱启动时自动运行
+```
+
+注意：普通工具编辑界面不设置自动运行延迟。  
+自动运行顺序与间隔统一在设置界面的自动运行列表中管理。
+
+### 5.2.2 系统工具字段
+
+系统工具显示：
+
+```text
+系统工具标识
+内置启动方式
+是否管理员运行
+```
+
+系统工具的启动标识可以显示，但默认不建议用户修改。
+
+允许用户修改：
+
+- 名称
+- 图标
+- 分类
+- 说明
+- 快捷键
+- 是否自动运行
+- 是否管理员运行
+
+### 5.2.3 本地工具字段
+
+本地工具显示：
+
+```text
+目标路径
+工作目录
+启动参数
+是否以管理员身份运行
+```
+
+高级设置默认折叠。
+
+建议显示逻辑：
+
+- exe / bat / cmd / lnk：显示启动参数、工作目录、管理员运行。
+- 普通文件：隐藏或折叠启动参数、工作目录。
+- 文件夹：隐藏启动参数。
+- 未知类型：优先交给 Windows Shell 打开。
+
+### 5.2.4 网址工具字段
+
+网址工具显示：
+
+```text
+网址
+```
+
+第一版只使用默认浏览器打开，不做指定浏览器。
+
+---
+
+## 5.3 组合编辑界面
+
+组合编辑界面建议使用较大的独立窗口，不建议塞进普通工具编辑弹窗。
+
+### 5.3.1 组合基础字段
+
+组合包含：
+
+```text
+组合名称
+图标
+所属分类
+说明 / 备注
+快捷键
+是否工具箱启动时自动运行
+```
+
+### 5.3.2 组合成员列表
+
+组合成员只能从已有工具或组合中选择。
+
+组合成员字段：
+
+```text
+成员工具 ID
+是否启用
+排序
+当前成员执行后等待间隔
+```
+
+界面上建议显示：
+
+```text
+启用 | 图标 | 名称 | 类型 | 间隔 | 操作
+```
+
+支持：
+
+- 添加成员。
+- 移除成员。
+- 启用 / 禁用成员。
+- 拖拽调整顺序。
+- 设置成员执行后的等待间隔。
+
+### 5.3.3 组合失败处理
+
+组合级设置：
+
+```text
+失败处理方式：
+○ 某项失败后继续执行后续工具
+○ 某项失败后停止执行整个组合
+```
+
+默认建议：
+
+```text
+失败后继续执行
+```
+
+### 5.3.4 组合校验
+
+保存组合前必须校验：
+
+1. 是否存在循环引用。
+2. 展开后是否存在重复工具。
+3. 成员引用是否有效。
+4. 成员是否引用已删除工具。
+
+如果校验失败，不允许保存，并提示具体原因。
+
+提示示例：
+
+```text
+无法保存组合“开发环境”，因为它会导致重复工具：
+- VS Code
+- 项目文件夹
+```
+
+```text
+无法保存组合“日常工作区”，因为它会导致循环引用：
+日常工作区 -> 文档工作区 -> 日常工作区
+```
+
+---
+
+## 5.4 设置界面
+
+设置界面建议按左侧导航或顶部 Tab 分组。
+
+### 5.4.1 常规设置
+
+包含：
+
+- 启动后是否默认隐藏到托盘。
+- 关闭窗口时隐藏到托盘。
+- 是否显示退出确认。
+- 主界面默认宽高。
+- 底部信息区默认展开 / 折叠。
+
+### 5.4.2 启动与托盘
+
+包含：
+
+- 是否开机自启。
+- 托盘单击行为：显示 / 隐藏主界面。
+- 托盘菜单配置。
+
+托盘菜单固定保持极简：
+
+```text
+显示 / 隐藏主界面
+全局快捷键：开启 / 关闭
+设置
+退出
+```
+
+### 5.4.3 自动运行列表
+
+自动运行列表不是独立任务编排器，而是自动汇总所有设置为“工具箱启动时自动运行”的工具和组合。
+
+显示字段：
+
+```text
+启用
+顺序
+工具名称
+工具类型
+间隔
+操作
+```
+
+支持：
+
+- 调整顺序。
+- 设置间隔。
+- 临时启用 / 禁用。
+- 从自动运行中移除。
+
+注意：
+
+- 从自动运行中移除，等价于把该工具的 `autoRunEnabled` 设置为 false。
+- 自动运行列表不提供失败中断功能。
+- 某项失败后继续执行下一项。
+
+### 5.4.4 快捷键管理
+
+显示所有已设置快捷键的工具和组合。
+
+字段：
+
+```text
+快捷键
+工具名称
+工具类型
+状态
+操作
+```
+
+支持：
+
+- 修改快捷键。
+- 清除快捷键。
+- 检测冲突。
+- 全局启用 / 禁用快捷键。
+
+快捷键状态包括：
+
+```text
+正常
+内部冲突
+系统注册失败
+已禁用
+```
+
+### 5.4.5 数据与备份
+
+包含：
+
+- 打开配置目录。
+- 导出全部配置。
+- 导入配置。
+- 重置配置。
+- 检查路径失效。
+
+导入配置后应自动检查路径失效。  
+路径失效的工具不删除，只标记。
+
+### 5.4.6 外观设置
+
+第一版支持：
+
+- 主题：跟随系统 / 浅色 / 深色。
+- 卡片大小：小 / 中 / 大。
+- 界面缩放。
+- 是否显示工具说明。
+
+### 5.4.7 系统工具恢复
+
+提供按钮：
+
+```text
+恢复默认系统工具
+```
+
+恢复规则：
+
+- 不清空用户现有工具。
+- 不覆盖用户自定义工具。
+- 不重复添加已有默认系统工具。
+- 只补回缺失的默认系统工具。
+- 恢复后默认放入“系统工具”分类。
+- 如果“系统工具”分类不存在，则自动重新创建。
+
+---
+
+## 5.5 图标选择器
+
+图标选择器用于：
+
+- 工具图标。
+- 组合图标。
+- 分类图标。
+
+支持：
+
+```text
+自动获取
+从内置图标库选择
+选择本地图片 / ico
+恢复默认图标
+```
+
+### 5.5.1 内置图标库分类
+
+建议内置图标库分组：
+
+1. 系统
+   - 设置
+   - 终端
+   - 任务管理器
+   - 控制面板
+   - 注册表
+   - 磁盘
+   - 服务
+
+2. 文件
+   - 文档
+   - 图片
+   - 视频
+   - 音乐
+   - 压缩包
+   - 代码
+   - 文件夹
+
+3. 工作区
+   - 工作
+   - 学习
+   - 剪辑
+   - 设计
+   - 开发
+   - 游戏
+   - 资料
+   - AI
+
+4. 操作
+   - 启动
+   - 组合
+   - 脚本
+   - 链接
+   - 收藏
+   - 常用
+   - 临时
+
+5. 通用符号
+   - 星标
+   - 闪电
+   - 工具箱
+   - 齿轮
+   - 火箭
+   - 网格
+   - 标签
+
+### 5.5.2 图标原则
+
+- 默认自动获取，避免用户必须手动设置。
+- 内置图标库用于补充，不要变成复杂素材管理器。
+- 不做图标市场。
+- 不做在线下载图标。
+
+---
+
+## 6. 交互规则
+
+## 6.1 主界面鼠标交互
+
+### 6.1.1 卡片单击
+
+单击卡片只选中，不启动。
+
+选中后：
+
+- 卡片显示选中状态。
+- 顶部“启动 / 编辑 / 删除”按钮启用。
+- 用户可按 Enter 启动。
+
+### 6.1.2 卡片双击
+
+双击卡片启动工具或组合。
+
+如果是组合，则按组合规则执行。
+
+### 6.1.3 卡片右键
+
+右键打开菜单。
+
+菜单包含：
+
+```text
+启动
+编辑
+重命名
+复制
+移动到分类
+加入 / 取消工具箱启动时自动运行
+删除
+```
+
+### 6.1.4 拖拽
+
+支持：
+
+- 当前分类内拖拽排序。
+- 拖到左侧分类上移动分类。
+- 组合编辑界面中拖拽调整成员顺序。
+
+---
+
+## 6.2 主界面键盘操作
+
+第一版支持：
+
+| 快捷键 | 行为 |
+|---|---|
+| 方向键 | 在卡片之间移动选中 |
+| Enter | 启动当前选中工具 / 组合 |
+| Delete | 删除当前选中项，需确认 |
+| F2 | 重命名当前选中项 |
+| Ctrl + F | 聚焦搜索框 |
+| Esc | 清空搜索，或取消当前选中 / 关闭搜索焦点 |
+| Ctrl + N | 新建工具 |
+| Ctrl + G | 新建组合 |
+| Ctrl + , | 打开设置 |
+
+其中最重要的是：
+
+```text
+方向键选择
+Enter 启动
+Ctrl + F 搜索
+```
+
+---
+
+## 6.3 托盘交互
+
+### 6.3.1 单击托盘图标
+
+显示 / 隐藏主界面。
+
+### 6.3.2 右键托盘图标
+
+打开极简菜单：
+
+```text
+显示 / 隐藏主界面
+全局快捷键：开启 / 关闭
+设置
+退出
+```
+
+### 6.3.3 关闭主窗口
+
+关闭主窗口时隐藏到托盘，不退出程序。
+
+---
+
+## 7. 数据模型设计
+
+## 7.1 总体原则
+
+所有能显示为卡片的对象都统一抽象为：
+
+```text
+Tool
+```
+
+也就是说：
+
+- 系统工具是 Tool。
+- 本地工具是 Tool。
+- 网址是 Tool。
+- 组合也是 Tool。
+
+区别只在于 `type` 和配置字段不同。
+
+组合成员不复制工具内容，只保存 Tool ID 引用。  
+自动运行列表也不复制工具内容，只保存 Tool ID 引用。
+
+---
+
+## 7.2 数据文件建议
+
+默认配置目录：
+
+```text
+%AppData%\ToolboxApp\
+```
+
+建议文件结构：
+
+```text
+ToolboxApp
+├─ appsettings.json        // 软件设置
+├─ categories.json         // 分类列表
+├─ tools.json              // 工具列表，包含组合
+├─ autorun.json            // 自动运行排序、间隔、临时启用状态
+├─ hotkeys.json            // 可选，也可并入 tools.json
+├─ icons\                  // 用户自定义图标
+├─ backups\                // 导出或自动备份
+└─ logs\                   // 可选，第一版可不持久化日志
+```
+
+也可以把 `hotkey` 存在 `tools.json` 中。  
+第一版推荐将工具核心配置集中在 `tools.json` 中，避免过度拆分。
+
+---
+
+## 7.3 Category 模型
+
+```json
+{
+  "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 | 更新时间 |
+
+特殊分类：
+
+```text
+cat_system：系统工具
+cat_uncategorized：未分类
+```
+
+`cat_uncategorized` 不允许删除。
+
+---
+
+## 7.4 Tool 模型
+
+```json
+{
+  "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 枚举
+
+```csharp
+public enum ToolType
+{
+    System,
+    Local,
+    Url,
+    Combination
+}
+```
+
+---
+
+## 7.6 IconRef 模型
+
+```json
+{
+  "kind": "BuiltIn",
+  "value": "icon.system.task_manager",
+  "color": "#4F7FFF"
+}
+```
+
+图标类型：
+
+```text
+Auto
+BuiltIn
+Extracted
+LocalFile
+SystemFileType
+```
+
+字段说明：
+
+| kind | 说明 |
+|---|---|
+| Auto | 自动获取 |
+| BuiltIn | 内置图标库 |
+| Extracted | 从 exe 或 lnk 提取后缓存 |
+| LocalFile | 用户选择的本地图标或图片 |
+| SystemFileType | 系统文件类型图标 |
+
+---
+
+## 7.7 Hotkey 模型
+
+```json
+{
+  "enabled": true,
+  "modifiers": ["Ctrl", "Alt"],
+  "key": "T"
+}
+```
+
+规则：
+
+- 至少包含一个修饰键。
+- 不允许多个工具使用完全相同的快捷键。
+- 注册失败时不删除配置，只标记状态。
+
+---
+
+## 7.8 SystemLaunchConfig 模型
+
+```json
+{
+  "systemId": "system.task_manager",
+  "launchTarget": "taskmgr.exe",
+  "launchMethod": "ShellExecute",
+  "runAsAdmin": false
+}
+```
+
+字段说明：
+
+| 字段 | 说明 |
+|---|---|
+| systemId | 固定系统工具 ID |
+| launchTarget | 启动目标 |
+| launchMethod | 启动方式 |
+| runAsAdmin | 是否管理员运行 |
+
+系统工具必须有固定 ID。恢复默认系统工具时根据固定 ID 判断是否缺失。
+
+---
+
+## 7.9 LocalLaunchConfig 模型
+
+```json
+{
+  "path": "D:\\Tools\\Example\\Example.exe",
+  "arguments": "",
+  "workingDirectory": "D:\\Tools\\Example",
+  "runAsAdmin": false,
+  "subType": "Executable",
+  "useShellExecute": true
+}
+```
+
+LocalSubType 建议：
+
+```text
+Executable
+Shortcut
+Script
+File
+Folder
+StoreAppShortcut
+Unknown
+```
+
+注意：用户侧不需要看到这些子类型，只在软件内部用于处理逻辑和显示只读状态。
+
+---
+
+## 7.10 UrlLaunchConfig 模型
+
+```json
+{
+  "url": "https://example.com",
+  "openWithDefaultBrowser": true
+}
+```
+
+第一版不需要指定浏览器。
+
+---
+
+## 7.11 CombinationConfig 模型
+
+```json
+{
+  "failurePolicy": "ContinueOnError",
+  "members": [
+    {
+      "toolId": "tool_001",
+      "enabled": true,
+      "sortOrder": 0,
+      "intervalAfterMs": 1000
+    },
+    {
+      "toolId": "tool_002",
+      "enabled": true,
+      "sortOrder": 1,
+      "intervalAfterMs": 3000
+    }
+  ]
+}
+```
+
+failurePolicy 可选值：
+
+```text
+ContinueOnError
+StopOnError
+```
+
+成员字段：
+
+| 字段 | 说明 |
+|---|---|
+| toolId | 引用的 Tool ID |
+| enabled | 是否启用该成员 |
+| sortOrder | 成员顺序 |
+| intervalAfterMs | 当前成员执行后的等待时间 |
+
+---
+
+## 7.12 AutoRunItem 模型
+
+```json
+{
+  "toolId": "tool_001",
+  "enabled": true,
+  "sortOrder": 0,
+  "intervalAfterMs": 1000
+}
+```
+
+自动运行列表由所有 `autoRunEnabled = true` 的工具和组合动态汇总而成。
+
+`autorun.json` 只保存自动运行列表中的附加配置：
+
+- 顺序。
+- 间隔。
+- 临时启用状态。
+
+不要在 `autorun.json` 中复制工具名称、路径、图标等内容。
+
+---
+
+## 7.13 AppSettings 模型
+
+```json
+{
+  "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 默认系统工具列表建议
+
+第一版建议内置：
+
+1. 设置
+2. 控制面板
+3. 文件资源管理器
+4. 任务管理器
+5. 命令提示符
+6. PowerShell
+7. Windows Terminal
+8. 运行
+9. 注册表编辑器
+10. 服务
+11. 设备管理器
+12. 磁盘管理
+13. 计算器
+14. 记事本
+15. 画图
+16. 截图工具
+17. Windows 安全中心
+18. 网络连接
+19. 环境变量
+20. 卸载程序 / 应用管理
+21. 事件查看器
+22. 资源监视器
+23. 系统信息
+24. 任务计划程序
+25. 远程桌面连接
+
+### 8.1.1 示例默认系统工具定义
+
+```json
+{
+  "id": "system.task_manager",
+  "name": "任务管理器",
+  "launchTarget": "taskmgr.exe",
+  "launchMethod": "ShellExecute",
+  "suggestRunAsAdmin": false,
+  "icon": "icon.system.task_manager"
+}
+```
+
+```json
+{
+  "id": "system.regedit",
+  "name": "注册表编辑器",
+  "launchTarget": "regedit.exe",
+  "launchMethod": "ShellExecute",
+  "suggestRunAsAdmin": true,
+  "icon": "icon.system.registry"
+}
+```
+
+```json
+{
+  "id": "system.windows_update",
+  "name": "Windows 更新",
+  "launchTarget": "ms-settings:windowsupdate",
+  "launchMethod": "ShellExecute",
+  "suggestRunAsAdmin": false,
+  "icon": "icon.system.update"
+}
+```
+
+## 8.2 恢复默认系统工具规则
+
+恢复默认系统工具时：
+
+1. 读取内置系统工具定义。
+2. 检查当前 tools.json 中是否存在相同 `systemId` 的工具。
+3. 已存在则跳过，不重复创建。
+4. 不存在则创建。
+5. 新创建工具放入“系统工具”分类。
+6. 如果“系统工具”分类不存在，则先创建。
+7. 恢复完成后输出日志。
+
+日志示例：
+
+```text
+[10:00:01] 开始恢复默认系统工具
+[10:00:01] 已存在：任务管理器，跳过
+[10:00:01] 已恢复：注册表编辑器
+[10:00:01] 已恢复：磁盘管理
+[10:00:01] 默认系统工具恢复完成：新增 2 项，跳过 18 项
+```
+
+---
+
+## 9. 本地工具设计
+
+## 9.1 用户侧概念
+
+用户不需要区分：
+
+- 自定义程序
+- 文件
+- 文件夹
+- 脚本
+- 快捷方式
+
+统一称为：
+
+```text
+本地工具
+```
+
+用户添加时选择一个路径即可。
+
+## 9.2 内部识别
+
+软件内部根据路径判断子类型：
+
+| 目标 | 子类型 | 处理方式 |
+|---|---|---|
+| .exe | Executable | ShellExecute 启动 |
+| .lnk | Shortcut | ShellExecute 打开快捷方式 |
+| .bat / .cmd | Script | ShellExecute 启动 |
+| .ps1 | File 或高级脚本 | 第一版不重点支持 |
+| 普通文件 | File | 默认软件打开 |
+| 文件夹 | Folder | 资源管理器打开 |
+| 未知扩展名 | Unknown | ShellExecute 尝试打开 |
+
+## 9.3 ShellExecute 优先
+
+第一版原则：
+
+```text
+优先交给 Windows Shell 打开
+```
+
+好处：
+
+- 文件自动用默认软件打开。
+- 文件夹自动用资源管理器打开。
+- 快捷方式自动解析。
+- Store 应用快捷方式也可被打开。
+- 复杂度低。
+
+## 9.4 PowerShell 脚本策略
+
+`.ps1` 比较特殊，因为 Windows 默认可能不是执行，而是打开编辑器，并且涉及执行策略。
+
+第一版建议：
+
+- 不把直接执行 `.ps1` 作为核心能力。
+- `.ps1` 可以按普通文件打开。
+- 后续可增加“高级脚本工具”能力。
+
+第一版重点支持：
+
+```text
+.bat
+.cmd
+.exe
+.lnk
+普通文件
+文件夹
+```
+
+## 9.5 Microsoft Store 应用策略
+
+第一版建议：
+
+```text
+通过 .lnk 快捷方式添加 Microsoft Store 应用
+```
+
+用户可以通过：
+
+```text
+Win + R -> shell:AppsFolder
+```
+
+找到 Store 应用，并创建快捷方式，然后作为本地工具添加。
+
+增强版可增加：
+
+```text
+StoreApp 子类型
+AUMID / AppUserModelID 启动
+```
+
+但第一版不强制实现。
+
+---
+
+## 10. 网址工具设计
+
+网址工具字段：
+
+```text
+名称
+图标
+分类
+说明
+网址
+快捷键
+是否自动运行
+```
+
+启动方式：
+
+```text
+使用默认浏览器打开
+```
+
+URL 校验：
+
+- 如果没有协议，可自动补全 `https://`，或提示用户确认。
+- 明显非法 URL 不允许保存。
+
+第一版不做：
+
+- 指定浏览器。
+- 多浏览器配置。
+- favicon 自动下载。
+
+---
+
+## 11. 组合工具设计
+
+## 11.1 组合核心规则
+
+组合是一种 Tool。
+
+组合的成员只能引用已有 Tool。
+
+组合可以包含：
+
+- 系统工具
+- 本地工具
+- 网址
+- 其他组合
+
+组合不复制成员内容，只保存成员 Tool ID。
+
+## 11.2 组合嵌套规则
+
+允许组合嵌套组合。  
+但必须满足两个约束：
+
+1. 不允许循环引用。
+2. 展开后的最终普通工具集合不能重复。
+
+这里的“普通工具”指非组合工具：
+
+```text
+System
+Local
+Url
+```
+
+组合本身是结构节点，不是最终启动目标。
+
+## 11.3 循环引用示例
+
+禁止：
+
+```text
+组合 A 包含 组合 B
+组合 B 包含 组合 C
+组合 C 包含 组合 A
+```
+
+## 11.4 重复工具示例
+
+禁止：
+
+```text
+组合 A
+├─ 工具 1
+├─ 工具 2
+└─ 组合 B
+   ├─ 工具 2
+   └─ 工具 3
+```
+
+因为组合 A 展开后，工具 2 出现了两次。
+
+## 11.5 组合执行规则
+
+执行组合时：
+
+1. 校验组合引用是否有效。
+2. 校验是否循环引用。
+3. 校验展开后是否重复工具。
+4. 按成员顺序执行。
+5. 跳过禁用成员。
+6. 每个成员执行后等待其配置的间隔。
+7. 如果成员是组合，递归执行该组合。
+8. 如果成员失败，根据组合的 failurePolicy 决定继续或停止。
+9. 所有过程输出到底部信息区。
+
+## 11.6 组合展开算法建议
+
+伪代码：
+
+```csharp
+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);
+}
+```
+
+注意：实际执行时不能只展开成扁平列表，因为还需要尊重嵌套组合自己的失败策略和间隔。  
+因此建议保存两种能力：
+
+1. 校验时可展平，用于检测重复工具。
+2. 执行时按树结构递归执行，用于保留组合级失败策略。
+
+---
+
+## 12. 自动运行设计
+
+## 12.1 自动运行来源
+
+自动运行列表不是用户手动创建的独立任务列表。  
+它来自每个工具或组合的设置：
+
+```text
+autoRunEnabled = true
+```
+
+设置界面只是动态汇总这些项目。
+
+## 12.2 自动运行列表配置
+
+自动运行列表保存附加执行信息：
+
+```text
+toolId
+enabled
+sortOrder
+intervalAfterMs
+```
+
+不保存工具名称、路径、图标等数据。
+
+## 12.3 自动运行执行规则
+
+工具箱启动后：
+
+1. 读取所有 `autoRunEnabled = true` 的工具和组合。
+2. 合并 autorun.json 中的排序、间隔、启用状态。
+3. 按 sortOrder 排序。
+4. 逐项执行。
+5. 某项失败后，记录日志，继续下一项。
+6. 如果某项是组合，则由组合自己的失败策略控制其内部执行。
+7. 自动运行完成后输出汇总。
+
+自动运行不提供全局失败中断。
+
+## 12.4 自动运行示例日志
+
+```text
+[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 快捷键限制
+
+第一版要求：
+
+- 必须包含至少一个修饰键。
+- 不支持纯单键快捷键。
+- 不允许两个工具使用完全相同快捷键。
+
+合法示例：
+
+```text
+Ctrl + Alt + T
+Ctrl + Shift + S
+Alt + Shift + V
+Win + Alt + C
+```
+
+不建议允许：
+
+```text
+A
+F1
+Enter
+Space
+```
+
+## 13.3 快捷键冲突
+
+需要处理两类冲突：
+
+### 13.3.1 软件内部冲突
+
+两个工具不能设置相同快捷键。
+
+### 13.3.2 系统注册失败
+
+如果快捷键被 Windows 或其他软件占用，注册可能失败。  
+此时应：
+
+- 不删除配置。
+- 标记状态为注册失败。
+- 在底部信息区输出提示。
+- 在设置界面快捷键管理中显示状态。
+
+## 13.4 快捷键触发行为
+
+快捷键触发后：
+
+```text
+HotkeyService -> ToolLaunchService.Launch(toolId)
+```
+
+不能在快捷键模块中直接写启动逻辑。
+
+---
+
+## 14. 启动执行服务设计
+
+## 14.1 核心服务
+
+建议核心服务：
+
+```text
+ToolLaunchService
+```
+
+所有启动入口都调用它。
+
+入口包括：
+
+- 双击卡片。
+- 点击启动按钮。
+- 按 Enter。
+- 全局快捷键。
+- 组合成员执行。
+- 启动时自动运行。
+
+## 14.2 启动前校验
+
+普通工具启动前检查：
+
+- 工具是否存在。
+- 工具是否被删除。
+- 本地路径是否存在。
+- 网址是否有效。
+- 启动配置是否完整。
+
+组合启动前检查：
+
+- 成员引用是否存在。
+- 是否循环引用。
+- 展开后是否重复工具。
+
+## 14.3 启动结果定义
+
+第一版只判断：
+
+```text
+是否成功发起启动
+```
+
+不判断：
+
+- 目标程序是否持续运行。
+- 目标程序是否崩溃。
+- 脚本业务逻辑是否成功。
+- 网页是否加载成功。
+
+## 14.4 LaunchResult 模型
+
+```csharp
+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：
+
+```text
+Success
+PathMissing
+InvalidUrl
+AccessDenied
+UserCancelledElevation
+ProcessStartFailed
+CircularReference
+DuplicateTool
+UnknownError
+Skipped
+```
+
+## 14.5 本地工具启动建议
+
+C# 思路：
+
+```csharp
+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 网址启动建议
+
+```csharp
+Process.Start(new ProcessStartInfo
+{
+    FileName = url,
+    UseShellExecute = true
+});
+```
+
+## 14.7 系统工具启动建议
+
+系统工具也使用统一启动流程。  
+系统工具的 `launchTarget` 可以是：
+
+```text
+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。
+- 运行时在内存中维护状态。
+- 修改后立即保存或短延迟防抖保存。
+- 保存前写入临时文件，再替换正式文件，避免写坏配置。
+
+保存流程：
+
+```text
+写入 tools.json.tmp
+写入成功后替换 tools.json
+失败则保留旧文件
+```
+
+## 15.2 数据版本
+
+配置中应包含：
+
+```text
+dataVersion
+```
+
+未来升级时可以做迁移。
+
+## 15.3 导出配置
+
+导出应包含：
+
+- appsettings.json
+- categories.json
+- tools.json
+- autorun.json
+- icons 目录
+
+建议导出为 zip。
+
+## 15.4 导入配置
+
+导入流程：
+
+1. 用户选择导出的 zip 或配置目录。
+2. 解压或读取配置。
+3. 校验数据版本。
+4. 备份当前配置。
+5. 导入新配置。
+6. 检查路径失效。
+7. 输出导入结果。
+
+## 15.5 路径失效检测
+
+检测对象：
+
+- 本地工具路径。
+- 本地图标路径。
+- 工作目录。
+
+路径失效时：
+
+- 不删除工具。
+- 卡片显示“路径失效”标记。
+- 双击启动时输出错误。
+- 右键提供“修改路径”。
+
+日志示例：
+
+```text
+[11:12:00] 路径检查完成：发现 3 个失效工具
+[11:12:00] 路径失效：旧版剪辑工具，D:\OldTools\Editor.exe
+```
+
+---
+
+## 16. 模块划分
+
+第一版建议分为六个核心模块。
+
+## 16.1 托盘与窗口模块
+
+职责：
+
+- 托盘图标。
+- 显示 / 隐藏主窗口。
+- 关闭窗口隐藏到托盘。
+- 托盘菜单。
+- 开机自启。
+
+建议服务：
+
+```text
+TrayService
+WindowStateService
+StartupService
+```
+
+## 16.2 数据存储模块
+
+职责：
+
+- 配置目录管理。
+- JSON 读取保存。
+- 导入导出。
+- 数据版本迁移。
+- 路径失效检测。
+
+建议服务：
+
+```text
+ConfigurationService
+ToolRepository
+CategoryRepository
+BackupService
+PathValidationService
+```
+
+## 16.3 工具管理模块
+
+职责：
+
+- 工具增删改查。
+- 分类管理。
+- 图标管理。
+- 系统工具恢复。
+- 搜索过滤。
+- 卡片排序。
+
+建议服务：
+
+```text
+ToolManager
+CategoryManager
+SystemToolService
+IconService
+SearchService
+```
+
+## 16.4 启动执行模块
+
+职责：
+
+- 启动系统工具。
+- 启动本地工具。
+- 启动网址。
+- 执行组合。
+- 执行自动运行。
+- 失败处理。
+- 输出日志。
+
+建议服务：
+
+```text
+ToolLaunchService
+CombinationLaunchService
+AutoRunService
+LaunchValidationService
+LogOutputService
+```
+
+## 16.5 快捷键模块
+
+职责：
+
+- 注册全局快捷键。
+- 注销全局快捷键。
+- 检测内部冲突。
+- 处理系统注册失败。
+- 全局启用 / 禁用。
+- 快捷键触发工具启动。
+
+建议服务：
+
+```text
+HotkeyService
+HotkeyRegistry
+HotkeyConflictDetector
+```
+
+## 16.6 UI 模块
+
+职责：
+
+- 主界面。
+- 工具编辑弹窗。
+- 组合编辑界面。
+- 设置界面。
+- 图标选择器。
+- 底部信息输出区。
+
+建议 ViewModel：
+
+```text
+MainWindowViewModel
+ToolCardViewModel
+CategoryListViewModel
+ToolEditorViewModel
+CombinationEditorViewModel
+SettingsViewModel
+IconPickerViewModel
+LogPanelViewModel
+```
+
+---
+
+## 17. 搜索设计
+
+搜索框位于主界面顶部。
+
+搜索范围：
+
+- 工具名称。
+- 工具说明。
+- 分类名称。
+- 本地路径。
+- 网址。
+
+搜索行为：
+
+- 实时过滤。
+- 搜索结果跨分类显示。
+- 卡片上标注所属分类。
+- 搜索状态下仍可双击启动、右键管理。
+- 清空搜索框后回到当前分类。
+
+---
+
+## 18. 图标处理设计
+
+## 18.1 图标来源优先级
+
+建议优先级：
+
+1. 用户手动选择的图标。
+2. 内置图标库图标。
+3. 从目标文件自动提取的图标。
+4. 系统文件类型图标。
+5. 默认通用图标。
+
+## 18.2 图标缓存
+
+从 exe、lnk 提取的图标可以缓存到：
+
+```text
+%AppData%\ToolboxApp\icons\cache\
+```
+
+用户手动选择的图标可以复制到：
+
+```text
+%AppData%\ToolboxApp\icons\custom\
+```
+
+避免原文件移动后图标丢失。
+
+## 18.3 图标库
+
+内置图标库可以使用：
+
+- XAML Geometry。
+- SVG 资源。
+- 字体图标。
+- PNG 资源。
+
+建议统一封装为 IconRef，不要让 UI 直接依赖某种具体图标实现。
+
+---
+
+## 19. 错误处理与信息输出
+
+## 19.1 错误处理原则
+
+- 普通错误不弹窗。
+- 输出到底部信息区。
+- 删除、重置、导入覆盖等破坏性操作需要确认。
+- UAC 由系统处理。
+
+## 19.2 常见错误
+
+需要处理：
+
+- 路径不存在。
+- 工作目录不存在。
+- URL 格式错误。
+- 工具引用不存在。
+- 组合循环引用。
+- 组合重复工具。
+- 快捷键内部冲突。
+- 快捷键系统注册失败。
+- 用户取消管理员权限。
+- 配置文件读取失败。
+- 配置文件写入失败。
+- 导入配置失败。
+- 图标加载失败。
+
+## 19.3 日志级别
+
+底部信息区日志建议分级：
+
+```text
+Info
+Success
+Warning
+Error
+```
+
+示例：
+
+```text
+[Info] 开始启动工具：任务管理器
+[Success] 启动成功：任务管理器
+[Warning] 路径失效：旧工具
+[Error] 启动失败：用户取消管理员权限
+```
+
+---
+
+## 20. 开机自启设计
+
+第一版可使用注册表 CurrentUser 启动项。
+
+建议位置：
+
+```text
+HKCU\Software\Microsoft\Windows\CurrentVersion\Run
+```
+
+启动项指向当前程序路径。
+
+注意：
+
+- 只设置当前用户自启。
+- 不需要管理员权限。
+- 设置失败要输出日志。
+- 如果程序路径变化，需更新启动项。
+
+---
+
+## 21. 安全与边界
+
+## 21.1 不做危险自动化平台
+
+本软件支持启动脚本文件，但第一版不提供直接输入命令并执行的能力。  
+避免软件变成复杂脚本执行器。
+
+## 21.2 管理员权限最小化
+
+工具箱自身不默认管理员运行。  
+只有用户明确设置某个工具管理员运行时，才触发 UAC。
+
+## 21.3 导入配置安全提示
+
+导入配置可能包含本地脚本和程序路径。  
+导入后应提示用户检查自动运行和快捷键。
+
+建议导入完成后输出：
+
+```text
+配置导入完成。建议检查自动运行列表和快捷键，确认其中没有不需要启动的工具。
+```
+
+---
+
+## 22. Codex 开发建议
+
+## 22.1 开发顺序建议
+
+建议按以下顺序开发：
+
+### 阶段 1：基础框架
+
+1. 创建 WPF 项目。
+2. 建立 MVVM 基础结构。
+3. 建立配置目录。
+4. 实现 JSON 读写。
+5. 实现基础数据模型。
+
+### 阶段 2：主界面
+
+1. 实现主窗口布局。
+2. 实现分类列表。
+3. 实现卡片网格。
+4. 实现卡片选中。
+5. 实现底部信息输出区。
+
+### 阶段 3：工具管理
+
+1. 实现添加本地工具。
+2. 实现添加网址工具。
+3. 实现编辑工具。
+4. 实现删除工具。
+5. 实现分类管理。
+6. 实现搜索。
+
+### 阶段 4：系统工具
+
+1. 内置默认系统工具定义。
+2. 首次启动创建系统工具分类和工具。
+3. 实现恢复默认系统工具。
+
+### 阶段 5：启动执行
+
+1. 实现 ToolLaunchService。
+2. 实现系统工具启动。
+3. 实现本地工具启动。
+4. 实现网址启动。
+5. 实现日志输出。
+
+### 阶段 6：组合
+
+1. 实现组合编辑界面。
+2. 实现组合成员引用。
+3. 实现循环引用检测。
+4. 实现重复工具检测。
+5. 实现组合执行。
+6. 实现失败策略。
+
+### 阶段 7：自动运行
+
+1. 实现 autoRunEnabled。
+2. 实现设置界面自动运行列表。
+3. 实现排序、间隔、启用状态。
+4. 实现工具箱启动后自动执行。
+
+### 阶段 8：托盘与自启
+
+1. 实现托盘图标。
+2. 实现显示 / 隐藏主界面。
+3. 实现关闭隐藏到托盘。
+4. 实现托盘菜单。
+5. 实现开机自启设置。
+
+### 阶段 9：快捷键
+
+1. 实现快捷键录入。
+2. 实现内部冲突检测。
+3. 实现系统注册。
+4. 实现全局开关。
+5. 实现托盘菜单快捷键开关。
+6. 实现快捷键触发 ToolLaunchService。
+
+### 阶段 10：图标与外观
+
+1. 实现自动图标。
+2. 实现内置图标库。
+3. 实现图标选择器。
+4. 实现主题和卡片大小设置。
+
+### 阶段 11：导入导出与打磨
+
+1. 实现导出配置。
+2. 实现导入配置。
+3. 实现路径失效检查。
+4. 完善错误处理。
+5. 完善键盘操作。
+6. 完成整体测试。
+
+---
+
+## 23. 验收标准
+
+## 23.1 基础验收
+
+- 软件能正常启动。
+- 软件能隐藏到托盘。
+- 关闭窗口不会退出。
+- 托盘菜单能显示 / 隐藏主界面。
+- 托盘菜单能退出软件。
+- 可设置开机自启。
+
+## 23.2 工具验收
+
+- 能添加本地工具。
+- 能添加网址工具。
+- 能启动系统工具。
+- 能启动本地 exe。
+- 能打开文件夹。
+- 能打开普通文件。
+- 能打开网址。
+- 路径失效时不崩溃，并显示提示。
+
+## 23.3 分类验收
+
+- 能新增分类。
+- 能重命名分类。
+- 能删除分类。
+- 删除分类时工具移动到未分类。
+- 分类只能一级。
+- 工具能移动分类。
+
+## 23.4 组合验收
+
+- 能创建组合。
+- 能添加工具成员。
+- 能添加组合成员。
+- 能调整顺序。
+- 能设置间隔。
+- 能禁用成员。
+- 能检测循环引用。
+- 能检测重复工具。
+- 能按失败策略继续或停止。
+
+## 23.5 自动运行验收
+
+- 工具可设置启动时自动运行。
+- 组合可设置启动时自动运行。
+- 设置界面自动汇总自动运行列表。
+- 能调整自动运行顺序。
+- 能设置自动运行间隔。
+- 某项失败后继续执行下一项。
+
+## 23.6 快捷键验收
+
+- 工具可设置快捷键。
+- 组合可设置快捷键。
+- 快捷键能触发启动。
+- 内部冲突能检测。
+- 系统注册失败能提示。
+- 设置界面可统一管理快捷键。
+- 托盘菜单可开启 / 关闭全局快捷键。
+
+## 23.7 数据验收
+
+- 配置能保存。
+- 重启后配置仍存在。
+- 能导出配置。
+- 能导入配置。
+- 导入后能检查路径失效。
+- 能恢复默认系统工具。
+
+---
+
+## 24. 最终产品边界总结
+
+本软件第一版应专注于：
+
+```text
+工具管理
+工具启动
+组合启动
+托盘常驻
+开机自启
+全局快捷键
+本地配置
+```
+
+不要扩展成：
+
+```text
+软件管家
+自动化平台
+插件平台
+脚本 IDE
+任务调度器
+进程监控器
+云同步服务
+```
+
+最重要的设计基准是：
+
+> 用户能用非常低的成本，把自己常用的系统功能、软件、文件夹、文件、网址整理成卡片，并能通过双击、快捷键、组合或启动时自动运行快速打开它们。
+
+如果后续开发中出现功能取舍，应优先保证：
+
+1. 启动稳定。
+2. 数据安全。
+3. 交互简单。
+4. 不误触。
+5. 不过度复杂。
+
+---
+
+## 25. 一句话规格
+
+这是一款 **WPF / .NET 开发的 Windows 个人工具箱软件**，常驻托盘，支持系统工具、本地工具、网址和组合的卡片化管理，支持一级分类、搜索、全局快捷键、工具箱启动时自动运行、组合嵌套、组合执行顺序和间隔、本地 JSON 配置、导入导出、图标自动获取与轻量图标库；其第一版目标是轻量稳定地完成个人工具集中启动，而不是成为复杂自动化平台。
+