commit b33f5e8f299cb5b489903c6ece14d27e19a99fd3
Author: gamewhale <gamewhale@163.com>
Date:   Sat May 9 17:25:03 2026 +0800

    doc:基础文档

diff --git a/详细开发路径文档.md b/详细开发路径文档.md
new file mode 100644
index 0000000..1c722d0
--- /dev/null
+++ b/详细开发路径文档.md
@@ -0,0 +1,115 @@
+# 个人工具箱 (Personal ToolBox) - 详细开发路径文档
+**Target Audience:** OpenCode (DeepSeek-v4-flash)
+**Architecture Pattern:** MVVM (Model-View-ViewModel)
+**Tech Stack:** C# / .NET 8 / WPF / CommunityToolkit.Mvvm
+
+---
+
+## 🤖 【全局系统提示词 (System Prompt)】
+*(在开始任何代码生成前，请先将以下全局设定发给 AI)*
+
+> "你现在是一位资深的 Windows 桌面客户端架构师和 C# WPF 专家。我们将一起开发一款名为“个人工具箱”的本地效率软件。
+> **开发规范要求：**
+> 1. 使用 **.NET 8 WPF** 技术栈。
+> 2. 严格遵循 **MVVM 架构**，引入 `CommunityToolkit.Mvvm` 库以简化开发。
+> 3. 采用**依赖注入 (DI)** 思想管理服务（如存储服务、日志服务）。
+> 4. UI 设计需极简现代化，原生支持暗黑/明亮模式切换。
+> 5. 必须提供完整、可运行的代码，且包含关键的中文注释。
+> 6. 请严格按照我后续给出的 Phase 阶段进行开发，不要跨越阶段。"
+
+---
+
+## 📍 Phase 0: 项目初始化与基础架构
+**【输入给 AI 的指令】：**
+> "现在我们开始 Phase 0：项目初始化。请帮我：
+> 1. 创建一个名为 `PersonalToolBox` 的 WPF 应用程序。
+> 2. 引入必要的 NuGet 包：`CommunityToolkit.Mvvm`、`System.Text.Json`。
+> 3. 建立标准 MVVM 目录结构：`Models`、`ViewModels`、`Views`、`Services`、`Helpers`。
+> 4. 编写 `ILogService` 接口和 `LogService` 实现类，用于管理底部的日志打印栏数据（需要包含时间、日志级别 Info/Warning/Error、日志内容），并能通过事件或 ObservableCollection 将日志实时推送到 UI。
+> 请给出项目结构树以及 `LogService` 的完整代码。"
+
+---
+
+## 📍 Phase 1: 数据模型与本地存储服务
+**【输入给 AI 的指令】：**
+> "进入 Phase 1：数据模型与存储。我们需要用本地 JSON 文件作为数据库。请帮我实现：
+> 1. 在 `Models` 文件夹下创建数据模型：
+>    - `ToolItem`: 包含 Id, Name, IconCode, ExecutablePath, Arguments, CategoryId, HotKey, IsValid(布尔值，用于标记文件是否丢失，不存入JSON，仅运行时计算)。
+>    - `Category`: 包含 Id, Name。
+>    - `AppConfig`: 包含 Theme(Dark/Light), AutoStart(bool), List<Category>, List<ToolItem>。
+> 2. 在 `Services` 下创建 `IDataService` 和 `JsonDataService`：
+>    - 实现数据的加载 (Load) 和 保存 (Save)，文件默认保存在 `AppDomain.CurrentDomain.BaseDirectory + "config.json"`。
+>    - **核心业务逻辑（容错机制）**：在 `Load` 时，遍历所有的 `ToolItem`，检查 `ExecutablePath` 是否存在（使用 `File.Exists`）。如果不存在，将该工具的 `IsValid` 设为 `false`，并调用 `ILogService` 打印警告日志 `[警告] 工具 {Name} 路径失效...`，**绝对不要从集合中删除它**。
+> 请提供这些 Model 和 Service 的完整 C# 代码。"
+
+---
+
+## 📍 Phase 2: 主窗口 UI 布局与主题切换
+**【输入给 AI 的指令】：**
+> "进入 Phase 2：主界面搭建。请帮我编写 `MainWindow.xaml` 及其 ViewModel `MainViewModel.cs`。
+> **UI 布局要求 (Grid 布局)：**
+> 1. **整体分为三部分**：左侧边栏 (宽200)、右侧主体区 (按比例占满)、底部日志栏 (高120)。
+> 2. **左侧边栏**：顶部显示软件名称，中间使用 `ListBox` 绑定 Categories（标签页分类），底部放置一个切换“黑夜/白天模式”的 Button。
+> 3. **右侧主体区**：顶部包含一个 `TextBox` (全局搜索框) 和一个 "添加工具" Button。下方使用 `ItemsControl` + `WrapPanel` 绑定当前分类下的 ToolItems，以卡片形式展示工具图标和名称。
+> 4. **底部日志栏**：包含一个标题栏（附带“清空日志”按钮）和一个只读的 `RichTextBox` 或 `ListBox`，绑定 `LogService` 的日志数据。
+> 
+> **功能要求：**
+> 1. 实现简单的黑夜/白天模式切换（动态替换 WPF 的 `ResourceDictionary` 中的颜色画笔）。
+> 2. 当 `ToolItem.IsValid` 为 false 时，UI 上的工具卡片需变灰（Opacity=0.5）。
+> 请提供 `MainWindow.xaml` 的布局代码、`ThemeHelper` 切换主题代码、以及绑定的 `MainViewModel` 代码。"
+
+---
+
+## 📍 Phase 3: 核心逻辑 - 增删改查与运行进程
+**【输入给 AI 的指令】：**
+> "进入 Phase 3：工具的管理与执行。请帮我实现：
+> 1. **新建/编辑工具弹窗**：创建一个 `ToolEditWindow.xaml`，包含表单字段（名称、路径选择按钮、参数、分类下拉框、快捷键输入框）。保存时更新到 `JsonDataService` 并刷新主界面。
+> 2. **搜索功能**：在 `MainViewModel` 中实现搜索框的过滤逻辑。根据 `TextBox` 的输入，实时过滤展示的 ToolItems。
+> 3. **运行进程服务**：新建 `ProcessExecutionService.cs`。
+>    - 接收 `ToolItem` 作为参数。
+>    - 如果 `!IsValid`，调用日志服务提示用户无法运行。
+>    - 使用 `System.Diagnostics.Process.Start(new ProcessStartInfo { FileName = path, Arguments = args, UseShellExecute = true })` 启动进程。
+>    - 如果发生异常（如权限不足），被 `try-catch` 捕获并将 Error 写入底部日志栏。
+> 请给出编辑窗口的 XAML 与代码，以及进程执行服务类的核心代码。"
+
+---
+
+## 📍 Phase 4: 高级特性 - 全局快捷键拦截 (Win32 API)
+**【输入给 AI 的指令】：**
+> "进入 Phase 4：全局快捷键支持。这个工具箱即使在后台，按下为某个工具配置的全局快捷键也需要能直接拉起该工具。
+> 1. 在 `Helpers` 目录下创建 `HotKeyManager.cs`。
+> 2. 使用 Win32 API (`RegisterHotKey` 和 `UnregisterHotKey`)。
+> 3. 在 `MainWindow.xaml.cs` 中重写 `OnSourceInitialized`，通过 `HwndSource.FromHwnd` 挂载 `AddHook` 拦截系统 Windows 消息 (`WM_HOTKEY`)。
+> 4. 当拦截到快捷键时，根据热键 ID 匹配对应的 `ToolItem`，并调用 `ProcessExecutionService` 启动它，同时在底部日志打印“通过快捷键启动：XXX”。
+> 请提供完整的 Win32 API 声明代码以及快捷键注册、解绑、拦截执行的完整逻辑。"
+
+---
+
+## 📍 Phase 5: 高级特性 - 系统托盘与开机自启
+**【输入给 AI 的指令】：**
+> "进入最后一个阶段 Phase 5：系统托盘与自启动。
+> 1. **系统托盘集成**：不需要引入复杂的第三方库，请直接使用 `System.Windows.Forms.NotifyIcon` 来实现。
+>    - 托盘图标常驻。
+>    - 鼠标左键点击托盘图标：如果主窗口隐藏则显示，如果显示则隐藏。
+>    - 重写 `MainWindow` 的 `OnClosing` 事件：点击右上角关闭按钮时，取消关闭 (`e.Cancel = true`)，改为隐藏窗口 (`this.Hide()`)。
+>    - 右键托盘图标提供菜单：“显示主界面”、“设置”、“彻底退出”。
+> 2. **开机自启动设置**：
+>    - 在 `Helpers` 目录下创建 `AutoStartHelper.cs`。
+>    - 通过写入 Windows 注册表 `HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run` 实现开机自启动。
+>    - 如果启动参数带有 `-autostart`，则主程序启动后直接隐藏到系统托盘，不弹出主窗口。
+> 请给出托盘管理逻辑代码和自启动帮助类的实现代码。"
+
+---
+
+### 💡 辅助除错指南 (针对 DeepSeek 可能会犯的错误)
+
+如果在开发过程中，AI 返回的代码运行报错：
+
+*   **如果 UI 数据不刷新**：
+    > "界面没有刷新。请检查 ViewModel 中的属性是否使用了 `[ObservableProperty]`（CommunityToolkit.Mvvm），以及集合是否使用了 `ObservableCollection<T>` 而不是 `List<T>`。"
+*   **如果快捷键注册失败**：
+    > "RegisterHotKey 返回 false。请确保热键 ID 唯一，且修饰键（Ctrl/Alt/Shift）和虚拟键码（VK）的转换正确。请检查是否与其他系统快捷键冲突，并在 LogService 中打印错误码。"
+*   **如果读取 JSON 失败**：
+    > "反序列化 JSON 失败。请检查 `System.Text.Json` 的配置，是否需要开启 `PropertyNameCaseInsensitive = true`，或者类定义缺少了无参构造函数。"
+*   **如果托盘图标不显示**：
+    > "NotifyIcon 没有显示。请确保为其分配了有效的 `.ico` 文件资源，并且设置了 `Visible = true`。请确保在程序退出时调用了 `NotifyIcon.Dispose()` 释放图标。"
\ No newline at end of file
diff --git a/需求与设计文档.md b/需求与设计文档.md
new file mode 100644
index 0000000..5ed5b4a
--- /dev/null
+++ b/需求与设计文档.md
@@ -0,0 +1,105 @@
+# 个人工具箱 (Personal ToolBox) 需求与设计文档
+
+**文档版本：** V1.0
+**目标平台：** Windows 10 / Windows 11
+
+## 一、 技术栈推荐 (Tech Stack)
+
+考虑到这是一款纯 Windows 平台的本地工具，且需要涉及**全局快捷键注册**、**系统托盘**、**开机自启动**以及**本地文件操作**，我强烈推荐以下技术栈：
+
+*   **开发语言与框架**：**C# + WPF (.NET 8)**
+    *   *推荐理由*：C# 是开发 Windows 桌面应用的最佳选择，调用底层 Windows API（如全局快捷键、托盘）非常稳定。WPF 支持高度定制的 UI，且性能优于 Electron。
+*   **UI 库**：**ModernWpf** 或 **MaterialDesignInXAML**
+    *   *推荐理由*：自带极简风格，原生支持**黑夜/白天模式一键切换**。
+*   **图标库**：内置 **FontAwesome** 或 **Segoe Fluent Icons**（Windows自带字体图标）。
+*   **数据存储**：**本地 JSON 文件** (`config.json`)。
+    *   *推荐理由*：轻量，非常方便进行数据的导入/导出备份，不需要引入笨重的数据库。
+
+---
+
+## 二、 核心功能需求 (PRD)
+
+### 2.1 工具管理模块
+*   **手动添加/编辑**：用户可通过弹窗表单添加工具，字段包含：
+    *   `显示名称` (String, 必填)
+    *   `工具路径` (String, 支持选择文件或直接填写 URL)
+    *   `运行参数` (String, 选填)
+    *   `所属标签页` (String, 下拉选择或新建)
+    *   `工具图标` (从内置图标库中选择)
+    *   `全局快捷键` (选填，如 `Ctrl+Alt+T`)
+*   **工具执行**：双击图标或点击运行按钮，程序根据路径和参数拉起对应工具（支持 `.exe`, `.bat`, `.py`, 网址等）。
+
+### 2.2 分类与检索
+*   **标签页分类 (Tabs)**：以标签页作为一级分类（如：开发工具、系统设置、常用脚本）。
+*   **全局搜索框**：位于界面顶部，输入关键字实时过滤当前所有工具，支持按名称检索。
+
+### 2.3 进阶功能
+*   **独立快捷键触发**：即使工具箱主窗口处于隐藏状态，只要在后台运行，按下为某工具设定的全局快捷键，即可直接运行该工具。
+*   **开机自启动**：在软件设置中提供开关，通过写入注册表或放入 Startup 文件夹实现静默自启（直接最小化到托盘）。
+*   **数据备份与容错机制（重点）**：
+    *   支持导出/导入 `config.json` 文件。
+    *   **容错处理**：程序启动或导入配置时，遍历所有工具的本地路径。若发现路径失效（文件缺失），**不删除该数据**，但在 UI 上将该工具置灰（或打上警告角标），同时在**底部信息打印栏**输出：`[警告] 工具 "XXX" 路径失效，找不到文件: D:\xxx.exe`。
+
+---
+
+## 三、 UI 与交互设计 (UI/UX)
+
+### 3.1 界面布局 (Layout)
+采用经典的三段式布局：
+1.  **左侧导航区 (Left Panel)**：
+    *   顶部：用户头像或软件 Logo。
+    *   中间：**标签页 (Tabs)** 列表，支持垂直切换（如：全部、组A、组B）。
+    *   底部：设置按钮（齿轮图标）、明暗主题切换按钮。
+2.  **右侧主内容区 (Main Panel)**：
+    *   顶部：**搜索框** 和 “添加工具” 按钮。
+    *   中间：工具展示区。采用网格布局 (Grid)，每个工具显示为一个小卡片，包含图标和自定义名称。
+3.  **底部信息栏 (Bottom Log Bar)**：
+    *   高度固定（约 100px），可折叠或清空。
+    *   用于打印软件运行日志，如：`[2023-10-27 10:00] 成功启动：Postman`，`[错误] 快捷键 Ctrl+D 冲突，注册失败`。
+
+### 3.2 窗口形态与托盘交互
+*   **常规状态**：标准 Windows 窗体。
+*   **关闭/最小化行为**：点击右上角“X”或最小化时，默认**隐藏窗口而不是退出进程**。
+*   **系统托盘 (System Tray)**：
+    *   常驻右下角托盘。
+    *   **左键单击托盘图标**：呼出/隐藏主窗口。
+    *   **右键单击托盘图标**：弹出菜单（显示主窗口、设置、退出）。
+
+---
+
+## 四、 系统架构与数据模型 (SDD)
+
+### 4.1 数据结构设计 (`config.json`)
+为了满足数据备份和恢复的需求，配置文件的结构建议如下：
+
+```json
+{
+  "Settings": {
+    "Theme": "Dark",
+    "AutoStart": true
+  },
+  "Categories": [
+    { "Id": "1", "Name": "开发工具" },
+    { "Id": "2", "Name": "常用脚本" }
+  ],
+  "Tools": [
+    {
+      "Id": "uuid-0001",
+      "Name": "内网穿透小工具",
+      "IconCode": "f0c2",          // 内置图标库的字符编码
+      "Path": "D:\\tools\\ngrok.exe",
+      "Arguments": "http 8080",
+      "CategoryId": "1",
+      "HotKey": "Ctrl+Shift+N"
+    }
+  ]
+}
+```
+
+### 4.2 核心模块逻辑描述
+1.  **启动逻辑 (Startup)**：
+    *   读取 `config.json` -> 渲染 UI -> 验证工具路径 -> 若缺失，打印日志到底部信息栏 -> 注册全局快捷键 -> 根据设置决定是否显示主窗口。
+2.  **执行逻辑 (Execution)**：
+    *   使用 C# 的 `System.Diagnostics.Process.Start(Path, Arguments)` 方法执行。如果执行失败（如权限不足），在底部信息栏打印 Exception 错误信息。
+3.  **全局快捷键拦截 (Global Hooks)**：
+    *   使用 Windows API `RegisterHotKey` 进行系统级键盘钩子注册。当捕获到设定的组合键时，触发对应的 `Process.Start` 事件。