nbQA 笔记本代码质量工具链

为什么需要它

在 Jupyter 笔记本驱动的项目里，代码散落在 .ipynb 的单元格中，而主流 Python 质量工具——Ruff、Mypy、Black、Flake8 等——默认只认 .py 文件。如果坚持使用这些工具，就得先把笔记本导出成脚本，跑完检查再手动合并回去，既容易出错又打断探索流程。这个技能要解决的正是：让 notebook 仓库也能获得与普通 Python 项目同等的静态检查、格式化和类型标注保障。

核心能力与工作流程

nbQA 充当了 notebook 与底层 QA 工具之间的转换层。它解析 .ipynb，把代码单元格提取成可分析的文本，交给对应的工具运行，再把结果映射回原始笔记本。这样一来，你可以直接在 notebook 上执行 ruff check、mypy 之类的操作，而不用先把笔记本拆成脚本。技能的核心步骤包括：确认环境里已装好 Python 3、Jupyter 和底层工具；用 nbQA 统一调用接口；针对 notebook 执行 format、lint 或 type check；若笔记本以 Jupytext 的 .md 形式保存，还需安装 jupytext 才能让格式化流程覆盖 .md 文件。

适用边界与注意点

并非所有工具都能完美处理 notebook 中的魔法命令和单元格级作用域，部分规则在单元测试或输出保留上可能表现不同。Jupytext 路径需要额外依赖；工具的具体行为仍以底层 QA 工具自身为准。建议在合并前先在分支上运行，并对照上游文档验证命令与参数。