XERJ 用户反馈语料库实战:02-discover-and-kql 分类如何量化 Kibana 的 Discover/KQL 痛点
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 | 1602 | Tools & Info for Sysadmins - Mega List of Tips, Tools, Books, Blogs & More | |
| 2 | 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 | 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 | 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 | 36 | (Grafana) Loki vs Kibana (ELK) |
从这张表可以读出几个信号:
- Discover 表格的可操作性是长期痛点:"Resizable discover table columns"(162 分)是
top-asks.md里按 GitHub reactions 排名的前 7 大 feature request 之一(见 top-asks.md)。 - "查不出结果 / 精确匹配 / 字段唯一值"类问题集中在 Stack Overflow:Top 20 里 4 条 stacko 条目全部落在"查询表达力与结果可预期性"上(no results、unique values、exact match),这正是 KQL/Lucene 语法学习成本的外在表现。
- 向量检索(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"生成段完整解释了它的每个字段从哪来:
- 读入:遍历
user-feedback/kibana/sources/*/enriched.jsonl(classify 阶段的产物),逐行JSON.parse,得到全部 enriched 条目(含category、sentiment、score、tags字段)。 - 聚合:按
it.category分桶,同时维护sentimentByCategory(negative/neutral/positive 三计数器)与tagCounts(标签频次)。 - 排序取 Top 20:对当前类别的条目按
(b.score || 0) - (a.score || 0)降序排序后slice(0, 20)——这就是上表的由来,分数即原帖在 HN/Reddit/GitHub 的点赞或 reactions。 - 渲染 Markdown:标题截断 80 字符(
trim函数),来源名截 6 字符,输出 Top 20 表格 + 该类别内前 12 个高频标签表。 - 落盘:
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 友好)、强制每个功能决策必须指向语料中的具体条目(杜绝猜测性功能)。