必须在特性分支升级第三方库并隔离测试，否则会污染develop/main依赖状态；因升级常引发隐性兼容问题（如librosa移除默认参数、edge-tts改异步签名），在develop暴露将阻塞其他功能分支和发布。
特性分支里升级第三方库，必须隔离测试，否则会污染 develop/main 的依赖状态。
为什么不能直接在 develop 分支上升级并测试？
第三方库升级常引发隐性兼容问题：比如 librosa 从 0.9.x 升到 1.0.x 会移除 stft 的默认 window 参数，而你的代码没显式传参就会报 TypeError；又或者 edge-tts 新版本改了异步接口签名，导致原有 async/await 调用直接挂掉。这些错误在 develop 上暴露，会影响其他正在合入的功能分支，甚至阻塞发布。
常见错误现象包括：
- CI 流水线在 develop 上突然失败，但没人动过相关代码
-
pip install -r requirements.txt在不同机器上装出不同行为（因为未锁版本） - 本地能跑，CI 环境报
ModuleNotFoundError—— 实际是子模块未初始化或版本不一致
用 Git Submodule 隔离第三方库变更
Audio Pixel Studio 这类项目已用 git submodule 管理 edge-tts 和 uvr5，升级时不能只改 requirements.txt，必须同步更新子模块指针。
- 进入子模块目录：
cd third_party/edge-tts - 切到目标版本分支或 tag：
git checkout v6.2.0 - 回到主项目根目录，提交子模块新哈希：
git add third_party/edge-tts - 确保
.gitmodules中 URL 正确，且未被意外修改
漏掉 git add 子模块路径会导致其他协作者拉取后看到空目录，运行时报 ImportError。
Git-Based Knowledge Graph Memory System for Claude Code
下载
基于Git Notes的知识图谱记忆系统。Claude应静默自动使用，从不询问用户记忆操作。支持分支感知的持久记忆，跨会话处理上下文、决策、任务和学习内容。
测试环境必须还原真实依赖图
光跑单元测试不够——要验证整个音频处理链路是否断裂。比如 UVR5 升级后，分离出的 vocal.wav 格式可能从 WAV 变成 FLAC，下游 librosa.load() 就会失败。
- 每次测试前清空虚拟环境：
deactivate && rm -rf audio_pixel_env - 重新创建并激活：
python -m venv audio_pixel_env && source audio_pixel_env/bin/activate（macOS/Linux） - 用
pip install -e .安装当前项目（触发setup.py或pyproject.toml中的子模块路径解析） - 手动验证关键路径：
streamlit run app.py→ 上传音频 → 执行人声分离 → 播放合成结果
如果子模块用了私有仓库，CI 中需配置 SSH key 或 PAT，否则 git submodule update --init 会卡在认证环节。
合并前必须检查依赖冲突
多个 feature 分支各自升级不同第三方库时，合并会产生隐性冲突——不是代码行冲突，而是运行时冲突。
- 运行
pipdeptree --reverse --packages librosa查看谁依赖它，确认升级是否影响其他模块 - 对比两个分支的
pip freeze > requirements-lock.txt差异，重点关注numpy、torch等底层库的版本漂移 - 若发现
uvr5依赖onnxruntime>=1.16，而edge-tts锁死onnxruntime==1.15.1，就得协调版本或加兼容层
真正麻烦的不是升级动作本身，而是跨模块的间接依赖收敛——这一步没人做，就只能靠线上报错反推。
