@fishdivinity/dsh-local-search 0.2.1 → 0.3.0

package/lib/config.js

@@ -1,47 +1,187 @@
 /**
- * Config access shared by activation and every tool call.
+ * 配置的路径表、默认值与读取规则，activate 与每次工具调用共用。
  *
- * The fields the Plugins page may edit are declared `.volatile()` in the
- * schema, so the Host hands `apply` a live reference instead of the value
- * frozen at activation. A save on the page updates that reference in place;
- * only `get()` sees it. Nothing downstream may keep such a reference, so every
- * operation starts from {@link readConfig}'s plain snapshot.
+ * 页面能改的字段都在 schema 里标了 `.volatile()`，Host 传给 `apply` 的因此是活引用而不是
+ * 激活时冻结的值；页面保存只改引用本身，只有 `get()` 看得到。下游任何模块都不许留着这种
+ * 引用，所以每个操作都从 {@link readConfig} 的纯快照出发。
  *
- * `timeoutMs` is deliberately not in {@link LIVE_KEYS}: `defineTool` fixes each
- * tool's deadline when the tool is registered, so a new value could not take
- * effect without reloading the row. It stays a profile-YAML setting.
+ * 路径只在这里写一遍：schema（`lib/schema.js`）、页面描述（`lib/describe.js`）、迁移与
+ * 自动配置都从 {@link PATHS} 取，避免同一串键名散落在四处。退役的旧路径是另一张表
+ * （{@link RETIRED_PATHS}）：只追加、不改写，规则见 `docs/config-migration.md`。
+ *
+ * `timeoutMs` 故意不在 {@link PATHS} 里：`defineTool` 在注册时就固定了每个工具的截止时间，
+ * 新值不重新加载那一行不会生效，所以它只能是 profile YAML 的设置。
  */
 
-/** Config keys the Plugins page edits. */
-export const LIVE_KEYS = [
-  'esPath',
-  'esEncoding',
-  'anytxtUrl',
-  'workspaceRoot',
-  'workRoot',
-  'personalRoot',
-  'allRoots',
-  'maxResults',
-  'readMaxChars',
+/** 可编辑字段的嵌套路径；键名是代码里的称呼，值是配置里的位置。 */
+export const PATHS = {
+  filesBackend: ['files', 'backend'],
+  esPath: ['files', 'everything', 'esPath'],
+  esEncoding: ['files', 'everything', 'esEncoding'],
+  contentBackend: ['content', 'backend'],
+  anytxtUrl: ['content', 'anytxt', 'url'],
+  workspaceRoot: ['scopes', 'workspaceRoot'],
+  workRoot: ['scopes', 'workRoot'],
+  personalRoot: ['scopes', 'personalRoot'],
+  allRoots: ['scopes', 'allRoots'],
+  maxResults: ['limits', 'maxResults'],
+  readMaxChars: ['limits', 'readMaxChars'],
+  autoConfigured: ['autoConfigured'],
+}
+
+/**
+ * 字段默认值。schema 从这里取默认值，`readConfig` 也用它补齐缺失层级，
+ * 所以一份不完整的 profile 不会读出一堆 `undefined`。
+ */
+export const DEFAULTS = {
+  files: { backend: 'everything', everything: { esPath: '', esEncoding: 'gbk' } },
+  content: { backend: 'anytxt', anytxt: { url: 'http://127.0.0.1:9920' } },
+  scopes: { workspaceRoot: '', workRoot: '', personalRoot: '', allRoots: '' },
+  limits: { maxResults: 20, readMaxChars: 8000 },
+  // 首用自动配置是否已经做过决定：写死之后，用户清空的字段不会再被自动填回去。
+  autoConfigured: false,
+  timeoutMs: 30000,
+}
+
+/**
+ * 已退役的路径 → 现在的位置。
+ *
+ * **一条 = 一次形状变更**，按发布顺序追加，永远不删、不改号；`from` 写当时的字面路径（不引用
+ * {@link PATHS}），否则将来改 PATHS 会把这行历史一起改掉。三条消费方都只读这张表：读取兜底
+ * （{@link readConfig}）、schema 里那几个隐藏的旧键（`lib/schema.js`）、启动迁移
+ * （`lib/bootstrap.js`）。规则与取舍见 `docs/config-migration.md`。
+ *
+ * 0.1 与 0.2 用的是同一批扁平键，所以这一条同时覆盖「0.1 直装 0.3」。
+ */
+export const RETIRED_PATHS = [
+  { from: ['esPath'], to: PATHS.esPath },
+  { from: ['esEncoding'], to: PATHS.esEncoding },
+  { from: ['anytxtUrl'], to: PATHS.anytxtUrl },
+  { from: ['workspaceRoot'], to: PATHS.workspaceRoot },
+  { from: ['workRoot'], to: PATHS.workRoot },
+  { from: ['personalRoot'], to: PATHS.personalRoot },
+  { from: ['allRoots'], to: PATHS.allRoots },
+  { from: ['maxResults'], to: PATHS.maxResults },
+  { from: ['readMaxChars'], to: PATHS.readMaxChars },
 ]
 
 /**
- * Read a value that may still be a live volatile reference.
- * @param {unknown} value - plain value, or a reference carrying `get()`
- * @returns {unknown} the current value
+ * 读一个可能仍是活引用的值。
+ * @param {unknown} value - 普通值，或带 `get()` 的引用
+ * @returns {unknown} 当前值
  */
 export function liveValue(value) {
   return typeof value?.get === 'function' ? value.get() : value
 }
 
 /**
- * Snapshot the whole config as plain values.
- * @param {object} config - schema output, volatile references included
- * @returns {object} plain values for this operation
+ * 沿路径取一个值。
+ * @param {object} object - 根对象，可为 undefined
+ * @param {string[]} path - 键名路径
+ * @returns {unknown} 命中值，或 undefined
+ */
+export function pathValue(object, path) {
+  let node = object
+  for (const key of path) {
+    if (node === null || typeof node !== 'object') return undefined
+    // 逐层解引用：schema 把 volatile 标在叶子上，但一份被外部包装过的配置可能整棵都是引用。
+    node = liveValue(node[key])
+  }
+  return node
+}
+
+/**
+ * 沿路径写一个值，中间层级按需创建。
+ * @param {object} object - 将被就地修改的根对象
+ * @param {string[]} path - 键名路径
+ * @param {unknown} value - 要写入的值
+ */
+export function setPath(object, path, value) {
+  let node = object
+  for (const key of path.slice(0, -1)) {
+    if (node[key] === null || typeof node[key] !== 'object') node[key] = {}
+    node = node[key]
+  }
+  node[path.at(-1)] = value
+}
+
+/**
+ * 路径是否由该层自己提供的键组成（不看继承值）。
+ * @param {object} object - 根对象，可为 undefined
+ * @param {string[]} path - 键名路径
+ * @returns {boolean} 每一层都显式带这个键时为 true
+ */
+export function hasPath(object, path) {
+  let node = object
+  for (const key of path) {
+    if (node === null || typeof node !== 'object' || !Object.prototype.hasOwnProperty.call(node, key)) return false
+    node = node[key]
+  }
+  return true
+}
+
+/** 深拷贝一份默认值，免得调用方改到共享常量。 */
+function defaults() {
+  return structuredClone(DEFAULTS)
+}
+
+/**
+ * 这个路径上的值算不算「还没设过」：缺失、空串，或仍等于默认值。
+ *
+ * 中间路径（上一版的位置）在 {@link DEFAULTS} 里没有记录，那时只有缺失与空串算没设过。
+ */
+function isUnset(snapshot, path) {
+  const value = pathValue(snapshot, path)
+  if (value === undefined || value === null) return true
+  if (typeof value === 'string' && value.trim() === '') return true
+  const fallback = pathValue(DEFAULTS, path)
+  return fallback !== undefined && String(value) === String(fallback)
+}
+
+/**
+ * 把退役路径上的值按发布顺序折进快照。
+ *
+ * 顺序就是执行顺序：更早的一次迁移先把值放到它的 `to`（对今天来说是中间位置），后一次再从
+ * 那里搬到当前路径。所以「0.1 直装 1.0」不需要中间版本存在过——这条链在同一次启动里跑完。
+ * @param config - schema 输出，含活引用
+ * @param snapshot - 已经按当前路径填过的快照，会被就地修改
+ * @param retired - 退役路径表，测试可注入
+ * @returns 快照与被旧路径填过的当前路径（点分）
+ */
+export function foldRetired(config, snapshot = defaults(), retired = RETIRED_PATHS) {
+  const filled = []
+  for (const { from, to } of retired) {
+    // 先看 profile 里的旧路径，再看快照：链上更早的一次迁移会把值放在快照的中间路径上。
+    let value = pathValue(config, from)
+    if (value === undefined || value === null) value = pathValue(snapshot, from)
+    if (value === undefined || value === null) continue
+    if (typeof value === 'string' && value.trim() === '') continue
+    if (!isUnset(snapshot, to)) continue
+    setPath(snapshot, to, value)
+    filled.push(to.join('.'))
+  }
+  return { snapshot, filled }
+}
+
+/**
+ * 当前结构 + 退役路径折过之后的快照。
+ *
+ * 读侧只是兜底：旧键上恰好等于默认值也不影响结果（同一个值）。要防的是迁移把它当成用户写的值
+ * 写回 profile——那件事在 `lib/bootstrap.js` 里按**用户层**判定，不靠这里。
+ * @param {object} config - schema 输出，含活引用
+ * @returns {object} 本次操作可用的纯值
  */
 export function readConfig(config) {
-  const snapshot = {}
-  for (const key of [...LIVE_KEYS, 'timeoutMs']) snapshot[key] = liveValue(config[key])
+  const snapshot = defaults()
+  for (const path of Object.values(PATHS)) {
+    const value = pathValue(config, path)
+    if (value !== undefined) setPath(snapshot, path, value)
+  }
+  // 退役路径只在目标位置还是默认值时补位：迁移成功后就清掉了，没清掉说明 settings 写不进去
+  // （home patch 覆盖），那时它仍是唯一来源。
+  foldRetired(config, snapshot)
+  const timeoutMs = liveValue(config?.timeoutMs)
+  if (timeoutMs !== undefined) snapshot.timeoutMs = timeoutMs
   return snapshot
 }
 
@@ -51,18 +191,23 @@ function assertPositiveInteger(field, value) {
   }
 }
 
-/** Hosts that name this machine. */
+function assertBackend(field, value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`dsh-local-search: ${field} must name a backend`)
+  }
+}
+
+/** 只认本机的 host 表。 */
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost'])
 
 /**
- * Whether a value is an `http(s)` URL that names this machine.
+ * 值是否是指向本机的 `http(s)` 地址。
  *
- * Both indexes describe the local machine: `es.exe` is spawned here, and every
- * Anytxt result carries a path that only resolves here. A remote endpoint would
- * answer with another machine's paths, so it is refused rather than supported —
- * tunnelling one in lands it on loopback anyway.
- * @param {unknown} value - candidate endpoint
- * @returns {boolean} true for a loopback `http(s)` URL
+ * 两个索引都描述这台机器：`es.exe` 在这里启动，Anytxt 的每条结果都带一个只在这里成立的
+ * 路径。远端地址会返回另一台机器的路径，因此拒绝而不是支持——把远端隧道进来最终仍落在
+ * loopback 上。
+ * @param {unknown} value - 待检查的地址
+ * @returns {boolean} 本机 `http(s)` 地址时为 true
  */
 export function isLoopbackUrl(value) {
   let parsed
@@ -76,24 +221,23 @@ export function isLoopbackUrl(value) {
 }
 
 /**
- * Validate a candidate config and return its plain snapshot. Run once at
- * activation; the page's writes are validated by the Host against the Config
- * schema before they are persisted, so the range checks that matter live there
- * (`lib/index.js`) and this function covers what the schema cannot express.
+ * 校验一份配置并返回它的纯快照。激活时跑一次；页面写入由 Host 按 Config schema 校验后才落盘，
+ * 所以这里只覆盖 schema 表达不了的部分。
  *
- * The endpoint's loopback rule is deliberately *not* enforced here. A profile
- * that 0.1 accepted must still activate: a wrong address should fail the content
- * engine with a readable error, not take file-name search down with it. The
- * rule lives where the endpoint is used (`lib/anytxt.js`).
- * @param {object} config - schema output, volatile references included
- * @param {number} [maxTimerDelayMs] - largest deadline the timer API accepts
- * @returns {object} the validated plain snapshot
+ * endpoint 的 loopback 规则故意不在这里执行。0.1 接受的 profile 必须还能激活：地址写错应该
+ * 让内容引擎报一个能读懂的错误，而不是把文件名检索一起拖下水。规则留在用到它的地方
+ * （`lib/anytxt.js`）。
+ * @param {object} config - schema 输出，含活引用
+ * @param {number} [maxTimerDelayMs] - 定时器 API 接受的最大截止时间
+ * @returns {object} 校验过的纯快照
  */
 export function validateConfig(config, maxTimerDelayMs) {
   const values = readConfig(config)
-  assertPositiveInteger('maxResults', values.maxResults)
+  assertBackend('files.backend', values.files.backend)
+  assertBackend('content.backend', values.content.backend)
+  assertPositiveInteger('limits.maxResults', values.limits.maxResults)
+  assertPositiveInteger('limits.readMaxChars', values.limits.readMaxChars)
   assertPositiveInteger('timeoutMs', values.timeoutMs)
-  assertPositiveInteger('readMaxChars', values.readMaxChars)
   if (maxTimerDelayMs !== undefined && values.timeoutMs > maxTimerDelayMs) {
     throw new Error(`dsh-local-search: timeoutMs must be no greater than ${maxTimerDelayMs}`)
   }

package/lib/describe.js

@@ -0,0 +1,157 @@
+/**
+ * 配置页的后端描述（`GET /dsh-local-search/api/describe`）。
+ *
+ * 页面不该知道世界上有 Everything 和 Anytxt：它只知道「有几个能力节、每节可选哪些后端、
+ * 选中后端后显示哪些字段」。这些事实由 Host 给，新增后端在 Host 注册表与这里各加一条，
+ * 页面逻辑不动；字段的措辞留在客户端字典里，这里只给键名。
+ *
+ * 能力名（文件名检索 / 文件内容检索）由客户端按语言取词，后端一律用产品名。
+ */
+
+import { DEFAULTS, PATHS } from './config.js'
+import { engineNames } from './engines.js'
+import { MAX_LIMIT, MAX_READ } from './limits.js'
+
+/**
+ * 页面那个统一的「重置」要做什么。
+ *
+ * 它等价于把首用自动配置重跑一遍：清掉引擎与上限、按探测结果把 `esPath` 与 Anytxt 地址填回去、
+ * 再盖上「已经做过决定」的标记。`scopes` 不在清空列表里——那是用户手填的机器路径，重置顺手抹掉
+ * 的代价太高。`default` 用来判断探到的值是否与默认一致，一致就不必写进 profile。
+ */
+const RESET = {
+  clear: [
+    PATHS.esPath,
+    PATHS.esEncoding,
+    PATHS.anytxtUrl,
+    PATHS.filesBackend,
+    PATHS.contentBackend,
+    PATHS.maxResults,
+    PATHS.readMaxChars,
+  ],
+  fills: [
+    { path: PATHS.esPath, from: 'everything.path' },
+    { path: PATHS.anytxtUrl, from: 'anytxt.url', default: DEFAULTS.content.anytxt.url },
+  ],
+  marker: PATHS.autoConfigured,
+}
+
+/** 后端的产品名在字典里的键；未收录的新后端直接显示注册表里的名字。 */
+const ENGINE_LABEL_KEYS = {
+  everything: 'engineEverything',
+  anytxt: 'engineAnytxt',
+}
+
+/**
+ * 每个后端自己的字段表。
+ *
+ * `path` 取 {@link PATHS}，不写字面量；`aliases` 让页面的二选一控件认旧标签（0.1 写过
+ * `utf8`，schema 至今仍接受任意 TextDecoder 标签）。
+ *
+ * 字段上这几个标记是 Host 与页面之间**唯一的暗号**，由页面据此决定渲染与校验，加字段时别漏：
+ * `verifyPath` / `verifyDir` 交给 Host 查存在性（不 spawn），`probeEndpoint` 是测试连接要探的地址，
+ * `localUrl` 要求本机 http(s)，`type: 'count'` 带 `max` 上限。
+ */
+const ENGINE_FIELDS = {
+  files: {
+    everything: [
+      {
+        path: PATHS.esPath,
+        type: 'text',
+        labelKey: 'esPathLabel',
+        hintKey: 'esPathHint',
+        // 保存前由 Host 只查「这个文件在不在」：跑一条任意路径等于开一个远程执行口。
+        verifyPath: true,
+      },
+      {
+        path: PATHS.esEncoding,
+        type: 'choice',
+        labelKey: 'esEncodingLabel',
+        hintKey: 'esEncodingHint',
+        choices: [
+          { value: 'gbk', labelKey: 'encodingGbk' },
+          { value: 'utf-8', labelKey: 'encodingUtf8' },
+        ],
+        aliases: { utf8: 'utf-8', utf: 'utf-8' },
+      },
+    ],
+  },
+  content: {
+    anytxt: [
+      {
+        path: PATHS.anytxtUrl,
+        type: 'text',
+        labelKey: 'anytxtUrlLabel',
+        hintKey: 'anytxtUrlHint',
+        localUrl: true,
+        probeEndpoint: true,
+      },
+    ],
+  },
+}
+
+/** 能力节：标题是能力，节内先选后端。 */
+const CAPABILITY_SECTIONS = [
+  { id: 'files', group: 'files', titleKey: 'sectionFiles', backendPath: PATHS.filesBackend },
+  { id: 'content', group: 'content', titleKey: 'sectionContent', backendPath: PATHS.contentBackend },
+]
+
+/** 与后端无关的节，留在页尾。 */
+const PLAIN_SECTIONS = [
+  {
+    id: 'scopes',
+    titleKey: 'sectionScopes',
+    fields: [
+      { path: PATHS.workspaceRoot, type: 'text', labelKey: 'workspaceRootLabel', hintKey: 'workspaceRootHint', verifyDir: true },
+      { path: PATHS.workRoot, type: 'text', labelKey: 'workRootLabel', hintKey: 'workRootHint', verifyDir: true },
+      { path: PATHS.personalRoot, type: 'text', labelKey: 'personalRootLabel', hintKey: 'personalRootHint', verifyDir: true },
+      { path: PATHS.allRoots, type: 'text', labelKey: 'allRootsLabel', hintKey: 'allRootsHint', verifyDir: true },
+    ],
+  },
+  {
+    id: 'limits',
+    titleKey: 'sectionLimits',
+    fields: [
+      { path: PATHS.maxResults, type: 'count', max: MAX_LIMIT, labelKey: 'maxResultsLabel', hintKey: 'maxResultsHint' },
+      { path: PATHS.readMaxChars, type: 'count', max: MAX_READ, labelKey: 'readMaxCharsLabel', hintKey: 'readMaxCharsHint' },
+    ],
+  },
+]
+
+/** 一个能力的后端列表，只列真正注册过的引擎。 */
+function backendsOf(group) {
+  return engineNames()[group].map((name) => {
+    const labelKey = ENGINE_LABEL_KEYS[name]
+    return labelKey === undefined ? { name } : { name, labelKey }
+  })
+}
+
+/** 一个能力的字段列表，标上它属于哪个后端。 */
+function fieldsOf(group) {
+  const fields = ENGINE_FIELDS[group] ?? {}
+  return engineNames()[group].flatMap((name) => (fields[name] ?? []).map((field) => ({ ...field, backend: name })))
+}
+
+/**
+ * 组装页面要渲染的结构。
+ * @param {object} [autoconfig] - 首用自动配置的进展，供页面决定是否提示引擎不可用
+ * @param {boolean} [autoconfig.ran] - 本次启动是否真的探测并写过配置
+ * @param {boolean} [autoconfig.pending] - 探测还没结束
+ * @param {Array<{engine: string, code: string}>} [autoconfig.failures] - 不可用的引擎
+ * @returns {object} describe 载荷
+ */
+export function describeConfig(autoconfig) {
+  const sections = [
+    ...CAPABILITY_SECTIONS.map(({ id, group, titleKey, backendPath }) => ({
+      id,
+      titleKey,
+      backendPath,
+      backends: backendsOf(group),
+      fields: fieldsOf(group),
+    })),
+    ...PLAIN_SECTIONS.map(({ id, titleKey, fields }) => ({ id, titleKey, fields })),
+  ]
+  const payload = { sections, reset: RESET }
+  if (autoconfig !== undefined) payload.autoconfig = autoconfig
+  return payload
+}

package/lib/engines.js

@@ -4,8 +4,8 @@ import { anytxtStatus, getFragments, getRawText, searchContent } from './anytxt.
 import { assertRefEngine, formatRef, parseRef } from './ref.js'
 
 /**
- * Engine registry. A new filename or content backend is one entry here plus
- * its module; the tool surface and `engine` values stay unchanged.
+ * 引擎注册表。新增一个文件名或内容后端 = 这里一条 + 它自己的模块；工具表面与 `engine` 的取值
+ * 都不用动。
  *
  * files:   { name, search(args), status(args) }
  * content: { name, search(args), fragments(args), read(args), status(args) }
@@ -19,7 +19,7 @@ const filesEngines = new Map([
       status: async (args) => ({
         ok: true,
         version: await getEsVersion(args),
-        path: resolveEsPath(args.config ?? {}),
+        path: resolveEsPath({ esPath: args.esPath }),
       }),
     },
   ],
@@ -66,17 +66,17 @@ function resolve(registry, kind, requested) {
   return engine
 }
 
-/** Resolve a filename engine; `auto` selects the first registered engine. */
+/** 解析文件名引擎；`auto` 取注册表里的第一个。 */
 export function resolveFilesEngine(requested = 'auto') {
   return resolve(filesEngines, 'files', requested)
 }
 
-/** Resolve a content engine; `auto` selects the first registered engine. */
+/** 解析内容引擎；`auto` 取注册表里的第一个。 */
 export function resolveContentEngine(requested = 'auto') {
   return resolve(contentEngines, 'content', requested)
 }
 
-/** Engine names for status output and future config pages. */
+/** 状态输出与配置页用的引擎名。 */
 export function engineNames() {
   return {
     files: [...filesEngines.keys()],

package/lib/errors.js

@@ -1,7 +1,6 @@
 /**
- * Engine-level error with a stable code. Kept independent of the DSH runtime
- * so engine modules and their unit tests can run under plain Node; the tool
- * layer converts these to `HarnessError` before returning to the model.
+ * 带稳定 code 的引擎层错误。刻意不依赖 DSH runtime，引擎模块与它们的单测才能裸跑在普通 Node
+ * 上；把它们转成 `HarnessError` 是工具层在返回模型之前做的事。
  */
 export class EngineError extends Error {
   /**

package/lib/everything.js

@@ -10,7 +10,7 @@ const EXCLUDED = [/\\\$RECYCLE\.BIN\\/i, /\\System Volume Information\\/i]
 
 let cachedEsPath
 
-/** Decode es.exe stdout using the console code page (GBK on zh-CN). */
+/** 按控制台代码页解码 es.exe 的 stdout（简中下是 GBK）。 */
 export function decodeEs(buffer, encoding = 'gbk') {
   try {
     return new TextDecoder(encoding).decode(buffer)
@@ -19,7 +19,7 @@ export function decodeEs(buffer, encoding = 'gbk') {
   }
 }
 
-/** Candidate es.exe locations, in priority order. */
+/** es.exe 的候选位置，按优先级排列。 */
 export function esCandidates() {
   const localAppData = process.env.LOCALAPPDATA || ''
   return [
@@ -29,7 +29,7 @@ export function esCandidates() {
   ].filter(Boolean)
 }
 
-/** Resolve es.exe from config, env, PATH, or common install directories. */
+/** 从配置、环境变量、PATH 或常见安装目录解析出 es.exe。 */
 export function resolveEsPath(config = {}) {
   if (config.esPath) {
     if (!existsSync(config.esPath)) {
@@ -59,14 +59,14 @@ export function resolveEsPath(config = {}) {
       return first
     }
   } catch {
-    // where.exe is unavailable or found nothing; fall through.
+    // where.exe 不可用或什么也没找到；继续往下走。
   }
   throw new EngineError('es.exe was not found', 'EVERYTHING_ES_NOT_FOUND', {
     hint: 'Install es.exe (https://www.voidtools.com/downloads/), add it to PATH, or set esPath in the plugin config.',
   })
 }
 
-/** Build the fixed, read-only es.exe argv. Model text is always after `--`. */
+/** 拼出固定、只读的 es.exe argv。模型给的文本永远放在 `--` 之后。 */
 export function buildEsArgs({ query, limit = 20, dir } = {}) {
   if (typeof query !== 'string' || query.trim().length === 0) {
     throw new EngineError('query must be a non-empty string', 'INVALID_ARGUMENT')
@@ -85,7 +85,7 @@ export function buildEsArgs({ query, limit = 20, dir } = {}) {
   return args
 }
 
-/** Run es.exe with a bounded buffer, timeout, and cancellation. */
+/** 带缓冲上限、超时与取消地跑 es.exe。 */
 export function runEsText(args, { esPath, timeoutMs = 15000, signal, encoding = 'gbk' } = {}) {
   return new Promise((resolve, reject) => {
     const executable = esPath || resolveEsPath({})
@@ -108,7 +108,7 @@ export function runEsText(args, { esPath, timeoutMs = 15000, signal, encoding =
       try {
         child?.kill()
       } catch {
-        // Process already gone.
+        // 进程已经没了。
       }
       finish(error)
     }
@@ -180,20 +180,19 @@ export function runEsText(args, { esPath, timeoutMs = 15000, signal, encoding =
 }
 
 /**
- * Whether an es.exe exit means "no answer" rather than "no match".
+ * es.exe 这次退出是「没有答案」还是「没有命中」。
  *
- * es.exe uses exit 1 both for "nothing matched" and for a failed connection, so
- * the code alone cannot decide; an empty stdout next to stderr text is the
- * failure, anything else is a result.
- * @param {number} code - the process exit code
- * @param {string} output - trimmed stdout
- * @returns true when the call produced no usable answer
+ * es.exe 对「什么也没匹配到」和「连接失败」都用 exit 1，光看 code 判不出来；stdout 为空而
+ * stderr 有内容才是失败，其余都算有结果。
+ * @param {number} code - 进程的退出码
+ * @param {string} output - 去掉首尾空白的 stdout
+ * @returns 这次调用没有拿到可用答案时为 true
  */
 export function isFailedExit(code, output) {
   return code !== 0 && (code !== 1 || output === '')
 }
 
-/** Parse es.exe `-json` output into rows, before any exclusion filter. */
+/** 把 es.exe 的 `-json` 输出解析成行，这一步在任何排除过滤之前。 */
 export function parseEsJson(text) {
   if (!text || text.trim().length === 0) return []
   let rows
@@ -217,15 +216,15 @@ export function parseEsJson(text) {
 }
 
 /**
- * Drop rows that live in an index we never surface.
- * @param {Array<{path: string}>} rows - parsed rows
- * @returns {Array<{path: string}>} the rows a tool may return
+ * 丢掉落在我们从不暴露的索引里的行。
+ * @param {Array<{path: string}>} rows - 已解析的行
+ * @returns {Array<{path: string}>} 工具可以返回的行
  */
 export function withoutExcludedPaths(rows) {
   return rows.filter((row) => !EXCLUDED.some((re) => re.test(row.path)))
 }
 
-/** Candidate Everything.exe locations, in priority order. */
+/** Everything.exe 的候选位置，按优先级排列。 */
 export function everythingCandidates() {
   const programFiles = process.env.ProgramFiles || 'C:\\Program Files'
   const programFilesX86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)'
@@ -233,13 +232,12 @@ export function everythingCandidates() {
 }
 
 /**
- * Whether Everything itself is installed, independent of es.exe.
+ * Everything 本身装了没有，与 es.exe 无关。
  *
- * `sc query` exits non-zero when the service is absent, which is the one signal
- * that survives a localized Windows console. An install outside Program Files
- * (or a portable one) is only found through that service, so a check that could
- * not run at all reports `known: false` instead of claiming "not installed".
- * @returns {{installed: boolean, via?: 'exe'|'service', known: boolean}} install evidence
+ * 服务不存在时 `sc query` 退出码非零，这是本地化的 Windows 控制台下唯一还立得住的信号。装在
+ * Program Files 之外（或便携版）只能靠那个服务找到，所以一个根本没能跑起来的检查报
+ * `known: false`，而不是断言「没装」。
+ * @returns {{installed: boolean, via?: 'exe'|'service', known: boolean}} 安装证据
  */
 export function everythingInstalled() {
   for (const candidate of everythingCandidates()) {
@@ -249,26 +247,25 @@ export function everythingInstalled() {
     execFileSync('sc.exe', ['query', 'Everything'], { encoding: 'utf8', windowsHide: true, timeout: 2000 })
     return { installed: true, via: 'service', known: true }
   } catch (error) {
-    // A numeric `status` means sc.exe ran and the service is absent; a spawn
-    // failure (EPERM, ENOENT) proves nothing about the machine.
+    // `status` 是数字说明 sc.exe 跑起来了、服务确实不在；spawn 失败（EPERM、ENOENT）说明不了
+    // 这台机器的任何事。
     const ran = typeof error?.status === 'number'
     return { installed: false, known: ran }
   }
 }
 
-/** Search file names/paths through Everything. */
+/** 通过 Everything 检索文件名/路径。 */
 export async function searchFiles({ query, dir, limit = 20, esPath, timeoutMs, signal, encoding } = {}) {
   const executable = esPath || resolveEsPath({})
   const args = buildEsArgs({ query, dir, limit })
   const text = await runEsText(args, { esPath: executable, timeoutMs, signal, encoding })
   const rows = parseEsJson(text)
-  // Truncation is decided on what es.exe returned, not on what survived the
-  // $RECYCLE.BIN filter: a capped page of excluded hits must not read as a
-  // plain "no files found".
+  // 截断按 es.exe 返回了什么来判，而不是按排除 $RECYCLE.BIN 之后剩下什么：一整页都被排除的
+  // 命中不能读成一句平平的 "no files found"。
   return { items: withoutExcludedPaths(rows), truncated: rows.length >= limit }
 }
 
-/** Read the running Everything version. */
+/** 读正在运行的 Everything 版本。 */
 export async function getEsVersion({ esPath, timeoutMs, signal, encoding } = {}) {
   const executable = esPath || resolveEsPath({})
   const text = await runEsText(['-get-everything-version'], { esPath: executable, timeoutMs, signal, encoding })