跳到主要内容

参与贡献

CadFlow 由公共 Python 前端、C++17 运行时、生成式跨语言契约和大型兼容测试套件组成。贡献应保持收窄的公共边界，并提供与行为变更风险相称的证据。

仓库结构​

CadFlow/
├── python/cadflow/          公共前端与领域 Facade
├── python/cadflow/_engine/  内置完整 Python 功能层
├── native/                  C++ Session、内核、I/O、Runtime 与 Physics
├── scene-contract/          跨语言 Scene Schema 与验证器
├── skills/                  Agent 工作流与 API 参考
├── examples/                零件、装配、柔性模型与重建
├── docs/                    架构、指南与生成 API 文档
├── agent_dsl/               可选实验性命令封装
└── tests/                   原生、打包、兼容和工作流测试

开发环境​

先完成安装，再安装测试依赖：

python -m pip install -e ".[test]" --no-build-isolation

修改原生后端时：

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j2

并行度应与可用内存匹配；OCCT 密集型构建可能消耗较多资源。

运行测试​

python -m pytest -q

开发时先运行最相关的测试文件，提交前再运行完整套件：

python -m pytest -q tests/test_native_backend.py
python -m pytest -q tests/compat_suite/test_compat_public_api_surface.py
python -m pytest -q

打包变更还应构建 Wheel：

python -m pip wheel . --no-deps -w dist

遵守所有权边界​

  • 公共集成使用 import cadflow as cad 和公共领域模块。
  • Python 前端不得泄漏 OCC 对象或私有 C++ Handle。
  • c_api.cpp 保持为稳定 ABI 入口。
  • 几何密集型算法属于原生 Kernel。
  • 约束、策略、Schema、诊断和元数据可以保留在 Python。
  • 迁移兼容行为前应先有特征化测试。

新增或修改公共操作​

根据实际情况覆盖完整纵向链路：

  1. C++ Kernel 实现与验证。
  2. 稳定 C ABI 入口。
  3. Python 原生 Binding。
  4. Model Facade，以及适用时的 Graph 支持。
  5. 所有权与无效输入测试。
  6. OCCT 等价或往返证据。
  7. 用户指南与生成 API 更新。

Pull Request 检查表​

  • 变更解决一个明确陈述的问题。
  • 公共行为与限制均有文档。
  • 新代码遵守既有所有权边界。
  • 测试覆盖成功、无效输入和相关兼容行为。
  • 只有源发生变化时才更新生成文件。
  • CAD 示例会验证几何并检查非空输出。
  • 应用代码不依赖 cadflow._engine 或直接 OCP 对象。
  • License 与 OpenCascade Notice 要求保持完整。

大型实现前，请先在 GitHub Issue Tracker 中讨论缺陷或行为提案。