Ant Design Issue 处理参考手册：标签体系、FAQ 资源与 Bug 规范落地指南

本篇技术指南基于 Ant Design 仓库中 issue 维护技能（issue-reply skill）的标签与资源参考文档，系统讲解该项目社区 issue 管理所使用的标签语义、FAQ 资源索引、Bug 重现模板与 Issue 创建规范。读完后你将掌握：如何依据标签快速判断一个 issue 的当前状态与处理方式，如何按官方资源查找顺序定位答案，以及如何结合更新日志与版本记录完成 Bug 的分类、回应与关闭。

一、这套参考文档的定位

Ant Design 的 .agents/skills/issue-reply 技能为 issue 维护者（含 AI 协作助手）提供了一套「先分类、再回应、后关闭」的标准化流程，而 labels-and-resources.md 正是该技能的标签与资源字典：它定义了哪些标签该用在什么状态，以及回应 issue 时应该去哪里查找现成答案。技能主文档 中明确规定，处理 issues 时采用「先草拟方案、经确认后再执行」的两阶段流程，标签操作（添加/移除）与是否关闭都是草拟方案的标准字段。因此，标签与资源不只是管理约定，而是回复流程中可执行操作的输入。

二、常用标签：语义、使用场景与判定依据

参考文档定义了如下标签体系（原文表格完整继承）：

标签	用途
🐛 Bug	已确认的 bug
🤔 Need Reproduce	缺少重现链接或无法复现
💡 Feature Request	功能请求
❓FAQ	常见问题
help wanted	欢迎社区贡献
good first issue	适合首次贡献者
unconfirmed	需要更多信息或验证
improvement	改进建议
Inactive	近期无活动（不代表已解决）

下面结合仓库内的佐证材料，说明每个标签在实际处理中的含义与触发条件。

2.1 状态类标签：🐛 Bug 与 🤔 Need Reproduce

这两个标签刻画的是 Bug 报告的两个互斥阶段，对应技能文档中的判定逻辑：

• 缺少/无关重现链接 → 添加 🤔 Need Reproduce，请求用户提供在线重现；
• 有重现链接且确认是 bug → 添加 🐛 Bug。

「重现链接」是 Ant Design 社区 Bug 规范的硬性要求：贡献指南 明确要求报告 bug 前先用 issue 小助手创建 issue 并附重现模板，README 中也列出了 Online Playground 作为 bug 报告渠道。也就是说，🤔 Need Reproduce 不是"暂缓处理"的垃圾桶标签，而是把 issue 拉回规范入口（可复现的最小案例）的中间状态。

2.2 分类类标签：💡 Feature Request、improvement、❓FAQ

• 💡 Feature Request：用户需要目前不存在的新能力。技能文档要求收到功能请求时先排查现有 API（用户提需求时常因"找不到"而误以为"没有"），确认未被覆盖后再打此标签，并追问使用场景与期望的 API 设计。
• improvement：改进建议，通常指现有行为可以更好但不构成缺陷，是功能请求与 Bug 之间的过渡分类。
• ❓FAQ：问题在官方 FAQ 或历史 issue 中已有答复。参考文档给出的查找资源顺序为：带 ❓FAQ 标签的 issues → 组件文档 FAQ 部分 → 常见问题汇总。仓库内可直接对标的落点见 FAQ 汇总文档 与 Table 文档、Form 文档 等组件页的 FAQ 小节。

2.3 社区协作类标签：help wanted、good first issue、unconfirmed

• help wanted：欢迎社区贡献的 issue，维护者确认问题但需要外部力量跟进。
• good first issue：适合首次贡献者的 issue。贡献指南 中专门说明了这一点：项目用 good first issues 标记一些容易修复的 bug 和小功能，作为新人的首次尝试入口；接手前先检查留言区是否已有他人认领。
• unconfirmed：需要更多信息或验证的 issue，与 🤔 Need Reproduce 的区别在于——后者缺的是可执行的重现，前者缺的是版本、环境、行为描述等上下文。

2.4 Inactive：只表示沉默，不表示解决

参考文档特别强调：Inactive 标签只表示近期无活动，不代表已解决，仍可回复。这一点与技能文档中"检查已回复的 Issues"流程一致：维护者提出问题后用户 7 天以上未回复才考虑关闭并留言，而不是看到 Inactive 就直接关闭。处理带 Inactive 标签的 issue 时，正确动作是先补全上下文再决定关闭还是继续跟进。

三、FAQ 资源索引：按官方 → 组件 → 社区的顺序查找

参考文档将回应 issue 时可引用的资源组织成三层，回答 FAQ 类 issue 时应按此顺序查找，命中即用现成答案背书。

3.1 官方资源层

• FAQ Issues 列表：按 ❓FAQ 标签过滤的 issues 集合，是历史答复的第一索引；
• 常见问题汇总：即仓库内 faq.zh-CN.md（英文见 faq.en-US.md），收录了如"undefined 与 null 在受控组件中的区别"、"为什么空内容仍渲染 DOM"、"popup 组件互相触发导致消失"等高频问题及官方答复；
• 更新日志：对应仓库中的 CHANGELOG.zh-CN.md 与 CHANGELOG.en-US.md，是"老版本 + changelog 中已修复 → 引导用户升级验证"这一 Bug 处理路径的依据。

3.2 组件 FAQ 层

参考文档点名了四个高频组件级入口，在仓库中均有对应文件可直接查阅：

资源	仓库内对应文档
Form FAQ	components/form/index.zh-CN.md 的 FAQ 小节
Table 虚拟滚动	components/table/index.zh-CN.md 的虚拟列表小节
国际化	docs/react/i18n.zh-CN.md
主题定制	docs/react/customize-theme.zh-CN.md

回复相关 issue 时引用这些文档锚点，比纯文字解释更利于用户自查，也更利于后续维护者复用同一答复。

3.3 社区资源层

• StackOverflow（antd tag）：英文社区的沉淀地；
• SegmentFault（antd tag）：中文社区的沉淀地。

当维护者无法在仓库内解决时，按技能文档的要求引导用户到上述渠道继续提问，而不是让 issue 悬空。

四、Bug 重现模板：在线可复现环境是硬性要求

参考文档列出两类在线重现模板：CodeSandbox 模板与 StackBlitz 模板（均为 antd 预置的 reproduction 环境）。它们的作用是把"用户本地跑不通"转化为"维护者点开链接即可复现"，从而让 🤔 Need Reproduce 与 🐛 Bug 之间的状态转换有据可依。

贡献指南 给出了配套的完整表述：报告 bug 前请先搜索已有 issue 并阅读 FAQ；要快速解决 bug，最好通过 issue 小助手提 issue 并使用官方重现模板提供复现。维护者侧则应反过来核验：用户附的链接是否为可用的在线环境、版本是否与最新一致——链接缺失或与问题无关时加 🤔 Need Reproduce，链接有效且复现成功时加 🐛 Bug。

五、Issue 规范：创建入口、Bug 与功能请求的准入条件

参考文档归纳的三条规范如下：

1. 所有 issue 应通过 issue 小助手（new-issue.ant.design 站点）创建；
2. Bug 报告必须包含重现链接；
3. 功能请求需要描述使用场景和期望的 API。

第一条在仓库中有明确的执行机制：.github/ISSUE_TEMPLATE.md 本身就是拦截文件，其全部内容就是提示使用者必须通过 issue 小助手新建 issue，否则 issue 会被立即关闭。这与参考文档末尾的柔性条款并不矛盾：技能文档明确"如果用户没有通过规范渠道创建 issue，但内容完整有效，无需强制关闭，可以正常处理"——模板拦截针对的是普通提交者，维护者处理时以内容完整性为准。

第三条对功能请求的准入要求，对应技能文档中的四步排查法：先查现有 API、关注命名可发现性、检查跨组件一致性（如 Table 的 rowKey 与 Select 的 fieldNames）、用提问式引导而非直接否定。即"场景 + 期望 API"不是客套字段，而是判断"已有功能是否已覆盖"的输入。

六、结合版本信息的 Bug 处理路径

参考文档中的"更新日志"资源指向一个可落地的维护动作：首先检查版本。结合仓库根目录的两个文件，可以还原完整的判定链：

• CHANGELOG.zh-CN.md / CHANGELOG.en-US.md：确认某问题是否在某个版本被修复，用于"老版本 + 已修复 → 引导升级验证"的路径；
• BUG_VERSIONS.json：仓库内维护的"存在已知问题的版本区间"清单，例如记录了 3.9.3、4.23.0、5.0.4 等版本对应的修复 commit/issue 链接。处理 Bug 报告时，用户报告的版本若落在清单内，可直接给出"该版本存在已知问题，请升级到 X 验证"的答复；若修复 PR 已合并但新版本尚未发布，则告知用户等待新版本，而不是重复排查。

这条路径与标签体系闭环：版本过旧但问题已修复 → 回复引导后按 ❓FAQ 或已解决关闭；确认是当前版本真实缺陷 → 🐛 Bug；无法复现 → 🤔 Need Reproduce。

七、完整工作流：从拉取 issue 到关闭

把标签、资源与规范串起来，一个 FAQ/Bug 混合场景的标准处理流程如下（与 SKILL.md 的两阶段流程一致）：

1. 草拟阶段：拉取 open issues，读取 body 判断语言（只看 issue 原始 body 的语言，忽略后续评论），完成分类（Bug / Feature Request / 使用问题）并确定状态（无人回复 / 维护者已回复 / 等待用户反馈）；
2. 查资源：按 ❓FAQ 标签 issues → 组件文档 FAQ → 常见问题汇总 → 社区资源 的顺序查找现成答案；
3. 查版本：对照 CHANGELOG 与 BUG_VERSIONS.json 判断是否需要引导升级；
4. 定操作：给出草拟回复（含语言、正文、代码示例）、标签操作（如添加 🤔 Need Reproduce 或 ❓FAQ）与是否关闭的建议，一次性呈现给执行者；
5. 确认后执行：维护者确认后才执行评论、加标签或关闭。关闭前再次确认语言正确，且满足关闭条件（重复问题、确定非 bug、已解决、用户 7 天以上未回复），对"不确定是否是 bug、用户未确认方案、有效功能请求、活跃讨论中"的 issue 不关闭。

八、要点回顾

• 标签是状态机：🤔 Need Reproduce → 🐛 Bug 的流转以"是否有有效重现链接"为唯一判据；Inactive 仅表示沉默，不等于已解决；
• 资源查找有固定顺序：FAQ 标签 issues → 组件文档 FAQ（Form、Table 等）→ 官方 FAQ 汇总 → 社区（StackOverflow / SegmentFault）；
• 规范有仓库内执行点：ISSUE_TEMPLATE.md 强制走 issue 小助手，贡献指南 规定 Bug 必须附重现、功能请求必须写场景与期望 API；
• 版本证据来自 CHANGELOG 与 BUG_VERSIONS.json，"引导升级验证"是有据可依的回复而非口头建议。

掌握以上内容后，你可以按照仓库既定的标签语义与资源索引独立完成 issue 的分类、回复草拟与关闭决策，且每一步操作都能在仓库内找到对应的文档或文件依据。