dsh-locator 0.5.0 → 0.5.3

package/README.md

@@ -1,227 +1,257 @@
-# dsh-locator
+<div align="center">
 
-[![npm](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
-[![ci](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml)
+# 🔎 dsh-locator
 
-[English](README.md) | [中文](README-zh.md) | [Español](README-es.md) | [Português](README-pt.md) | [हिन्दी](README-hi.md)
+**不依赖 Everything 的全盘毫秒级文件搜索，给 DeepSeek Harness。**
 
-A whole-disk, millisecond file search for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) that builds its **own** index. No Everything installation, no `es.exe`, no Everything service.
+自建跨平台索引（Windows USN/MFT · macOS FSEvents · Linux inotify），四个 agent 工具 + 可排序 Web 面板。
 
-`dsh-locator` scans the directories you choose once, keeps the result in a compact snapshot, applies filesystem changes as they happen, and answers name/path queries in tens of milliseconds across a million entries. The agent gets `locator_search`, `locator_status` and `locator_rebuild`; people get a global **search panel** in the Web GUI (`Ctrl+Shift+F` or the magnifier at the sidebar foot) with sortable columns, filters, keyboard navigation and one-key path copy.
+[![npm version](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
+[![CI](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml)
+[![version](https://img.shields.io/github/v/tag/PerryLink/dsh-locator?label=version)](https://github.com/PerryLink/dsh-locator/releases)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-locator)
+[![GitCode](https://img.shields.io/badge/GitCode-mirror-1f6feb)](https://gitcode.com/PerryLink/dsh-locator)
 
-Everything inspired the *ideas*: a persistent index of file names, a query language with `ext:` / `size:` / `dm:` filters, and an updater that consumes the filesystem's own change stream. The implementation is independent and cross-platform.
+[简体中文](README.md) · [English](README.en.md) · [Español](README-es.md) · [Português](README-pt.md) · [हिन्दी](README-hi.md)
 
-## Why another file search
+```sh
+dsh plugin --profile web add dsh-locator
+```
+
+</div>
+
+> **官方仓库**：[GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator)。Gitee / GitCode 是自动同步的镜像，以 GitHub 为准。
+>
+> 这是 [DSH 插件家族](https://github.com/PerryLink) 的一员（Apache-2.0）。如果它帮到了你，**给个 ⭐**——不会解锁任何功能，但会让下一个人更容易找到它。
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的全盘毫秒级文件搜索，**自建索引**：不装 Everything、不用 `es.exe`、不需要 Everything 服务。
 
-`glob` and `grep` walk the workspace on every call — fine when you know the directory, slow when you remember only part of a name. Everything is excellent on Windows but is Windows-only, and wrapping it leaves macOS, Linux, WSL and remote hosts uncovered. `dsh-locator` owns the index, so the same tools work everywhere Node and Go run.
+`dsh-locator` 扫描你指定的目录，把文件名、路径、大小、修改时间写进一个紧凑的快照；之后按文件系统事件增量更新，百万条目上的名字/路径查询在几十毫秒内返回。模型拿到 `locator_search`、`locator_status`、`locator_rebuild`、`locator_export` 四个工具；人则有一个 Web GUI 全局**搜索面板**（`Ctrl+Shift+F`，或侧栏底部的放大镜），支持列排序、过滤、键盘操作和一键复制路径。
 
-## Install
+思路借鉴 Everything：常驻的文件名索引、带 `ext:` / `size:` / `dm:` 过滤的查询语法、直接消费文件系统的变更流。实现是独立的，并且跨平台。
+
+## 为什么再做一个
+
+`glob` / `grep` 每次调用都要遍历工作区——知道目录时很快，只记得名字的一部分时很慢。Everything 在 Windows 上很好用，但它只支持 Windows；包一层 Everything 仍然覆盖不了 macOS、Linux、WSL 和远程主机。`dsh-locator` 自己拥有索引，所以同一套工具在哪都能用。
+
+## 安装
 
 ```sh
-# from npm
+# npm（推荐）
 dsh plugin --profile web add dsh-locator
 
-# from a checkout
+# GitHub 主仓（最新 main）
+dsh plugin --profile web add github:PerryLink/dsh-locator
+
+# 从源码
 pnpm install
-pnpm build            # TypeScript plugin
-pnpm build:engine     # Go engine for the host platform
-dsh plugin --profile web add /absolute/path/to/dsh-locator
+pnpm build            # TypeScript 插件
+pnpm build:engine     # 本机平台的 Go 引擎
+dsh plugin --profile web add /绝对路径/dsh-locator
 
-# from a packed tarball (verified install path)
+# 从打包 tarball（已实测的安装路径）
 npm pack
-dsh plugin --profile web add /absolute/path/to/dsh-locator-0.1.0.tgz
+dsh plugin --profile web add /绝对路径/dsh-locator-0.5.0.tgz
 ```
 
-The npm package ships prebuilt engines for `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` and `darwin-arm64`.
+npm 包内置 `linux-x64`、`linux-arm64`、`win32-x64`、`win32-arm64`、`darwin-x64`、`darwin-arm64` 六个平台的预编译引擎。
 
-After installing into a Web profile that is already running, **reload the page** (`F5`): the host tools may mount immediately, but the browser panel (`client.js`) is loaded from the boot graph at page load. Headless/TUI profiles never mount the panel.
+装进**已经在运行**的 Web profile 后，请**刷新页面**（`F5`）：宿主工具可能立即热挂载，但浏览器面板（`client.js`）是在页面加载时从 boot graph 取的。headless/TUI profile 不会挂面板。
 
-## First run
+## 首次运行
 
-On first mount the engine indexes the configured roots (default: your home directory) and writes a snapshot to the platform cache directory:
+首次挂载时引擎扫描配置的根目录（默认：用户主目录），快照写到平台缓存目录：
 
-| Platform | Default state directory |
+| 平台 | 默认状态目录 |
 |---|---|
 | Windows | `%LOCALAPPDATA%\dsh-locator` |
 | macOS | `~/Library/Application Support/dsh-locator` |
-| Linux | `$XDG_CACHE_HOME/dsh-locator` or `~/.cache/dsh-locator` |
+| Linux | `$XDG_CACHE_HOME/dsh-locator` 或 `~/.cache/dsh-locator` |
+
+大目录首次扫描会读盘；之后启动直接加载快照。首次扫描**期间也照常响应**：搜索返回已索引的部分并带 `indexing: true`，面板底栏提示索引构建中，不会被冷扫描卡住。默认排除 `node_modules`、`.git`、`.svn`、`.hg`、`.cache`、`__pycache__`、`.venv`、`venv`、`.next`。
 
-The first scan of a large home directory reads the disk; later starts load the snapshot instead. Requests are served **during** that first scan: search returns the entries indexed so far with `indexing: true`, and the panel footer says the index is still building. Nothing blocks on the cold scan. A default exclude list skips `node_modules`, `.git`, `.svn`, `.hg`, `.cache`, `__pycache__`, `.venv`, `venv` and `.next`.
+## Web 搜索面板
 
-## Web search panel
+![dsh-locator 搜索面板：按路径过滤 Markdown，显示命中数、耗时和排序](docs/assets/panel-zh.png)
 
-Press `Ctrl+Shift+F` anywhere in the Web GUI, or click the magnifier at the sidebar foot. The overlay queries the same index through two same-origin host routes (`POST /dsh-locator/search`, `POST /dsh-locator/status`), so it needs no second server and no extra port.
+在 Web GUI 里按 `Ctrl+Shift+F`，或点侧栏底部的放大镜。浮层通过两个同源宿主路由（`POST /dsh-locator/search`、`POST /dsh-locator/status`）查询同一个索引，不另起服务、不加端口。
 
-* Empty query lists the most recently modified entries; typing runs the same Everything-style syntax as the tool after a 110 ms debounce.
-* Click a column header to sort by name, size, modification time or path; toggle ascending/descending.
-* `只看文件` / `只看目录` filter the kind; the footer reports matches, the page cap and query latency.
-* `↑`/`↓` select, `Enter` copies the selected path, `Ctrl+O` opens it, `Ctrl+Enter` inserts a quoted `@"path"` into the composer, **double-click reveals it** in Explorer/Finder/`xdg-open`, `Esc` closes.
-* The panel follows `navigator.language` (zh/en/es/pt/hi).
-* The panel is optional: profiles without a Web server never mount it, and the three tools keep working.
+* 空查询按修改时间倒序列出最近条目；输入后 110 ms 防抖，走和工具完全相同的 Everything 风格语法。
+* 点列头按名称、大小、修改时间、路径排序，再点切换升降序。
+* `只看文件` / `只看目录` 过滤类型；底栏显示命中数、分页上限和查询耗时。
+* `↑`/`↓` 选择，`Enter` 复制选中路径，`Ctrl+O` 打开，`Ctrl+Enter` 把带引号的 `@"路径"` 插入输入框，**双击在文件管理器中定位**（Explorer / Finder / `xdg-open`），`Esc` 关闭。
+* 面板跟随 `navigator.language`（中/英/西/葡/印地语）。
+* 面板是可选的：没有 Web server 的 profile 不会挂载它，三个工具照常工作。
 
-## Tools
+## 工具
 
-| Tool | What it does |
+| 工具 | 作用 |
 |---|---|
-| `locator_search` | Query the index. Returns path, size, modification time, extension and kind, plus total/truncated so a capped page is never presented as complete. |
-| `locator_status` | Roots, entry counts, watcher state, state directory and engine path. Use it to explain coverage or diagnose a stale result. |
-| `locator_rebuild` | Replace the index with a fresh background scan. Searches keep using the old index until the new one is ready. |
-| `locator_export` | Write a read-only SQLite mirror of the index (`entries` table) for external SQL tools. Streams page by page; the binary snapshot stays primary. |
+| `locator_search` | 查询索引，返回路径、大小、修改时间、扩展名、类型，并给出 total/truncated，截断页面不会被当成完整结果。 |
+| `locator_status` | 根目录、条目数、监听状态、状态目录与引擎路径。用来解释覆盖范围或排查结果过期。 |
+| `locator_rebuild` | 后台重建索引；新索引就绪前，搜索继续用旧索引。 |
+| `locator_export` | 把索引导出成只读 SQLite（`entries` 表），供外部 SQL 工具查询；逐页流式导出，二进制快照仍是主存储。 |
 
-### Query language
+### 查询语法
 
-Bare words are ANDed substrings of the file name. Everything-style filters combine with them:
+裸词是文件名子串，多个词取 AND；可叠加 Everything 风格过滤：
 
-| Example | Meaning |
+| 例子 | 含义 |
 |---|---|
-| `report` | name contains `report` |
-| `report ext:pdf` | …and the extension is `pdf` |
-| `ext:ts,js` / `ext:!tmp` | include or exclude extensions |
-| `*.sln` / `?ata` | `*` and `?` wildcards |
-| `"annual report"` | phrase with a space |
-| `!archive` | negate a term |
-| `path:src` | the full path contains `src` |
-| `size:>10mb` / `size:1kb..2mb` | size comparisons |
-| `dm:today` / `dm:thisweek` / `dm:2026-01-01` | modification time |
-| `folder:` / `file:` | directories or files only |
-| `case:1` / `wholeword:1` | case-sensitive / word boundaries |
+| `report` | 文件名含 `report` |
+| `report ext:pdf` | 且扩展名是 `pdf` |
+| `ext:ts,js` / `ext:!tmp` | 包含/排除扩展名 |
+| `*.sln` / `?ata` | `*`、`?` 通配 |
+| `"annual report"` | 带空格的短语 |
+| `!archive` | 取反 |
+| `path:src` | 完整路径含 `src` |
+| `size:>10mb` / `size:1kb..2mb` | 大小比较 |
+| `dm:today` / `dm:thisweek` / `dm:2026-01-01` | 修改时间 |
+| `folder:` / `file:` | 只看目录 / 只看文件 |
+| `case:1` / `wholeword:1` | 区分大小写 / 全词匹配 |
 
-`locator_search` also takes `sort` (`name`, `path`, `size`, `mtime`, `ext`), `desc`, `offset`, `limit`, `regex`, `caseSensitive` and `wholeWord` parameters.
+`locator_search` 还接受 `sort`（`name`、`path`、`size`、`mtime`、`ext`）、`desc`、`offset`、`limit`、`regex`、`caseSensitive`、`wholeWord`。
 
-## Configuration
+## 配置
 
-Every field is a Schemastery config field; edit the `dsh-locator` entry in the profile patch (or the bundled `cordis.patch.yml` defaults).
+所有字段都是 Schemastery 配置；改 profile patch 里的 `dsh-locator` 条目，或改包内 `cordis.patch.yml` 的默认值。
 
-| Key | Default | Meaning |
+| 键 | 默认 | 含义 |
 |---|---|---|
-| `enabled` | `true` | Mount no tools and start no engine when `false`. |
-| `roots` | `[]` | Directories to index; empty means the home directory. |
-| `excludes` | dev/cache directories | Base-name globs skipped by scanner and watcher. |
-| `watch` | `true` | Apply native filesystem notifications. |
-| `refreshIntervalMs` | `1800000` | Rebuild cadence when no native watcher is active (kqueue fallback or a watcher failure); `0` disables. |
-| `scanWorkers` | `0` | Directory reader concurrency during scans; `0` uses the CPU count. |
-| `windowsUsn` | `false` | Try the NTFS USN/MFT enumeration before the walk (Windows, administrator; falls back automatically). |
-| `stateDir` | `''` | Snapshot directory; empty means the platform cache directory. |
-| `binaryPath` | `''` | Override the bundled engine (development). |
-| `maxResults` | `100` | Hard cap for one search page. |
-| `startupTimeoutMs` | `120000` | How long a cold build may take before the plugin reports failure. |
-| `requestTimeoutMs` | `15000` | Per-request deadline. |
-
-Narrow `roots` if indexing the whole home directory is too much I/O. A small, focused set (`~/Documents`, `~/Downloads`, one code tree) is usually the best trade-off.
-
-## Platform support
-
-| Platform | Scan + snapshot | Live updates | Notes |
+| `enabled` | `true` | 关掉后不挂工具、不起引擎。 |
+| `roots` | `[]` | 要索引的目录；空 = 用户主目录。 |
+| `excludes` | 开发/缓存目录 | 扫描与监听都跳过的基础名 glob。 |
+| `watch` | `true` | 启用原生文件系统通知。 |
+| `refreshIntervalMs` | `1800000` | 没有原生监听时（kqueue 回退或监听失败）的重建周期；0 关闭。 |
+| `scanWorkers` | `0` | 扫描时的目录读取并发；0 = CPU 数。 |
+| `memoryLimitMB` | `0` | 引擎的 Go 软堆上限（MiB）；0 = 交给 `GOMEMLIMIT`/`GOGC`。 |
+| `windowsUsn` | `false` | 扫描时先试 NTFS USN/MFT 枚举（Windows，需管理员；失败自动回退）。 |
+| `stateDir` | `''` | 快照目录；空 = 平台缓存目录。 |
+| `binaryPath` | `''` | 覆盖内置引擎路径（开发用）。 |
+| `maxResults` | `100` | 单页硬上限。 |
+| `startupTimeoutMs` | `120000` | 冷启动建索引的容忍时间。 |
+| `requestTimeoutMs` | `15000` | 单次请求超时。 |
+
+主目录太大就收窄 `roots`：`~/Documents`、`~/Downloads` 加一两棵代码树，通常比全盘更划算。
+
+## 平台支持
+
+| 平台 | 扫描 + 快照 | 实时更新 | 说明 |
 |---|---|---|---|
-| Linux | yes | inotify, recursive | Watch descriptors are per directory; very large trees can hit `fs.inotify.max_user_watches`. |
-| Windows | yes | `ReadDirectoryChangesW`, recursive | No admin rights and no Everything needed. Optional USN/MFT enumeration when running elevated. Changes made by WSL to `/mnt/<drive>` may not raise notifications; use `locator_rebuild` for those. |
-| macOS | yes | FSEvents in the shipped cgo binaries, recursive and uncapped | kqueue is the `CGO_ENABLED=0` fallback (up to 4,096 directories). File content changes do not raise vnode events in the fallback, so size/mtime refresh comes from `refreshIntervalMs` or `locator_rebuild`. |
+| Linux | 是 | inotify，递归 | 每个目录一个 watch；极大目录树可能撞 `fs.inotify.max_user_watches`。 |
+| Windows | 是 | `ReadDirectoryChangesW`，递归 | 不需要管理员，不需要 Everything。提权时可选用 USN/MFT 枚举。WSL 写 `/mnt/<盘>` 可能不产生 Windows 通知，用 `locator_rebuild` 补。 |
+| macOS | 是 | 随包发布的 cgo 二进制使用 FSEvents（递归、无上限） | `CGO_ENABLED=0` 构建回退到 kqueue（最多 4,096 个目录）；回退模式下内容变化仍由 `refreshIntervalMs` 或 `locator_rebuild` 刷新。 |
 
-The engine is pure Go except the macOS FSEvents backend, which uses cgo and is built on a macOS runner. Linux, Windows and the kqueue fallback build with `CGO_ENABLED=0`; USN is optional and needs admin rights, everything else does not.
+引擎是纯 Go、无 cgo，一台机器交叉编译全部平台；运行时从不需要管理员权限。
 
-### Windows and the USN journal
+### Windows 与 USN 日志
 
-The engine carries a USN decoder, an opt-in fast path and a probe. The path is **off by default** (`windowsUsn: false`) because the volume ioctl needs administrator rights; it has been validated end to end on a GitHub Actions Windows runner (administrator, real NTFS volume):
-- 1,345,546 MFT records read, 1,345,539 paths resolved
-- 164,209 entries under `C:\Windows` (122,915 files, 41,294 dirs)
-- `scan --usn --root C:\Windows` indexed 164,216 entries in 7.8 s; a query returned in 9.6 ms
-- the change journal was read (8,233 records on one run) and an inactive journal on `D:` fell back to the walk with a warning
+引擎里已经有 USN 解码器、可选的快路径和探针。快路径**默认关闭**（`windowsUsn: false`）：卷 ioctl 需要管理员权限；它已经在 GitHub Actions 的 Windows runner（管理员、真实 NTFS 卷）上端到端验证：
+- 读取 1,345,546 条 MFT 记录，解析出 1,345,539 条路径
+- `C:\Windows` 下 164,209 条（122,915 文件、41,294 目录）
+- `scan --usn --root C:\Windows` 建索引 164,216 条用 7.8 秒；查询 9.6 ms
+- 变更日志可读（某次运行读到 8,233 条）；`D:` 卷日志未启用时带警告回退目录遍历
 
-You can still run the same probe yourself:
+你也可以自己跑同一个探针：
 
 ```powershell
-# Elevated PowerShell (or: Start-Process -Verb RunAs <path> ...)
+# 管理员 PowerShell（或：Start-Process -Verb RunAs <路径> ...）
 & ".\bin\win32-x64\indexd.exe" usn-probe --volume C: --root "C:\Windows" --limit 5 --journal 5
 ```
 
-It prints the journal id/USNs, enumerates the MFT (records per second, files/dirs below the root, sample paths) and decodes the last few change-journal records. A non-elevated run fails with `Access is denied` — the parser and path reconstruction are covered by unit tests on every platform.
+它会打印日志 id/USN、枚举 MFT（每秒记录数、根目录下文件/目录数、样例路径），并解码最近几条变更日志。非管理员运行会明确报 `Access is denied`；解析与路径重建在 Linux 上有单元测试覆盖。
 
-With `windowsUsn: true` (or `indexd scan --usn`) the engine enumerates the MFT instead of walking directories, then builds paths from the FRN parent map. A successful USN scan also writes `usn-state.json` (journal id, next USN, roots) and keeps the FRN in each record; on the next `serve --usn` the engine replays the journal from that cursor before answering, so files created while it was stopped appear without a full scan. A wrapped, deleted or mismatched journal falls back to the portable watcher. It keeps the volume handle and polls the change journal every two seconds, applying creates, deletes and renames through `usn.ApplyChanges` (the same FRN map, updated in place). USN records carry **no size or modification time**: results are correct for names and paths, `locator_status` marks such an index with `USN`, and the daemon stats the returned page so the rows the panel/model sees still show real sizes and dates. `size:`/`dm:` filters over the whole index stay approximate until a metadata pass runs. Any failure (no elevation, unsupported volume, too many records) falls back to the portable walk with a warning; it never disables search. If journal polling fails mid-session, the watcher reports it and stops; the portable `ReadDirectoryChangesW` watcher and `locator_rebuild` are still there. The journal applier is covered by synthetic-record tests and the ioctl path by the Windows CI job.
+打开 `windowsUsn: true`（或 `indexd scan --usn`）后，引擎用 MFT 枚举代替目录遍历，再按 FRN 父表重建路径。成功的 USN 扫描会写 `usn-state.json`（日志 id、next USN、根目录），并把 FRN 存进索引记录；下次 `serve --usn` 会先从该游标重放日志再提供服务，停机期间新建的文件无需全量重扫即可出现。日志回绕/被删/不匹配时回退到可移植监听。引擎保留卷句柄，每 2 秒轮询变更日志，按同一张 FRN 表就地应用新建、删除、重命名（`usn.ApplyChanges`）。USN 记录**没有大小和修改时间**：名字/路径是准的，`locator_status` 会把这种索引标成 `USN`，守护进程会对返回页现场 stat，所以面板/模型看到的行仍有真实大小和日期；但全库的 `size:`/`dm:` 过滤在元数据补齐前是近似的。任何失败（没提权、卷不支持、记录过多）都会带警告回退到目录遍历，绝不会让搜索不可用。运行中日志轮询失败会报警并停止该监视器，可移植的 `ReadDirectoryChangesW` 监听和 `locator_rebuild` 仍然可用。变更应用逻辑有合成记录测试，ioctl 路径由 Windows CI job 验证。
 
-Everything reads the NTFS Master File Table through the USN journal, which is why its first index is nearly instant. `dsh-locator` keeps a portable directory walk as the default (no service, no UAC, any filesystem) and uses USN/MFT as an opt-in fast path where the process holds `GENERIC_READ` (admin), with journal replay across restarts. The portable path stays the fallback.
+Everything 之所以首次索引近乎瞬时，是因为它通过 USN 日志直接读 NTFS 主文件表。`dsh-locator` v0.1 刻意先做可移植的目录遍历 + 变更通知：不需要服务、不需要 UAC、任何文件系统都能用。USN/MFT 枚举会作为可选快路径加入路线图（需要进程对卷持有 `GENERIC_READ`，通常意味着管理员权限），可移植路径始终保留为回退。
 
-## Performance
+## 性能
 
-Measured on a developer WSL2 machine with a Linux home directory (1,234,757 entries: 1,128,288 files, 106,469 directories), excluding `node_modules`, `.git`, `.cache` and `.venv`:
+开发者 WSL2 机器、Linux 主目录实测（1,234,757 条目：1,128,288 文件、106,469 目录，排除 `node_modules`、`.git`、`.cache`、`.venv`）：
 
-| Metric | Result |
+| 指标 | 结果 |
 |---|---|
-| Cold scan (uncached I/O) | 50.3 s |
-| Warm scan (page cache, 8 readers) | 4.6–6.5 s (~190–265k entries/s) |
-| Snapshot size | 133 MB |
-| Peak scan RSS | ~490 MB |
-| First search during the initial scan | 2 ms (partial, `indexing: true`) |
-| `locator_search "report"` (981 matches) | 34 ms |
-| `locator_search "package.json"` (1,287 matches) | 25 ms |
-| Query process RSS (1.2 M entries) | ~197 MB |
-| Small tree (39k entries) scan | 0.47 s |
+| 冷扫描（未命中页缓存） | 50.3 s |
+| 热扫描（页缓存命中，8 个读取协程） | 4.6–6.5 s（约 190–265k 条目/秒） |
+| 快照大小 | 133 MB |
+| 扫描峰值 RSS | 约 490 MB |
+| 首次扫描进行中的第一次搜索 | 2 ms（部分结果，`indexing: true`） |
+| `locator_search "report"`（981 命中） | 34 ms |
+| `locator_search "package.json"`（1,287 命中） | 25 ms |
+| 查询进程 RSS（120 万条目） | 约 197 MB |
+| 小目录树（3.9 万条目）扫描 | 0.47 s |
+
+查询阶段按记录分片并行；冷扫描慢在磁盘。数字随文件系统、缓存和 CPU 变化。
 
-Search is parallel over the record array; the slower cold scan is disk-bound. Numbers vary with the filesystem, cache state and CPU.
+## 设计
 
-## Design
+![dsh-locator 架构：文件系统 → 扫描/监听 → 紧凑快照 → 查询引擎 → agent 工具 / Web 面板](docs/assets/architecture.svg)
 
 ```
 DeepSeek Harness
-  └─ dsh-locator (TypeScript plugin)
+  └─ dsh-locator（TypeScript 插件）
        ├─ locator_search / locator_status / locator_rebuild
-       ├─ client.js: Ctrl+Shift+F overlay (shell.overlay slot)
-       ├─ POST /dsh-locator/{search,status} (same-origin, loopback-hosted)
-       └─ child process: indexd serve  (Go, NDJSON over stdio)
-            ├─ scanner: recursive walk, excludes, progress
-            ├─ index:   names arena + fixed records + open-addressing path table
-            ├─ query:   parser, matcher, top-K selection, sort, pagination
-            ├─ watcher: inotify (Linux) / ReadDirectoryChangesW (Windows)
-            └─ snapshot: single file, mmap-friendly, atomic rename
+       ├─ client.js：Ctrl+Shift+F 浮层（shell.overlay slot）
+       ├─ POST /dsh-locator/{search,status}（同源、仅回环宿主）
+       └─ 子进程：indexd serve（Go，stdio 上的 NDJSON）
+            ├─ 扫描器：递归遍历、排除、进度
+            ├─ 索引：名字 arena + 定长记录 + 开放寻址路径表
+            ├─ 查询：解析、匹配、Top-K 选择、排序、分页
+            ├─ 监听：inotify（Linux）/ ReadDirectoryChangesW（Windows）
+            └─ 快照：单文件、原子重命名
 ```
 
-* **Parallel scanner.** Directory readers drain a bounded work queue and flush one batch per directory (`AddBatch`), so a parent record exists before its children are enqueued. The queue never blocks: a full queue falls back to scanning that subtree inline.
-* **Memory layout.** Records store a name offset/length into one byte arena plus a parent id; full paths are reconstructed only for the result page and for `path:` filters. That avoids one string header per file.
-* **Path table.** An open-addressing table of `id+1` slots keeps lookup/update near 12 bytes per entry instead of the ~50 bytes a `map[string]int32` costs.
-* **Query engine.** Bare terms and filters are compiled once, matched in parallel chunks, then reduced with a bounded max-heap: the top `offset+limit` rows are selected without sorting a million matches.
-* **Persistence.** The snapshot is written to a temporary file and renamed; a generation counter lets the daemon autosave only when the index changed. Tombstones are compacted when deletions exceed a threshold.
-* **Protocol.** One JSON request/response per line on stdio, with unsolicited `scan`, `stats`, `warning`, `error` and `rebuilt` events. No ports, no auth surface, no network listeners.
-* **Read-only.** The engine opens files for metadata only; it never writes to indexed paths.
+* **并行扫描**：目录读取协程消费一个有界任务队列，每个目录批量调用 `AddBatch` 落库，保证父记录先于子记录；队列满时改为在当前协程内联扫描，永不阻塞。
+* **内存布局**：记录只存名字在 arena 中的偏移/长度和父记录 id，完整路径只在结果页和 `path:` 过滤时重建，避免每个文件一个字符串头。
+* **路径表**：开放寻址、槽位存 `id+1`，每条约 12 字节，而 `map[string]int32` 约 50 字节。
+* **查询引擎**：裸词与过滤只编译一次，分片并行匹配，再用有界大顶堆选出 `offset+limit` 行，不排序上百万命中。
+* **持久化**：先写临时文件再重命名；generation 计数让守护进程只在索引变化时自动保存；墓碑超过阈值后压缩。
+* **协议**：stdio 上一行一个 JSON 请求/响应，另有 `scan`、`stats`、`warning`、`error`、`rebuilt` 事件。不开端口、无网络监听面。
+* **只读**：引擎只读元数据，绝不修改被索引的文件。
 
-## Build from source
+## 从源码构建
 
-Requirements: Node `^22.19 || >=24.9`, pnpm, Go 1.22+ for the engine.
+需要 Node `^22.19 || >=24.9`、pnpm、Go 1.22+。
 
 ```sh
 pnpm install
 pnpm typecheck
 pnpm test
 pnpm build
-pnpm build:engine:all   # or build:engine for the host target
+pnpm build:engine:all   # 或 build:engine 只构建本机
 ```
 
-The engine is a separate Go module under `engine/`; run its tests with `cd engine && go test ./...`.
+引擎是 `engine/` 下的独立 Go module；`cd engine && go test ./...`。
 
-## Limitations (v0.1)
+## 限制
 
-* File names, paths, sizes and modification times only — **no content indexing**. Use `grep` for contents.
-* The index covers configured roots; it is not a filesystem driver.
-* Linux inotify watches one descriptor per directory; a home directory with hundreds of thousands of directories can exceed the kernel limit. The plugin reports the warning and the snapshot stays usable; rebuilds catch up.
-* WSL writes into `/mnt/c` may not produce Windows notifications (the Windows watcher cannot see the 9p writer's change stream). Rebuild those roots explicitly.
-* Network shares are scanned only if they are reachable as ordinary directories; no SMB-specific change feed.
-* macOS uses FSEvents (recursive) in the shipped binaries; a `CGO_ENABLED=0` build falls back to kqueue, capped at 4,096 directories. Content-only changes rely on the periodic rebuild either way.
-* Windows USN/MFT is optional and only used when the process can read the volume and the journal is active; otherwise the portable walk is used.
+* 只索引文件名、路径、大小、修改时间，**不索引内容**；内容检索请用 `grep`。
+* 只覆盖配置的根目录，不是文件系统驱动。
+* Linux inotify 每个目录一个描述符；几十万目录的主目录可能超过内核上限。插件会报警告，快照仍可用，重建可以补齐。
+* WSL 写 `/mnt/c` 可能不产生 Windows 侧通知（Windows 监听看不到 9p 写入方的变更流），需显式重建。
+* 网络共享只有在能当普通目录访问时才会被扫描；没有 SMB 专用变更源。
+* macOS 随包二进制使用 FSEvents（递归）；`CGO_ENABLED=0` 构建回退到 kqueue（每目录一个描述符，上限 4,096）。两种模式的内容变更都靠周期重建兜底。
 
-## Roadmap
+## 路线图
 
-1. Electron desktop runtime check on a real Windows install.
-2. Richer previews and result grouping in the panel.
-3. Windows on ARM / Linux ARM runtime coverage.
-4. Optional lowercase-name arena and trigram prefilter for large indexes.
-5. Incremental snapshot compaction and per-root journals.
+1. macOS FSEvents 监听。
+2. 有卷读取权限时的 Windows USN/MFT 快速枚举；停机后按 USN 日志补齐。
+3. 专用 Web GUI 面板（表格、列排序、过滤、预览、插入为 `@file`）。
+4. 可选的小写名字 arena 与 trigram 预筛。
+5. 增量快照压缩与按根目录的日志。
 
-## Memory
+## 内存
 
-The engine is a single Go process and honours the standard `GOMEMLIMIT` and `GOGC` environment variables. A 1.24 M-entry index peaks around 700–800 MB RSS with the default GC; set `GOMEMLIMIT=600MiB` (soft limit, the runtime trades CPU for memory) or `GOGC=50` when the host is tight on RAM. Neither changes the snapshot format.
+引擎是单个 Go 进程，遵循标准 `GOMEMLIMIT` / `GOGC` 环境变量。124 万条索引在默认 GC 下峰值约 700–800MB RSS；内存紧张时设 `GOMEMLIMIT=600MiB`（软上限，运行时用 CPU 换内存）或 `GOGC=50`。都不改变快照格式。
 
-## Security and privacy
+## 安全与隐私
 
-The index is local: no network calls, no telemetry, no uploads. The snapshot contains file names and paths, so treat the state directory as private data and exclude it from backups if that matters to you. The plugin never modifies, moves or deletes indexed files.
+索引完全本地：不联网、不埋点、不上传。快照里是文件名和路径，请把状态目录当私有数据；介意的话别把它纳入备份。插件绝不修改、移动或删除被索引的文件。
 
-## License
+## 许可证
 
-Apache-2.0.
+Apache-2.0。

package/client.js

@@ -467,7 +467,7 @@ window.__ModuleLoader__.load({
             'aria-label': t('searchLabel'),
           }),
           h('span', { className: 'dsh-locator-kbd' }, 'Ctrl+Shift+F'),
-          h('button', { className: 'dsh-locator-close', onClick: close, title: t('closeTitle'), 'aria-label': t('closeLabel') }, '✕'),
+          h('button', { className: 'dsh-locator-close', onClick: close, title: t('closeTitle'), 'aria-label': t('closeLabel') }, '×'),
         ),
         h('div', { className: 'dsh-locator-bar' },
           h('label', { className: 'dsh-locator-check' },

package/docs/assets/architecture.svg

@@ -0,0 +1,68 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 980 380" width="980" height="380" role="img" aria-label="dsh-locator architecture">
+  <style>
+    .box{fill:#fff;stroke:#c9d1d9;stroke-width:1.5;rx:10}
+    .accent{fill:#eef4ff;stroke:#4f7cff}
+    .title{font:600 15px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;fill:#1f2328}
+    .body{font:12px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;fill:#57606a}
+    .mono{font:11px ui-monospace,SFMono-Regular,Consolas,monospace;fill:#57606a}
+    .arrow{stroke:#8c959f;stroke-width:1.6;fill:none;marker-end:url(#a)}
+    .label{font:11px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;fill:#8c959f}
+    .chip{fill:#f6f8fa;stroke:#d0d7de;stroke-width:1}
+  </style>
+  <defs>
+    <marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0L10 5L0 10z" fill="#8c959f"/>
+    </marker>
+  </defs>
+
+  <text class="title" x="24" y="32">dsh-locator — self-built index, no Everything</text>
+
+  <!-- filesystem -->
+  <rect class="box" x="24" y="58" width="190" height="150"/>
+  <text class="title" x="42" y="86">Filesystems</text>
+  <rect class="chip" x="42" y="102" width="154" height="26" rx="6"/><text class="body" x="54" y="119">Linux · inotify</text>
+  <rect class="chip" x="42" y="136" width="154" height="26" rx="6"/><text class="body" x="54" y="153">macOS · FSEvents</text>
+  <rect class="chip" x="42" y="170" width="154" height="26" rx="6"/><text class="body" x="54" y="187">Windows · USN/MFT</text>
+
+  <!-- ingest -->
+  <rect class="accent" x="258" y="58" width="220" height="150"/>
+  <text class="title" x="276" y="86">Scan &amp; watch</text>
+  <text class="body" x="276" y="112">parallel walker (16 workers)</text>
+  <text class="body" x="276" y="134">MFT enumeration + journal reader</text>
+  <text class="body" x="276" y="156">native change watchers</text>
+  <text class="mono" x="276" y="184">fallback: rebuild / refresh</text>
+
+  <!-- snapshot -->
+  <rect class="box" x="522" y="58" width="196" height="150"/>
+  <text class="title" x="540" y="86">Compact snapshot</text>
+  <text class="body" x="540" y="112">40 B records · shared name arena</text>
+  <text class="body" x="540" y="134">open-addressed path table</text>
+  <text class="body" x="540" y="156">atomic save · mmap-friendly load</text>
+  <text class="mono" x="540" y="184">usn-state.json → journal cursor</text>
+
+  <!-- query -->
+  <rect class="box" x="762" y="58" width="190" height="150"/>
+  <text class="title" x="780" y="86">Query engine</text>
+  <text class="body" x="780" y="112">parse Everything-style terms</text>
+  <text class="body" x="780" y="134">parallel match · bounded top-K</text>
+  <text class="body" x="780" y="156">25–35 ms over 1.2 M entries</text>
+
+  <path class="arrow" d="M214 133H250"/>
+  <path class="arrow" d="M478 133H514"/>
+  <path class="arrow" d="M718 133H754"/>
+
+  <!-- consumers -->
+  <rect class="box" x="258" y="254" width="300" height="88"/>
+  <text class="title" x="276" y="282">Agent tools (host side)</text>
+  <text class="mono" x="276" y="306">locator_search · locator_status</text>
+  <text class="mono" x="276" y="326">locator_rebuild · locator_export</text>
+
+  <rect class="box" x="590" y="254" width="362" height="88"/>
+  <text class="title" x="608" y="282">Web panel · Ctrl+Shift+F</text>
+  <text class="mono" x="608" y="306">POST /dsh-locator/search · status</text>
+  <text class="mono" x="608" y="326">reveal · open · sort · filters · @file</text>
+
+  <path class="arrow" d="M600 208V246"/>
+  <path class="arrow" d="M700 208V246"/>
+  <text class="label" x="610" y="232">same snapshot, no second server</text>
+</svg>

package/lib/config.d.ts

@@ -21,6 +21,8 @@ export interface Config {
     refreshIntervalMs: number;
     /** Directory reader concurrency during scans; 0 uses the CPU count. */
     scanWorkers: number;
+    /** Soft Go heap limit in MiB for the engine; 0 leaves it to GOMEMLIMIT/GOGC. */
+    memoryLimitMB: number;
     /**
      * Try the NTFS USN/MFT enumeration before the portable walk (Windows only,
      * requires running DSH as administrator). Falls back automatically.

package/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAE7C,oCAAoC;AACpC,MAAM,WAAW,MAAM;IACrB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAA;IAChB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAA;IACd;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAA;IACxB,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,yEAAyE;AACzE,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CAuBhC,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAE7C,oCAAoC;AACpC,MAAM,WAAW,MAAM;IACrB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAA;IAChB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAA;IACd;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAA;IACxB,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,yEAAyE;AACzE,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CAwBhC,CAAA"}

package/lib/config.js

@@ -21,6 +21,7 @@ export const Config = Schema.object({
     watch: Schema.boolean().default(true),
     refreshIntervalMs: Schema.number().default(1_800_000),
     scanWorkers: Schema.number().default(0),
+    memoryLimitMB: Schema.number().default(0),
     windowsUsn: Schema.boolean().default(false),
     stateDir: Schema.string().default(''),
     binaryPath: Schema.string().default(''),

package/lib/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAqC7C,yEAAyE;AACzE,MAAM,CAAC,MAAM,MAAM,GAAmB,MAAM,CAAC,MAAM,CAAC;IAClD,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;QAC9C,cAAc;QACd,MAAM;QACN,KAAK;QACL,MAAM;QACN,QAAQ;QACR,aAAa;QACb,OAAO;QACP,MAAM;QACN,OAAO;KACR,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;IACrD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACxC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;IAClD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;CAClD,CAAC,CAAA"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAuC7C,yEAAyE;AACzE,MAAM,CAAC,MAAM,MAAM,GAAmB,MAAM,CAAC,MAAM,CAAC;IAClD,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;QAC9C,cAAc;QACd,MAAM;QACN,KAAK;QACL,MAAM;QACN,QAAQ;QACR,aAAa;QACb,OAAO;QACP,MAAM;QACN,OAAO;KACR,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;IACrD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACxC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;IAClD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;CAClD,CAAC,CAAA"}