给开源仓库提第一个 Issue：从复现到建议的完整模板

很多新手第一次给开源仓库提 Issue，写出来的内容是「这个功能用不了，求修复」。维护者看不到版本、看不到复现步骤、也看不到你期望的行为，只能来回问三轮，问题就沉了。

本文用一个真实例子走一遍完整流程，仓库是 GitCode 上的 agent-best-practices 组织下的 eduSwarm 项目。

第一步，确认问题是不是真的存在。先在 Issues 列表里搜关键词，看有没有人提过。重复的 Issue 会被直接关掉，先搜一遍能省双方的时间。

第二步，在本地复现。按 README 的快速开始一步一步做，不要跳步。我这次就是在克隆仓库后直接执行启动命令，服务报缺少模型服务相关配置。

第三步，把复现过程写成别人能照着做的步骤。要写到「点哪里、输什么、看到什么」这个粒度。例如：克隆仓库后执行快速开始中的启动命令，服务启动时提示缺少模型服务相关配置。

第四步，写清楚期望的行为。只描述现象不够，要说你希望它变成什么样。我写的是：建议在 README 的快速开始章节补一张环境变量表格，列出变量名、是否必填、默认值和示例值，并在启动前加一步配置检查。

第五步，附上环境信息。操作系统、运行时版本、分支名、提交号，这四项基本能覆盖大部分定位需求。我这次给的是 macOS 14、Node 20、main 分支最新提交。

把这五步套进一个固定模板，写起来就很快了。我的模板是这样的：问题描述一段话说清楚是什么坏了；复现步骤用有序列表，每步一个动作；期望行为一句话说清目标；环境信息列四行。

提交的时候注意一件事：Issue 的标题决定维护者会不会点开。标题里带上模块名和一句话结论，比如「快速开始章节建议补充本地运行所需的环境变量说明」，比「启动报错」有用得多。

最后，Issue 提完之后不要就不管了。维护者可能会追问，及时回复；如果自己先找到了原因或者绕过了问题，也要补一条评论，把结论留下来，下一个遇到同样问题的人能直接搜到。

整个过程花不了二十分钟，但一个好的 Issue 能帮维护者省掉大量沟通成本，也让自己的问题更快被解决。这就是参与开源最划算的入门方式。