🔎 dsh-locator

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 面板
• 在会话中查找（Ctrl+F）
• 工具一览
• 查询语法
• 配置
• 性能与资源
• 平台支持
• 故障排查
• 从源码构建
• 设计
• 限制
• 安全与隐私
• 版本与兼容性
• 路线图
• 许可证

30 秒了解

找文件通常分两种情况：

• 记得名字，不记得位置。 glob/grep 每次都要重新遍历；文件在 ~/Downloads 还好，只记得半个文件名时就很难受。
• 记得某句话、某个结论、某段代码，想不起在哪个文件、哪次对话里。 这时只搜文件名没有用，而 DSH 的会话日志本身也是一等公民。

dsh-locator 把两件事放进同一个插件：

索引完全在本地：不联网、不上传、不埋点；插件不会修改、移动或删除被索引的文件。

和 Everything / Spotlight / grep 有什么不同

一句话：Everything 的思路（常驻索引 + 结构化查询）被独立实现成了跨平台版本，并补上了 DSH 会话这一层；不是 Everything 的封装。

安装

# npm（推荐）
dsh plugin --profile web add dsh-locator

# 指定版本
dsh plugin --profile web add dsh-locator@0.7.6

# 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。

第一次运行

默认索引你的主目录，快照和内容库放在系统缓存目录：

第一次扫描要读盘；之后启动直接加载快照。扫描期间搜索照常可用：返回已索引的部分，并带 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，或者点侧栏底部的放大镜。面板通过同源路由工作（search、content、content/rebuild、combined、status、reveal、open），不另起服务、不占额外端口。/combined 新增 matchMode、caseSensitive、wholeWord、sessionId、count 参数，内容组返回 count/warnings，文件命中带 line。

• 默认同时搜索三个范围：内容（正文 + 会话）、文件、目录，三个勾选默认全部打开；取消任一勾选即可缩小范围。结果按“内容 → 文件 → 目录”分组，组头显示数量；内容按相关度排序，文件/目录按排序菜单。
• 双击或 Enter 激活：会话命中打开对应会话，并把命中的词用半透明琥珀色高亮（随滚动跟随、自动居中、Esc 清除）；文件/目录在文件管理器中定位。Ctrl+Shift+C 复制路径，Ctrl+O 打开，Ctrl+Enter 插入 @file，Alt+1–3 切换范围。
• 计数：组头显示命中数；可精确时显示数字，受上限保护时显示 ≥ N；头部显示当前选中位置 3/37，底栏汇总三组。内容页面路径已改为“先取 rank rowid、再按 rowid 取正文、JS 生成片段/行号”，常见词从约 2.7 秒降到 300 毫秒以内。
• 查找选项：工具栏提供模式（普通 / 扩展 / 正则）、Aa 大小写、全词、当前会话范围。模式和大小写/全词对文件、目录名生效；内容支持普通/扩展/大小写/全词，正则模式下内容组自动暂停（文件/目录仍可正则），避免全库正则扫描。
• 当前会话范围：勾选后只查该会话已落定的索引消息（活跃会话约有 2 分钟索引延迟），文件/目录勾选会禁用但保留；实时逐处查找请用下文的 Ctrl+F 会话内查找条。
• 内容查询至少需要 3 个字符；空查询和 1–2 个字符的查询不会启动内容索引构建。构建期间内容组显示进度，文件名/目录结果立即返回；勾选和查找选项会记住。
• 键盘：↑/↓、Home/End、PageUp/PageDown 移动，F3/Shift+F3 在结果行间循环，Enter 激活，Esc 关闭；对话框有焦点陷阱并在关闭时还原。面板文案跟随 navigator.language（中/英/西/葡/印地语）。

在会话中查找（Ctrl+F）

在对话里按 Ctrl+F（或点会话头部的 ⌕）打开非模态查找条，只搜索当前会话已加载的消息，不依赖内容索引、没有 2 分钟延迟：

• 计数与导航：显示 3/17；Enter/F3 下一个，Shift+Enter/Shift+F3 上一个，循环查找默认开启，到端点会回到另一端并提示。所有命中半透明高亮，当前命中加深并加下划线。
• 选项：Aa 区分大小写、全词匹配（ASCII [A-Za-z0-9_] 边界，中文按非词字符处理）、循环、反向（改变 Enter 主方向）；方向按钮始终显式可用。
• 模式：普通（字面量）、扩展（支持 \n \r \t \0 \xHH \\，未知转义按字面）、正则（JS RegExp，在 Worker 中执行并带 500ms 超时；非法正则内联报错）。正则零宽匹配会跳过，不卡死。
• 选区查找：先在会话里选中文本，再按 Ctrl+F，查找条默认只在该选区范围内查找，并显示选区 chip；跨消息选区也支持；选区失效会自动回退到整个会话。
• 已加载窗口：查找条只覆盖当前已加载的消息；长会话可点“加载更早消息后重试”，不会自动连续翻页。
• Esc 关闭查找条并清除高亮；会话切换、面板打开、插件卸载都会清理。全局面板负责跨文件/跨会话发现，查找条负责当前会话内逐处定位，两者不叠加高亮。

工具一览

查询语法

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']

binaryPath、maxResults、startupTimeoutMs、requestTimeoutMs 也支持，分别用于自定义引擎、单页上限和超时；一般不需要改。

性能与资源

以下数字来自开发机（WSL2，Linux，热页缓存）和真实主目录；你的机器会因磁盘、文件数、缓存和 GC 状态而不同。

名称索引

内容索引（真实主目录，1GB 预算上限）

怎么更省

• 只要 Everything 式文件名搜索：contentIndex: false，内容开销归零。
• 想保留内容但更省磁盘：调小 contentMaxTotalBytes（如 256000000）、contentMaxFileBytes，或把 contentRefreshMs 调大。
• 想覆盖更多文件：调大 contentMaxTotalBytes / contentMaxFiles，并确认 contentExcludes 没把真实文档目录排除掉。
• 注意：内容库是缓存，删掉 stateDir 后会自动重建，不会影响源文件。

平台支持

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，且内容变更依赖定时重建。

• 文件正文命中目前只在文件管理器里定位（在 DSH 内按行预览是下一步；查询结果已带 line 行号）；assistant 消息通过 turn:step 节点键精确定位，找不到时才退回短语匹配。

• 全库内容正则 P0 不做：正则模式会暂停内容组（文件/目录名仍可正则），避免 1GB 级全库扫描和 ReDoS；会话内查找条支持正则。

• 当前会话范围只覆盖已落定索引的会话消息（活跃会话约 2 分钟延迟）；实时查找用 Ctrl+F。会话内查找条只覆盖已加载窗口，更早历史需手动加载。

• 会话内高亮依赖 CSS Custom Highlight API；不支持它的旧浏览器会退化为整行描边。

0.11.0 升级注意

• 状态/面板会显示 全量内容 与 含思考内容；客户端语言优先跟随宿主 <html lang>（DSH locale），没有时退回浏览器语言。

• 宿主 connection 服务在插件启动时尚未就绪也不会永久丢路由：先注册、每个请求再检查并 503；确实没有 connection 的 host 可设 httpConnectionOptional: true，退回宿主鉴权 + 同源 Fetch 检查（默认 false）。

• 可选 思考内容索引：contentIndexReasoning: true 会把 assistant 的 reasoning/thinking block 并入同一条会话消息（最终答案在前，8KB 上限内），因此 locator_find 能搜思考过程，跳转仍指向消息；默认关闭，切换该开关会强制重建会话索引。

• 全量内容索引：设置 contentFullIndex: true（或把两个 cap 都设为 0），即可索引全部符合文本扩展名/单文件上限的文件。实测本机 eligible 约 185k 文件 / 2.0GB 文本，FTS 库约 5.9GB；首次构建约几分钟，查询约 0.04–0.7s。默认仍保留 1GB/200k 上限，避免普通用户磁盘暴涨；面板会显示 truncated。

• locator_find 默认仍 workspace：当前会话 + 调用者 cwd；但如果 cwd 不在任何已索引 root 内，不再把文件命中限制到 cwd（否则必然为空），而是搜索已索引 root 的文件；会话仍只查当前会话。跨范围仍用 scope:"all"。

• 面板新增：加载更多（按 offset 分页）、最近搜索（localStorage，可清空）、过滤已加载结果。

• 安全：Linux 下拒绝 root 内嵌套 mount point 的目标（bind mount 防逃逸）；/open 用 O_NOFOLLOW 打开并核对 inode，缩小 TOCTOU 窗口。

• 内容查询支持 offset；名称/内容分组各自分页。

0.10.0 升级注意

• 内容搜索最短 3 个字符；1–2 字符请用 Ctrl+F 会话内查找。查询超过 256 字符/32 个词会直接报错。
• locator_find 默认 workspace 范围（会话只查调用者当前会话，文件正文只查调用者 cwd）；跨工作区需显式传 scope: "all"。新增 matchMode/caseSensitive/wholeWord/sessionId/count/pathPrefix 参数。
• 面板 HTTP 路由现在硬依赖 DSH connection 服务（缺失则不挂载/503），并强制 POST + JSON + 同源校验；stock web profile 正常。
• locator_export 默认只写插件 stateDir，覆盖前校验是否本工具生成的 SQLite；locator_rebuild 只接受配置 roots/excludes 的子集。
• 引擎二进制版本为 0.10.0；快照保存改为脏数据 debounce、sort=path 内存修复、watcher 降级/refresh fallback；macOS 发布版必须由 macOS cgo/FSEvents 构建，debug kqueue fallback 不能发布。
• 客户端：面板点击结果后键盘/Esc 保持；软换行/<br>/CJK 查找修复；assistant 同 nodeKey 双行优先回复行；正则优先 Unicode u 且 worker 失败不再回退主线程；内容错误/警告/截断在面板可见。

安全与隐私

• 索引完全在本地：不联网、不上传、不埋点；插件不会修改、移动或删除被索引的文件。
• 内容库与构建锁以 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。

路线图

不是承诺，只是当前方向：

1. Electron 桌面运行时在真实 Windows 安装上的验证。
2. 面板里的预览和结果分组。
3. Windows on ARM / Linux ARM 的运行时覆盖。
4. 更大的索引：小写名字 arena 与 trigram 预筛选。
5. 快照增量压缩与按根目录的 journal。

许可证

Apache-2.0。