dsh-locator
Verifieddsh-locator · v0.7.7 · Apache-2.0 · Web UI
Whole-disk, millisecond file search for DeepSeek Harness without Everything: a self-built cross-platform index, an Everything-style query language, agent tools and a Web search panel (Ctrl+Shift+F). Windows, macOS and Linux.
Install
dsh plugin add dsh-locator Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
🔎 dsh-locator
记得名字就搜名字,记得内容就搜内容;找到之后直接打开,或者跳回那次对话。
给 DeepSeek Harness 的全盘文件搜索:自带索引,不装 Everything,不依赖 es.exe,Windows / macOS / Linux 用同一套工具和同一个面板。
简体中文 · English · Español · Português · हिन्दी
dsh plugin --profile web add dsh-locator
官方仓库是 GitHub
PerryLink/dsh-locator,Gitee 和 GitCode 是自动同步的镜像,GitHub 为准。插件属于 DSH 插件家族,Apache-2.0;已被 awesome-dsh-plugin 收录。如果它帮你省了时间,点个 ⭐ 就行。
目录
- 30 秒了解
- 和 Everything / Spotlight / grep 有什么不同
- 安装
- 第一次运行
- 两种搜索
- Web 面板
- 工具一览
- 查询语法
- 配置
- 性能与资源
- 平台支持
- 故障排查
- 从源码构建
- 设计
- 限制
- 安全与隐私
- 版本与兼容性
- 路线图
- 许可证
30 秒了解
找文件通常分两种情况:
- 记得名字,不记得位置。
glob/grep每次都要重新遍历;文件在~/Downloads还好,只记得半个文件名时就很难受。 - 记得某句话、某个结论、某段代码,想不起在哪个文件、哪次对话里。 这时只搜文件名没有用,而 DSH 的会话日志本身也是一等公民。
dsh-locator 把两件事放进同一个插件:
| 能力 | 怎么用 |
|---|---|
| 文件名 / 路径搜索 | locator_search,或面板默认模式 |
| 文件正文搜索 | locator_find,或面板勾选“搜内容” |
| DSH 会话内容搜索 | 同上;命中带 sessionId / messageId,可直接跳回那次对话 |
| 打开 / 定位 | 工具返回路径;面板双击在文件管理器定位,Ctrl+O 打开,Ctrl+Enter 把 @"路径" 插进输入框 |
| 外部工具消费 | locator_export 导出只读 SQLite |
索引完全在本地:不联网、不上传、不埋点;插件不会修改、移动或删除被索引的文件。
和 Everything / Spotlight / grep 有什么不同
| dsh-locator | Everything | Spotlight | glob / grep |
|
|---|---|---|---|---|
| 平台 | Windows / macOS / Linux / WSL | Windows | macOS | 跨平台 |
| 索引形态 | 常驻索引(自建) | 常驻索引(NTFS USN) | 系统元数据/内容索引 | 每次调用重新遍历 |
| 按正文搜索 | 文本文件 + DSH 会话消息 | 默认只搜文件名 | 支持,可用性因系统而异 | 支持,但无索引 |
| 会话跳转 | 命中带 sessionId / messageId,可跳回 |
无 | 无 | 无 |
| 给 agent 用 | 6 个工具,查询语法一致 | 需另装 CLI/服务 | 需另接脚本 | 原生工具,无持久索引 |
| Windows 速度 | 接近 Everything(USN 可选) | 最快最轻 | 不适用 | 慢于索引方案 |
一句话:Everything 的思路(常驻索引 + 结构化查询)被独立实现成了跨平台版本,并补上了 DSH 会话这一层;不是 Everything 的封装。
安装
# npm(推荐)
dsh plugin --profile web add dsh-locator
# 指定版本
dsh plugin --profile web add [email protected]
# GitHub 主仓
dsh plugin --profile web add github:PerryLink/dsh-locator
# 从源码
pnpm install
pnpm build
pnpm build:engine # 当前平台的 Go 引擎
dsh plugin --profile web add /绝对路径/dsh-locator
# 从 tarball(npm pack 产物;替换成实际版本号)
npm pack
dsh plugin --profile web add /绝对路径/dsh-locator-0.7.6.tgz
- 包里已经带了六个平台的预编译引擎:
linux-x64、linux-arm64、win32-x64、win32-arm64、darwin-x64、darwin-arm64,装完不需要本机 Go。 - 国内 npm 镜像偶尔滞后:如果
latest不是新版本,加--registry=https://registry.npmjs.org再装。 - 装进正在运行的 Web profile 后,刷新一下页面(F5):宿主工具通常会热挂载,但浏览器面板是页面加载时从 boot graph 里取的。headless / TUI profile 只有工具,没有面板。
- 升级:
dsh plugin --profile web add dsh-locator@latest,然后 F5;内容库结构变化时只重建一次。 - 卸载:
dsh plugin --profile web remove dsh-locator;想临时关掉但保留配置,设enabled: false。
第一次运行
默认索引你的主目录,快照和内容库放在系统缓存目录:
| 平台 | 默认位置 |
|---|---|
| Windows | %LOCALAPPDATA%\dsh-locator |
| macOS | ~/Library/Application Support/dsh-locator |
| Linux | $XDG_CACHE_HOME/dsh-locator 或 ~/.cache/dsh-locator |
第一次扫描要读盘;之后启动直接加载快照。扫描期间搜索照常可用:返回已索引的部分,并带 indexing: true,面板底栏也会提示“索引构建中”。
默认跳过 node_modules、.git、.hg、.svn、.cache、__pycache__、.venv、venv、.next(按名称匹配,excludes 可改)。
可以这样试:
帮我找上周改过的 PDF
哪里讨论过 “contentRefreshMs”?
看看哪个会话里定过这个方案
两种搜索
按名字找:locator_search
Everything 风格的查询语法,返回路径、大小、修改时间、扩展名、类型。适合“我记得文件名里有 report”“找上周改过的 PDF”“找 50MB 以上的视频”这类问题。
查询语法见下方。排序、分页、limit/offset 都由宿主引擎完成,151 万条记录的常见查询在几十毫秒内。
按内容找:locator_find
在文本文件和 DSH 会话消息里搜正文,返回命中片段和来源:
- 文件命中带路径,可以直接打开或定位;
- 会话命中带
sessionId和messageId,可以跳回那次对话并尽量滚动到命中的那句话; - 中文和英文子串都能搜(trigram 分词),不要求分词正确。
内容索引的行为:
- 惰性启动:插件启动时什么都不建;第一次搜内容(
locator_find或面板“搜内容”)才开始后台构建,contentLazy: false可恢复启动即建。第一次查询会立刻返回building: true,不会让你干等或误以为没结果。 - 重启复用:有内容库时只做一次增量刷新,不重读全部正文;只有库不存在、结构版本不兼容、上次构建没完成或损坏时才全量重建(先会话、后文件正文)。
- 增量刷新:默认每 5 分钟检查一次,只重读 mtime 变化的文件/会话;
contentRefreshMs可调,0 关闭。 - 归档与活动会话:已归档会话默认不索引(
contentIncludeArchived: true才索引);正在写入的会话等它安静contentActiveSessionDelayMs(默认 2 分钟)后再索引,不会每轮刷新重解压整份日志;已删除的会话随文件消失自动退出索引。 - 预算与截断:默认单文件最多 1MB、文件数最多 20 万、内容总量最多 1GB、最近 100 个会话。撞到总额上限时按扫描顺序保留先到的文件,
locator_find的输出会提示content budget reached,HTTP 状态里是truncated: true;调大contentMaxTotalBytes或收窄contentExcludes即可。 - 依赖目录不读正文:
node_modules、.cargo、.bun、.pnpm、site-packages、toolchain等默认被contentExcludes跳过,否则预算会先被库代码吃满;文件名索引不受影响。
内容索引跑在宿主进程里,但文件读取和 zstd 解压都是异步的,构建循环每约 8ms 让出一次事件循环(28.6MB 语料实测最大事件循环阻塞从 968ms 降到约 20ms),所以不会拖慢会话加载/切换。内容查询在 worker 线程里用只读连接执行,常见词约 100ms 量级、生僻词几毫秒,不阻塞宿主。
Web 面板

在 Web GUI 里按 Ctrl+Shift+F,或者点侧栏底部的放大镜。
- 空查询按修改时间列出最近的条目;输入后 110ms 防抖,和工具用同一套语法。
- 点列头按名称、大小、修改时间、路径排序;可勾选“只看文件”“只看目录”。
- 勾选“搜内容”切换到正文/会话搜索;构建期间底栏显示状态并自动重查。
↑/↓选择,Enter复制路径,Ctrl+O打开,Ctrl+Enter把@"路径"插进输入框,Esc关闭。- 双击文件结果在文件管理器里定位;双击会话结果打开对应会话并尝试滚动到命中处。
- 面板文案跟随
navigator.language(中/英/西/葡/印地语)。
面板通过同源路由工作:/dsh-locator/search、/dsh-locator/content、/dsh-locator/content/rebuild、/dsh-locator/status、/dsh-locator/reveal、/dsh-locator/open。不另起服务,也不占额外端口。
工具一览
| 工具 | 作用 |
|---|---|
locator_search |
按文件名/路径搜索,支持 ext:、size:、dm:、path: 等过滤与排序分页。 |
locator_find |
按文件正文和会话内容搜索,返回片段与 sessionId/messageId,并带内容索引状态。 |
locator_status |
查看根目录、名称索引条目数、监听状态、状态目录和引擎版本(内容索引进度由 locator_find / 面板报告)。 |
locator_rebuild |
后台重建名称索引;新索引就绪前搜索继续使用旧的。 |
locator_reindex |
重建/刷新内容索引:默认增量,full: true 全量。 |
locator_export |
把名称索引导出成只读 SQLite,方便外部工具查询。 |
查询语法
report 文件名里同时包含这些词
"two words" 完整短语
*.go ? 通配符
ext:pdf,docx 按扩展名
ext:!tmp 排除某类扩展名
path:src 路径里包含 src
size:>10mb 1kb..2mb 按大小
dm:today dm:thisweek 按修改日期
folder: file: 只看目录 / 只看文件
!tmp 排除包含 tmp 的
case:1 wholeword:1 区分大小写 / 全词匹配
配置
在 profile 的 cordis.patch.yml 里覆盖,例如:
- id: dsh-locator
name: dsh-locator
config:
roots: ['/home/me/Documents', '/home/me/notes']
contentMaxTotalBytes: 2000000000
contentExcludes: ['node_modules', '.git', '.cargo', 'site-packages']
| 配置项 | 默认值 | 说明 |
|---|---|---|
enabled |
true |
总开关;false 时不挂工具、不启动引擎。 |
roots |
主目录 | 要索引的目录,可多选。 |
excludes |
node_modules 等 |
名称索引跳过的目录名/路径 glob。 |
watch |
true |
是否监听文件系统变化。 |
refreshIntervalMs |
1800000 | 没有原生监听时的重建周期(kqueue 回退或监听失败时用到)。 |
scanWorkers |
0 | 扫描并发;0 表示按 CPU 数。 |
windowsUsn |
false |
Windows 上尝试 USN/MFT 快路径,需要管理员权限。 |
memoryLimitMB |
0 | 引擎的 Go 软堆上限;0 交给 GOMEMLIMIT/GOGC。 |
contentIndex |
true |
是否构建正文/会话内容索引;false 时只保留名称搜索,开销接近 0。 |
contentLazy |
true |
惰性构建:第一次搜内容时才建库;false 表示启动后就在后台建。 |
contentMaxFileBytes |
1000000 | 单个文本文件最多读多少字节。 |
contentMaxTotalBytes |
1000000000 | 内容库总量上限;0 表示不限制。 |
contentMaxFiles |
200000 | 最多索引多少个文件;0 表示不限制。 |
contentMaxSessions |
100 | 最多索引最近多少个会话;0 表示全部。 |
contentRefreshMs |
300000 | 内容增量刷新周期;0 关闭自动刷新。 |
contentIncludeArchived |
false |
是否索引已归档的会话。 |
contentActiveSessionDelayMs |
120000 | 会话日志安静多久后才索引。 |
contentSessionDirs |
$DSH_HOME/sessions |
额外的会话目录。 |
contentExcludes |
依赖/工具链目录 | 内容索引跳过的路径片段/子串;名称索引不受影响。 |
stateDir |
系统缓存 | 快照和内容库的位置;多个 DSH 进程请用不同目录。 |
binaryPath、maxResults、startupTimeoutMs、requestTimeoutMs也支持,分别用于自定义引擎、单页上限和超时;一般不需要改。
性能与资源
以下数字来自开发机(WSL2,Linux,热页缓存)和真实主目录;你的机器会因磁盘、文件数、缓存和 GC 状态而不同。
名称索引
| 项目 | 实测 |
|---|---|
| 冷启动扫描 | 约 151 万条目 / 11–12 秒 |
| 快照体积 | 约 171 MB(151 万条目) |
热查询(locator_search) |
常见查询 6–25ms;path: 前缀扫描约 70ms |
| 查询时索引重建 | 旧索引继续服务,新索引就绪后切换 |
| 扫描峰值内存 | 数百 MB 量级;引擎独立子进程,可用 memoryLimitMB / GOMEMLIMIT 限制 |
内容索引(真实主目录,1GB 预算上限)
| 项目 | 实测(0.7.x,真实主目录) |
|---|---|
| 覆盖 | 约 9.6 万个文本文件 / 95 个会话 / 1,050 条消息 |
| 全量重建 | 约 3.5 分钟(后台、不阻塞宿主;期间宿主 p95 14ms / max 115ms) |
| 无变化增量刷新 | 约 12 秒(主要花在引擎 151 万条目的 dump 上) |
| 空闲宿主延迟 | p50 2ms / p95 3ms / max 6ms |
| 内容库体积 | 约 3.1 GB(约为正文预算的 3 倍) |
| 内容查询 | 常见词约 100ms、生僻词几毫秒(worker 线程,不阻塞宿主) |
怎么更省
- 只要 Everything 式文件名搜索:
contentIndex: false,内容开销归零。 - 想保留内容但更省磁盘:调小
contentMaxTotalBytes(如 256000000)、contentMaxFileBytes,或把contentRefreshMs调大。 - 想覆盖更多文件:调大
contentMaxTotalBytes/contentMaxFiles,并确认contentExcludes没把真实文档目录排除掉。 - 注意:内容库是缓存,删掉
stateDir后会自动重建,不会影响源文件。
平台支持
| 平台 | 扫描 | 实时更新 |
|---|---|---|
| Linux | 并行遍历 | inotify,递归监听 |
| Windows | 并行遍历,或管理员下的 USN/MFT | ReadDirectoryChangesW;USN 模式下重启会补日志 |
| macOS | 并行遍历 | 发布版二进制用 FSEvents;CGO_ENABLED=0 构建回退到 kqueue(目录上限 4096) |
Windows 与 USN 日志
USN/MFT 快路径默认关闭(windowsUsn: true):需要管理员权限和启用中的卷变更日志,任何一步失败都会回退到普通遍历,不会让搜索不可用。成功扫描后会记下日志游标(usn-state.json),重启时先补上停机期间的变更。
它在 Windows CI runner 上做过端到端验证:读取 134 万条 MFT 记录、解析 134 万条路径;C:\Windows 下 16.4 万条目用 USN 索引约 7.8 秒、查询 9.6ms。也可以手动探测:
# 管理员 PowerShell
& ".\bin\win32-x64\indexd.exe" usn-probe --volume C: --root "C:\Windows" --limit 5 --journal 5
USN 记录本身不带大小和修改时间:结果的名字/路径是准确的,locator_status 会标记这种索引为 USN,返回结果页时再 stat 补齐大小和日期;size:/dm: 过滤在整库上仍是近似值,直到跑一次元数据补全。日志被覆盖、删除或卷不支持时,自动回退可移植遍历。
故障排查
装完面板没出现?
刷新页面(F5);确认装的是 web profile,且面板从 boot graph 加载。headless/TUI profile 本来就没有面板。
刚创建的文件搜不到?
监听可能还没收到通知(WSL 写入 /mnt/c、网络盘、部分容器的 overlay 常见)。等几秒,或对相应根目录执行 locator_rebuild。USN 模式重启后会补日志。
搜内容没结果?
先看 locator_find 返回里的 building:第一次搜索会触发惰性构建,构建期间结果可能不全,面板会自动重查。再确认文件扩展名在文本类型内、大小没超过 contentMaxFileBytes、没被 contentExcludes 排除、会话没归档(归档默认不索引)。
内容库很大 / 磁盘涨得快?
见性能与资源:调小预算或关闭 contentIndex;删除 stateDir 会触发重建。
inotify 相关警告?
目录太多时会碰到内核 watch 上限;索引仍然可用,只是变化依赖定时重建。可调大 fs.inotify.max_user_watches,或减少 roots。
升级后行为变了?
dsh plugin --profile web add dsh-locator@latest 后 F5;内容库结构变化时只重建一次。更新记录见 CHANGELOG。
从源码构建
需要 Node ^22.19 || >=24.9、pnpm、Go 1.22+。
pnpm install
pnpm build
pnpm build:engine:all # 六个平台的引擎
pnpm check # typecheck + 测试 + 打包/安装校验
Go 引擎在 engine/ 下,测试用 cd engine && go test ./...。macOS 的 FSEvents 版本需要 cgo,由 macOS CI 构建。Node 测试在 Linux、Windows、macOS 三个平台的 CI 上运行。
设计
- 名称索引:Go 引擎维护紧凑快照;记录只存名字在 arena 里的偏移和父记录 id,完整路径在返回结果时重建;路径表用开放寻址(
id+1槽,约 12 字节/条)替代map[string]int32。 - 并行扫描:目录读取协程消费有界队列,每个目录批量写入,保证父目录先于子目录;队列满时退化为就地扫描,不阻塞。
- 查询:解析一次查询,分片并行匹配,用有界最大堆选出前
offset+limit条,不排序全部命中。 - 内容索引:宿主侧 SQLite FTS5 + trigram 分词,支持中文和子串;文件清单来自引擎已有扫描结果,会话日志用 Node 自带 zstd 解压;查询在 worker 线程执行。
- 持久化:快照先写临时文件再原子重命名;generation 计数让守护进程只在索引变化时自动保存;删除量超过阈值时压缩墓碑。
- 跳转:文件走
/reveal和/open;会话通过uiWorkspace.openSession(sessionId)打开,再在页面里定位命中文字。 - 协议:引擎通过 stdio 上的 NDJSON 通信,不监听端口;Web 面板只走同源宿主路由。
限制
- 内容索引只处理文本类文件;PDF、Word、图片里的文字暂不提取。
- 内容预算按扫描顺序消耗,不是按文件重要性排序;达到上限后后面的文件不可搜(
truncated为 true)。 - 名称索引不是文件系统驱动,只覆盖配置的根目录。
- Linux inotify 每个目录占一个描述符,目录特别多时可能碰到内核上限;插件会报警,快照仍然可用。
- 通过 WSL 写入
/mnt/c的文件,Windows 端可能收不到通知,需要重建对应根目录。 - 网络盘只在能作为普通目录访问时才会被扫描,没有 SMB 专用的变更流。
- 会话内容来自本地日志;如果会话还没落盘,搜不到最新几条消息。
- 两个 DSH 进程共享同一个
stateDir时,构建锁只能串行化写入;建议各用各的缓存目录。 - macOS 的发布版二进制用 FSEvents;
CGO_ENABLED=0构建只有 kqueue,目录上限 4096,且内容变更依赖定时重建。
安全与隐私
- 索引完全在本地:不联网、不上传、不埋点;插件不会修改、移动或删除被索引的文件。
- 内容库与构建锁以
0600创建、状态目录以0700创建,同机其他用户无法读取被索引的文档或会话正文。 - 快照和内容库里有文件名、路径和正文,请当作私有数据;删除
stateDir即可清空。 - 建议给同时运行的多个 DSH 进程配置不同的
stateDir。
版本与兼容性
- Node:
^22.19.0 || >=24.9.0;DSH:>=0.2.1-rc.2 <0.3.0(见package.json的engines)。 - 发布走 GitHub Actions provenance,npm 上的包可验证来源;Gitee / GitCode 由 mirror workflow 自动同步。
- 更新记录:CHANGELOG.md;问题与建议:Issues。
路线图
不是承诺,只是当前方向:
- Electron 桌面运行时在真实 Windows 安装上的验证。
- 面板里的预览和结果分组。
- Windows on ARM / Linux ARM 的运行时覆盖。
- 更大的索引:小写名字 arena 与 trigram 预筛选。
- 快照增量压缩与按根目录的 journal。
许可证
Apache-2.0。