读 dsh-free-search 的接管逻辑与配置落点

装上能用只是第一步。当 profile 里已有别的 provider、你手改 cordis.patch.yml、或从旧版本升级时，三件事不清楚就会反复踩坑：它何时接管、provider id 是什么语义、配置落在哪。

接管的第一层：bundle patch 里的显式写入

正常安装（dsh plugin add 或插件管理器）时，插件自带的 bundle patch（cordis.patch.yml）会在配置层显式写入 searchProvider: ddg。

想横向比较同类插件的取舍，可对照完整插件清单与汉化避坑指南。

第二层：运行时兜底，接管官方默认

第一层并不总生效——手工安装、或 profile patch 整体覆盖了 web 条目时，显式写入可能就没了。运行时兜底接手：web.searchProvider 未设置，或仍是出厂默认的 deepseek-official 时自动切换——不允许静默退回官方搜索。

第三层：已有 provider 时不抢占，只告警

如果你或别的插件已显式选择其他 provider，本插件不抢占，只在启动日志输出一条 WARN 与一段可复制的切换 YAML——装插件不等于夺走配置权。处理方式两条：照日志给的 YAML 显式声明，或在插件管理器里停用原来的 provider 条目。别把「搜索没被接管」当成安装失败。

ddg 是 provider id，不是引擎名

searchProvider: ddg 里的 ddg 是本插件注册的固定 provider id，不是「使用 DuckDuckGo 引擎」。它解决「搜索交给哪个 provider」，「用哪个引擎」由设置页 provider 字段决定（可填 bing / baidu / auto 等）。

整段覆盖：为什么 fetchProvider 必须重述

DSH 0.1.2+ 的 patch 语义是「整段覆盖 config」而不是深度合并：你写的 patch 会替换整条 entry 的 config，原 web 条目里没被重述的字段会被静默抹掉。所以 fetchProvider: http 必须一并重述：

配置落点挪过家：从 settings.yaml 到 profile 条目

从 DSH 0.1.7-rc.1 起，配置跟随 profile 的插件条目保存：设置页的改动与 /free-search-engine 的切换，都写进当前 profile 的 cordis.patch.yml 中 web-search-free 条目的 config。

旧版 ~/.dsh/settings.yaml 里的 free-search: 段不会被核心自动导入（importLegacyDocument 只为 ui-developer-tools / ui-onboarding / shell 三段提供映射），原文件会被改名成 settings.yaml.imported。插件启动时会检测它，把可识别字段一次性补种进当前 profile 的条目 config，写一次后不再重复，日志可见 free-search: migrated N field(s)…。

peerDependencies：唯一实例是硬约束

插件对 @deepseek-ai/dsh-settings 与 @deepseek-ai/dsh-tools 使用 peerDependencies，因为 DSH 运行时必须用安装树里的唯一实例。安装一律走 dsh plugin –profile <name> add …，不要把 DSH 核心包复制进 profile 的本地 node_modules：重复副本会让工具调度器失效，表现为「工具时好时坏」。

低版本 DSH 看不到设置入口

行配置插槽 plugins.row.config 需要 DSH 0.1.7-rc.1+。版本不够时，「插件」页里根本没有 web-search-free 行的「配置」入口。解法是升级 DSH；升级前只能改 cordis.patch.yml，或用 tools/ 里那个零依赖的本地切换小工具。

实现侧：lib/index.js 里注册了什么

host 端 lib/index.js 实现 WebSearchProvider，对外暴露 id / available() / search()，内部做引擎路由与自动回退、timeRange 透传；它在 web-search-free 条目上声明可编辑配置（.volatile()）。浏览器端 lib/client.js 是 React 配置卡片与 /free-search-engine（commandUi popupSelect）。id 决定 provider 归属，available() 决定是否被选中，search() 承载回退链，.volatile() 让配置可被设置页改写。

总结

接管分三层：bundle patch 先写、运行时再兜底、已有 provider 时只告警；配置落点也已从 settings.yaml 迁到 profile 条目，认准 cordis.patch.yml 就不会找错地方，详见完整插件清单与汉化避坑指南。再记两条硬约束：整段覆盖要重述 fetchProvider，唯一实例不能有重复副本。

适合与不适合

适合：想读懂接管与配置落点的使用者；profile 里装了多个 provider、需要判断谁在生效的维护者；从旧版 DSH 升级、要迁移 settings.yaml 配置的人。

不适合：只想「装上就能搜」、不愿碰 cordis.patch.yml 的纯使用者；Node 低于 20 或 DSH 低于 0.1.7-rc.1 的环境，行配置入口与补种逻辑可能对不上；有强 SLA 要求的场景——免费引擎存在匿名限流、额度型引擎有月度或日度上限。

标签：dsh-free-search、DeepSeek Harness、provider 接管、cordis patch、配置迁移

本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。