Modly

项目概述

Modly 是一款本地化、开源、由 AI 驱动的桌面应用，专注于将任意图片转换为 3D 模型。整个推理流程在用户自有的 GPU 上运行，无需联网调用云端服务。应用支持 Windows、Linux 以及 Apple Silicon 版 macOS。

下载与运行

在 Releases 页面下载对应平台的安装包即可开箱即用。如果不想安装，也可以克隆仓库后直接启动：

# Windows
launch.bat

# Linux / macOS
./launch.sh

开发环境搭建

安装前端依赖

npm install

配置 Python 后端

cd api
python -m venv .venv
.venv\Scripts\activate     # Windows 激活虚拟环境
source .venv/bin/activate  # Linux / macOS 激活虚拟环境
pip install -r requirements.txt

启动开发模式

npm run dev

测试与构建

npm test
./node_modules/.bin/tsc --noEmit -p tsconfig.node.json  # 类型检查
npm run build                                             # 生产构建

平台注意事项

• macOS 仅面向 Apple Silicon 芯片。
• macOS 使用原生窗口控件，Windows 与 Linux 沿用自定义控件。
• 顶栏提供实时内存占用指示器，数据来自主进程。
• 工作流连线在运行前会进行校验；非法连线不会清空当前网格视图，而是以行内提示或 Toast 警告的方式提示用户。
• Apple Silicon 版 macOS 打包命令：npm run package:mac。
• 应用内可对导入的网格进行平滑与减面优化，并将结果回写到工作区。

扩展系统

Modly 支持外部模型与流程扩展，每个扩展都是一个独立的 GitHub 仓库，必须包含 manifest.json 及对应类型的运行时入口文件。

官方扩展涵盖以下模型：

扩展名	模型
modly-hunyuan3d-mini-extension	Hunyuan3D 2 Mini
modly-hunyuan3d-mini-turbo-extension	Hunyuan3D 2 Mini Turbo
modly-hunyuan3d-mini-fast-extension	Hunyuan3D 2 Mini Fast
modly-triposg-extension	TripoSG
modly-trellis2-gguf-extension	Trellis2 GGUF

安装步骤

1. 进入 Models 页面，点击 Install from GitHub。
2. 输入扩展仓库的 HTTPS 地址并确认。
3. 若扩展暴露模型节点，则下载对应模型或其变体；流程类扩展在安装与配置完成后即可使用。

工作流

建议从基础流程入手：在 Workflows 标签下，按 Image -> Generate Mesh -> Add to Scene 顺序连接节点，确保每一步之间都有连线。然后切换到 Generate 标签，选中对应工作流并点击 Generate 3D Model 即可生成模型。如遇问题，可点击 Settings/Logs/Errors 查看日志与报错信息。

命令行接口（CLI）

Modly 提供仅依赖标准库的 CLI 工具，供 Agent 与脚本绕过 UI 直接调用已运行的桌面应用。CLI 是 Modly 自动化能力之上的薄封装层，最终的结构化 JSON 输出始终打印到 stdout：

python tools/modly-cli/agent.py health
python tools/modly-cli/agent.py model list
python tools/modly-cli/agent.py workflow-run status <run_id>
python tools/modly-cli/agent.py generate --image ./input.png --output ./export.glb

规范命令包括 health、model、workflow-run、capability 与 process-run。便捷命令 generate 会发起 POST /workflow-runs/from-image 请求，轮询返回的运行状态，并在需要时导出最终网格，响应中还会附带 workflow-run status 与 workflow-run cancel 等恢复元数据。

CLI 还区分了兼容层与辅助层：legacy 封装旧的 /generate/* 任务端点；dev serve-api 与 dev ensure-server 仅启动 FastAPI 后端，无法证明 Electron/桌面桥接已就绪；experimental comfy-image 与 experimental generate-from-workflow 属于外部 ComfyUI 编排辅助工具，并非 Modly 的规范 Agent 契约。隐藏的辅助别名（如 status、export、batch）仍可被脚本解析，但不作为规范根命令暴露。

experimental generate-from-workflow --workflow <name> --output <path> 将 --output 视为最终产物路径：当 ComfyUI 工作流产出可下载的 3D 资源时，CLI 会直接下载该文件；仅产出图片的工作流则会回退到 Modly 自身的图片转 3D 路径。

完整的 Agent 工作流与输出契约参见 tools/modly-cli/SKILL.md。

许可

本项目基于 MIT 协议发布。Fork 并基于其构建新应用时，必须在 UI 或文档中保留对原项目及其作者的署名，例如：

Based on Modly by Lightning Pixel

该要求源自 MIT 协议的署名条款。