什么是好的开源 PR（从我的 PR 被关闭中得到的教训）

Source: Dev.to

问题

我在研究 ClawHub 的搜索排序系统（ClawHub 是 OpenClaw 的技能市场）时，发现了一个奇怪的现象：如果你用技能的完整 slug 进行搜索，它不一定会出现在顶部，甚至有时根本找不到。

根本原因在于搜索流水线。先进行向量相似度搜索，然后再应用词汇提升。但如果某个技能下载量很低，且它的嵌入向量对自身名称的得分不佳，向量召回阶段就会直接跳过它。因为它根本没有进入候选池，完整 slug 的匹配就永远得不到 +1.4 的提升。

我的 PR：快速修复

我在向量搜索之后加入了一个 slug 召回步骤——通过 slug 进行 O(1) 查找，如果缺失则注入。简单且有效。

出了什么问题

• V1 过于硬编码，审查时立即被指出。
• V2 漏掉了关键的边缘情况：如果用户有意按下载量排序怎么办？我的注入会覆盖他们的显式选择。

竞争的 PR

另一位贡献者提交的修复被合并了。主要区别如下：

• 尊重用户选择 – 他们区分了系统默认排序和用户手动选择的排序，保留了用户的显式决定。
• 根本原因修复 – 与其在下游打补丁，他们直接在上游删除了有问题的代码。
• 演示视频 – 一段简短的前后对比屏幕录制帮助维护者快速验证改动。
• 回归测试 – 他们添加了覆盖我未考虑的边缘情况的测试。

我的收获

1. 在提交前先考虑边缘情况

对每一次行为改动，列出至少三个可能出错的场景。如果想不出任何情况，说明思考不够深入。

2. 修复根本原因，而不是症状

自问：我是在为另一段坏代码补偿吗？如果是，应该先修复底层错误。

3. 展示你的工作

提供截图、视频或前后对比。审查大量 PR 的维护者更倾向于那些验证过程简单的贡献。

4. 了解完整系统

仅了解要改动的代码是不够的，还需要理解其周边代码以及相互作用方式。

给开源新手的建议

• 在提交自己的 PR 之前先阅读已有的 PR。
• 不要急于求成——最好的修复会被采纳，而不是最先提交的。
• 快速且有思考地回复审查评论。
• PR 被关闭也没关系；一次被关闭的 PR 能教会的东西可能比十个合并的拼写修复更多。

本文基于我在 ClawHub 搜索排序 PR 中的经验。竞争的 PR 客观上更好，我也对这次学习机会心怀感激。