@fishdivinity/dsh-local-search 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/LICENSE +21 -21
  2. package/README-zh.md +167 -166
  3. package/README.md +177 -176
  4. package/cordis.patch.yml +9 -9
  5. package/icon.svg +35 -7
  6. package/lib/anytxt.js +272 -252
  7. package/lib/client.js +623 -0
  8. package/lib/config.js +101 -0
  9. package/lib/engines.js +85 -85
  10. package/lib/errors.js +18 -18
  11. package/lib/everything.js +277 -219
  12. package/lib/format.js +101 -92
  13. package/lib/index.js +77 -71
  14. package/lib/limits.js +14 -0
  15. package/lib/probe.js +88 -0
  16. package/lib/ref.js +38 -38
  17. package/lib/roots.js +114 -86
  18. package/lib/route.js +170 -0
  19. package/lib/tools.js +498 -506
  20. package/locale/en.json +6 -6
  21. package/locale/zh.json +6 -6
  22. package/package.json +86 -65
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 fishdivinity
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 fishdivinity
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README-zh.md CHANGED
@@ -1,166 +1,167 @@
1
- <div align="center">
2
-
3
- <img src="https://raw.githubusercontent.com/fishdivinity/dsh-local-search/main/icon.svg" width="96" alt="Local Search 图标">
4
-
5
- # 本地搜索（DeepSeek Harness）
6
-
7
- **只读的 Everything 文件名检索 + Anytxt 文档内容检索，统一在一套能力型工具面下。**
8
-
9
- [![npm version](https://img.shields.io/npm/v/@fishdivinity/dsh-local-search)](https://www.npmjs.com/package/@fishdivinity/dsh-local-search)
10
- [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
- [![platform](https://img.shields.io/badge/platform-Windows-blue)](#前提)
12
- [![dsh](https://img.shields.io/badge/dsh-%3E%3D0.2.1--0%20%3C0.3.0-blue)](#前提)
13
- [![CI](https://img.shields.io/github/actions/workflow/status/fishdivinity/dsh-local-search/ci.yml?branch=main&label=CI)](https://github.com/fishdivinity/dsh-local-search/actions)
14
- [![GitHub stars](https://img.shields.io/github/stars/fishdivinity/dsh-local-search?style=flat)](https://github.com/fishdivinity/dsh-local-search)
15
-
16
- [English](README.md) · [简体中文](README-zh.md) · [安装](#安装) · [配置](#配置) · [工具](#工具) · [安全](#安全与限制)
17
-
18
- </div>
19
-
20
- ## 目录
21
-
22
- - [工具](#工具)
23
- - [前提](#前提)
24
- - [安装](#安装)
25
- - [配置](#配置)
26
- - [Scope](#scope)
27
- - [引擎选择](#引擎选择)
28
- - [错误码](#错误码)
29
- - [安全与限制](#安全与限制)
30
- - [已知限制](#已知限制)
31
- - [开发](#开发)
32
- - [许可证](#许可证)
33
-
34
- ## 工具
35
-
36
- | 工具 | 引擎 | 用途 |
37
- |---|---|---|
38
- | `local_search_files` | Everything / `es.exe` | 文件名、路径、跨盘找文件 |
39
- | `local_search_content` | Anytxt JSON-RPC | PDF/DOCX/XLSX/PPTX/EPUB/RTF/TXT/MD 内容 |
40
- | `local_search_fragments` | Anytxt | 命中片段 |
41
- | `local_search_read` | Anytxt | 抽取后的全文（截断） |
42
- | `local_search_status` | 两者 | 检查引擎是否可用 |
43
-
44
- ## 前提
45
-
46
- - Windows。
47
- - DeepSeek Harness `>=0.2.1-0 <0.3.0`。
48
- - Everything 正在运行，并安装 `es.exe`（voidtools 单独下载；插件会从 PATH/常见目录探测，也可配置 `esPath`）。
49
- - 内容检索需要 Anytxt Searcher 的 **GUI**（`ATGUI.exe`）在运行；JSON-RPC 服务在 GUI 进程里，只有 `ATService` 不够。
50
-
51
- 插件不打包 Everything、`es.exe` 或 Anytxt，需自行安装并遵守各自许可。
52
-
53
- ## 安装
54
-
55
- ```powershell
56
- dsh plugin --profile desktop add @fishdivinity/dsh-local-search
57
- ```
58
-
59
- npm 首发前可从 GitHub 安装：
60
-
61
- ```powershell
62
- dsh plugin --profile desktop add github:fishdivinity/dsh-local-search
63
- ```
64
-
65
- 重启 profile 或新开会话，工具列表出现 5 个 `local_search_*` 工具。
66
-
67
- ## 配置
68
-
69
- v0.1 **没有配置页面**。在 profile 的 `cordis.patch.yml` 里改插件 row，或使用下面的 override 示例。v0.2 计划在侧边栏 **Plugins** → 本插件 → **Configure** 提供表单。
70
-
71
- 全部可选；row config 是整块替换，不会深合并。
72
-
73
- | 字段 | 默认 | 说明 |
74
- |---|---|---|
75
- | `esPath` | 自动探测 | `es.exe` 绝对路径。顺序：`esPath` → `ES_PATH` → 常见安装目录 → `where.exe` |
76
- | `anytxtUrl` | `http://127.0.0.1:9920` | Anytxt JSON-RPC 地址；默认还会尝试 `:9921` |
77
- | `workspaceRoot` | 会话默认目录 | `scope=workspace` 的根 |
78
- | `workRoot` | 空 | `scope=work` 的根；使用前必须配置 |
79
- | `personalRoot` | 空 | `scope=personal` 的根；使用前必须配置 |
80
- | `allRoots` | `C:\` + 存在时的 `D:\` | Anytxt `scope=all` 的根，分号分隔；Everything 的 `all` 搜它索引的所有卷 |
81
- | `maxResults` | `20` | 默认结果上限；硬上限 100 |
82
- | `timeoutMs` | `30000` | 单次调用超时预算 |
83
- | `readMaxChars` | `8000` | `local_search_read` 默认窗口；硬上限 20,000 字符 |
84
- | `esEncoding` | `gbk` | `es.exe` 输出的代码页；zh-CN 用 GBK |
85
-
86
- 示例：
87
-
88
- ```yaml
89
- - id: fishdivinity-local-search
90
- name: '@fishdivinity/dsh-local-search'
91
- config:
92
- workRoot: 'D:\Projects'
93
- personalRoot: 'D:\Documents'
94
- allRoots: 'C:\;D:\'
95
- ```
96
-
97
- ## Scope
98
-
99
- - `workspace`（默认）：会话工作目录。
100
- - `work`：`workRoot`。
101
- - `personal`：`personalRoot`。
102
- - `all`：Anytxt 用 `allRoots`；Everything 搜所有已索引卷。
103
-
104
- 只有用户明确说“全盘/跨盘”时才用 `all`；`path` 参数可覆盖 `scope`。
105
-
106
- ## 引擎选择
107
-
108
- `engine` 默认 `auto`：
109
-
110
- - `local_search_files`：`auto` / `everything`。
111
- - `local_search_content` / `fragments` / `read`：`auto` / `anytxt`。
112
- - `local_search_status`：`auto` / `everything` / `anytxt`。
113
-
114
- 以后加引擎时工具名不变，只增加 `engine` 取值。内容结果同时带 `engine` 和自描述的 `ref`（如 `anytxt:123`）；把 `ref` 原样传给 `local_search_fragments` / `local_search_read`，`engine` 只作为校验用。
115
-
116
- ## 错误码
117
-
118
- | code | 含义 |
119
- |---|---|
120
- | `EVERYTHING_ES_NOT_FOUND` | 找不到 `es.exe`；安装或配置 `esPath` |
121
- | `EVERYTHING_DOWN` | Everything 没运行/不可达 |
122
- | `EVERYTHING_TIMEOUT` / `EVERYTHING_TOO_LARGE` | 查询太宽或太慢；缩小范围 |
123
- | `ANYTXT_DOWN` | Anytxt GUI 没运行或 JSON-RPC 不可达 |
124
- | `ANYTXT_TIMEOUT` / `ANYTXT_RPC` / `ANYTXT_HTTP` | Anytxt 侧查询/传输失败 |
125
- | `ROOT_NOT_FOUND` / `SCOPE_NOT_CONFIGURED` / `INVALID_SCOPE` | 根目录/scope 配置问题 |
126
- | `INVALID_ARGUMENT` | 空查询、非法 limit 等 |
127
-
128
- 搜到 `*_DOWN` 时回退 `grep`/`glob`，并说明已回退。
129
-
130
- ## 安全与限制
131
-
132
- - **只读**：没有写、删、索引同步、OCR、导出、改设置等操作。
133
- - `es.exe` 固定 argv，模型文本永远在 `--` 之后；`-export-*`、`-save-settings`、`-clear-settings`、`-exit`、`-reindex`、`-save-db`、run-count 不可达。
134
- - Anytxt 只调 `Search` / `GetResult` / `GetFragmentAll` / `GetRawTextByFID`。
135
- - 除本地 Anytxt 地址外不联网；结果有上限；`local_search_read` 截断。
136
- - 插件以用户权限运行，能读用户能读的文件；默认 `scope=workspace`，不要无故全盘。
137
-
138
- ## 已知限制
139
-
140
- - 仅 Windows。
141
- - Everything 1.4 只索引元数据，不索引文件内容；内容检索靠 Anytxt。
142
- - Anytxt 的 JSON-RPC 是本地非官方接口，GUI 版本可能变；插件对不可达/结构不符会明确报错。
143
- - Anytxt 索引可能滞后；重要命中要用 `read`/原文件复核。
144
- - 不自动启动 `ATGUI.exe`（启动会写索引），由用户手动控制。
145
- - v0.1 没有配置页面；改 profile patch。v0.2 计划做 Plugins 页表单。
146
- - Anytxt 条款限个人/非商业使用；商用需单独授权。
147
-
148
- ## 开发
149
-
150
- 无运行时依赖，测试用 Node 内置 test runner：
151
-
152
- ```powershell
153
- npm test
154
- npm run check
155
- npm run pack:check
156
- ```
157
-
158
- `lib/everything.js`、`lib/anytxt.js`、`lib/roots.js`、`lib/format.js` 不依赖 DSH runtime，可在普通 Node 下测试。架构与扩展见 [`docs/architecture.md`](docs/architecture.md)、[`docs/extending-engines.md`](docs/extending-engines.md)。
159
-
160
- ## Changelog
161
-
162
- 见 [CHANGELOG.md](CHANGELOG.md)。它保留在仓库里；npm tarball 只带运行时文件、README、LICENSE、locale 和 icon。
163
-
164
- ## 许可证
165
-
166
- MIT。Everything 与 Anytxt 是独立产品，各有自己的许可与商标；本项目与 voidtools、CBEWIN 无隶属关系。
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/fishdivinity/dsh-local-search/main/icon.svg" width="96" alt="Local Search 图标">
4
+
5
+ # 本地搜索（DeepSeek Harness）
6
+
7
+ **只读的 Everything 文件名检索 + Anytxt 文档内容检索，统一在一套能力型工具面下。**
8
+
9
+ [![npm version](https://img.shields.io/npm/v/@fishdivinity/dsh-local-search)](https://www.npmjs.com/package/@fishdivinity/dsh-local-search)
10
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
+ [![platform](https://img.shields.io/badge/platform-Windows-blue)](#前提)
12
+ [![dsh](https://img.shields.io/badge/dsh-%3E%3D0.2.1--0%20%3C0.3.0-blue)](#前提)
13
+ [![CI](https://img.shields.io/github/actions/workflow/status/fishdivinity/dsh-local-search/ci.yml?branch=main&label=CI)](https://github.com/fishdivinity/dsh-local-search/actions)
14
+ [![GitHub stars](https://img.shields.io/github/stars/fishdivinity/dsh-local-search?style=flat)](https://github.com/fishdivinity/dsh-local-search)
15
+
16
+ [English](README.md) · [简体中文](README-zh.md) · [安装](#安装) · [配置](#配置) · [工具](#工具) · [安全](#安全与限制)
17
+
18
+ </div>
19
+
20
+ ## 目录
21
+
22
+ - [工具](#工具)
23
+ - [前提](#前提)
24
+ - [安装](#安装)
25
+ - [配置](#配置)
26
+ - [Scope](#scope)
27
+ - [引擎选择](#引擎选择)
28
+ - [错误码](#错误码)
29
+ - [安全与限制](#安全与限制)
30
+ - [已知限制](#已知限制)
31
+ - [开发](#开发)
32
+ - [许可证](#许可证)
33
+
34
+ ## 工具
35
+
36
+ | 工具 | 引擎 | 用途 |
37
+ |---|---|---|
38
+ | `local_search_files` | Everything / `es.exe` | 文件名、路径、跨盘找文件 |
39
+ | `local_search_content` | Anytxt JSON-RPC | PDF/DOCX/XLSX/PPTX/EPUB/RTF/TXT/MD 内容 |
40
+ | `local_search_fragments` | Anytxt | 命中片段 |
41
+ | `local_search_read` | Anytxt | 抽取后的全文（截断） |
42
+ | `local_search_status` | 两者 | 检查引擎是否可用 |
43
+
44
+ ## 前提
45
+
46
+ - Windows。
47
+ - DeepSeek Harness `>=0.2.1-0 <0.3.0`。
48
+ - Everything 正在运行，并安装 `es.exe`（voidtools 单独下载；插件会从 PATH/常见目录探测，也可配置 `esPath`）。
49
+ - 内容检索需要 Anytxt Searcher 的 **GUI**（`ATGUI.exe`）在运行；JSON-RPC 服务在 GUI 进程里，只有 `ATService` 不够。
50
+
51
+ 插件不打包 Everything、`es.exe` 或 Anytxt，需自行安装并遵守各自许可。
52
+
53
+ ## 安装
54
+
55
+ ```powershell
56
+ dsh plugin --profile desktop add @fishdivinity/dsh-local-search
57
+ ```
58
+
59
+ npm 首发前可从 GitHub 安装：
60
+
61
+ ```powershell
62
+ dsh plugin --profile desktop add github:fishdivinity/dsh-local-search
63
+ ```
64
+
65
+ 重启 profile 或新开会话，工具列表出现 5 个 `local_search_*` 工具。
66
+
67
+ ## 配置
68
+
69
+ 侧边栏 **Plugins** → **Official plugins** 组里的「本地搜索」卡片 → 插件自己的页面。这张卡和 GitHub 插件那张是同一个形态。保存后对下一次工具调用生效；离开页面丢弃未保存改动，字段上的「重置」把它交回 profile 层。
70
+
71
+ **测试连接**就放在 Anytxt 地址输入框下面，测的是**输入框里当前的地址**（不用先保存），同时把 Everything 一起探一遍，一行给结果。某个引擎不可用时会给出它的官方下载页；本插件不打包、不下载、也不代替你安装这两个程序。
72
+
73
+ 全部可选；row config 是整块替换，不会深合并。只有 `timeoutMs` 留在 profile 的 `cordis.patch.yml`：每个工具在注册时就固定截止时间，因此页面上不提供这个字段，免得出现“改了没反应”。
74
+
75
+ | 字段 | 默认 | 说明 |
76
+ |---|---|---|
77
+ | `esPath` | 自动探测 | `es.exe` 绝对路径。顺序：`esPath` → `ES_PATH` → 常见安装目录 → `where.exe` |
78
+ | `anytxtUrl` | `http://127.0.0.1:9920` | 本机 Anytxt JSON-RPC 地址（只接受 `127.0.0.1`、`localhost`、`[::1]`）；默认还会尝试 `:9921` |
79
+ | `workspaceRoot` | 会话默认目录 | `scope=workspace` 的根 |
80
+ | `workRoot` | 空 | `scope=work` 的根；使用前必须配置 |
81
+ | `personalRoot` | 空 | `scope=personal` 的根；使用前必须配置 |
82
+ | `allRoots` | `C:\` + 存在时的 `D:\` | Anytxt `scope=all` 的根，分号分隔；Everything 的 `all` 搜它索引的所有卷 |
83
+ | `maxResults` | `20` | 默认结果上限；硬上限 100 |
84
+ | `timeoutMs` | `30000` | 单次调用超时预算；仅 profile YAML |
85
+ | `readMaxChars` | `8000` | `local_search_read` 默认窗口；硬上限 20,000 字符 |
86
+ | `esEncoding` | `gbk` | `es.exe` 输出的代码页；页面上是 `gbk` / `utf-8` 的二选一控件 |
87
+
88
+ 示例：
89
+
90
+ ```yaml
91
+ - id: fishdivinity-local-search
92
+ name: '@fishdivinity/dsh-local-search'
93
+ config:
94
+ workRoot: 'D:\Projects'
95
+ personalRoot: 'D:\Documents'
96
+ allRoots: 'C:\;D:\'
97
+ ```
98
+
99
+ ## Scope
100
+
101
+ - `workspace`（默认）：会话工作目录。
102
+ - `work`：`workRoot`。
103
+ - `personal`：`personalRoot`。
104
+ - `all`：Anytxt 用 `allRoots`；Everything 搜所有已索引卷。
105
+
106
+ 只有用户明确说“全盘/跨盘”时才用 `all`；`path` 参数可覆盖 `scope`。
107
+
108
+ ## 引擎选择
109
+
110
+ `engine` 默认 `auto`：
111
+
112
+ - `local_search_files`：`auto` / `everything`。
113
+ - `local_search_content` / `fragments` / `read`：`auto` / `anytxt`。
114
+ - `local_search_status`：`auto` / `everything` / `anytxt`。
115
+
116
+ 以后加引擎时工具名不变，只增加 `engine` 取值。内容结果同时带 `engine` 和自描述的 `ref`（如 `anytxt:123`）；把 `ref` 原样传给 `local_search_fragments` / `local_search_read`，`engine` 只作为校验用。
117
+
118
+ ## 错误码
119
+
120
+ | code | 含义 |
121
+ |---|---|
122
+ | `EVERYTHING_ES_NOT_FOUND` | 找不到 `es.exe`；安装或配置 `esPath` |
123
+ | `EVERYTHING_DOWN` | Everything 没运行/不可达 |
124
+ | `EVERYTHING_TIMEOUT` / `EVERYTHING_TOO_LARGE` | 查询太宽或太慢；缩小范围 |
125
+ | `ANYTXT_DOWN` | Anytxt GUI 没运行或 JSON-RPC 不可达 |
126
+ | `ANYTXT_TIMEOUT` / `ANYTXT_RPC` / `ANYTXT_HTTP` | Anytxt 侧查询/传输失败 |
127
+ | `ROOT_NOT_FOUND` / `SCOPE_NOT_CONFIGURED` / `INVALID_SCOPE` | 根目录/scope 配置问题 |
128
+ | `INVALID_ARGUMENT` | 空查询、非法 limit 等 |
129
+
130
+ 搜到 `*_DOWN` 时回退 `grep`/`glob`，并说明已回退。
131
+
132
+ ## 安全与限制
133
+
134
+ - **只读**：没有写、删、索引同步、OCR、导出、改设置等操作。
135
+ - `es.exe` 固定 argv，模型文本永远在 `--` 之后；`-export-*`、`-save-settings`、`-clear-settings`、`-exit`、`-reindex`、`-save-db`、run-count 不可达。
136
+ - Anytxt 只调 `Search` / `GetResult` / `GetFragmentAll` / `GetRawTextByFID`。
137
+ - 除本地 Anytxt 地址外不联网；结果有上限；`local_search_read` 截断。
138
+ - 插件以用户权限运行，能读用户能读的文件；默认 `scope=workspace`，不要无故全盘。
139
+
140
+ ## 已知限制
141
+
142
+ - 仅 Windows。
143
+ - Everything 1.4 只索引元数据，不索引文件内容；内容检索靠 Anytxt。
144
+ - Anytxt 的 JSON-RPC 是本地非官方接口，GUI 版本可能变；插件对不可达/结构不符会明确报错。
145
+ - Anytxt 索引可能滞后；重要命中要用 `read`/原文件复核。
146
+ - 不自动启动 `ATGUI.exe`（启动会写索引），由用户手动控制。
147
+ - Anytxt 条款限个人/非商业使用；商用需单独授权。
148
+
149
+ ## 开发
150
+
151
+ 无运行时依赖，测试用 Node 内置 test runner：
152
+
153
+ ```powershell
154
+ npm test
155
+ npm run check
156
+ npm run pack:check
157
+ ```
158
+
159
+ 引擎与配置模块（`lib/everything.js`、`lib/anytxt.js`、`lib/roots.js`、`lib/format.js`、`lib/config.js`）不依赖 DSH runtime，可在普通 Node 下测试。`lib/client.js` 是随包发布的浏览器半：直接按客户端模块系统的 lazy-CJS factory 格式手写成最终产物，没有构建步骤。架构与扩展见 [`docs/architecture.md`](docs/architecture.md)、[`docs/extending-engines.md`](docs/extending-engines.md)。
160
+
161
+ ## Changelog
162
+
163
+ 见 [CHANGELOG.md](CHANGELOG.md)。它保留在仓库里；npm tarball 只带运行时文件、README、LICENSE、locale 和 icon。
164
+
165
+ ## 许可证
166
+
167
+ MIT。Everything 与 Anytxt 是独立产品，各有自己的许可与商标；本项目与 voidtools、CBEWIN 无隶属关系。