# DesktopTool

**Repository Path**: xiaomao12/desktop-tool

## Basic Information

- **Project Name**: DesktopTool
- **Description**: 本地桌面工具快捷管理器
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DesktopTool — 本地桌面工具快捷管理器

> 一款基于 **Electron + Vue3 + TypeScript** 的 Windows 桌面程序快捷启动器。
> 把散落在桌面、文件夹里的 `.exe`、`.bat`、快捷方式，**拖进来、分好组、一键启动**。
> 纯本地 JSON 存储 · 完全离线 · 无任何数据库依赖 · 支持打包为免安装 exe。

---

## 🎯 这个工具是干什么的

一句话：**给你的常用程序做一个「可视化启动面板」**——一个只属于你、按自己习惯分好类的程序坞（Dock）。

它解决的是这类日常烦恼：

| 痛点 | DesktopTool 的解法 |
| --- | --- |
| 桌面图标堆成瀑布，找程序靠肉眼扫 | 按用途分组收纳，再配拼音模糊搜索（输 `jsb` 就能命中「记事本」） |
| 程序藏在 `D:\Program Files\xxx\bin\` 多层目录里，每次进去翻 | 一次拖拽录入，之后双击卡片即启 |
| 脚本启动要开终端、敲命令、记参数 | `.bat / .cmd / .ps1` 录入时配好参数和工作目录，双击等效于带参运行 |
| 重装系统 / 换电脑后配置难搬家 | 全部数据在一个 `config.json`，导出导入一个文件完成迁移 |
| 公司内网不让装来路不明的软件 | 纯本地离线、零网络请求，还提供免安装便携版单文件 |

**典型使用场景**：

- **开发**：前后端联调要同时开 IDEA + Navicat + Docker Desktop + Apifox？收进「开发工具」组，逐个双击；
- **测试 / 运维**：把环境脚本、远程终端、命令行工具收进一组，配好启动参数一键拉起；
- **办公**：微信、浏览器、OA 客户端等高频应用分组收纳，双击即达，不再翻桌面和开始菜单；
- **公共 / 借用电脑**：便携版拷进 U 盘，配置随身带，拔走不留痕。

面向开发、测试、运维、办公人员：日常高频开启多款本地程序和脚本的用户。

---

## 目录

- [这个工具是干什么的](#-这个工具是干什么的)
- [功能总览](#-功能总览)
- [环境要求与快速开始](#-环境要求与快速开始)
- [使用方式](#-使用方式)
- [打包为 exe 可执行文件](#-打包为-exe-可执行文件)
- [数据存储位置](#-数据存储位置)
- [项目结构](#-项目结构)
- [技术栈](#-技术栈)
- [IPC 接口一览](#-ipc-接口一览)
- [安全设计](#-安全设计)
- [常见问题](#-常见问题)

---

## ✨ 功能总览

| 功能 | 说明 |
| --- | --- |
| 🖱️ 拖拽导入 | 从资源管理器直接拖拽 `exe / bat / cmd / lnk / url` 到**分组面板**或**左侧分组**即可录入；拖到窗口空白处会弹出「选择分组」确认框，并按名称**智能推荐分组**；自动解析快捷方式真实目标、提取资源管理器图标 |
| ➕ 浏览添加 | 不方便拖拽时，点击标题栏 ➕ 打开文件选择框添加，效果与拖拽一致 |
| 🗂️ 分组收纳 | 内置「聊天AI / 开发工具 / 数据库 / 设计工具 / 常用软件」五个分组；支持自定义分组（emoji 图标 + 主题色）、重命名、删除（应用自动移入首个剩余分组）；同组应用**单行排列，超出可横向滚动**（鼠标悬停在行上滚动滚轮即可左右滑动） |
| 🚀 一键启动 | **双击卡片**或右键菜单「启动」；带启动参数时以子进程方式运行并可指定工作目录；自动记录启动次数与最近启动时间 |
| ⏳ 启动反馈 | 双击瞬间卡片图标转圈即时反馈；快启动只弹「已启动」确认（带应用图标与启动次数），超 700ms 才补「正在启动…」；失败翻译成口语化原因并给出建议、自动标记卡片；启动中防重复点击，点击提示可提前关闭 |
| 🗂️ 可收起侧边栏 | `Ctrl+B` 或侧栏顶部箭头收起/展开；收起后仅保留图标列（悬停显示应用风格名称提示），筛选、拖拽、右键功能不受影响，状态持久化 |
| ✅ 应用风格确认弹窗 | 删除应用/分组、导入覆盖、迁移数据目录等危险操作均使用应用内确认弹窗（警告图标 + 双按钮，支持 `Esc` / `Enter`），主题联动 |
| 🔄 一键刷新校验 | 右下角 ↻ 一键刷新系统信息，并重新校验全部应用的文件状态（自动同步 ⚠ 标记），带转圈与结果提示 |
| 🔍 全局模糊搜索 | `Ctrl+F` 呼出，同时匹配 **名称 / 路径 / 全拼 / 拼音首字母**（输入 `jsb` 即可命中「记事本」），输入即出结果，应用双击卡片打开；基于 pinyin-pro 纯离线实现 |
| 📏 显示大小三档 | 标题栏右侧「紧凑 / 标准 / 宽松」分段开关，图标、卡片、字号整体缩放，随配置持久化 |
| 🎨 背景主题四套 | 标题栏调色板按钮循环切换，或 ⋮ 菜单选择：**深色 / 纯黑 / 深蓝 / 浅色**，主界面与弹窗同步换肤，随配置持久化 |
| 🔃 两种排序 | 「添加时间」与「常用优先」（启动次数 + 最近启动）一键切换 |
| 🖥️ 实时系统面板 | 底部常驻：主机名、内网 IPv4（自动优选物理网卡）、系统版本、实时时钟、应用/分组统计，30 秒自动刷新 |
| 💾 纯本地持久化 | 无数据库。全部分组 / 应用 / 设置存于单个 `config.json`，原子写入 + `.bak` 自动备份，重启不丢失 |
| 🔌 完全离线 | 零网络请求、不上传任何本机信息，企业内网可放心使用 |
| 🧰 完整管理 | 右键卡片：启动 / 打开所在位置 / 编辑 / 移动到分组 / 复制路径 / 删除；卡片可拖拽跨分组；目标文件被删自动标记 ⚠ |
| 🖼️ 无边框窗口 | 自定义标题栏，最小化 / 最大化 / 关闭齐全，窗口可自由缩放（最小 980×640） |
| 📦 配置备份 | 一键导出 / 导入配置 JSON，换机迁移只需一个文件 |

---

## 🚀 环境要求与快速开始

**环境要求**：Windows 10 / 11，Node.js ≥ 18（推荐 18 / 20 LTS）。

```bash
# 1. 安装依赖（.npmrc 已配置国内 Electron 镜像加速）
npm install

# 2. 开发模式（热更新）
npm run dev

# 3. 类型检查 + 生产构建
npm run build

# 4. 原生能力冒烟测试（无窗口，验证配置读写 / 图标提取 / lnk 解析 / 启动链路）
npm run smoke

# 5. 打包 Windows 可执行文件（详见下文）
npm run dist
```

---

## 📖 使用方式

### ⚡ 60 秒上手

1. **打开应用**：首次启动会自动创建「聊天AI / 开发工具 / 数据库 / 设计工具 / 常用软件」五个示例分组（可随意改名、删除）；
2. **拖入程序**：从资源管理器把 `.exe` / `.lnk` / `.bat` 拖到任意分组面板上松手——图标自动提取，完成录入；
3. **双击启动**：以后要用它，打开 DesktopTool 双击卡片即可，底部弹出「已启动」确认。

就这么多。下面的分组管理、启动参数、搜索、主题都是可选的进阶玩法。

### 🖥️ 界面导览

| 区域 | 内容与作用 |
| --- | --- |
| 标题栏 | 搜索框（`Ctrl+F`）、➕ 添加应用、排序切换、背景主题、显示大小三档、⋮ 更多菜单、窗口控制按钮 |
| 左侧边栏 | 「全部应用」与各分组的筛选入口，可收起（`Ctrl+B`）；**把卡片拖到侧栏分组上可直接改归属** |
| 分组面板 | 每个分组一行卡片，单行排列、超出可横向滚动（悬停行上滚轮横滑）；组名右侧显示应用数量 |
| 底部状态栏 | 主机名 / 内网 IP / 系统版本 / 实时时钟 / 应用统计，右下角 **↻** 一键刷新并校验文件状态 |

### 1. 添加应用（三种方式任选）

| 方式 | 操作 |
| --- | --- |
| **拖拽录入**（推荐） | 从资源管理器选中一个或多个程序/快捷方式 → 按住拖到某个分组面板上松手 → 完成。窗口会显示蓝色拖拽遮罩提示 |
| **拖到空白处** | 拖到窗口其它区域松手 → 弹出「选择分组并导入」窗口 → 每项已带 💡 智能分组推荐，可逐项修改 → 点「导入」 |
| **浏览添加** | 点击标题栏 ➕ → 选择文件 → 弹出编辑窗口（自动提取图标、预填名称）→ 可改名称/分组/备注/启动参数 → 保存 |

> 同一文件重复添加会自动跳过并提示。

### 2. 启动应用

- **双击卡片**启动；
- 启动瞬间卡片转圈反馈，完成后显示「已启动」确认（含应用图标与「第 N 次启动」）；超 700ms 未完成才补「正在启动…」；失败给出口语化原因与建议并自动标记卡片；
- 需要带参数启动的程序：右键 → 编辑 → 展开「高级选项」填写启动参数与工作目录。

### 3. 搜索应用

按 `Ctrl+F` 聚焦搜索框，输入即搜。支持四种匹配方式（任一命中即显示）：

- 中文名：`记事本`
- 路径片段：`system32`
- 全拼：`jishiben`
- 拼音首字母：`jsb`

输入即搜、即输即显；**`Esc`** 一键清空并退出搜索，应用仍双击卡片打开。

### 4. 管理分组与应用

- **右键分组**（面板标题或左侧栏）：添加应用到该分组 / 编辑分组 / 删除分组；
- **右键卡片**：启动 / 打开所在位置 / 编辑 / 移动到分组 / 复制路径 / 删除；
- **按住卡片拖到左侧另一个分组**：直接移动归属；
- 分组可自定义 emoji 图标与主题色，删除分组时其中应用自动移入首个剩余分组。

### 5. 调整显示大小与背景主题

- **显示大小**：点击标题栏右上角的 **紧凑 / 标准 / 宽松** 分段开关，图标、卡片、字号整体缩放，立即生效并记住选择；
- **背景颜色**：点击标题栏的 **调色板按钮** 循环切换（深色 → 纯黑 → 深蓝 → 浅色），或从 **⋮ 菜单 → 背景颜色** 直接选择目标主题；弹窗、右键菜单、提示条同步换肤。

### 6. 收起 / 展开侧边栏

- 点击**侧栏顶部箭头**或按 **Ctrl+B**，侧栏收起为 56px 图标列（悬停显示分组名称），内容区自动加宽；
- 收起态下点击筛选、拖拽归组、右键菜单功能完整保留，状态持久化。

### 7. 备份、迁移与数据目录

- **导出配置** / **导入配置**：把全部分组/应用/设置保存为一个 JSON 文件，或一键恢复（覆盖前二次确认）；
- **自定义数据目录**：打开 **⋮ → 关于 DesktopTool**，在「数据目录」区块点击 **更改…**，选择新文件夹后应用自动重启生效；点击 **恢复默认目录** 可切回 `%APPDATA%\desktoptool`。各目录的配置相互独立：目标目录已有 `config.json` 时直接使用它（不会被覆盖），为空时才把当前配置迁移过去，因此反复切换不会丢任何一侧的数据。数据目录的位置记录在 `%APPDATA%\desktoptool\datapath.txt` 指针文件里（位于默认数据目录内部、与 `config.json` 同级），因此请勿删除默认数据目录，否则指针会随之删除、导致切换状态丢失；若启动时自定义目录暂不可用（盘未就绪 / 权限变化），会回退默认位置并在界面明确提示；
- **打开数据目录**：直接定位到配置文件所在文件夹；
- **刷新校验**：点击右下角 **↻**，刷新系统信息的同时重新校验全部应用的文件状态（自动同步 ⚠ 标记）。

### ⌨️ 快捷键与操作速查

| 操作 | 作用 |
| --- | --- |
| 双击卡片 | 启动应用 |
| 右键卡片 / 分组 | 打开对应操作菜单（启动 / 编辑 / 移动 / 删除…） |
| `Ctrl + F` | 聚焦搜索框 |
| `Esc`（搜索时） | 清空关键词并退出搜索 |
| `Ctrl + B` | 收起 / 展开侧边栏 |
| `Esc` / `Enter` | 在确认弹窗中取消 / 确认 |
| 拖拽 `.exe` 等文件入窗口 | 录入应用（拖到分组直录，拖到空白处弹分组选择） |
| 拖拽卡片到侧栏分组 | 移动应用归属 |
| 悬停分组行 + 滚轮 | 该行横向滚动 |

---

## 📦 打包为 exe 可执行文件

### 一条命令打包

```bash
npm run dist
```

命令执行 `electron-vite build`（前端/主进程/预加载三端构建）后调用 `electron-builder` 完成打包，产物全部输出到 **`dist/`** 目录：

| 产物 | 说明 |
| --- | --- |
| `DesktopTool Setup 1.0.0.exe` | **NSIS 安装包**（约 79MB）：双击安装，可选安装目录，自动创建桌面快捷方式，带卸载器 |
| `DesktopTool 1.0.0.exe` | **便携版单文件**：免安装，拷贝到任意位置（含 U 盘）双击直接运行 |
| `win-unpacked/` | 免打包目录版，其中 `DesktopTool.exe` 可直接运行 |

三个入口功能完全一致，均读取同一份 `%APPDATA%\desktoptool\config.json` 配置。

### 打包配置说明

打包参数集中在 **`electron-builder.yml`**：

```yaml
appId: com.desktoptool.app
productName: DesktopTool        # exe 名称与安装目录名
win:
  target:
    - target: nsis              # 安装包
    - target: portable          # 便携版单文件
nsis:
  oneClick: false               # 非一键安装，允许选择目录
  allowToChangeInstallationDirectory: true
  createDesktopShortcut: true   # 自动创建桌面快捷方式
```

### 自定义应用图标

项目已内置应用图标（`build/icon.ico`，多尺寸 256~16px），由 **`scripts/make-icon.cjs`** 生成——纯 Node 实现（SDF 光栅化 + 手写 PNG/ICO 编码，不依赖 GPU 与第三方库），设计源参数直接写在脚本常量里：

```bash
# 修改 scripts/make-icon.cjs 中的设计参数后重新生成
node scripts/make-icon.cjs
```

生成后重新 `npm run dist` 即可，exe / 安装包 / 任务栏图标自动更新；运行期任务栏图标通过 `app.setAppUserModelId`（与 `appId` 一致）关联。

### 常见打包问题

- **SmartScreen 提示“已保护你的电脑”**：安装包未做代码签名（证书需购买），点击「更多信息 → 仍要运行」即可；企业内网分发可联系管理员加白名单；
- **首次打包较慢**：electron-builder 需下载 NSIS / winCodeSign 工具链，`.npmrc` 已配置国内镜像自动加速；
- **只想要安装包**：把 `electron-builder.yml` 中 `target: portable` 一段删除即可。

---

## 💾 数据存储位置

| 文件 | 位置 |
| --- | --- |
| 主配置 | `%APPDATA%\desktoptool\config.json` |
| 自动备份 | 同目录 `config.json.bak`（每次覆盖写入前生成） |

> 开发模式与打包版共用该目录（主进程已显式固定 userData 路径），配置无缝衔接。

`config.json` 结构（对应 `src/shared/types.ts` 中的 `AppConfig`）：

```jsonc
{
  "version": 1,
  "groups": [
    { "id": "g_dev", "name": "开发工具", "icon": "🛠️", "color": "#4f8cff", "order": 1 }
  ],
  "apps": [
    {
      "id": "a_xxx",
      "name": "VS Code",
      "path": "D:\\tools\\Code.exe",       // 程序绝对路径
      "args": "",                            // 启动参数（可选）
      "cwd": "",                             // 工作目录（可选，默认程序所在目录）
      "groupId": "g_dev",
      "icon": "data:image/png;base64,...",   // 48px PNG dataURL（已裁透明边）
      "kind": "exe",                         // exe / bat / lnk / url / folder / other
      "launchCount": 3,                      // 启动次数
      "lastLaunchAt": 1756000000000
    }
  ],
  "settings": {
    "sortMode": "default",                   // default 添加时间 | frequent 常用优先
    "density": "standard",                   // compact 紧凑 | standard 标准 | large 宽松
    "theme": "dark",                         // dark 深色 | black 纯黑 | blue 深蓝 | light 浅色
    "sidebarCollapsed": false                // 侧边栏收起状态
  }
}
```

图标以 48×48 PNG dataURL 内联存储（单条约 5KB，百级应用约 1MB），单文件即可整体备份迁移。

---

## 🏗️ 项目结构

```
DesktopTool/
├── electron.vite.config.ts        # electron-vite 构建配置（main / preload / renderer 三段）
├── electron-builder.yml           # 打包配置（NSIS 安装包 + 便携版单文件）
├── tsconfig.json                  # 全工程单一 TS 配置（vue-tsc 类型检查）
├── .npmrc                         # Electron / builder-binaries 国内镜像
├── scripts/
│   └── smoke.cjs                  # 无窗口冒烟测试：配置IO / 图标提取 / lnk解析 / 启动链路
└── src/
    ├── shared/                    # ★ 共享类型层（三端同源，规避弱类型隐患）
    │   ├── types.ts               #   AppItem / GroupItem / AppConfig / SystemInfo / Density ...
    │   └── api.ts                 #   DtApi：渲染层可用原生能力的完整接口定义
    ├── main/                      # Electron 主进程
    │   ├── index.ts               #   入口：单实例锁、无边框窗口、userData 固定、安全策略
    │   ├── config.ts              #   config.json 读写（原子写 + .bak 备份 + 结构校验 + 图标补齐）
│   │                          #   自定义数据目录：指针文件读写 / 迁移 / 恢复默认
    │   ├── icon.ts                #   图标提取（getFileIcon → 透明边裁剪 → PNG dataURL）
    │   ├── system.ts              #   主机名 / 内网IP（物理网卡优先）/ 系统版本 / CPU / 内存
    │   └── ipc.ts                 #   全部 IPC handler（解析拖入路径 / 智能图标 / 启动 / 对话框 / 窗口控制）
    ├── preload/
    │   └── index.ts               # contextBridge 暴露 dtApi（webUtils.getPathForFile 等）
    └── renderer/                  # Vue3 渲染层
        └── src/
            ├── App.vue            # 布局骨架 + 全局文件拖拽 + 密度切换重建 + 快捷键
            ├── stores/            # Pinia
            │   ├── config.ts      #   分组/应用/设置 + 250ms 防抖持久化 + 启动状态
            │   ├── ui.ts          #   弹窗 / 右键菜单 / Toast / 拖拽遮罩
            │   └── system.ts      #   1s 时钟 + 30s 系统信息刷新
            ├── utils/
            │   ├── search.ts      #   名称/路径/全拼/首字母 模糊匹配
            │   ├── suggest.ts     #   按名称关键词智能推荐分组
            │   └── misc.ts        #   uid / 主题色 / emoji 常量
            ├── components/        # TitleBar / SideBar(可收起) / GroupSection / AppCard / ContextMenu
            │                      # ConfirmModal / AboutModal / SearchBar / SysFooter / EmptyState
            │                      # AppEditModal / GroupModal / MoveModal / DropChooserModal
            │                      # Icon（内置线性 SVG 图标集）/ Toasts
            └── styles/main.css    # 深色工作台主题（CSS 变量驱动，三档密度）
```

## 💻 技术栈

| 层 | 选型 | 说明 |
| --- | --- | --- |
| 框架 | Electron 33 + Vue 3.5 | Composition API + `<script setup>` |
| 语言 | TypeScript 5.6（strict） | 共享类型层贯通三端，全量 vue-tsc 检查 |
| 构建 | electron-vite 2 / Vite 5 | 三端统一构建，热更新 |
| 状态 | Pinia 2 | setup 风格 store |
| 搜索 | pinyin-pro | 全拼 / 首字母匹配，纯离线 |
| 打包 | electron-builder 25 | NSIS 安装包 + 便携版单文件 |

---

## 🔌 IPC 接口一览

渲染层唯一入口为 preload 通过 `contextBridge` 暴露的强类型 `dtApi`（接口定义见 `src/shared/api.ts`）：

| 通道 | 类型 | 作用 |
| --- | --- | --- |
| `dt:config:load / save` | invoke | 读取 / 原子写入 config.json（load 时自动补齐缺失图标） |
| `dt:config:export / import` | invoke | 导出 / 导入配置 JSON |
| `dt:config:open-dir` | invoke | 打开数据目录 |
| `dt:apps:parse-paths` | invoke | 解析拖入路径：类型 / 名称 / lnk 真实目标 / 图标 dataURL |
| `dt:app:launch` | invoke | 启动程序（openPath 或带参子进程，cmd/ps1 特殊处理） |
| `dt:app:reveal` | invoke | 资源管理器中定位文件 |
| `dt:sysinfo:get` | invoke | 主机名 / 内网IP / 系统版本 / CPU / 内存 |
| `dt:dialog:pick-app / pick-icon / pick-folder` | invoke | 原生文件 / 图片 / 目录选择 |
| `dt:icon:from-file` | invoke | 本地图片规范化为 PNG dataURL |
| `dt:file:exists` | invoke | 文件存在性（丢失检测） |
| `dt:datadir:get / set / reset` | invoke | 数据目录查看 / 迁移到自定义目录 / 恢复默认（自动重启生效） |
| `dt:app:version` | invoke | 应用版本号（关于弹窗） |
| `dt:ui:repaint` | send | 强制整帧重绘（密度切换兜底） |
| `dt:window:minimize / toggle-maximize / close` | send | 无边框窗口控制 |
| `dt:window:maximized` | 主进程推送 | 最大化状态变化 |

---

## 🔐 安全设计

- `contextIsolation: true` + `nodeIntegration: false`，渲染层零 Node 能力；
- 渲染层唯一原生入口为 preload 暴露的强类型 `dtApi`，IPC 参数三端同构校验；
- 拖拽取路径使用 Electron 32+ 标准方案 `webUtils.getPathForFile`（`File.path` 已移除）；
- 禁止渲染进程导航与 `window.open`；
- 零外发网络请求，`config.json` 仅存本机。

## ❓ 常见问题

- **给快捷方式填了启动参数没生效？** `.lnk` / `.url` 走系统默认双击行为，暂不支持附加参数；需要参数请直接录入目标程序本体（`.exe` / `.bat`），在「编辑 → 高级选项」里配置。
- **启动应用时想看到反馈？** 双击瞬间卡片图标会转圈；快启动只出「已启动」确认条（带应用图标与启动次数），超 700ms 才补「正在启动…」；点击确认条可提前关闭。
- **快捷方式显示成通用图标？** 应用对 `.lnk` 会自动解析真实目标程序并提取其图标（含透明边裁剪，图形更饱满）；旧数据无图标的，启动时自动补齐，也可在「编辑 → 重新提取」手动刷新。
- **想自定义图标？** 右键卡片 → 编辑 → 「选择图片」，支持 png/ico/jpg 等，自动规范化。
- **启动 .bat 出现黑窗口？** 与双击运行脚本行为一致，脚本执行完窗口自动关闭。
- **卡片出现 ⚠？** 目标文件被移动/卸载，会自动标记；修复路径或删除该卡片即可，也可点右下角 **↻** 重新校验。
- **配置坏了？** 同目录 `config.json.bak` 是上一次写入的备份，改回文件名即可恢复。
- **想把配置挪到别的磁盘？** ⋮ → 关于 DesktopTool → 数据目录「更改…」，迁移后自动重启生效。
- **切换显示大小后界面没变化？** 已内置强制整帧重绘兜底；如仍出现，切走再切回即可（该问题仅个别机器的绘制驱动场景出现）。

## 📄 许可

仅供学习与内部工具使用。