Search Debugging Guide
如何调试 Twitter 搜索工作流里的结果缺失问题，不要太早把锅甩给 endpoint
很多团队一看到结果不完整，就会怀疑 search 坏了。但大多数缺失问题，最后都出在 query 形状、collection window、排除项太激进，或者团队自己对“本来应该抓到什么”没有写清楚。
1. 先写清楚这条流程本来应该抓到什么
当团队能指出具体哪几条帖子本来应该命中却没命中时，debug 会容易很多。
没有这个 baseline，团队很容易随机改 query，最后自己也不知道到底哪里变好了或变坏了。
- 先找几条理论上应该命中的样本。
- 记下当时的 query 和 collection window。
- 把缺失问题和噪音问题分开看。
2. 先复核 query 逻辑，再考虑更深改动
过严的关键词逻辑、排除项和别名处理，是最常见的 missing-result 来源。
更稳的 debug 步骤通常是先把 query 简化，再带着证据把复杂逻辑加回来。
- 临时去掉 exclusions，看看差异。
- 同时测试偏宽和偏严版本的 query。
- 比较公开帖子里的真实表达和你现在写的 query 语言。
3. 再看 collection window 和分页假设
有些流程看起来像 search 缺结果，其实是因为时间窗口太窄、采集频率太低，或者 checkpoint 规则不对。
这在 repeated monitoring 场景里尤其常见，因为 timing 和 pagination 都会影响最终保存下来的结果。
- 检查 time range 或 checkpoint 逻辑。
- 确认分页深度是否真的够这条流程用。
- 把 retrieval gap 和 post-processing gap 分开看。
4. 保存 debug 样本给下次复盘用
最好复用的 debug 资产，通常不是口头记忆，而是几条能说明 query 为什么失效、后来又怎么修好的样本帖子。
这样下次维护这条流程时，团队会轻松很多。
- 保留 before / after query 样本。
- 保存几条能说明 false negative 的帖子。
- 把 debug 备注挂回 query 或 monitoring rule 上。
团队在实现这条流程时最常问的几个问题
这些问题通常会在团队从单次测试走向可重复 Twitter / X 数据采集时冒出来。
最常见的 missing-result 原因是什么？
很多团队最后发现，第一问题通常是 query 用词或 exclusions，而不是底层 endpoint。
应该立刻把 query 放宽吗？
通常先测试更简单的版本更稳。太快放宽 query，很容易用更大的噪音把真正的问题盖住。
怎么让 debug 结果以后还能复用？
把样本帖子、失败 query 和最终修复方案一起保存到工作流旁边，下次维护会轻松很多。
通常会一起看的实现型页面
如果问题还停留在 query 设计本身，可以继续看这页。
如果问题其实出在 repeated collection 或 checkpoint，可以继续看这页。
如果结果集已经对了，但来源解释还不稳，可以继续看这页。
如果你想先看 search 工作流背后的能力页，可以继续看这页。
把 Twitter / X 公开帖子做成团队能反复运行的流程
如果这些问题已经开始频繁出现在你的流程里，可以去验证 tweet search、账号复核或 timeline 接入路径，并把输出接进稳定团队循环。