先给结论：text-to-cad 不是"AI 画图工具"，它是一套把智能体接入真实工程工作流的本地运行时。 它值钱的地方不在于"能生成 STEP 文件"，而在于它把三件通常被忽略的事写成了硬规则：模型脚本就是工具本身、生成物与源码彻底解耦、审查只给测量、不给认证。这三条决定了它能不能被工程交付信任。

目录

1. 它是什么
2. 真问题：不是"会不会建模"，是"能不能对结果负责"
3. 三层架构：技能层 / 引擎层 / 呈现层
4. 模型契约：脚本就是工具，没有 CLI
5. 第一条"法律"：生成物与源码彻底解耦
6. 技能是产品，模型是测试夹具
7. 审查哲学：证据优先，不认证，不能测就明说
8. Gauntlet：一个盲评美学的质量闭环
9. 技能矩阵与路由
10. 运行形态：uv、pinned 版本、MCP Apps、常驻 daemon
11. 工程治理：合并即发布
12. 现实约束：Smart App Control、遥测、内核依赖
13. 对 BIM 与工程交付的启发
14. 成熟度评估
15. 结语
16. 免责声明

一、它是什么

一句话：给智能体装上 CAD 能力的本地插件 + 技能库 + 引擎，输出 STEP / GLB / STL / 3MF，并附带可制造性审查、工程图纸和切片能力。

项目由 earthtojake 维护，MIT 许可，主语言 Python。数据快照（2026-10-16）：

贡献者分布也值得看一眼，因为它透露了这个项目的运作方式：

一个智能体账号（claude）排在人类贡献者前面——这不是彩蛋，而是这个仓库的日常工作方式：它本身就是一个"由智能体执行、由人治理"的工程。AGENTS.md 是仓库根目录的一等公民文件，里面写的是分支纪律和发布规则，不是给人类的贡献指南。

二、真问题：不是"会不会建模",能不能对结果负责

大多数 text-to-CAD 方案停在"生成一个模型"。这一步在演示里很漂亮，在工程里不够用，因为它缺三样东西：

1. 可复现性——生成的模型是一次性产物，改一个尺寸就得从头再来，没有"源"；
2. 可验证性——它说"壁厚 2 mm"，但没人量过，只是模型自己说的；
3. 可交付性——工程交付要的是图纸、公差、工艺判断、刀路，不是一个能转着看的 3D 预览。

text-to-cad 的应对方式很直接：把 CAD 工作流拆成可执行的契约。模型是脚本，脚本可重跑；测量是工具输出的事实，不是模型的自述；图纸是从几何投影出来的文档，不是手画的；审查是"测量 + 引用的规则来源"，不是"AI 觉得可以"。

这就是它和"AI 建模"最大的分野：它把 AI 放在执行者的位置，把判断权留给可验证的证据。

三、三层架构：技能层 / 引擎层 / 呈现层

flowchart TD
    A["智能体宿主
Claude Code / Codex / Cursor / Gemini / Grok"] --> B["插件清单层
plugin.json · claude.mcp.json · gemini-extension.json · skills.sh.json"]
    B --> C["技能层 skills/（12 个）
cad · dxf · engineering-drawing · urdf · srdf · sdf
dfm · dfam-check · gcode · bambu-labs · step-parts · sendcutsend"]
    C --> D["引擎层 cadgen（PyPI）
Python 引擎 + 打包的 JS runtime + 原生 file tracer"]
    D --> E["呈现层
cadgen viewer（本地 HTTP，端口 3245）
cadgen mcp（MCP Apps）· 常驻 build daemon"]
    D --> F["几何内核
OCP（Open CASCADE 7.9 的 Python 绑定）+ build123d 0.11"]
    style C fill:#0A7CFF,stroke:#0A7CFF,color:#fff
    style D fill:#7C3AED,stroke:#7C3AED,color:#fff
    style E fill:#2EA44F,stroke:#2EA44F,color:#fff
    style F fill:#E2001A,stroke:#E2001A,color:#fff

三层的职责边界在文档里写得很干净：

• 技能层是"产品"——每个 SKILL.md 定义任务边界、工作流和引用参考，智能体读它来行动；
• 引擎层是"能力"——模型执行、store、文档装配、运动学、导出、校验、检查、快照、build pool；
• 呈现层是"界面"——同一个 viewer 页面，通过 HTTP（浏览器）或 MCP Apps 桥（宿主内嵌卡片）两种通道暴露。

值得注意的是 @text-to-cad/core 的依赖约束里有一句：“Never React, ReactDOM, Electron, Next.js, UI or application source”，且"Browser entry points never import Node-only code"。这是一个把"渲染核心"和"应用"严格分开的包边界声明——它保证引擎层能脱离任何具体宿主运行。这也是为什么同一个页面能同时服务 Codex 的 tab、Claude Desktop 的卡片和浏览器 viewer。

四、模型契约：脚本就是工具，没有 CLI

这是整个项目最容易被低估的一条设计。skills/cad/references/step-generation.md 的标题就是 “The model script is the tool”——生成没有 CLI。一个模型就是一个普通 Python 脚本：

from cadgen import build123d as bd
from cadgen import step

WIDTH = 10.0

@step
def bracket():
    return bd.Box(WIDTH, 10, 10)

if __name__ == "__main__":
    bracket()

跑 python bracket.py 就产出 bracket.step。契约里几条规则很讲究：

• 装饰器只声明，不执行——装饰或 import 时什么都不发生，只有直接运行文件时才构建；
• 一个模型只有一套输出，在装饰器里声明，没有"每次运行临时指定输出"的口子；
• 未改动的源是快速 no-op——重跑不重复计算；
• store 的记录以脚本为键，不是以产物为键。

这套设计把"生成"从一次性动作变成了可持续的源。改尺寸 = 改参数 = 重跑，产物、缓存、sidecar 全部跟着走。对工程场景，这就是"可复现"的最小实现——它比"AI 又生成了一个新模型"强一个数量级。

五、第一条"法律"：生成物与源码彻底解耦

packages/cadgen/README.md 里明确用 LAWS（不是 conventions）这个词，并且给每条法律配了一个"压力测试"。第一条是：

生成文件与它的源代码完全独立——STEP、DXF、STL、GLB、3MF 及其 sidecar（<name>.step.json）永远独立成立。

它的压力测试写得非常具体：一个生成文件必须"仅通过读这个生成文件"就能被完整读取（viewer、snapshot、read_scene），不许去猜旁边的 JavaScript 文件、不许回读源码。

由此派生出 Viewer three-input law：客户端渲染只依赖三样东西——文件本体、可选的 sidecar、缓存。动画源嵌在那一个 sidecar 里，不发现、不抓取任何相邻文件。

这条法律的实际价值在于：交付物可以脱离工具存在。你把 .step 发给工厂、发给同事、发给另一个软件，它不需要"我们的生成脚本"就能被正确解读。这是工程交付的基本前提，很多 AI 生成工具恰恰在这里断链——产物离开了它的生成环境就变成一堆无法解释的数据。

顺带一提，文档里还有一句很硬的话：“a change that violates them is wrong even when it works.”（违反法律的改动，即使能跑也是错的。）这种表述方式本身就说明这个项目的治理强度。

六、技能是产品，模型是测试夹具

CONTRIBUTING.md 和 AGENTS.md 都写了同一句话：把 skills/ 当作被测产品，把 models/ 当作共享夹具。

这个定位很关键——它意味着这个仓库的"软件"不是某个 app，而是技能定义本身。models/ 里的东西（f1、f14d、hypercar、radial、w16、tendon_hand、falcon_heavy、juno、lyra、moonwatch、motorbike、qdd_actuator）是验证这些技能是否真的能跑通的样本集。

models/README.md 里的三分法也很清楚：一个零件是一个脚本，一个装配体是一个目录，一张图纸是一个 @dxf——三者各有自己的 src/README.md 目录清单。而且新克隆的仓库里没有 STEP/ 目录，产物靠跑脚本重新生成：

cd models/<project>
ls src/*.py | xargs -n1 -P4 python     # unchanged models no-op

这跟第五节的法律是自洽的：产物不进仓库，源进仓库；产物是源的函数，但产物本身不依赖源就能被读取。

样本集的质量也值得一提。models/radial/REPORT.md（九缸星形发动机，2026-09-25 完成）里每一项参数都带来源：

还有一句很关键的验证记录：轴承 STEP 往返测试，用未改动的 main 版 cadgen，最大相对体积差 1.01e-7。 这是可复现的量化证据，不是"看起来对"。

tendon_hand 则是 24 个关节自由度、48 个对置肌腱驱动器的研究项目，明确标注"工程状态仍在进行中"——它连"哪些是已完成的、哪些是交接状态"都用文件（RESUME_STATUS.md、各种 *_handoff.md）分开记录。这种状态管理方式，比大多数 CAD 仓库成熟。

七、审查哲学：证据优先，不认证，不能测就明说

skills/dfm/SKILL.md 的开头就把自己限死了：

这是一个 guided review skill，不是自动特征识别或制造认证引擎。不可用的检查必须显式报告。

它的证据规则非常具体：

• 优先用用户实际供应商/工装规范，而不是通用指导；
• 遇到冲突规范要记录冲突，不擅自选一个；
• 优先精确的 STEP/B-rep 测量（半径、解析面）；只有网格时记录其分辨率和近似限制；
• 截图只能支持"疑似问题"，不能支持"测量通过/不通过"；
• 源码参数描述的是设计意图，必须先验证它与被审查的产物一致，才能当证据；
• 绝不从渲染的材质或颜色推断合金、树脂、强度或坯料厚度。

dfam-check 更极端：它的工具是 fact-only——只报测量值，不输出 pass/fail 或就绪状态，判断权归工作流。而且它明确"从不切片、不上传、不启动打印任务"。

这套哲学在 AI 工具里很少见。多数工具倾向于给一个结论（“这个零件可以注塑，建议加大圆角”），而 text-to-cad 倾向于给一个可追溯的证据链 + 明确的不可测项。对工程交付，后者才是能签字的东西——因为签字需要的是"我量过、规则来源是这一版这一节"，不是"AI 说可以"。

engineering-drawing 技能里也有同一种洁癖：图纸是从零件几何投影出来的文档，尺寸放在几何上的点之间，中心标记在几何上找，“没有任何东西是手画的，没有任何数字是你敲的，除非你主动覆盖”。输出是一张 PDF——车间收到的就是它。它同时明确区分：$dxf 做的是刀路和展开，那是工具路径，不是文档，两者是不同的活。

八、Gauntlet：一个盲评美学的质量闭环

这是我觉得最有意思的一块。models/radial/GAUNTLET.md 定义了一套盲评协议：

每个零件，一个全新上下文的评审者只看两张图——我们的渲染（presentation envelope, presentation-large）和一张博物馆/修复实物照片，作为 a.png / b.png 随机顺序呈现（密钥在 tmp/critic/keys/，永远不给评审者看）。问题是"哪个更美？"。输的一方，评审者只指出一个最大差距，这个差距路由回该零件的负责人。

flowchart LR
    P["某个零件"] --> C1["渲染（presentation-large）"]
    REF["博物馆 / 修复实物照片"] --> PACK["critic_pack.py
a.png / b.png 随机顺序"]
    C1 --> PACK
    PACK --> CR["全新上下文的评审者
只看两张图"]
    CR --> Q{"哪个更美？"}
    Q -->|赢| DONE["通过"]
    Q -->|输| GAP["只指出一个最大差距"]
    GAP --> OWNER["路由给该零件负责人"]
    OWNER --> P
    style CR fill:#7C3AED,stroke:#7C3AED,color:#fff
    style GAP fill:#EF4444,stroke:#EF4444,color:#fff

它的价值不在"审美"，而在方法：随机顺序 + 密钥不外露 + 全新上下文 + 只允许指出一个差距。这四条把"评审者偏袒自己人做的东西"和"评审者一次提十条意见导致无法收敛"两个常见失效都堵住了。

看它的实际记录就知道这套方法有多不留情面——连续多轮全输，而且失败原因具体到可执行：

• 连杆轮：“可动连杆看起来像短粗的黄铜杯形衬套……没有杆身伸到活塞” → 路由给 layout（窗口/曲轴箱剖视/相机）；
• 缸头轮：“摇臂箱是过大的平盖长方体，压过了缸头本身，应该是小而圆的铸造壳体” → 路由给 heads；
• 活塞轮：“腕销凸台有黑色斑点的 z-fighting，裙部以一个截锥式的平面斜切收尾；应该显示中空内部、肋状凸台、干净的销孔” → 路由给 pistons。

注意最后一条：评审者不知道哪张图是自己的，它照样能指出具体缺陷。这就是盲评的意义。

对做工程可视化和汇报的人，这套协议可以直接搬——把"渲染质量"从主观印象变成一个可收敛、可追溯的闭环。

九、技能矩阵与路由

12 个技能，覆盖从建模到交付的完整链路：

路由逻辑（技能之间边界清楚，不重叠）：

flowchart TD
    Q["自然语言请求"] --> R{"任务类型"}
    R -->|"建模 / 改模型"| CAD["cad → STEP（主输出）
STL / 3MF / GLB"]
    R -->|"2D 切割 / 展开"| DXF["dxf → 刀路图"]
    R -->|"出图纸"| ED["engineering-drawing → 一张 PDF"]
    R -->|"机器人描述"| UR["urdf / srdf / sdf"]
    R -->|"可制造性审查"| DFM["dfm（钣金 / CNC / 注塑）
dfam-check（增材）"]
    R -->|"切片与打印"| GC["gcode（OrcaSlicer）→ bambu-labs"]
    R -->|"标准件"| SP["step-parts"]
    R -->|"上传前校验"| SC["sendcutsend"]
    style CAD fill:#0A7CFF,stroke:#0A7CFF,color:#fff
    style DFM fill:#F59E0B,stroke:#F59E0B,color:#fff
    style ED fill:#2EA44F,stroke:#2EA44F,color:#fff

几个边界写得很干净，值得注意：

• $dxf 拥有 2D，$cad 拥有这张图纸投影出的任何 3D 零件——谁拥有几何，谁负责；
• $gcode 永不接触打印机，它只切片；Bambu 的路交给 $bambu-labs，其他打印机把 .gcode 交回给用户；
• $dfam-check 从不切片、不上传、不启动打印，它只测量；
• URDF 的 .urdf 文件就是唯一真相源，不允许为它建 Python 生成管线（“There is no gen_urdf() contract”）——这条是对"脚本即工具"的例外，说明规则是按领域定的，不是一刀切。

十、运行形态：uv、pinned 版本、MCP Apps、常驻 daemon

运行形态上几个具体事实：

• 一切通过 uv 跑，所有技能共享同一份安装和同一个 warm build daemon；技能里的 cadgen 实际是 uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.21 cadgen——版本是钉死的；
• 首次运行才下载，后续复用；旧版本留在 uv 缓存里，直到 uv cache prune；
• viewer 是本地 HTTP 服务，端口 3245（或 --port 指定），按绝对路径服务每个 CAD 文件；
• MCP 服务（cadgen mcp）走 viewer 自己的路由，两种呈现方式：Codex 类宿主给 tab（侧栏 CAD、每个 thread 一个 CAD tab、Open with CAD），其他 MCP Apps 宿主在对话里挂 viewer 卡片；
• agents 只用绝对路径命名模型——“agents name models by absolute path only”，这条看似琐碎，实际是避免路径歧义的关键约束；
• 离线时什么都不发、一切照常工作。

安装方式上有个细节值得说：README 推荐的首选安装方式是"让智能体自己装"——发一句 Install text-to-cad from https://github.com/earthtojake/text-to-cad。这不是营销话术，而是这个项目的自我定位：它的产品就是给智能体用的，所以安装动作本身也交给智能体执行。

另外 latest 分支和 main 分支的分工很清晰：latest 只放插件、每个发布一个 commit、只由 Publish Release 写；main 是开发分支，也能装，但可能含未发布的改动。各宿主引用分支的语法不同（#latest、--ref latest、@latest、--branch latest），不写就装 main。

十一、工程治理：合并即发布

AGENTS.md 里的发布规则是我见过最简洁的一套：

一个改动 VERSION 的 PR 就是一个发布，合并它即发布。 正常开发期间绝不 bump，也不要自己挑版本号——如果请求没说明是 patch / minor / major 或精确版本，就要问。

flowchart LR
    PR["PR 改动 VERSION"] --> TC["Test：跑全部 job
Version Check 校验 bump"]
    TC --> MERGE["需明确批准才合并
合并 = 发布"]
    MERGE --> PUB["Publish Release
插件 ZIP + bundle + wheel + sdist
安装并跑一遍 wheel · 传 PyPI · 等索引列出"]
    PUB --> LATEST["latest 分支：每发布一个 commit
只由 Publish Release 写"]
    style MERGE fill:#F59E0B,stroke:#F59E0B,color:#fff
    style PUB fill:#0A7CFF,stroke:#0A7CFF,color:#fff

几条配套的纪律：

• main 是唯一长期分支，从它开分支、向它开 PR，绝不直接推 main；
• Version Check 只认本仓库的分支（fork 不能发布），且必须是超过 main 当前版本和最新 tag 的版本；
• 发布 PR 的 checks 通过后，只在明确指示下合并；
• Publish Release 会找到把合并树完整测过的那次 Test 运行，否则先跑一遍——发布是整体测试的；
• 没有 development symlink 布局，树里每个路径都是真实文件。

这套治理的可贵之处在于它把"发布"这个动作压缩成一个可验证的单一事件：改版本号 + 合并。没有"发版分支"、没有"手动打包"、没有"忘了同步 tag"这类常见的漂移源。

十二、现实约束：Smart App Control、遥测、内核依赖

丑话说在前面，几条实际会踩的：

1. Windows 11 Smart App Control 会直接阻断。 几何内核 OCP（Open CASCADE 的 Python 绑定）的 wheel 带一个未签名的原生模块。Windows 11 的 Smart App Control 拦截未签名原生代码，所以在开启 SAC 的机器上（全新安装默认开启），每个 cadgen 命令和 import build123d 都会失败：ImportError: DLL load failed while importing OCP，事件查看器在 CodeIntegrity › Operational 下记录 Event ID 3077。cadgen doctor 能识别这个情况。

关键是：Smart App Control 没有单应用例外。要么关掉（关掉后只能重装 Windows 才能再开），要么在 WSL 下跑（那里不适用）。这个 wheel 是 cadquery-ocp 项目构建的，签名不是这个仓库能做的事。

2. 遥测默认开启。 上报的是版本、安装来源、OS 与宿主 app、各类计数（工具调用频次、失败原因用固定词表、视图使用、格式分布、构建与快照数量、耗时），以及崩溃报告（错误类型和发生位置，不含消息，你自己的代码只留占位符）。服务器按 IP 推断国家（不保留 IP），存进 PostHog。从不上报文件名、路径、内容或 prompt。 关闭方式：uvx cadgen telemetry off（同时删除已发送数据）、界面里的 Share usage stats、或 DO_NOT_TRACK=1 / CADGEN_TELEMETRY=0；CI 和开发安装默认不发送。

更新检查是另一回事：每天最多一次匿名请求 api.texttocad.dev/v1/versions，不带 ID、路径或任何关于你的信息，不进 CI，CADGEN_UPDATE_CHECK=0 可关。

3. 依赖不轻。 Python 3.11+、Node 20+（打包 runtime / viewer / core / 文档站需要 Node 22）、uv、Open CASCADE 7.9、build123d 0.11。纯 Python 工作可以推迟 Node，但"轻量插件"这个印象不成立——它是一个带原生模块和 JS runtime 的运行时。

4. 项目仍年轻。 创建约 6 个月，版本 0.7.x，43 个开放 issue，4 天 5 个版本的节奏说明它在快速变动。README 里也承认 main 可能含未发布改动，且已退役的 cad-viewer、cad-mcp-setup 技能需要手动清理——这类"接口仍在收敛"的信号很明确。

十三、对 BIM 与工程交付的启发

抛开 CAD 本身，有几条是可以直接搬走的：

1. 把"生成"变成"源 + 产物"的分离。 参数化脚本是源，产物是函数结果，产物本身不依赖源就能被读取。这正是 BIM 里"族/参数/导出物"关系应有的样子——很多 BIM 工作流的痛点恰恰是导出物离开了生成环境就无法解释。

2. 给工具写"法律"，并配压力测试。 “违反法律的改动即使能跑也是错的”——这条比代码规范更有效，因为它给的是判定方法（“仅读这个文件能否完整解读它？"），不是偏好。

3. 审查输出区分"测量"和"判断”。 fact-only 的工具只报事实，判断归工作流。这个分离在 BIM 校审里同样成立：检查器报"净高 2.35 m、规则来源是 GB 50096 第 X 条"，而不是报"不合规"。前者可追溯、可签字，后者不可。

4. 明确"不可检查项"是输出的一部分。 DFM 技能要求显式报告不可用的检查。很多校审报告的问题不是判断错，而是把无法验证的项写成了已验证。

5. 盲评闭环值得复制到可视化质量管控上。 随机顺序 + 密钥不外露 + 全新上下文 + 只允许指出一个差距——这是一个可收敛的质量闭环，比"领导说渲染不够好"强得多。

6. 把"合并即发布"作为最小治理。 一个可验证的单一事件，比一套发版流程可靠。

十四、成熟度评估

已经确认的：三层架构成立且边界明确；模型契约可执行；生成物独立性有明确判定方法；审查哲学在文档中自洽；发布治理完整且可验证；样本集带可复现的量化证据。

需要你自己验证的：

• 它能不能接住你的工程——大型装配、外部导入 STEP、复杂运动学、既有命名规范；
• Windows 上 Smart App Control 是否开启（这是硬阻断，无例外）；
• 遥测策略是否符合你的合规要求（默认开启，可关，但需要主动关）；
• 技能文档与安装版本的一致性——README 提醒 main 可能含未发布改动，已退役技能不会自动移除；
• 与既有 BIM 工具链的互操作（STEP 是通用交换格式，但属性、图层、族语义不在 cadgen 的契约范围内）。

适合谁：需要"AI 能真的产出可交付物"而不是"AI 能画个好看的模型"的工程团队；愿意把参数化脚本当作源、把产物当作函数结果的人；需要可追溯审查证据（而不是结论）的场合；以及想把"技能契约 + 法律 + 压力测试"这套方法搬到自己项目里的人。

不太适合：不能接受默认遥测的强合规环境；Windows 上无法关闭 Smart App Control 的机器；只想要"点一下出个模型"的轻量场景（它的价值在契约，不在便利）；以及需要属性/族语义级 BIM 交换的场合——它管的是几何，不是 BIM 数据模型。

十五、结语

text-to-cad 真正值得记住的，不是"2 万 star"，而是它对"AI 做工程"这件事的三个立场：

• 源必须存在——模型是脚本，不是一次性产物；改一个参数要能重跑，而不是重新生成；
• 产物必须独立——生成文件与它的源代码完全独立，这是法律，不是惯例，而且配了压力测试；
• 判断必须有出处——工具只给测量，规则要引用到具体版本和章节，不可测的项要明说，截图不能当作测量结论。

这三条合起来，把"AI 生成"从演示拉回到交付。它没有声称 AI 能做工程判断，它做的是：让 AI 能执行，让证据能追溯，让边界能承认。

在一个几乎所有 AI 工具都在承诺"我都能做"的赛道里，一个明确写着"这是 guided review，不是认证引擎"、“不可用的检查必须显式报告”、“绝不从渲染的颜色推断合金"的项目，工程气质是罕见的。

免责声明

本文为个人学习性质的开源项目文档解读，不构成对该软件的推荐、担保或安全评估。text-to-cad 为 MIT 许可的开源项目，处于快速迭代期（数据快照 2026-10-16，版本 0.7.21，创建约 6 个月）；文中数据来自 GitHub API 与仓库自身文档（README、CONTRIBUTING、AGENTS、各 SKILL.md、packages 文档、models 报告），不代表你的实机表现。特别提示：① 默认开启遥测（不含文件名、路径、内容、prompt，可关闭），使用前请核对你的合规要求；② Windows 11 Smart App Control 会硬阻断 OCP 原生模块，无单应用例外，只能关闭 SAC 或改用 WSL；③ 依赖不轻（Python 3.11+、Node 20+/22、uv、Open CASCADE 7.9、build123d 0.11）；④ 文档中的质量数据（如 1.01e-7 体积差）来自项目自身的验证记录，需在你自己的工程上复现后才可依赖；⑤ 涉及制造、打印、加工的判断属于工程责任范畴，本项目的审查技能明确声明不是认证引擎，最终判断仍需由具备资质的人员作出。