用途：为 bx-sites 站点配置和排查搜索功能。bxsites.yaml 中的 search: true/false 是总开关，与选用的 searchProvider.provider 无关。
内置 provider： local（默认）：纯静态客户端方案。构建时 SearchIndexer 写入 site/search-index.json，每页一条，含标题、URL、frontmatter 标签、各级标题文本、截断的正文纯文本，以及用于结果展示的 section（顶层祖先标题）和 breadcrumb（祖先标题链）。浏览器端 assets/search.js 只拉取一次并建立 MiniSearch 索引，默认开启前缀与容错模糊匹配；权重依次为标题、标签、标题文本、正文。无需服务器、数据库或外部服务。结果展示含高亮标题、面包屑和正文片段；快捷键 / 聚焦侧栏搜索框，Cmd/Ctrl+K 打开命令面板多行浮层（复用同一本地索引），Escape 关闭；上下方向键移动高亮，Enter 打开高亮或首个结果，悬停也会移动高亮。
algolia：需配置 appId、apiKey（仅搜索用公开 key，绝不能用 admin key）、indexName。启用后不再生成 search-index.json，也不随包发布 MiniSearch/search.js，结果来自 Algolia 托管索引（由 DocSearch 爬虫或自有 Algolia Crawler 配置填充，需另行注册，bx-sites 仅接入客户端组件）。各主题渲染空的 #bxsites-search-algolia 容器，layout.bxm 从 jsDelivr 加载 @docsearch/css、@docsearch/js 并调用 docsearch({...})，Cmd+K 由 DocSearch 自带。
pagefind：bin 与 options 均可选（bin 默认 "pagefind"，从 PATH 解析；options 为额外原始 CLI 参数）。pagefind CLI 必须已安装并在 PATH 中，bx-sites 只是调用它，不会代为安装；缺失或失败会让构建报错（BxSites.PagefindFailed），不会静默降级。每次文档树与 sitemap.xml/llms.txt 写完后立即对构建产物 site/ 执行 pagefind --site <siteDir> [...options]，多版本/多语言站点一次索引完成。产物写入 site/pagefind/，自托管、无 CDN；不生成 search-index.json，bxSites search-index 对该 provider 为空操作。
相关命令：bxSites search-index 仅重建索引（build 已包含该步骤）；bxSites search:query --query="..." 可校验实际搜索会命中什么。注意结果中的标题、面包屑、片段均来自构建期文件，页面移动或重新嵌套后，下一次构建（或 search-index）前仍显示旧面包屑。
选型参考：local 无需服务器与账号，适合多数项目、零配置；algolia 需账号，适合想要托管分析与调优的大型站点；pagefind 不需账号，适合多版本/多语言大站点、全文索引，但构建时需 PATH 上有 pagefind CLI。
自定义 provider：searchProvider.provider 接受任意字符串，配置只校验三个内置 provider。搜索 UI 没有插件钩子，内置主题对无法识别的 provider 不渲染任何内容，因此需做项目级主题覆盖：先配 searchProvider 下任意形状的子块（不校验）；用 bxSites theme:new --theme=bootstrap 将内置主题复制到项目 .theme/ 目录；在 .theme/search.bxm 中加挂载分支（如判断 variables.searchProviderName eq 'meilisearch' 时输出 <div id="bxsites-search-meilisearch"></div>）；在 .theme/layout.bxm 中加载客户端并接线，从 variables.siteConfig.searchProvider.meilisearch.* 读回配置；若引擎非爬虫托管，可在插件的 onBuildComplete( siteDir, config ) 钩子里推送文档，注意即使 provider 无法识别，site/search-index.json 仍会生成，可直接作为推送载荷。