# 快速启动 FastRun **Repository Path**: ahsin/app_fast_run ## Basic Information - **Project Name**: 快速启动 FastRun - **Description**: FastRun 快速启动 — 标签页式快捷启动器，支持 Windows 与 macOS。app/ 文件夹即标签页，settings.ini 便携配置。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: http://www.cnmlb.com - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-11 - **Last Updated**: 2026-10-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 快速启动 FastRun 标签页式快捷启动器 · Windows / macOS · v3.8 > **特别致敬鸣谢：急速启动 HurryRun** —— 卒于 x86 年代（官方站 `windstyle.net` 早已不在） > > 本程序是它的精神续作。
主界面 装得多的标签
主界面。顶栏左上角放大显示鼠标经过的图标，右上角依次是搜索、图钉、设置、关闭；
标签栏与内框都会跟着窗口缩放。		 装得多的标签。一个标签 38 项也照排：图标顶边对齐，名字再长也会换行显示完整
（CFFExplorerv80 这种没有空格的长名字同样处理）。
设置：标签页 设置：界面页
设置 → 标签。app/ 下每个文件夹就是一个标签，可以增删、改名、排序。 设置 → 界面。透明度、标签栏位置（上/下/左/右）、默认尺寸、
隐藏模式（一直显示 / 呼叫时显示）、隐藏竖向滚动条。
## 桌面越来越乱？ 你电脑的桌面快捷方式是不是越来越多？桌面上的杂乱文件是不是也越来越多？ 大厂的桌面文件整理工具是不是都是广告？整理完，效果也不尽如人意？ **快来试试快速启动 FastRun 吧！** ## 能做什么 1. **自定义是否开机自动启动** 2. **自行创建文件夹到标签、自行指定文件夹到标签** —— 设置里也能创建标签 3. **标签页就是一个文件夹容器，什么都能往里放** —— 不限格式，程序、文档、图片、压缩包都行 4. **可自定义标签排序** 5. **单击标签中的图标即可快速启动** 6. **可自定义呼出快捷键** —— 即使被别的程序占用了同一个组合，照样触发 7. **可自定义软件尺寸，标签容器内的图标自动对齐** 8. **支持搜索目标图标** —— 跨全部标签搜索，不用记得它放在哪个标签里 9. **标签页可自定义设置靠上、靠下、靠左、靠右** 10. **双模式**： - **呼叫时显示** —— 平时隐藏到系统图标栏，快捷键呼出，启动图标后继续隐藏 - **一直显示** —— 面板常驻，点完图标不消失 11. **可完全自定义主界面配色** 12. **自动记住窗口尺寸、启动位置** 13. **本程序免费开源，随意分享，禁止转售** ## 界面结构：三个框 主界面是**三个矩形**叠出来的，尺寸不是写死的 —— 边框与内框会跟着窗口缩放： ``` ┌──────────────────────────────────────────────────────┐ ← 外框（圆角矩形，= 窗口） │ [图标] 当前鼠标经过的快捷方式 📌 ⚙ ✕ │ 顶栏直接画在外框上 │ 描述 / 文件路径 │ 它不属于内框 │ ┌──────┬───────────────────────────────────────────┐ │ │ │ 常用 │ │ │ ← 按钮框（透明） │ │ 工具 │ ▣ ▣ ▣ ▣ │ │ + 内框（浅色内容区） │ │ 影音 │ 名称 名称 名称 名称 │ │ │ │ 开发 │ │ │ │ └──────┴───────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────┘ ``` | 框 | 形状 | 说明 | | --- | --- | --- | | **外框** | 圆角矩形 | 四周那一圈深色，顶栏画在它上面 | | **内框** | **直角**矩形 | 浅色内容区，四角都是直角 | | **按钮框** | **直角**矩形 | **透明**，露出外框色；里面的标签按钮自带颜色 | > 标签栏四个方向都可用（上 / 下 / 左 / 右），在设置 →「界面」里改。 > **缩放窗口时，按钮框只锚定一条边**（居上锚左右、居下锚左右底、 > 居左/居右锚自己那一侧的边并与内框顶边对齐），所以怎么拉都不会跑偏。 > 标签按钮的圆角方向跟着停靠位置走：**贴着内框的那两个角是圆的**， > 居上圆上面两角、居下圆下面两角、居左圆左面两角、居右圆右面两角。 --- ## 一、核心概念：`app/` 文件夹就是数据库 ``` FastRun/ ← 软件目录（便携） 快速启动FastRun.exe settings.ini ← 配置（自动生成） app/ ← 标签页来源 常用/ ← 「常用」标签 微信.lnk Edge.lnk 工具/ 7-Zip.lnk example.url 影音/ PotPlayer.lnk ``` - **每个子文件夹 = 一个标签页**，文件夹名就是标签名。 - **文件夹里的东西 = 容器里显示的东西**，不转换、不复制、不改名，拖什么进去就显示什么。 - 用任何资源管理器往 `app/` 里丢文件都可以，界面刷新（`F5`）后即可看到。 - 标签为空时，界面上会提示该文件夹的完整路径，方便直接去放文件。 支持的文件类型（有什么就显示什么）： | 平台 | 能拖进来的东西 | | --- | --- | | Windows | `.lnk` 快捷方式、`.url` 网址、`.exe` 程序、任意文档、任意文件夹 | | macOS | `.app` 应用、`.webloc` 网址、任意文档、任意文件夹 | | 通用 | `.url` / `.webloc` 里的网址会被识别出来，点击直接用浏览器打开 | **图标规则**：文件自带图标就用自带的；取不到就向系统要该文件的图标。 `.lnk` 会先解析出它指向的真实程序，用那个程序的图标 —— 否则只会拿到千篇一律的快捷方式小箭头。 ## 二、快速开始 需要 **Python 3.11+**（开发运行）。 ```bash python -m pip install PySide6 python run.py ``` 首次启动时 `app/` 里没有标签，主界面会显示 `app` 文件夹路径和一个「打开设置新建标签」按钮。 建完标签，面板会立刻出现对应的标签页 —— 一边设一边看。 ### 打包 先用 PyInstaller 把环境备齐： ```bash python -m pip install pyinstaller ``` 然后打包（两个平台各一条命令，互不影响）： ```bash python tools/dist-win.py # Windows：出文件夹版（唯一形态） python tools/dist-win.py --no-measure # 同上，但跳过启动耗时测量 python tools/dist-mac.py # macOS：直接出 .app ``` 产物： | 平台 | 形态 | 路径 | 说明 | | --- | --- | --- | --- | | Windows | **文件夹版**（EVB 的输入） | `dist/win-unpacked/FastRun/快速启动FastRun.exe` | 含 `_internal/`（Qt 的 dll 等） | | macOS | `.app` bundle | `dist/mac/快速启动FastRun.app` | 必须 onedir（**不要 onefile**：单文件打不了公证票据，`stapler` 报 `Error 65`） | > **发布用的单文件 exe 由 Enigma Virtual Box 从这个文件夹做出来**：EVB 把整个文件夹 > **虚拟化进一个 exe**，程序读文件时**就地映射、不落盘解压**，所以启动快（实测 1~3 秒）、 > 强杀也不留垃圾。不用 PyInstaller 的 `--onefile`（那个选项已经删掉了）。 > **`dist/` 已在 `.gitignore` 中**，仓库里不含 exe / `.app`。产物上传到 Gitee 的 Release 附件。 > mac 版产物**未签名**：首次打开会被 Gatekeeper 拦，右键 →「打开」放行； > 要发给别人得自己走一遍签名 + 公证（流程与凭据见「我的签名公正」技能）。 > 数据（`app/`、`settings.ini`、`appicon/`）在**软件自己所在目录**：Windows 是 exe 旁边 > （单文件版也不会留到 `%TEMP%` 解压目录里，由 `python tools/verify-portable.py` 守着）； > **macOS 则在 `.app` 内部**（`Contents/MacOS/`）—— 所以覆盖升级会连标签一起删， > 见第九节。 > **版本号只写在 `fastrun/version.py` 一处**，两个打包脚本各自取它：Windows 写进 exe > 属性页，macOS 写进 `Info.plist` 的 `CFBundleShortVersionString` / `CFBundleVersion` > （访达「显示简介」看的就是这两个；PyInstaller 默认写 `0.0.0`，所以由 `dist-mac.py` 自己改）。 ### 图标怎么改 **改 `ui/icon.png` 这一张就够了**（用 PS 美化后覆盖它）： ``` ui/icon.png ← 唯一要维护的素材 ↓ 编译时自动（tools/生成图标.py） build/icon/icon.ico icon.icns icon.png run_icon.png ↓ exe 图标 + 界面/托盘图标 ``` 编译时会自动生成 12 档尺寸的 `.ico`、8 档的 `.icns` 和运行时用的 PNG。 `ui/` 里不要放生成物，也**不会**被打进包。 > `.icns` 里**故意没有 16×16 与 32×32 这两档**。自己拼容器时这两档要写成 `icp4` / > `icp5`，而 macOS 的 IconServices 读不了这两个类型码 —— **只在小尺寸上渲染成彩色噪点** > （36 及以上正常，所以不容易发现）。去掉之后 16px 由系统从 32px 那档缩下去， > 实机看是干净清晰的。详见 `tools/生成图标.py` 里 `ICONSET` 的注释。 ## 三、界面与操作 ### 顶栏 | 元素 | 说明 | | --- | --- | | 左上角大图标 | **放大显示当前鼠标经过的快捷方式**的图标，并显示名称与描述；鼠标不在任何图标上时显示本程序图标 | | 📌 图钉 | 切换「一直显示」/「呼叫时显示」。**朝上 = 呼叫时显示，朝下并变黄 = 一直显示** | | ⚙ 齿轮 | 打开设置窗口 | | ✕ 关闭 | 隐藏到系统托盘（不退出程序） | ### 窗口显示逻辑 | 模式 | 行为 | | --- | --- | | **一直显示**（图钉朝下、变黄） | 窗口保持置顶，点到任何其他地方都不会收起；只能点 ✕ 隐藏 | | **呼叫时显示**（图钉朝上） | 用快捷键呼出；**点击窗口以外的任何地方自动隐藏**；点击快捷方式后也隐藏 | | **打开设置窗口期间** | 主界面保持显示，**设置窗口停靠在它右侧**，改配色 / 尺寸 / 标签位置时能立刻看到效果。关闭设置后按当前模式恢复 | ### 标签页 - **新增标签**：设置 → 标签，在顶部输入框里填名称并点「新增标签」，会在 `app/` 下**生成同名文件夹**。 - **重命名标签**：设置里点该行的「重命名」，名称就地变成可编辑输入框；**文件夹同步改名**。 - **删除标签**：设置里点该行的「删除」，会弹确认框并写明**文件夹完整路径与其中项目数量**； 确认后连同文件夹一起删除，**里面的东西也会一起没了，无法恢复**。 - 每行还有 ↑ ↓ 调整顺序、「打开」在文件管理器里定位该文件夹。 - 单击标签切换。把文件拖到某个标签上，会**剪切（移动）**进那个标签（并自动切换过去）； 按住 Ctrl 拖则是复制。若目标里已有同名文件，会弹窗问「覆盖 / 取消」，而不是自动改名成「名字 (2)」。 - 也可以在资源管理器里 Ctrl+X 剪切文件，回到面板按 **Ctrl+V**，同样会**剪切（移动）**进当前标签； 若在资源管理器里按的是 Ctrl+C（复制），粘贴时则保留源文件。同名冲突一样弹窗问「覆盖 / 取消」。 ### 快捷方式容器 - **单击即启动，无需双击**。 - 鼠标经过时，顶栏放大显示该图标。 - 右键菜单：打开 / 打开所在文件夹 / 在文件夹中显示 / 刷新图标 / 删除（移到回收站）。 - 空白处右键：添加文件 / 把已有文件夹添加为标签 / 打开 app 文件夹 / 刷新 / 设置 / 隐藏。 ### 快捷键 | 按键 | 作用 | | --- | --- | | `Command+Option`（macOS 默认） | 显示 / 隐藏主界面（**全局有效**，可改） | | `Win+Alt`（Windows 默认） | 同上 | | `Esc` | 关菜单 → 隐藏窗口 | | `←` `→` `↑` `↓` | 在容器中移动选择 | | `Enter` / `Space` | 启动选中项 | | `Tab` / `Shift+Tab` | 切换标签 | | `1`–`9` | 跳到第 N 个标签 | | `F5` | 重新扫描 `app/` 并刷新 | > **macOS 上要先授「辅助功能」权限**（系统设置 → 隐私与安全性 → 辅助功能）， > 没授时全局快捷键**静默失效** —— 这时设置页会直接把原因写出来。 > 两个默认值都是**纯修饰键组合**（都没有主键）：凑齐即触发，并且**不吞按键** —— > 吞掉的话系统会跟丢修饰键状态，别的程序的快捷键就坏了。 > **没有鼠标键呼出。** 这个功能实现过又删掉了：它需要装系统级的低层鼠标钩子， > 而那东西的回调跑在桌面输入队列里，写错一点点就会让**整个桌面的鼠标不能动** > （实测踩过两次）。代价远大于收益 —— 理由详见 [HANDOVER.md](HANDOVER.md) 的 5.3。 ## 四、设置（`settings.ini`） 所有设置写在**软件目录下的 `settings.ini`**，纯文本、可直接手改，程序保存时会保留文件里未知的键。 ```ini [hotkey] keyboard=Win+Alt ; 键盘组合键（macOS 默认 Command+Option），留空 = 禁用 [window] opacity=95 ; 30-100，主界面透明度 tab_position=top ; top / bottom / left / right pin_mode=summon ; pinned = 一直显示，summon = 呼叫时显示 width=700 height=480 [colors] ; 自定义控件配色，改完立即生效 back=#3D4353 ; 窗体背景 barBack=#3D4353 ; 顶栏背景 barText=#FFFFFF ; 顶栏文字 panelBack=#CFDAE7 ; 内容区背景 panelText=#111111 ; 快捷方式文字 tabBack=#22262F ; 标签背景 tabText=#FFFFFF ; 标签文字 tabActiveBack=#CFDAE7 ; 选中标签背景 tabActiveText=#1B64B4 ; 选中标签文字 border=#3A4569 ; 边框 highlight=#0274D1 ; 高亮 [startup] auto_start=0 ; 1 = 开机自动启动 [tabs] order=常用|工具|影音 ; 标签顺序记录 last=常用 ; 上次打开的标签 ``` 设置窗口有六个页签：**标签 / 快捷键 / 界面 / 配色 / 通用 / 关于**，改动即时写入并生效。 颜色以外的页面用**系统原生控件**，跟着你的系统主题走（深色系统就是深色）。 配色页带实时预览，可一键恢复默认。 > **按了没反应时先看设置页的「快捷键」页**：macOS 没授「辅助功能」权限时会静默失效， > 原因就写在那儿。默认值两平台互不冲突（`Command+Option` / `Win+Alt`）， > 但 `Alt+Space` 在 Windows 上被系统占用（打开窗口左上角菜单），想换回它多半按不动 —— > 建议改用 `Ctrl+Space`、`Ctrl+Alt+F9` 这类组合。 > > 顺带一提：本程序**不跟系统注册热键**，走的是低层钩子 —— > 所以**别的程序占用了同一个组合，本程序照样触发**。 ## 五、关于窗口 **托盘菜单**的「关于」会打开独立窗体：居中放大显示软件 logo，然后四行信息 —— **快速启动 FastRun** / 项目地址 / 下载地址 / Ahsinsoft ahsin@qq.com， 两个网址可直接点击，用系统默认浏览器打开。 ## 六、系统托盘 托盘图标右键菜单：**显示主界面 / 设置 / 关于 / 退出**。左键单击托盘图标也会显示主界面。 ## 七、开发辅助脚本 全部是 Python，大部分不需要显示器也能跑。 | 脚本 | 用途 | | --- | --- | | `python run.py --self-test` | **改完代码先跑这个**：走完整启动路径、逐项检查后干净退出 | | `pytest -q` | 216 项单元测试（其中 13 项只有 Windows 能跑，在 macOS 上必然失败） | | `python tools/probe_tabs.py` | 标签栏四个停靠位置是否都对 | | `python tools/probe_tab_center.py` | 标签文字居中（量实际像素） | | `python tools/probe_settings_dock.py` | 设置停靠与主界面保持显示 | | `python tools/probe_record_flow.py` | 录制快捷键的完整链路 | | `python tools/verify_drop.py` | 拖放 | | `python tools/verify_lnk.py` | `.lnk` 解析（对 138 个真实快捷方式与参考数据比对） | | `python tools/check_assets.py` | 图标资源今天到底从哪儿读的 | | `python tools/check_icon_files.py` | 生成的 `.ico` / `.icns` 结构校验 | | `python tools/verify-portable.py` | 便携语义（数据落在 exe 旁边，没落进 `%TEMP%`） | | `python tools/capture_panel.py <输出.png>` | 离屏截图主界面 | | `python tools/capture_settings.py <目录>` | 六个设置页 + 关于窗截图 | | `python tools/bench-startup.py` | 启动耗时对比 | ## 八、技术要点 - **Python 3.11+ / PySide6**（Qt for Python）。界面用 `.ui` 文件 —— Qt Designer 可以直接 打开改，改完直接生效（运行期装载，不需要 `uic` 编译步骤）；配色用 `.qss`。 - **便携优先**：`settings.ini` 与 `app/` 都在可执行文件同级目录；若安装目录不可写 （例如装进 `Program Files`），自动回落到用户目录并在设置里说明。 可用环境变量 `FASTRUN_HOME` 指定数据目录。 - **纯 Python 的 `.lnk` 解析器**（`fastrun/core/lnk.py`），不依赖原生模块， 因此 macOS 上同样可用。逐字段对照 Windows 自身解析结果验证过 **138 个真实快捷方式**， 处理了这些真实世界的坑：部分安装器写的 `LinkInfoSize` 不含末尾的 `CommonPathSuffix`； `CommonNetworkRelativeLink` 的偏移基准是它自身而非 LinkInfo；路径可能是 ANSI（GBK / Big5 / CP1252 逐级尝试）也可能是 UTF-16LE；`LinkFlags` 并没有必须置位的位。 - **图标**：进入视口才请求，磁盘缓存落在 `appicon/`；macOS 直接解析 `Contents/Resources/*.icns` 取出 PNG 原图，比系统缩略图清晰。Windows 上 Qt 的快路径上限是 32×32， 需要高清图标时走 PowerShell + .NET 兜底（见 `fastrun/core/powershell.py`）。 - **点击窗口外自动隐藏**：无边框窗口在用户点到桌面或别的窗口时会收到 `blur` 事件， 正好等价于「点击窗体以外的空白处」；图钉按下时忽略该事件。 - **全局快捷键是低层钩子，不是系统热键**：Windows 走 `WH_KEYBOARD_LL`，macOS 走 `CGEventTap`（`fastrun/core/mac_hotkey.py`）—— 两边语义一致： **别的程序占用了同一个组合，本程序照样触发**。代价是回调跑在输入链路上，写错会波及全局输入 （Windows 侧因此只在钩子里做整数比较，命中就 `PostThreadMessageW` 交给主线程， 别的什么都不做）。macOS 上创建 tap 要「辅助功能」权限，**没权限时静默失败** （返回空指针、不报错），所以注册前先探测权限，把失败原因显示在设置页。 - **Python 互操作纪律**：路径用 base64 经 stdin 传给 PowerShell（中文 Windows 控制台是 GB2312）， 脚本用 `-File` 而非 `-Command`，`Add-Type` 里的 C# 必须写成一行。详见 `core/powershell.py`。 ## 九、已知限制 - **macOS 版只编了 Apple Silicon（arm64）**：Intel Mac 跑不了（x86 版不再考虑）。 - **macOS 的数据目录在 `.app` 里面**（`Contents/MacOS/` 下的 `app/`、`settings.ini`、 `appicon/`）：拿新 `.app` 覆盖升级会**连标签一起删掉**。这是已知问题， 改动点只在 `core/paths.py` 一处（详见 [HANDOVER.md](HANDOVER.md) 的 5.2）。 - **别在运行过的 `.app` 里手动增删文件**：往 bundle 里写东西会破坏代码签名的封存， `spctl -a -vvv` 会报 `a sealed resource is missing or invalid`。 - `Alt+Space` 在 Windows 上被系统占用，需自行改键。 - 删除标签是**永久删除文件夹**（有二次确认），不进回收站；删除单个快捷方式才走回收站。 - **没有鼠标键呼出**（见第三节末尾的理由）。 ## 十、许可 本项目以 **MIT License** 发布，全文见 [LICENSE](LICENSE)。 ``` Copyright (c) 2026 Ahsinsoft ``` **这是有意选择的，并且知道它的代价**：MIT 同样授权你的用户自由分发、甚至转卖本软件 —— 作者接受这一点，不去限制别人的转卖行为。 ### 打包产物里的第三方组件 本程序自己的代码是 MIT，但**产物里还含第三方组件，它们的许可同样适用于分发**。 `licenses/` 目录会在打包时整个复制进产物： | 组件 | 许可 | 说明 | | --- | --- | --- | | **PySide6 / Qt** | **LGPL-3.0** | 界面框架，随包分发 | | **shiboken6** | **LGPL-3.0** | PySide6 的绑定运行库 | | Python 运行时 | PSF License | 宽松许可，允许商用与再分发 | | MSVC 运行时 | Microsoft 可再发行条款 | `_internal/api-ms-win-*.dll` 等 | > ⚠️ **PySide6 的 wheel 里没有 LGPL/GPL 全文**，只有一份 470 字节的商业许可说明 > （实测确认）。所以本仓库自己带了 `licenses/LGPL-3.0.txt` 等文件 —— > **删掉它们会让产物缺少 LGPL 要求的声明。** ### 关于商用 **可以商用、可以卖钱、不需要开源你自己的代码**，但 LGPL 与 MIT 不同，**它有条件**： - 以**动态链接**方式使用 Qt（本程序就是：EVB 把文件夹虚拟化进 exe，Qt 的 `.dll` 仍是独立的动态库）→ 可以闭源分发 - **必须保留** `licenses/` 里的许可声明，不能删 - 若**修改**了 Qt / PySide6 本身，修改部分要按 LGPL 开源（本程序没有修改它们） - 若改成**静态链接**，限制会明显变严（本程序是动态链接） 简单说：**你自己写的代码怎么授权随你，但 Qt 那部分的条件要遵守。** > 以上是基于许可证文本的说明，**不是法律意见**。真要靠它收钱之前， > 涉及金额或独家授权的话建议找律师确认一次。 ### 名字与标识 产品的正式名称是 **快速启动 FastRun**（中文在前，中间有空格）。用户可见处统一用它： 关于窗、设置里的关于页、托盘提示、面板顶栏、窗口标题。 **机器可见的标识故意没跟着改**，改了会破坏已有安装 （交付给用户的 exe 文件名是中文 `快速启动FastRun.exe`，那是**用户指定的交付名**， 不在此列）： | 标识 | 值 | 为什么不改 | | --- | --- | --- | | 数据目录 | `%APPDATA%\FastRun` | 改成中文会让老用户的 `settings.ini` 与 `app/` 变成孤儿 | | 标签文件夹 | `app/` | 用户的标签都在里面，改名等于把他们的东西弄丢 | | 配置键名 | `settings.ini` 里的键 | 用户手改过的配置要能继续用 | 另外「急速启动」是**别人**的软件（本项目早期受它启发分析过），别用它的名字或图标去分发。 作者：Ahsinsoft · ahsin@qq.com ·