XERJ 用户反馈语料库实战:02-discover-and-kql 分类如何量化 Kibana 的 Discover/KQL 痛点

原创2026-10-17 15:40:301,904 阅读
文章标签:搜索引擎全文检索向量数据库数据库后端MCP 服务Agent 记忆人工智能日志分析dsh-plugin

XERJ 用户反馈语料库实战:02-discover-and-kql 分类如何量化 Kibana 的 Discover/KQL 痛点

本文以 XERJ 仓库中 user-feedback/kibana/categories/02-discover-and-kql/ 分类报告为主体,讲解一份"真实用户反馈语料库"是如何组织、统计与分類的:1,740 条来自 GitHub、Stack Overflow、Reddit、Hacker News 和 Elastic 官方论坛的反馈如何被关键词分类器归入 "Discover / KQL" 这一查询体验维度,Top 20 高热度条目与 Top 标签揭示了哪些具体痛点,以及这套语料如何直接映射为 XERJ 控制台的 search-discover 面板设计决策。读完你可以掌握:用确定性关键词规则对 UGC 做类别/情感/标签三维标注的完整管线设计,以及如何把"用户痛点语料"转译成产品功能清单。

一、这个分类报告是什么:1,740 条反馈的"体检单"

user-feedback/kibana/categories/02-discover-and-kql/README.md 本身是一份机器生成的分类统计报告,头部三行即给出核心数字:

  • 1,740 items(该类别下的反馈条目总数)
  • negative 736 · neutral 798 · positive 206(情感分布,负反馈占比 42%)
  • 条目指针存于 pointers.jsonl,原始正文在 user-feedback/kibana/sources/<src>/enriched.jsonl

它对应的产品痛点维度定义在 TAXONOMY.md 中,02-discover-and-kql 属于 QUERYING 痛点轴,覆盖:Discover 视图、搜索栏、KQL / Lucene 语法、字段选择、scroll/分页、saved search、深度分页、"无结果"困惑等场景。在整个 15,282 条反馈的语料库中,它是按条数排第 4、按负反馈占比排第 5 的类别(见 INDEX.md 与 kibana 语料库总览)。

二、Top 20 by score:这个类别里用户吵得最凶的是什么

分类报告的核心内容是"按原帖热度(点赞/反应/评分)排名的前 20 条"。完整继承原表如下(外部站点链接按规范省略,可用指针文件回溯原文):

# 来源 分数 标题(截断至原文长度)
1 reddit 1602 Tools & Info for Sysadmins - Mega List of Tips, Tools, Books, Blogs & More
2 reddit 400 Tools & Info for Sysadmins - NAC Solution, Tech Library, SSH Client & More
3 github 162 Resizable discover table columns
4 github 144 Investigate various implementations of ann search for vector fields
5 github 143 [Dashboard] Allow Authors to Limit Interactivity
6 reddit 132 Tools & Info for MSPs #1 - Mega List of Tips, Tools, Books, Blogs & More
7 hacker 125 Show HN: Open-source Kibana alternative for logs and traces in ClickHouse
8 stacko 83 Kibana doesn't show any results in "Discover" tab
9 stacko 74 How to list unique values of a particular field in Kibana
10 stacko 67 Kibana query exact match
11 github 64 Custom drilldown links for a dashboard panel
12 github 57 Ability to change the index pattern on a visualization
13 github 54 Support dynamic interval and fixed buckets for histogram aggregation
14 stacko 48 Kibana server is not ready yet
15 github 44 Possibility to hide time field in Discover view
16 github 41 Create an API to manage synonyms
17 reddit 40 ELK a pain in the ass
18 stacko 37 Elasticsearch Docker: flood stage disk watermark [95%] exceeded
19 github 36 Add 'key' field to function_score query function for explanation retrieval
20 reddit 36 (Grafana) Loki vs Kibana (ELK)

从这张表可以读出几个信号:

  1. Discover 表格的可操作性是长期痛点:"Resizable discover table columns"(162 分)是 top-asks.md 里按 GitHub reactions 排名的前 7 大 feature request 之一(见 top-asks.md)。
  2. "查不出结果 / 精确匹配 / 字段唯一值"类问题集中在 Stack Overflow:Top 20 里 4 条 stacko 条目全部落在"查询表达力与结果可预期性"上(no results、unique values、exact match),这正是 KQL/Lucene 语法学习成本的外在表现。
  3. 向量检索(ann search)与 KQL 的边界开始被用户讨论:第 4 条 GitHub issue 说明社区已在关注"向量字段如何做近似最近邻"——XERJ 把 semantic/hybrid 查询直接做进 Discover 面板,正是回应这条线。

三、Top tags:这个类别里高频出现的 12 个主题词

原报告的标签统计同样值得完整保留(标签由分类器从正文/标题中正则抽取,计数覆盖类别内全部 1,740 条而非仅 Top 20):

标签 计数
discover 750
kql 37
license 26
saved-objects 24
alerting 23
anomaly 15
apm 8
oom 6
time-picker 5
dark-mode 4
fleet 4
ml 3

discover 标签 750 次出现,意味着"Discover 页面慢 / 卡 / 不好用"是本类别最集中的抱怨面;license、oom、time-picker 等次级标签则说明 Discover 的痛点经常和授权、内存、时间选择器耦合出现(跨源聚类文件 cross-source-clusters.md 里的 kql-confusion 簇即捕捉到了"KQL 值补全拖垮集群"这类典型抱怨)。

四、报告是怎么生成的:stats.mjs 的完整继承逻辑

这份 README 不是手写的。stats.mjs 的"per-category README"生成段完整解释了它的每个字段从哪来:

  1. 读入:遍历 user-feedback/kibana/sources/*/enriched.jsonl(classify 阶段的产物),逐行 JSON.parse,得到全部 enriched 条目(含 category、sentiment、score、tags 字段)。
  2. 聚合:按 it.category 分桶,同时维护 sentimentByCategory(negative/neutral/positive 三计数器)与 tagCounts(标签频次)。
  3. 排序取 Top 20:对当前类别的条目按 (b.score || 0) - (a.score || 0) 降序排序后 slice(0, 20)——这就是上表的由来,分数即原帖在 HN/Reddit/GitHub 的点赞或 reactions。
  4. 渲染 Markdown:标题截断 80 字符(trim 函数),来源名截 6 字符,输出 Top 20 表格 + 该类别内前 12 个高频标签表。
  5. 落盘:fs.writeFileSync(path.join(dir, 'README.md'), md.join('\n') + '\n'),每个类别目录重写一份。

配套入口在 INDEX.md 的 Pipeline 小节:

node pipeline/collect.mjs   # pull from APIs, write sources/<src>/raw.jsonl
node pipeline/classify.mjs  # rewrite enriched.jsonl + category pointers
node pipeline/stats.mjs     # rewrite this file + per-category READMEs

零依赖,纯 Node ESM + 内置 fetch;JSONL 按 id 去重、可重复运行。

五、classify.mjs:02-discover-and-kql 的关键词规则与判定流程

分类器 classify.mjs 是这份报告的数据源头。它对本类别使用的加权关键词规则(片段摘录,权重越高信号越强):

['02-discover-and-kql', 'QUERYING', [
  ['discover', 3], ['kql', 3], ['lucene query', 2],
  ['search bar', 2], ['saved search', 3],
  ['scroll api', 2], ['document table', 2],
  ['from + size', 1], ['deep paging', 2],
  ['no results', 1], ['kibana query language', 3],
  // soft
  ['lucene', 2], ['query', 1], ['wildcard query', 2],
  ['query syntax', 2], ['dsl query', 1],
]],

打分与判定逻辑(对应 classify() 函数):

  • 噪声前置过滤:Failing test: / flaky test: / CI backport 等模式直接归入 99-noise,不计入用户反馈。
  • 加权子串打分:scoreText() 对标题+正文(截断前 5,000 字符)逐条做大小写不敏感的子串匹配,命中即累加权重;也支持 { rx: /regex/i, w: 2 } 形式的正则规则。
  • 主类别选择:15 个类别打分后降序排列,最高分 ≥ 1 才成立主类别;若未命中任何规则但文本提到 "kibana",落入兜底类别 10-docs-and-ux;否则进 99-uncategorized 待人工分诊。
  • 次级类别:其余得分 > 0 的前三名写入 secondary_categories。这些次级条目会带 _secondary: true 标记追加进各类别的 pointers 文件(用 jq -r 'select(._secondary)' user-feedback/kibana/categories/02-discover-and-kql/pointers.jsonl 即可过滤出跨类别引用)。
  • 情感:朴素词库法。NEG 词表(broken、slow、oom、unusable…)与 POS 词表(love、great、reliable…)各自计数,neg > pos * 1.5 判 negative,pos > neg * 1.5 判 positive,否则 neutral——这也解释了报告头部的 736/798/206 三组数字。README 的"Honest limits"一节 明确声明这是 naive lexicon,绝对值要谨慎使用,跨类别的相对排序才可靠。
  • 标签:extractTags() 用一组固定正则打标(\bkql\b、/discover\b/、/time picker/i 等),产生 Top tags 表里的 12 个标签。

确定性是这套管线的硬约束:规则表、打分、排序全部无随机性,"re-running the classifier reassigns — pointer files are deterministic"(TAXONOMY.md),报告因此可随每次 collect 刷新而整体重算,不存在人工编辑漂移。

六、pointers.jsonl:从"统计行"回溯到"完整正文"

按 SCHEMA.md 的设计,categories/<slug>/pointers.jsonl 是 raw.jsonl 的投影,每行一条:

{ "id": "disc-672313", "source": "discourse", "score": 9,
  "posted_at": "2019-07-05T06:10:47.890Z",
  "tags": [], "title": "Terribly slow kibana query", "_secondary": true }

真实文件 pointers.jsonl 共 2,941 行(含 1,740 条主类别条目 + 次类别引用)。回溯方法:拿 id(形如 disc-672313、gh-<issue>、hn-<id>)到对应 user-feedback/kibana/sources/<source>/enriched.jsonl 中查找同 id 记录,即可拿到 body、source_url、author、quote 等完整字段。JSONL 而非 per-file markdown 的选择理由也写在 SCHEMA 里:5,000+ 条目要保持 grep 友好、rsync 友好、更新便宜。

七、从痛点语料到产品决策:design-inputs 如何消费这个类别

语料库的最终用途在 design-inputs.md 中兑现:每个类别的 Top 痛点被逐条映射到一个 XERJ 实现点。02-discover-and-kql 一节给出的映射是:

XERJ.ai response: web/src/dashboards/search-discover.js · live query box, 8 query types, plan tree

对应条目为:Dashboard 交互限制(143 分)、Custom drilldown links(64 分)、修改可视化 index pattern(57 分)、隐藏 Discover 时间字段(44 分)。

XERJ 侧的实际实现在 search-discover.js 中可以直接对照验证,文件头注释写清了设计立场:索引选择器跟随引擎真实索引列表、facet 用 mapping 里真实存在的 keyword 字段做 terms 聚合、REQUEST 面板展示由同一个 buildSearchBody 函数构建的请求体("preview and execution cannot drift")、没有样本数据集——查询在途就显示在途,失败就显示错误和 0 行。查询类型定义在 search-body.js:

export const QUERY_TYPES = ['match', 'term', 'range', 'prefix', 'phrase', 'semantic', 'hybrid'];

knn 被刻意排除——原始 kNN 需要查询向量,控制台无法生成,"一个声称 knn 却执行 match_all 的预览正是被 #923 review 追责的那种不一致"。对照 Top 20 里的痛点(exact match 语义、字段唯一值、可预期的结果),这套"所见即所执行"的查询面板正是对 02-discover-and-kql 类别痛点清单的逐条回应;而语料库自身的筛选原则(README:"If the answer is 'nothing', the feature is speculative. If the answer is '12 of these 20', it's worth shipping.")保证了这不是反向推导的营销话术,而是可回溯到具体 issue 编号与分数的工程决策链。

八、复现与扩展指南

在仓库中查看(仓库为只读,以下为查看/复现流程):

# 1. 查看类别报告与指针
less user-feedback/kibana/categories/02-discover-and-kql/README.md
head -5 user-feedback/kibana/categories/02-discover-and-kql/pointers.jsonl

# 2. 按标签过滤该类别下的条目
grep '"kql"' user-feedback/kibana/categories/02-discover-and-kql/pointers.jsonl | head

# 3. 刷新语料(需要网络;GitHub 抓取建议设置 GH_TOKEN,否则第 5 页即停)
cd user-feedback/kibana
node pipeline/collect.mjs --source github --pages 100
node pipeline/classify.mjs
node pipeline/stats.mjs      # 重新生成本报告 + INDEX.md
node pipeline/themes.mjs    # 重新生成 themes/*.md

适用前提与限制(承自语料库自身的诚实声明):情感分类是朴素词库法,对反讽和技术性 "the bug is" 句式会误判,绝对计数仅供趋势参考,类别间相对排序才可靠;分类器是关键词规则而非 LLM(README 指出可在 classify.mjs 中十分钟内换成对 XERJ 自身 embed proxy 的调用,schema 不变);仅采集英文公开数据;GitHub 抓取受 10K 条 API 上限约束(每仓库前 100 页)。

小结

02-discover-and-kql 这份 47 行的 README 背后,是一条"采集 → 确定性分类 → 统计 → 设计输入"的完整证据链:1,740 条反馈、42% 负反馈占比、Top 20 高热度条目与 12 个高频标签共同刻画了 Discover/KQL 这一查询体验维度的痛点分布;而 XERJ 的 search-discover 面板与统一 search-body 构建器,则是这条链落在产品侧的可验证终点。对想借鉴这套方法的人来说,可迁移的核心经验有三条:用加权关键词规则而不是 LLM 做第一版分类器(保证可重放)、把 pointers 与正文分层存储(保持 grep 友好)、强制每个功能决策必须指向语料中的具体条目(杜绝猜测性功能)。

登录后查看全文
xerj