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.md
  • skills/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。

S
Description
No description provided
Readme Apache-2.0 77 MiB
Languages
Python 58.3%
C++ 30.5%
TypeScript 11%
CMake 0.1%