深度学习代码调试与修复助手 · 静态规则 + 动态沙箱

这个项目解决什么问题

深度学习代码的报错有强烈的"套路感"：90% 的失败逃不出七八种模式。但初学者往往要对着报错信息逐条搜索半小时。本项目把这套"看一眼报错就知道原因"的经验固化为规则引擎，输入代码，输出为什么错、怎么改的诊断报告——相当于一个不收费、不嫌烦的调试搭档。

核心亮点

• 静态规则引擎（R1~R7）：设备不一致、缺少 zero_grad()、缺少 backward()、缺 model.eval()、推理未关梯度、nn.Linear 维度不衔接、跨版本 API（Variable/tf.Session）——每条规则都能在报错之前就抓住隐患。
• 动态沙箱执行：隔离子进程（强制 CPU、30 秒限时）真实运行代码，捕获 traceback 后按内置知识库自动归因，"Expected all tensors..."这类报错直接翻译成人话。
• 双形态交付：终端秒出结论摘要，Markdown 完整报告落盘 outputs/（含规则清单），可以直接当实验报告附件。
• 零依赖可用：不安装 PyTorch 也完成全部静态诊断，框架装好后动态沙箱自动启用——环境自适应，任何机器都能演示。
• 内置"埋雷"示例：buggy_examples/ 里两个故意写错的文件覆盖 5 种错误，克隆即可复现完整诊断流程。
• 教学友好：每条结论都是"为什么错 + 怎么改"的教科书式结构，可直接用作深度学习实验课的调试教案。

效果预览

对内置错误示例的诊断输出——三个高危问题全部命中：

双引擎工作流：静态抓写法隐患，动态抓运行时爆炸：

预览图为演示数据下的实际输出；规则命中情况随你的代码而定。

你将学到

• ast 静态分析的实战套路：模式匹配、维度推导、父节点遍历
• 深度学习高频报错的根因分类法（8 类 traceback 知识库）
• 子进程沙箱的安全设计：超时、环境隔离、GPU 屏蔽
• "诊断结论 → 可执行修复"的报告工程化写法

适合谁

被 PyTorch 报错反复折磨的深度学习初学者、需要"AI + 代码质量"方向的毕设学生、以及想给自己的实验课配调试助教的老师。难度 ★★★☆，规则引擎部分每条都有注释，可自行扩充新规则。

traceback 归因的 8 条正则怎么写的、维度推导的边界在哪——源码注释里都有，这里刻意没有展开，留给你自己探索。

交付内容：完整可运行源码、README.md（逐步运行方法与实现说明）、requirements.txt。

许可：个人使用，可用于自己的学习、课程实验与研究报告，请勿转售或公开传播。

环境与步骤

pip install -r requirements.txt

pip install -r requirements.txt

python main.py buggy_examples        # 内置错误示例，开箱即用
python main.py your_model.py         # 诊断你的代码
python main.py your_project --no-dynamic   # 纯静态模式

注意事项

• 不装 PyTorch/TensorFlow 也能完成全部静态诊断；框架就位后沙箱自动启用。

Q：不装 PyTorch / TensorFlow 有用吗？

A：有。静态规则引擎 R1~R7 只读源码文本，零框架依赖就能抓出设备不一致、缺 zero_grad()、缺 backward()、缺 model.eval()、推理未关梯度、nn.Linear 维度不衔接、跨版本 API（Variable / tf.Session）这些隐患。

Q：动态沙箱会不会把机器卡住？

A：沙箱是隔离子进程、强制使用 CPU、30 秒限时，超时与异常都会被捕获成结构化归因结果，不会拖垮主程序。

Q：有现成的错例可以试吗？

A：有。buggy_examples/ 里两个故意写错的文件覆盖 5 种常见错误，拿到就能复现完整诊断流程，报告落盘 outputs/（含规则清单），可以直接当实验报告附件。

Q：报错信息能讲明白吗？

A：内置知识库把常见 traceback 翻译成人话，例如 “Expected all tensors to be on the same device” 会直接给出是模型还是输入没挪到同一设备、以及可复制的修复代码。