| name | github-setup-zh |
| description | 配置任意开源 GitHub 研究仓库（任何领域）时使用——clone、配 conda env、装依赖、下权重、跑 demo。触发信号：README 给了 `quick_install.sh` / `requirements.txt` 你正要照着跑；pip install 卡住/失败/意外把 numpy 拉到不同版本；`import X` 能跑但 demo 崩；demo "应该 30 秒"却跑了几小时。 |
GitHub 仓库配置 — 通用流程
概述
开源研究仓库的安装脚本几乎都很脆弱：作者机器上当时跑通的 pip pin，merge 之后就开始漂。照 README 字面跑通常会失败。这个 skill 抓住通用流程 —— 不管哪个仓库，做什么、按什么顺序，都是相同的；最后给一份 pixel3dmm + SMIRK 的实战案例，把每条通用原则映射到具体的坑。
核心原则：最小安装 → 验证 import → 在小样例上 smoke test → 再扩。不要无脑信 pip pin 组合，numpy / cv2 / cuda 传染性依赖会在你脚下挪动。
何时使用
- clone 任意 GitHub 研究仓库并按其 install 步骤配置
- 在已有 conda env 上加一个姊妹项目（只装差异化包）
- 跑需要 FLAME / SMPL-X / mediapipe / gdown 重权重的 demo
- pip install 卡 / 失败 / 拉到意外版本
import X 能跑但 X.load(ckpt) 报模糊错误- demo "应该 30 秒"实际跑几小时 — 多半是 env 或资源问题
不适用：生产部署（用容器）、纯 CPU 工具库。
通用流程
digraph workflow_zh {
"已有可用姊妹 env？" [shape=diamond];
"复用 + 装差异包" [shape=box];
"新建 conda env" [shape=box];
"完整读 README" [shape=box];
"8 阶段安装" [shape=box];
"小样例 smoke 测试" [shape=doublecircle];
"失败？" [shape=diamond];
"按类型诊断" [shape=box];
"已有可用姊妹 env？" -> "复用 + 装差异包" [label="是"];
"已有可用姊妹 env？" -> "新建 conda env" [label="否"];
"复用 + 装差异包" -> "小样例 smoke 测试";
"新建 conda env" -> "完整读 README";
"完整读 README" -> "8 阶段安装";
"8 阶段安装" -> "小样例 smoke 测试";
"小样例 smoke 测试" -> "失败？";
"失败？" -> "按类型诊断" [label="是"];
"按类型诊断" -> "8 阶段安装";
"失败？" -> "固化为 install_env.sh" [label="否"];
}
8 阶段
- 决策：复用姊妹 env vs 新建
- 完整读 README：跑任何命令前，先把所有权重 / 子仓库 / 版本 pin / 外部服务（FLAME 官网账号、gdown ID 等）列出来
- 加固 env：PATH 顺序、pip index、build-isolation 默认值
- 装 torch + CUDA toolkit + 编译工具：在做其他事之前先验证
torch.cuda.is_available()
- 装 requirements.txt：先 pin
numpy + setuptools，再用 --no-build-isolation 装老旧 / 源码编译类包
- 源码编译附加包（pytorch3d / nvdiffrast / 自定义 CUDA kernel）：永远
--no-build-isolation
- 子仓库 + 重权重：gdown / wget；下载后立即检查文件大小；放到期望的路径
- 重 pin 容易被传染性依赖拉走的包（numpy、opencv），需要时加 monkey-patch（torch.load weights_only）
然后：在小样例上 smoke test。通过则把工作命令固化成一份幂等的 install_env.sh。
失败类型（按症状诊断，不按仓库）
出错时，先识别是哪个类型。每个类型都有固定的修法。
| 类型 | 症状 | 修法 |
|---|
| A. Env 隔离 | conda activate ENV 后 which python 还是 base | 手动追加 $ENV/bin:$PATH |
| B. 构建依赖 | pip 编译时 ModuleNotFoundError | --no-build-isolation + 确保依赖已预装 |
| C. 版本兼容矩阵 | 运行时 numpy / cv2 / torch 报 AttributeError | 找到冲突对，pin 较低那个，重装 |
| D. 网络 / 镜像 | pip / wget 超时、gdown 403、conda 校验和错配 | 切 index、重试、用镜像、清缓存 |
| E. 资源放置 | FLAME / 预训练 ckpt FileNotFoundError | 检查目录是否是占位结构；cp 不要 ln -sfn |
| F. 系统层兼容 | libx264 not found、EGL 初始化失败 | 用 conda-forge 替代、接受 CPU 后退、换库 |
| G. API 破坏性变更 | ckpt 加载报模糊错、签名不匹配 | 在脚本入口处 monkey-patch 默认值 |
| H. 资源争用 | demo 比 README 慢 100 倍 | 怪 env 之前先 nvidia-smi / ps aux --sort=-%cpu |
每个具体问题都映射到某个类型；识别出类型后，修法就短。
复用模式（姊妹 env）
大多数项目都跑在已有的 torch-cuda-python 栈之上。只装差异比新装风险更低、更快。
source ~/miniconda3/etc/profile.d/conda.sh
conda activate sister_env
export PATH="$CONDA_PREFIX/bin:$PATH"
export PIP_INDEX_URL="https://pypi.org/simple"
pip list | grep -iE "torch|numpy|opencv|cuda|matplotlib"
pip install --no-build-isolation --no-cache-dir <only_diff_packages>
pip install --no-build-isolation --no-cache-dir "numpy==<known_good>" "opencv-python<<known_good>"
Smoke 测试模式
任何 install 完成后、做任何其他事之前：
time python demo.py --input samples/short_clip.mp4 --out /tmp/test.npz
失败：停下来，按类型诊断。8 个类型基本覆盖你会遇到的情况。
通过但比 README 慢 100 倍：先排资源争用（nvidia-smi、ps aux）再怪 env。后台训练 / 推理任务会无声拖累你的 demo。
常见误区
信任 README pin 组合：numpy==1.22.4 + opencv==4.9 + mediapipe==0.10.10 一起装会传染性把 numpy 拉到 2.0。每次完整 install 后都要重 pin numpy（类型 C）。
跳过 smoke 测试："直接跑全数据集" → 6 小时后发现第 1 步配错了。
信任部分 git clone 状态：上次失败留下半个 checkout。新 install 看到目录存在就跳过 clone，但配置文件缺失。永远 ls subrepo/，不是只 [ -d subrepo ]。
5 个 retry 脚本而不是修原脚本：每次 retry 都应该 patch 原脚本（加幂等 guard），而不是建 install_v2.sh / install_v3.sh / ...。
没排查 GPU 占用：慢 100 倍时，怪 env 之前先 nvidia-smi。后台训练任务是无声小偷。
警示信号 — 立刻停下排查
- pip 输出
Successfully installed numpy-2.0.x 且你已经 pin 过 1.23.x → 立刻重 pin（类型 C）
mediapipe 第一帧调用 > 5s → 已退到 CPU（类型 F）- Demo "完成" 但输出文件空 / 形状不对 → smoke test 抓到逻辑 bug 而不是 env 问题
- README 说 "30 秒 / 卡" 你看到 30 分钟 → 类型 H（资源）或 F（CPU 后退）
conda activate X 后 which python 是 base 路径 → 类型 A- 项目里出现 3 个
install_*_resume.sh → 你的脚本不幂等，要合并
固化
Smoke 通过后，把工作命令落成一份：
install_env.sh
要求：
set -euxo pipefail，失败时大声停下[ -d X ] || git clone ... guard，重跑安全- 8 阶段全部内联，每步注释属于哪个类型
- 把所有
_v2.sh / _resume.sh 这类 retry 残骸丢到 legacy/
案例：Pixel3DMM + SMIRK（本项目踩过的具体坑）
这是一个仓库的具体实例，对应到上面的类型。供参考"这些类型实际长什么样"。
| # | 实际现象 | 类型 | 修法 |
|---|
| 1 | conda activate p3dmm 后 which python 还是 base 3.13，不是 env 的 3.9 | A | activate 后 export PATH="$CONDA_PREFIX/bin:$PATH" |
| 2 | pip 卡在清华镜像 read timed out | D | export PIP_INDEX_URL="https://pypi.org/simple" |
| 3 | chumpy 的 setup.py 直接 import pip（旧式代码）→ build env 里 ModuleNotFoundError | B | pip install --no-build-isolation chumpy |
| 4 | pytorch3d 源码编译找不到 torch（build isolation 隔离了 env） | B | pip install --no-build-isolation git+... |
| 5 | conda CUDA tarball ChecksumMismatchError (libcusolver) | D | mv $CONDA_PKGS/*.tar.bz2 /tmp/ 后重试 |
| 6 | ln -sfn /path/FLAME2020 ./MICA/data/FLAME2020 嵌套了内层链接（占位目录已存在） | E | cp /path/FLAME2020/*.pkl ./MICA/data/FLAME2020/ |
| 7 | PIPNet 的 .pyx 用 np.int_t（numpy ≥1.20 已删），Cython 3 编译失败 | C | sed -i 's/np\.int_t/np.intp_t/g' *.pyx; pip install "Cython<3" |
| 8 | 运行时 AttributeError: module 'numpy' has no attribute 'int'（mediapipe / opencv 4.13 把 numpy 拉到 2.0） | C | 每次可能拉 numpy 2 的 install 后都 pip install "numpy==1.23.5" "opencv-python<4.10" |
| 9 | torch.load(ckpt) 报 UnpicklingError ... Unsupported global: omegaconf.dictconfig.DictConfig（PyTorch 2.6+ 默认 weights_only=True） | G | 脚本顶部 monkey-patch：torch.load = lambda *a, **kw: _orig(*a, **{**kw, "weights_only": False}) |
| 10 | 系统 ffmpeg 不识别 -crf / 没有 libx264（RHEL 8 ffmpeg 3.1） | F | mpeg4 -q:v 1 高质量编码或装 conda-forge ffmpeg |
| 11 | mediapipe Linux GPU 初始化失败：EGL not initialized | F | 接受 CPU 后退（~50-200 ms/帧）或换 face_alignment torch GPU（~63 ms/帧） |
| 12 | gdown 大文件 403 | D | gdown <ID> --fuzzy 或换 HuggingFace 镜像 |
| 13 | SMIRK demo 跑 150 帧用了 53 分钟 | H | 后台训练把 GPU 占满 100%，等空闲或换卡 |
实测收益
Pixel3DMM 完整安装：本来要 4+ 小时调试 → 用此 skill 30 分钟搞定。
SMIRK 复用 pixel3dmm env：2 个差异包，5 分钟全部装完。
5s smoke 测试在处理 89 段数据集前抓到 9/13 个坑。
最终 SMIRK 推理：2.6 秒 / 150 帧（vs README 的 mediapipe 路径会跑 30+ 秒）。
参见 pixel3dmm_test/shell/install_env.sh — 把 5 个 retry 脚本（在 legacy/）整合成的单一可复现脚本。
