铸想 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 管的是軟體本身）。

铸想 ForgeForm