文档站点全文搜索功能 - 对齐清单

[cc-hearts]

背景

当前 @antdv-next/docs 文档站点缺少跨页面全文搜索能力：Header 仅有导航、主题切换、语言切换与 GitHub 入口（见 packages/docs/src/layouts/docs/components/header-actions.vue），用户无法在站内搜索文档内容/组件/API。

参考实现位于同工作区的 antdv-next 主库文档站（/Users/carl/Desktop/antdv-next/antdv-next/docs），其已有一套成熟的 flexsearch 全文搜索方案，技术栈与 antdv-next-x docs 高度一致（Vite + Vue 3 + antdv-next + @mdit-vue + markdown-it），可直接参考移植。本 issue 用于追踪该搜索能力的对齐工作。

参考实现（antdv-next 主库 docs）

能力	参考文件
搜索索引生成脚本（构建时）	docs/scripts/gen-search.ts
DocSearch 搜索组件	docs/src/components/doc-search/index.vue
组件总览本地搜索	docs/src/components/component-overview/index.vue
图标搜索（主库特有，X 暂不需要）	docs/src/components/icon-search/IconSearch.vue
Header 集成 DocSearch	docs/src/layouts/base/header.vue（.ant-doc-header-search）

参考方案要点

• 索引方案：flexsearch 的 Document 索引；中文用 Charset.CJK + full 分词，英文用 Charset.Default + forward。
• 构建时生成：gen-search.ts 扫描 src/pages/**/*.{zh-CN,en-US}.md，用 markdown-it + @mdit-vue/plugin-frontmatter|headers|title 解析 frontmatter / headers / title，按 H2/H3 切分 section，每段产出 { id, title, description, content, headers, path, section }，index.export() 导出 JSON 到 public/search.cn.json 与 public/search.en.json。
• 运行时检索：DocSearch 按当前 locale 懒加载对应索引，支持结果高亮、键盘上下导航（activeIndex）、防抖（useDebounceFn）、点击外部关闭（onClickOutside）、按 section 分组（components/docs/...）带图标。

待对齐清单

1. 依赖补齐

antdv-next-x docs 已具备：@mdit-vue/*、markdown-it、@antdv-next/icons、antdv-style、pinia、@vueuse/core（doc-header.vue 已在用）。
需新增（加入 pnpm catalog 并在 packages/docs 引入）：

• flexsearch
• tinyglobby

2. 搜索索引生成脚本

新建 packages/docs/scripts/gen-search.ts，移植自主库同名脚本，并适配 antdv-next-x 的路由规则：

• md 命名规则一致（*.zh-CN.md / *.en-US.md）✅
• ⚠️ 路由后缀差异：antdv-next-x 的 router/docs.ts 中英文分别用 -cn / -en 后缀；而主库 gen-search.ts 的 resolveRoutePath 英文为无后缀。移植时需将英文分支改为追加 -en，否则搜索结果跳转 404。
• 输出 public/search.cn.json / public/search.en.json。

3. DocSearch 组件

新建 packages/docs/src/components/doc-search/index.vue，移植自主库，并做以下项目化适配：

• 样式由主库的 less + ant-doc-* 类名改为 antdv-style 的 createStyles（参考 antdv-next-x 已有的 components/component-overview/index.vue 写法）。
• locale 联动：复用 @/composables/use-locale 与 @/stores/app 的 locale。
• section 图标改用 @antdv-next/icons。

4. Header 集成

在 packages/docs/src/layouts/docs/components/ 下接入 DocSearch：

• 桌面端：置于 doc-header.vue 的 HeaderNavigation 与 HeaderActions 之间（对齐主库 .ant-doc-header-search 位置）。
• 移动端：在 header-actions.vue 的抽屉/展开区内提供搜索入口。

5. 构建脚本接入

packages/docs/package.json 的 build 在 vp build . 之前追加索引生成，与已有 generate-llms*.mjs 并列：

- "build": "vp run --filter @antdv-next/x build:token && node ./scripts/llm/generate-llms-semantic.mjs && node ./scripts/llm/generate-llms.mjs && vp build ."
+ "build": "vp run --filter @antdv-next/x build:token && node ./scripts/llm/generate-llms-semantic.mjs && node ./scripts/llm/generate-llms.mjs && node ./scripts/gen-search.ts && vp build ."

6. i18n 文案

搜索占位符、"无结果"、分组标题等文案接入 use-locale（中/英）。

已对齐项（无需重复）

• ✅ 组件总览本地搜索：packages/docs/src/components/component-overview/index.vue 已实现关键词过滤 + affix 吸顶（createStyles 写法），与主库 component-overview 对齐，可直接作为 DocSearch 的样式参考。

技术栈映射

antdv-next 主库 docs	antdv-next-x docs
less + ant-doc-* 类名	antdv-style createStyles + uno + clsx
英文路由无后缀	英文路由 -en 后缀
vite 直跑	vp（Vite+）
flexsearch、tinyglobby	需新增

验收标准

• Header 出现搜索框，输入关键词可跨所有文档页检索（标题/正文/小节）。
• 搜索结果高亮命中词、支持键盘 ↑↓ 选择、Enter 跳转、Esc/点击外部关闭。
• 中英文 locale 切换后加载对应索引，结果路由正确（-cn / -en 后缀无误，不 404）。
• public/search.{cn,en}.json 在 build 时自动生成。
• vp check 与 vp test 通过。

下一步行动

1. 新增 flexsearch、tinyglobby 依赖。
2. 移植并适配 gen-search.ts（重点修正英文路由后缀）。
3. 移植 DocSearch 组件（createStyles 化）。
4. Header 集成 + i18n 文案。
5. 接入 build 脚本，验证 vp build 产物。

[zha-ji-tui]

@cc-hearts 指派给我吧