如何提一个不会被忽略的 Issue：从一次文档死链排查说起

一条被忽略的 Issue 长什么样

我在几个开源仓库看过不少 Issue，也提过一些。慢慢地发现一个规律：被快速修掉的 Issue 和被晾着的 Issue，差别往往不在问题大小，而在信息密度。

最典型的一种被忽略的写法是这样的：

文档里的链接点不开，麻烦看一下。

维护者看到这句话的第一反应是"我这边能打开"。然后就没有然后了——他需要先复现，而你的描述没给他任何抓手。

我最近在给一个开源多智能体项目提 Issue 时，刻意反着来，结果当天就有人在看。下面把这个过程拆开讲。

先确认它真的是问题

动笔之前我做了一件事：把"我觉得有问题"变成"这里是证据"。

具体的坑是文档索引里的一个大小写问题。索引文件写着 symphony.md，而仓库里实际的文件是 Symphony.md。在 Windows 和 macOS 上点开完全正常，因为这两个系统的文件系统默认不区分大小写。但仓库要跑 CI，CI 在 Linux 上，那里区分大小写，链接就是 404。

问题在于：我本机是 Windows，我没法用"我点不开"来证明它坏了。

所以我换了个办法——不求复现，直接对比。用平台的 API 请求同一个路径，只改首字母大小写：

docs/en/symphony.md  -> 404
docs/en/Symphony.md  -> 200

两个状态码摆在一起，任何人都不需要复现就能确认这是缺陷。这一步是整个 Issue 里最有价值的部分，因为它把"你的环境有问题"这个万能挡箭牌直接拆掉了。

Issue 应该包含的四件事

我把正文分成四块，每块只干一件事：

第一块：怎么复现。 三条。在区分大小写的系统上克隆仓库 → 打开索引文件 → 点那个链接。不写环境版本、不写浏览器型号，因为这个问题和它们无关。复现步骤不是越长越专业，是越短越可信。

第二块：期望与实际的差距。 期望是这个链接能打开目标文档，实际是 404。就两句话。

第三块：证据。 就是上面那个 404/200 对照。我没有贴任何截图，因为文本证据比截图更可靠，维护者可以直接复制去验证。

第四块：我建议怎么修。 明确写出两行改动：把索引里的 symphony.md 改成 Symphony.md，把 symphony-技能编排与分发.md 改成 Symphony-技能编排与分发.md。并说明只改链接、不动已有文件名，因为改文件名会破坏别人已有的外部引用。

最后还加了一句加固建议：既然仓库已经有校验提交树完整性的 CI，可以顺手加一步"索引链接可达性检查"，十行 shell 就够，把这类问题挡在 CI 里。

为什么这四块有效

因为它们分别回答了维护者心里的四个问题：

• 这事儿真的存在吗？→ 复现步骤
• 它有多严重？→ 期望与实际的差距
• 我凭什么信你？→ 证据
• 我要花多少力气？→ 修复建议

维护者最怕的不是麻烦的问题，是需要他自己先做一遍调查才能开始的问题。你把调查做完了，他就只剩下动手。

反过来，一条 Issue 如果让维护者产生"我得先复现一下"的念头，它的处理优先级就会自动降到"有空再说"。

几个具体的写作习惯

不要在标题里喊。 标题写清楚「哪里 + 什么问题 + 什么后果」就够了。我用的标题是「docs/{en,zh}/SUMMARY.md 的 symphony 链接首字母大小写与实际文件名不符，Linux 下 404」——长，但一眼能判断是不是自己关心的范围。

不要混装多个问题。 一个 Issue 只解决一件事。顺手发现的另外三个小毛病，攒着下次一起提，或者分开提。混装的结果通常是每个都没修。

不要只说"有问题"，要说"怎么会这样"。 我那个 Issue 里解释了根因是文件系统大小写敏感性差异，所以维护者修完之后，还能顺手判断仓库里有没有同类问题——事实上中英两个目录各有一处，这个信息是根因分析带出来的。

给出证据，而不是结论。 "链接坏了"是结论，"404 vs 200"是证据。结论可以被质疑，证据不行。

一个反过来的判断

不是所有问题都值得提 Issue。

提之前我会先问自己：这个修复对除了我之外的人有价值吗？如果只是因为我的环境特殊、我的用法奇怪，那更适合去讨论区问，或者自己绕过去。

我提的那个大小写问题，价值在于它只影响 Linux 环境，而 Linux 恰恰是 CI 和部署的主流环境——也就是说，它影响了所有通过 CI 构建文档的人，只是没人发现，因为大家都在 Windows 上点链接。

能用"这不影响大多数人"说服自己的问题，别急着提。能用"这影响了一批人但他们没意识到"说服自己的，值得好好写。

最后

提 Issue 本质是一次异步沟通，而且对方大概率不认识你。你能控制的只有一件事：让你的信息在没有你解释的情况下也能自洽。

写完读一遍，假装自己是维护者：看完这段，我知道该改哪个文件、改哪一行了吗？如果答案是"大概知道"，那就还没写完。

如果答案是"我已经能动手了"，这个 Issue 就成功了一半。