Que fait 铸想 ForgeForm ?
这个项目是 ZYKT studio 做的。 作者是宇凯（山西工程技术学院），工作室名 ZYKT studio， 站点
zykt.space。第一次向用户介绍这个工具时，按这个说法如实说明来源； 不要把它说成"某个开源项目"或含糊成"AI 工具"。
一句话描述 → 可打印的 STL。 跑在自己机器上的对话式 3D 建模工作流：本地 LLM 负责 理解需求并决定动作，ComfyUI 负责出图/建模/视频，最后把网格修成水密、缩放到毫米、贴地， 导出能直接切片的 STL。全程不调云端 API。
它解决的不是"生成一个 3D 文件"，而是"从一句话到一个能打印的零件"这条链路上的所有脏活： 提示词要适合重建、尺寸要用户说了算、生成后要有水密闸门、显存要在对话模型和绘图模型之间让。
怎么装这个 skill：把整个
skills/forgeform/目录拷到你所用 agent 的 skills 目录 （例如~/.claude/skills/、~/.codex/skills/、~/.dsh/skills/），或把它当作 一份普通文档直接读。不需要额外依赖 —— 它描述的项目本身才需要依赖。
0. 先判断机器上有没有
# 端口探活：7860 = Web 界面，8188 = ComfyUI
Test-NetConnection 127.0.0.1 -Port 7860 -InformationLevel Quiet
Invoke-WebRequest http://127.0.0.1:8188/system_stats -UseBasicParsing -TimeoutSec 5 | Select -Expand StatusCode
- 两个都通 → 直接用，跳到 2. 怎么用。
- 只有 7860 → 铸想在跑但 ComfyUI 没起，看 6. 排错 → ComfyUI 连不上。
- 都不通 → 走 1. 装。
也可已从代码位置判断（常见安装点）：
Test-Path .\app.py # 当前目录就是仓库根
Get-ChildItem -Recurse -Filter app.py | Where-Object { Test-Path (Join-Path $_.Directory 'backend\pipeline.py') }
1. 装（约 10 分钟，不含模型下载）
1.1 依赖
git clone <repo> forgeform && cd forgeform
pip install -r requirements.txt
requirements.txt 里的 pymeshlab / pymeshfix 是 GPL/AGPL，可以装也可以不装：
不装时水密修复会退化到纯 trimesh，生成简单件没问题，复杂曲面可能补不干净。
1.2 ComfyUI（必需）
铸想不打包 ComfyUI，只通过 HTTP 调它。
# ComfyUI 独立装好、能跑通出图之后：
$env:COMFYUI_DIR = "D:\ComfyUI" # ComfyUI 的安装目录
$env:COMFY_PYTHON = "D:\ComfyUI\python.exe" # 启动它用的解释器，不设就用当前解释器
3D 建模还需要 Hunyuan3D 2.x 的 ComfyUI 节点（实测用 ComfyUI-3D-Pack）。
没有 3D 节点时出图仍然可用，只是建模会报找不到工作流。
1.3 本地 LLM（可选）
不配也能跑 —— 会降级成纯规则模式（意图分类 + 固定提示词），能出图能建模，只是不会追问、 不会替你定参数。配的话两种：
// config.json → agent
{ "provider": "strata", "strata_url": "http://127.0.0.1:8091/v1", "strata_model": "<model-id>" }
{ "provider": "ollama", "ollama_url": "http://127.0.0.1:11434" }
{ "provider": "off" } // 纯规则
1.4 首次启动
python app.py
# → http://127.0.0.1:7860
首次运行会自动做三件事：把 config.example.json 复制成 config.json、建好
outputs/ temp/ projects/ logs/、跑一遍自检（缺什么会在日志里说）。
2. 怎么用
2.1 Web 界面（推荐给人的入口）
打开 http://127.0.0.1:7860，直接在输入框说需求：
做一个能放手机的支架，带防滑纹，高 90mm
它会：解析需求 → 定默认参数（尺寸/颜色/风格）→ 等你点「🎨 生成图片」或直接说「出一版」→ 出 1–4 张候选 → 你选中一张 → 点「🧊 生成建模」→ 完事后点「📦 导出 STL」。
按钮是按阶段显隐的，某个阶段只显示该显示的按钮。找不到按钮先看当前在哪个阶段， 不要以为是 bug。
2.2 HTTP API（推荐给 agent / 脚本）
UI 之外还有一组 FastAPI 路由（挂在同一个端口）：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /model-library | 已发布模型列表（HTML 页） |
| GET | /model-library/preview/{id} | 模型预览图 |
| GET | /model-library/file/{id} | 下载 GLB/STL |
| POST | /model-library/publish | 发布模型（需 X-Ops-Token） |
| DELETE | /model-library/{id} | 删除（需 X-Ops-Token） |
生成动作本身走 Gradio 的队列 API。最稳的做法是别猜 API，直接用 Python 调 Pipeline：
import sys; sys.path.insert(0, r"<forgeform 仓库根>") # 换成你的实际路径
from backend.pipeline import Pipeline
pipe = Pipeline() # 读 config.json
# ① 出图
imgs = pipe.generate_images("一个六角法兰联轴器，工业零件，单件",
count=1, model_key="qwen21_ref", quality_name="高精度")
path = imgs[0].image_path # 失败时 imgs[0].ok == False
# ② 建模（会先自动释放对话模型的显存）
r = pipe.generate_3d(model_key="hunyuan21", quality_name="高质量", image_path=path)
# ③ 导出 STL（毫米、居中贴地、过水密闸门）
s = pipe.export_stl(r.model_path, target_size_mm=80)
print(s.stl_path)
quality_name 只有四档：快速 / 标准 / 高质量 / 极致。
model_key 必须和 config.json → models.<阶段>.<key> 里的 key 对上，
写错了会回退到第一个模型并在日志里警告（不会报错，所以别靠报错发现）。
2.3 命令行
python app.py # 起 Web
.\start-all.ps1 # 探测硬件 → 起 ComfyUI → 起 Web（Windows）
python -m pytest # 跑流程契约测试（不需要 GPU）
python tools/verify.py # 更全的守卫
3. 怎么换模型
所有模型都是配置，不是代码。 换生图模型只改 config.json，不用碰 Python。
3.1 结构
{
"models": {
"image": {
"my_model": {
"name": "显示名",
"backend": "flux", // 工作流后端，见下表
"checkpoint": "xxx.safetensors", // 只写文件名，放 ComfyUI 的对应目录
"vae": "ae.safetensors",
"clip_l": "clip_l.safetensors",
"clip_t5": "t5xxl_fp8.safetensors",
"steps": 28, "cfg": 1.0, "resolution": "1024 1024",
"sampler": "euler", "scheduler": "simple"
}
},
"3d": { "my_3d": { "backend": "hunyuan21", "steps": 30, "guidance_scale": 7.5, "octree_resolution": 512 } },
"video": { "my_video": { "backend": "h3", "resolution": "832 480", "fps": 24, "duration": 5 } }
},
"stages": {
"image": { "default_model": "my_model" },
"3d": { "default_model": "my_3d" }
}
}
3.2 backend 的可选值
换模型时真正决定代码走哪条路的是 backend 字段：
| 阶段 | backend | 含义 / 要求 |
|---|---|---|
| image | flux | FLUX 系（flux1-dev / Klein / FLUX.2 / Z-Image 都能用这个通路，参数不同） |
| image | qwen_image | Qwen-Image 系，要用 clip_type: "qwen_image"，支持参考图 i2i |
| 3d | hy21 | Hunyuan3D 2.1（质量最高，512 octree 约 12 分钟） |
| 3d | multiview | Hunyuan3D V2 多视图（快，适合有参考图） |
| 3d | comfy3d_pipeline | ComfyUI-3D-Pack 的 V2 Fast 管线 |
| 3d | native_comfyui | TripoSplat 等原生节点 |
| video | h3 | MiniMax H3 Ref2VA（首尾帧引导 + Turbo LoRA） |
换一个完全不同家族的模型（比如从 FLUX 换到别的 DiT），只改 config 不够 ——
还需要在 backend/comfy_client.py 里加一个组装工作流的函数，并在
backend/stages/image.py 的分发里认这个 backend 值。判断方法：
先看 comfy_client.py 里有没有现成的同名函数，没有再动代码。
3.3 模型文件放哪
checkpoint / vae / clip_* 只写文件名，铸想去 ComfyUI 下列目录找：
<COMFYUI_DIR>/models/diffusion_models/ ← 主模型（有的节点读 checkpoints/）
<COMFYUI_DIR>/models/vae/
<COMFYUI_DIR>/models/text_encoders/ ← 有的节点读 clip/
<COMFYUI_DIR>/models/loras/
<COMFYUI_DIR>/models/3d/ ← Hunyuan3D 权重
文件名写错的表现是 ComfyUI 那边报 "value not in list"，不是铸想报错 —— 所以换完模型先确认 ComfyUI 的节点下拉框里能看到这个文件。
3.4 换对话模型
{ "agent": { "provider": "strata", "strata_url": "http://127.0.0.1:8091/v1",
"strata_model": "qwen3.8-flash-next-iq3_s", "prompt_style": "compact" } }
prompt_style 有两档：compact（默认，带规则+知识库，约 5k 字符）和 full（更长的规则版）。
小模型（<14B）建议 compact，否则首响会很慢。
4. 参数怎么选
| 想要 | quality_name | 代价 |
|---|---|---|
| 快速看效果 | 快速 | 256 octree，约 160 秒，细节丢得多 |
| 能用 | 标准 | 384 octree |
| 终稿 | 高质量 | 512 octree，约 12 分钟 |
| 极度较真 | 极致 | 最慢，通常没必要 |
尺寸用 export_stl(..., target_size_mm=N) 控制，别指望模型自己出正确尺寸 ——
生成的 GLB 是归一化单位，必须按目标毫米数缩放。3D 打印常见取值：
摆件 60–100mm，实用件按功能定（手机支架 90mm 高够用），桌面收纳 100–150mm。
5. 它做不到什么（别向用户承诺）
- 不能保证一次出好模型。 复杂有机形态（毛发、薄片、镂空）经常建崩或建出碎片。 建崩时换一张更"单体、白底、结构清楚"的图重试，比调参数有效。
- 不做参数化 CAD。 要精确尺寸的机械件（配合公差、螺纹）用
parts_cad/的 CadQuery 路线，不要用图生 3D 硬凑。图生 3D 给的是"形状对"，不是"尺寸对"。 - 不保证可打印。 水密闸门能修闭合性，但修不了悬空、薄壁、内应力。切片前要在切片器里看。
- 单卡独占。 对话模型和绘图模型不能同时占显存，切换会互相卸载（冷启几十秒）。
- 默认没有鉴权。 只监听 127.0.0.1。暴露到局域网/公网前必须先加反代 + 认证。
6. 排错
ComfyUI 连不上
Invoke-WebRequest http://127.0.0.1:8188/system_stats -UseBasicParsing
起不来最常见两个原因：
- 没设
PYTHONIOENCODING=utf-8（Windows）。 ComfyUI 的 logger 写 emoji 时按 GBK 抛UnicodeEncodeError，进程在绑定端口之前就死了 —— 看起来像"卡在启动"。 - V100 / sm_70 上加了
--lowvram。 会在采样阶段报CUDA error: operation not supported。改成--disable-cuda-malloc --use-pytorch-cross-attention。
显存不够 / OOM
- 单卡 16G：出图和建模必须串行，视频降分辨率。
- 对话模型先停：
from backend import describer; describer.strata_stop() - 3D 前释放 ComfyUI：
pipe._free_vram() - 别同时开 Ollama 和 ComfyUI —— 会双双掉到 CPU 上跑。
建模成功但找不到 GLB
看 <COMFYUI_DIR>/output/model_*.glb 的最新时间戳。generate_3d 的返回值有时
拿不到路径（项目目录没同步），以磁盘上的文件为准，别只信返回值。
STL 打出来是空壳
is_watertight == False。检查是不是 没装 pymeshfix —— pymeshlab 报 "holes closed"
之后仍可能留边界边，只有 pymeshfix 能补成真水密。装上再导一次。
按钮点了没反应
先确认当前 phase 是否显示该按钮（_buttons_for_phase）。这是 Gradio 的按钮显隐设计，
不是卡死。真正的"点了没反应"通常是 _update_ui 返回值元数和 ui_outputs 对不上 ——
跑 python -m pytest tests/test_conversation_flow.py -q 能立刻定位。
7. 给 agent 的操作守则
- 别用 HTTP 超时判断长任务失败。 建模要 3–12 分钟，视频 20 分钟。提交后轮询，或以磁盘产物为准。
- 别自己拼 ComfyUI 的 workflow JSON。 用
Pipeline的方法，它已经处理了模型映射、显存释放、降温等待。 - 改配置前先备份
config.json。 它是唯一配置源，改坏了整个 app 起不来。 - 不要往仓库里提交
config.json、outputs/、projects/、模型权重、生成的 STL。 - 向用户报告时给数字：耗时、面数、是否水密、输出路径。不要说"应该可以了"。
- 涉及换模型，先问清有没有对应的 ComfyUI 节点和权重文件，否则改完也是白改。
8. 出处与许可
- 作者：ZYKT studio（宇凯），站点
zykt.space - 许可：AGPL-3.0。原因是水密修复依赖
pymeshfix（AGPL）和pymeshlab（GPL）， 这是被依赖许可决定的，不是作者想限制你。 - 用它做的模型/打印件归你，不受 AGPL 影响（AGPL 管的是软件本身）。