lawn 命令面板搜索架构:Convex SearchIndex + 热键联动,如何实现秒开的全局搜索
lawn 命令面板搜索架构:Convex SearchIndex + 热键联动,如何实现秒开的全局搜索
lawn 是一个面向创意团队的视频审阅(Video Review)平台。打开它的 Dashboard 按下 Cmd/Ctrl+K,弹出的命令面板不仅能执行"上传视频、切换主题"等快捷指令,还能基于 Convex SearchIndex 全文搜索实时检索文件夹和视频。本文带你拆解 lawn 命令面板搜索的完整架构:服务端索引如何构建与同步、文本归一化如何让 "fin cu" 也能命中 "FinalCut_v2.mp4",以及前端热键联动如何做到输入防抖、悬停预热、零闪跳的体验。
为什么值得研究这套搜索架构 🎯
很多产品里的"全局搜索"只是把请求丢给搜索引擎,但 lawn 展示了一套适合中小型 B 端项目的轻量搜索范式:
- 🗂️ 一张索引表:不引入外部搜索引擎,只用 Convex 内置的
searchIndex - 📡 触发器自动同步:视频/文件夹改名、移动、删除,索引自动跟随
- 🧠 自定义分词 + 前缀扩展:弥补 Convex 全文搜索"只匹配最后一个词前缀、无容错"的短板
- ⌨️ 热键联动:
Cmd/Ctrl+K全局唤起 + 页面级命令注册 + 悬停预取,打开即达
核心关键词一览:命令面板(Command Palette)、Convex SearchIndex、全文搜索、热键联动、防抖搜索、路由预热。
一、整体架构:一张图看懂数据流向
lawn 的搜索由两端协作完成:
| 层 | 职责 | 核心文件 |
|---|---|---|
| 后端(Convex) | 维护搜索索引、全文检索、重排序 | convex/search.ts、convex/searchEntries.ts |
| 共享逻辑 | 分词、前缀扩展、匹配打分、高亮区间 | convex/searchText.ts |
| 前端(React) | 热键监听、命令注册、防抖查询、路由预热 | app/routes/dashboard/-commandPalette.tsx、src/lib/commandPalette.tsx |
数据流可以概括为一句话:
视频/文件夹发生写入 → Convex Trigger 拦截 → 生成归一化
searchText写入searchEntries表 → 前端输入框防抖后调用api.search.search查询 SearchIndex → 客户端用同一套打分规则重排 + 高亮展示。
这套设计的巧妙之处在于:索引写入、查询打分、前端高亮三方共用 convex/searchText.ts 里的同一套文本归一化函数,保证了"你搜到的"和"你看到的"永远一致。
二、搜索索引表:Schema 与 SearchIndex 定义
搜索能力的起点是 searchEntries 表,它同时收录文件夹和视频的最新版本,定义在 convex/schema.ts#L182-L196:
searchEntries: defineTable(
v.union(
v.object({ kind: v.literal("folder"), ...searchEntryFields }),
v.object({ kind: v.literal("video"), videoId: v.id("videos"), ...searchEntryFields }),
),
)
.index("by_video_id", ["videoId"])
.searchIndex("search_search_text", {
searchField: "searchText",
filterFields: ["teamId"],
}),
几个值得注意的设计点:
- Union 类型:
kind字段区分 folder / video 两种条目,一份 schema 承载两种实体 searchIndex声明全文索引:searchText是被索引的文本字段,teamId是过滤字段——检索时先按团队过滤再做全文匹配,天然实现了多租户数据隔离- 辅助索引:
by_video_id用于同步时快速定位旧记录;by_team_id_and_kind_and_sort_at支撑"最近视频"列表
查询入口在 convex/search.ts#L78-L107,流程是:取候选(上限 50 条)→ 用 matchRank 按标题匹配度重排(保留 Convex 相关度做同分决胜)→ 全词命中优先于部分命中 → 截取前 20 条返回。另有 recent 查询(convex/search.ts#L109-L124)按 sortAt 倒序返回团队最新 5 个视频,作为面板打开时的默认内容。
三、热键联动:Cmd/Ctrl+K 全局唤起与命令注册
热键的核心实现在 src/lib/commandPalette.tsx#L42-L51。lawn 在 CommandPaletteProvider 中挂了一个全局 keydown 监听:
- 只响应
Cmd/Ctrl + K,且拦截preventDefault,避免触发浏览器自带行为 - 过滤掉输入法合成中(
isComposing)、按键连击(repeat)、Shift/Alt 组合——保证在输入框里打字时快捷键永远不会"吃掉"你敲的字 - 用"toggle"语义:再按一次就关闭
面板的命令分为两类来源,在 app/routes/dashboard/-commandPalette.tsx#L168-L238 中合并:
- 全局命令:团队主页、团队设置、成员管理、上传视频、切换主题等,部分按角色显隐(如 Billing 只有 owner 可见)
- 页面级命令:每个页面通过
useRegisterPaletteCommands在挂载时把自己的操作注册进面板,卸载时自动注销。例如团队页 app/routes/dashboard/-team.tsx#L124 注册了"新建文件夹、邀请成员"等对话框命令,实现面板内容随页面上下文变化
这是典型的 Context + 注册表模式:Provider 持有命令列表数组,页面只负责"挂载期间"贡献命令,面板组件无感知地聚合。
四、前端搜索体验三件套:防抖、稳定值、路由预热
打开面板开始输入后,前端做了三件事让搜索"又快又稳":
1️⃣ 防抖 + 惰性查询
输入内容经过 120ms 防抖(app/routes/dashboard/-commandPalette.tsx#L130-L138)后才触发 useQuery(api.search.search, ...);面板关闭时查询参数为 "skip",不产生任何网络开销。
2️⃣ 稳定值防闪跳
useStableValue(app/routes/dashboard/-commandPalette.tsx#L64-L71)在查询重载期间保留上一次的结果,避免列表随每次击键清空再填充;同时以 teamSlug 为 key,切换团队时立即丢弃旧团队的结果,防止 A 团队的视频闪现到 B 团队的面板里。
3️⃣ 悬停即预热
这是最"杀手级"的细节(app/routes/dashboard/-commandPalette.tsx#L293-L299):当某个结果项被键盘高亮并停留 120ms 后,面板会提前调用 prewarmVideo / prewarmProject(定义在 app/routes/dashboard/-video.data.ts#L101-L110、app/routes/dashboard/-project.data.ts#L88-L96),把目标页面的 Convex 查询提前取好。按下回车跳转时页面瞬间就绪——"搜索 → 直达"之间没有加载屏。
此外每个结果标题都会按查询词做前缀高亮(Highlight 组件,app/routes/dashboard/-commandPalette.tsx#L77-L87),高亮区间由 convex/searchText.ts 的 highlightRanges 计算,连带音符(如 "Café" 的 é)都能正确圈中。
五、文本归一化:让 "fin cu" 命中 "FinalCut_v2.mp4"
Convex 全文搜索有个已知限制:只对小写化、按非字母数字切分后的文本做匹配,且仅对最后一个查询词做前缀匹配,没有容错能力。也就是说直接索引原始标题,用户必须逐词打全才搜得到。
lawn 的解法在 convex/searchText.ts:建索引时就把标题"扩展"成一串宽口径 token。
分词:拆驼峰、拆字母数字边界
tokenize 会把 FinalCut_v2.mp4 拆成:
finalcut, final, cut, v2, v, 2, mp4, mp, 4
即小写化、截断超长词(Convex 会静默丢弃超过 32 字符的词项),再按驼峰/数字边界拆出子词。
前缀扩展:每个词自带所有前缀
buildSearchText(convex/searchText.ts#L30-L38)为每个 token 追加从第 2 个字符开始的所有前缀(final → f, fi, fin, fina, final)。这样查询里的每个词都天然享受前缀匹配,而不是只有最后一个词。
打分:客户端也能复用同一套规则
matchRank(convex/searchText.ts#L48-L58)定义了 0~4 五级匹配度:0 完全相等、1 标题以查询开头、2 每个查询词都命中某个标题词、3 部分命中、4 无命中。后端用它重排候选(convex/search.ts#L95-L102),前端用它过滤命令和团队项(只有 rank ≤ 2 的才展示)。同一套规则贯穿索引、查询、展示三层,这就是搜索"可预期"的来源。
重音折叠:搜 "cafe" 命中 "Café"
归一化先做 NFKD 分解并剥离组合记号,所以输入 cafe 能匹配到 Café interview。这套行为被完整覆盖在测试 convex/search.vitest.ts#L71-L91 中:fin cu、cut、cafe、edit 四个查询逐一验证了前缀、子词、折叠与文件夹搜索。
六、索引同步:触发器维护 + 迁移回填
搜索表如何保持"永远新鲜"?答案在 convex/functions.ts:项目强制所有 mutation 经过一个 Trigger 包装的 db(triggers.wrapDB),于是任何对 projects / videos 表的写入都会经过两道触发器:
projects变更 → syncFolderEntry:名称变化时更新条目,删除时移除条目videos变更 → syncVideoEntry:仅当标题、所属项目、版本状态真正变化时才写索引(上传进度这类高频 patch 会被直接跳过);且只有版本栈中最新版本可被搜到,被取代或已删除的视频自动失去索引条目
对于触发器上线前就已存在的老数据,convex/migrations.ts 定义了两个迁移任务 indexFoldersForSearch / indexVideosForSearch,在每次部署后执行、扫描全表并回填索引,保证新旧数据都能被搜到(迁移与回填逻辑对应测试见 convex/search.vitest.ts#L167-L214)。
安全方面,搜索查询入口 teamForMember(convex/search.ts#L13-L26)做了"软成员校验":非成员会得到空列表而不是报错,既防越权又不暴露团队是否存在。
七、关键文件速查表 📚
| 想改什么 | 去哪里 |
|---|---|
| 热键行为、命令注册机制 | src/lib/commandPalette.tsx |
| 面板 UI、防抖、预热、高亮 | app/routes/dashboard/-commandPalette.tsx |
| 搜索查询与重排逻辑 | convex/search.ts |
| 索引表结构与 searchIndex | convex/schema.ts#L182-L196 |
| 索引条目同步(触发器回调) | convex/searchEntries.ts |
| 分词 / 前缀 / 打分 / 高亮 | convex/searchText.ts |
| 触发器接线与 mutation 包装 | convex/functions.ts |
| 存量数据回填迁移 | convex/migrations.ts |
| 行为验证(单元测试) | convex/search.vitest.ts、convex/searchText.vitest.ts |
总结
lawn 的命令面板搜索架构,本质上回答了一个普遍问题:不依赖外部搜索引擎,如何做出"像搜索引擎一样聪明"的全站搜索?
它的答案可以浓缩为四条经验:
- ✅ 一张宽口径索引表:写入时就把标题拆词、扩前缀、去音符号,把"聪明"前置到索引层
- ✅ 共享一套文本规则:归一化函数同时服务索引、查询、前端展示,三层行为天然一致
- ✅ 触发器 + 迁移双保险:新数据靠 Trigger 实时同步,老数据靠部署后迁移回填
- ✅ 体验细节即架构:120ms 防抖、稳定值防闪跳、悬停 120ms 预热路由——这些"小优化"组合起来,就是"秒开"的全部秘密
如果你正在为产品寻找一套可落地的命令面板 + 全局搜索方案,这套"Convex SearchIndex + 前端热键联动"的实现值得逐文件精读。
