dsh-locator 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 — 2026-11-09
+
+First working release.
+
+* Go engine (`indexd`) with a persistent file index, parallel query matching and top-K selection.
+* Serve-during-scan: a cold start answers searches from the partially built index (`indexing: true`) instead of blocking until the scan finishes; incomplete snapshots are marked and rescanned on the next start.
+* Parallel scanner (bounded queue, per-directory batches, inline fallback) with exclude globs, progress and cancellation; snapshot save/load; tombstone compaction. Warm scan of 1.23 M entries dropped from 11.8 s to 6.5 s on the test machine.
+* Linux inotify watcher (recursive) and Windows `ReadDirectoryChangesW` watcher (recursive, no admin).
+* macOS gets a kqueue vnode watcher (directory-level creates/deletes/renames, capped at 4,096 watched directories) plus the periodic rebuild fallback; FSEvents is next.
+* USN change feed: after MFT enumeration the engine polls the journal every two seconds and applies creates, deletes and renames through a tested pure applier (`usn.ApplyChanges`), updating the FRN path map in place.
+* USN decoder and opt-in fast path (`internal/usn`): USN_RECORD_V2 parsing, FRN parent-map path reconstruction, journal read, `windowsUsn` / `--usn` MFT enumeration with automatic portable-walk fallback, page-level metadata fill for names-only records, and an `indexd usn-probe` elevated acceptance command. Off by default until the elevated probe is validated.
+* Everything-style query language: bare terms, `!` negation, quotes, `*`/`?`, `ext:`, `path:`, `size:`, `dm:`, `folder:`, `file:`, `case:`, `wholeword:`.
+* DSH plugin with `locator_search`, `locator_status`, `locator_rebuild`, a path-search result card and configurable roots/excludes/state.
+* Global Web GUI search panel (`Ctrl+Shift+F`, sidebar magnifier): debounced live search, sortable columns, kind filters, keyboard selection, path copy, status footer. Served through same-origin host routes with the Web connection's own trust check; headless profiles simply omit it.
+* Prebuilt engines for linux-x64, linux-arm64, win32-x64, win32-arm64, darwin-x64 and darwin-arm64.
+* Go unit tests, plugin integration tests and a package verification script.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 PerryLink contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README-zh.md

@@ -0,0 +1,212 @@
+# dsh-locator
+
+中文 | [English](README.md)
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的全盘毫秒级文件搜索，**自建索引**：不装 Everything、不用 `es.exe`、不需要 Everything 服务。
+
+`dsh-locator` 扫描你指定的目录，把文件名、路径、大小、修改时间写进一个紧凑的快照；之后按文件系统事件增量更新，百万条目上的名字/路径查询在几十毫秒内返回。模型拿到 `locator_search`、`locator_status`、`locator_rebuild` 三个工具；人则有一个 Web GUI 全局**搜索面板**（`Ctrl+Shift+F`，或侧栏底部的放大镜），支持列排序、过滤、键盘操作和一键复制路径。
+
+思路借鉴 Everything：常驻的文件名索引、带 `ext:` / `size:` / `dm:` 过滤的查询语法、直接消费文件系统的变更流。实现是独立的，并且跨平台。
+
+## 为什么再做一个
+
+`glob` / `grep` 每次调用都要遍历工作区——知道目录时很快，只记得名字的一部分时很慢。Everything 在 Windows 上很好用，但它只支持 Windows；包一层 Everything 仍然覆盖不了 macOS、Linux、WSL 和远程主机。`dsh-locator` 自己拥有索引，所以同一套工具在哪都能用。
+
+## 安装
+
+```sh
+# npm（发布后）
+dsh plugin --profile web add dsh-locator
+
+# 从源码
+pnpm install
+pnpm build            # TypeScript 插件
+pnpm build:engine     # 本机平台的 Go 引擎
+dsh plugin --profile web add /绝对路径/dsh-locator
+
+# 从打包 tarball（已实测的安装路径）
+npm pack
+dsh plugin --profile web add /绝对路径/dsh-locator-0.1.0.tgz
+```
+
+npm 包内置 `linux-x64`、`linux-arm64`、`win32-x64`、`win32-arm64`、`darwin-x64`、`darwin-arm64` 六个平台的预编译引擎。
+
+装进**已经在运行**的 Web profile 后，请**刷新页面**（`F5`）：宿主工具可能立即热挂载，但浏览器面板（`client.js`）是在页面加载时从 boot graph 取的。headless/TUI profile 不会挂面板。
+
+## 首次运行
+
+首次挂载时引擎扫描配置的根目录（默认：用户主目录），快照写到平台缓存目录：
+
+| 平台 | 默认状态目录 |
+|---|---|
+| Windows | `%LOCALAPPDATA%\dsh-locator` |
+| macOS | `~/Library/Application Support/dsh-locator` |
+| Linux | `$XDG_CACHE_HOME/dsh-locator` 或 `~/.cache/dsh-locator` |
+
+大目录首次扫描会读盘；之后启动直接加载快照。首次扫描**期间也照常响应**：搜索返回已索引的部分并带 `indexing: true`，面板底栏提示索引构建中，不会被冷扫描卡住。默认排除 `node_modules`、`.git`、`.svn`、`.hg`、`.cache`、`__pycache__`、`.venv`、`venv`、`.next`。
+
+## Web 搜索面板
+
+在 Web GUI 里按 `Ctrl+Shift+F`，或点侧栏底部的放大镜。浮层通过两个同源宿主路由（`POST /dsh-locator/search`、`POST /dsh-locator/status`）查询同一个索引，不另起服务、不加端口。
+
+* 空查询按修改时间倒序列出最近条目；输入后 110 ms 防抖，走和工具完全相同的 Everything 风格语法。
+* 点列头按名称、大小、修改时间、路径排序，再点切换升降序。
+* `只看文件` / `只看目录` 过滤类型；底栏显示命中数、分页上限和查询耗时。
+* `↑`/`↓` 选择，`Enter` 复制选中路径，`Esc` 关闭。
+* 面板是可选的：没有 Web server 的 profile 不会挂载它，三个工具照常工作。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `locator_search` | 查询索引，返回路径、大小、修改时间、扩展名、类型，并给出 total/truncated，截断页面不会被当成完整结果。 |
+| `locator_status` | 根目录、条目数、监听状态、状态目录与引擎路径。用来解释覆盖范围或排查结果过期。 |
+| `locator_rebuild` | 后台重建索引；新索引就绪前，搜索继续用旧索引。 |
+
+### 查询语法
+
+裸词是文件名子串，多个词取 AND；可叠加 Everything 风格过滤：
+
+| 例子 | 含义 |
+|---|---|
+| `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` 还接受 `sort`（`name`、`path`、`size`、`mtime`、`ext`）、`desc`、`offset`、`limit`、`regex`、`caseSensitive`、`wholeWord`。
+
+## 配置
+
+所有字段都是 Schemastery 配置；改 profile patch 里的 `dsh-locator` 条目，或改包内 `cordis.patch.yml` 的默认值。
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `enabled` | `true` | 关掉后不挂工具、不起引擎。 |
+| `roots` | `[]` | 要索引的目录；空 = 用户主目录。 |
+| `excludes` | 开发/缓存目录 | 扫描与监听都跳过的基础名 glob。 |
+| `watch` | `true` | 启用原生文件系统通知。 |
+| `refreshIntervalMs` | `1800000` | 没有原生监听时（目前是 macOS）的重建周期；0 关闭。 |
+| `scanWorkers` | `0` | 扫描时的目录读取并发；0 = CPU 数。 |
+| `windowsUsn` | `false` | 扫描时先试 NTFS USN/MFT 枚举（Windows，需管理员；失败自动回退）。 |
+| `stateDir` | `''` | 快照目录；空 = 平台缓存目录。 |
+| `binaryPath` | `''` | 覆盖内置引擎路径（开发用）。 |
+| `maxResults` | `100` | 单页硬上限。 |
+| `startupTimeoutMs` | `120000` | 冷启动建索引的容忍时间。 |
+| `requestTimeoutMs` | `15000` | 单次请求超时。 |
+
+主目录太大就收窄 `roots`：`~/Documents`、`~/Downloads` 加一两棵代码树，通常比全盘更划算。
+
+## 平台支持
+
+| 平台 | 扫描 + 快照 | 实时更新 | 说明 |
+|---|---|---|---|
+| Linux | 是 | inotify，递归 | 每个目录一个 watch；极大目录树可能撞 `fs.inotify.max_user_watches`。 |
+| Windows | 是 | `ReadDirectoryChangesW`，递归 | 不需要管理员，不需要 Everything。提权时可选用 USN/MFT 枚举。WSL 写 `/mnt/<盘>` 可能不产生 Windows 通知，用 `locator_rebuild` 补。 |
+| macOS | 是 | kqueue vnode 监听（最多 4,096 个目录）+ 周期性重建 | 目录级事件覆盖新建、删除、重命名；文件内容变化不产生 vnode 事件，大小/时间由 `refreshIntervalMs` 或 `locator_rebuild` 刷新。 |
+
+引擎是纯 Go、无 cgo，一台机器交叉编译全部平台；运行时从不需要管理员权限。
+
+### Windows 与 USN 日志
+
+引擎里已经有 USN 解码器、可选的快路径和探针。快路径**默认关闭**（`windowsUsn: false`）：卷 ioctl 需要管理员权限，而当前开发机没有提权，探针就是验收步骤：
+
+```powershell
+# 管理员 PowerShell（或：Start-Process -Verb RunAs <路径> ...）
+& ".\bin\win32-x64\indexd.exe" usn-probe --volume C: --root "C:\Windows" --limit 5 --journal 5
+```
+
+它会打印日志 id/USN、枚举 MFT（每秒记录数、根目录下文件/目录数、样例路径），并解码最近几条变更日志。非管理员运行会明确报 `Access is denied`；解析与路径重建在 Linux 上有单元测试覆盖。
+
+打开 `windowsUsn: true`（或 `indexd scan --usn`）后，引擎用 MFT 枚举代替目录遍历，再按 FRN 父表重建路径。引擎保留卷句柄，每 2 秒轮询变更日志，按同一张 FRN 表就地应用新建、删除、重命名（`usn.ApplyChanges`）。USN 记录**没有大小和修改时间**：名字/路径是准的，`locator_status` 会把这种索引标成 `USN`，守护进程会对返回页现场 stat，所以面板/模型看到的行仍有真实大小和日期；但全库的 `size:`/`dm:` 过滤在元数据补齐前是近似的。任何失败（没提权、卷不支持、记录过多）都会带警告回退到目录遍历，绝不会让搜索不可用。运行中日志轮询失败会报警并停止该监视器，可移植的 `ReadDirectoryChangesW` 监听和 `locator_rebuild` 仍然可用。变更应用逻辑有合成记录测试，但 ioctl 本身仍待提权探针验收。
+
+Everything 之所以首次索引近乎瞬时，是因为它通过 USN 日志直接读 NTFS 主文件表。`dsh-locator` v0.1 刻意先做可移植的目录遍历 + 变更通知：不需要服务、不需要 UAC、任何文件系统都能用。USN/MFT 枚举会作为可选快路径加入路线图（需要进程对卷持有 `GENERIC_READ`，通常意味着管理员权限），可移植路径始终保留为回退。
+
+## 性能
+
+开发者 WSL2 机器、Linux 主目录实测（1,234,757 条目：1,128,288 文件、106,469 目录，排除 `node_modules`、`.git`、`.cache`、`.venv`）：
+
+| 指标 | 结果 |
+|---|---|
+| 冷扫描（未命中页缓存） | 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 变化。
+
+## 设计
+
+```
+DeepSeek Harness
+  └─ dsh-locator（TypeScript 插件）
+       ├─ locator_search / locator_status / locator_rebuild
+       ├─ 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）
+            └─ 快照：单文件、原子重命名
+```
+
+* **并行扫描**：目录读取协程消费一个有界任务队列，每个目录批量调用 `AddBatch` 落库，保证父记录先于子记录；队列满时改为在当前协程内联扫描，永不阻塞。
+* **内存布局**：记录只存名字在 arena 中的偏移/长度和父记录 id，完整路径只在结果页和 `path:` 过滤时重建，避免每个文件一个字符串头。
+* **路径表**：开放寻址、槽位存 `id+1`，每条约 12 字节，而 `map[string]int32` 约 50 字节。
+* **查询引擎**：裸词与过滤只编译一次，分片并行匹配，再用有界大顶堆选出 `offset+limit` 行，不排序上百万命中。
+* **持久化**：先写临时文件再重命名；generation 计数让守护进程只在索引变化时自动保存；墓碑超过阈值后压缩。
+* **协议**：stdio 上一行一个 JSON 请求/响应，另有 `scan`、`stats`、`warning`、`error`、`rebuilt` 事件。不开端口、无网络监听面。
+* **只读**：引擎只读元数据，绝不修改被索引的文件。
+
+## 从源码构建
+
+需要 Node `^22.19 || >=24.9`、pnpm、Go 1.22+。
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm build:engine:all   # 或 build:engine 只构建本机
+```
+
+引擎是 `engine/` 下的独立 Go module；`cd engine && go test ./...`。
+
+## v0.1 的限制
+
+* 只索引文件名、路径、大小、修改时间，**不索引内容**；内容检索请用 `grep`。
+* 只覆盖配置的根目录，不是文件系统驱动。
+* Linux inotify 每个目录一个描述符；几十万目录的主目录可能超过内核上限。插件会报警告，快照仍可用，重建可以补齐。
+* WSL 写 `/mnt/c` 可能不产生 Windows 侧通知（Windows 监听看不到 9p 写入方的变更流），需显式重建。
+* 网络共享只有在能当普通目录访问时才会被扫描；没有 SMB 专用变更源。
+* macOS 是目录级监听（kqueue，每目录一个描述符，上限 4,096）：新建/删除/重命名即时生效；文件内容变化靠周期重建。无上限、文件级的 FSEvents 仍在路线图。
+* 还没有 USN/MFT 快速枚举（见上）。
+
+## 路线图
+
+1. macOS FSEvents 监听。
+2. 有卷读取权限时的 Windows USN/MFT 快速枚举；停机后按 USN 日志补齐。
+3. 专用 Web GUI 面板（表格、列排序、过滤、预览、插入为 `@file`）。
+4. 可选的小写名字 arena 与 trigram 预筛。
+5. 增量快照压缩与按根目录的日志。
+
+## 安全与隐私
+
+索引完全本地：不联网、不埋点、不上传。快照里是文件名和路径，请把状态目录当私有数据；介意的话别把它纳入备份。插件绝不修改、移动或删除被索引的文件。
+
+## 许可证
+
+Apache-2.0。

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# dsh-locator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文](README-zh.md) | English
+
+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.
+
+`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.
+
+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.
+
+## Why another file search
+
+`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.
+
+## Install
+
+```sh
+# from npm (once published)
+dsh plugin --profile web add dsh-locator
+
+# from a checkout
+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
+
+# from a packed tarball (verified install path)
+npm pack
+dsh plugin --profile web add /absolute/path/to/dsh-locator-0.1.0.tgz
+```
+
+The npm package ships prebuilt engines for `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` and `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.
+
+## 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` |
+
+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 search panel
+
+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.
+
+* 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, `Esc` closes.
+* The panel is optional: profiles without a Web server never mount it, and the three tools keep working.
+
+## 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. |
+
+### Query language
+
+Bare words are ANDed substrings of the file name. Everything-style filters combine with them:
+
+| 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 |
+
+`locator_search` also takes `sort` (`name`, `path`, `size`, `mtime`, `ext`), `desc`, `offset`, `limit`, `regex`, `caseSensitive` and `wholeWord` parameters.
+
+## Configuration
+
+Every field is a Schemastery config field; edit the `dsh-locator` entry in the profile patch (or the bundled `cordis.patch.yml` defaults).
+
+| 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 exists (macOS today); `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 |
+|---|---|---|---|
+| 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 | kqueue vnode watches for up to 4,096 directories, plus periodic rebuild | Directory-level events cover creates, deletes and renames. File content changes do not raise vnode events, so size/mtime refresh comes from `refreshIntervalMs` or `locator_rebuild`. |
+
+The engine is pure Go with no cgo, cross-compiled from one machine. It never needs admin privileges.
+
+### Windows and the USN journal
+
+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 and the development machine here has no elevation; the probe is the acceptance step:
+
+```powershell
+# Elevated PowerShell (or: Start-Process -Verb RunAs <path> ...)
+& ".\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.
+
+With `windowsUsn: true` (or `indexd scan --usn`) the engine enumerates the MFT instead of walking directories, then builds paths from the FRN parent map. 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, but the ioctl path itself still awaits the elevated probe.
+
+Everything reads the NTFS Master File Table through the USN journal, which is why its first index is nearly instant. `dsh-locator` v0.1 deliberately starts with a portable directory walk plus change notifications: it works without a service, without UAC and on every filesystem. USN/MFT enumeration is on the roadmap as an opt-in fast path for volumes where the process holds `GENERIC_READ` (admin) — the portable path stays the fallback.
+
+## 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`:
+
+| 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 |
+
+Search is parallel over the record array; the slower cold scan is disk-bound. Numbers vary with the filesystem, cache state and CPU.
+
+## Design
+
+```
+DeepSeek Harness
+  └─ dsh-locator (TypeScript plugin)
+       ├─ 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
+```
+
+* **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.
+
+## Build from source
+
+Requirements: Node `^22.19 || >=24.9`, pnpm, Go 1.22+ for the engine.
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm build:engine:all   # or build:engine for the host target
+```
+
+The engine is a separate Go module under `engine/`; run its tests with `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 watches are directory-level (kqueue, one descriptor per directory, capped at 4,096). Creates/deletes/renames land immediately; file content changes rely on the periodic rebuild. FSEvents remains the roadmap item for an uncapped, file-level feed.
+* No USN/MFT fast enumeration yet (see above).
+
+## Roadmap
+
+1. macOS FSEvents watcher.
+2. Windows USN/MFT fast enumeration when the process can read the volume; journal-based catch-up after downtime.
+3. Dedicated Web GUI panel (table, sortable columns, filters, preview, insert-as-`@file`).
+4. Optional lowercase-name arena and trigram prefilter for large indexes.
+5. Incremental snapshot compaction and per-root journals.
+
+## 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.