PyTorch 分布式 Issue 自动分诊：Claude Skills 二级分诊流水线的规则设计与源码实现

PyTorch 仓库在 .claude/skills/ 目录下维护了一套基于 Claude Skills 的 Issue 自动分诊体系，其中 distributed-triage 子技能专门负责处理已路由到 oncall: distributed 队列的 GitHub Issue：判定其是否真是分布式问题、路由到三个分布式子 oncall 之一、按模块打标并标记 triaged。本文完整拆解这套二级分诊流水线的设计脉络——从七步分诊流程、路由决策树、模块分类信号与置信度校准，到白名单标签约束和三个 hook 校验脚本的源码实现，帮助读者理解如何用"规则文档 + 白名单 + 强制校验 hook"组合，把 LLM 的 Issue 分诊行为约束在可审计、可复现的边界内。

1. 技能定位：父技能之后接力的二级分诊

分布式分诊不是孤立的，它是 triaging-issues 父技能 流水线中的一环。父技能在 Step 3 中负责把疑似分布式训练（DDP、FSDP、RPC、c10d、DTensor、DeviceMesh、symmetric memory、context parallel、pipelining）的 Issue 打上 oncall: distributed 标签，并停止后续分诊——子 oncall 队列归子团队所有。随后 distributed-triage 子技能（即 SKILL.md 所定义的技能）接管，执行"二级分诊"：

1. 路由（Routing）：把 Issue 分派到三个分布式子 oncall 标签之一；
2. 模块分类（Classification）：打上若干 module: 标签；
3. 状态标记（Marking）：打上 triaged 标记分诊完成。

这种两级拆分的关键动机是职责隔离：PT 级机器人只负责"是否属于分布式"这一粗粒度判断，不选择子 oncall；子 oncall 的选择、模块标签、置信度判断全部由子技能承担，且子技能只被允许使用白名单内的标签。

2. 技能文件构成与职责划分

该技能由 4 个文件组成，主文档 + 3 个参考文件：

文件	职责
SKILL.md	主文档：MCP 工具清单、评论去重规则、七步分诊流程、约束红线
distributed-labels.json	标签白名单：子技能只允许打名单内的标签
distributed-rubric.md	分诊细则：子 oncall 路由规则、模块分类信号、置信度校准、常见误标陷阱
templates.json	响应模板：needs_distributed_reproduction 与 not_distributed 两个评论模板

此外，SKILL.md 的 frontmatter 通过 hooks.PreToolUse 声明了两条拦截规则，在调用特定 GitHub MCP 工具前强制执行父技能的校验脚本：

• matcher 为 mcp__github__issue_write | mcp__github__update_issue | mcp__github__add_issue_comment | mcp__github__transfer_issue 时，执行 validate_issue_target.py；
• matcher 为 mcp__github__issue_write | mcp__github__update_issue 时，执行 validate_labels.py。

这套"文档定义行为 + hook 强制兜底"的结构是理解整个技能的关键：即使 LLM 试图打白名单外的标签或篡改其他 Issue，也会在工具调用前被脚本拦截。

3. 分诊操作的安全边界：MCP 工具与评论去重

3.1 可用的 MCP 工具

技能限定分诊过程中只能使用以下 GitHub MCP 工具，每个工具的用途被明确约束：

工具	用途
mcp__github__get_issue	获取 Issue 详情与现有标签
mcp__github__get_issue_comments	获取已有评论
mcp__github__update_issue	打标签或关闭 Issue
mcp__github__add_issue_comment	添加评论（仅用于索要复现或标记误标两种场景）
mcp__github__search_issues	搜索相似 Issue 以获取上下文

注意 add_issue_comment 的括号限定——这直接对应 SKILL.md 约束章节中"除 Step 1（误标通知）和 Step 6（索要复现）外不得添加任何评论"的红线。

3.2 评论去重规则

在添加任何评论之前，必须执行三步去重：

1. 用 mcp__github__get_issue_comments 读取已有评论；
2. 检查分诊机器人是否已发布过相同模板或实质等价的内容；
3. 若存在重复，不再添加评论，但继续执行仍然需要的非评论动作（如打标签）。

去重判定采用"实质等价"标准而非字面匹配：即使措辞略有差异、或使用的是旧版模板，也视为重复。对分布式分诊而言，这特别包括已存在的"分布式复现请求"评论和已存在的"非分布式"通知评论。这一规则的目的是避免机器人在多次运行中反复刷屏同一 Issue。

4. 七步分诊流程详解

Step 0：是否已被人工完整分类

人工"完整分类"的充要条件是同时满足两个条件：

1. 带有 distributed-labels.json 中列出的任意一个 module: 标签；
2. 带有三个子 oncall 标签之一：oncall: distributed parallelisms、oncall: distributed infra 或 oncall: distributed checkpointing。

两者齐备时：添加 bot-triaged + triaged 标签，然后停止——人工已经完成了分类。若只有一个条件满足（有模块标签但无子 oncall，或反之），分诊视为不完整，继续 Step 1。文档特别指出：PT 级机器人可以打分布式模块标签，但它不会选择子 oncall，那是子技能的职责。SKILL.md 还备注"仅这一步就能清掉积压中的很大一部分"。

Step 1：它真的是分布式问题吗

读取 Issue 标题、描述与评论，判断其是否确实与分布式训练相关。文档给出了"不是分布式问题"的四类典型信号：

• 无分布式代码的单 GPU 问题（如单卡 torch.nn 报错、单设备 CUDA OOM）；
• 构建/打包问题（如 import torch 时出现 undefined symbol: ncclAlltoAll，但用户根本没跑分布式代码）；
• 纯 torch.compile 问题且无分布式成分；
• 领域库（视觉、文本、音频）问题，只是碰巧提到了 "distributed"。

判定为非分布式问题时的动作序列：

1. 添加 triage review + bot-triaged 标签；
2. 除非已存在等价的"非分布式"评论，否则使用 templates.json 中的 not_distributed 模板发评论；
3. 不要移除 oncall: distributed——保留它让人工 oncall 重新路由；
4. 停止。

Step 2：路由到分布式子 oncall

核心规则：每个 Issue 恰好携带一个子 oncall 标签。若 Issue 已有三个子 oncall 之一，保持原样，不得添加第二个子 oncall（即使自己分类出的结果不同），并按已有子 oncall 决定后续：是 oncall: distributed parallelisms 则继续 Step 3；否则添加 bot-triaged 并停止。

若无子 oncall，则按 distributed-rubric.md 的路由规则打且仅打一个：

子 oncall 标签	适用场景
oncall: distributed parallelisms	FSDP、DDP、DTensor、张量并行、上下文并行、流水线并行。拿不准时的默认值
oncall: distributed infra	c10d、进程组、集合通信、NCCL/Gloo/MPI 后端、elastic/torchrun、RPC、stores、分布式工具、DeviceMesh、symmetric memory
oncall: distributed checkpointing	分布式 checkpoint 保存/加载、DCP、state_dict 工具、异步 checkpoint

路由后的行为分叉：

• 路由到 oncall: distributed infra 或 oncall: distributed checkpointing：添加 bot-triaged（路由本身是自信且完整的结论），然后停止——后续分诊归子 oncall 团队；
• 路由到 oncall: distributed parallelisms：继续 Step 3 做模块分类。

Step 3：模块分类（置信度驱动的动作表）

从 Issue 描述、评论、代码片段与堆栈中，将其归入一个或多个分布式模块。动作由置信度决定：

置信度	判据	动作
HIGH 或 MEDIUM	明确提到模块、API 使用明显、或根据上下文可合理推断模块	添加 module: 标签 + bot-triaged + triaged
LOW	无法确定模块——描述含糊、无代码、无堆栈	添加 triage review + bot-triaged（不打 triaged，踢回人工）

配套规则：

• 跨模块的 Issue 可以打多个模块标签（例如 FSDP2 问题命中 DTensor bug 时，module: fsdp + module: dtensor 并存）；
• 若 Issue 已被打上 oncall: pt2，不得移除，在其旁边追加分布式模块标签；
• 模块不明时打 triage review + bot-triaged，不要猜模块标签。

Step 4：类型标签

非 bug 报告的 Issue 需要类型标签：

• feature —— 今天尚不存在任何形式的完全新功能；
• enhancement —— 对已经能工作的东西做改进（性能优化、更好的报错信息、为已有 fallback 路径的 op 增加原生后端等）。

文档强调：大多数分布式 Issue 是 bug 报告，bug 不加类型标签。一个实用的判别式：如果 Issue 说该操作"currently works"或"falls back to"较慢路径，那是 enhancement 而非 feature；若 enhancement 与性能相关，还要追加 module: performance。

Step 5：高优先级——强制人工复核

这是文档中标注 CRITICAL 的一步：若认为某 Issue 属于高优先级，必须只添加 triage review 且不添加 bot-triaged，并绝不直接添加 high priority 标签——那需要人工确认。

分布式 Issue 的高优先级判据：

• 分布式代码中的崩溃 / 段错误 / illegal memory access；
• 静默正确性问题（集合通信结果错误、梯度同步不正确）；
• 相对旧版本的回归（如 FSDP 在 2.x 正常、2.y 坏掉）；
• 影响多机训练的挂死（NCCL 超时、集合通信死锁）；
• 分布式 checkpoint 过程中的数据损坏；
• c10d 或进程组代码内部的断言失败；
• 大量用户受影响，或核心分布式组件被波及。

Step 6：缺少复现

若 Issue 缺少最小复现脚本：

1. 添加 needs reproduction + bot-triaged 标签；
2. 除非已存在等价的分布式复现请求，否则使用 templates.json 中的 needs_distributed_reproduction 模板发评论。

同时文档明确了不应索要复现的三种情况：

• Issue 已包含代码片段、脚本或他人可遵循的复现步骤；
• Issue 是功能请求（不需要复现）；
• 已提供多机脚本（即使本地跑不起来，也算复现）。

5. 路由决策树：优先级与边缘案例

rubric 第 1 节定义了三个子 oncall 的详细覆盖范围和路由优先级。每个子 oncall 的覆盖面：

• oncall: distributed parallelisms（默认）：用户直接打到的并行训练 API——FSDP1/FSDP2（FullyShardedDataParallel、fully_shard、分片策略、混合精度）、DDP（DistributedDataParallel、梯度同步、参数广播）、DTensor（distribute_tensor、Shard/Replicate 放置、张量重分布）、张量并行、上下文并行、流水线并行（PipelineSchedule、PipelineStage）、与分布式训练配合使用的激活 checkpoint。
• oncall: distributed infra：通信基础设施层——c10d/进程组（init_process_group、new_group、TCPStore/FileStore）、集合通信（all_reduce、all_gather、broadcast、reduce_scatter、all_to_all、barrier）、后端（NCCL、Gloo、MPI、UCC）、elastic/torchrun（rendezvous、agent、worker 管理）、RPC、分布式工具（调试工具、flight recorder、分布式日志）、DeviceMesh、Symmetric Memory。
• oncall: distributed checkpointing：分布式模型状态的保存/加载——DCP（torch.distributed.checkpoint 的 save/load/state_dict）、state dict 工具（get_model_state_dict 等）、checkpoint 格式（文件系统 planner、HDF5、跨 world size resharding）、异步 checkpoint。

当 Issue 可能落入多个桶时，按如下优先级裁决：

1. oncall: distributed checkpointing——如果问题在于分布式状态的保存/加载；
2. oncall: distributed infra——否则，若问题在通信/基础设施层；
3. oncall: distributed parallelisms——其余情况（也是拿不准时的默认值）。

rubric 还给出了四个典型的边缘案例裁决：

案例	裁决
FSDP 训练中的 NCCL 超时	路由到 oncall: distributed infra——NCCL 超时时 bug，FSDP 只是用户上下文
FSDP state_dict 保存	若关于 checkpoint 保存/加载 → oncall: distributed checkpointing；若关于 FSDP 内部 state dict 处理（如 ShardedStateDictConfig）→ oncall: distributed parallelisms
torchrun + DDP	问题在启动/rendezvous → oncall: distributed infra；启动正常但 DDP 训练本身失败 → oncall: distributed parallelisms
init_process_group 时的后端选择错误	路由到 oncall: distributed infra

6. 模块分类信号与置信度校准

rubric 第 2 节为每个模块标签定义了四类信号：关键词、import 路径、堆栈模式、易混淆点。以下覆盖全部 16 个模块标签的核心信号：

模块标签	关键词 / 信号要点	易混淆提醒
module: fsdp	FSDP、fully_shard、ShardingStrategy、MixedPrecision、FULL_SHARD、CPUOffload；路径 torch.distributed.fsdp、torch.distributed._composable.fsdp	"sharding" 也可能是 DTensor 分片，需确认 FSDP 专属 API
module: ddp	DistributedDataParallel、find_unused_parameters、gradient_as_bucket_view、static_graph	"data parallel" 可能指遗留 DataParallel（单机），需确认是 DistributedDataParallel
module: dtensor	DTensor、distribute_tensor、Shard/Replicate、redistribute	DTensor 是 FSDP2 与 TP 的底座：FSDP2 用户撞上 DTensor 错误时两个标签都打
module: c10d	ProcessGroup、init_process_group、all_reduce 等集合通信、TCPStore/FileStore/PrefixStore、Work handle	几乎所有分布式问题都会间接触及 c10d；仅当问题确实在集合通信/PG/store 层才打，c10d 只是调用路径上的不算
module: nccl	ncclSystemError、NCCL 超时、NCCL watchdog、ProcessGroupNCCL、ncclCommInitRank	import torch 时的 "NCCL error" 且无分布式代码是打包问题（module: binaries），不是 module: nccl
module: DeviceMesh	init_device_mesh、mesh_dim、mesh["dp"]/mesh["tp"]	DeviceMesh 被 FSDP2、DTensor、TP 共用；只有 bug 在 DeviceMesh 本身才打
module: pipelining	PipelineSchedule、PipelineStage、ScheduleGPipe、Schedule1F1B	—
module: rpc	rpc_sync、rpc_async、RRef、distributed autograd	RPC 属遗留代码、维护较少，许多 RPC Issue 可能是 won't-fix
module: elastic	torchrun、elastic_launch、RendezvousHandler、torch.distributed.run	"torchrun crashes" 既可能是 elastic 问题，也可能是用户脚本经 torchrun 崩溃——要看实际报错
module: data parallel	torch.nn.DataParallel、replicas、scatter/gather	遗留单机数据并行；判别法：用户是否调用了 init_process_group？没有就是遗留 DataParallel
module: symm_mem	symmetric_memory、symm_mem、SymmetricMemory	—
module: context parallel	context parallel、CP、序列并行（指上下文并行时）	—
module: activation checkpointing	torch.utils.checkpoint、activation checkpointing、recomputation	仅限激活 checkpoint；"checkpoint 保存"是 oncall: distributed checkpointing 的事
module: mpi	MPI 后端	—
module: threaded pg	多线程进程组	—
module: distributed_tool	分布式训练辅助工具	—

置信度校准示例

rubric 第 3 节用具体案例校准了 HIGH / MEDIUM / LOW 三档：

• HIGH："FSDP2 使用 MixedPrecision 时 fully_shard 崩溃" → module: fsdp（明确提到 API）；model = DDP(model, device_ids=[rank]) 挂死 → module: ddp；all_reduce 期间 ncclSystemError: Connection refused → module: nccl + module: c10d；
• MEDIUM："多卡训练 100 步后挂死"——无代码但提到多 GPU，可能是 DDP、FSDP 或 c10d，按其他线索最佳猜测；"checkpoint 在 GPU 数量不同时加载报错"——可能是 DCP，也可能是 FSDP state dict；同时提到 DTensor 与 FSDP2 的问题——大概率 module: fsdp + module: dtensor 但根因未定；
• LOW："我的模型在多卡上不收敛"——无代码、无报错、未提任何分布式 API；"torch.distributed doesn't work"——过于含糊。

LOW 置信度对应 Step 3 的动作：打 triage review + bot-triaged，把决定权交还人工。

常见误标陷阱

rubric 第 4 节列出的红线包括：

• NCCL import 错误出现在单卡场景：import torch 时的 undefined symbol: ncclAlltoAll 是打包/构建问题（module: binaries），不是分布式问题；
• 单卡 CUDA 错误：无任何分布式代码的 OOM 或 device-side assert；
• torch.compile 错误：即使发生在分布式代码上，根因也可能在编译器侧，属于 oncall: pt2；
• 单机 DataParallel：技术上算分布式但优先级极低，仍打 module: data parallel。

另一条总原则是"按根因打标，而不是按关键词"：堆栈穿过 c10d 不代表 module: c10d（bug 可能在于 FSDP 对集合通信的使用方式）；报错提到 "NCCL" 可能是 c10d watchdog 超时而非 NCCL bug；标题里有 "distributed" 不等于它是分布式问题。

7. 约束红线：DO / DO NOT

SKILL.md 的 Constraints 章节是子技能的行为边界清单：

禁止（DO NOT）：

• 关闭 Issue（只有 PT 级机器人或人工可以关）；
• 移除任何已有标签——只允许追加标签；
• 移除 oncall: distributed——即使误标也保留；
• 移除 oncall: pt2——已存在就保留；
• 移除 bot-triaged 或 triaged——它们由父技能流程打上，必须保留；
• 在分类不自信时添加 triaged——即任何同时打了 triage review 或 needs reproduction 的动作，以及 §5 高优先级流程，都不加 triaged；
• 添加 distributed-labels.json 之外的任何标签；
• 除 Step 1（误标通知）和 Step 6（索要复现）两个模板场景外添加评论；
• 在机器人已发布过相同模板或实质等价消息时重复添加评论；
• 把 Issue 指派给用户；
• 直接添加 high priority——只能用 triage review 交给人工决定。

必须（DO）：

• 保守行事——拿不准就打 triage review 请人工介入；
• 只要机器人处理过 Issue 就打 bot-triaged，与置信度无关；LOW 置信度或不确定时与 triage review 配对，这样定时扫尾（cron sweep）不会重复捞起该 Issue（例外：§5 高优先级流程刻意不打 bot-triaged）；
• triaged 只在达到自信且完整的分类时打：人工已分类（Step 0）、自信的子 oncall 路由（Step 2）、或 HIGH/MEDIUM 置信度的模块分类（Step 3）；
• 先打子 oncall 标签（Step 2）再打模块标签（Step 3）；
• 分类前通读 Issue 全文包括所有评论；每次评论动作前先读已有评论并跳过重复的机器人消息；
• 定稿前检查 rubric 的 "Common Mislabel Traps" 章节。

8. 源码级强制：三个 hook 校验脚本

文档规则最终由三个 Python hook 脚本在工具调用层强制执行，它们通过 SKILL.md frontmatter 中的 PreToolUse / PostToolUse 声明接入。

8.1 目标锁定：validate_issue_target.py

validate_issue_target.py 拦截所有 Issue 变更类 MCP 调用（issue_write、update_issue、add_issue_comment、transfer_issue），保证机器人只能操作"工作流指定的那一个 Issue"：

• 从环境变量 GITHUB_REPOSITORY（owner/repo 格式）与 TRIAGE_ISSUE_NUMBER 读取期望目标，两者缺一或格式非法即抛错；
• 从 MCP 工具入参中提取 owner/repo/issue_number 作为请求目标，并对 mcp__github__issue_write 额外限定 method 必须为 update（即禁止借 issue_write 创建或做其他操作）；
• 两者不相等即向 stderr 打印 Blocked issue mutation 并以 exit code 2 退出——按 Claude hook 约定，退出码 2 表示阻断本次工具调用并把反馈回传给模型。

从源码结构看，这层锁防止了"串号"事故：分诊机器人在处理 Issue #A 时，任何指向 #B（或其他仓库）的写操作都会在到达 GitHub 之前被拦截。

8.2 标签净化：validate_labels.py

validate_labels.py 拦截 issue_write / update_issue 调用，对请求中的标签做五重处理：

1. 剥离禁止标签：FORBIDDEN_PATTERNS（正则匹配 ^ciflow/、^test-config/、^release notes:、^ci-、^ci:、^sev、deprecated）加 FORBIDDEN_EXACT 精确匹配列表（actionable、merge blocking、needs design、needs reproduction、needs research、oncall: releng）。注意：needs reproduction 在父技能白名单里是保留给人工的，但被 hook 列为禁止项——子技能流程中的 needs reproduction 由父技能 Step 1.55 场景处理，这里体现了父/子技能在标签权限上的差异。被剥离标签的调用会被自动补上 triage review 转人工；
2. 剥离不存在标签：合法标签集是父技能 labels.json 与子技能 distributed-labels.json 的并集（见 load_valid_labels() 中 labels |= _load_labels_from_file(DISTRIBUTED_LABELS_FILE)），不在并集内的标签被丢弃；
3. 剥离冗余标签：REDUNDANT_PAIRS 定义的"具体标签 + 泛化标签"共存时丢弃泛化者（当前为 module: rnn 与 module: nn）；
4. 兜底：若过滤后一个标签都不剩，不直接阻断（阻断会导致模型反复重试后放弃，Issue 反而没有任何状态标签），而是回退为只打 triage review 转人工；
5. 与现有标签合并后重写工具入参：脚本通过 gh issue view --json labels 拉取 Issue 当前标签，与新标签取并集排序后，以 updatedInput 重写 MCP 调用。这一步很关键——因为 MCP 的 update_issue 对 labels 字段是全量 SET 语义，不做合并就会抹掉人工已打的标签；hook 在工具层把"追加"语义强制出来，与 SKILL.md"只加不删"的红线形成双重保障。

脚本退出码约定：0 表示放行（可能伴随 stdout 上的 hookSpecificOutput JSON 重写入参），2 表示阻断（如入参 JSON 解析失败、无法拉取现有标签等 hook 自身错误）。调试信息默认追加到 /tmp/triage_hooks.log，可用环境变量 TRIAGE_HOOK_DEBUG_LOG 改路径、TRIAGE_HOOK_VERBOSE 打开 stderr 输出。

8.3 事后盖章：add_bot_triaged.py

add_bot_triaged.py 是父技能声明的 PostToolUse hook：在任何一次 Issue 变更（标签/评论/关闭/转移）成功之后，直接调用 gh issue edit <n> --repo owner/repo --add-label bot-triaged 为 Issue 补上 bot-triaged 标签，让定时扫尾任务知道"机器人已碰过这个 Issue"。该脚本对所有异常都吞掉并以 exit 0 退出——它是尽力而为的状态标记，不应阻断主流程。子技能文档中"打了 bot-triaged 的 Issue 不会被 cron 重复捞起"这一机制，正是依赖这个 post-hook 与 Step 5 高优先级流程"刻意不打"的例外配合。

9. 标签白名单与响应模板

9.1 白名单标签（distributed-labels.json 全文）

distributed-labels.json 声明自己是"主 labels.json 的子集"（"repo": "pytorch/pytorch"），共 26 个标签，分为三组：

三个子 oncall（3 个）：

标签	描述
oncall: distributed parallelisms	分布式并行 oncall（FSDP、DDP、DTensor、DeviceMesh、张量/上下文/流水线并行、symmetric memory）
oncall: distributed infra	分布式基础设施 oncall（c10d、进程组、NCCL/Gloo/MPI 后端、elastic、torchrun、stores）
oncall: distributed checkpointing	一切与分布式 checkpoint 相关的 Issue 都应挂此 oncall

模块标签（16 个）：

module: fsdp（FSDP1 与 FSDP2）、module: ddp（DistributedDataParallel）、module: dtensor（Distributed Tensor）、module: c10d（进程组、集合通信、stores、通信后端）、module: DeviceMesh（设备网格抽象）、module: pipelining（流水线并行）、module: rpc（RPC、分布式 autograd、RRef）、module: nccl（NCCL 后端问题）、module: elastic（TorchElastic）、module: data parallel（遗留 DataParallel，明确注明"不是 DistributedDataParallel"）、module: symm_mem（对称内存）、module: context parallel（上下文并行）、module: activation checkpointing（与分布式配合使用的激活 checkpoint）、module: mpi（MPI 后端）、module: threaded pg（多线程进程组）、module: distributed_tool（分布式训练辅助工具）。

流程与类型标签（7 个）：

bot-triaged（机器人已分诊）、triaged（团队已审视并分诊到合适模块）、feature（今天尚不存在的新功能）、enhancement（对已有功能的改进）、module: performance（性能问题）、triage review（需要人工审查）、needs reproduction（需要最小复现脚本）。

9.2 两个响应模板（templates.json 全文）

templates.json 定义了两条机器人评论，均落款 "This comment was generated by PTD's claude triage bot."：

needs_distributed_reproduction（动作：加 needs reproduction 标签 + 评论；使用时机：Issue 缺少最小复现脚本且机器人无法自信地确定模块）：

Thanks for the report! To help us investigate this distributed issue, could you provide:

1. Minimal reproduction script — a self-contained script we can run
2. Environment details: Number of nodes and GPUs per node / How you launch the job (torchrun, mp.spawn, etc.) / PyTorch version (torch.__version__) / NCCL version (if applicable) / GPU model and driver version
3. Full error logs — ideally from all ranks (at minimum rank 0), including the full stack trace
4. Distributed init method — env://, tcp://, file://, etc.

A self-contained script that reproduces on a single node with 2 GPUs is ideal, if possible.

这条模板把分布式问题的"最小信息集"固化了下来：节点数/每节点 GPU 数、启动方式、PyTorch 与 NCCL 版本、GPU 型号与驱动、全 rank 错误日志（至少 rank 0）、初始化方式——比单卡问题的复现要求多出并行拓扑与多 rank 日志两个维度。

not_distributed（动作：加 triage review 标签，不移除 oncall: distributed；使用时机：Issue 疑似误标，实际并非分布式训练问题）：

After reviewing this issue, it appears it may not be related to distributed training (DDP, FSDP, DTensor, c10d, etc.). We've flagged it for human review so the oncall can re-route it to the correct team.

If this issue does involve distributed training, please update the description with details about your distributed setup and we'll re-evaluate.

10. 与 torch.compile 的交叉地带

rubric 第 5 节专门处理"PT2 + 分布式"重叠场景——当 Issue 同时涉及 torch.compile 与分布式时：

• 错误发生在编译器侧（dynamo trace、inductor 代码生成、AOTAutograd 编译分布式 op 时）→ 主要归 oncall: pt2，但为可见性仍要追加相应的分布式 module: 标签；
• 错误发生在分布式运行时、只是编译之后被触发 → 主要归分布式，若已有 oncall: pt2 则保留；
• 永不移除 PT 级机器人已打的 oncall: pt2，只在其旁边追加分布式标签；
• 常见模式："torch.compile breaks FSDP" → 大概率需要 oncall: pt2 + module: fsdp 并存。

这与 SKILL.md Step 3 中"已有 oncall: pt2 不得移除"的规则相互呼应，也解释了为什么 validate_labels.py 采用两份 labels 文件的并集作为合法集：一个分布式 Issue 在整个生命周期里可能先后经过两个技能的标签权限。

11. 小结：这套流水线做对了什么

回顾 distributed-triage 子技能的完整设计，它对"LLM 操作 GitHub Issue"这一高风险场景给出了几个可借鉴的工程手段：

1. 权限最小化：26 个标签的白名单（distributed-labels.json）+ hook 层并集校验，机器人物理上打不出名单外的标签；
2. 目标锁定：环境变量注入期望的 owner/repo#issue，任何跨 Issue 写入在工具层被拦截；
3. 只加不删：update_issue 的全量 SET 语义被 hook 用"拉取现有标签 → 并集 → 重写入参"改写为追加语义，机器人在机制上无法移除人工标签；
4. 置信度分级 + 人工兜底：HIGH/MEDIUM 置信度自动完成、LOW 置信度和高优先级一律降级为 triage review，triaged 与 triage review/needs reproduction/高优先级流程互斥；
5. 幂等与去重：评论前先读全量评论、实质等价即跳过，post-hook 幂等地补 bot-triaged，保证 cron 重复扫描不会刷屏或重复分诊；
6. 规则文档与代码分离：SKILL.md 管流程、rubric 管裁决细节、labels 管权限、templates 管话术，四文件各司其职，任何一项都可独立演化。

阅读路径建议：先读 SKILL.md 掌握七步流程与约束，再对照 distributed-rubric.md 的路由与信号表，最后到 triaging-issues/scripts/ 查看 hook 脚本如何把规则变成不可绕过的代码。