@objectivex666/dsh-settings-search 1.13.1 → 1.14.1

package/README.en.md

@@ -7,6 +7,8 @@
 [![node](https://img.shields.io/node/v/@objectivex666/dsh-settings-search)](https://nodejs.org)
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/objectivex666/dsh-settings-search)
+[![dshbase 实测可装](https://dshbase.com/badges/dsh-settings-search-plugin.svg)](https://dshbase.com/zh/plugins/dsh-settings-search-plugin/)
+[![dshfind](https://dshfind.com/api/card/objectivex666/dsh-settings-search?lang=zh)](https://dshfind.com/zh/plugins/objectivex666/dsh-settings-search?ref=badge)
 
 **English** · [中文](./README.md)
 
@@ -18,16 +20,16 @@
 - 🧩 **Three search styles** — choose the classic sidebar, window top bar, or popup search page. The choice is saved in the current browser.
 - ⌨️ **Search shortcut (v1.10.0)** — focus the search box with `Ctrl+F` or `⌘F` inside the settings panel. You can enable or disable it from the "Settings Search" page; disabling keeps the browser's default find behavior.
 - 🤝 **Import DSH model config (v1.9.0)** — import the Base URL and model name from DSH's current default model in the AI config section. When that default is a built-in DeepSeek route (whose settings carry no Base URL), the import uses DeepSeek's own endpoint, `https://api.deepseek.com/anthropic`. For credential safety, the API key is never imported.
-- 🎯 **First-run onboarding (v1.9.0)** — a welcome modal appears only the first time the settings panel opens after installation. It introduces the four search styles, pinyin/intent/AI hints, click-to-jump, and auto-indexing; there are no "Don't show again" or manual reopen buttons.
-- 📂 **In-page option search (v1.2.0)** — search beyond pages and reach the specific options inside them: Plugins-page tabs (`settings.plugins.tab`), the pre-0.2 plugin-card seats (`settings.plugin.item` / `web-ui.plugin.item`, both gone in 0.2), general rows, and more, each shown with a "page › option" breadcrumb.
+- 🎯 **First-run onboarding (v1.9.0)** — a welcome modal appears only the first time the settings panel opens after installation. It introduces live search, pinyin and intent hints, AI hints, click-to-jump, the built-in settings page, and auto-indexing; there are no "Don't show again" or manual reopen buttons.
+- 📂 **In-page option search (v1.2.0)** — search beyond pages and reach the specific options inside them: Plugins-page tabs (`settings.plugins.tab`), the **会话插件 / 全局插件** group titles on the Plugins page, the pre-0.2 plugin-card seats (`settings.plugin.item` / `web-ui.plugin.item`, both gone in 0.2), general rows, and more, each shown with a "page › option" breadcrumb.
 - 🔤 **Pinyin association search (v1.5.0)** — type initials (`sz`) or full pinyin (`shezhi`) to surface Chinese settings items; navigate with `↑`/`↓`, confirm with `Enter`, dismiss with `Esc`, and matched text is highlighted.
 - 🧠 **Intent search (v1.6.0)** — describe the goal in Chinese (e.g. 「太亮了」 "too bright", 「字太小」 "text too small") to surface matching settings without knowing their names, shown in a "You may want" group.
 - 🤖 **AI-assisted search** — when nothing matches locally, your OpenAI-compatible, Anthropic, or local Ollama model understands your search intent and suggests settings. Off by default; configure it on the plugin's settings page. Ollama needs no API key.
-- 💾 **Persistent settings index (v1.12.0)** — the first harvested settings index is stored locally. It rebuilds only on first use or after another plugin is installed or updated, and can be rebuilt manually from the Settings Search page.
+- 💾 **Persistent settings index (v1.12.0)** — the first harvested settings index is stored locally. It rebuilds only on first use, after another plugin is installed, updated, enabled, or disabled, and can be rebuilt manually from the Settings Search page.
 - 🧾 **Logging & viewing (v1.13.0 / v1.7.0)** — records key plugin actions, searches, and AI requests. Logs are written per local day as `$DSH_HOME/logs/dsh-settings-search/settings-search-YYYY-MM-DD.log`: one dated file per day, capped at 100 MB (the day then continues in numbered parts, `.1`, `.2`, …), with the whole folder held at 100 MB by deleting the oldest files — never the one being written. The plugin's page can **view logs**, **open the log folder**, copy, export, or clear them; the badge beside the "Logs" title counts today's file. API keys are never logged.
 - 🧭 **Click-to-jump** — selecting a result clicks the matching left-nav entry to open its section; for tab options it also opens the tab and flashes the target row. A manual-path hint appears if automatic navigation is not possible.
 - 🌱 **Auto-index on startup (v1.8.0)** — the first time the settings panel opens, the plugin automatically visits every settings section, silently reads in-page options (e.g. "Enable Workshop card") into the search index, then restores your current section, so all section options are searchable without having to open each page manually. A "Importing section options…" hint shows under the search box and clears when done.
-- 🛠 **Built-in settings page (v1.4.0)** — a "Settings Search" page in the left navigation shows the current version and checks npm for a newer release on demand; when one exists it hands you a copy-ready `dsh plugin update` command.
+- 🛠 **Built-in settings page (v1.4.0)** — a "Settings Search" page in the left navigation shows the current version and checks npm for a newer release on demand; when one exists it hands you a copy-ready upgrade command carrying the profile name and the latest version.
 - 🧭 **View release notes (v1.7.1)** — the "Settings Search" page has a "View changelog" button next to "Check for updates"; it fetches the GitHub release notes and shows them inline, opening the release page if fetching fails.
 - 🌐 **i18n** — built-in Chinese/English dictionaries that follow the DSH localization system and are easy to extend.
 - 🎨 **Theme-aware** — styled entirely with CSS variables, automatically following the DSH theme (light/dark).
@@ -39,9 +41,11 @@
 
 This plugin is a standard **DSH profile bundle**: once installed it wires itself into the settings panel — no manual edits to any DSH configuration file.
 
+The commands below target a command-line profile. The desktop app manages its own `desktop` profile, which the CLI cannot touch — install the plugin for the desktop app from its plugin management page instead.
+
 ### Prerequisites
 
-- **DeepSeek Harness (DSH)** — DSH 0.2 stable (desktop and `dsh web`) and earlier 0.1 builds; the plugin picks the API the running release offers.
+- **DeepSeek Harness (DSH)** — DSH 0.2 stable (desktop and `dsh web`) and earlier 0.1 builds; the plugin picks the API the running release offers. Verified against **0.2.2-rc.3** item by item (`npm run compat`); behaviour on 0.2.1 and earlier is unchanged.
 - **Node.js** >= 18 (LTS recommended).
 
 ### From npm (recommended)
@@ -62,7 +66,7 @@ dsh plugin --profile web add github:objectivex666/dsh-settings-search
 dsh plugin --profile web add /path/to/dsh-settings-search
 ```
 
-After installing, **restart DSH** (`dsh web`); the search box appears at the top of the settings panel.
+After installing, **restart DSH** (`dsh web`); the search box appears in the settings panel.
 
 To uninstall: `dsh plugin --profile web remove @objectivex666/dsh-settings-search`.
 
@@ -115,9 +119,12 @@ scripts/log.test.mjs Host log file and route regression tests (temp dirs; never
 ## Development
 
 ```bash
-npm test   # structural checks and mocked Ollama / OpenAI / Anthropic regression tests
+npm test       # structural checks and mocked Ollama / OpenAI / Anthropic regression tests
+npm run compat # audit compatibility against the Harness installed on this machine
 ```
 
+`npm run compat` reads the local install (auto-detected; `--asar <app.asar>` or `DSH_ASAR=<app.asar>` also work) and checks the surfaces this plugin relies on that belong to no npm API — service names, Remote descriptors, slots, theme tokens, the Fetch route registry, and the DeepSeek constants. Run it first after a Harness upgrade to see exactly what moved.
+
 > Historical note: up to v1.1 the repo shipped `dsh-settings-search.js` (an
 > in-session `cordis_define` dynamic-plugin source). Because keeping it in
 > sync with the shipping package kept drifting silently, it was removed in
@@ -135,7 +142,7 @@ When submitting an issue, please include as much of the following as possible so
 
 - **Problem description**: what you expected vs. what actually happened.
 - **Reproduction steps**: a step-by-step walkthrough, including the triggering keywords and the settings page involved.
-- **Logs**: export the recent search/runtime logs from the plugin's "Logging & export" page and paste them (API keys are never logged, so it is safe to share); include any console errors as well.
+- **Logs**: open the "Logs" section of the plugin's page, use "Export logs", and paste the recent search/runtime logs (API keys are never logged, so it is safe to share); include any console errors as well.
 - **Environment**: DSH version, Node.js version, plugin version (shown on the "Settings Search" page), OS, and browser.
 - **Screenshots / screen recording**: helpful for UI-related issues.
 
@@ -143,8 +150,8 @@ When submitting an issue, please include as much of the following as possible so
 
 Every version bump keeps git tags and GitHub Releases in sync, with a bilingual body that lists both new features and fixes:
 
-- Update [CHANGELOG.md](./CHANGELOG.md) (Chinese) and [CHANGELOG.en.md](./CHANGELOG.en.md) (English), each with `### ✨ Features` and `### 🐛 Fixes` sections.
-- Bump the version in `package.json` and the README, then tag and push as `vX.Y.Z`; GitHub Actions publishes to npm (`npm-publish.yml`) and creates a bilingual GitHub Release (`release.yml`).
+- Update [CHANGELOG.md](./CHANGELOG.md) (Chinese) and [CHANGELOG.en.md](./CHANGELOG.en.md) (English), each with a features section and a fixes section (`新功能` / `修复` in Chinese, `Features` / `Fixes` in English).
+- Bump `version` in `package.json` together with `PKG_VERSION` in `lib/client.js` (`npm test` enforces they match), add the version label next to any new feature, then tag and push as `vX.Y.Z`; GitHub Actions publishes to npm (`npm-publish.yml`) and creates a bilingual GitHub Release (`release.yml`).
 - Preview the release body locally: `node scripts/release.mjs --version <ver>`
 - Tag and publish for real: `node scripts/release.mjs --version <ver> --publish` (requires `gh` CLI, logged in)
 

package/README.md

@@ -1,12 +1,14 @@
 # dsh-settings-search
 
-> 为 DSH（Cordis）设置面板提供即时搜索能力，快速定位设置页与通用设置项。
+> 给 DSH（Cordis）设置面板加一个搜索框，输入关键词就跳到对应的设置页和设置项。
 
 [![npm version](https://img.shields.io/npm/v/@objectivex666/dsh-settings-search)](https://www.npmjs.com/package/@objectivex666/dsh-settings-search)
 [![license](https://img.shields.io/npm/l/@objectivex666/dsh-settings-search)](./LICENSE)
 [![node](https://img.shields.io/node/v/@objectivex666/dsh-settings-search)](https://nodejs.org)
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/objectivex666/dsh-settings-search)
+[![dshbase 实测可装](https://dshbase.com/badges/dsh-settings-search-plugin.svg)](https://dshbase.com/zh/plugins/dsh-settings-search-plugin/)
+[![dshfind](https://dshfind.com/api/card/objectivex666/dsh-settings-search?lang=zh)](https://dshfind.com/zh/plugins/objectivex666/dsh-settings-search?ref=badge)
 
 **中文** · [English](./README.en.md)
 
@@ -14,36 +16,39 @@
 
 ## 功能特性
 
-- 🔍 **实时搜索**：在设置面板中嵌入搜索框，输入关键词立即过滤所有已注册的设置页（`settings.section`）与通用设置项（`settings.general.item`）。
-- 🧩 **三种搜索样式**：可选择经典侧栏、窗口顶栏或弹出搜索页；选择会保存在当前浏览器。
-- ⌨️ **搜索快捷键（v1.10.0）**：在设置面板内按 `Ctrl+F` 或 `⌘F` 聚焦搜索框；可在「设置搜索」页启用或关闭，关闭后保留浏览器默认查找。
-- 🤝 **导入 DSH 模型配置（v1.9.0）**：在 AI 配置区一键读取 DSH 当前默认模型的 Base URL 与模型名；默认模型是 DSH 内置的 DeepSeek 路由时（设置里不含 Base URL），导入 DeepSeek 的接口地址 `https://api.deepseek.com/anthropic`。为避免凭据扩散，导入始终不包含 API Key。
-- 🎯 **新用户引导（v1.9.0）**：仅在安装后首次打开设置面板时弹出引导弹窗，介绍四种搜索样式、拼音/意图/AI 联想、点击即达与自动导入索引等核心功能；不再提供“不再显示”和手动重开按钮。
-- 📂 **页内选项搜索（v1.2.0）**：不只搜页面，还能直达每个设置页内部的具体选项——插件页的标签页（`settings.plugins.tab`）、旧版的插件卡片座位（`settings.plugin.item` / `web-ui.plugin.item`，0.2 已移除）、通用设置行等，结果以「页面 › 选项」面包屑展示。
-- 🔤 **拼音联想搜索（v1.5.0）**：输入拼音首字母（如 `sz`）或全拼（如 `shezhi`）即可联想中文设置项；支持 `↑`/`↓` 选择、`Enter` 跳转、`Esc` 关闭，命中的文字自动高亮。
-- 🧠 **意图联想搜索（v1.6.0）**：直接描述想做的事（如「太亮了」「字太小」「忘记密码」），无需知道选项名即可联想真实设置项，结果在「猜你想找」分组展示。
-- 🤖 **AI 联想搜索**：没有本地匹配时，用你配置的 OpenAI 兼容、Anthropic 或本机 Ollama 模型理解搜索意图并推荐设置项。默认关闭，可在「设置搜索」页开启并配置；Ollama 无需 API Key。
-- 💾 **持久设置索引（v1.12.0）**：首次采集后的设置索引保存在本机浏览器；只在首次安装、其它插件安装或更新时重建，也可在「设置搜索」页手动重建。
-- 🧾 **日志与查看（v1.13.0 / v1.7.0）**：记录插件运行、搜索与 AI 请求的关键动作。日志按天写入 DSH 日志目录（`$DSH_HOME/logs/dsh-settings-search/settings-search-YYYY-MM-DD.log`，文件名带日期，每天一个文件）；单个文件上限 100 MB，超出则同日续写编号分片（`.1`、`.2`…），整个日志目录上限 100 MB，超出时删除最旧的文件（正在写的文件永不删除）。「设置搜索」页可直接**查看日志**、**打开日志文件夹**、复制、导出或清空；「日志」标题旁的计数显示当天文件的条目数。不会记录 API Key。
-- 🧭 **点击即达**：选中结果后自动点击对应的左侧导航项打开所在分区；若是页内标签页会继续点开对应标签，并高亮闪烁目标选项行。无法自动跳转时显示手动路径提示。
-- 🌱 **启动自动索引（v1.8.0）**：首次打开设置面板时自动遍历各设置分区，静默读取分区内选项（如「启用创意工坊卡片」）并导入搜索索引；此后分区选项无需逐页手动打开即可直接搜索，读取完成后自动恢复当前所在分区，导入过程搜索框下方会显示提示，完成后自动消失。
-- 🛠 **自带设置页（v1.4.0）**：左侧导航新增「设置搜索」页——展示当前版本，一键检查 npm 注册表上的最新版本；有更新时直接给出复制就用的 `dsh plugin update` 命令。
-- 🧭 **更新说明查看（v1.7.1）**：在「设置搜索」页「检查更新」旁新增「查看更新说明」按钮，可拉取 GitHub Release 更新内容并就地展示；拉取失败时自动跳转 Release 页面。
-- 🌐 **多语言支持**：内置中英文国际化，可跟随 DSH 本地化系统扩展。
-- 🎨 **主题适配**：完全使用 CSS 变量，自动跟随 DSH 主题（亮/暗）。
-- ⚡ **动态响应**：实时订阅设置项的新增/删除/变更，搜索结果自动刷新。
+DSH 的设置项散落在各个分区和插件页里，找一个开关往往要一页页翻过去。这个插件把面板里的每一页、每一行都采进一份索引，再在面板上放一个搜索框，你直接说想找什么就行。
+
+- 🔍 **实时搜索**。装好以后设置面板里会多出一个搜索框，输入关键词就实时过滤所有已注册的设置页（`settings.section`）与通用设置项（`settings.general.item`）。
+- 🧩 **三种搜索样式**。经典侧栏、窗口顶栏、弹出搜索页，挑一个顺眼的。选择记在当前浏览器里，换浏览器或换机器要重新选一次。
+- ⌨️ **搜索快捷键**（v1.10.0）。在设置面板里按 `Ctrl+F` 或 `⌘F`，焦点直接落到搜索框上。不需要的话可以在「设置搜索」页关掉，关掉以后按 `Ctrl+F` 恢复成浏览器自己的查找。
+- 🤝 **导入 DSH 模型配置**（v1.9.0）。在 AI 配置区点一下，插件会读取 DSH 当前默认模型的 Base URL 与模型名。默认模型走 DSH 内置的 DeepSeek 路由、设置里没有 Base URL 时，导入的是 `https://api.deepseek.com/anthropic`。导入的内容里没有 API Key，这一点是有意的。
+- 🎯 **新用户引导**（v1.9.0）。装好以后第一次打开设置面板时弹一次，讲的是实时搜索、拼音与意图联想、AI 联想、点击即达、自带设置页和自动导入索引。关掉就不会再出现，也没有手动重开的入口。
+- 📂 **页内选项搜索**（v1.2.0）。索引里有页面，也有页面内部的选项，比如插件页的标签页（`settings.plugins.tab`）、插件页里的**会话插件 / 全局插件**分组标题、旧版的插件卡片座位（`settings.plugin.item` / `web-ui.plugin.item`，0.2 已移除）、通用设置行。结果显示成「页面 › 选项」的面包屑。
+- 🔤 **拼音联想搜索**（v1.5.0）。输入拼音首字母（`sz`）或全拼（`shezhi`）就能联想到中文设置项。`↑`/`↓` 选择，`Enter` 跳转，`Esc` 关闭，命中的字自动高亮。
+- 🧠 **意图联想搜索**（v1.6.0）。记不清选项叫什么也没关系，直接写「太亮了」「字太小」「忘记密码」，插件会猜你指的是哪几个设置，结果显示在「猜你想找」分组里。
+- 🤖 **AI 联想搜索**。本地匹配不到时，把搜索词交给你自己配置的 OpenAI 兼容接口、Anthropic 或本机 Ollama 模型，由模型判断你想改什么。功能默认关闭，需要到「设置搜索」页打开并填好配置，Ollama 不必填 API Key。
+- 💾 **持久设置索引**（v1.12.0）。采集过的索引存在本机浏览器里，只在首次安装，或者别的插件安装、更新、启用、停用时重建，也可以在「设置搜索」页手动重建。
+- 🧾 **日志与查看**（v1.13.0 / v1.7.0）。插件运行、搜索与 AI 请求的关键动作按天写进 DSH 日志目录（`$DSH_HOME/logs/dsh-settings-search/settings-search-YYYY-MM-DD.log`，文件名带日期，一天一个）。单个文件写到 100 MB 就同日换编号分片续写（`.1`、`.2`…），整个日志目录上限 100 MB，超了删最旧的文件，正在写的那个不删。「设置搜索」页里可以直接查看日志、打开日志文件夹、复制、导出或清空，标题旁的计数是当天文件里的条目数。API Key 不会进日志。
+- 🧭 **点击即达**。选中一条结果，插件替你点开左侧对应的导航项，目标在页内标签页里就继续点开那个标签，并把目标行高亮闪一下。跳不过去的时候显示手动路径提示。
+- 🌱 **启动自动索引**（v1.8.0）。第一次打开设置面板时，插件自己把各分区走一遍，静默读走分区里的选项（比如「启用创意工坊卡片」）并收进索引，读完回到你原先待着的分区。过程里搜索框下方有提示，读完自动消失。这之后那些选项不用逐页打开也能搜到。
+- 🛠 **自带设置页**（v1.4.0）。左侧导航多了「设置搜索」页，显示当前版本，可以一键查 npm 上的最新版本。有更新时给出能直接复制执行的升级命令，命令里带着 profile 名和最新版本号。
+- 🧭 **更新说明查看**（v1.7.1）。「设置搜索」页的「检查更新」旁边还有一个「查看更新说明」，拉取 GitHub Release 的内容就地展示，拉不到就直接跳到 Release 页面。
+- 🌐 **多语言支持**。内置中英文两套文案，跟着 DSH 的本地化系统走，也可以继续扩别的语言。
+- 🎨 **主题适配**。样式全部用 CSS 变量写，亮色暗色跟着 DSH 走。
+- ⚡ **动态响应**。插件实时订阅设置项的新增、删除和变更，结果列表跟着刷新。
 
 ---
 
 ## 安装（命令行）
 
-本插件是一个标准的 **DSH profile bundle**：安装后自动写入设置面板，
-无需手动修改任何 DSH 配置文件。
+本插件是一个标准的 DSH profile bundle。装完会自动写进设置面板，不需要手动改任何 DSH 配置文件。
+
+下面的命令都是给命令行 profile 用的。桌面端用的是 `desktop` profile，由桌面应用自己管理，命令行改不动它，在桌面端装插件要走应用的插件管理页。
 
 ### 前置要求
 
-- **DeepSeek Harness (DSH)**：DSH 0.2 正式版（桌面版与 `dsh web`）以及更早的 0.1 版本；本插件会按运行中的版本自动选择对应接口。
-- **Node.js** >= 18（推荐 LTS）。
+- **DeepSeek Harness (DSH)**。DSH 0.2 正式版（桌面版与 `dsh web`）和更早的 0.1 版本都可以，插件会按运行中的版本自动选择对应接口。当前已在 **0.2.2-rc.3** 上逐项核对过（`npm run compat`），0.2.1 及更早版本的行为保持不变。
+- **Node.js**。18 或更高，推荐 LTS。
 
 ### 通过 npm 安装（推荐）
 
@@ -63,16 +68,23 @@ dsh plugin --profile web add github:objectivex666/dsh-settings-search
 dsh plugin --profile web add /path/to/dsh-settings-search
 ```
 
-安装完成后**重启 DSH**（`dsh web`），打开设置面板即可看到顶部的搜索框。
-卸载：`dsh plugin --profile web remove @objectivex666/dsh-settings-search`。
+装完记得重启 DSH（`dsh web`），打开设置面板就能看见搜索框。要卸载就跑 `dsh plugin --profile web remove @objectivex666/dsh-settings-search`。
 
-> 非 `web` profile 请把命令中的 `--profile web` 换成你的 profile 名。
+> 如果你的 profile 不叫 `web`，把命令里的 `--profile web` 换成实际的名字。
+
+---
+
+## 它不做什么
+
+- 索引存在本机浏览器里，换个浏览器要重新采集一遍。
+- 导入 DSH 模型配置时不带 API Key，写日志时也不记录 API Key。
+- 关掉搜索快捷键之后，`Ctrl+F` 还给浏览器，插件不再拦截。
 
 ---
 
 ## 手动接线（不通过命令行安装时）
 
-把本包加入 profile 依赖并声明为 bundle 层即可（`dsh plugin add` 会自动完成）：
+不想用命令行的话，把本包加进 profile 依赖，声明成 bundle 层就行（`dsh plugin add` 帮你做的就是这件事）。
 
 ```yaml
 # 你的 profile 的 cordis.patch.yml（或通过 --patch 传入）
@@ -81,27 +93,26 @@ dsh plugin --profile web add /path/to/dsh-settings-search
       name: '@objectivex666/dsh-settings-search'
 ```
 
-包内自带 `cordis.patch.yml`（本文件内容），`dsh plugin add` 会自动应用。
+包内自带 `cordis.patch.yml`，内容和上面一样，`dsh plugin add` 会自动应用。
 
 ---
 
 ## 本机 Ollama（v1.11.0）
 
-在「设置搜索」页开启「AI 联想搜索」，将「接口类型」选为「Ollama（本机）」：
+在「设置搜索」页打开「AI 联想搜索」，把「接口类型」选成「Ollama（本机）」，要填的东西不多。
 
-- **Base URL**：默认 `http://127.0.0.1:11434`，也可填写自定义端口；支持根地址、`/api`、`/api/chat` 和 `/v1`。
-- **模型名**：点「获取模型」从服务返回的模型中选择，或手动输入完整模型名（包括标签），可用 `ollama list` 查看。
-- **API Key**：无需填写，Ollama 请求不会携带原有云端密钥。
+- **Base URL**。默认 `http://127.0.0.1:11434`，端口可以自己改。填根地址、`/api`、`/api/chat` 或 `/v1` 都能识别。
+- **模型名**。点「获取模型」从服务返回的列表里挑，也可以手动敲完整模型名（包括标签），用 `ollama list` 能看到手头有哪些。
+- **API Key**。不用填，发往 Ollama 的请求不会带上原来那套云端密钥。
 
-保存后可用「测试接口」检查连接。本地模型首次加载可能较慢，Ollama 请求的超时时间为 120 秒；取消搜索会中止请求。
+保存后可以点「测试接口」看看通不通。本地模型第一次加载可能比较慢，Ollama 请求的超时时间定在 120 秒，搜索中途取消会中止这次请求。
 
-插件不会安装或启动 Ollama，也不会下载模型。使用时需自行准备已运行的 Ollama 服务和模型。请求由浏览器发出，因此「本机」指浏览器所在设备，而非远程 DSH 服务器。
+请求由浏览器直接发出，所以「本机」说的是浏览器所在的那台机器，不是 DSH 服务器所在的机器。插件不会安装或启动 Ollama，也不会下载模型，服务和模型都要自己准备好。
 
-连接被拒绝时检查服务地址；跨域访问失败时，将当前 DSH 页面的确切来源（如 `http://127.0.0.1:3080`）加入 Ollama 的 `OLLAMA_ORIGINS`，并重启 Ollama。不要使用不必要的通配符来源。非本机地址仍要求 HTTPS。
+连不上先看服务地址对不对。浏览器报跨域错误时，把当前 DSH 页面的确切来源（例如 `http://127.0.0.1:3080`）加进 Ollama 的 `OLLAMA_ORIGINS`，重启 Ollama 再试，别图省事写通配符来源。Ollama 不在本机时，地址仍然要求 HTTPS。
 
 ---
 
-
 ## 包结构
 
 ```
@@ -116,35 +127,34 @@ scripts/log.test.mjs 宿主日志文件与路由回归测试（临时目录，
 ## 开发
 
 ```bash
-npm test   # 结构检查及 Ollama / OpenAI / Anthropic 模拟接口回归测试
+npm test       # 结构检查及 Ollama / OpenAI / Anthropic 模拟接口回归测试
+npm run compat # 针对本机已安装的 Harness 核对兼容性（服务名、Remote 描述符、slot、主题令牌、路由、DeepSeek 常量）
 ```
 
-> 历史说明：v1.1 及之前仓库曾附带 `dsh-settings-search.js`（会话内
-> `cordis_define` 动态插件源）。因与正式包代码长期双份维护漂移，已于 v1.4.1
-> 移除；如需动态用法可从 git 历史（tag `v1.4.0`）取回参考。
+`npm run compat` 直接读本机安装包（默认自动查找，也可 `--asar <app.asar>` 或 `DSH_ASAR=<app.asar>`），
+Harness 升级后先跑一遍就能知道哪些「非公开契约」变了——它检查的正是这个插件依赖、但不属于任何 npm API 的那些接口。
+
+> 历史说明。v1.1 及更早的版本里，仓库还带一个 `dsh-settings-search.js`（会话内 `cordis_define` 动态插件源）。它和正式包长期分头维护，两边越改越不像，v1.4.1 已经删掉。想参考动态插件的写法可以翻 git 历史，tag `v1.4.0` 里还在。
 
 ## 反馈与贡献
 
-欢迎提交 **Issue** 反馈 Bug、功能建议或使用疑问：
-[GitHub Issues](https://github.com/objectivex666/dsh-settings-search/issues)，
-也欢迎直接发起 [Pull Request](https://github.com/objectivex666/dsh-settings-search/pulls)——
-动手前请先读一遍 [贡献指南](./CONTRIBUTING.md)（结构、代码约定、测试与发布流程）。
+用着不对劲、想到什么功能，或者只是没搞明白怎么用，都可以开 [GitHub Issues](https://github.com/objectivex666/dsh-settings-search/issues) 说。也欢迎直接提 [Pull Request](https://github.com/objectivex666/dsh-settings-search/pulls)，动手改代码之前先看一眼 [贡献指南](./CONTRIBUTING.md)，结构、代码约定、测试和发布流程都写在里面。
 
-提交 Issue 时，请尽量完整地提供以下信息，便于定位与复现：
+提 Issue 时把这些写全，定位和复现都会快很多。
 
-- **问题描述**：期望的行为与实际发生的情况。
-- **复现步骤**：一步步说明如何复现，包括触发关键词、所在设置页等。
-- **日志**：在「设置搜索」页的「日志与导出」中导出最近的搜索/运行日志并粘贴（API Key 不会被记录，可放心提供）；控制台报错也请一并附上。
-- **环境信息**：DSH 版本、Node.js 版本、插件版本（可在「设置搜索」页查看）、操作系统与浏览器。
-- **截图/录屏**：涉及界面表现时，附上截图或录屏更有帮助。
+- **问题描述**。你期望发生什么，实际发生了什么。
+- **复现步骤**。一步步写清楚怎么做，包括输入的关键词和当时所在的设置页。
+- **日志**。在「设置搜索」页的「日志」区块里点「导出日志」，把最近的搜索与运行日志贴上来，API Key 不会被记录，可以放心发，控制台里的报错也一并附上更好。
+- **环境信息**。DSH 版本、Node.js 版本、插件版本（「设置搜索」页能看到）、操作系统和浏览器。
+- **截图或录屏**。跟界面表现有关的问题，截图比文字描述清楚。
 
 ## 更新日志与发布
 
-每次版本更新需同时更新 GitHub Release 与 git tag，正文为双语，并写明「新功能」与「修复」：
+每次版本更新要同时更新 GitHub Release 和 git tag，正文双语，写清「新功能」与「修复」。
 
-- 更新 [CHANGELOG.md](./CHANGELOG.md)（中文）与 [CHANGELOG.en.md](./CHANGELOG.en.md)（英文），两者各含 `### ✨ 新功能 / Features` 与 `### 🐛 修复 / Fixes`。
-- 同步 `package.json` 与 README 的版本号，按 `vX.Y.Z` 打 tag 并推送；GitHub Actions 会同时发布到 npm（`npm-publish.yml`）并创建双语 GitHub Release（`release.yml`）。
-- 本地预览 release 正文：`node scripts/release.mjs --version <ver>`
-- 实际打 tag 并发布：`node scripts/release.mjs --version <ver> --publish`（需 `gh` CLI 且已登录）
+- 更新 [CHANGELOG.md](./CHANGELOG.md)（中文）和 [CHANGELOG.en.md](./CHANGELOG.en.md)（英文），两边各要有「新功能」和「修复」两节，英文对应 Features 与 Fixes。
+- 把 `package.json` 的 `version` 和 `lib/client.js` 里的 `PKG_VERSION` 一起改掉（`npm test` 会校验两者一致），功能列表旁边新加的版本标注也顺手补上，然后按 `vX.Y.Z` 打 tag 并推送。GitHub Actions 会同时发 npm（`npm-publish.yml`）并创建双语 GitHub Release（`release.yml`）。
+- 本地预览 release 正文用 `node scripts/release.mjs --version <ver>`
+- 打 tag 并发布用 `node scripts/release.mjs --version <ver> --publish`（需要装好 `gh` CLI 并已登录）
 
-> 未带 `--publish` 时脚本只校验并打印 release 正文，不会创建 tag、推送或发布。
+> 不带 `--publish` 时，脚本只校验并打印 release 正文，不会创建 tag、推送或发布。