8000 GitHub - spygg/listery: 一款 Windows 快速文件搜索与启动器,支持快捷键唤起、即时搜索、快速跳转文件夹和启动应用。 · GitHub
[go: up one dir, main page]

Skip to content
spyggPublic

About

一款 Windows 快速文件搜索与启动器,支持快捷键唤起、即时搜索、快速跳转文件夹和启动应用。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Listery

双击 Ctrl,全盘程序一秒到位。

一个用 Qt / C++ 写的 Listary 风格快速启动器:全盘索引可执行文件 → 双击 Ctrl 唤起 → 输入即时补全 → 按使用习惯动态排序。

Build & Release Release License: MIT Qt Platform Language

简体中文 · English


输入即搜:命中字符高亮,常用程序自动上浮

没有输入时只显示一个输入框,不占桌面

Everything 风格列视图:点击表头排序,右侧三角标出当前列与方向

为什么用它

能力 说明
双击 Ctrl 唤起 300ms 内两次 Ctrl 才触发,中间夹了别的键(如 Ctrl+C)不算,不会误伤日常快捷键
输入即搜 35ms 防抖 + 后台检索线程,界面从不执行 SQL;连续输入只保留最新一次请求
拼音检索 tengxunhuiyi、txhy、腾讯会议 三种输入命中同一个程序;多音字保留全部读音
越用越准 排序分 = 0.72 × 匹配度 + 0.28 × 使用习惯,常用程序自动上浮
智能扫描 按分区自适应调度:没装过软件的分区自动降低扫描频率;Linux 上直接读 locate 快照
英汉翻译 Alt+E 唤起翻译插件,输入英文给汉语、输入汉语给英文,回车把译文复制到剪贴板
文件搜索 Alt+S 唤起,自建紧凑索引检索文件;结果按「名称 / 路径 / 大小 / 修改日期」等列展示(列可在配置里选),支持 ext: / path: / full: / re: 过滤和 D:\*关键词* 通配符路径,单击或回车直接打开;结果面板可「固定」,点击表头按列排序(参照 Everything)
插件机制 纯 C ABI 的插件接口:插件不依赖 Qt / OpenSSL,第三方可自行扩展(见 插件开发指南)
在线升级 自动检测 GitHub Release 最新版(语义化版本比较,能正确处理 1.10.0 > 1.2.0);Windows 下发现新版本后点托盘提示即可内置下载安装包,下载完主程序先退出再静默安装,不用手动去网站找
日志轮转 运行日志只保留最近 3 天,启动前自动裁剪,不会无限膨胀
免安装 索引、配置、日志都在可执行文件旁边,拷走 U 盘也能用

快速开始

  1. 到 Releases 下载对应平台的压缩包,解压;
  2. 运行 listery(Windows 为 listery.exe),程序静默进托盘并开始建立索引;
  3. 双击 Ctrl,输入程序名,回车或单击结果运行。

Windows 也可以用 安装版 listery-windows-setup.exe(Inno Setup 打包,免管理员,可选开机启动与桌面快捷方式); Windows XP 用户请下载 listery-windows-xp.zip(MinGW 32 位 + Qt 5.7 构建)。

快捷键

按键 作用
双击 Ctrl 唤起 / 隐藏搜索面板
Alt+E 唤起英汉翻译插件(可在插件管理里改或清空)
Alt+S 唤起文件搜索插件(可在插件管理里改或清空)
↑ ↓ PgUp PgDn 在候选里移动
Enter / 鼠标单击 运行选中的结果
Ctrl + Enter 在文件管理器中定位
Shift + Enter 以管理员身份运行
Esc 隐藏面板(「固定」状态下也强制关闭,固定状态保留)
右键候选 管理员运行 / 打开所在位置 / 复制路径;文件搜索结果还可「复制文件」「打开所在目录」

插件

插件是可执行文件同目录 plugins/ 里的动态库,接口是纯 C 的 ABI,不依赖 Qt、不需要 OpenSSL(网络请求由宿主代劳):

内置插件 热键 说明
英汉翻译(translator) Alt+E 有道词典 suggest 接口的中英双向翻译,整句也能翻;回车复制译文,可切换 Google 后端(LISTERY_TRANSLATOR_ENDPOINT=google)
文件搜索(filesearch) Alt+S 自建紧凑索引检索文件,Everything 风格分列展示,支持 ext:pdf、path:项目名 过滤和 re: 正则、full: 完整路径与 D:\*关键词* 通配符搜索;单击或回车打开结果
  • 「设置 → 插件管理…」打开独立的插件管理对话框,可逐个启用/禁用、改热键(写法如 Alt+E、Ctrl+Shift+F1),也能打开插件自带的设置界面;
  • 翻译插件支持自定义查词链接:在插件管理里点「插件设置…」打开 translator.ini / french.ini,填写 url=https://example.com/lookup?q={query} 并可用 format=youdao|google|text 指定返回格式,保存后下一次查词立即生效;
  • 文件搜索索引闲置 10 分钟后自动卸载,按 Alt+S 打开面板时在后台预热加载(通常 0.2–0.5 秒),平时不白占内存;
  • 文件搜索默认不是全盘索引:只扫「用户目录 + Public + 非系统固定磁盘」,跳过隐藏/系统属性文件,并排除 Windows / Program Files / AppData 等 24 个目录名(完整清单见 filesearch.ini 注释)。要 Everything 那种「所有文件」覆盖,在 !config 里设 index_scope=all(或输入 !scope all)再 !reindex:此时覆盖所有固定磁盘(含系统盘 C:\)、纳入隐藏与系统文件、去掉内置目录排除,只保留回收站 / 系统卷信息等安全项。代价是首次建库明显变慢、快照更大,所以默认不开。只想要隐藏/系统文件、不想扫系统盘,单独设 include_hidden=1 即可;
  • 结果列在 !config 打开的 filesearch.ini 里用 columns= 选择,例如 columns=name,path,size,mtime;可选 name(名称)、path(完整路径)、dir(所在目录)、size(大小)、mtime(修改日期)、ctime(创建日期)、ext(扩展名),按书写顺序从左到右排列,写 off 回到经典两行视图。也可以直接在搜索框输入 !columns name,dir,size,mtime,立即生效并写回配置;!status 会显示当前索引范围与列;
  • 固定结果面板:输入框右侧的「固定」按钮可勾选(也对应「设置 → 固定结果面板」)。固定后,选中并运行结果、切换程序/文件插件都不会再把面板收起,适合连续挑文件;Esc 仍然强制关闭,但固定状态会保留,下次唤起继续固定。状态写入 ui/pinResults,跨重启生效;
  • 表头点击排序(Everything 风格):列视图下点击「名称 / 路径 / 大小 / 修改日期 / 创建日期 / 扩展名」等表头即可排序。同一列再点一次翻转方向,换列默认从升序开始;当前列右侧画蓝色三角(向上升序、向下降序),可排序列悬停显示手型光标。排序会重新查询列表并写入 filesearch.ini 的 sort_mode / sort_desc,跨查询、跨重启保留;!sort name|size|mtime|ctime|path|dir|ext [asc|desc] 与点击表头写的是同一份配置;
  • 托盘菜单的「插件」子菜单也能直接唤起插件(热键不可用时的兜底);
  • 想自己写插件:插件开发指南(English),含最小示例、action 协议与 CMake 模板;
  • 插件加载失败不会弹窗,原因显示在插件管理对话框里;插件日志写进 logs/YYYYMMDD.txt。

智能索引

全盘遍历一次要几分钟、几万次系统调用,而绝大多数分区根本没装过软件。Listery 因此不再"每隔 N 小时无脑全扫一遍":

按分区自适应调度

每个分区单独记录"上次扫到多少条可执行文件、什么时候扫的、连续空扫了几轮",刷新间隔据此伸缩(以默认 12 小时为例):

分区情况 刷新间隔 说明
程序很多(> 5 条) 12 小时 用户配置的间隔,正常刷新
只有零星几个(1–5 条) 24 小时 放宽 2 倍
一个都没有(第 1 轮空扫) 2 天 放宽 4 倍
连续空扫 2 / 3 / 4 轮 4 天 / 8 天 / 14 天 指数退避,封顶 14 天
从没扫过 立即 首次启动必须建索引
上一轮快速通道结果可疑 立即(且强制全量遍历) 例如 locate 库太旧导致"突然一条都没有"

关键点:一次只扫到期的分区,没到期的分区不会被顺带遍历;只扫部分分区时也只清理这些分区的失效记录,其它分区的索引不受影响。

Linux:用 locate 秒级建索引

Linux 上优先读取系统已有的 plocate / mlocate 快照(通常在 /var/lib/{plocate,mlocate}/)而不是遍历文件系统:

  • 两条 locate -r 查询搞定:白名单后缀 + bin/sbin/games 目录下带可执行位的文件(Unix 程序大多没有后缀);
  • 建索引从"几分钟"变成"一两秒",几乎不产生磁盘 IO;
  • 快照由系统的 updatedb 每天更新,所以当天新装的程序最多晚一天进入索引;为保证这点,清理失效记录时会保留 mtime 晚于快照时间的条目;
  • locate 不可用(没装或没有数据库)时自动退回全量遍历;托盘里的"重新扫描全盘"始终是强制全量遍历。

其它省资源的做法

  • 扫描线程以最低优先级运行(Windows 降线程优先级,Linux 抬高 nice 值),不与前台抢 CPU;
  • 遍历用 QDirIterator 逐个产出,并先用文件名过滤再做 stat——系统盘里 95% 以上的文件都不是可执行文件,这一步省掉了它们的系统调用;
  • 面板正在被使用时推迟扫描(最多让 3 次),不抢搜索时的磁盘 IO;
  • 每 2000 条提交一次事务;数据库 WAL 模式,扫描写入与界面检索互不阻塞。

构建

要求:Qt 5.15+ 或 Qt 6.x(Widgets + Sql + Network),CMake ≥ 3.16,Ninja 或 MSVC。

Windows(Qt 5.15.2 + MinGW 8.1)
build.bat

等价的手工命令:

set "QTDIR=E:\programes\Qt\Qt\5.15.2\mingw81_64"
set "MINGW=E:\programes\Qt\Qt\Tools\mingw810_64"
set "PATH=%MINGW%\bin;E:\programes\Qt\Qt\Tools\Ninja;%QTDIR%\bin;%PATH%"

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=%QTDIR%
cmake --build build --parallel

发布目录(带 Qt 运行库,可直接双击):

deploy.bat                  :: 默认取 build\ 产物,Qt5 运行库
deploy.bat build-qt5        :: 也可指定其它构建目录

Qt 6 只需把 QTDIR 换成对应套件,代码里已做 Qt5/Qt6 兼容处理。

Linux
sudo apt install -y build-essential cmake ninja-build qtbase5-dev libqt5sql5-sqlite libxtst-dev
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
QT_QPA_PLATFORM=xcb ./build/listery        # 需要 X11 会话;Wayland 下热键不可用,托盘仍可用

XRecord 头文件来自 libxtst-dev;缺少时 CMake 会给出 WARNING,程序仍可编译,只是无法监听全局双击 Ctrl。Qt6 把 qtbase5-dev 换成 qt6-base-dev。

macOS
brew install qt@5 cmake ninja
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$(brew --prefix qt@5)"
cmake --build build --parallel
./build/listery

首次运行需要在"系统设置 → 隐私与安全性 → 辅助功能 / 输入监控"里勾选 Listery,否则 CGEventTap 创建失败(托盘会提示原因)。

运行

build\listery.exe              :: 常驻托盘,等待双击 Ctrl
build\listery.exe --show       :: 启动后立即打开搜索框
build\listery.exe --rescan     :: 启动后立刻重建索引
build\listery.exe --autostart  :: 开机自启用:静默进托盘,不主动弹窗
build\listery.exe --selftest   :: 无界面自检(结果写日志,退出码 0 表示全部通过)
build\listery.exe --render-preview out.png "c"      :: 离屏渲染"有结果"面板
build\listery.exe --render-preview out.png --empty  :: 离屏渲染"空输入只有输入框"面板

Linux / macOS 把 build\listery.exe 换成 ./build/listery,其余参数相同。

数据目录:可执行文件所在目录(目录不可写时回退到各平台的 AppDataLocation)

文件 用途
index.db SQLite 索引(executables / usage_stats / app_meta / volume_stats 表 + FTS5 倒排)
settings.ini 后缀白名单、跳过目录、可移动磁盘、智能调度、热键间隔、结果数量等
logs/YYYYMMDD.txt 运行日志,按天分文件,只保留最近 7 天(扫描错误、热键告警、插件日志)
crashes/ 崩溃转储(minidump,仅 Windows 构建生成,本地保留、不上传)

删除 index.db 或点"重新扫描全盘"即可重建索引;使用统计在 usage_stats 中,重建索引不会清空。

跨平台支持

三个平台共用同一套索引、检索、排序与界面代码,平台差异集中在 src/Platform/ 与 src/Core/LaunchService.cpp:

能力 Windows Linux macOS
全局双击 Ctrl WH_KEYBOARD_LL 低级键盘钩子 X11 XRecord(需 libXtst;Wayland 会话不可用) CGEventTap(需授予"辅助功能 / 输入监控"权限)
建索引 全量遍历所有本地卷 优先读 locate 快照,不可用才遍历 遍历 / 与 /Volumes/*
启动程序 ShellExecuteW(runas 提权) QProcess::startDetached;提权走 pkexec LaunchServices open(.app 包自动识别);提权走 osascript
打开所在位置 explorer /select nautilus / dolphin / nemo / thunar,失败回退 xdg-open open -R
开机自启动 HKCU ...\CurrentVersion\Run ~/.config/autostart/listery.desktop ~/Library/LaunchAgents/com.listery.launcher.plist

验证范围(如实说明):

  • Windows:本机 Qt 5.15.2 + MinGW 8.1 实际编译、运行,69 项自检全部通过,打包后的 dist\ 在无 Qt 环境也可运行;
  • Linux:在 WSL2 Ubuntu 24.04(Qt 5.15.13、libXtst、XRecord 头文件齐全)实际编译通过,并以 QT_QPA_PLATFORM=offscreen 跑完自检;全局双击 Ctrl 需要真实 X11 桌面会话,未在无头环境实测;
  • macOS:代码路径已按 CGEventTap、open -R、LaunchAgents 实现,但当前没有 Mac 机器,未编译、未运行验证。

工程结构

listery/
├─ CMakeLists.txt
├─ build.bat / deploy.bat
├─ .github/workflows/release.yml   # 四目标(含 XP)矩阵构建 + Windows 安装版
├─ sdk/listery_plugin_api.h        # 插件 ABI(纯 C,随发布分发给第三方开发者)
├─ plugins/translator/             # 内置插件:英汉翻译(零依赖,只调宿主 httpGet)
├─ plugins/filesearch/             # 内置插件:文件搜索(自建紧凑索引,Windows)
├─ installer/windows/listery.iss   # Inno Setup 安装脚本
├─ src/
│  ├─ main.cpp                 程序入口、单实例、预览与自检开关
│  ├─ AppController.*          组装索引库 / 扫描调度 / 热键 / 面板 / 托盘
│  ├─ Core/
│  │  ├─ AppSettings.*         基于 settings.ini 的配置(含插件启用状态与热键)
│  │  ├─ Database.*            SQLite 表结构、批量写入、检索 SQL、卷统计
│  │  ├─ Scanner.*             扫描线程:全量遍历 / locate 快照 / 按卷统计
│  │  ├─ Pinyin.* / PinyinData.* 汉字转全拼与首字母(静态字表,多音字多变体)
│  │  ├─ SearchEngine.*        粗筛 + 内存精排、匹配高亮
│  │  ├─ SearchService.*       后台检索线程(合并排队请求、按序号丢弃过期结果)
│  │  ├─ PluginHost.*          插件宿主:加载动态库、分发查询、代插件发 HTTP
│  │  ├─ UsageRecorder.*       使用统计写入(独立线程 + 独立连接)
│  │  └─ LaunchService.*       启动 / 提权 / 定位(三平台分支)
│  ├─ Platform/
│  │  ├─ HotkeyHook.*          全局热键(双击 Ctrl + Alt+E / Alt+S 等组合键,三平台实现)
│  │  ├─ DoubleCtrlDetector.h  双击 Ctrl 状态机(可单测)
│  │  ├─ Autostart.*           开机自启动(Run 项 / .desktop / LaunchAgent)
│  │  ├─ WindowUtils.*         强制前台、屏幕居中靠上定位
│  │  └─ Branding.*            运行时绘制图标
│  ├─ Ui/
│  │  ├─ LauncherWindow.*      搜索面板(无边框 + 阴影 + 键盘导航 + 单击运行 + 右键菜单)
│  │  ├─ ResultModel.* / ResultDelegate.*  结果模型与行绘制(图标 / 高亮 / 路径 / 次数)
│  │  ├─ PluginManagerDialog.* 独立插件管理对话框(启用 / 热键 / 插件设置)
│  │  └─ SettingsDialog.*      设置界面
│  └─ SelfTest.*               自检(索引、插件、界面与热键)
└─ docs/
   ├─ preview.png
   ├─ PLUGINS.md / PLUGINS_EN.md   插件开发指南(中英)

检索与排序细节

检索流程
  1. 输入框 35ms 防抖后把查询交给 SearchService 的检索线程,GUI 线程从不执行 SQL;
  2. 请求带自增序号:连续输入时排队中的旧请求会被合并,结果回来时序号不是最新的一律丢弃;
  3. 先用使用统计种入候选:取启动次数最高的几百个程序,按本次输入做名字前缀过滤,保证常用程序不会因为粗筛截断被挤掉;
  4. 单词查询先走 name 索引做前缀范围扫描(20 万条约 0.6~1.5ms),逐字打字时这一趟通常就能填满一屏;
  5. 前缀扫描不够一屏时补一次 FTS5 词首匹配("chr"*,name / dir / pinyin / pinyin_initials),覆盖 studio → visual studio code、tengxunhuiyi → 腾讯会议 这类词首命中;带扩展名的输入(kylin.bat)会拆成子词分别匹配——FTS5 在 detail=column 下不接受含标点的整段短语;
  6. 只有前缀和 FTS 都落空时才跑 LIKE '%关键字%' 子串扫描兜底(20 万条约 50ms,仅在检索线程);
  7. 命中候选只取 path/name/dir/ext 等列,使用统计通过一次快照补齐,再在内存里精排后返回前 N 条。

升级后的首次启动会把已有索引灌进 FTS(20 万条约 0.4 秒,一次性);系统 SQLite 没编译 FTS5 时静默退化为 LIKE 扫描,功能不受影响。

排序公式
最终分 = 0.72 × 匹配度 + 0.28 × 使用习惯

匹配度:每个关键字取最高分后求平均
  文件名完全相等 1.55 | 前缀 1.32 | 子串 1.05(越靠后越低,词边界加分)
  子序列 0.45~0.63(按命中密度)
  拼音完全相等 1.5 | 全拼前缀 1.2 | 全拼子串 0.9 | 首字母相等 1.25 | 首字母前缀 1.02
  目录命中 0.30~0.48

使用习惯:
  0.65 × log(1+启动次数)/log(1+候选最高次数)
+ 0.35 × exp(-距今天数 / 14)      ← 14 天半衰期的"最近使用"权重

输入越精确时匹配度主导,输入模糊时常用程序上浮。

表结构
CREATE TABLE executables (
  path TEXT PRIMARY KEY,      -- 完整路径(原生分隔符)
  name TEXT NOT NULL,         -- 小写文件名,供 FTS 与 LIKE 前缀使用
  display_name TEXT NOT NULL, -- 原始大小写,用于显示
  dir TEXT NOT NULL,          -- 小写目录,用于路径片段匹配
  ext TEXT NOT NULL,
  pinyin TEXT NOT NULL DEFAULT '',           -- 全拼变体,多音字空格分隔
  pinyin_initials TEXT NOT NULL DEFAULT '',  -- 首字母变体
  size INTEGER, mtime INTEGER, drive TEXT,
  gen INTEGER                 -- 本轮扫描代次
);

CREATE TABLE volume_stats (   -- 智能调度:每个分区的索引概况
  root TEXT PRIMARY KEY, exe_count INTEGER, last_scan INTEGER,
  empty_rounds INTEGER, deep_pending INTEGER
);

CREATE TABLE usage_stats (path TEXT PRIMARY KEY, launch_count INTEGER, last_used INTEGER);

CREATE VIRTUAL TABLE exe_fts USING fts5(
  name, dir, pinyin, pinyin_initials,
  content='executables', content_rowid='rowid', detail=column
);

已知限制

  • 双击 Ctrl:Windows 上少数带反作弊的游戏 / 安全软件会拦截 WH_KEYBOARD_LL;Linux 只在 X11 会话有效(Wayland 下取不到全局按键);macOS 必须授予辅助功能 / 输入监控权限。三者都失败时仍可用托盘菜单唤起。
  • 索引新鲜度:Linux 走 locate 快照时,新装的程序最多晚一天进入索引;需要立刻生效请用托盘的"重新扫描全盘"。
  • 增量精度:扫描按代次清理失效记录,已收录文件的体积 / 修改时间只在真正遍历时更新;mtime 变化不影响启动。
  • 开机自启动:Unix 下写入的条目在下次登录时生效。
  • 拼音表只覆盖常用汉字(U+4E00–U+9FA5,约 2 万字),生僻字没有拼音,但仍可用汉字或文件名子串命中。
  • .sh 在 Windows 上需要 Git Bash / WSL 提供 bash;.ps1 用 PowerShell 执行。
  • macOS 的可执行文件大多没有后缀(.app 包内二进制),默认后缀白名单可能扫不到应用主体;可在设置里补充后缀。
  • macOS 分支与 Linux 全局热键分支尚未在真实桌面会话中实机验证。

许可证

本项目以 MIT 许可证 开源,详见 LICENSE。

自动构建与发布

仓库通过 GitHub Actions 的 Matrix Strategy 并行构建,推送 v* 标签(或手动触发)时自动生成 Release 并上传资产:

Asset 平台 说明
listery-windows.zip Windows x64 绿色版:解压即用,Qt 5.15.2 / MSVC2019 构建,Windows 7 及以上
listery-windows-setup.exe Windows x64 安装版:Inno Setup 打包,免管理员,可选开机启动 / 桌面快捷方式,自带卸载
listery-windows-xp.zip Windows 32 位 Qt 5.7.1 / MinGW 5.3 构建,兼容 Windows XP
listery-linux.AppImage Linux x64 独立运行镜像(已打包 Qt 运行库)
listery-macos.zip macOS 可执行程序(已打包 Qt 框架)
git tag v1.0.0
git push origin v1.0.0      # 触发 Actions 构建并发布 Release

About

一款 Windows 快速文件搜索与启动器,支持快捷键唤起、即时搜索、快速跳转文件夹和启动应用。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0