037cd4cbb43a85443bf39f87f55d57f4e18943a4
SimpleCADAPI
SimpleCADAPI 是一个基于 CADQuery 的命令式 CAD 建模 Python 包,目标是把常见建模动作封装成清晰、可组合、可测试的函数式 API,并支持通过 Skills 方式分发“文档 + 脚本 + 运行时安装”工作流。
README 定位
本 README 仅包含包级能力、安装方式、发布/打包流程与 Skills 使用说明。 实验性脚本和临时建模样例不作为正式文档内容。
包安装(Python 包管理器)
当前包名:simplecadapi,版本:2.0.0(见 pyproject.toml)。
方式 A:用 pip 从包仓库安装
pip install simplecadapi
开发依赖可选安装:
pip install "simplecadapi[dev]"
方式 B:用 uv 安装
在当前虚拟环境安装:
uv pip install simplecadapi
作为项目依赖写入 pyproject.toml:
uv add simplecadapi
方式 C:从本地构建产物安装
仓库内已有示例构建产物(dist/):
pip install dist/simplecadapi-2.0.0-py3-none-any.whl
如果你需要重新构建:
uv build
快速验证安装
import simplecadapi as scad
box = scad.make_box_rsolid(10.0, 20.0, 30.0)
scad.export_stl(box, "example_box.stl")
scad.export_step(box, "example_box.step")
如何打包并使用 Skills
本项目提供 skill-pack CLI,用于生成轻量技能包(thin mode):不内置 SDK 源码,运行时从包仓库安装 simplecadapi。
1) 打包命令
在仓库根目录执行:
uv run skill-pack --refresh-docs --archive --skill-name simplecad-self-evolve
常用参数:
--output-root <dir>:输出目录(默认./skills)--package-name <pkg>:运行时安装包名(默认读取project.name)--package-version <ver>:运行时安装版本(默认读取project.version)--no-clean:不清理已有输出目录--archive:额外生成<skill-name>.tar.gz
2) 打包结果结构
打包后将得到类似目录:
skills/simplecad-self-evolve/SKILL.mdskills/simplecad-self-evolve/scripts/skills/simplecad-self-evolve/references/skills/simplecad-self-evolve/cases/simplecad_self_evolve_cases/
3) 在 skill 目录中安装并检查运行时
cd skills/simplecad-self-evolve
PYTHON_BIN=.venv/bin/python scripts/install.sh
PYTHON_BIN=.venv/bin/python scripts/with_skill.sh --check
4) 用包装脚本运行你的程序
PYTHON_BIN=.venv/bin/python scripts/with_skill.sh -- .venv/bin/python your_script.py
5) 激活 skill-local 案例模块路径
eval "$(scripts/with_skill.sh --print-env)"
激活后可直接导入:
from simplecad_self_evolve_cases.evolve import make_involute_spur_gear_rsolid
6) 向 skill 本地 evolve 模块追加新函数
scripts/add_new_case.sh path/to/new_case.py
7) Jupyter 与结构校验
scripts/jupyter_with_skill.sh lab
scripts/validate_skill.sh
自动化工具(Auto Tools)
项目内置 4 个主要 CLI:
auto-docs-gen:从 API 源码生成docs/api/文档make-export:更新src/simplecadapi/__init__.py的导入导出evolve:从脚本提取函数并追加到 evolve 模块skill-pack:打包 thin skill(文档 + 脚本 + cases)
示例:
uv run make-export --dry-run
uv run auto-docs-gen
uv run evolve path/to/your_case.py
uv run skill-pack --refresh-docs --archive
开发与测试
本地开发安装(可编辑):
uv pip install -e ".[dev]"
运行单元测试:
uv run python -m unittest test/test_all_features.py
运行示例:
uv run python examples.py
核心设计约束(简要)
- API 函数统一使用
snake_case,并通过函数名体现返回类型(如*_rsolid、*_rwire)。 - 核心类型尽量稳定,功能扩展通过新增函数完成(开放封闭原则)。
- 支持
SimpleWorkplane上下文进行局部坐标建模。 - 导出接口支持单实体、多实体及嵌套列表输入。
文档入口
- API 文档:
docs/api/ - Core 文档:
docs/core/
License
MIT,见 LICENSE。
Description
Languages
Python
58.3%
C++
30.5%
TypeScript
11%
CMake
0.1%