dsh-everything 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.3.1] - 2026-10-27
+
+### Fixed
+- Multi-word queries (`*.docx dm:thisweek`) silently returned 0 results: the
+  whole query string was handed to es.exe as ONE argument, which Everything
+  then matched literally. Queries are now tokenized on whitespace (outside
+  double quotes) and each term is passed as its own argument, restoring AND
+  semantics. Quoted phrases without spaces keep their phrase meaning; quoted
+  phrases containing spaces degrade to ANDed words (es.exe cannot express
+  them positionally — use `regex=true` for exact multi-word matching).
+- Non-ASCII file names came back as mojibake (`?????`): es.exe pipes results
+  in the console/ANSI codepage, not UTF-8. Results are now read from es.exe's
+  UTF-8 `-export-json` file instead, so Chinese/Japanese/emoji names survive
+  the round trip on every codepage (with a decoded-stdout fallback for es.exe
+  builds without `-export-json`).
+
 ## [1.3.0] - 2026-10-26
 
 ### Added

package/README.md

@@ -37,16 +37,18 @@ Start-Process "C:\Program Files\Everything\Everything.exe"
 In a DSH session, ask the agent or call the plugin manager:
 
 ```
-plugin_manager install_bundle with target = this package directory (or the npm spec once published)
+plugin_manager install_bundle with target = dsh-everything
 ```
 
 The plugin activates as `dsh-everything` and registers the `everything_search` tool for every agent in the profile.
 
+Published on npm as [`dsh-everything`](https://www.npmjs.com/package/dsh-everything); installing from the package directory works too.
+
 ## Tool: `everything_search`
 
 | Parameter | Type | Description |
 |---|---|---|
-| `query` *(required)* | string | Everything search expression: `report ext:docx`, `*.sln dm:thisweek`, `path:\projects\ ext:py`. Space = AND, `\|` = OR, `!` = NOT, quotes = exact phrase. |
+| `query` *(required)* | string | Everything search expression: `report ext:docx`, `*.sln dm:thisweek`, `path:\projects\ ext:py`. Space = AND, `\|` = OR, `!` = NOT. Multi-word queries are split into es.exe terms automatically. |
 | `path` | string | Restrict to a directory and its subtree (absolute path). |
 | `maxResults` | integer | Result cap (default 100, ceiling 1000). |
 | `offset` | integer | Skip leading results (pagination). |
@@ -62,6 +64,9 @@ Returns `{ query, total, truncated, results: [{ path, size, dateModified, dateCr
 
 Typical queries: `report ext:docx` · `*.sln dm:thisweek` · `size:>500mb` · `notes !archive` · recently changed files with `sort: date-modified-descending` + `dm:thisweek`.
 
+> **Phrase quirks:** a quoted phrase only matches the *name* part, so `"report.docx"` matches nothing — pass it unquoted. Phrases containing spaces cannot be expressed through the es.exe CLI (they degrade to ANDed words); use `regex=true` for exact multi-word matching.
+> **Encoding:** results are read from es.exe's UTF-8 `-export-json` output, so non-ASCII file names (Chinese, Japanese, emoji, …) survive the round trip intact.
+
 > **Scope note:** searches names and paths only, never file contents — content search stays with `grep`.
 > **Coverage note:** results follow the local Everything index — NTFS/reFS drives and folders explicitly added to the index. FAT/exFAT removable drives and network shares are typically not covered.
 

package/README.zh-CN.md

@@ -34,19 +34,19 @@ Start-Process "C:\Program Files\Everything\Everything.exe"
 
 ## 安装
 
-在 DSH 会话中让插件管理器安装本包目录（或发布后的 npm 包名）：
+在 DSH 会话中让插件管理器安装 npm 包名：
 
 ```
-plugin_manager install_bundle，target = 本包目录的绝对路径
+plugin_manager install_bundle，target = dsh-everything
 ```
 
-插件以 `dsh-everything` 激活，并为该 profile 下的所有 Agent 注册 `everything_search` 工具。
+插件以 `dsh-everything` 激活，并为该 profile 下的所有 Agent 注册 `everything_search` 工具。已发布到 npm（[`dsh-everything`](https://www.npmjs.com/package/dsh-everything)），直接用本包目录安装也可以。
 
 ## 工具：everything_search
 
 | 参数 | 类型 | 说明 |
 |---|---|---|
-| `query` *（必填）* | string | Everything 搜索表达式：`report ext:docx`、`*.sln dm:thisweek`、`path:\projects\ ext:py`。空格 = 与，`\|` = 或，`!` = 非，双引号 = 精确短语。 |
+| `query` *（必填）* | string | Everything 搜索表达式：`report ext:docx`、`*.sln dm:thisweek`、`path:\projects\ ext:py`。空格 = 与，`\|` = 或，`!` = 非。多词查询会自动拆分为 es.exe 的独立搜索词。 |
 | `path` | string | 限定在某目录及其子目录内（绝对路径）。 |
 | `maxResults` | integer | 返回条数上限（默认 100，封顶 1000）。 |
 | `offset` | integer | 跳过前 N 条（分页）。 |
@@ -62,6 +62,9 @@ plugin_manager install_bundle，target = 本包目录的绝对路径
 
 典型查询：`report ext:docx` · `*.sln dm:thisweek` · `size:>500mb` · `notes !archive` · 最近改动文件用 `sort: date-modified-descending` + `dm:thisweek`。
 
+> **短语怪癖**：带引号的短语只匹配文件名的“名字部分”，所以 `"report.docx"` 永远搜不到——直接写不带引号的 `report.docx`。含空格的短语无法经 es.exe CLI 表达（会退化为逐词 AND）；需要精确多词匹配请用 `regex=true`。
+> **编码**：结果改从 es.exe 的 UTF-8 `-export-json` 输出读取，非 ASCII 文件名（中文、日文、emoji 等）完整回传、不再乱码。
+
 > **范围说明**：只搜文件名和路径，不搜文件内容——内容搜索请继续用 `grep`。
 > **覆盖说明**：结果取决于本机 Everything 索引——NTFS/reFS 磁盘与显式加入索引的目录；FAT/exFAT 可移动盘与网络共享通常不在覆盖范围。
 

package/index.js

@@ -2,8 +2,9 @@
  * dsh-everything: model-facing `everything_search` tool backed by the local
  * Everything (voidtools) index through the official ES command line (es.exe).
  *
- * The tool spawns es.exe with a fixed argv vector (no shell layer), parses its
- * `-json` output, and projects results onto the built-in search-paths card.
+ * The tool spawns es.exe with a fixed argv vector (no shell layer), reads its
+ * results from a UTF-8 `-export-json` file (immune to console codepages), and
+ * projects results onto the built-in search-paths card.
  * No external npm dependencies. Windows only: Everything itself is a Windows
  * application, so on other platforms a stub tool is registered that fails with
  * a clear platform message instead of a confusing spawn error.
@@ -18,8 +19,9 @@
  *   timeoutMs      per-spawn timeout in milliseconds (default: 8000)
  */
 import { execFile, spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { win32 as win32path } from 'node:path';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join as joinPath, win32 as win32path } from 'node:path';
 import { ensureBackend, EverythingError } from './setup.js';
 
 const DEFAULT_MAX_RESULTS = 100;
@@ -64,7 +66,7 @@ function resolveEverythingPath(config, esPath) {
   return 'Everything.exe';
 }
 
-/** Run es.exe once and resolve with its raw stdout. Errors are classified into actionable codes. */
+/** Run es.exe once and resolve with its raw stdout Buffer. Errors are classified into actionable codes. */
 function runEs(esPath, argv, timeoutMs, signal) {
   return new Promise((resolve, reject) => {
     let child;
@@ -72,7 +74,7 @@ function runEs(esPath, argv, timeoutMs, signal) {
       child = execFile(
         esPath,
         argv,
-        { timeout: timeoutMs, maxBuffer: MAX_BUFFER, windowsHide: true, signal },
+        { timeout: timeoutMs, maxBuffer: MAX_BUFFER, windowsHide: true, signal, encoding: 'buffer' },
         (error, stdout, stderr) => {
           const stderrText = typeof stderr === 'string' ? stderr.trim() : '';
           if (error) {
@@ -104,7 +106,7 @@ function runEs(esPath, argv, timeoutMs, signal) {
             reject(new EverythingError('everything_search: Everything is not running.', 'ES_NOT_RUNNING'));
             return;
           }
-          resolve(typeof stdout === 'string' ? stdout : '');
+          resolve(stdout); // Buffer (execFile encoding: 'buffer')
         }
       );
     } catch (error) {
@@ -146,6 +148,84 @@ async function autoStartEverything(everythingPath, esPath, signal) {
   throw new EverythingError('everything_search: Everything was started but did not answer within 15s; retry the search.', 'ES_NOT_RUNNING');
 }
 
+/**
+ * Split an Everything search expression into es.exe search terms.
+ *
+ * es.exe takes each command-line argument as ONE search term; an argument
+ * that itself contains a space is matched literally and never matches, so
+ * `*.docx dm:thisweek` MUST be passed as two arguments. Quoted phrases
+ * without spaces keep their quotes (phrase semantics); a quoted phrase that
+ * contains a space cannot be expressed positionally, so it degrades to its
+ * component words ANDed together (use regex=true for exact multi-word
+ * matching).
+ */
+function tokenizeQuery(query) {
+  const tokens = [];
+  let current = '';
+  let inQuotes = false;
+  const flush = () => {
+    if (current.length === 0) return;
+    if (/\s/.test(current)) {
+      // Only reachable for a quoted phrase with internal spaces: es.exe cannot
+      // take it as one term, so degrade to its component words (quotes stripped).
+      for (const word of current.split(/\s+/)) {
+        const bare = word.replace(/"/g, '');
+        if (bare.length > 0) tokens.push(bare);
+      }
+    } else if (current.replace(/"/g, '').length > 0) {
+      tokens.push(current);
+    }
+    current = '';
+  };
+  for (const ch of query) {
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      current += ch;
+    } else if (!inQuotes && /\s/.test(ch)) {
+      flush();
+    } else {
+      current += ch;
+    }
+  }
+  flush();
+  return tokens;
+}
+
+/** Decode es.exe stdout: it emits the console/ANSI codepage, not UTF-8. */
+function decodeEsStdout(buf) {
+  if (!buf || buf.length === 0) return '';
+  const utf8 = buf.toString('utf8');
+  if (!utf8.includes('\uFFFD')) return utf8;
+  try {
+    return new TextDecoder('gbk').decode(buf);
+  } catch {
+    return utf8;
+  }
+}
+
+let exportFileCounter = 0;
+
+/**
+ * Read the UTF-8 file written by `es.exe -export-json <file>`.
+ * The file occasionally exists but is still empty right after the process
+ * exits (flush race), so an empty read is retried briefly.
+ * Returns { exists, text } — `exists: false` lets the caller fall back to
+ * decoding stdout (e.g. an es.exe build that ignores -export-json).
+ */
+function readExportText(filePath) {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const text = readFileSync(filePath, 'utf8');
+      if (text.length > 0) return { exists: true, text: text.replace(/^\uFEFF/, '') };
+    } catch {
+      return { exists: false, text: '' };
+    }
+    // exists but empty: brief wait for the flush race
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+  }
+  return { exists: true, text: '' };
+}
+
 /**
  * Shared search flag vector (everything except output formatting and result
  * window). NOTE: `-regex` consumes the search text as its own value, so the
@@ -166,7 +246,13 @@ function buildSearchFlags(args, query) {
     argv.push('-sort', sort);
   }
   if (args.regex === true) argv.push('-regex', query);
-  else argv.push(query);
+  else {
+    const terms = tokenizeQuery(query);
+    if (terms.length === 0) {
+      throw new EverythingError('everything_search: "query" must contain at least one search term (not only quotes or whitespace).', 'ES_INVALID_ARGS');
+    }
+    argv.push(...terms);
+  }
   return argv;
 }
 
@@ -286,7 +372,7 @@ const PARAMETERS_SCHEMA = {
 };
 
 const TOOL_DESCRIPTION =
-  'Locate files and folders across every indexed drive on this machine through the local Everything (voidtools) index — answers in milliseconds, far faster than glob or a recursive directory scan. Use this FIRST whenever you need to find a file or folder by name, extension, or path, especially outside the workspace. The query uses Everything search syntax, not a glob: plain words match names, `*`/`?` wildcards, `ext:js;ts` filters extensions, `dm:today` / `dm:thisweek` filter date modified, `size:>10mb` filters size, space means AND, `|` means OR, `!` means NOT, double quotes give an exact phrase (avoid combining quoted phrases with modifiers such as ext:). Combine sort="date-modified-descending" with dm:thisweek for recently changed files, or sort="size-descending" to find the biggest ones first. Restrict scope with the dedicated path parameter rather than a path: prefix inside query. Set regex=true for a full regular expression over the whole path, countOnly=true for a fast match count without paths, dateCreated=true to also return creation dates. Returns absolute paths with size and date modified. Names and paths only, never file contents — use grep for content. Coverage follows the local Everything index: NTFS/reFS drives and explicitly added folders; FAT/exFAT removable drives and network shares are typically not indexed.';
+  'Locate files and folders across every indexed drive on this machine through the local Everything (voidtools) index — answers in milliseconds, far faster than glob or a recursive directory scan. Use this FIRST whenever you need to find a file or folder by name, extension, or path, especially outside the workspace. The query uses Everything search syntax, not a glob: plain words match names, `*`/`?` wildcards, `ext:js;ts` filters extensions, `dm:today` / `dm:thisweek` filter date modified, `size:>10mb` filters size, space means AND, `|` means OR, `!` means NOT. Two quoting quirks: do NOT quote a filename-with-extension like "report.docx" — quoted phrases only match the name part, so pass it unquoted; and quoted phrases must not contain spaces (use regex=true for exact multi-word matching). Combine sort="date-modified-descending" with dm:thisweek for recently changed files, or sort="size-descending" to find the biggest ones first. Restrict scope with the dedicated path parameter rather than a path: prefix inside query. Set regex=true for a full regular expression over the whole path, countOnly=true for a fast match count without paths, dateCreated=true to also return creation dates. Returns absolute paths with size and date modified; non-ASCII names come back intact. Names and paths only, never file contents — use grep for content. Coverage follows the local Everything index: NTFS/reFS drives and explicitly added folders; FAT/exFAT removable drives and network shares are typically not indexed.';
 
 const OUTPUT_SCHEMA = {
   type: 'object',
@@ -416,8 +502,34 @@ export function apply(ctx, config = {}) {
     if (input.dateCreated === true) searchArgv.push('-dc');
     if (offset > 0) searchArgv.push('-viewport-offset', String(offset));
     searchArgv.push(...flags);
-    const stdout = await runEsWithRetry(searchArgv, signal);
-    return { flags, results: parseResults(stdout) };
+
+    // Primary path: es.exe writes results to a UTF-8 file. Piping stdout
+    // instead emits the ANSI codepage and mangles non-ASCII names (GBK on a
+    // zh-CN machine, question marks elsewhere).
+    const exportPath = joinPath(tmpdir(), `dsh-everything-${process.pid}-${Date.now()}-${++exportFileCounter}.json`);
+    try {
+      let stdoutBuf;
+      try {
+        stdoutBuf = await runEsWithRetry([...searchArgv, '-export-json', exportPath], signal);
+      } catch (error) {
+        // es.exe builds that reject the option: retry once in stdout mode.
+        if (!(error instanceof EverythingError) || error.code !== 'ES_FAILED' || !/export|unknown|invalid|option/i.test(error.message ?? '')) throw error;
+        stdoutBuf = await runEsWithRetry(searchArgv, signal);
+        return { flags, results: parseResults(decodeEsStdout(stdoutBuf)) };
+      }
+      const exported = readExportText(exportPath);
+      if (!exported.exists) {
+        // No file written: an es.exe that ignores the option printed to stdout.
+        return { flags, results: parseResults(decodeEsStdout(stdoutBuf)) };
+      }
+      return { flags, results: parseResults(exported.text) };
+    } finally {
+      try {
+        unlinkSync(exportPath);
+      } catch {
+        /* best effort */
+      }
+    }
   }
 
   async function execute(args, exec) {
@@ -447,7 +559,7 @@ export function apply(ctx, config = {}) {
     if (results.length === limit) {
       try {
         const countOut = await runEs(esPath, ['-get-result-count', ...flags], timeoutMs, signal);
-        const parsed = Number.parseInt(countOut.trim(), 10);
+        const parsed = Number.parseInt(String(countOut).trim(), 10);
         if (Number.isFinite(parsed) && parsed >= total) total = parsed;
       } catch {
         /* count is cosmetic; keep the page-based estimate */
@@ -482,10 +594,12 @@ export function apply(ctx, config = {}) {
 export {
   buildSearchFlags,
   clampInt,
+  decodeEsStdout,
   formatSize,
   parseResults,
   presentCall,
   presentResult,
   renderResults,
   resolveEsPath,
+  tokenizeQuery,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-everything",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "DeepSeek Harness plugin: millisecond whole-disk file search for agents via the local Everything (voidtools) index",
   "keywords": ["dsh", "deepseek-harness", "everything", "voidtools", "file-search", "agent-tool"],
   "license": "MIT",