GitHub Issue 模板设计与必填字段治理

当一个开源项目的 Star 数突破一千后，维护者面临的最大挑战往往不是代码本身，而是 GitHub Issue 列表中海量的无效反馈。

每天打开通知，满屏都是类似这样的标题和内容：
“在 Mac 上跑不起来”、“更新之后报错了怎么办”、“为什么无法调用接口？”。
内容除了这句话，没有操作系统版本、没有 Node/Go 运行时版本、没有完整堆栈，更没有最小复现代码。

过去，维护者必须像客服一样逐条回复：“请问你的环境是什么？”、“能贴一下终端的完整输出吗？”。几天后用户回了一行日志，你再问一句，来回反复拉扯三四个回合，一个本来五分钟能修完的 Bug 要耗费两周时间，严重透支维护者的热情。

要彻底终结这种低效沟通，最有效的手段就是废弃随意的 Markdown 模板，全面迁移到 GitHub Issue Forms（结构化表单） 并实施必填字段治理。

从 Markdown 模板到 Issue Forms 的转变

旧式的 .github/ISSUE_TEMPLATE/bug_report.md 只是在文本框里预置了一些注释和标题占位符。很多用户在发帖时会直接按全选、删除所有提示，然后写下一句吐槽。

而 GitHub 提供的 Issue Forms 允许我们使用 YAML 定义结构化输入表单，支持必填校验（validations.required: true）、下拉选择框、代码块输入框以及 Markdown 说明。用户不填齐关键信息，界面上的“Submit issue”按钮根本无法点击。

生产级 Bug Report 表单配置

下面是我们在开源 CLI 项目中正在使用的 .github/ISSUE_TEMPLATE/bug_report.yml 配置：

name: 🐛 Bug 报告 (Bug Report)
description: 提交程序运行中的报错、崩溃或不符合预期的行为
title: "[Bug]: "
labels: ["bug", "need-triage"]
body:
  - type: markdown
    attributes:
      value: |
        感谢提交 Bug 反馈！在提交前，请确认已检索过已关闭的 Issue，避免重复提问。

  - type: input
    id: version
    attributes:
      label: 工具与环境版本
      description: 请提供当前 CLI 版本、Node.js 版本以及操作系统
      placeholder: 例如：CLI v0.5.2, Node.js v20.11.0, macOS 14.4 (Apple Silicon)
    validations:
      required: true

  - type: textarea
    id: reproduction
    attributes:
      label: 详细复现步骤
      description: 请按顺序写出能稳定复现该问题的具体操作步骤
      placeholder: |
        1. 执行 `aicli init` 初始化项目
        2. 在配置文件中设置 `model: "gpt-4o"`
        3. 执行 `aicli run "hello world"`
    validations:
      required: true

  - type: textarea
    id: logs
    attributes:
      label: 终端完整报错日志 (Error Stack)
      description: 请贴上带 `--verbose` 参数运行后的完整输出堆栈
      render: shell
    validations:
      required: true

  - type: checkboxes
    id: checks
    attributes:
      label: 自检确认
      options:
        - label: 我已经阅读了项目文档，确认这并非未配置环境变量引起的错误
          required: true
        - label: 我确认该问题在最新版本（npm i -g 升级后）依然能够复现
          required: true

表单设计的关键细节与取舍

设计表单时，有几个务实原则需要把握：

1. 强制要求版本与环境：
   CLI 工具在跨平台（macOS、Linux、Windows WSL）以及不同 Node 版本（CommonJS vs ESM）下的表现差异极大。把版本设为必填文本框，能在第一时间排除 50% 因环境不匹配导致的伪 Bug。

2. 强制使用代码块渲染日志：
   通过设置 render: shell，GitHub 会自动将用户粘贴的日志包裹在带有代码高亮的容器中，避免未转义的 ANSI 控制字符、堆栈行号打乱页面布局。

3. 设置自检复选框（Checkboxes）：
   强制要求勾选“已升级到最新版”和“已查阅文档”，能够拦截大量因为使用远古版本或者未填 API Key 导致的无意义提问。

社区治理配套规则

仅有模板是不够的，如果个别用户在必填框里胡乱输入一个点“.”或者“asdf”绕过校验，必须有明确的治理机制：

• 设立 Stale / Need Info 自动化工作流：
  若 Issue 缺少关键复现 Demo，打上 need-info 标签，并由 GitHub Bot 发送规范回复：“请在 7 天内补充最小复现仓库或具体配置，否则该 Issue 将被自动关闭”。
• 坚决关闭不合规提问：
  维护者的精力是项目最宝贵的资产。对不愿提供复现步骤的 Issue 保持礼貌但坚决地关闭，不是傲慢，而是对其他认真提交反馈的贡献者负责。

通过规范的表单治理，项目的无效来回追问减少了 80% 以上。绝大多数新 Issue 在提交的瞬间就包含了完整的环境与日志，使得定位与修复 Bug 的效率提升了数倍。良好的基础设施，是开源项目走向专业与健康的关键一步。