dsh-locator 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.2.0 — 2026-11-09
+
+* `locator_export`: stream the index page by page and write a read-only SQLite mirror (`entries(path, name, dir, size, mtime_ms, ext)`) through Node's built-in `node:sqlite`. The compact snapshot remains the primary store.
+* Engine `dump` RPC with a record-id cursor, so exports do not hold the index lock between pages.
+* CI runs the engine build before the Node tests, exercising the new RPC and the clean-install path together.
+* Windows USN path validated end to end on a Windows CI runner (1.34 M records, `C:\Windows` indexed in 7.8 s); macOS kqueue watcher covered by a macOS CI test.
+* Experimental cgo FSEvents backend was attempted and removed after an arm64 `FSEventStreamCreate` crash; kqueue remains the shipped macOS backend.
+
+## 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; the ioctl path, path reconstruction, journal read and the full `scan --usn` route are validated on a Windows CI runner.
+* 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,222 @@
+# dsh-locator
+
+[![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)
+
+中文 | [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` | 后台重建索引；新索引就绪前，搜索继续用旧索引。 |
+| `locator_export` | 把索引导出成只读 SQLite（`entries` 表），供外部 SQL 工具查询；逐页流式导出，二进制快照仍是主存储。 |
+
+### 查询语法
+
+裸词是文件名子串，多个词取 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 需要管理员权限；它已经在 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:` 卷日志未启用时带警告回退目录遍历
+
+你也可以自己跑同一个探针：
+
+```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 路径由 Windows CI job 验证。
+
+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。