Text-to-CAD：参数化源码、几何证据与负责任的交接
cadgen 源码分析：惰性 build123d 代理、对象缓存与提前导入
检查公共入口，用假依赖测试准确的代理源码，不把隔离机制验证说成 CAD 内核性能测试。
你将学会
- 公共命名空间只延迟部分工作
- 代理返回真实对象，再把它缓存
- 只验证正在讨论的机制
开始前需要
- 了解 Python 函数、模块与文件路径
- 理解单位以及设计和实物之间的区别
规划有边界的 CAD 练习，区分源码新鲜度、文档检查、视觉审阅和制造决策。
先看结论
- 代理缓存依赖的真实对象，而不是包装类。
- dir 和直接对象导入可能提前触发解析。
- 代理隔离测试不是几何或性能测试。
公共命名空间只延迟部分工作
cadgen.__init__ 使用模块级属性查找暴露格式命名空间、装配辅助、场景工具和 build123d 代理。格式名称返回其模块，让导入和装饰器访问保持同一标识。这是 API 组织方式，不代表所有导入依赖都很轻量。
包入口还在导入时调用内核导入追踪和字体保护。我们检查了这些调用，但测试没有运行包初始化器，也没有审核全部辅助逻辑。延迟获取几何类，不应被描述为整个包导入完全没有副作用。
代理返回真实对象，再把它缓存
cadgen/build123d.py 的 _REAL 初始为空。首次请求普通属性时，它导入 build123d、取得真实对象，并写入代理模块全局字典。以后读取该名称就成为普通属性访问，不是用新的兼容类包装 Box。
缺失的双下划线探测会直接抛出 AttributeError，不触发重导入。但 __dir__ 会向真实模块查询名称，因此 dir(proxy) 能触发导入。直接导入 Box 同样需要立即解析对象，属性式访问才把成本推迟到实际使用时。
只验证正在讨论的机制
八项隔离测试用假的 build123d 模块执行已阅读代理源码，覆盖延迟加载、双下划线探测、对象标识、全局缓存、重复与第二属性、dir、直接导入和未知属性失败。测试恢复模块状态，不导入几何内核。
这些结果验证受控输入下的小型代理机制，不验证完整 CAD 生成、真实导入延迟或守护进程性能。源码包含时间描述，本系列不会把它改称为自己的实测结果。未知属性保持报错，不被悄悄补造。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
分开追踪包入口工作和惰性属性。
- 2
阅读首次访问与全局缓存赋值。
- 3
同时测试普通访问和内省。
- 4
明确说明假依赖和未测运行时。
可复制示例
{
"隔离测试": true,
"依赖": "假的 build123d 模块",
"通过案例": 8,
"已执行CAD内核": false,
"已生成几何": false,
"已测导入时间": false
}常见问题
bd.Box 是另外一个包装类吗？
已检查代理返回并缓存依赖中的真实对象。
仅调用 dir 也会触发真实导入吗？
会，代理的 __dir__ 需要解析真实模块来收集名称。
资料来源
- Text-to-CAD / packages/cadgen/src/cadgen/__init__.py来源核查 2026-09-14
- Text-to-CAD / packages/cadgen/src/cadgen/build123d.py来源核查 2026-09-14