Benchmark 指南
Benchmark 文档的职责，不是堆更多数字，而是帮助维护者解释数字的来源、边界与可比较性。只有在这些前提清楚时，性能结论才值得写进白皮书、PR 描述或发布说明。
先回答三个问题
- 比较对象是什么？ 是不同提交、不同参数，还是不同工具？
- 工作负载是什么？ 输入规模、读长、压缩状态、线程数是否一致？
- 结论要服务谁？ 是帮助维护者调优，还是帮助读者理解产品定位？
运行 benchmark 的基本入口
以仓库现有脚本与目录为准，优先使用项目提供的 benchmark 工作流，而不是临时拼装命令。这样做的原因很简单：性能测试只有在输入、环境与记录方式一致时才有比较价值。
如何阅读结果
- 结果层：看到吞吐、耗时、内存等直接数值；
- 方法层：回看线程数、输入分布、机器拓扑与构建配置；
- 规范层：确认这些表述是否仍然符合项目对外的 benchmark 叙事。
如果你只能拿到“更快了”这种一句话结论，说明 benchmark 还没有准备好被传播。
维护者常见误区
- 用不同工作负载比较两个结论，却把它们写成一张表；
- 把一次偶然的峰值结果当成长期能力；
- 忽略 I/O、压缩比例或线程配置，导致读者无法复现；
- 只展示数字，不解释风险边界与不适用场景。
何时需要同步文档
当 benchmark 结论进入首页、白皮书、发布说明或 PR 核心叙事时，就不再只是维护者内部材料。此时要同时检查性能总览、相关 changelog 与研究附录中的参考材料是否需要一起更新。