增加集体通信逐项进程布局结构化输出

[ghangz]

这次改动补上了集体通信逐项进程布局结构化输出，主要是为了解决集体通信测试与结果整理流程里相关信息不够集中、人工整理成本较高的问题，让日常排查、验证和结果归档更直接。

实现上补充了对应工具或脚本逻辑，补上了对应测试，同时尽量保持现有用法不变，避免影响已有流程。

这一分支已经在沐曦算力环境完成实际验证，相关检查均已通过，现提交合入。

[gemini-code-assist]

Code Review

This pull request introduces a new Python utility, per_rank_layout.py, along with its unit tests, to preview the per-rank MACA_VISIBLE_DEVICES layout used by MCCL helpers. The feedback points out a potential configuration issue where hardcoded 8-GPU layouts are used even if max_gpus_per_node is configured differently, and suggests adding parameter validation to prevent invalid layouts.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

当 visible_device_per_rank 大于 1 且 max_gpus_per_node 不等于 8 时，由于代码中硬编码了 8 卡的布局模板（EVEN_NODE_LAYOUT 和 ODD_NODE_LAYOUT），会导致生成的 visible_devices 包含越界的 GPU 编号（例如在 4 卡节点上输出 0-7 的布局），从而产生错误的配置。此外，visible_device_per_rank 也不应该超过 max_gpus_per_node。

建议在 build_layout 函数中增加参数校验，以防止生成无效的配置。

Suggested change

	def build_layout(world_size: int, visible_device_per_rank: int = 1, max_gpus_per_node: int = 8) -> dict[str, object]:
	if world_size <= 0:
	raise ValueError("world size must be positive")
	if visible_device_per_rank <= 0:
	raise ValueError("visible_device_per_rank must be positive")
	if max_gpus_per_node <= 0:
	raise ValueError("max_gpus_per_node must be positive")
	def build_layout(world_size: int, visible_device_per_rank: int = 1, max_gpus_per_node: int = 8) -> dict[str, object]:
	if world_size <= 0:
	raise ValueError("world size must be positive")
	if visible_device_per_rank <= 0:
	raise ValueError("visible_device_per_rank must be positive")
	if max_gpus_per_node <= 0:
	raise ValueError("max_gpus_per_node must be positive")
	if visible_device_per_rank > max_gpus_per_node:
	raise ValueError("visible_device_per_rank cannot exceed max_gpus_per_node")
	if visible_device_per_rank != 1 and max_gpus_per_node != 8:
	raise ValueError("max_gpus_per_node must be 8 when visible_device_per_rank is not 1")