distributed-triage

分布式问题分诊子技能

此子技能接手 PT 级分诊机器人尚未完成的工作。它会处理已有 oncall: distributed 标签的问题，并执行二级分诊：分派给分布式子值班人员、按模块分类并标记为已分诊。

目录

• 可用的 MCP 工具
• 参考文件
• 评论去重
• 分布式问题分诊步骤
  • 步骤 0：已由人工分诊
  • 步骤 1：这确实是分布式问题吗？
  • 步骤 2：分派给分布式子值班人员
  • 步骤 3：分类模块
  • 步骤 4：类型标签
  • 步骤 5：高优先级 — 需要人工审核
  • 步骤 6：缺少复现信息
• 约束

**分布式标签参考：**有关此技能允许应用的标签，请参阅 distributed-labels.json。只能应用此文件中的标签。

**分布式分诊规则：**有关详细的分派指导、模块分类信号和置信度校准，请参阅 distributed-rubric.md。

**回复模板：**有关分布式专用评论模板，请参阅 templates.json。

---

可用的 MCP 工具

使用以下 GitHub MCP 工具进行分诊：

工具	用途
mcp__github__get_issue	获取问题详情和现有标签
mcp__github__get_issue_comments	获取现有问题评论
mcp__github__update_issue	应用标签或关闭问题
mcp__github__add_issue_comment	添加评论（仅用于请求复现信息或标记错误分类）
mcp__github__search_issues	查找类似问题以供参考

---

评论去重

添加任何问题评论之前：

1. 使用 mcp__github__get_issue_comments 读取现有评论。
2. 检查分诊机器人是否已发布相同模板，或实质相同的请求／说明。
3. 如果存在重复评论，不要再添加评论。继续执行仍然需要的非评论操作，例如添加标签。

即使措辞略有不同，或使用了较旧版本的模板，也应将评论视为重复。对于分布式问题分诊，这包括已有的分布式复现信息请求或已有的“非分布式”通知。

---

分布式问题分诊步骤

0) 已由人工分诊？

只有当问题同时具备以下两项时，才表示已由人工完成分类：

1. distributed-labels.json 中列出的任意 module: 标签，以及
2. 以下子值班标签之一：oncall: distributed parallelisms、oncall: distributed infra 或 oncall: distributed checkpointing。

如果两项都具备：

• 添加 bot-triaged + triaged 标签（人工分类已完成且置信度高）
• 停止 — 此问题已由人工分类。

如果只具备其中一项（有模块标签但没有子值班标签，或有子值班标签但没有模块标签），则分诊尚未完成 — 继续执行步骤 1。PT 级分诊机器人可以在 oncall: distributed 旁应用分布式模块标签，但它不会选择子值班人员；这正是你的工作。

仅此步骤就应能清理积压问题中的很大一部分。

1) 这真的是分布式问题吗？

阅读问题标题、描述和评论，判断该问题是否确实与分布式训练有关。

以下迹象表明这不是分布式问题：

• 单 GPU 问题，且没有分布式代码（例如，在单个 GPU 上使用 torch.nn，或单个设备上的 CUDA OOM）
• 构建／打包问题（例如，在 import torch 时出现 undefined symbol: ncclAlltoAll，且没有分布式代码）
• 纯粹的 torch.compile 问题，没有分布式组件
• 关于某个领域库（视觉、文本、音频）的问题，只是恰好提到了“distributed”

如果不是分布式问题：

1. 添加 triage review + bot-triaged 标签
2. 使用 templates.json 中的 not_distributed 模板发表评论，除非已有等效的“not distributed”评论
3. 不要移除 oncall: distributed — 由人工值班人员重新分派
4. 停止

2) 分派给分布式子值班团队

每个问题只能有一个子值班标签。如果问题已有三个子值班标签之一（oncall: distributed parallelisms、oncall: distributed infra 或 oncall: distributed checkpointing），则保持原样——即使你自己的分类会选择其他标签，也不要再添加第二个子值班标签。根据已有的子值班标签决定下一步（如果是 oncall: distributed parallelisms，则继续执行第 3 步；否则根据以下规则添加 bot-triaged 并停止）。

如果没有子值班标签，请根据 distributed-rubric.md 中的分派规则，恰好应用一个标签：

子值班标签	适用情况
oncall: distributed parallelisms	FSDP、DDP、DTensor、张量并行、上下文并行、流水线并行。不确定时默认使用此标签。
oncall: distributed infra	c10d、进程组、集合通信、NCCL/Gloo/MPI 后端、elastic/torchrun、RPC、存储、分布式工具、DeviceMesh、对称内存
oncall: distributed checkpointing	分布式检查点保存／加载、DCP、state_dict 工具、异步检查点

参考 distributed-rubric.md 第 1 节中的分派决策树和边缘情况，确定正确的子值班标签。

分派给 oncall: distributed infra 或 oncall: distributed checkpointing 后：

• 添加 bot-triaged（子值班分派是明确且完整的处理结果）
• 停止 — 后续分诊由子值班团队负责

分派给 oncall: distributed parallelisms 后：

• 继续执行第 3 步进行模块分类

3) 分类模块

根据问题描述、评论、代码片段和堆栈跟踪，将问题归入一个或多个分布式模块。请参考 distributed-rubric.md 中的模块分类信号。

基于置信度采取行动：

置信度	标准	操作
HIGH 或 MEDIUM	明确提及模块、明显使用相关 API，或根据上下文推测可能涉及某个模块	添加 module: 标签 + bot-triaged + triaged
LOW	无法确定模块——描述含糊、没有代码、没有堆栈跟踪	添加 triage review + bot-triaged（不添加 triaged — 转交人工处理）

规则：

• 如果问题涉及多个模块，可以应用多个模块标签（例如，对于涉及 DTensor Bug 的 FSDP2 问题，可添加 module: fsdp + module: dtensor）。
• 如果问题已有 oncall: pt2，请勿移除。应同时添加分布式模块标签。
• 如果无法确定模块，请添加 triage review + bot-triaged — 不要猜测模块标签。

4) 类型标签

如果问题不是错误报告，请添加相应的类型标签：

• feature — 完全新增的功能，目前不存在任何形式的实现
• enhancement — 对已有可用功能的改进（例如，性能优化、提供更好的错误消息，或为原本通过回退路径运行的操作添加原生后端）

分布式问题大多是错误报告——请勿为错误添加类型标签。如果问题称某项操作“目前可用”或“会回退到”较慢的路径，则属于 enhancement，而非 feature。如果改进涉及性能，也请添加 module: performance。

5) 高优先级 — 需要人工审核

重要： 如果你认为某个问题优先级较高，必须：

1. 添加 triage review 标签，且不要添加 bot-triaged

未经人工确认，请勿直接添加 high priority。

分布式问题的高优先级标准：

• 分布式代码中发生崩溃、段错误或非法内存访问
• 静默的正确性问题（集合通信结果错误、梯度同步不正确）
• 相较于先前版本出现回归（例如，FSDP 在 2.x 中可用，但在 2.y 中失效）
• 影响多节点训练的卡住问题（NCCL 超时、集合通信死锁）
• 分布式检查点期间发生数据损坏
• c10d 或进程组代码中的内部断言失败
• 影响许多用户或核心分布式组件

6) 缺少复现步骤

如果问题缺少最简复现脚本：

1. 添加 needs reproduction + bot-triaged 标签
2. 使用 templates.json 中的 needs_distributed_reproduction 模板发表评论，除非已有等效的分布式复现请求

以下情况请勿请求复现：

• 问题已包含代码片段、脚本或可供他人照做的复现步骤
• 问题是功能请求（无需复现）
• 已提供多节点脚本（即使无法在本地运行，也算作复现）

---

约束

请勿：

• 关闭问题（只有 PT 级机器人或人工才能关闭问题）
• 删除现有标签——只能添加标签
• 删除 oncall: distributed——即使问题标签有误，也要保留
• 删除 oncall: pt2——如果已存在，就保留
• 删除 bot-triaged 或 triaged——这些标签由父级技能应用，必须保留
• 在对问题分类不确定时添加 triaged——也就是说，只要操作还会添加 triage review 或 needs reproduction 标签，或处于 §5 的高优先级流程中，就不要添加
• 添加 distributed-labels.json 中不存在的标签
• 除使用步骤 1（标签错误）或步骤 6（复现）中的模板外，不要在问题下发表评论
• 如果机器人已在问题下发布相同模板或实质等效的消息，不要发表评论
• 将问题分配给用户
• 直接添加 high priority——请使用 triage review，由人工决定

请：

• 保持谨慎——有疑问时，添加 triage review 以供人工关注
• 只要机器人处理过问题，就添加 bot-triaged，无论置信度如何。对于低置信度或不确定的情况，应同时添加 triage review，以免定时任务再次选中该问题。（例外：§5 的高优先级流程有意不添加 bot-triaged。）
• 仅在完成有把握的分类时添加 triaged：人工已完成分类（步骤 0）、有把握地完成子 oncall 路由（步骤 2），或以高／中置信度完成模块分类（步骤 3）。
• 始终先添加子 oncall 标签（步骤 2），再添加模块标签（步骤 3）
• 分类前阅读问题全文，包括评论
• 每次发表评论前阅读现有评论，并跳过重复的机器人消息
• 最终确定前，检查评分标准中的“常见标签误用陷阱”部分