DynamisLab/docs/QUICK_REFERENCE.md

项目结构优化与 Submodule 工作流总结

📁 优化后的目录结构

✅ 简化前（有冗余）

DynamisLab/
└── src/
    └── dynamis/          # 不必要的嵌套
        ├── config.py
        └── environments/

✅ 简化后（推荐）

DynamisLab/
└── src/                  # 直接是包的根
    ├── __init__.py
    ├── config.py
    └── environments/

优势：

• 更简洁的导入路径
• 符合Python src layout最佳实践
• 包名就是项目名（DynamisLab）

🔧 导入方式变化

在开发时（src在PYTHONPATH中）

# 简化前
from dynamis.config import load_celeris_configs
from dynamis.environments import CFDFlowControlEnv

# 简化后  
from config import load_celeris_configs
from environments import CFDFlowControlEnv

安装后（pip install -e .）

# 两种方式都可以，但推荐第二种
import dynamis
from dynamis import config, environments

# 或更直接
from config import load_celeris_configs
from environments import CFDFlowControlEnv

🔄 Submodule 开发工作流（你的核心问题）

推荐方式：独立开发 + Submodule 同步

你的开发环境：
/home/frank14f/
├── CelerisLab/          # 独立仓库，在这里开发CFD
└── DynamisLab/          # 独立仓库，在这里开发ML
    └── CelerisLab/      # submodule，指向上面的仓库

典型工作流

场景1：只改 CelerisLab

# 1. 在独立的CelerisLab目录开发
cd ~/CelerisLab
vim src/CelerisLab/utils.py
git commit -am "feat: improve config"
git push  # 推送到GitHub+Gitea

# 2. 在DynamisLab中更新submodule
cd ~/DynamisLab
git submodule update --remote CelerisLab
git add CelerisLab
git commit -m "chore: update CelerisLab"
git push

场景2：只改 DynamisLab

cd ~/DynamisLab
vim src/environments/cfd_env.py
git commit -am "feat: new environment"
git push
# submodule不需要更新

场景3：同时开发两者

# Terminal 1: CFD开发
cd ~/CelerisLab
# 改代码 → commit → push

# Terminal 2: ML开发  
cd ~/DynamisLab
git submodule update --remote  # 获取最新CelerisLab
# 改代码，使用新的CelerisLab功能
git add CelerisLab src/
git commit -m "feat: use new CelerisLab + update env"
git push

关键命令

# 更新submodule到最新
cd ~/DynamisLab
git submodule update --remote

# 查看submodule状态
git submodule status

# 固定到特定版本
cd CelerisLab
git checkout v0.2.0
cd ..
git add CelerisLab
git commit -m "pin to v0.2.0"

📝 快速参考

CelerisLab 开发（CFD功能）

cd ~/CelerisLab
# 修改 → 测试 → commit → push
git commit -am "feat: xxx"
git push

DynamisLab 同步 CelerisLab

cd ~/DynamisLab
git submodule update --remote
git add CelerisLab && git commit -m "update CelerisLab" && git push

DynamisLab 开发（ML功能）

cd ~/DynamisLab  
# 修改 → 测试 → commit → push
git commit -am "feat: xxx"
git push

🎯 最佳实践

✅ DO（推荐）

1. 在 ~/CelerisLab 开发所有CFD功能

   • 独立测试
   • 完成后推送

2. 用 submodule 保持同步

   • DynamisLab定期 git submodule update --remote
   • 提交submodule引用的更新

3. 使用开发模式安装

   pip install -e ~/CelerisLab
   pip install -e ~/DynamisLab
   

4. VSCode Workspace 管理

   • 创建 workspace 文件同时打开两个项目
   • Git视图可以分别管理

❌ DON'T（避免）

1. ❌ 不要在 ~/DynamisLab/CelerisLab submodule 内直接开发

   • 容易忘记推送
   • 路径混乱

2. ❌ 不要忘记提交 submodule 引用更新

   • 改了 CelerisLab 但 DynamisLab 没更新引用
   • 别人克隆会得到旧版本

3. ❌ 不要直接复制代码

   • 用 Git submodule 管理依赖
   • 保持单一数据源

📚 详细文档

• Submodule工作流详解: docs/SUBMODULE_WORKFLOW.md
• 项目重构总结: docs/REFACTORING_SUMMARY.md
• VSCode Git配置: 参考CelerisLab的VSCODE_GIT_SETUP.md

🚀 现在可以开始工作了！

1. 上传两个项目到Git

   # CelerisLab
   cd ~/CelerisLab
   git init && git add . && git commit -m "Initial commit"
   git remote add origin <url>
   git remote set-url --add --push origin <github_url>
   git remote set-url --add --push origin <gitea_url>
   git push -u origin main
   
   # DynamisLab（同样配置）
   cd ~/DynamisLab
   # ... 同上
   

2. 添加 submodule

   cd ~/DynamisLab
   git submodule add <celerislab_github_url> CelerisLab
   git commit -m "Add CelerisLab submodule"
   git push
   

3. 开始开发

   • CFD功能：在 ~/CelerisLab
   • ML功能：在 ~/DynamisLab
   • 定期同步 submodule

---

简单总结你的问题答案：

"我是在CelerisLab下开发CFD功能，同步到git，然后在DynamisLab中pull submodule吗？"

答：是的！ 这就是推荐的工作流：

1. 在 ~/CelerisLab 开发CFD → commit → push
2. 在 ~/DynamisLab 运行 git submodule update --remote
3. 提交更新：git add CelerisLab && git commit && git push

这样两个项目独立管理，但通过submodule保持连接。✨