基于 devcontainer 的 MindStudio 统一开发环境方案

💻 需求背景

MindStudio 工具链覆盖算子和训推两大场景共 20+ 工具（C++/Python/混合），目前缺少统一的开发环境基础设施。开发者 clone 代码后需要手工搭建编译工具链、Python 版本、C++ 调试环境、IDE 插件和 pre-commit 检查，新人环境配置耗时 2-4 小时。环境不一致导致"在我机器上能编"类问题频繁出现。

参考连接：

Development Containers Specification — devcontainer 开放标准
设计文档：基于devcontainer的高效开发环境方案.md

当前现状

问题	具体表现
环境搭建复杂	构建工具链、Python、C++、npm、IDE 插件均需手工准备，无自动化
入口分散	Release/Debug 构建、UT 测试、静态检查、调试各有不同命令，无统一 IDE Task
C++ 代码跳转不可用	`compile_commands.json` 生成路径不一致，clangd 无法稳定读取
调试模板缺失	C++ GDB 和 Python debugpy 缺少标准 VS Code 配置
pre-commit 漏装	提交前检查依赖开发者自觉安装，漏装率高
工作区污染	构建产物、Python 缓存、IDE 配置常出现在 `git status` 中

期望实现的功能

开发者在 VS Code 中打开仓库后，可一键进入容器、一键编译、一键调试、代码跳转开箱即用；git commit 自动触发 pre-commit 检查；构建/测试后 git status 保持清洁。

具体目标：

功能	说明
容器固化	`devcontainer.json` 声明镜像、挂载、用户、环境变量、推荐扩展
自动初始化	`post-create.sh` 幂等准备 Python、系统依赖、pre-commit、clangd、Git 身份
一键构建/测试	4 个 VS Code Task：Release 构建 / Debug 构建 / UT 测试 / 清理
一键调试	Python debugpy + C++ GDB 调试模板
代码跳转	C++ clangd + Python Pylance
自动检查	`git commit` 自动触发 pre-commit
工作区洁净	`.gitignore` + `.gitmodules ignore=all` + `skip-worktree` 三层治理

具体的设计方案

目录结构

工具仓库根目录/
├── .devcontainer/
│   ├── devcontainer.json        # 容器定义
│   └── post-create.sh           # 幂等初始化脚本
├── .vscode/
│   ├── tasks.json               # Build/Debug/Test/Clean
│   ├── launch.json              # 调试配置
│   └── settings.json            # watcher/search 排除 + clangd
├── .clangd                      # CompilationDatabase: build/
├── .gitignore                   # 构建产物/缓存忽略
└── .gitmodules                  # submodule ignore = all

核心组件

1. devcontainer.json — 使用 MindStudio 标准构建镜像，remoteUser: mindstudio，postCreateCommand: bash /workspace/.devcontainer/post-create.sh

2. post-create.sh — 9 个幂等函数：用户 bin 目录 → Python 3.11（含多 Python 共存处理）→ 系统/pip 依赖安装 → Git 身份同步 → pre-commit 安装 → clangd → skip-worktree → compile_commands 检查

3. 构建任务 — Debug 构建分两步：build.py -e only_down_deps=true 只下载依赖，然后 CMake 接管 Debug 编译

4. Git 洁净三层治理：

.gitignore 覆盖 build/、output/、artifacts/、pycache/、.cache/、.pytest_cache/ 等
.gitmodules 对第三方 submodule 加 ignore = all
skip-worktree .vscode/settings.json 隔离个人偏好

5. CMake 适配 — CMAKE_EXPORT_COMPILE_COMMANDS ON + 默认 CMAKE_BUILD_TYPE=Release

6. 多 Python 共存 — 容器内 pyenv python3.11 和系统 python3 共存时，两套都装 pip 依赖；pyenv Python PATH 优先

纯 Python 工具裁剪

不创建 .clangd，裁剪 C++ 构建/调试任务，.gitignore 重点补充 .venv/、dist/、*.egg-info/

测试方案

环境就绪性

验证项	操作	预期
post-create 零阻塞	Rebuild Container Without Cache	容器正常创建，所有函数无报错
pre-commit 自动安装	`git commit`	Hook 自动触发
Git 状态洁净	构建+UT 后 `git status --short`	无产物/缓存污染

构建验证

验证项	操作	预期
Release 构建	`Build: Release Mode` Task	产物与命令行构建一致
Debug 构建	`Build: Debug Mode` Task	带 `-g -O0` 的 Debug 二进制
UT 测试	`Test: Run Unit Tests` Task	全量通过

调试与跳转验证

验证项	操作	预期
断点调试	F5 → debugpy / GDB	断点命中，变量查看正常
C++ F12 跳转	对函数按 F12	clangd 跳转到定义
Python F12 跳转	对函数/类按 F12	Pylance 语义跳转