MAC（Multi-Agent CAD）
解耦多智能体框架，用约 1/116 的 token 将简短自然语言描述直接转换为可打印的 3D CAD 模型（STEP/STL）。
证据显示：白盒透明度极好（所有中间产物落盘可审计，检查点可介入），来源归属完整（MIT、引用基线项目、标注 vendored 包来源）。扣分点：生成代码在服务端子进程执行且 Web UI 绑定 0.0.0.0，最小权限仅靠'仅限可信网络'的口头告诫，无沙箱证据；config.py 允许将 API key 写入文件（虽有环境变量优先机制）；依赖安全有 pin 与冲突说明但无 lockfile；无破坏性默认操作，回滚有 config-reset 与 halt 保留产物。
各文件间安装说明、依赖列表、入口点一致，self_consistency 高。扣分点：pip 路径本质上脆弱（需 --no-deps 强绕 numpy pin，属可点名的脆弱点）；错误消息质量（如 QA 失败、aider 漂移时的具体报错）在静态证据中几乎未展示，仅得分。
受众与场景清晰（科研、3D 打印），环境适配极好（conda/pip/macOS/Windows/CI 均有说明且标注限制）。扣分点：能力边界仅通过基准范围间接呈现，无明确'不适用场景'声明；触发精度（QA 检查点 10 秒窗口、缓存命中条件）有描述但有已知陷阱（换 prompt 不清缓存会复用旧模型），未达满分。
信息架构（目录、分节、Mermaid 指引）、安装说明、示例库均为一流水平；license 完整。扣分点：无 CHANGELOG（仅 SECURITY.md 的 1.0.x 表）；作者署名不一致——pyproject 写 'PUMA'，LICENSE/README 写清华大学 IEI 实验室，且 2026 年份异常；temp_* 文件命名依赖清理习惯，env var 名 DASHSCOPE_API_KEY 自认'历史遗留'。
输出可用性强（STEP/STL/测量 JSON/3D 预览/一键下载），边际价值有明确的每 prompt 成本与 token 分解支撑，成本收益主张量化且具体。作为静态评审这些主张未被独立执行验证，但证据内部完整自洽。
事实与推断分离做得好（10× 壁钟时间明确标注'未正式基准测试，仅数量级估计'；模型名提醒'仅为示意'）。扣分点：核心数字（116×/99.3%）全部由基线对比自报，cross_source_corroboration 薄弱；claim_traceability 依赖 docs/qwen3.7_token.md 与 quantified_quality.md，这些文件在本次证据集中未包含，无法核实其内容。
- 生成的 build123d Python 代码在服务端子进程中执行，Web UI 默认绑定 0.0.0.0——切勿在不可信网络直接暴露，务必走 SSH 隧道。
- 不要把 DASHSCOPE_API_KEY 写入 config.py 文件本体；优先使用环境变量，并确认该文件不会被提交。
- 更换 USER_REQUEST 前必须清除 pipeline_cache/ 下的两个 JSON，否则会静默返回旧模型。
- 116× token 节省、99.3% 通过率、10× 速度均为作者自报数据，未经独立验证；采用前请按 docs/quantified_quality.md 复现基准。
- 纯 pip 安装路径依赖 --no-deps 强行绕过 aider-chat 的 numpy pin，属于脆弱安装方式，建议使用 conda 路径。
- pyproject 作者署名（PUMA）与 README/LICENSE（清华大学 IEI）不一致，出版方身份未经验证，企业采用前应自行尽调。
这个 Agent 能做什么，适合哪些场景？
MAC 是清华大学 IEI 实验室开源的文本转 CAD 生成框架，核心思路是把单智能体的长上下文推理拆成 4 个由 LangGraph 状态机串联的智能体：Spec Planner、Geometric Architect、Python Coder 和 Autonomous Skill Loop（含 Aider 修复循环）。各阶段之间只传递紧凑的结构化状态（CADBrief、ArchitectPlan JSON、QA 报告），不重放对话历史，从而在 10 提示 / 141 特征基准上把总 token 从 1.039 亿降到 89.6 万，成本从 ¥125.69 降到 ¥9.67，特征通过率从 97.9% 升到 99.3%。系统通过 OpenAI 兼容端点调用模型，默认是阿里云 DashScope 的 qwen3.7-max，也可切换到 OpenAI、DeepSeek、Gemini、Ollama 本地模型或经网关使用 Claude。代码生成由确定性翻译器 _plan_to_code 将 ArchitectPlan 直接转为 build123d 代码（零 token），不支持的步骤才产出 #TODO_AIDER 占位符交给 Aider 补全。提供终端与 Web UI 两种运行方式，所有中间产物（CADBrief、ArchitectPlan、temp_design_*.py、测量与诊断 JSON、QA 报告）都落盘可审计，最终输出 STEP/STL 及生成源码。
MAC 读取 config.py 中的 USER_REQUEST 自然语言描述，按四阶段流水线处理：1）Spec Planner 将需求解析为只含 3 个验证目标的 CADBrief JSON；2）Geometric Architect 生成包含草图、步骤和选择器的 ArchitectPlan JSON；3）Python Coder 通过确定性翻译器 _plan_to_code（multi_agent_cad/nodes.py）将计划转为 build123d 代码，支持 extrude、revolve、hole、boolean_union/cut、pattern_linear/circular、mirror、fillet、chamfer、shell 等操作，不支持的步骤生成 #TODO_AIDER 占位符；4）Autonomous Skill Loop 执行代码生成 STEP/STL，用白盒特征测量（temp_measurements_*.）和运行时诊断（temp_missed_*.，分类为 MISSED_CUT / FILLET_FAILED / CHAMFER_FAILED）做 QA，失败时调用 Aider（aider-chat 0.82.3）修复循环。每次 QA 后有 10 秒检查点，可选择自动迭代（1）、注入修改要求（2）或停止（3）。运行入口为 python -m multi_agent_cad.graph（或 graph_aider 变体）和 python -m multi_agent_cad.web（FastAPI + Uvicorn Web UI，浏览器内 model-viewer 预览 GLB 并下载工件）。pipeline_cache/ 缓存前两阶段输出，重跑同一提示可跳过前两个 LLM 阶段。
- 机械工程师或创客想用一句话生成可直接 3D 打印的零件（如法兰、支架、行星齿轮组件），并控制 API 成本。
- 设计打印即装（print-in-place）铰接玩具的用户：MAC 支持单 STEP 内多实体并精确控制 0.4–1 mm 间隙，如笼中球和可旋转陀螺。
- 希望分阶段混用模型的团队：需求解析挂便宜模型、几何推理挂 qwen3.7-max、代码修复换 Claude/GPT，各阶段独立配置 MODEL/TEMPERATURE/KWARGS。
- 想训练专用小型模型替代某个阶段的研究者：因阶段间只通过 CADBrief/ArchitectPlan 结构化 JSON 交接，可单独替换 Architect 而不动其他阶段。
- 需要白盒可审计流程的工程团队：所有中间产物落盘，可在迭代检查点人工介入并注入修改要求。
- 本地部署、无云依赖的用户：通过 Ollama（如 qwen3-coder:32b）在 http://localhost:11434/v1 运行全流水线。
这个 Agent 有哪些优点和局限？
- Token 效率是核心差异化优势：基准实测总 token 从 1.039 亿降到 89.6 万（116 倍），成本从 ¥125.69 降到 ¥9.67（13 倍），API 调用从 1307 降到 50，同时特征通过率反而升至 99.3%。
- 确定性翻译器让常见 CAD 操作（挤出、旋转、孔、布尔、阵列、圆角等）零 token 生成代码，LLM 只处理边角情况。
- 白盒可审计：CADBrief、ArchitectPlan、生成源码、特征测量与失败诊断全部落盘，且每个 QA 循环有 10 秒人工干预检查点，可注入修改要求。
- 混合路由：四个阶段各自独立选模型（含温度、max_tokens、kwargs），任一阶段可用自己训练的本地小模型替换而不影响其他阶段。
- 提供终端和 Web UI 双入口，Web UI 支持浏览器内 3D 预览和一键下载。
- 安装有真实的依赖冲突需要处理：aider-chat 硬锁定 numpy==1.26.4 与 build123d 的 numpy>=2 冲突，纯 pip 路径需手动强装 numpy 2.x，Windows 只建议走 conda。
- 生成的 Python 代码在服务端执行，Web UI 明确仅限单用户可信网络，不可直接暴露到不受信任的网络。
- 默认配置绑定阿里云 DashScope 和 qwen3.7-max；切到其他提供商时需清空 Qwen 专属的 enable_thinking toggle（*_KWARGS = {}），且 README 提醒示例模型名（如 gpt-5.6）仅为示意，需自行核实实际模型 ID。
- 阶段间缓存只检查文件存在性而不校验 USER_REQUEST 是否匹配，换提示词时若忘清缓存会得到旧模型。
- 约 10 倍的挂钟速度提升只是量级估计，作者声明未做正式基准；README 中的模型名称（Qwen 3.7-max 等）与官方文档一致性的验证责任在使用者。
如何安装或部署这个 Agent？
推荐 conda 安装：
git clone https://github.com/Pan-Chera/Multi-Agent-CAD
cd Multi-Agent-CAD
conda env create -f environment.yml
conda activate multi_agent_cad
pip install --no-deps "aider-chat==0.82.3"最后的 pip 命令是必需的：PyPI 上所有 aider-chat 版本都硬锁定 numpy==1.26.4，与 build123d 要求的 numpy>=2 冲突，conda 的 pip 子进程无法绕过该锁定，因此 aider 未写入 environment.yml。纯 pip 用户（已在 macOS arm64 + Python 3.11 验证）需先装 aider-chat==0.82.3，再 pip install --no-deps --force-reinstall "numpy>=2,<2.3"，随后安装 build123d>=0.8、langgraph>=0.2,<0.3、pydantic>=2.5、openai>=1.20.0、trimesh>=4.0 等，最后 pip install --no-deps -e .。Windows 建议走 conda 流程，不要用纯 pip 变通。Web UI 需额外执行 pip install -e ".[web]"（安装 fastapi + uvicorn）。需要设置 API 密钥：export DASHSCOPE_API_KEY="sk-..."（变量名是历史遗留，接受任何 OpenAI 兼容密钥），或在 PowerShell 用 $env:DASHSCOPE_API_KEY = "sk-..."。
如何使用这个 Agent？
1）编辑 multi_agent_cad/config.py：设置 DS_API_KEY（或环境变量）、USER_REQUEST（默认生成请求）、DS_BASE_URL 及各阶段 *_MODEL/*_TEMPERATURE/*_MAX_TOKENS/*_KWARGS。2）终端运行：python -m multi_agent_cad.graph（默认工作流）或 python -m multi_agent_cad.graph_aider（把 USER_REQUEST 作为对现有 temp_design*.py 的修改需求）。LangGraph 事件流式输出到终端，每次 QA 后 10 秒检查点按 1/2/3 选择自动迭代、注入修改或停止。输出写入仓库根目录：temp_output_0.step/.stl、temp_design_0.py、temp_measurements_0.、temp_missed_0.。3）Web UI：pip install -e ".[web]" 后运行 python -m multi_agent_cad.web，浏览器打开 http://<server>:8000，填表单、预览 GLB、下载工件；生成代码在服务端执行，仅限单用户可信网络，远程访问建议 SSH 隧道。4）换提示词后需清除缓存：rm pipeline_cache/cad_brief. pipeline_cache/architect_plan.，或设 force_refresh: True。恢复默认配置：python -m multi_agent_cad._config_defaults --reset。
这个 Agent 与同类方案有什么区别？
README 将其与 earthtojake/text-to-cad（CAD Skills）做了定量对比：在相同的 10 个基准提示上，CAD Skills 消耗 1.039 亿 token、成本 ¥125.69、1307 次 API 调用、通过率 97.9%；MAC 为 89.6 万 token、¥9.67、50 次调用、通过率 99.3%。该项目的 10 个基准提示词和 vendored 的 packages/cadpy 运行时均来自 CAD Skills（MIT 许可）。若引用 MAC，作者也要求同时引用该项目。