VS Code 贡献工作流指南：Issue 报告规范、自动化管理与内置 Issue Reporter 的源码剖析

本文围绕 VS Code 仓库根目录的 CONTRIBUTING.md 展开，系统讲解参与 VS Code 贡献的完整流程：提问渠道、反馈途径、定位正确的 Issue 仓库、撰写高质量 Bug 报告与功能请求、提交 Pull Request，以及项目基于 GitHub Actions 的自动化 Issue 管理策略。更进一步，本文将深入 src/vs/workbench/contrib/issue/ 源码，剖析帮助菜单中"Report Issue"工具背后的命令注册、系统信息采集与扩展清单收集机制，帮助你在报告问题的同时理解 VS Code 的 Workbench 服务架构。

一、参与贡献的方式概览

VS Code 项目欢迎多种形式的贡献，写代码只是其中之一。CONTRIBUTING.md 将贡献渠道分为四类：提问（Asking Questions）、提供反馈（Providing Feedback）、报告问题（Reporting Issues）、贡献修复（Contributing Fixes）。其中报告问题是最核心的日常协作环节，也是本文的重点。

1. 提问与反馈

• 提问：有使用问题时，建议先搜索社区已有的问答（使用 visual-studio-code 标签），而不是直接开 Issue。原文明确指出，措辞得当的问题本身就能成为帮助后来者的资源。
• 反馈：开发团队通过多个渠道收集意见，文档指向官方 Wiki 的 Feedback Channels 页面了解具体渠道（本文按仓库证据边界不展开外部链接，可查阅官方 Wiki "Feedback Channels" 词条）。

2. 贡献修复

如果你想写代码来修复问题，文档指向官方 Wiki 的 "How to Contribute" 词条作为入口。对本地仓库而言，可以从 README.md 与根目录 AGENTS.md 了解构建与开发约定，配合 scripts/ 下的 code.sh、test.sh 等脚本完成本地运行与测试验证。

二、报告 Issue：完整的实战流程

1. 确定在哪个仓库报告

VS Code 项目分散在多个仓库中，文档要求先确认问题归属的正确仓库；不确定时可查阅官方 Wiki 的 "Related Projects" 列表。一个关键的排查动作是：

禁用所有扩展后问题是否依然存在？ 如果禁用扩展后问题消失，说明问题由某个扩展引起，应直接到该扩展的仓库中报告，而不是 VS Code 主仓库。

2. 先搜索是否已有同类 Issue

• 在新建 Issue 前，先在仓库的 open issues 中搜索，确认问题或功能请求尚未被提交；
• 功能请求类建议额外浏览热门（最多 +1 反应）的 feature-request 列表，避免重复提议；
• 若已存在：补充有价值的评论，并用 Reaction 代替 "+1" 评论——👍 表示支持，👎 表示反对。原文特别强调：Reaction 应替代 "+1" 评论，以减少 Issue 时间线噪音。

如果确认没有已存在的 Issue，再按下一节的规范新建。

3. 撰写高质量的 Bug 报告与功能请求

文档给出的硬性规则：

• 一个 Issue 只描述一个问题，不要把多个 Bug 或多个功能请求堆在同一个 Issue 里；
• 不要把自己的问题作为评论追加到已有 Issue 下，除非确认是完全相同的问题——很多 Issue 表面相似但根因不同。

报告包含的信息越多，越容易被复现和修复。文档要求每个 Issue 至少包含以下内容（完整继承原文清单）：

必含信息	说明
VS Code 版本	Version of VS Code
操作系统	Your operating system
已安装扩展列表	List of extensions that you have installed
可复现步骤	Reproducible steps (1... 2... 3...)
期望行为 vs 实际行为	What you expected to see, versus what you actually saw
截图/动图/视频	Images, animations, or a link to a video showing the issue occurring
代码片段或仓库链接	A code snippet or a repo developers can clone to recreate the issue
Dev Tools 控制台错误	从 Help > Toggle Developer Tools 打开控制台获取的错误

其中对代码片段有一条容易忽略的注意事项：开发者需要能复制粘贴这段代码，因此把代码片段作为 .gif 等媒体文件附上是不够的，必须提供可编辑的文本形式（代码块或仓库链接）。

4. 源码佐证：内置 "Report Issue" 工具的实现

文档中提到 VS Code 帮助菜单里的 Report Issue 内置工具可以自动附带 VS Code 版本、全部已安装扩展和系统信息，并会搜索已有相似 Issue。这些能力在当前仓库源码中可以直接验证：

（1）命令与菜单注册

在 src/vs/workbench/contrib/issue/common/issue.contribution.ts 中，BaseIssueContribution 注册了核心命令 workbench.action.openIssueReporter（以及面向扩展 API 的 vscode.openIssueReporter），并把它挂到两个入口：命令面板（MenuId.CommandPalette）和帮助菜单（MenuId.MenubarHelpMenu，菜单标题为 "Report Issue..."，见 该文件 L115-L130）。这正是文档所说的 Help 菜单入口。该贡献还允许通过参数预填表单，支持 { extensionId, issueTitle, issueBody } 结构（见 L21-L60），意味着扩展也可以程序化地打开 Issue 报告器并预置内容。

值得注意的是注册条件：若 productService.reportIssueUrl 未配置，整个报告器命令不会被注册。而该 URL 在 product.json 中定义（reportIssueUrl），在 src/vs/platform/product/common/product.ts 中给出了默认值。也就是说，Issue 报告的提交目标是由产品配置驱动的，这是各 VS Code 发行版可以定制报告入口的底层机制。

（2）版本与扩展信息自动采集

文档说报告工具"自动提供 VS Code 版本、所有已安装扩展和系统信息"。在 src/vs/workbench/contrib/issue/browser/baseIssueReporterService.ts 中可以看到 versionInfo 的构造：vscodeVersion 由产品名、版本号（Universal 构建会追加 "(Universal)"）、commit 与构建日期拼成，同时记录 extensionsDisabled 状态——这与文档要求的"版本 + 扩展列表 + 系统信息"逐项对应。扩展表（含扩展 ID 与版本）由 该文件 L1619-L1650 的 updateExtensionTable / getExtensionTableHtml 生成，且会排除主题类扩展并给出数量提示。

（3）系统信息命令与向导模式

在 src/vs/workbench/contrib/issue/electron-browser/issue.contribution.ts 中注册了内部命令 _issues.getSystemStatus，其实现直接调用 IProcessService.getSystemStatus()，即文档中"系统信息"（System Information）的底层来源。同一文件 L48-L66 还注册了 issueReporter 相关配置：issueReporter.wizard.enabled（默认 false，启用新的 Issue 报告向导替代经典报告器）与 issueReporter.wizard.fullWorkspaceScan（默认 true，性能诊断自动采集时是否遍历整个工作区而非停在默认 2 万文件上限）。从源码结构看，这是报告器正在向向导式流程演进，且针对超大工作区提供了性能保护开关。

（4）相似 Issue 搜索的仓库侧佐证

文档称报告工具"会搜索已有相似 Issue"。仓库中同样存在服务端层面的去重机制：.github/similarity.yml 配置了实验性的重复 Issue 检测（perform: true），当新提交的 Issue 与既有 Issue 相似时，会自动评论一条 "Experimental duplicate detection" 提示并列出潜在重复项（${potentialDuplicates}）。客户端搜索与服务端检测两者共同降低了重复报告的概率。

5. 创建 Pull Request 与最终检查清单

• Pull Request：文档指向官方 Wiki 的 "How to Contribute" 中 Pull Request 章节作为规范入口。
• 提交前自查清单（完整继承原文）：
  • [ ] 已在 Issue 仓库搜索，确认这是一个新问题
  • [ ] 已在禁用所有扩展后复现过问题
  • [ ] 已围绕问题精简代码，以更好隔离问题

文档最后提醒：如果开发者无法立刻复现你的问题，不要介意——他们只会继续向你索要更多信息。

6. 提交后的跟进

Issue 提交后会进入项目的 Issue Tracking 工作流（文档指向官方 Wiki "Issue Tracking" 词条）。理解后续会发生什么，能帮助你明确在每个阶段如何继续协助推进。

三、自动化 Issue 管理（GitHub Actions）

VS Code 使用 GitHub Actions 机器人管理 Issue 生命周期。文档明确列举了三个典型行为：

自动化行为	说明
自动关闭	被标记 info-needed（信息不足）的 Issue，若过去 7 天没有回复，自动关闭
自动锁定	Issue 关闭 45 天后自动锁定，防止后续无关讨论
功能请求流水线	自动执行 VS Code 的 feature request 分级流转流程

这些 Actions 定义在独立的 triage 仓库中（文档指向 vscode-github-triage-actions 仓库，该仓库不在本仓库内，故此处不作为仓库事实引用）。若认为机器人判断有误，文档建议新开一个 Issue 反馈，而不是直接修改 bot 的结论。

结合上文提到的 .github/similarity.yml 可以看到：自动化管理不止"关 Issue"，还包括提交时的重复检测，两者共同维护了 Issue 仓库的信噪比——这也是文档反复强调"先搜索、用 Reaction、一个 Issue 只讲一个问题"的机制性原因。

四、小结：从规范到机制

CONTRIBUTING.md 的价值在于它把"如何与这个大型项目协作"拆成了可执行的流程：提问走社区、反馈走指定渠道、报告走"定位仓库 → 查重 → 补齐信息 → 提交 → 跟进"五步。而当前仓库的源码进一步印证了这套规范的工程化落地：

• 报告入口由 product.json 的 reportIssueUrl 驱动，命令注册见 issue.contribution.ts；
• 版本、扩展、系统信息的自动采集分别对应 versionInfo、扩展表格与 _issues.getSystemStatus 命令（baseIssueReporterService.ts、issue.contribution.ts）；
• 服务端重复检测配置在 .github/similarity.yml，与客户端"搜索已有 Issue"的要求形成闭环。

遵循这些流程提交报告，不仅提高问题被处理的效率，也能让你顺带读懂 VS Code Workbench 的命令/菜单/服务注册体系——这为后续"贡献修复"打下基础。