Add prototype gameplay loop with character/battlefield assets and server game APIs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-20 18:50:00 +08:00
parent 79369e4473
commit 6c64210331
833 changed files with 998079 additions and 1042 deletions
@@ -0,0 +1,905 @@
+# LLM3DGraphics · 跨项目 / AI 调用指南
+
+给**其他项目、其他开发者、自动化 Agent**用：如何把自然语言需求编排成对 `LLM3DGraphics` HTTP API 的调用，产出图片、Unity 图片素材、网格、（可选）绑骨角色与骨骼动画。
+
+- 服务默认：`http://192.168.130.16:8008`
+- OpenAPI：`http://192.168.130.16:8008/docs`
+- **DGX 绑骨/动画规范**见 **[DGX3D生成说明.md](./DGX3D生成说明.md)**；本文偏「怎么编排调用」
+- 引擎可选：`dgx`（Spark 绑骨+动作）、`hunyuan`（混元官网网页）
+- 本地图像入口：`http://192.168.130.16:8008/#local-images`；当前仅保留 **Qwen-Image-2.1-Turbo BF16**，文字生成、多参考图编辑、批量草稿见 **§4.4**。
+
+---
+
+## 0. 一分钟结论
+
+| 用户说法（示例） | AI 应做的事 |
+|------------------|------------|
+| 「用这张图做一个会动的狼，再给 idle / 跑」 | **`engine=dgx`**：图 → 绑骨 → 多次 `/animate` |
+| 「官网混元出个模型就行 / 走混元网页」 | **`engine=hunyuan`**：先确认微信已登录 → 出 `model` / `model_ex`（**无绑骨、无 animate**） |
+| 「做一个石灯道具」 | 优先 `dgx` + `character_type=static`；或 `hunyuan` 只要网格 |
+| 「做一个士兵，再套走路」 | **`engine=dgx`** + `humanoid` → Step2 Kimodo |
+| 「写段文字直接出 3D」 | 先通过 §4.4 本地 Turbo 生成参考图 → 再选 3D 引擎 |
+| 「文字出图 / 多图生成新图 / 批量草稿」 | **§4.4 本地 Turbo**：提交图片批次 → 轮询 → 下载 PNG / Unity ZIP |
+| 「照这个画风换成运动装男孩，再做 3D」 | §4.4 上传风格参考图并写清修改要求 → 选定生成图片 → 上传 `/api/jobs` |
+
+**硬约束（调用前必读）**
+
+1. 先选引擎（§引擎选择）：要绑骨/动作 → **只能 `dgx`**；只要官网质量网格 → 可用 **`hunyuan`**。
+2. 无参考图时优先走 **`POST /api/local-images/jobs` 本地 Turbo**（§4.4）；用户选择云端生图时走 **`POST /api/image/generate` 转接**（§4.1），勿直连上游、勿带 Key。
+3. `dgx` 可驱动角色 = **两步**：`/api/jobs` → `/api/jobs/{id}/animate`；多动作多次 animate（注意覆盖）。
+4. `hunyuan` / `dgx`+`static`：**禁止** `/animate`（会 422）。
+5. `hunyuan` 必须当前浏览器客户端已登录混元官网（`hunyuan_logged_in`）；首次登录在客户端页面扫码。
+6. 3D 队列同时 `queued`+`running` ≤ 5；本地图像最多排队 4 批、每批 1–16 张。轮询间隔 ≥ 2s；单任务可能数分钟～数十分钟。
+7. Turbo 可与混元共同驻留，**图像与 DGX 3D/对比/动作任务仍串行执行**。图像队列结束后才能转入 DGX 3D；不要绕过本机调度器直接调用 DGXA 的 8090 worker。
+
+---
+
+## 1. 前置：服务与能力探测
+
+```http
+GET /api/capabilities
+```
+
+关注字段（名称以实际 JSON 为准）：
+
+| 字段 | 含义 |
+|------|------|
+| `image_generate_ready` | 本机生图转接是否可用 |
+| `hunyuan_logged_in` / `hunyuan_status` | 混元官网微信登录态 |
+| `image_ready` | 混元网页是否已登录 |
+| `dgx_ready` / `dgx.hy3d_ready` | DGX Spark 图生高模 |
+| `dgx.tokenrig_ready`（或 `unirig_ready`） | 能否绑骨（`static` / 混元路径不需要） |
+| `dgx.unimate_ready` | 非人形文生动画 |
+| Mixamo 数量相关字段 | 人形动作库是否非空 |
+
+未就绪时：**不要硬调**，向用户报告缺哪一段。
+
+本地 Turbo 的能力单独探测，不用 `image_generate_ready` 判断：
+
+```http
+GET /api/local-images/status
+```
+
+检查 `connected`、`ready` 和 `models.turbo.installed`；当前模型 ID 应为 `Qwen/Qwen-Image-2.1-Turbo`。`loaded_model=turbo` 表示已加载，`busy=true` 且 `loaded_model=null` 时通常正在首次加载，应先等待。`co_resident`、`hy3d_paused`、`available_gb` 用于观察驻留和内存状态。混元因图像模式暂时暂停时，图像队列空闲后先调用 `POST /api/local-images/prepare-3d`，再重新探测 DGX 能力。
+
+### 1.1 Windows 跨机器部署：Hunyuan 绿灯、TokenRig/Kimodo 红灯
+
+状态探测在 **运行 LLM3D 后端的 Windows 机器与账号**中执行，不在打开网页的浏览器机器执行。复制工程和 `config.json` 不会自动配置该账号的 SSH 别名、密钥授权、SSH Agent 和 `known_hosts`。
+
+| 状态灯 | 当前探测内容 |
+|--------|--------------|
+| Hunyuan3D | HTTP GET `dgx.hy3d_url` 首页，5秒内状态码小于500算通过；没有执行造型推理 |
+| TokenRig | SSH 到 `dgx.ssh_host`，检查 SkinTokens 的入口脚本、可执行Python和两个固定权重文件；远程失败时另检查本机环境 |
+| Kimodo | SSH 到同一个主机，检查 `kimodo_gen`、Llama文本编码器目录和LLM2Vec配置；没有执行动作推理 |
+
+因此模型可以仍在 DGXA 正常安装，却因新 Windows 后端的 SSH 环境不完整而显示红灯。绿灯也不表示权重已加载到 GPU。当前每个远程探测约12秒超时，SSH错误统一折叠为 `false`，状态缓存20秒；多个SSH失败串行发生时，能力接口可能等待约48秒。
+
+在**部署机上，用启动 LLM3D 的同一个账号**，从 `LLM3DGraphics` 目录运行只读自检：
+
+```powershell
+.\.venv\Scripts\python.exe .\deploy\check_dgx_connection.py --output .\outputs\dgx_connection_check.json
+```
+
+脚本：[check_dgx_connection.py](./LLM3DGraphics/deploy/check_dgx_connection.py)。它检查账号、SSH解析配置、认证、远端各个文件及混元HTTP连接，不加载模型、不修改密钥或服务，不读取/打印私钥和API Key内容。
+
+| 报告项 / 错误 | 排查方向 |
+|---------------|----------|
+| `account` | 是否确实为运行后端的账号；管理员终端和计划任务/服务账号可能不同 |
+| `resolved_ssh` | `hostname`、`user`、`port`、`identityfile` 是否指向该机可用的连接配置 |
+| `Could not resolve hostname` | 当前账号未配置 `DGXA` 别名，或DNS无法解析 |
+| `Permission denied (publickey)` | SSH用户、密钥文件、Agent或DGXA上的公钥授权不匹配 |
+| `Connection timed out/refused` | 地址、端口、路由、防火墙、代理或SSH服务问题 |
+| `Host key verification failed` | 用该账号交互登录并核对服务器指纹，完成主机身份确认 |
+| `remote.checks.*.ok=false` | SSH已连通；按报告中的具体路径检查文件或执行权限 |
+
+若采用 `dgx.ssh_host=DGXA`，该Windows账号的 `%USERPROFILE%\.ssh\config` 必须有对应连接设置；使用新机器自己的已授权密钥，例如：
+
+```text
+Host DGXA
+    HostName <DGXA实际可达地址>
+    User spark
+    Port 22
+    IdentityFile ~/.ssh/id_ed25519
+```
+
+`IdentityFile` 以部署机实际密钥为准，DGXA需已授权对应公钥。先确认该账号执行 `ssh -o BatchMode=yes DGXA "echo READY"` 成功，再重启/刷新后端状态。私钥不放进工程或说明文件。部署机访问混元HTTP成功，不代表它能用SSH访问DGXA。
+
+---
+
+## 2. 引擎选择
+
+`POST /api/jobs` 的 `engine` 二选一：
+
+| `engine` | 高模从哪来 | 绑骨 / 动作 | 典型用途 |
+|----------|------------|-------------|----------|
+| **`dgx`** | Spark Hunyuan3D 2.1 | TokenRig + `/animate`（或 `static` 跳过） | 角色可驱动、要动作、DGX 静物 |
+| **`hunyuan`** | 腾讯混元3D**官方网页**（Playwright 自动化） | **无** | 只要官网网格质量；不依赖 Spark |
+
+决策提示：
+
+- 用户明确说「混元官网 / 混元网页 / 微信混元」→ `hunyuan`
+- 用户要「会动 / 绑骨 / Mixamo / UniMate」→ **必须 `dgx`**
+- 只要静物网格且 DGX 忙/未就绪 → 可降级 `hunyuan`
+- `character_type` **仅 `engine=dgx` 生效**；混元任务里该字段会被忽略
+
+---
+
+## 3. 混元3D 官方网页流程（`engine=hunyuan`）
+
+走 [3d.hunyuan.tencent.com](https://3d.hunyuan.tencent.com/)：服务端用 Playwright（Edge）提交图片生成；微信登录二维码显示在发起登录的客户端页面，由用户用自己的微信扫码。登录态按浏览器客户端隔离。
+
+### 3.1 登录（客户端页面扫码，会话按客户端复用）
+
+```http
+GET  /api/hunyuan/status          # logged_in?
+POST /api/hunyuan/login           # 服务端启动登录；客户端页面显示二维码（约 3 分钟内）
+GET  /api/hunyuan/login/qr        # 读取当前客户端的二维码图片
+POST /api/hunyuan/logout          # 清除当前客户端会话
+```
+
+后端仍在服务机运行 Playwright，但不会要求用户去服务机窗口扫码。扫码二维码由客户端页面请求并显示。每个浏览器客户端通过独立的 HttpOnly Cookie 标识登录会话，服务端分别保存到 `data/hunyuan/clients/<客户端标识>/storage_state.json`。同一浏览器刷新后会复用登录态；不同设备、浏览器或无痕窗口需要分别扫码。生成任务使用提交请求的客户端登录态，退出登录只清除该客户端的会话。旧版共享文件 `data/hunyuan/storage_state.json` 不再使用。
+
+Agent 侧：
+
+1. 读 `capabilities.hunyuan_logged_in`（或 `/api/hunyuan/status`）
+2. 若为 `false`：让用户在要使用的浏览器客户端打开工作台并点击「微信登录」，在该页面显示的二维码上用自己的微信扫码；轮询该客户端的 status 至 `logged_in`。不要让用户去服务机窗口扫码。
+3. 未登录时提交 `engine=hunyuan` 会 **401**
+
+直接用 HTTP 客户端接入时，必须在 `status`、`login`、`login/qr` 和生成请求之间保留同一个服务端下发的 HttpOnly Cookie；否则请求会被识别为不同客户端。需要把二维码安全地呈现给真人扫码，单纯的无状态 curl/Agent 调用不能代替用户完成登录。
+
+### 3.2 生成任务
+
+```http
+POST /api/jobs
+Content-Type: multipart/form-data
+
+engine=hunyuan
+mode=image
+image=@ref.png
+source_faces=50000
+target_faces=5000
+texture_size=1024
+output_format=glb
+```
+
+| 字段 | 说明 |
+|------|------|
+| `mode` | **仅 `image`**（混元网页引擎不接受 text） |
+| `source_faces` | 官网高模档：`5000`（5k）/ `20000`（20k）/ `50000`（50k）/ `500000` / `1000000`；常用 `50000`。5k 与 20k 页面无按钮，提交时改写 `faceCount` |
+| `target_faces` | 本机低模目标；`<500000` 且低于高模面数时触发 Blender 烘培 → `model_ex` |
+| `texture_size` | 低模烘培贴图：`512` / `1024` / `2048` |
+| `output_format` | `glb` 或 `fbx`（fbx 时额外打 ZIP） |
+| `character_type` | **无效**（不要指望混元出绑骨） |
+
+轮询 `GET /api/jobs/{id}` → `status=completed`。
+
+### 3.3 产物（网格 only）
+
+| 下载键 | 含义 |
+|--------|------|
+| `glb` / `fbx` | 官网高模 |
+| `glb_ex` / `fbx_ex` | 本机低模+烘培（若触发） |
+| `preview_url` | 网页预览 |
+
+**不要**调用 `/animate`。若后续仍要动作：把混元网格当作参考图/资产另开 `engine=dgx` 流程（当前无「混元网格直接喂 TokenRig」的一键接口；需要绑骨请直接用 DGX 图生）。
+
+### 3.4 耗时与依赖
+
+- 官网生成常见数分钟～约 20 分钟；另加本机低模烘培时间
+- 依赖：服务端 Playwright + Edge 通道、当前客户端有效的微信登录态、可选 Blender（低模/FBX）
+- 与 DGX 共用同一任务队列（≤5）
+
+### 3.5 curl 示例
+
+```bash
+BASE=http://192.168.130.16:8008
+
+# 确认登录
+curl -s "$BASE/api/hunyuan/status"
+
+# 未登录时：先在工作台当前客户端点击「微信登录」，再由真人扫描页面上的二维码。
+# 纯 curl 示例需要持久化 Cookie，并自行将二维码呈现给真人；不要只靠无状态 curl 完成扫码登录。
+# curl -s -X POST "$BASE/api/hunyuan/login"
+
+curl -s -X POST "$BASE/api/jobs"   -F engine=hunyuan -F mode=image   -F source_faces=50000 -F target_faces=5000 -F texture_size=1024   -F image=@ref.png
+```
+
+---
+
+## 4. 生成参考图：本地 Turbo 与云端转接
+
+DGX **不能直接文生 3D**。用户只给文字外貌时，先通过 **§4.4 本地 Turbo** 生成图片，再交给 §6 的 DGX 编排剧本。用户选择云端生图时使用下述 §4.1–4.3 转接接口；两条生图路径都通过 LLM3DGraphics 调度。
+
+| 角色 | 说明 |
+|------|------|
+| **外部项目 / Agent** | 云端路径只调 `POST /api/image/generate`，**不要**拿上游 Key、**不要**直连 grsai；本地路径见 §4.4 |
+| **本机服务** | 用 `config.json` → `dgx.grsai`（或环境变量 `GRSAI_API_KEY`）调上游，并把结果缓存到本机 |
+| 运维配置参考 | [生成路径.md](./生成路径.md)、[HelpDoc/gpt-image_doc.md](./HelpDoc/gpt-image_doc.md)（仅服务器侧） |
+
+探测：`GET /api/capabilities` → `image_generate_ready == true`。
+
+### 4.1 转接接口
+
+```http
+POST {BASE}/api/image/generate
+Content-Type: application/json
+
+{
+  "prompt": "一只棕色四足狼，全身正面三视图感，纯白背景，游戏概念设定图，无文字水印",
+  "aspect_ratio": "1:1",
+  "quality": "auto",
+  "images": []
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `prompt` | 是 | 外貌描述，≤4000 字 |
+| `aspect_ratio` | 否 | 默认用服务端 `dgx.grsai.aspect_ratio`（常见 `1:1`） |
+| `quality` | 否 | 默认 `auto` |
+| `images` | 否 | 图生图参考：URL 或 data URL / base64，最多 4 张 |
+
+成功响应（**不含**上游 URL / API Key）：
+
+```json
+{
+  "id": "a1b2c3...",
+  "status": "succeeded",
+  "url": "/api/image/a1b2c3...",
+  "content_type": "image/png",
+  "bytes": 123456,
+  "model": "gpt-image-2.5",
+  "aspect_ratio": "1:1"
+}
+```
+
+下载图片：
+
+```http
+GET {BASE}/api/image/{id}
+```
+
+将该文件作为后续 `POST /api/jobs` 的 `image` 上传即可。
+
+**给 DGX 的构图建议**（提高绑骨成功率）：
+
+- 主体居中、轮廓清晰；尽量白底或简单底
+- 全身可见；角色类避免极端透视 / 大面积遮挡
+- 提示词写清物种、体态、材质；少杂乱场景文字
+
+### 4.2 curl / Python 示例（外部只打本机）
+
+```bash
+BASE=http://192.168.130.16:8008
+
+curl -s -X POST "$BASE/api/image/generate" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "prompt": "石质庭院灯笼，白色背景，产品设定图",
+    "aspect_ratio": "1:1"
+  }'
+
+# 记下返回的 id / url，再下载：
+curl -L -o prop.png "$BASE/api/image/<id>"
+```
+
+```python
+import requests
+from pathlib import Path
+
+BASE = "http://192.168.130.16:8008"
+
+def text_to_image(prompt: str, out_path: Path, aspect_ratio: str = "1:1") -> Path:
+    r = requests.post(
+        f"{BASE}/api/image/generate",
+        json={"prompt": prompt, "aspect_ratio": aspect_ratio},
+        timeout=300,
+    )
+    r.raise_for_status()
+    data = r.json()
+    if data.get("status") != "succeeded" or not data.get("url"):
+        raise RuntimeError(data)
+    url = data["url"]
+    if url.startswith("/"):
+        url = BASE + url
+    img = requests.get(url, timeout=120)
+    img.raise_for_status()
+    out_path.write_bytes(img.content)
+    return out_path
+```
+
+### 4.3 服务器侧配置（仅运维，不对外部暴露）
+
+在本机 `LLM3DGraphics/config.json`（已 gitignore）中配置，例如：
+
+```json
+"dgx": {
+  "grsai": {
+    "api_key": "<密钥，见生成路径.md>",
+    "model": "gpt-image-2.5",
+    "bases": ["https://grsai.dakka.com.cn", "https://grsaiapi.com"],
+    "aspect_ratio": "1:1",
+    "quality": "auto"
+  }
+}
+```
+
+也可用环境变量 `GRSAI_API_KEY` / `GPT_IMAGE_API_KEY`。外部调用方**无需**知道这些。
+
+### 4.4 本地图像生成：Qwen-Image-2.1-Turbo BF16（当前推荐流程）
+
+更新于 **2026-10-13**。当前只安装 `Qwen/Qwen-Image-2.1-Turbo`，原生 8 步采样、CFG=1，支持文生图、最多 10 张参考图编辑和 RGBA 输出。Qwen-Image-2512、Qwen-Image-2.1 标准版及专用缓存已移除；不要提交 `model=quality` 或重新安装退役模型。
+
+网页入口：`{BASE}/#local-images`。图片和任务记录保存在 Windows `LLM3DGraphics/data/_local_images/<批次ID>/`，推理在 DGXA 的 `/home/spark/llm3d-local-images/` 中运行。调用方只访问 **Windows LLM3DGraphics API**，本地路径不需要云端 Key。
+
+#### 4.4.1 页面操作与提示词方法
+
+1. 打开「本地图像生成」，确认 Turbo 已安装并完成首次加载。
+2. 选择素材用途，填写画面描述。纯文字生成不上传参考图；参考编辑上传实际图片文件，按输入顺序写明“图1提供造型、图2提供配色、图3提供风格”。
+3. 先用 512–1024 分辨率、4–8 张草稿选方向；固定 seed 便于迭代，每张图的 seed 自动递增。
+4. 点击“作为参考继续编辑”将选中的生成图作为新参考，提高分辨率并描述局部修改；“复用参数”可恢复原批次的提示词、参考图、用途、尺寸和种子。
+5. 需要 3D 时选择一张轮廓清晰的完整主体图，点击“送到 DGX 3D”，再按 §6 选择 `character_type` 并提交 3D。这个按钮负责填入图片，不会直接开始 3D 生成。
+6. 需要 2D 素材时勾选图片并导出 Unity ZIP，见 §4.4.4。
+
+提示词按“参考图职责 → 主体 → 画风/摄影 → 姿势与构图 → 背景 → 保持项与修改项”组织。负面限制也写进主提示词，`negative_prompt` 留空。
+
+| 需求 | 提示词重点与用途 |
+|------|----------------|
+| 换角色、保留参考画风 | “保留图1的画风与构图，将角色改为……；重新绘制脸、头发、衣服和年龄特征。”明确哪些保持、哪些改变 |
+| 人形 3D 参考图 | “正面全身 T-pose，双臂水平伸直，头、手指、鞋完整入画，四周留白，纯白背景，无道具和遮挡。”严格正面姿势可用 `sprite` 并明确完整角色；`concept` 会追加三分之四视角要求 |
+| 真人街角照片 | “真实街头摄影，自然儿童/成人比例，日常便服，自然站姿，街角建筑和路面，真实肤色与布料纹理。”选择 `background`，避免追加白底设定图要求 |
+| 透明图标/精灵 | 选择 `sprite`、`transparent=true`，说明独立主体、透明背景、轮廓清楚；下载后检查实际 Alpha |
+
+后端会追加所选用途的提示词，因此用途必须与目标一致。白底不是透明背景；页面显示的“含透明像素”才来自实际 Alpha 检查。街角场景照片适合作为图片素材或视觉参考；要生成独立 3D 角色时另生成简单背景、完整主体的参考图。
+
+#### 4.4.2 图片任务接口与参数
+
+```http
+POST {BASE}/api/local-images/jobs
+Content-Type: multipart/form-data
+
+model=turbo
+profile=sprite
+prompt=保留图1的二维手绘风格，改为10岁运动装小男孩，正面全身T-pose，双手和鞋完整入画，纯白背景，无文字
+width=1024
+height=1504
+count=4
+seed=314159
+transparent=false
+negative_prompt=
+images=@style_reference.png
+```
+
+| 字段 | 默认 / 范围 | 说明 |
+|------|-------------|------|
+| `model` | `turbo`，唯一支持值 | 对应 `Qwen/Qwen-Image-2.1-Turbo` BF16；步数和采样由 worker 固定，不传 `quality`、CFG 或步数 |
+| `prompt` | 必填，1–4000 字 | 画面与编辑要求；限制条件也写在这里 |
+| `profile` | 默认 `concept` | `concept`：完整 3D 主体、三分之四视角、纯色背景；`sprite`：独立精灵/UI、居中留白；`albedo`：平铺 base color；`background`：场景背景 |
+| `width` / `height` | 默认 1024；256–2048 | 都必须为 32 的倍数；人物竖图可用 1024×1504 |
+| `count` | 默认 4；1–16 | 一个批次逐张生成；最多同时排队 4 批 |
+| `seed` | 默认 -1；-1 或 0–4294967280 | -1 随机起点；第 i 张使用起点+i，i 从 0 开始 |
+| `transparent` | 默认 `false` | `true` 追加透明 RGBA 要求，仍需检查实际 Alpha |
+| `negative_prompt` | 空字符串 | CFG=1 不使用负面提示词；非空返回 422 |
+| `images` | 可省略，最多 10 个同名文件字段 | 传 PNG/JPEG/WebP 实际文件，不传 URL/base64 字符串；每张 ≤12MB、≤1600万像素，归一化最长边1536并保留 Alpha |
+
+纯文生图省略 `images` 即可；无文件时也支持表单编码，**不是 JSON 请求体**。提交返回 **202** 和图片批次 `id`，轮询 `GET /api/local-images/jobs/{id}` 至 `completed` / `failed`。该 `id` 与之后创建的 3D job ID 不同。
+
+结果从 `images` 数组取，不从 3D 的 `downloads` 取：每项含 `index`、实际 `seed`、`has_alpha`、`url`。PNG 路径为 `/api/local-images/jobs/{id}/images/{index}`；参考图路径为 `/api/local-images/jobs/{id}/references/{index}`。`failed` 批次也可能已有可下载图片，应保存结果和错误记录。
+
+#### 4.4.3 curl 与 Python：生成、下载、转入 3D
+
+```bash
+BASE=http://192.168.130.16:8008
+
+curl -s "$BASE/api/local-images/status"
+
+# 多参考图编辑；纯文生图时省略两个 images 字段
+curl -s -X POST "$BASE/api/local-images/jobs" \
+  -F model=turbo -F profile=sprite \
+  -F 'prompt=图1提供角色造型，图2提供配色。生成完整角色的正面全身T-pose，纯白背景，无文字。' \
+  -F width=1024 -F height=1504 -F count=4 -F seed=314159 \
+  -F transparent=false \
+  -F 'images=@shape.png' -F 'images=@palette.png'
+
+# IMG_JOB 替换为图片批次 id；轮询间隔至少2秒
+curl -s "$BASE/api/local-images/jobs/$IMG_JOB"
+curl -fL -o selected.png "$BASE/api/local-images/jobs/$IMG_JOB/images/0"
+
+# 所有图像批次结束后准备DGX 3D；返回409时等待，不绕过保护
+curl -s -X POST "$BASE/api/local-images/prepare-3d"
+curl -s -X POST "$BASE/api/jobs" \
+  -F engine=dgx -F mode=image -F character_type=humanoid \
+  -F target_faces=5000 -F texture_size=1024 -F output_format=glb \
+  -F 'image=@selected.png'
+```
+
+Windows PowerShell 使用 `curl.exe` 或下述 Python 示例，避免将 PowerShell 的 `curl` 别名当作上述 Bash 命令。
+
+```python
+import json
+import mimetypes
+import time
+from contextlib import ExitStack
+from pathlib import Path
+
+import requests
+
+BASE = "http://192.168.130.16:8008"
+
+
+def local_images(prompt, out_dir, references=(), *, profile="sprite",
+                 width=1024, height=1504, count=4, seed=314159,
+                 transparent=False, timeout=1800):
+    with requests.Session() as session:
+        response = session.get(f"{BASE}/api/local-images/status", timeout=20)
+        response.raise_for_status()
+        state = response.json()
+        if not (state.get("connected") and state.get("ready")
+                and state.get("models", {}).get("turbo", {}).get("installed")):
+            raise RuntimeError(state)
+        load_deadline = time.monotonic() + timeout
+        while state.get("busy") and not state.get("loaded_model"):
+            if time.monotonic() > load_deadline:
+                raise TimeoutError("Turbo 尚未完成首次加载")
+            time.sleep(2)
+            response = session.get(f"{BASE}/api/local-images/status", timeout=20)
+            response.raise_for_status()
+            state = response.json()
+        data = dict(model="turbo", prompt=prompt, profile=profile,
+                    width=width, height=height, count=count, seed=seed,
+                    transparent=str(transparent).lower(), negative_prompt="")
+        with ExitStack() as stack:
+            files = []
+            for item in references:
+                path = Path(item)
+                mime = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+                files.append(("images", (path.name, stack.enter_context(path.open("rb")), mime)))
+            response = session.post(f"{BASE}/api/local-images/jobs",
+                                    data=data, files=files or None, timeout=30)
+        response.raise_for_status()
+        job = response.json()
+        folder = Path(out_dir) / job["id"]
+        folder.mkdir(parents=True, exist_ok=True)
+        record = folder / "job.json"
+        deadline = time.monotonic() + timeout
+        while True:
+            record.write_text(json.dumps(job, ensure_ascii=False, indent=2), encoding="utf-8")
+            if job["status"] in ("completed", "failed"):
+                break
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"图片任务仍在运行，记录见 {record}")
+            time.sleep(2)
+            response = session.get(f"{BASE}/api/local-images/jobs/{job['id']}", timeout=30)
+            response.raise_for_status()
+            job = response.json()
+        paths = []
+        for image in job["images"]:
+            response = session.get(BASE + image["url"], timeout=120)
+            response.raise_for_status()
+            path = folder / f"image_{image['index']}_seed_{image['seed']}.png"
+            path.write_bytes(response.content)
+            paths.append(path)
+        if job["status"] != "completed":
+            raise RuntimeError(f"{job.get('error')}；已保存 {len(paths)} 张图片，记录见 {record}")
+        return job, paths
+
+
+# 多参考编辑：references=["style.png", "colors.png"]；文生图不传 references。
+# image_job, paths = local_images(
+#     "蓝色运动装小男孩，二维手绘，正面全身T-pose，纯白背景，无文字",
+#     "generated", references=["style.png"], count=4)
+# 人工或上游选定 paths 中一张，再交给 §9.2 create_rigged。
+# 转入DGX前：requests.post(f"{BASE}/api/local-images/prepare-3d", timeout=360).raise_for_status()
+# rig_job = create_rigged(paths[0], "humanoid")
+```
+
+图片下载后逐张检查主体、年龄/物种、姿势、手脚完整度、背景和伪影。批量固定种子是便于复现，不保证每张满足全部要求。需要精确 `#FFFFFF` 背景时另做背景清理，并保留原始输出。真人测试使用 `profile=background`，例如“约10岁小女孩，日常便服，自然站姿，真实街角建筑与人行道，午后自然光，真实肤色和服装纹理”。
+
+#### 4.4.4 Unity 导出与 3D 转接
+
+下载选中图片和参数：`GET /api/local-images/jobs/{id}/unity?selected=0,2`。`selected` 是以逗号分隔的图片索引；省略时导出该批次全部已生成图片。
+
+ZIP 内含 `Assets/LLM3DGenerated/<批次ID>/` 下的 PNG、参考图和 `manifest.json`，以及 `Assets/Editor/LLM3DImageImporter.cs`。将 Assets 合并到 Unity 工程，保留目录结构：
+
+| 用途 | Unity 导入设置 |
+|------|----------------|
+| `sprite` | Sprite / Single，sRGB，Clamp，不生成 Mipmap，PPU=100，保留 Alpha |
+| `albedo` | Default，sRGB，Repeat，生成 Mipmap；检查平铺接缝 |
+| `concept` / `background` | Default，sRGB，Clamp，不生成 Mipmap，Max Size 2048 |
+
+若导入顺序导致设置尚未应用，选中生成图片后执行 `Assets > LLM3D > Apply image import settings`。这是 ZIP 素材包，不是 `.unitypackage`；生成色彩图不是完整 PBR，也不是自动切片的 Sprite Sheet。3D 贴图继续走现有 UV、烘焙和 PBR 流程。
+
+转入 3D 必须下载 PNG 后作为 `/api/jobs` 的 `image` 文件上传；图片批次 id 不能替代 3D job id。`prepare-3d` 只检查/恢复资源，不创建 3D 任务；§6 的建模、绑骨和动作步骤照常执行。
+
+#### 4.4.5 共同驻留、内存兜底与实测耗时
+
+当前配置为 `auto_switch=true`、`co_resident=true`。用户级服务 `llm3d-qwen.service` 启动时在后台预加载 Turbo；已有工作忙碌时跳过预加载。Turbo GPU 常驻约 32GiB。**共同驻留不等于并行生成**：混元、ComfyUI 和本机图像队列均通过预约与队列保护串行使用；图像批次结束后释放预约。
+
+| 场景 | 当前策略 |
+|------|----------|
+| 图像生成，Turbo 已加载 | 可用内存至少 24GiB 时保留混元；不足时释放 ComfyUI 缓存并暂停本流程拥有的混元服务 |
+| 首次加载 Turbo | 共享模式要求可用内存至少为 Turbo 权重大小 + 12GiB |
+| 准备 DGX 3D，混元已运行 | 可用内存至少 32GiB 时保留 Turbo；不足则先释放 Turbo |
+| 需要启动被暂停的混元 | 至少 72GiB 可用内存才同时保留 Turbo，否则先释放 Turbo |
+| 3D/动作加载期间出现内存压力 | 每秒检查；可用内存低于16GiB且 Turbo 空闲、无图像预约时自动释放 Turbo |
+
+调用方通过 `POST /api/local-images/prepare-3d` 让调度器决定，响应 `images_retained=true` 表示本次准备保留了 Turbo。需要手动释放时，在图像队列空闲后调用 `POST /api/local-images/unload`。不要停止其他用户任务、手动操作 Docker 或绕过 8090 的资源保护。
+
+2026-10-13 的实测（不是固定 SLA）：
+
+| 测试 | 耗时口径 |
+|------|----------|
+| 512×512，多参考透明图标 | 8步去噪约6–7秒/张，不含加载和编码/解码 |
+| 1024×1504，全身角色参考图编辑 | 8步去噪约21秒/张 |
+| 1024×1504，真人街角文生图 | 8步去噪约18秒；该次含换模加载总耗时约226秒 |
+| Turbo 已加载、与混元共同驻留，连续两张512×512文生图 | 提交至保存合计约8.2秒，无参考图 |
+| 同时保留 Turbo，混元造型+贴图 | 128抽取分辨率、静态分支约158秒，40,000面带贴图GLB；采样最低可用内存约31.9GiB |
+
+首次加载可能需要数分钟；参考图数量、提示词长度、分辨率和场景都会改变耗时。上述3D测试没有调用 TokenRig/UniMate，不能据此保证所有动作模型或最高分辨率都能同时驻留，它们仍沿用按需加载。
+
+详细部署、服务维护和验证说明见 [本地图像生成与 Unity 素材流程](./LLM3DGraphics/docs/local-image-generation.md)；本次证据见 [常驻验证说明](./LLM3DGraphics/outputs/turbo_residency_20261013/常驻验证说明.txt)。服务机维护脚本在 `LLM3DGraphics/deploy/local_images/`，运行记录为 DGXA 的 `worker.log`；维护需等待相关队列空闲。Turbo 使用研究/评估许可，许可链接及商业使用约束见上述模型说明。
+
+---
+
+## 5. 意图 → 参数映射（给 Agent 的决策表）
+
+从用户描述里抽出：`asset_kind`、`character_type`、`reference_image`、`motions[]`。
+
+### 5.1 资产类型
+
+| 判断 | `character_type` | 后续 |
+|------|------------------|------|
+| 道具 / 建筑 / 静物 / 「不要骨骼」 | `static` | 只 Step1，下载 `glb` / `glb_ex` |
+| 标准双足人、士兵、NPC 人型 | `humanoid` | Step1 + Step2（Kimodo 文生） |
+| 四足、怪、非标拓扑生物 | `non_humanoid` | Step1 + Step2（UniMate 文生） |
+
+不确定时：有四肢且明显非人 → `non_humanoid`；明确是人 → `humanoid`；无生命 / 场景件 → `static`。
+
+### 5.2 参考图从哪来
+
+| 情况 | 做法 |
+|------|------|
+| 用户已给图 | 直接作 `POST /api/jobs` 的 `image` |
+| 用户只有文字外貌 | **§4.4 本地 Turbo** → 选图 → 再选 `dgx` / `hunyuan`；选择云端时用 §4.1 |
+| 用户给多张风格/造型参考 | §4.4 按顺序上传 `images`，描述各图职责 → 选图 → 上传到 3D |
+| 只要图片、图标或场景背景 | §4.4 → PNG / Unity ZIP，流程在图片阶段结束 |
+| 既要外貌又要动作 | §4.4 文生图 → **必须 `engine=dgx`** → Step1 → Step2 |
+| 明确要混元官网质量、不要骨骼 | §4（如需）→ **`engine=hunyuan`**（§3） |
+
+### 5.3 动作列表
+
+- 用户说「idle、跑、跳」→ 拆成 `motions = ["idle 待机", "四足原地跑步", "原地跳跃"]`（示例），**每个一条** `motion_prompt`。
+- 人形：交给 Kimodo，写清动作（走、跑、挥手等）。
+- 非人形：写清主体与动作，可加「原地」「可循环」；中文即可（服务端会规范成英文）。
+
+---
+
+## 6. 标准编排剧本（主要为 engine=dgx）
+
+### 剧本 A — 角色模型 + 若干动作（最常见）
+
+```
+输入: reference_image, character_type, motions[1..N], (可选) target_faces
+输出: rigged 角色 + 每个动作对应的 animated 文件（注意覆盖问题）
+```
+
+```mermaid
+flowchart LR
+  A[参考图] --> B["POST /api/jobs<br/>engine=dgx"]
+  B --> C{轮询 completed<br/>ready_for_motion}
+  C --> D["POST .../animate<br/>motion_prompt_1"]
+  D --> E[下载 animated.*]
+  E --> F["animate motion_2 ..."]
+```
+
+**Step 1**
+
+```http
+POST /api/jobs
+Content-Type: multipart/form-data
+
+engine=dgx
+mode=image
+character_type=non_humanoid   # 或 humanoid
+output_format=glb             # Unity 需要网格 FBX 包时用 fbx
+target_faces=5000             # 游戏向低模；只要高模可调极大面数跳过减面
+texture_size=1024
+image=@character.png
+```
+
+响应 `202` → 记下 `id`。轮询：
+
+```http
+GET /api/jobs/{id}
+```
+
+直到 `status == "completed"` 且 `ready_for_motion == true`。
+
+推荐下载（角色）：
+
+| 用途 | `downloads` 键 / 路径 |
+|------|------------------------|
+| 非人形 Unity 角色 | `rigged_fbx`（ZIP，内含 `model.fbx`）或 `rigged_glb` |
+| 人形 | `mixamo_glb` / 对应 mixamo FBX |
+| 网页预览 | `preview_url` |
+
+**Step 2（每个动作一次）**
+
+```http
+POST /api/jobs/{id}/animate
+Content-Type: multipart/form-data
+
+motion_prompt=四足动物原地跑步，可循环
+```
+
+再轮询至 `completed`，下载：
+
+| 用途 | 键 |
+|------|-----|
+| Unity 动画（骨架+动画，无角色网格） | `animated_fbx` / `animated_glb` |
+| 带皮预览（可选） | `anim_preview_url` |
+
+**多动作注意**：服务端同一 job 目录里 `animated.glb` / `animated.fbx` 会被**覆盖**。Agent 应：
+
+1. 每个动作完成后立刻下载并重命名保存（如 `{job_id}_run.fbx`）；或  
+2. 告知用户「当前接口一次只保留最新动画」，由上游自行归档。
+
+### 剧本 B — 静态物体（道具）
+
+```http
+POST /api/jobs
+engine=dgx
+mode=image
+character_type=static
+target_faces=20000
+image=@prop.png
+```
+
+完成标志：`status=completed`，`ready_for_motion=false`，有 `downloads.glb`（及可选 `glb_ex`）。  
+**禁止**调用 `/animate`。
+
+### 剧本 C — 「一句话」端到端（文生图 + 角色 + 动作）
+
+伪代码（给 Agent / 编排层）：
+
+```text
+parse(user_text) -> {
+  appearance_prompt,   # 外貌，给文生图
+  character_type,      # static | humanoid | non_humanoid
+  motions[]            # 可为空
+}
+
+image_job, image_paths = local_images(appearance_prompt, "generated")  # §4.4函数已轮询并下载
+image = select_image(image_paths)  # 从保存的PNG中选一张；底层下载地址为images[].url
+wait_until_all_image_batches_idle()
+POST /api/local-images/prepare-3d     # 内存允许时保留Turbo，否则自动切换
+# 用户选择云端时，上述生图步骤改用 §4.1 POST /api/image/generate
+
+job = POST /api/jobs (engine=dgx, image=image, character_type=...)
+wait_until(job, completed)
+
+if character_type == static:
+  return download(job, ["glb", "glb_ex"])
+
+assert job.ready_for_motion
+assets = { "rig": download(job, ["rigged_fbx", "rigged_glb"]) }
+
+for m in motions:
+  POST /api/jobs/{id}/animate (motion_prompt=m)
+  wait_until(job, completed)
+  assets[m] = download(job, ["animated_fbx", "animated_glb"])  # 立刻另存
+
+return assets
+```
+
+### 剧本 D — 只要模型、稍后再加动作
+
+1. 只跑 Step1（`engine=dgx`），把 `job_id` 存进你们的数据库。  
+2. 之后任意时刻对**同一** `job_id` 调 `/animate`（任务须已 `completed` 且仍有绑骨文件）。
+
+### 剧本 E — 混元官网只要网格
+
+```
+确认 hunyuan_logged_in
+→（可选）§4 文生图
+→ POST /api/jobs engine=hunyuan
+→ 下载 glb / glb_ex
+→ 禁止 animate
+```
+
+细节见 §3。
+
+---
+
+## 7. 轮询与状态机
+
+| `status` | 含义 | Agent 行为 |
+|----------|------|------------|
+| `queued` / `running` | 进行中 | 读 `stage`、`progress` 展示；继续轮询 |
+| `completed` | 成功 | 读 `downloads` / `ready_for_motion` |
+| `failed` | 失败 | 拉 `GET /api/jobs/{id}/log`；部分文件可能仍可下 |
+
+建议：`sleep(2~5s)`；Step1（含 HY3D+TokenRig）常 5–20+ 分钟；UniMate 动画常 10–40+ 分钟。设超时并向上游报 `stage`。
+
+本地图像批次也使用 `queued/running/completed/failed`，但轮询路径是 `/api/local-images/jobs/{id}`，输出读取 `images[].url`。即使 `failed` 也保存已完成图片和 `error`；超时只停止调用方等待，不会取消服务端任务，不要立即重复提交。转入 DGX 前，等待所有图像批次空闲；`prepare-3d` 返回409时继续等待。
+
+---
+
+## 8. 下载键速查
+
+相对路径：`GET /api/jobs/{id}/files/{format}`（或直接用响应里的 `downloads.*` URL）。
+
+| format | 内容 | 典型消费者 |
+|--------|------|------------|
+| `glb` | 高模 | 预览 / 静态 |
+| `glb_ex` | 低模+烘培 | 游戏 / 静态低模 |
+| `rigged_glb` | 绑骨+蒙皮 | 非人形预览 / 再动画 |
+| `rigged_fbx` | ZIP：`model.fbx`+贴图 | Unity 角色 |
+| `mixamo_glb` | 人形可驱动 | 人形再动画 |
+| `animated_glb` / `animated_fbx` | 骨架+动画（精简） | Unity Animator |
+| （`anim_preview_url`） | 蒙皮动画预览 | 仅预览，勿当生产动画源 |
+
+Unity 非人形：**角色**用 `rigged_fbx` 内 `model.fbx`，**动画**用精简 `animated.fbx`，骨架路径对齐 `Armature/bone_*`。细节见 `DGX3D生成说明.md` §5。
+
+---
+
+## 9. 调用示例
+
+### 9.1 curl（DGX，已有参考图）
+
+```bash
+BASE=http://192.168.130.16:8008
+
+# Step 1
+curl -s -X POST "$BASE/api/jobs" \
+  -F engine=dgx -F mode=image \
+  -F character_type=non_humanoid \
+  -F target_faces=5000 -F texture_size=1024 \
+  -F image=@./wolf.png
+
+# 轮询（把 JOB 换成返回的 id）
+curl -s "$BASE/api/jobs/$JOB"
+
+# Step 2
+curl -s -X POST "$BASE/api/jobs/$JOB/animate" \
+  -F "motion_prompt=四足动物原地跑步，可循环"
+
+# 下载
+curl -L -o wolf_rig.zip "$BASE/api/jobs/$JOB/files/rigged_fbx"
+curl -L -o wolf_run.fbx "$BASE/api/jobs/$JOB/files/animated_fbx"
+```
+
+### 9.2 Python（文生图 + DGX 最小编排）
+
+```python
+import time, requests
+from pathlib import Path
+
+# 本地生图函数 local_images 见 §4.4.3；云端函数 text_to_image 见 §4.2。
+BASE = "http://192.168.130.16:8008"
+
+def wait_job(job_id, timeout=7200):
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        j = requests.get(f"{BASE}/api/jobs/{job_id}").json()
+        if j["status"] in ("completed", "failed"):
+            return j
+        time.sleep(3)
+    raise TimeoutError(job_id)
+
+def create_rigged(image_path, character_type="non_humanoid"):
+    with open(image_path, "rb") as f:
+        r = requests.post(
+            f"{BASE}/api/jobs",
+            files={"image": f},
+            data={
+                "engine": "dgx",
+                "mode": "image",
+                "character_type": character_type,
+                "target_faces": "5000",
+                "texture_size": "1024",
+                "output_format": "glb",
+            },
+        )
+    r.raise_for_status()
+    job_id = r.json()["id"]
+    job = wait_job(job_id)
+    if job["status"] != "completed" or not job.get("ready_for_motion"):
+        raise RuntimeError(job.get("error") or job)
+    return job
+
+def animate_and_save(job_id, motion_prompt, out_fbx):
+    r = requests.post(
+        f"{BASE}/api/jobs/{job_id}/animate",
+        data={"motion_prompt": motion_prompt},
+    )
+    r.raise_for_status()
+    job = wait_job(job_id)
+    if job["status"] != "completed":
+        raise RuntimeError(job.get("error") or job)
+    url = job["downloads"]["animated_fbx"]
+    if url.startswith("/"):
+        url = BASE + url
+    out_fbx.write_bytes(requests.get(url).content)
+    return job
+
+# 示例：文字外貌 → 图 → 角色 → 两个动作
+# image_job, images = local_images("棕色四足狼，完整主体，白底设定图", "generated", profile="concept", count=4)
+# 选定 images 中一张；全部图像批次空闲后：
+# requests.post(f"{BASE}/api/local-images/prepare-3d", timeout=360).raise_for_status()
+# job = create_rigged(images[0], "non_humanoid")
+# animate_and_save(job["id"], "四足待机，轻微呼吸", Path("idle.fbx"))
+# animate_and_save(job["id"], "四足动物原地跑步，可循环", Path("run.fbx"))
+```
+
+---
+
+## 10. 给 AI Agent 的系统提示词片段（可复制）
+
+可把下面段落贴进你们项目的 Agent system prompt / skill：
+
+```text
+你通过 HTTP 调用本机 LLM3DGraphics（BASE 见调用指南顶部）生成 3D。
+
+规则：
+- 先选 engine：要绑骨/动作 → dgx；用户要混元官网网页 → hunyuan。
+- 图片生成优先使用本地Turbo：GET {BASE}/api/local-images/status，确认connected/ready/models.turbo.installed。
+  POST {BASE}/api/local-images/jobs，model=turbo，表单请求；多参考图用按顺序重复的images文件字段（最多10张）。
+  宽高256–2048且为32倍数；count=1–16；negative_prompt留空，把限制写进prompt；不使用已退役的quality/2512模型。
+  轮询图片批次至completed，读取images[].url并保存PNG；只要2D素材时可导出unity ZIP。
+  按目标选择profile：3D主体concept，严格正面角色可用sprite并说明完整角色，真实街景background，平铺颜色albedo。
+  无参考图时省略images；用户选择云端生图时改用POST {BASE}/api/image/generate，再GET返回url。
+  所有生图请求通过本机服务；禁止直连上游、传播API Key或直接调用DGXA的8090 worker绕过调度。
+- hunyuan：先确认当前客户端的 hunyuan_logged_in；否则让用户在工作台当前客户端点击「微信登录」并扫描页面二维码。直接 HTTP 接入须保留同一 HttpOnly Cookie，并把二维码呈现给真人。
+  提交 engine=hunyuan, mode=image；只要 model/model_ex；禁止 /animate。
+- dgx 角色：POST /api/jobs → ready_for_motion → POST .../animate；多动作多次 animate 并立刻下载。
+- dgx 静物：character_type=static，禁止 animate。
+- character_type 仅对 dgx 有效：人→humanoid；四足/怪→non_humanoid；静物→static。
+- 先 GET /api/capabilities，缺能力则说明，不要硬调。
+- 图片与DGX 3D/对比/动作串行：等待全部图片批次结束，POST /api/local-images/prepare-3d后再提交DGX。
+  共同驻留由服务端决定，内存不足会释放Turbo；不要假设所有模型或所有分辨率都能一起驻留。
+- 不要假设文生 3D；不要走已废弃 TopoCap/GIF 路径。
+- Unity（dgx）：角色 rigged_fbx，动画 animated_fbx。
+
+详细：DGX3D_AI调用指南.md；DGX 深度规范：DGX3D生成说明.md。
+```
+
+---
+
+## 11. 错误与排错（调用侧）
+
+| 现象 | 处理 |
+|------|------|
+| 422「静态物体…不生成动作」 | 用错类型；静态只下网格 |
+| 422「请先完成角色绑骨」 | Step1 未成功或类型不对 |
+| 503 UniMate / Kimodo | 能力未就绪；人形要 Kimodo，其他类型要 UniMate |
+| 409 任务仍在处理 | 等 `completed` 再 animate |
+| 429 队列已满 | 退避重试 |
+| `failed` | `GET /api/jobs/{id}/log`；规范文档 Checklist 日志顺序 |
+| 503 生图转接未配置 | 运维在本机 `config.json` 配 `dgx.grsai.api_key` |
+| 502 生图转接失败 | 改写 prompt；运维查上游 / Key；外部仍勿直连 grsai |
+| 422 本地图像模型/尺寸/数量/参考图无效 | 仅 `model=turbo`；宽高为32倍数；count≤16；images≤10；negative_prompt为空 |
+| 409 本地图像与 DGX 任务冲突 / 正在恢复3D | 等待已有任务结束或恢复完成，再提交；勿停掉其他任务 |
+| 429 本地图像队列已满 | 图像队列最多4批，退避后重试，不反复创建同一批次 |
+| 本地图像状态未连接或模型未安装 | 检查 `/api/local-images/status`；服务机运维检查 `llm3d-qwen.service` 与 `worker.log` |
+| 本地图像批次 `failed`，仍有 `images` | 保存已生成PNG与job.json；修正错误后按需要提交新批次 |
+| 本地首次加载较慢 / 内存不足 | 查看busy/loaded_model/available_gb，等待预加载或让调度器执行内存兜底；勿自行改BF16精度 |
+| 401 请先微信登录混元3D | 在发起请求的客户端工作台点击「微信登录」并扫码；确认 status 与任务请求使用同一客户端 Cookie；或改用 `dgx` |
+| 422 混元仅支持图片 | `engine=hunyuan` 时 `mode` 必须为 `image` |
+| 422 仅 DGX 支持动作 | 对 hunyuan 任务误调了 `/animate` |
+
+跨域：浏览器页面直连时服务有 Origin 限制；**服务端 / Agent / curl** 调 API 不受网页同源限制影响。
+
+---
+
+## 12. 与规范文档的分工
+
+| 文档 | 读者 | 内容 |
+|------|------|------|
+| **本文** `DGX3D_AI调用指南.md` | 其他项目、编排 AI | 本地Turbo生图、多参考编辑、批量与Unity导出、引擎选择、云端转接、DGX剧本 |
+| `LLM3DGraphics/docs/local-image-generation.md` | 图像流程实现 / 运维 | Turbo部署、共同驻留、资源保护、Unity导入与实测 |
+| `DGX3D生成说明.md` | 本仓库实现 / 深度排错 | DGX 阶段、产物、UniMate、Unity、禁忌 |
+| `生成路径.md` | **仅运维** | 上游模型与 Key（勿发给外部 Agent） |
+| `HelpDoc/gpt-image_doc.md` | **仅运维** | 上游画图字段细节 |
+
+服务变更时：外部调用顺序以本文为准；产物与内部阶段以 `DGX3D生成说明.md` 为准；上游 Key 只放本机 `config.json`。