# dsh-local-search

> Read-only local file and document search for DeepSeek Harness on Windows: file and folder names through Everything (`es.exe`), the text inside PDF / DOCX / XLSX / PPTX / EPUB / RTF / TXT / MD through Anytxt, exposed as five tools plus a configuration page.

This file is the compact, machine-readable summary for agents and crawlers. The contract is in `README.md`; this one repeats only what a tool router needs.

## 中文摘要

DeepSeek Harness 的本机文件搜索与文档全文检索插件：文件名走 Everything（`es.exe`），PDF / DOCX / XLSX / PPTX / EPUB / RTF / TXT / MD 的正文走 Anytxt，合成五个只读工具。查询由这两个引擎已建好的索引回答，毫秒级，不重新扫盘；整套只读，不写、不删、不重建索引、不做 OCR、不启动引擎。仅 Windows，两个引擎另行安装。

## Use it when

- The search is a step inside the task, not the task: the answer needs a document the session cannot point at, and the reply has to cite the path and quote it found.
- The session knows the answer's shape but not the keyword — a supplier name, a paraphrase, Chinese and English spellings, a product code — so it must try several queries and read what comes back.
- The answer spans several files and needs comparison, or the work is batch ("the counterparty in each of these 30 contracts").
- The text is inside PDF, DOCX, XLSX, PPTX or EPUB, which `grep` cannot read.

Finding one file by name is a legitimate request on its own: `local_search_files` answers it directly. Inside the session directory, `grep`/`glob` stay cheaper.

## Tools

| Tool | Use for | Notes |
|---|---|---|
| `local_search_files` | File and folder names, paths, cross-root discovery | Everything via `es.exe`; covers what Everything indexed |
| `local_search_content` | Text inside PDF, DOCX, XLSX, PPTX, EPUB, RTF, TXT, MD | Anytxt; each hit carries a `ref` such as `anytxt:123` |
| `local_search_fragments` | Snippets around one match | Pass a content hit's `ref` back unchanged |
| `local_search_read` | Extracted plain text of one file | Capped at `limits.readMaxChars`, hard 20,000 characters |
| `local_search_status` | Per-engine reachability | Ask before reporting "no results" |

## Arguments and limits

- `scope`: defaults to `scopes.defaultScope` (`all` out of the box); `workspace`, `work`, `personal`, `all`. `path` overrides `scope`; narrow only when the user limits the search.
- `engine`: `auto` by default and follows the configured backend; passing a name asserts the engine rather than selecting one.
- Result caps: `limits.maxResults` (default 20, hard 100) and `limits.readMaxChars` (default 8000, hard 20,000).
- Failed calls are typed with stable codes, for example `EVERYTHING_ES_NOT_FOUND`, `EVERYTHING_DOWN`, `ANYTXT_DOWN`, `ROOT_NOT_FOUND`, `SCOPE_NOT_CONFIGURED`, `INVALID_ARGUMENT`. Quote the code.

## Rules that avoid wrong answers

- `*_DOWN` means the engine is not running. Fall back to `grep`/`glob` and say you fell back; a down engine is not "no such file".
- `local_search_status` reports reachability, not repairs: installing, starting or reconfiguring an engine is the user's call, and the fix lives in the plugin card.
- Read-only: no write, delete, index-sync, OCR, export or settings operation exists on this surface.
- Windows only, and Everything / Anytxt are installed and licensed separately; the plugin never bundles, downloads or starts them.

## Links

- Source and README: https://github.com/fishdivinity/dsh-local-search
- Chinese README: https://github.com/fishdivinity/dsh-local-search/blob/main/README-zh.md
- Package: https://www.npmjs.com/package/@fishdivinity/dsh-local-search
- Changelog: https://github.com/fishdivinity/dsh-local-search/blob/main/CHANGELOG.en.md
- Architecture: https://github.com/fishdivinity/dsh-local-search/blob/main/docs/architecture.md