psychic:带 ML 排序的终端文件浏览器
Psychic: Like fzf but learns from your actions
作者发布终端文件浏览器 psychic,它记录用户打开的文件和 cd 进入的目录,用 LightGBM 模型对搜索结果排序,并支持 brew install kshitijl/tap/psychic 安装。
psychic 是一个快速的文件浏览器,带有基于机器学习的排序功能
大多数时候我都在终端里 cd 进入各个目录,并在编辑器中打开文件。在任意一周里,我处理的文件和目录基本都差不多,因为我在做同样的项目。我烦透了必须记住文件放在哪里,也厌倦了一遍又一遍地对那几个路径做 Tab 补全。我的电脑应该早就知道我想打开哪个文件了!
所以我做了 psychic,一个快速的基于终端的文件浏览器。它会追踪你去过的目录,并记住你打开过哪些文件。它在你的数据上训练一个轻量级机器学习模型,并用该模型对结果排序。它把交互性和速度置于一切之上:结果随输入实时更新,UI 渲染时间低于 16ms。
它的一切工作方式都源于一个关键设计决策:它必须快到在按键后一帧之内完成更新。我宁愿在几秒内做 10 次快速搜索,也不愿做 1 次耗时许多秒的智能搜索。
我每次用电脑都会用 psychic。它已经成为我在文件系统中移动的主要方式。一些数据:自从 2025 年 10 月开始使用它以来,
- 我打开过它 1450 次。平均而言,我只输入了 1.6 个字符就得到了我想要的结果。
- 有 29% 的时候我一个字符都没输入!psychic 知道我想要什么,直接给出第一条结果。我所做的只是打开它然后按回车。
- 从打开 psychic 到抵达目标位置的中位时间是 2 秒。41% 的搜索在 1 秒内完成,69% 在 3 秒内完成。
- 有 80% 的时候,我选择了第一条结果。96% 的选择都在前三条之内。
- 我选中的路径平均大约有 50 个字符长。所以我只输入了其中 3% 就到达了那里。
(这些数据来自内置的 psychic stats 命令,你也可以在自己的历史记录上运行它!)
它在 homebrew 上:brew install kshitijl/tap/psychic。
左侧是搜索结果。右侧是当前选中的文件或目录的预览。你在底部输入查询,结果会被过滤和排序,并随每个字母变化。如果你在某个文件上按 Enter,它会在同一窗口中打开你的终端编辑器,并在后台等待。如果它是一个目录,它会从该目录内部重新开始搜索。它会记住你打开过的每个文件和目录,而一个 shell 集成会记录你从 psychic 外部 cd 进入的每个目录。所有这些都会包含在每次搜索中。
它就像是 fzf 和 zoxide 的结合体,再加上一个小型机器学习模型来学习你的模式和偏好。它是在你自己的数据上做广告优化,帮你更快地浏览电脑。
工作原理
你所有的搜索和点击都会写入你电脑上的一个 sqlite 数据库。psychic 在该数据上训练一个 LightGBM 模型。该模型学习根据你的搜索查询来预测你会打开哪些文件。psychic 使用该模型对搜索结果排序。每次按键后,psychic 都会重新运行模型并重新对所有结果排序。
更多细节,请参阅 仓库中的 README。
一些关键设计决策
我使用的模型是 LightGBM,它是梯度提升树的一种实现。它小巧、快速,几秒钟就能完成训练。它可以学习依赖阈值条件的规则。例如,它可以学到这样的规则:“大于 1 MB 的文件,只有在最近 24 小时内被修改过时才会被打开”,比如日志文件。LightGBM 还有出色的 LambdaRank 目标函数,正是为这类排序任务专门设计的。
延迟预算排除了任何非本地模型:一次网络调用很容易超过 10 毫秒甚至更糟。它同样排除了 LLM 或任何 transformer 模型。线性回归和逻辑回归过于简单,表现远不如 LightGBM。
每次你打开 psychic 时,模型都会从头重新训练。这意味着它始终反映你当前的使用模式。训练在后台进行,完成后将模型写入磁盘。在你查看结果时,我们不会切换到新模型,因为应用这样做会让人感到突兀。相反,我们会等到你不看屏幕的时候,比如你在编辑器中打开文件或点击目录时,再切换到新模型。我为这个精心设计的小小舞蹈感到自豪。
当用户刚开始使用 psychic 时,没有足够的点击数据用于训练。我们使用一个简单模型,奖励最近的点击、最近的修改时间以及查询与文件名之间的模糊匹配。最终得分是简单模型和机器学习模型的加权和。点击较少时,简单模型占主导。随着点击数据积累,机器学习模型的得分权重越来越高,直到基本为 1。
如何做到未卜先知
我使用一组精心挑选的特征来尝试预测你会打开哪个文件。有些特征很简单:你在 psychic 中最近一次点击它的时间、它的修改时间、文件名是否以查询开头、查询与文件名之间的模糊文本匹配得分。下面是一个调试面板,展示了这些特征和一些性能统计:

这个调试面板在初期对于弄清奇怪的结果或性能缓慢非常有帮助。如今 psychic 已经相当稳定,但我有时还是喜欢打开它看看。
有一个特征是“最近点击的、与此文件位于同一目录下的文件数量”。这个特征帮助模型提升当前活跃项目中的文件。
“此查询的点击次数”这一特征帮助模型将特定查询与特定文件关联起来,而无需字面记住文件名和查询文本。这样,虽然模型并不直接看到文件名,它仍然能记住关联。

每次训练运行都会写出一份包含一些统计信息的 pdf。这里我们看到一条训练曲线和每个特征的增益。
一个片段定义为从打开 psychic(或从上次点击)到点击某个项目之间发生的所有事情。因此单个片段包含一系列查询,包括按退格键和尝试新查询。“片段中带有此查询的交互次数”这一特征统计的是:在一个片段中,只要该片段出现过当前查询,你点击文件的次数。所以如果你总是输入“es”并最终点击“bayesian-estimate.md”,模型就能看到这种关联。下次你输入“es”时,模型就会把那个文件放在列表顶部。

以下是 SHAP 值和点图。这些帮助我理解一个特征对模型输出的影响程度,并解释模型为何会表现出某种行为。例如,点图显示模型偏好最近修改过的文件,而不喜欢大多数大文件。
计算机运行很快
我密切关注性能,并在良好的基准测试设置上投入了大量精力,还加入了性能日志记录。每次提交都有性能基准测试。如果你使用 psychic 后遇到性能不佳的情况,那就是一个 bug!请告诉我,我会修复它。
我的技术选择是由性能驱动的。最重要的选择大概是 Rust 和 LightGBM。
系统调用开销很大,但当然整个程序都是系统调用。我尽量减少了系统调用。主渲染循环中没有文件系统系统调用;我仔细确保在遍历文件系统时请求文件元数据,然后在其他地方一直携带这些元数据。
来源:Hacker News · klauria.tech