triaging-issues

PyTorch Issue Triage Skill

本 Skill 用于对 GitHub Issue 进行 Triage 分流与分类：包括路由转发、打标签以及提供一线回复。

目录

• 可用 MCP 工具
• 绝不能添加的 Label
• Issue Triage 处理步骤
  • 步骤 0：已完成路由 — 跳过
  • 步骤 1：区分“提问”与“Bug/新功能”
  • 步骤 1.5：需要复现 — 包含外部文件
  • 步骤 2：转移仓库
  • 步骤 2.5：PT2 类 Issue — 特殊处理
  • 步骤 3：重定向至二级 Oncall
  • 步骤 4：给 Issue 打标签
  • 步骤 5：高优先级 — 必须人工审核
  • 步骤 6：bot-triaged（自动打标）
  • 步骤 7：标记为已分流
• V1 限制说明

标签参考： 适用于 Triage 分流的完整标签目录请参阅 labels.json。只允许添加该文件中明确存在的标签。 绝不能随意捏造或盲猜标签名称。该文件已排除了 CI 触发器、测试配置、Release Notes、废弃标签以及需要人工决策的标签。

PT2 Triage 指南： 分流 PT2/torch.compile 相关 Issue 时，请参阅 pt2-triage-rubric.md 获取详细的打标指导。

回复模板： 标准回复文案请参阅 templates.json。

---

可用 MCP 工具

使用以下 GitHub MCP 工具完成 Triage 操作：

工具	用途
mcp__github__issue_read	获取 Issue 详情、评论列表及现有 Label
mcp__github__issue_write	打 Label 或关闭 Issue
mcp__github__add_issue_comment	添加评论（仅在重定向/解答提问时使用）
mcp__github__search_issues	搜索相似 Issue 以补充上下文

---

绝不能添加的 Label

前缀 / 类别	禁加原因
未在 labels.json 中列出的 Label	只能添加允许列表（Allowlist）中存在的 Label
ciflow/*	仅用于 PR 的 CI 工作流触发器
test-config/*	仅用于 PR 的测试套件选择器
release notes: *	用于 Release Notes 的自动分配 Label
ci-*, ci:*	CI 基础设施控制 Label
sev*	严重程度（Severity）Label 需要人工决策
merge blocking	需要人工决策
actionable, needs design, needs reproduction, needs research	仅留给人工 Reviewer 审查完 Issue 后添加
包含 "deprecated" 的任意 Label	已废弃 Label
oncall: releng	不属于 Triage 的路由目标，请改为使用 module: ci

遇到拦截时： 一旦有 Label 被 Hook 拦截，只需添加 triage review 标签并立即停止后续操作，交由人工介入。

上述规则由 PreToolUse Hook 强制约束，所有 Label 在提交前都会对照 labels.json 进行校验。

绝不覆盖人工打上的 Label

如果人工已经添加了 Label（特别是 ci: sev、严重程度 Label 或优先级 Label），切勿移除或替换它们。你的职责是补充 Label，而非覆盖人工选择。

---

Issue Triage 处理步骤（针对每个 Issue）

0) 已完成路由 — 跳过

如果 Issue 已经包含任意 oncall: 开头的 Label，直接跳过（SKIP），不做处理。 切勿：

• 添加任何 Label
• 添加 triaged 标签
• 发表评论
• 执行任何 Triage 逻辑

此类 Issue 已归属于子 Oncall 团队，由他们自行管理对应队列。

1) 区分“提问”与“Bug/新功能”

• 如果是纯咨询提问（非 Bug 报告或 Feature 请求）：关闭 Issue，并调用 templates.json 中的 redirect_to_forum 模板评论引导。
• 如果无法确定属于 Bug/Feature 还是纯提问：调用 request_more_info 模板请求补充信息并停止后续操作。

1.5) 包含外部文件

检查 Issue 正文中是否包含需要下载后才能复现问题的外部文件链接。

需识别的特征：

• 文件附件：.zip、.pt、.pth、.pkl、.safetensors、.onnx、.bin 等文件
• 外部网盘：Google Drive、Dropbox、OneDrive、Mega、WeTransfer 链接
• 模型社区：Hugging Face Hub 中指向模型文件的链接

处理动作：

1. 编辑 Issue 正文，删除/擦除外部下载链接
   • 替换为：[Link removed - external file downloads are not permitted for security reasons]
2. 使用 templates.json 中的 request_self_contained_reproduction 模板发表评论
3. 不要添加 triaged 标签 — 等待用户补充可独立运行的复现代码

1.55) 缺乏复现代码 — 其他情况

在出现以下情况时，请求用户提供独立自包含的复现代码并停止后续操作：

• 用户报告了硬件特定问题（如特定 GPU 型号），但未提供独立复现脚本
• 用户引用了特定的模型 / Checkpoint / 数据集，且无法通过几行代码公开运行复现
• Issue 描述了版本升级导致的破坏，但只给了高层描述，缺少最小复现代码
• 复现依赖特定的训练配置、分布式环境或非平凡的底层基础设施

1.6) 边界情况与数值精度问题

如果 Issue 涉及极值或数值精度不一致问题：

需识别的特征：

• 接近 torch.finfo(dtype).max 或 torch.finfo(dtype).min 的数值
• 合法（但极端）输入导致输出中出现 NaN/Inf
• CPU 与 GPU 计算结果存在差异
• 不同数据类型间的精度差异（如 fp32 vs fp16）
• 由 Fuzzer 自动生成的边界用例

重要提示 —— 避免被关键词误导打错 Label：

打 Label 必须基于根本原因（Root Cause），而非报错信息或标题中出现的关键词。关键词只反映哪里报错，不代表问题根源在哪里。

• import torch 时报 undefined symbol: ncclAlltoAll 属于打包问题（module: binaries），而不是分布式训练 Bug —— 因为用户压根还没执行分布式代码。
• 参数名或容差检查中出现 nan，不直接等同于 module: NaNs and Infs，除非 Bug 本身就是 NaN 传播引起的。
• Callstack 涉及 autograd 并不代表应该打 module: autograd —— 需排查 Bug 是出在 autograd 本身还是仅仅位于调用链上。
• 测试用例断言的 Tolerance 失败属于 module: tests，而非 module: numerical-stability。

思考核心：“根本性的 Fix 应该改哪个模块的代码？”—— 这才决定应该打什么 Label。

处理动作：

1. 打上 module: edge cases Label
2. 如果来自 Fuzzer，同时打上 topic: fuzzer Label
3. 使用 templates.json 中的 numerical_accuracy 模板提供官方文档参考
4. 如果根据文档确认其属于预期行为，使用模板评论并关闭 Issue

2) 转移仓库（领域库或 ExecuTorch）

如果 Issue 属于其他 Repo（如 vision / text / audio / RL / ExecuTorch 等），将 Issue 转移（Transfer）至对应仓库并停止后续操作。

2.5) PT2 类 Issue — 特殊处理

PT2 不属于简单重定向。 oncall: pt2 与步骤 3 中的其他 Oncall Label 不同。PT2 的 Issue 需要继续完成步骤 4–7 的完整 Triage 流程 —— 即添加 oncall: pt2 后，继续补充具体的 module: Label、标记 triaged 等。

每个 oncall: pt2 Issue 必须包含至少一个 module: Label。 缺乏模块 Label 会导致 PT2 Oncall 队列过于繁杂 —— 团队需要明确知道受影响的具体组件（如 module: dynamo、module: inductor、module: helion、module: dynamic shapes）。若无法精准判断，可以打上 module: compile ux 兜底，但应优先尝试精确定位。详见 pt2-triage-rubric.md。

3) 重定向至二级 Oncall

至关重要： 当把 Issue 重定向给非 PT2 的 Oncall 队列时，打上恰好一个 oncall: ... Label 并立即停止后续操作。切勿：

• 添加任何 module: Label
• 标记为 triaged
• 执行后续任何 Triage 工作

二级 Oncall 团队会负责各自队列的分流。你的任务仅仅是路由转发给他们。

Oncall 重定向 Label 对照表

Label	适用场景
oncall: jit	TorchScript 相关问题
oncall: distributed	分布式训练（DDP、FSDP、RPC、c10d、DTensor、DeviceMesh、Symmetric Memory、Context Parallel、Pipelining）。特殊处理： 打上该 Label 后，针对该 Issue 触发分布式 Triage 子 Skill（/distributed-triage）执行二级分流 —— 它会进一步路由给具体的子 Oncall、添加模块 Label 并标记已分类。
oncall: export	torch.export 相关问题
oncall: quantization	量化（Quantization）相关问题
oncall: mobile	移动端（iOS/Android），不含 ExecuTorch
oncall: profiler	Profiler 性能分析问题（CPU、GPU、Kineto）
oncall: visualization	TensorBoard 集成问题

需避开的常见路由误区：

• MPS ≠ Mobile。 MPS (Metal Performance Shaders) 是 macOS/Apple Silicon 的 GPU 后端。切勿将 MPS 问题分流至 oncall: mobile。MPS 问题留在主队列中，打上 module: mps 即可。
• DTensor → oncall: distributed。 DTensor 问题哪怕没提到 DDP/FSDP，也一律路由给 oncall: distributed。
• ONNX → module: onnx。 不存在 oncall: onnx 这个标签。打上 module: onnx 并留在主队列即可。
• CI/releng → module: ci。 不要使用 oncall: releng。CI 基础设施问题请使用 module: ci。
• torch.compile + 分布式。 当 torch.compile 处理分布式算子（如 dist.all_reduce）出现问题时，通常需要同时打上 oncall: pt2 和 oncall: distributed，因为 Fix 可能涉及两边代码库。

注意： oncall: cpu inductor 是 PT2 的子队列。通用 Triage 阶段打上 oncall: pt2 即可。

4) 给 Issue 打标签（未转移/重定向时）

仅当 Issue 保留在通用主队列时：

• 根据受影响区域打上 1 个或多个 module: ... Label
• 当特定 Label 与通用 Label 同时存在时，优先使用具体 Label。参考 labels.json 里的描述说明来判断具体 Label 何时覆盖通用 Label（例如：SDPA 问题使用 module: sdpa 代替 module: nn；Flex Attention 问题使用 module: flex attention 代替 module: nn）。
• feature — 当前完全不存在的全新功能
• enhancement — 对现有可用功能的改进（例如：为已可通过 Fallback/Composite 运行的算子补充原生 Backend Kernel、性能优化、优化错误提示等）。如果是性能改进，需同时打上 module: performance。
• function request — 请求新函数，或为现有函数添加新参数/新模式
• 如果 Issue 描述该操作“目前可用”或“回退降级至”较慢路径，属于 enhancement，而非 feature

易遗漏的常见 Label — 需重点排查：

匹配条件	Label
段错误（Segfault）、非法内存访问、SIGSEGV	module: crash
性能问题：性能退化（Regression）、变慢或优化诉求	module: performance
Windows 系统特有 issue	module: windows
之前正常的功能现在损坏了	module: regression
原本正常、现在失效的文档/链接	module: docs + module: regression（不能打 enhancement）
仅仅是测试用例失败（而非底层功能故障）	module: tests
反向传播 / 梯度计算 Bug	module: autograd（需叠加算子对应的 module Label）
torch.linalg 算子或线性代数算子（solve、svd、eig、inv 等）	module: linear algebra
has workaround	仅当 Workaround 非显而易见且非同义反复时添加。若 Issue 内容为“X 在非连续 Tensor 上不生效”，那么调用 .contiguous() 是同义反面，而非 Workaround