ClawHub 发布者搜索缺陷复现与句柄前缀检索修复验证

后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载listPublicPage是 ClawHubOpenClaw 的 Skill Plugin Registry对外提供发布者publisher公开列表与搜索的 Convex query。本文以仓库中的验证报告 .proof/report.md 为主线完整还原一次生产缺陷先复现、后修复、再回归验证的过程在真实部署数据上确认vyctorbrzezowski、vincentkoc等明明存在却搜不到的发布者剖析其根因搜索仅依赖热门窗口讲解源码中精确匹配 句柄前缀检索的修复逻辑并给出可一键执行的回归测试命令。读完本文你将能复现同类搜索漏检问题并理解 ClawHub 发布者检索的底层索引设计。一、背景ClawHub 的公开发布者列表与搜索入口ClawHub 的公开发布者浏览/搜索能力由convex/publishers.ts中的listPublicPagequery 提供定义于 convex/publishers.tsexport const listPublicPage query({ args: { kind: v.optional(v.union(v.literal(user), v.literal(org))), official: v.optional(v.boolean()), query: v.optional(v.string()), paginationOpts: paginationOptsValidator, }, handler: async (ctx, args) { // ... const numItems clampInt(args.paginationOpts.numItems, 1, 50); const queryText args.query?.trim(); // ... }, });关键行为分两种模式浏览模式无query按下载量/安装量取活跃发布者的 Top 列表搜索模式有query进入检索流程返回page、counts、globalCounts、continueCursor、isDone等分页信息numItems被clampInt限制在 150 之间。二、缺陷现场Profile 存在却搜不到验证报告 .proof/report.md 记录了在 Convex 部署环境wry-manatee-359.convex.cloud上、后端修复部署之前所做的只读复现报告状态标注为pass (production bug reproduction before backend deploy)。用listPublicPage分别查询四个句柄得到如下结果QuerylistPublicPagehandlesvyctor[]vyctorbrzezowski[]vincent[vincentchan]vincentkoc[]也就是说vyctorbrzezowski与vincentkoc是真实存在、却在搜索中消失的发布者而查询vincent命中的是前缀相同的另一位发布者vincentchan。报告同时列出了这两个被漏检 Profile 的实际情况vyctorbrzezowski→ 5 skills、1 package、46 installsvincentkoc→ 有公开 profile但 0 个已发布 skills。前者有实打实的发布内容与安装量后者只是一个空的公开主页。两者在缺陷环境中均无法被搜索到这正是本次验证要复现并钉死的生产缺陷。三、根因热门窗口之外的发布者不可见复现数据背后的根因藏在listPublicPage无查询时的浏览取数逻辑getActivePublisherRowsByDownloads中见 convex/publishers.tsconst MAX_PUBLIC_PUBLISHER_LIST_LIMIT 500; const LEGACY_PUBLISHER_DOWNLOAD_FALLBACK_LIMIT MAX_PUBLIC_PUBLISHER_LIST_LIMIT; // 1) 按总下载量倒序取前 500 // index: by_active_total_downloads // 2) 再按总安装量倒序取前 500兼容未回填下载量的旧数据 // index: by_active_total_installs // 3) mergePublisherRows 按 _id 去重合并修复前的搜索逻辑只在这份热门窗口Top 500内做过滤与匹配。于是任何落在窗口之外的发布者——例如只有 46 次安装的vyctorbrzezowski、0 安装的vincentkoc——都直接不可见即使它们存在、甚至拥有公开内容和发布物。这解释了报告中的全部[]vyctor、vyctorbrzezowski、vincentkoc都在窗口外vincent之所以能命中vincentchan是因为该发布者恰好进入了窗口或前缀命中了窗口内的记录。四、修复精确匹配 句柄前缀检索的合并取集当前仓库源码中搜索模式的取数已改为collectActivePublisherRowsForListPage见 convex/publishers.ts其流程为句柄归一化normalizePublisherHandle(queryText)——去除首尾空白、剥离前导、转小写定义于 convex/lib/publishers.ts。这保证 Vyctor 与vyctor等价精确匹配getPublisherByHandle走publishers表的by_handle唯一索引convex/lib/publishers.ts前缀匹配对user、org两种 kind 分别执行queryActivePublishersByHandlePrefix使用by_active_kind_handle索引做字典序范围扫描convex/publishers.tsfunction publisherHandlePrefixUpperBound(value: string) { return ${value}\uffff; } // .gte(handle, handlePrefix).lt(handle, publisherHandlePrefixUpperBound(handlePrefix)) // .take(MAX_PUBLISHER_HANDLE_PREFIX_CANDIDATES) // 100以\uffffUnicode 最大码位作为上界等价于所有以该前缀开头的句柄并限制候选数为MAX_PUBLISHER_HANDLE_PREFIX_CANDIDATES 100 4.三路合并去重浏览窗口行、精确命中行、前缀命中行按_id合入一个 Map最终返回并集。合并后仍保留两道语义过滤matchesPublisherQueryconvex/publishers.ts对displayName handle bio的小写拼接串做子串包含匹配保证搜索结果与展示字段一致includeEmptyPublishers Boolean(queryText)convex/publishers.ts搜索模式下允许展示0 发布内容的公开 Profile——这正是vincentkoc这类空主页也能被搜到的关键开关。排序由comparePublisherListItems负责下载量 → 星标 → 发布数 → 显示名分页仍按offset/numItems切片完成。五、只读验证如何在 Convex 环境钉死生产缺陷报告展示的是一种可复用的缺陷钉死方法后端修复部署之前直接对线上 Convex 部署wry-manatee-359.convex.cloud发起只读查询。在 Convex Dashboard 或脚本中对listPublicPage传入{ query: vyctorbrzezowski, paginationOpts: { cursor: null, numItems: 25 } }若返回空页而 Profile 实际存在即可在生产环境层面确认缺陷避免本地能过、线上不行的争议。本次四个查询的对照结果vyctor/vyctorbrzezowski/vincentkoc为空vincent命中vincentchan既复现了缺陷也锁定了修复后必须满足的行为基线前缀与精确句柄都必须可检索。六、回归测试与验证命令报告给出的验证命令为VITE_CONVEX_URLhttps://example.invalid bunx vitest run convex/publishers.test.ts通过注入一个无效的VITE_CONVEX_URL确保测试进程不会触达真实 Convex 后端随后用bunx vitest执行发布者模块的完整测试套件。convex/publishers.test.ts中与本次缺陷一一对应的两个用例finds publishers outside the popular install window via handle prefix searchconvex/publishers.test.ts构造 500 条高安装量热门行模拟vincentkoc0 skills、0 installs、只有公开 Profile在窗口之外断言listPublicPage({ query: vincent })能通过前缀检索返回[vincentkoc]且counts为{ all: 1, individuals: 1, organizations: 0 }finds publishers with published skills outside the popular install windowconvex/publishers.test.ts模拟vyctorbrzezowski5 skills、1 package、46 installs分别以前缀vyctor与精确句柄vyctorbrzezowski查询断言两种输入都能命中该发布者——同时验证了报告中的Profile 存在、内容统计可反序列化这一前提。此外测试还覆盖了浏览模式的by_active_total_downloads/by_active_total_installs双索引合并、officialPublishers的by_created官方过滤以及includeEmptyPublishers开关的行为可作为后续修改发布者检索逻辑时的回归防线。七、结论本次验证与修复形成了一个完整的闭环先在生产数据上只读复现.proof/report.md中的四组查询对照再定位到搜索仅依赖 Top 500 热门窗口的根因最终通过精确匹配 句柄前缀范围扫描 浏览窗口合并的取集逻辑与includeEmptyPublishers开关修复漏检并由两个以真实被漏检句柄命名的单元测试vincentkoc、vyctorbrzezowski钉死回归。对任何基于热门 Top N 窗口内过滤实现的搜索而言这一案例都值得作为漏检风险清单中的典型条目搜索必须脱离浏览窗口独立检索且空内容 Profile 是否可搜应由产品语义显式决定。赞分享后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载相关推荐ClawHub 插件发布校验问题排查与修复指南从 clawhub package validate 发现到发布通过ClawHub 插件发布校验问题排查与修复指南从 clawhub package validate 发现到发布通过 本文是 ClawHubOpenClaw后端前端AI 技能AI 插件搜索引擎local-deep-research 1.9.3 发布解析OrcaRouter 接入、DNS 重绑定加固与索引/检索缺陷修复local deep research 1.9.3 发布解析OrcaRouter 接入、DNS 重绑定加固与索引/检索缺陷修复 本文解读 local deepAI应用人工智能大模型RAGAI Agent深度研究本地部署后端前端OpenProject 6.1.1 发布说明工作包、时间线与搜索模块的关键缺陷修复解析OpenProject 6.1.1 发布说明工作包、时间线与搜索模块的关键缺陷修复解析 本指南基于 OpenProject 仓库中的 6.1.1 官方发布说明后端前端项目管理企业应用协同办公上一篇最完整vscode-drawio使用手册从安装到高级功能全解析下一篇【免费下载】 Diffy 使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考