@fishdivinity/dsh-local-search 0.2.0 → 0.3.0

package/README-zh.md

@@ -45,7 +45,7 @@
 
 - Windows。
 - DeepSeek Harness `>=0.2.1-0 <0.3.0`。
-- Everything 正在运行，并安装 `es.exe`（voidtools 单独下载；插件会从 PATH/常见目录探测，也可配置 `esPath`）。
+- Everything 正在运行，并安装 `es.exe`（voidtools 单独下载；插件会从 PATH/常见目录探测，也可配置 `files.everything.esPath`）。
 - 内容检索需要 Anytxt Searcher 的 **GUI**（`ATGUI.exe`）在运行；JSON-RPC 服务在 GUI 进程里，只有 `ATService` 不够。
 
 插件不打包 Everything、`es.exe` 或 Anytxt，需自行安装并遵守各自许可。
@@ -66,24 +66,34 @@ dsh plugin --profile desktop add github:fishdivinity/dsh-local-search
 
 ## 配置
 
-侧边栏 **Plugins** → **Official plugins** 组里的「本地搜索」卡片 → 插件自己的页面。这张卡和 GitHub 插件那张是同一个形态。保存后对下一次工具调用生效；离开页面丢弃未保存改动，字段上的「重置」把它交回 profile 层。
+侧边栏 **Plugins** → **Official plugins** 组里的「本地搜索」卡片 → 插件自己的页面。这张卡和 GitHub 插件那张是同一个形态。保存后对下一次工具调用生效；离开页面丢弃未保存改动。描述下面那个**重置**会先把会清什么摆出来，确认后才清掉引擎与上限、按一次新的探测填回去；检索范围不动，因为那是你自己敲进去的路径。
 
-**测试连接**就放在 Anytxt 地址输入框下面，测的是**输入框里当前的地址**（不用先保存），同时把 Everything 一起探一遍，一行给结果。某个引擎不可用时会给出它的官方下载页；本插件不打包、不下载、也不代替你安装这两个程序。
+页面按能力组织：「文件名检索」与「文件内容检索」各以一行后端选择器开头，选中后展开该后端的字段；「检索范围」与「上限」与后端无关，收在页尾。分节、后端列表、字段类型与硬上限都由 Host 的 `GET /dsh-local-search/api/describe` 给出，页面只负责渲染，新增后端不用改页面逻辑。
+
+**测试连接**就放在 Anytxt 地址字段下面，测的是**输入框里当前的地址和 `es.exe` 路径**（不用先保存），同时把 Everything 一起探一遍：路径打错就直接说找不到文件，不会拿已保存的那个报「正常」。结果与修法在一个弹窗里，弹窗还能再测一次。某个引擎不可用时会给出它的官方下载页；本插件不打包、不下载、也不代替你安装这两个程序。
+
+**保存前会先校验。** 只要这次保存动了地址或 `es.exe` 路径，页面就先把它们探一遍：不通过就不写，弹窗问你要不要「仍然保存」——那是你明知的例外，而不是默认结果；路径上没有文件、目录不存在、地址被拒这类硬错没有强行写入的出口。路径那一项 Host 只查「文件在不在」，绝不启动请求里指定的文件。路径字段与 Anytxt 地址都在**失焦时**先校验一次：不存在、把目录填成文件、地址不是本机，都会在字段下面标红，改掉就收回。
+
+路径字段保存时会改成标准写法：`d:/alpha` 存成 `D:\alpha`（盘符大写、反斜杠、去掉末尾分隔符），`allRoots` 按分号逐项改；路径存在时还会按磁盘上的真实大小写写回（`d:/alpha` → `D:\Alpha`）。名字里的空格与中文不动——`D:\Alpha\我的项目\drawio a` 这样带空格的目录名照写就行，宿主按值传给 `es.exe` 与文件接口，不经过 shell。
+
+首用只补一次就停：`files.everything.esPath` 或 `content.anytxt.url` 还空着时，插件探一次、把能应答的写进去，并在隐藏键 `autoConfigured` 里记下这次已经做过决定。之后你清空的字段会保持空着，不会再被自动填回去。
 
 全部可选；row config 是整块替换，不会深合并。只有 `timeoutMs` 留在 profile 的 `cordis.patch.yml`：每个工具在注册时就固定截止时间，因此页面上不提供这个字段，免得出现“改了没反应”。
 
-| 字段 | 默认 | 说明 |
+| 键 | 默认 | 说明 |
 |---|---|---|
-| `esPath` | 自动探测 | `es.exe` 绝对路径。顺序：`esPath` → `ES_PATH` → 常见安装目录 → `where.exe` |
-| `anytxtUrl` | `http://127.0.0.1:9920` | 本机 Anytxt JSON-RPC 地址（只接受 `127.0.0.1`、`localhost`、`[::1]`）；默认还会尝试 `:9921` |
-| `workspaceRoot` | 会话默认目录 | `scope=workspace` 的根 |
-| `workRoot` | 空 | `scope=work` 的根；使用前必须配置 |
-| `personalRoot` | 空 | `scope=personal` 的根；使用前必须配置 |
-| `allRoots` | `C:\` + 存在时的 `D:\` | Anytxt `scope=all` 的根，分号分隔；Everything 的 `all` 搜它索引的所有卷 |
-| `maxResults` | `20` | 默认结果上限；硬上限 100 |
+| `files.backend` | `everything` | `auto` 使用的文件名后端 |
+| `files.everything.esPath` | 自动探测 | `es.exe` 绝对路径。顺序：配置值 → `ES_PATH` → 常见安装目录 → `where.exe` |
+| `files.everything.esEncoding` | `gbk` | 解码 `es.exe` 输出的代码页；接受任意 `TextDecoder` 标签，页面上是 `gbk` / `utf-8` 二选一 |
+| `content.backend` | `anytxt` | `auto` 使用的内容后端 |
+| `content.anytxt.url` | `http://127.0.0.1:9920` | 本机 Anytxt JSON-RPC 地址（只接受 `127.0.0.1`、`localhost`、`[::1]`）；默认还会尝试 `:9921` |
+| `scopes.workspaceRoot` | 会话默认目录 | `scope=workspace` 的根 |
+| `scopes.workRoot` | 空 | `scope=work` 的根；使用前必须配置 |
+| `scopes.personalRoot` | 空 | `scope=personal` 的根；使用前必须配置 |
+| `scopes.allRoots` | `C:\` + 存在时的 `D:\` | Anytxt `scope=all` 的根，分号分隔；Everything 的 `all` 搜它索引的所有卷 |
+| `limits.maxResults` | `20` | 默认结果上限；硬上限 100 |
+| `limits.readMaxChars` | `8000` | `local_search_read` 默认窗口；硬上限 20,000 字符 |
 | `timeoutMs` | `30000` | 单次调用超时预算；仅 profile YAML |
-| `readMaxChars` | `8000` | `local_search_read` 默认窗口；硬上限 20,000 字符 |
-| `esEncoding` | `gbk` | `es.exe` 输出的代码页；页面上是 `gbk` / `utf-8` 的二选一控件 |
 
 示例：
 
@@ -91,23 +101,27 @@ dsh plugin --profile desktop add github:fishdivinity/dsh-local-search
 - id: fishdivinity-local-search
   name: '@fishdivinity/dsh-local-search'
   config:
-    workRoot: 'D:\Projects'
-    personalRoot: 'D:\Documents'
-    allRoots: 'C:\;D:\'
+    scopes:
+      workRoot: 'D:\Projects'
+      personalRoot: 'D:\Documents'
+    limits:
+      maxResults: 50
 ```
 
+0.2 的 profile 不用手改：启动时那九个扁平键（`esPath`、`esEncoding`、`anytxtUrl`、`workspaceRoot`、`workRoot`、`personalRoot`、`allRoots`、`maxResults`、`readMaxChars`）会搬进上面的嵌套结构并清掉旧键。settings 写不进去时（profile 被 home patch 覆盖）旧键留在原地，读取仍然认它。
+
 ## Scope
 
 - `workspace`（默认）：会话工作目录。
-- `work`：`workRoot`。
-- `personal`：`personalRoot`。
-- `all`：Anytxt 用 `allRoots`；Everything 搜所有已索引卷。
+- `work`：`scopes.workRoot`。
+- `personal`：`scopes.personalRoot`。
+- `all`：Anytxt 用 `scopes.allRoots`；Everything 搜所有已索引卷。
 
 只有用户明确说“全盘/跨盘”时才用 `all`；`path` 参数可覆盖 `scope`。
 
 ## 引擎选择
 
-`engine` 默认 `auto`：
+`engine` 默认 `auto`，跟随该能力配置的后端：`local_search_files` 用 `files.backend`，`local_search_content` / `fragments` / `read` 用 `content.backend`。
 
 - `local_search_files`：`auto` / `everything`。
 - `local_search_content` / `fragments` / `read`：`auto` / `anytxt`。
@@ -119,7 +133,7 @@ dsh plugin --profile desktop add github:fishdivinity/dsh-local-search
 
 | code | 含义 |
 |---|---|
-| `EVERYTHING_ES_NOT_FOUND` | 找不到 `es.exe`；安装或配置 `esPath` |
+| `EVERYTHING_ES_NOT_FOUND` | 找不到 `es.exe`；安装或配置 `files.everything.esPath` |
 | `EVERYTHING_DOWN` | Everything 没运行/不可达 |
 | `EVERYTHING_TIMEOUT` / `EVERYTHING_TOO_LARGE` | 查询太宽或太慢；缩小范围 |
 | `ANYTXT_DOWN` | Anytxt GUI 没运行或 JSON-RPC 不可达 |
@@ -156,7 +170,7 @@ npm run check
 npm run pack:check
 ```
 
-引擎与配置模块（`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)。
+引擎与配置模块（`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)；改配置形状前先读 [`docs/config-migration.md`](docs/config-migration.md)。
 
 ## Changelog
 

package/README.md

@@ -46,7 +46,7 @@
 
 - Windows.
 - DeepSeek Harness `>=0.2.1-0 <0.3.0`.
-- [Everything](https://www.voidtools.com/) running, plus `es.exe` (a separate download from voidtools; the plugin auto-detects PATH/common install folders, or set `esPath`).
+- [Everything](https://www.voidtools.com/) running, plus `es.exe` (a separate download from voidtools; the plugin auto-detects PATH/common install folders, or set `files.everything.esPath`).
 - [Anytxt Searcher](https://anytxt.net/) for content search: the **GUI** (`ATGUI.exe`) must be running because the JSON-RPC service lives inside it. The indexing service alone is not enough.
 
 This plugin does **not** bundle Everything, `es.exe`, or Anytxt. Install and license them separately.
@@ -67,24 +67,34 @@ Restart the profile or open a new session. The five `local_search_*` tools appea
 
 ## Configuration
 
-Sidebar **Plugins** → the **Local Search** card in the **Official plugins** group → the plugin's own page. That is the same card shape the GitHub plugin contributes. Saves apply to the next tool call; leaving the page drops unsaved edits, and a field's reset returns it to the profile layer.
+Sidebar **Plugins** → the **Local Search** card in the **Official plugins** group → the plugin's own page. That is the same card shape the GitHub plugin contributes. Saves apply to the next tool call; leaving the page drops unsaved edits. **Reset**, under the description, first shows what it will clear and only writes once you confirm: the engine and limit settings go, a fresh probe refills them, and the search scopes are left alone because they are paths you typed.
 
-**Test connection**, directly under the Anytxt endpoint, probes that address as typed — nothing has to be saved first — together with Everything, and answers in one line. A failing engine gets a link to its official download page; this plugin never bundles, downloads, or installs either product.
+The page is organised by capability: **File names** and **File contents** each open with a backend picker and show that backend's fields once it is selected; **Search scopes** and **Limits** are the same whichever backend runs, so they close the page. The Host's `GET /dsh-local-search/api/describe` supplies the sections, the registered backends, the field types and the hard caps, and the page only renders them, so a new backend does not change the page logic.
+
+**Test connection** sits under the Anytxt endpoint field. It probes the endpoint as typed — nothing has to be saved first — together with Everything, and puts the result and its fix in a dialog that can probe again. The `es.exe` path in the field is checked too, so a typo there says the file is missing instead of reporting the saved binary as OK. A failing engine gets a link to its official download page; this plugin never bundles, downloads, or installs either product.
+
+**A save checks before it writes.** When the endpoint or the `es.exe` path is part of the edit, the page probes them first: whatever the check refuses is not written, and a dialog asks whether to **Save anyway** — a deliberate exception rather than the default. A hard rejection (no file at that path, no such directory, a rejected address) gets no such way out. The Host only checks that the path exists; it never starts a file named by a request. Path fields and the endpoint are also checked when focus leaves them: a missing path, a directory where a file belongs, or a non-local address is flagged under the input and clears as soon as the value changes.
+
+Path fields are rewritten to one standard spelling on save: `d:/alpha` is stored as `D:\alpha` (upper-case drive letter, backslashes, no trailing separator), and `allRoots` is rewritten entry by entry. When the path exists, the on-disk spelling wins (`d:/alpha` → `D:\Alpha`). Spaces and non-ASCII names are left alone — `D:\Alpha\我的项目\drawio a` is fine as typed, because the Host passes values to `es.exe` and the file APIs without going through a shell.
+
+The first run fills what it can and then stops: while `files.everything.esPath` or `content.anytxt.url` is still unset, the plugin probes once, writes what answered, and records that pass in a hidden `autoConfigured` key. After that a field you clear stays clear instead of being filled again.
 
 Every key is optional, and the row config replaces the whole config object rather than merging. Only `timeoutMs` stays in the profile's `cordis.patch.yml`: each tool fixes its deadline when it registers, so the page leaves it out rather than showing a field that would not take effect.
 
 | Key | Default | Meaning |
 |---|---|---|
-| `esPath` | auto-detect | Absolute path to `es.exe`. Resolution order: `esPath`, `ES_PATH`, common install folders, `where.exe`. |
-| `anytxtUrl` | `http://127.0.0.1:9920` | Anytxt JSON-RPC endpoint on this machine (`127.0.0.1`, `localhost` or `[::1]` only). The default also tries `:9921`. |
-| `workspaceRoot` | session default directory | Root for `scope=workspace`. |
-| `workRoot` | empty | Root for `scope=work`; required before using that scope. |
-| `personalRoot` | empty | Root for `scope=personal`; required before using that scope. |
-| `allRoots` | `C:\` plus `D:\` when present | Semicolon-separated roots for Anytxt `scope=all`. Everything `scope=all` searches all volumes it indexes. |
-| `maxResults` | `20` | Default result cap. Hard cap is 100. |
+| `files.backend` | `everything` | Filename backend `auto` uses. |
+| `files.everything.esPath` | auto-detect | Absolute path to `es.exe`. Resolution order: the configured value, `ES_PATH`, common install folders, `where.exe`. |
+| `files.everything.esEncoding` | `gbk` | Code page used to decode `es.exe` output. Any `TextDecoder` label is accepted; the page offers `gbk` and `utf-8`. |
+| `content.backend` | `anytxt` | Content backend `auto` uses. |
+| `content.anytxt.url` | `http://127.0.0.1:9920` | Anytxt JSON-RPC endpoint on this machine (`127.0.0.1`, `localhost` or `[::1]` only). The default also tries `:9921`. |
+| `scopes.workspaceRoot` | session default directory | Root for `scope=workspace`. |
+| `scopes.workRoot` | empty | Root for `scope=work`; required before using that scope. |
+| `scopes.personalRoot` | empty | Root for `scope=personal`; required before using that scope. |
+| `scopes.allRoots` | `C:\` plus `D:\` when present | Semicolon-separated roots for Anytxt `scope=all`. Everything `scope=all` searches all volumes it indexes. |
+| `limits.maxResults` | `20` | Default result cap; hard cap 100. |
+| `limits.readMaxChars` | `8000` | Default `local_search_read` window; hard cap 20,000 characters. |
 | `timeoutMs` | `30000` | Per-call timeout budget; profile YAML only. |
-| `readMaxChars` | `8000` | Default `local_search_read` window; hard cap is 20,000 characters. |
-| `esEncoding` | `gbk` | Code page used to decode `es.exe` output. The page offers `gbk` and `utf-8` as a two-choice control. |
 
 Example row override:
 
@@ -92,23 +102,27 @@ Example row override:
 - id: fishdivinity-local-search
   name: '@fishdivinity/dsh-local-search'
   config:
-    workRoot: 'D:\Projects'
-    personalRoot: 'D:\Documents'
-    allRoots: 'C:\;D:\'
+    scopes:
+      workRoot: 'D:\Projects'
+      personalRoot: 'D:\Documents'
+    limits:
+      maxResults: 50
 ```
 
+A 0.2 profile needs no hand edit: on startup its nine flat keys (`esPath`, `esEncoding`, `anytxtUrl`, `workspaceRoot`, `workRoot`, `personalRoot`, `allRoots`, `maxResults`, `readMaxChars`) move into the structure above and are removed. When the settings layer refuses that write — a home patch overrides the profile — the old keys stay and are still read.
+
 ## Scopes
 
 - `workspace` (default): the session's working directory.
-- `work`: `workRoot`.
-- `personal`: `personalRoot`.
-- `all`: `allRoots` for Anytxt; all indexed volumes for Everything.
+- `work`: `scopes.workRoot`.
+- `personal`: `scopes.personalRoot`.
+- `all`: `scopes.allRoots` for Anytxt; all indexed volumes for Everything.
 
 Use `all` only when the user explicitly asks for a cross-drive/global search. The `path` argument overrides `scope`.
 
 ## Engine selection
 
-`engine` defaults to `auto`:
+`engine` defaults to `auto`, which follows the backend configured for that capability: `files.backend` for `local_search_files`, `content.backend` for `local_search_content`, `fragments`, and `read`.
 
 - `local_search_files`: `auto` or `everything`.
 - `local_search_content` / `fragments` / `read`: `auto` or `anytxt`.
@@ -122,7 +136,7 @@ Failures are typed `HarnessError`s with stable codes:
 
 | Code | Meaning |
 |---|---|
-| `EVERYTHING_ES_NOT_FOUND` | `es.exe` is missing; install it or set `esPath`. |
+| `EVERYTHING_ES_NOT_FOUND` | `es.exe` is missing; install it or set `files.everything.esPath`. |
 | `EVERYTHING_DOWN` | Everything is not running / cannot be reached. |
 | `EVERYTHING_TIMEOUT`, `EVERYTHING_TOO_LARGE` | Query too broad or slow; narrow it. |
 | `ANYTXT_DOWN` | Anytxt GUI is not running or the JSON-RPC endpoint is unreachable. |
@@ -166,7 +180,7 @@ npm run check
 npm run pack:check
 ```
 
-The engine and config modules (`lib/everything.js`, `lib/anytxt.js`, `lib/roots.js`, `lib/format.js`, `lib/config.js`) are independent of the DSH runtime so their tests run under plain Node. `lib/client.js` ships as the browser half: it is written directly in the client module system's lazy-CJS factory format, so there is no build step. See [`docs/architecture.md`](docs/architecture.md), [`docs/extending-engines.md`](docs/extending-engines.md), and [`.github/RELEASING.md`](.github/RELEASING.md).
+The engine and config modules (`lib/everything.js`, `lib/anytxt.js`, `lib/roots.js`, `lib/format.js`, `lib/config.js`) are independent of the DSH runtime so their tests run under plain Node. `lib/client.js` ships as the browser half: it is written directly in the client module system's lazy-CJS factory format, so there is no build step. See [`docs/architecture.md`](docs/architecture.md), [`docs/extending-engines.md`](docs/extending-engines.md), [`docs/config-migration.md`](docs/config-migration.md) for the rules a config-shape change has to follow, and [`.github/RELEASING.md`](.github/RELEASING.md).
 
 ## Changelog
 

package/cordis.patch.yml

@@ -2,7 +2,8 @@
 # Every key has a schema default; override any of them here by replacing this
 # row's config (the whole row is replaced, never deep-merged).
 # Keep this file neutral (config: {}) in the package: machine-specific paths
-# such as esPath / workRoot belong in the user's profile patch, not here.
+# such as files.everything.esPath / scopes.workRoot belong in the user's
+# profile patch, not here.
 - insert:
     - id: fishdivinity-local-search
       name: '@fishdivinity/dsh-local-search'

package/lib/anytxt.js

@@ -6,15 +6,13 @@ const EXCLUDED = [/\\\$RECYCLE\.BIN\\/i, /\\System Volume Information\\/i]
 const RPC_TIMEOUT_MS = 15000
 
 /**
- * Primary URL plus the 9921 fallback used by some Anytxt builds.
+ * 主地址，加上某些 Anytxt 构建会用的 9921 回退口。
  *
- * This is where the loopback rule lives: the endpoint is read per call, so a
- * profile that still names another machine fails only the content search, with
- * a code the model can explain — instead of failing activation and taking
- * file-name search down with it.
- * @param url - configured endpoint
- * @returns the endpoints to try, in order
- * @throws {EngineError} ANYTXT_ENDPOINT_REMOTE when the endpoint is not local
+ * loopback 规则就住在这里：地址是每次调用现读的，所以一份仍写着另一台机器的 profile 只会让
+ * 内容检索失败，并给出一个模型能解释的 code——而不是让激活失败、把文件名检索一起拖下水。
+ * @param url - 配置的地址
+ * @returns 要依次尝试的地址
+ * @throws {EngineError} 地址不是本机时抛 ANYTXT_ENDPOINT_REMOTE
  */
 export function resolveAnytxtUrls(url = DEFAULT_URL) {
   const base = String(url || DEFAULT_URL).replace(/\/+$/, '')
@@ -28,7 +26,7 @@ export function resolveAnytxtUrls(url = DEFAULT_URL) {
   return urls
 }
 
-/** Quoted phrases use exact mode (st=1); other queries use advanced mode. */
+/** 带引号的短语走精确模式（st=1），其余查询走高级模式。 */
 export function quoteAware(query) {
   const trimmed = String(query ?? '').trim()
   if (/^".*"$/s.test(trimmed)) {
@@ -37,7 +35,7 @@ export function quoteAware(query) {
   return { pattern: trimmed, st: '2' }
 }
 
-/** Remove Anytxt's match highlight markers from snippets. */
+/** 去掉 Anytxt 在片段里加的命中高亮标记。 */
 export function stripHighlights(text) {
   return String(text ?? '').replace(/\*<<\*|\*>>\*/g, '')
 }
@@ -59,7 +57,7 @@ function parseFileTuple(tuple) {
   return item
 }
 
-/** POST one JSON-RPC request and return `result.data.output`. */
+/** 发一次 JSON-RPC POST 并返回 `result.data.output`。 */
 export async function anytxtRpc(url, method, input, { timeoutMs = RPC_TIMEOUT_MS, signal, fetchImpl = fetch } = {}) {
   const timeoutSignal = AbortSignal.timeout(timeoutMs)
   const combined = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal
@@ -70,9 +68,8 @@ export async function anytxtRpc(url, method, input, { timeoutMs = RPC_TIMEOUT_MS
       headers: { accept: 'application/json', 'content-type': 'application/json' },
       body: JSON.stringify({ id: 1, jsonrpc: '2.0', method, params: { input } }),
       signal: combined,
-      // A 307/308 would re-POST this body wherever the endpoint points, so a
-      // loopback service could bounce the request off-machine and have its
-      // answer trusted as index data.
+      // 307/308 会把这个 body 重新 POST 到地址指向的任何地方，于是一个本机服务就能把请求弹到
+      // 别的机器上，而它的回答还会被当成索引数据信下来。
       redirect: 'error',
     })
   } catch (error) {
@@ -122,7 +119,7 @@ export async function anytxtRpc(url, method, input, { timeoutMs = RPC_TIMEOUT_MS
   return output
 }
 
-/** Try the primary URL, then the 9921 fallback only on connection failures. */
+/** 先试主地址，只在连接失败时才试 9921 回退口。 */
 async function rpcFirst(urls, method, input, options) {
   let lastError
   for (const url of urls) {
@@ -137,7 +134,7 @@ async function rpcFirst(urls, method, input, options) {
   throw lastError
 }
 
-/** Search document contents through Anytxt, one request pair per root. */
+/** 通过 Anytxt 检索文档内容，每个根一对请求。 */
 export async function searchContent({
   query,
   roots,
@@ -203,7 +200,7 @@ export async function searchContent({
   return { items, total, truncated: total > items.length }
 }
 
-/** Snippets around a match in one indexed file. */
+/** 一个已索引文件里命中处附近的片段。 */
 export async function getFragments({
   ref,
   query,
@@ -225,7 +222,7 @@ export async function getFragments({
   return (output.text || []).map(stripHighlights).filter(Boolean)
 }
 
-/** Full extracted text for one indexed file. */
+/** 一个已索引文件的完整抽取文本。 */
 export async function getRawText({
   ref,
   url = DEFAULT_URL,
@@ -243,7 +240,12 @@ export async function getRawText({
   return typeof output.text === 'string' ? output.text : ''
 }
 
-/** Probe Anytxt without throwing. */
+/**
+ * 探测 Anytxt，不抛异常。
+ *
+ * 返回**实际应答**的那个地址，不是第一个尝试的地址：`resolveAnytxtUrls` 会带上 `:9921` 回退，
+ * 而自动配置要把「哪个端口能用」写回配置，报错端口等于把结论写反。
+ */
 export async function anytxtStatus({
   url = DEFAULT_URL,
   root = process.env.SystemDrive ? `${process.env.SystemDrive}\\` : 'C:\\',
@@ -252,21 +254,33 @@ export async function anytxtStatus({
   fetchImpl = fetch,
 } = {}) {
   const urls = resolveAnytxtUrls(url)
-  try {
-    await rpcFirst(
-      urls,
-      'ATRpcServer.Searcher.V1.Search',
-      {
-        pattern: 'the',
-        filterDir: root,
-        filterExt: 'txt',
-        lastModifyBegin: 0,
-        lastModifyEnd: 2147483647,
-      },
-      { timeoutMs, signal, fetchImpl },
-    )
-    return { ok: true, url: urls[0] }
-  } catch (error) {
-    return { ok: false, code: error.code ?? 'ANYTXT_DOWN', message: error.message, url: urls[0] }
+  let lastError
+  for (const candidate of urls) {
+    try {
+      await anytxtRpc(
+        candidate,
+        'ATRpcServer.Searcher.V1.Search',
+        {
+          pattern: 'the',
+          filterDir: root,
+          filterExt: 'txt',
+          lastModifyBegin: 0,
+          lastModifyEnd: 2147483647,
+        },
+        { timeoutMs, signal, fetchImpl },
+      )
+      return { ok: true, url: candidate }
+    } catch (error) {
+      lastError = error
+      // 与 rpcFirst 同一条规则：只有「连不上」才值得换下一个端口。
+      if (error.code === 'ANYTXT_DOWN' && candidate !== urls[urls.length - 1]) continue
+      break
+    }
+  }
+  return {
+    ok: false,
+    code: lastError?.code ?? 'ANYTXT_DOWN',
+    message: lastError?.message,
+    url: urls[0],
   }
 }

package/lib/bootstrap.js

@@ -0,0 +1,201 @@
+/**
+ * 启动时的两次配置写入：把 0.2 的扁平键搬进嵌套结构，以及首用自动配置。
+ *
+ * 两者都走 `ctx.settings`：只有它能把值写进 profile 的 `cordis.patch.yml` 并通过 Loader
+ * 让 volatile 引用就地更新，不重载插件。写入范围都限定在「用户层还没有值的字段」，
+ * 所以幂等，也永远不会覆盖用户已经选过的值。
+ *
+ * 迁移失败不算致命：profile 被 home patch 覆盖时 settings 会拒绝写入，旧键留在原地，
+ * `readConfig` 的回退让它们继续生效。
+ */
+
+import { DEFAULTS, PATHS, RETIRED_PATHS, hasPath, pathValue, readConfig, setPath } from './config.js'
+import { probeEngines } from './probe.js'
+
+/**
+ * 在 settings 的描述里找本插件的命名空间。
+ * @param {Array<object>} descriptors - `settings.describe()` 的结果
+ * @param {string} ns - profile 行 id
+ * @returns {object|undefined} 对应的描述
+ */
+export function findDescriptor(descriptors, ns) {
+  return descriptors.find((descriptor) => descriptor.ns === ns)
+}
+
+/**
+ * 把退役路径搬进当前结构、再清掉旧键的操作列表。
+ *
+ * **只认用户层里真的存在的旧路径**。schema 给退役路径也声明了默认值，所以「配置里有值」不等于
+ * 「用户写过」——按配置判断会把 `esEncoding` / `anytxtUrl` / `maxResults` / `readMaxChars` 四个
+ * 默认值写进 profile，并让首用自动配置以为地址已经设过，从而丢掉 9921 那一次探测。
+ *
+ * 链式迁移在同一次调用里跑完：上一段的 `to` 是下一段的 `from`，所以「0.1 直装 1.0」不需要中间
+ * 版本存在过。链上的中间路径只搬不写（写进去也没人读）；先写新位置再清旧键，settings 只应用了
+ * 一半时读侧兜底仍拿得到值。
+ * @param user - 设置表单的用户层
+ * @param retired - 退役路径表，测试可注入
+ * @returns {{ops: Array<object>, keys: string[]}} 操作列表与清掉的旧路径
+ */
+export function migrationOps(user = {}, retired = RETIRED_PATHS) {
+  const staged = {}
+  const carried = []
+  for (const { from, to } of retired) {
+    // 用户层里有这个旧路径就用它；否则接着链上一步放在 `staged` 里的值。
+    const value = hasPath(user, from) ? pathValue(user, from) : pathValue(staged, from)
+    if (value === undefined || value === null) continue
+    if (typeof value === 'string' && value.trim() === '') continue
+    setPath(staged, to, value)
+    carried.push(to.join('.'))
+  }
+  const currentPaths = new Set(Object.values(PATHS).map((path) => path.join('.')))
+  const ops = []
+  const keys = []
+  for (const pathKey of carried) {
+    if (!currentPaths.has(pathKey)) continue
+    const path = pathKey.split('.')
+    if (hasPath(user, path)) continue
+    const value = pathValue(staged, path)
+    if (value === undefined) continue
+    ops.push({ op: 'set', path, value })
+  }
+  for (const { from } of retired) {
+    // 只有用户层里真的存在、且不是空白的旧键才需要清；schema 默认值不算。
+    if (!hasPath(user, from)) continue
+    const value = pathValue(user, from)
+    if (value === undefined || value === null) continue
+    if (typeof value === 'string' && value.trim() === '') continue
+    keys.push(from.join('.'))
+    ops.push({ op: 'unset', path: from })
+  }
+  return { ops, keys }
+}
+
+/**
+ * 写一次设置，撞上并发修改就重读 revision 再试一次。
+ *
+ * 自动配置把「探测」夹在 `describe()` 与 `mutate()` 之间（一次 es.exe + 一次 HTTP），这段时间
+ * 里谁在页面上点了保存，我们的 revision 就过期（`SETTINGS_CONFLICT`）。重放安全——ops 只碰
+ * 用户层还没设过的字段。
+ *
+ * 命名空间消失时抛错而不是静默返回：那条消息是「写回为什么没发生」唯一的线索。
+ * @param {object} settings - Host 的 settings 服务
+ * @param {string} ns - profile 行 id
+ * @param {Array<object>} ops - 设置操作列表
+ */
+async function writeSettings(settings, ns, ops) {
+  const descriptor = findDescriptor(settings.describe(), ns)
+  if (descriptor === undefined) throw new Error(`settings namespace "${ns}" is not available`)
+  try {
+    await settings.mutate(ns, ops, descriptor.revision)
+  } catch (error) {
+    if (error?.code !== 'SETTINGS_CONFLICT') throw error
+    const retried = findDescriptor(settings.describe(), ns)
+    if (retried === undefined) throw error
+    await settings.mutate(ns, ops, retried.revision)
+  }
+}
+
+/**
+ * 是否还有值得探测的东西。
+ *
+ * 没有待填字段就完全不探测：一次探测要花一次 es.exe 启动和一次 HTTP 请求，配置齐了就不该
+ * 在每次启动时付这个成本。
+ * @param {object} values - 配置快照
+ * @param {object} user - 设置表单的用户层
+ * @returns {boolean} 需要探测时为 true
+ */
+export function autoconfigNeeds(values, user) {
+  const wantsEsPath = !hasPath(user, PATHS.esPath) && !values.files.everything.esPath
+  const wantsUrl = !hasPath(user, PATHS.anytxtUrl) && values.content.anytxt.url === DEFAULTS.content.anytxt.url
+  return wantsEsPath || wantsUrl
+}
+
+/**
+ * 探测结果里可以写回去的字段。
+ * @param {{everything: object, anytxt: object}} probed - 探测结果
+ * @param {object} values - 配置快照
+ * @param {object} user - 设置表单的用户层
+ * @returns {Array<object>} 设置操作列表
+ */
+export function autoconfigOps(probed, values, user) {
+  const ops = []
+  const everythingPath = probed.everything?.ok ? probed.everything.path : undefined
+  if (typeof everythingPath === 'string' && everythingPath !== '') {
+    if (!hasPath(user, PATHS.esPath) && !values.files.everything.esPath) {
+      ops.push({ op: 'set', path: PATHS.esPath, value: everythingPath })
+    }
+  }
+  // 只在探测真的落到 9921 回退口时才写地址：默认值本身写回去没有信息量。
+  const anytxtUrl = probed.anytxt?.ok ? probed.anytxt.url : undefined
+  if (typeof anytxtUrl === 'string' && anytxtUrl !== '' && anytxtUrl !== DEFAULTS.content.anytxt.url) {
+    if (!hasPath(user, PATHS.anytxtUrl) && values.content.anytxt.url === DEFAULTS.content.anytxt.url) {
+      ops.push({ op: 'set', path: PATHS.anytxtUrl, value: anytxtUrl })
+    }
+  }
+  return ops
+}
+
+/** 探测失败且值得告诉用户的引擎。取消与跳过是部署事实，不是故障。 */
+function probeFailures(probed) {
+  const failures = []
+  for (const engine of ['everything', 'anytxt']) {
+    const status = probed[engine] ?? {}
+    if (status.ok) continue
+    const code = String(status.code ?? 'UNKNOWN')
+    if (code === 'SKIPPED' || code.endsWith('_ABORTED')) continue
+    failures.push({ engine, code })
+  }
+  return failures
+}
+
+/**
+ * 执行一次启动配置：先迁移旧键，再按需探测并写回。
+ * @param {object} options
+ * @param {object} options.settings - Host 的 settings 服务
+ * @param {string} options.ns - profile 行 id（= 设置命名空间）
+ * @param {object} options.config - schema 输出，含活引用
+ * @param {object} [options.logger] - 有 `warn` 时迁移失败会记一条
+ * @param {Function} [options.probe] - 可注入的探测函数
+ * @param {object} [options.state] - 会被就地更新的描述载荷
+ * @returns {Promise<object>} 同一个 state
+ */
+export async function bootstrap({ settings, ns, config, logger, probe = probeEngines, state = {} }) {
+  const target = Object.assign({ ran: false, written: [], failures: [] }, state)
+  try {
+    const descriptor = findDescriptor(settings.describe(), ns)
+    if (descriptor === undefined) return target
+    const { ops, keys } = migrationOps(descriptor.user)
+    if (ops.length > 0) {
+      await writeSettings(settings, ns, ops)
+      target.written.push(...keys)
+    }
+  } catch (error) {
+    target.error = String(error?.message ?? error)
+    logger?.warn?.('dsh-local-search: could not migrate the flat config keys', error)
+  }
+  try {
+    const values = readConfig(config)
+    const descriptor = findDescriptor(settings.describe(), ns)
+    if (descriptor === undefined) return target
+    // 已经做过决定就再不碰：用户清空的字段必须能保持空着，否则「重置」形同虚设。
+    if (values.autoConfigured === true) return target
+    if (!autoconfigNeeds(values, descriptor.user)) {
+      // 配置本来就齐：只补标记，免得以后清空某个字段又被自动写回。
+      await writeSettings(settings, ns, [{ op: 'set', path: PATHS.autoConfigured, value: true }])
+      target.written.push(PATHS.autoConfigured.at(-1))
+      return target
+    }
+    target.ran = true
+    const probed = await probe(config, { detail: true })
+    target.failures = probeFailures(probed)
+    const ops = autoconfigOps(probed, values, descriptor.user)
+    // 标记与值同一次落盘：哪怕这次什么也没探测到，也只做这一次决定。
+    ops.push({ op: 'set', path: PATHS.autoConfigured, value: true })
+    await writeSettings(settings, ns, ops)
+    target.written.push(...ops.slice(0, -1).map((op) => op.path.at(-1)))
+  } catch (error) {
+    target.error = String(error?.message ?? error)
+    logger?.warn?.('dsh-local-search: first-run autoconfiguration failed', error)
+  }
+  return target
+}