企业官网建设流程全解析

Modly如何与ComfyUI联动？实验性工作流编排命令详解

【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modly

Modly 是一款完全运行在本地 GPU 上的开源 AI 桌面应用，可以从图片或文字提示词生成 3D 模型。除了内置的工作流编排，它还隐藏了一套实验性（experimental）ComfyUI 编排命令：通过 tools/modly-cli/agent.py 这个仅依赖标准库的 CLI，把 Modly 的本地 API（http://127.0.0.1:8765）与 ComfyUI（默认http://127.0.0.1:8188）串成一条自动化链路——"ComfyUI 出图/出模 → Modly 图生 3D → 导出 mesh"，全程无需人工点击界面。

联动原理：两个本地服务 + 一个 JSON 优先的 CLI

整个联动架构可以拆成三层：

CLI 的所有命令都遵循同一套"契约"：最终结果以 JSON 打到 stdout，进度信息（如启用--progress）打到 stderr。这样脚本和 AI Agent 都能稳定解析，例如 SKILL.md 中定义的就是一份完整的 Agent 输出契约。

ComfyUI 侧的对接逻辑集中在 agent.py 的几个函数里：

• 工作流定位（_load_comfy_workflow）：--workflow既可以是本地 JSON 文件路径，也可以是 ComfyUI 里已保存的工作流名。后者会依次尝试 ComfyUI 的/userdata/workflows/API、COMFYUI_WORKFLOW_DIR环境变量、~/ComfyUI/user/default/workflows/、Windows 的APPDATA/ComfyUI/...等候选目录。
• 参数注入（_patch_comfy_workflow）：--prompt会自动写入第一个正向CLIPTextEncode节点，--seed会替换所有seed/noise_seed输入，方便复现实验。
• 任务提交与轮询（_run_comfy_workflow）：以 API 格式 POST 到 ComfyUI 的/prompt，拿到prompt_id后循环查询/history/{prompt_id}直到完成，超时则返回TIMEOUT错误码。

⚠️ 注意：工作流必须是API 格式（顶层为节点 ID 对象的 JSON），编辑器格式（含nodes/links字段）会被明确拒绝，需先在 ComfyUI 中导出为 API 格式。

前置准备：先体检，再联动

任何实验命令执行前，建议先确认 Modly 桌面端在运行且 API 可达：

python tools/modly-cli/agent.py health

返回{"ok": true}才算就绪。如果应用未启动，CLI 会给出结构化失败信息（code: "API_UNAVAILABLE"）而不是直接崩溃——这是它"fail closed"的设计特点。

ComfyUI 侧只需保证服务在http://127.0.0.1:8188（或通过--comfy-url/COMFYUI_URL环境变量指向其他地址）即可，无需额外配置。

命令一：experimental comfy-image（只取 ComfyUI 的图）

comfy-image是最小联动单元：跑一个 ComfyUI 工作流，把它的第一张图像产物下载到本地。

python tools/modly-cli/agent.py experimental comfy-image \ --workflow Trellis2Workflow \ --prompt "clean object render, isolated on white" \ --comfy-output ./source.png

行为细节（见 agent.py）：

• 默认工作流名为Trellis2Workflow，可省略--workflow参数；
• 不指定--comfy-output时，图片会写入一个modly-comfy-前缀的临时文件；
• 若工作流跑完却没有图片产物，报错码为NO_WORKFLOW_OUTPUT；
• 输出 JSON 中带meta: {"experimental": true, "canonical": false}，明确提示这属于实验能力，不属于 Modly 的正式契约。

命令二：experimental generate-from-workflow（出图或出模，自动走完全链路）

这是联动玩法的核心命令，逻辑分两种情况（agent.py）：

1. ComfyUI 直接产出 3D 资产：若历史记录中存在可下载的.glb/.gltf/.obj/.stl/.ply文件，CLI 会直接下载到--output指定的路径并结束——不会再调用 Modly。
2. 工作流只产出图片：CLI 先下载该图，然后自动走 Modly 标准的workflow-run图生 3D 路径，最终得到 3D 模型；JSON 中source为comfy-workflow、output_type为image，并附带comfy字段记录 ComfyUI 侧信息。
3. 既没有 3D 资产也没有图片：报错NO_WORKFLOW_OUTPUT。

完整示例：

python tools/modly-cli/agent.py experimental generate-from-workflow \ --workflow Trellis2-Full \ --prompt "clean orthographic product render of a stylized robot toy" \ --output ./export.glb \ --progress

--progress会在 stderr 按行输出进度 JSON（如{"phase": "comfy", "prompt_id": "...", "status": "running"}），方便脚本实时展示状态。

关键参数速查

与可视化工作流页的关系

实验命令走的是"终端编排"路线，而 Modly 桌面端本身也提供可视化工作流编排：在Workflows页把Image → Generate Mesh → Add to Scene用连线串起来即可（实现见 WorkflowsPage.tsx）。两者的分工是：

• 可视化画布：适合手工搭建、调试单个流水线，运行前会自动做连线校验，非法图不会直接丢弃当前视图；
• experimental 命令：适合把 ComfyUI 生态里现成的文生图/图生 3D 工作流"外包"出去，由 Modly 只负责它最擅长的本地图生 3D 与导出，天然适合批量与 Agent 自动化。

相关回归测试可参考 test_agent.py，其中对 ComfyUI 历史输出被 mock 成直接产出资产的场景做了断言，能帮你理解 JSON 返回结构。

常见问题排查

小结

Modly 的 ComfyUI 联动属于experimental 实验能力，刻意与正式的health / model / workflow-run / capability / process-run契约分离——好处是你既能安心用正式命令做日常图生 3D，又可以把 ComfyUI 的丰富节点生态当作"外部预处理/出模引擎"，两条路线共用同一套 JSON 输出风格。上手顺序建议：先health体检 → 用comfy-image单测 ComfyUI 侧 → 再上generate-from-workflow跑完整链路。

【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modly