想给 audio-separation-nodes-comfyui 贡献代码？这是一份面向新手的完整开发者指南：从搭建本地测试环境、正确运行 pytest 测试套件，到理解 CI 的 Linux + Windows 双平台检查矩阵和 Ruff 代码规范，带你一步步掌握这个 ComfyUI 音轨分离节点项目（将音频拆分为 vocals、bass、drums、other 四个 stem，并提供混音、变速、裁剪等工具）的提交规范，让你的 PR 一次通过 CI。

ComfyUI 音频分离节点工作流截图：从 LoadAudio 到 AudioSeparation 再到 PreviewAudio

快速了解项目结构

贡献代码前，先花一分钟认识这个仓库的核心文件：

所有测试与源码一一对应：例如test_separation.py覆盖 src/separation.py，test_tempo_match.py覆盖 src/tempo_match.py。给哪个模块贡献代码，就优先读它的测试文件——这是理解"项目期望的行为"最快的方式。

一键安装：本地开发环境三步搭建

按照 CONTRIBUTING.md 的官方流程，只需三步：

git clone https://gitcode.com/gh_mirrors/au/audio-separation-nodes-comfyui cd audio-separation-nodes-comfyui pip install -e '.[test,dev]' pre-commit install

• pip install -e '.[test,dev]'：可编辑安装会同时拉入pytest、pytest-cov（测试组）和ruff（开发组），见 pyproject.toml。
• pre-commit install：让每次git commit自动执行 Ruff 修复 + 格式化，与 CI 检查保持一致，避免"本地通过、CI 打回"的尴尬。

ComfyUI 提取伴奏工作流：音轨分离后用 AudioCombine 节点合并 stem 并保存

💡 运行时依赖为librosa、numpy、torchaudio、moviepy（见 requirements.txt），版本要求锁定在 Python 3.9 ~ 3.11。

最快运行测试的方法：pytest 与 90% 覆盖率门槛

项目运行测试的标准命令是：

PYTHONPATH=src pytest tests

几个关键点值得注意：

1. 必须带PYTHONPATH=src——这模拟了 CI 环境的导入方式（CONTRIBUTING.md 明确指出该命令与 CI 环境一致）。
2. 覆盖率有硬性门槛：pyproject.toml 中配置了--cov=src --cov-report=term-missing --cov-fail-under=90。新增功能如果没写测试导致覆盖率跌破 90%，pytest 会直接失败——所以"加功能不写测试"在这个仓库走不通。
3. 无需 GPU 也能跑：tests/conftest.py 提供了轻量的MockTensor替代torch.Tensor，大部分单元测试可在 CPU 环境快速完成，方便你频繁提交、频繁验证。

ComfyUI 视频人声分离工作流：AudioCrop 裁剪后送入 AudioSeparation 节点分离 stem

写测试时的惯例（参考 tests/test_separation.py）：

• 每个src/模块对应一个tests/test_<模块名>.py；
• 需要 torch 的场景用unittest.mock的MagicMock/patch打桩，而不是依赖真实模型权重；
• 测试音频数据用 numpy 直接生成（如np.zeros波形），不依赖外部大文件。

读懂 CI：Linux + Windows 双平台检查矩阵

打开 .github/workflows/tests.yml，CI 由两个 job 组成：

触发条件是 push 到master或任何 pull_request（tests.yml），并配置了并发取消旧任务，节省资源。

每个 job 的执行步骤完全一致（tests.yml），这就是你本地提交前应全部通过的"验收清单"：

ComfyUI 替换背景音乐工作流：用 AI 生成的 BGM 替换原视频音轨

⚠️新手最常见的 CI 失败原因：ruff format --check格式不通过。只要装了 pre-commit，提交时会自动格式化，基本不会踩坑。

代码规范：Ruff 规则组与 mypy 配置

所有规范都集中在 pyproject.toml 中，提交前了解一遍可以少走弯路：

• 目标版本：Python 3.9（target-version = "py39"），请避免使用过新的语法特性。
• 行宽：120 字符（line-length = 120），略宽于 PEP8 的 88。
• 启用的 Ruff 规则组（pyproject.toml）：

• import 排序：torch、librosa、numpy、moviepy、comfy等被声明为第三方库（pyproject.toml），导入顺序会据此分组。
• 类型检查：项目还配置了 mypy（pyproject.toml），开启warn_return_any，建议关键函数保持类型注解完整——src/下的代码普遍使用from __future__ import annotations，新代码请沿用这一惯例。
• 提交钩子：.pre-commit-config.yaml 注册了ruff --fix和ruff-format两个钩子，提交时自动修复，与 CI 检查一一对应。

提交 PR 前检查清单 📋

最后，对照下面这份清单再提交，可大幅提高合并效率：

1. ☑️ 本地跑通PYTHONPATH=src pytest tests，覆盖率不低于 90%；
2. ☑️ 新增/修改的src/模块在tests/中有对应测试覆盖；
3. ☑️ruff check与ruff format --check均为零告警（pre-commit 自动处理）；
4. ☑️ 兼容 Python 3.9+，且注意 Windows 平台行为（CI 有 Windows job）；
5. ☑️ 变更符合 CHANGELOG.md 的 Keep a Changelog 格式与语义化版本（SemVer）习惯，可在 PR 描述中说明变更类型（Added / Fixed / Changed）；
6. ☑️ 发现安全漏洞？不要公开提 issue，按 SECURITY.md 通过邮件私下报告；
7. ☑️ 提交 bug 或功能请求时，使用仓库内置的模板（.github/ISSUE_TEMPLATE/bug_report.yml），补充复现步骤和系统环境。

ComfyUI 歌曲 Remix 工作流：多节点串联实现人声、鼓点、贝斯的重组混音

掌握以上流程——测试环境一键安装、pytest 90% 覆盖率门槛、双平台 CI 矩阵、Ruff 规范——你就具备了向 audio-separation-nodes-comfyui 提交高质量 PR 的全部知识。祝你的第一个贡献顺利合入！🚀