ECC pytorch-build-resolver 深度解析：PyTorch 运行时与 CUDA 训练错误修复 Agent 的完整工作机制

本文以 ECC（Everything Claude Code）仓库中的 Kiro Agent 定义文件 .kiro/agents/pytorch-build-resolver.md 为主体，完整拆解这个 PyTorch 错误修复专家 Agent 的职责边界、诊断命令链、六步修复工作流、十类常见错误的修复模式表、形状/内存调试手段、停止条件与输出契约，并结合仓库内的编排规则与配套 Skill，说明它如何被自动调度进 build 修复链路、如何落地到 Kiro 项目中。读完本文，你可以掌握一个"外科手术式"修复 PyTorch 训练崩溃的方法论，并知道如何将该 Agent 安装到 Kiro 项目中使用。

1. 定位：ECC 多语言 Agent 体系中的 PyTorch 专项修复者

ECC 是一个面向 Claude Code、Codex、OpenCode、Cursor 等编码 Agent 的性能优化系统，仓库内置 68 个专用 Agent、286 个 Skill、94 个 Slash 命令（见 AGENTS.md）。pytorch-build-resolver 是其中的语言级构建/运行时错误修复者（build resolver）家族成员，与 cpp-build-resolver、go-build-resolver、rust-build-resolver、java-build-resolver、kotlin-build-resolver 等并列，但它是唯一专门处理深度学习运行时错误而非编译期错误的成员——PyTorch 程序往往能通过导入与编译，却在训练循环运行到某个 batch 时才因张量形状、设备放置、显存耗尽而崩溃，这类"运行时故障"需要完全不同的诊断路径。

该 Agent 在仓库中有多处登记，可作为事实依据：

• 主 Agent 目录：agents/pytorch-build-resolver.md（Claude Code 主格式）
• Kiro 适配目录：.kiro/agents/pytorch-build-resolver.md（本文主体，Kiro IDE 格式）
• AGENTS.md 的 Available Agents 表：pytorch-build-resolver | PyTorch runtime/CUDA/training errors | PyTorch build/training failures
• CHANGELOG.md：该 Agent 随 v1.9.0 发布（PR #549），与 pytorch-patterns Skill（PR #550）同批上线，共同构成 ECC 的 PyTorch 工程化能力

在 agents/mle-reviewer.md 的"Reuse Existing Review Lanes"一节中，还明确了分工边界：当张量形状、设备放置、梯度、CUDA、DataLoader 或 AMP 故障阻塞训练/推理时，MLE 审查 Agent 应把问题移交 pytorch-build-resolver；而 CI 依赖、原生扩展等非 PyTorch 本身的环境失败则归 build-error-resolver。这划清了"框架内运行时错误"与"环境/依赖错误"的责任边界。

1.1 两种格式的差异：主格式与 Kiro 格式

同一 Agent 在仓库中存在两种定义，理解差异对使用者很重要：

维度	agents/pytorch-build-resolver.md（主格式）	.kiro/agents/pytorch-build-resolver.md（Kiro 格式，本文主体）
frontmatter 工具声明	tools: Read, Write, Edit, Bash, Grep, Glob	allowedTools: read, shell
模型声明	model: sonnet	无（.kiro/README.md 说明 Kiro 中 Agent 模型由用户在 Kiro 侧的当前模型选择决定）
Prompt Defense Baseline	有（防注入基线条目）	无
错误模式表	10 行，错误列含完整异常前缀（如 RuntimeError: / ValueError: / IndexError:）	10 行，错误列为缩写形式
形状调试	额外提供 torchsummary 全模型结构打印示例	仅单点 shape 打印
内存调试	额外提供 torch.cuda.memory_allocated/reserved/max_memory_allocated 三段式显存检查命令	以文字条目列出常见显存修复手段

从源码结构看，Kiro 版本是该 Agent 在 .kiro/ 适配层（由 .kiro/install.sh 以非破坏性复制方式分发）中的精简镜像：工具白名单收窄为 read + shell，说明在 Kiro 环境下该 Agent 的写入能力受平台侧 Agent 配置约束；主格式则完整开放 Write/Edit 并附带 Prompt Defense Baseline（要求不泄露机密、不输出未经验证的可执行代码、把外部数据一律视为不可信等）。正文的核心方法论（诊断命令、修复工作流、模式表、停止条件）两者一致，因此本文以 Kiro 版为骨架，以主格式补齐被精简的细节。

2. 核心职责：六大故障域

文档开篇即声明该 Agent 的使命是"以最小、外科手术式的改动修复 PyTorch 运行时错误、CUDA 问题、张量形状不匹配与训练失败"。其核心职责覆盖六类故障域：

1. 诊断 PyTorch 运行时错误与 CUDA 错误
2. 修复跨模型层级的张量形状不匹配（tensor shape mismatch）
3. 解决设备放置问题（CPU/GPU 混用）
4. 调试梯度计算失败
5. 修复 DataLoader 与数据管线错误
6. 处理混合精度（AMP）问题

这一职责列表与配套 Skill skills/pytorch-patterns/SKILL.md 中列出的"Anti-Patterns to Avoid"几乎一一对应：设备硬编码（.cuda() 写死）→ 职责 3；in-place 操作破坏 autograd → 职责 4；collate_fn 缺失导致变长数据无法堆叠 → 职责 5；AMP 使用不当 → 职责 6。可以推断，ECC 的设计意图是让"模式 Skill（预防）"与"修复 Agent（治疗）"互为镜像：Skill 教 Agent 写对的代码，Resolver 在代码已经崩溃时按图索骥。

3. 诊断命令链：先固化环境事实，再碰代码

文档要求按顺序执行五条诊断命令。这套命令的设计逻辑是自底向上固化环境事实：先确认 PyTorch/CUDA 是否可用，再确认 cuDNN、依赖清单、驱动状态，最后做一次最小化的 CUDA 张量创建冒烟测试。

python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}, Device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"CPU\"}')"
python -c "import torch; print(f'cuDNN: {torch.backends.cudnn.version()}')" 2>/dev/null || echo "cuDNN not available"
pip list 2>/dev/null | grep -iE "torch|cuda|nvidia"
nvidia-smi 2>/dev/null || echo "nvidia-smi not available"
python -c "import torch; x = torch.randn(2,3).cuda(); print('CUDA tensor test: OK')" 2>&1 || echo "CUDA tensor creation failed"

逐条解读其作用与"为什么需要"：

#	命令	固化的事实	对应的典型故障
1	打印 torch.__version__ / cuda.is_available() / 设备名	PyTorch 版本、CUDA 运行时是否可用、实际 GPU 型号	装了 CPU 版 wheel 却在调用 .cuda()；版本过旧不支持新 API
2	打印 torch.backends.cudnn.version()	cuDNN 是否链接、版本多少	cuDNN error: CUDNN_STATUS_INTERNAL_ERROR 类兼容性故障
3	pip list 过滤 torch/cuda/nvidia	各 PyTorch/nvidia 组件版本是否匹配	torch 与 nvidia-* 运行时包版本错位导致的 CUDA 加载失败
4	nvidia-smi	驱动版本、GPU 显存占用、是否有其他进程占卡	显存被残留进程占满导致的 OOM
5	创建 2x3 CUDA 张量	最小化 CUDA 上下文创建冒烟测试	区分"框架/驱动坏了"与"用户代码坏了"——若此步失败，问题与环境有关而非代码

注意第 5 条用 2>&1 保留 stderr 以便看到真实错误，而前两条用 || echo 做优雅降级：在无 GPU 的 CPU 环境下命令不会中断，而是打印可读的降级信息。这是"诊断脚本必须能在无 GPU 机器上安全运行"的防御性写法，与主格式中"Device: CPU"的 fallback 分支属于同一思路。

主格式还额外提供了一段显存三段式检查命令，用于量化显存压力（当 OOM 反复出现时比单看 nvidia-smi 更精确，因为它区分"已分配"与"缓存"）：

python -c "
import torch
print(f'Allocated: {torch.cuda.memory_allocated()/1e9:.2f} GB')
print(f'Cached: {torch.cuda.memory_reserved()/1e9:.2f} GB')
print(f'Max allocated: {torch.cuda.max_memory_allocated()/1e9:.2f} GB')
"

memory_allocated 是 PyTorch 实际持有张量占用的显存，memory_reserved 含缓存分配器预留但未用的部分；两者差异过大通常指向碎片化或泄漏，与 torch.cuda.empty_cache() 的使用判断直接相关。

4. 修复工作流：六步法与"最小改动"约束

文档给出的 Resolution Workflow 是一个严格的六步流水线：

1. Read error traceback     -> Identify failing line and error type
2. Read affected file       -> Understand model/training context
3. Trace tensor shapes      -> Print shapes at key points
4. Apply minimal fix        -> Only what's needed
5. Run failing script       -> Verify fix
6. Check gradients flow     -> Ensure autograd computes expected gradients

六步中有三个值得展开的设计决策：

第 1 步优先读 traceback 而不是猜。PyTorch 错误的异常类型（RuntimeError vs ValueError vs IndexError）直接决定进入模式表的哪一行，因此第 1 步的产出是"失败行 + 错误类型"这对定位坐标。

第 3 步把"打印形状"固化为流程步骤而非可选技巧。文档随后给出具体注入方式（见第 6 节）。这一步之所以被显式列为工作流环节，是因为形状类错误（模式表第一行、第五行、第七行）的根因几乎都在失败点上游若干层，不打印就无法区分"该层参数错了"还是"输入被上游截断了"。

第 6 步要求验证梯度流而非仅验证"不再报错"。脚本能跑通只说明前向传播成立；loss.backward() 后参数 .grad 是否非空、梯度图是否完整，才是训练代码"修好了"的判据。这与主格式模式表中 element 0 of tensors does not require grad（.detach()/.item() 断图）这类错误呼应——它们的症状恰恰是"不报错但学不动"。

5. 常见错误修复模式表：十类故障的完整对照

文档的核心资产是一张十行的"错误 → 根因 → 修复"对照表，覆盖 PyTorch 训练中最高频的运行时故障。以下完整继承原文档表格，并结合 skills/pytorch-patterns/SKILL.md 的反模式清单补充源码级佐证：

错误	根因	修复
mat1 and mat2 shapes cannot be multiplied	Linear 层输入尺寸不匹配	把 in_features 改为上一层输出的维度
Expected all tensors to be on the same device	CPU/GPU 张量混用	对所有张量和模型统一 .to(device)
CUDA out of memory	batch 过大或显存泄漏	减小 batch size，加 torch.cuda.empty_cache()，使用梯度检查点
element 0 of tensors does not require grad	loss 计算中混入已 detach 的张量	在梯度计算前移除 .detach() 或 .item()
Expected input batch_size X to match target batch_size Y	batch 维度不匹配	修 DataLoader 的 collation 或模型输出的 reshape
one of the variables needed for gradient computation has been modified by an inplace operation	in-place 操作破坏 autograd	把 x += 1 换成 x = x + 1
stack expects each tensor to be equal size	DataLoader 中张量尺寸不一致	加 padding/截断，或自定义 collate_fn
cuDNN error: CUDNN_STATUS_INTERNAL_ERROR	cuDNN 不兼容	先置 torch.backends.cudnn.enabled = False 验证，再升级驱动
index out of range in self	Embedding 索引 >= num_embeddings	修正词表大小或 clamp 索引
Trying to reuse a freed autograd graph	复用了已释放的计算图	加 retain_graph=True 或重构 forward 结构

（注：.kiro 版表格的错误列为缩写形式；主格式 agents/pytorch-build-resolver.md 中同一张表带完整异常前缀 RuntimeError: / ValueError: / IndexError:，且 in-place 行额外提示"避免 in-place relu"、batch 行强调"修模型输出 reshape"。）

其中几个模式在配套 Skill 中有完整的正反例代码，值得作为修复时的参照模板：

in-place 破坏 autograd（模式表第 6 行）。skills/pytorch-patterns/SKILL.md 给出的反模式/正模式对照：

# 反模式：in-place 操作破坏梯度图
x = F.relu(x, inplace=True)  # 可能破坏梯度计算
x += residual                  # in-place 加法破坏 autograd 图

# 正模式：out-of-place
x = F.relu(x)
x = x + residual

stack expects each tensor to be equal size（第 7 行）。根因是变长序列（如 NLP 文本）在默认 collate 下无法 torch.stack。Skill 中给出了标准解法——自定义 collate_fn 做 batch 内 padding：

def collate_fn(batch: list[tuple[torch.Tensor, int]]) -> tuple[torch.Tensor, torch.Tensor]:
    sequences, labels = zip(*batch)
    # 填充到 batch 内最大长度
    padded = nn.utils.rnn.pad_sequence(sequences, batch_first=True, padding_value=0)
    return padded, torch.tensor(labels)

dataloader = DataLoader(dataset, batch_size=32, collate_fn=collate_fn)

.item() 在 backward 之前调用（第 4 行）。这是"loss 恒为 0 但 loss 值正常"这类隐蔽故障的高频来源：

# 反模式：.item() 把标量从图中剥离
loss = criterion(output, target).item()  # 与图断开！
loss.backward()  # 报错：无法穿过 .item() 反向传播

# 正模式：.item() 只在日志时用
loss = criterion(output, target)
loss.backward()
print(f"Loss: {loss.item():.4f}")

AMP 混合精度（职责 6）。模式表把 AMP 列为职责域，skills/pytorch-patterns/SKILL.md 给出了与之配套的 GradScaler 标准训练循环（scale → backward → unscale → clip → step → update）与 torch.amp.autocast("cuda") 用法，可作为修复 AMP 报错时的目标形态参照；其中 optimizer.zero_grad(set_to_none=True) 的写法也解释了为何"显存偏高"问题常常先从这里查起——set_to_none=True 用 None 替换梯度而非置零，直接节省一份梯度内存。

6. 形状调试与内存调试：两套具体手段

6.1 形状调试

Kiro 版给出的最小注入式探针：

# 加在失败行之前：
print(f"tensor.shape = {tensor.shape}, dtype = {tensor.dtype}, device = {tensor.device}")

一次性打印 shape/dtype/device 三元组是关键——因为模式表中第 2 行（设备）与第 1 行（形状）常同时发生，单看 shape 会漏掉设备维度。

主格式在此基础上的补充是全模型结构级追踪：

# 完整模型形状追踪：
from torchsummary import summary
summary(model, input_size=(C, H, W))

torchsummary 会逐层打印每个模块的输入/输出形状与参数量，适合"不知道形状在哪一层开始错"的场景；而单点 print 适合已经锁定可疑层的场景。两者构成"全局扫描 → 局部确认"的两级策略。这与 skills/pytorch-patterns/SKILL.md 中"Explicit Shape Management"原则（forward 内每步用注释标注 (batch, C, H, W) 变化）是同一思想的三个粒度：预防时写注释、出错时打日志、定位不到时上 summary。

6.2 内存调试

Kiro 版列出四条常见显存修复手段：

• 验证阶段用 with torch.no_grad(): 包裹（Skill 中进一步给出 @torch.no_grad() 装饰器写法，并强调验证时必须 model.eval()——否则 dropout 仍然生效、BatchNorm 使用 batch 统计量，这本身就是评测不准的隐患）；
• 主动释放：del tensor; torch.cuda.empty_cache()；
• 梯度检查点：model.gradient_checkpointing_enable()（Skill 中给出更通用的 torch.utils.checkpoint.checkpoint(block, x, use_reentrant=False) 逐块包裹写法，以重计算换显存）；
• 混合精度：torch.cuda.amp.autocast()（Skill 推荐当前写法 torch.amp.autocast("cuda") 并配合 GradScaler）。

7. 关键原则与停止条件：约束 Agent 的"行为合同"

文档的 Key Principles 是防止修复 Agent 过度发挥的行为合同，六条原则可以归纳为三组约束：

只修不改组

• Surgical fixes only —— 不重构，只修错误
• 绝不在错误不要求时改动模型架构
• 绝不在未获批时用 warnings.filterwarnings 压制警告

验证义务组

• 总是在修复前后核对张量形状
• 总是先用小批量（batch_size=2）验证
• 修根因，不压症状

第三条"先小批量"与模式表第 3 行（OOM → 减小 batch）形成闭环：小 batch 既能快速复现逻辑错误，又能把显存压力降到最低，使"代码错误"与"资源错误"可分离。

7.1 停止条件：什么时候必须停下来上报

Stop Conditions 定义了四条硬边界，任何一条命中，Agent 必须停止自动修复并报告：

1. 同一错误连续 3 次修复尝试后仍然存在（防止无限试错循环烧 token）；
2. 修复需要从根本上改变模型架构（超出"surgical"授权）；
3. 错误源于硬件/驱动不兼容（此时正确动作是建议升级驱动，而不是改代码）；
4. batch_size=1 时仍然 OOM（说明是模型本身太大，需要换小模型或梯度检查点等结构性手段）。

从源码结构看，这四条与 ECC 整体的循环防护设计一致——仓库对自主循环普遍设置"最大迭代 + 显式退出 + 失败上报"的护栏，build resolver 家族（cpp-build-resolver、go-build-resolver 等）共享同一行为合同。

8. 输出格式：可机读的修复报告契约

文档规定了修复完成后的输出格式，目标是让人和上层编排系统都能无歧义地解析结果：

[FIXED] train.py:42
Error: RuntimeError: mat1 and mat2 shapes cannot be multiplied (32x512 and 256x10)
Fix: Changed nn.Linear(256, 10) to nn.Linear(512, 10) to match encoder output
Remaining errors: 0

最终以一行汇总收尾：Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list

该契约的设计要点：每条修复记录包含文件:行号（train.py:42）、原始错误全文、具体改动描述、剩余错误数；汇总行用固定分隔符 | 划分三个字段，便于 CI 脚本或编排 Agent 做正则提取。示例本身也示范了正确的修复叙述方式——说明"为什么"改（to match encoder output），而不只是"改成什么"。

9. 编排集成：它如何被自动调度进 build 链路

pytorch-build-resolver 不是孤立的提示词，它被接入了 ECC 的自动编排体系，有三处可验证的集成点：

（1）Agent 注册表。AGENTS.md 的 Available Agents 表将其登记为"PyTorch runtime/CUDA/training errors"的触发对象，使用场景为"PyTorch build/training failures"，与 Agent-First 原则（"Delegate to specialized agents for domain tasks"）配套。

（2）plan-orchestrate 的 build 链特殊规则。skills/plan-orchestrate/SKILL.md 定义了把计划文档分解为 Agent 链的编排协议，其中与 PyTorch 相关的规则有两条，是理解该 Agent 调度条件的关键事实：

• Phase 0 的 PyTorch 子档案检测：当 lang=python 且 pyproject.toml / requirements.txt / uv.lock 中声明了对 torch 的依赖时，置 pytorch=true。该标志只影响 build 链的选择，reviewer 仍是 python-reviewer；
• Phase 2 链组成规则第 6 条：<lang>-build-resolver 在 lang=unknown 时回退为通用 build-error-resolver；特殊情况：若 Phase 0 置了 pytorch=true，则 build 链一律使用 pytorch-build-resolver，与 <lang> 无关。该 Skill 还特别指出不存在 python-build-resolver——--lang=python 且 pytorch=false 时回退到 build-error-resolver。

换言之，只要编排器检测到项目依赖里声明了 torch，所有被打上 build 标签（触发词：build、compile、lint failure、CI）的步骤都会自动路由到这个 Agent，无需人工指派。

（3）审查 Agent 的移交边界。如第 1 节所述，agents/mle-reviewer.md 明确把"形状/设备/梯度/CUDA/DataLoader/AMP 阻塞"这一故障面划给 pytorch-build-resolver，把"CI、依赖、原生扩展、CUDA 环境"等非 PyTorch 内失败划给 build-error-resolver，形成"审查发现 → 专项修复 → 再验证"的多 Agent 流水线。

10. 安装与使用方式

该 Agent 随 ECC 仓库的 Kiro 适配层分发，安装方式见 .kiro/README.md 与 .kiro/install.sh：

# 进入 .kiro 目录
cd .kiro

# 安装到指定项目
./install.sh /path/to/your/project

# 安装到当前目录
./install.sh

# 全局安装（对所有 Kiro 项目生效）
./install.sh ~

安装器采用非破坏性复制（.kiro/install.sh 中对已存在的目标文件跳过覆盖，if [ ! -f "$TARGET/.kiro/agents/$local_name" ] 判断后复制），因此自定义过的 Agent 文件在重复安装时不会被覆盖。安装后：

• Kiro IDE：在会话中通过 / 菜单显式调用（如 /pytorch-build-resolver），或由平台自动选择；
• Kiro CLI：kiro-cli --agent pytorch-build-resolver 直接以该 Agent 启动会话，或 /agent swap 中途切换。

使用建议遵循文档自身的触发语义——"Use when PyTorch training or inference crashes"：把报错的 traceback 贴给 Agent，它会自行按第 3 节的诊断命令链固化环境事实、按第 4 节六步工作流推进，并按第 8 节契约输出修复报告。若同时希望预防同类问题，应让 pytorch-patterns Skill 参与编写/审查环节，形成"写码时用模式约束、崩了时由 resolver 按图修复"的闭环。

11. 小结

.kiro/agents/pytorch-build-resolver.md 定义的不是一个泛泛的"AI 修 bug"角色，而是一套可审计的 PyTorch 故障处置协议：五条诊断命令固化环境事实，六步工作流强制"定位 → 最小改动 → 复验 → 验梯度"的闭环，十行模式表把高频运行时错误映射到确定性修复动作，停止条件与输出契约则约束了自主 Agent 的授权边界与可解析性。它在 ECC 体系中由 plan-orchestrate 依 pytorch=true 标志自动路由、由 mle-reviewer 划定移交边界，配套 pytorch-patterns Skill 完成预防侧能力——这套"预防模式 + 修复 Agent + 编排路由"的三层结构，正是 ECC 将 PyTorch 工程能力产品化的核心方式。