PrintGuard_Aholo 0.5.0__tar.gz

printguard_aholo-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PrintGuard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

printguard_aholo-0.5.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: PrintGuard_Aholo
+Version: 0.5.0
+Summary: PrintGuard —— FDM 打印件的生成→可制造性校核→修复→交付（Lux3D + 几何工具链），MCP Server 形态
+License: MIT
+Project-URL: Repository, https://github.com/milu348/PrintGuard_Aholo
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: trimesh
+Requires-Dist: manifold3d
+Requires-Dist: scikit-image
+Requires-Dist: requests
+Requires-Dist: matplotlib
+Requires-Dist: lxml
+Requires-Dist: pillow
+Requires-Dist: uvicorn
+Requires-Dist: mcp<2,>=1
+Provides-Extra: aholo
+Requires-Dist: manycore-aholo-sdk-lux3d; extra == "aholo"
+Requires-Dist: manycore-aholo-sdk-asset; extra == "aholo"
+Dynamic: license-file
+
+# PrintGuard
+
+面向 FDM 打印件的 **"生成 → 可制造性校核 → 修复 → 交付"** MCP 能力包。
+Lux3D 生成模型 + 确定性几何工具链（水密/悬垂/壁厚检测，体素重构/增厚/自动摆向），
+交付可直接切片的 3MF、诊断报告图（缺陷着色+中文指标）与旋转预览 GIF。
+
+> 运行环境：**Linux / WSL**（Python ≥ 3.11，推荐 3.13）。不再兼容 Windows。
+
+## 交付示例
+
+九尾狐手办（anime / G1-Turbo / 130mm，fast 档端到端 ~2min）：风险 D→S，水密，悬垂 16%→5%。
+诊断图左=缺陷着色 3D（灰=正常 · 蓝=贴床 · 红=悬垂 · ◆=最薄壁），右=中文指标与修复步骤；GIF 为对话内旋转预览。
+
+![诊断报告图](docs/img/diagnostic_sheet.png)
+
+![旋转预览](docs/img/turntable.gif)
+
+## MCP 接入（Server Config）
+
+两种接入方式，工具完全一致：**方式一**把服务跑在你本机；**方式二**免安装，直接用
+魔搭社区的免费算力（2vCPU/8GB）。
+
+### 方式一：本机运行（stdio，uvx 自动安装）
+
+在支持 MCP 的客户端（Claude Desktop / Cursor / OpenCode 等）配置中添加以下 JSON
+（需先安装 [uv](https://docs.astral.sh/uv/)：`curl -LsSf https://astral.sh/uv/install.sh | sh`，
+首次调用时 uv 自动拉取并安装本仓库）：
+
+```text
+{
+  "mcpServers": {
+    "printguard": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/milu348/PrintGuard_Aholo", "printguard-mcp"],
+      "env": {
+        "AHOLO_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+- 环境变量 `AHOLO_API_KEY` 可留空：检测/修复已有模型完全不需要 key；仅生成新模型需要
+  （免费申请：labs.aholo3d.cn），也可在每次工具调用的 `api_key` 参数中提供
+- 产物以本地绝对路径交付
+
+### 方式二：云端托管（Streamable HTTP，免安装）
+
+服务运行在魔搭社区创空间上，客户端只需配置远程地址：
+
+```json
+{
+  "mcpServers": {
+    "printguard": {
+      "type": "streamable_http",
+      "url": "https://studio-miluzzz-printguard.api-inference.modelscope.net/mcp",
+      "headers": {
+        "Authorization": "Bearer <你的 ModelScope 访问令牌>"
+      }
+    }
+  }
+}
+```
+
+- 需要一个 ModelScope 访问令牌（免费）：modelscope.cn → 访问令牌 页面获取，
+  填入上方 `Authorization` 请求头
+- 产物为签名限时下载链接；生成新模型同样在工具参数 `api_key` 中自带 AHOLO key
+
+接入后对 Agent 说：**"帮我做一个能打印的手机支架，高 10 厘米"**。
+
+## 两种质量档
+
+| | `fast`（默认） | `fine` |
+|---|---|---|
+| 适用 | 结构件/支架 | **手办/细节件** |
+| 配方 | G1-Turbo + 100k + 自适应 pitch | G1 + 300k + 0.3mm 细 pitch |
+| 耗时 | ~2 分钟 | ~10 分钟 |
+
+Agent 会按场景自动选择；交付物为 `printable.3mf` + `turntable.gif`（渲染预览；诊断图作为内部诊断件供 agent 讲解）。
+
+## 本地开发（Linux / WSL）
+
+```bash
+uv venv --python 3.13 .venv          # 或 python3 -m venv .venv（需 3.11+）
+.venv/bin/python -m pip install -e . # 或 uv pip install -e .
+.venv/bin/python printguard.py selftest        # 8 个检查用例
+.venv/bin/python pipeline.py "测试" --height-mm 100
+.venv/bin/python mcp_server.py                 # MCP stdio（本机桌面宿主）
+.venv/bin/python mcp_server.py --transport streamable-http --port 8000   # MCP HTTP（云端托管；魔搭创空间用 7860）
+```
+
+协议回归（Linux 版）：
+
+```bash
+.venv/bin/python test_mcp_client.py   # stdio 形态：instructions / enum / 错误语义
+.venv/bin/python test_mcp_http.py     # HTTP 形态：MCP over HTTP + 签名下载链接
+```
+
+详见 `PrintGuard.md`（技术方案）、`docs/deploy-modelscope.md`（云端部署）与
+`.dsh/skills/printguard/SKILL.md`（Agent 编排规约）。

printguard_aholo-0.5.0/PrintGuard_Aholo.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: PrintGuard_Aholo
+Version: 0.5.0
+Summary: PrintGuard —— FDM 打印件的生成→可制造性校核→修复→交付（Lux3D + 几何工具链），MCP Server 形态
+License: MIT
+Project-URL: Repository, https://github.com/milu348/PrintGuard_Aholo
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: trimesh
+Requires-Dist: manifold3d
+Requires-Dist: scikit-image
+Requires-Dist: requests
+Requires-Dist: matplotlib
+Requires-Dist: lxml
+Requires-Dist: pillow
+Requires-Dist: uvicorn
+Requires-Dist: mcp<2,>=1
+Provides-Extra: aholo
+Requires-Dist: manycore-aholo-sdk-lux3d; extra == "aholo"
+Requires-Dist: manycore-aholo-sdk-asset; extra == "aholo"
+Dynamic: license-file
+
+# PrintGuard
+
+面向 FDM 打印件的 **"生成 → 可制造性校核 → 修复 → 交付"** MCP 能力包。
+Lux3D 生成模型 + 确定性几何工具链（水密/悬垂/壁厚检测，体素重构/增厚/自动摆向），
+交付可直接切片的 3MF、诊断报告图（缺陷着色+中文指标）与旋转预览 GIF。
+
+> 运行环境：**Linux / WSL**（Python ≥ 3.11，推荐 3.13）。不再兼容 Windows。
+
+## 交付示例
+
+九尾狐手办（anime / G1-Turbo / 130mm，fast 档端到端 ~2min）：风险 D→S，水密，悬垂 16%→5%。
+诊断图左=缺陷着色 3D（灰=正常 · 蓝=贴床 · 红=悬垂 · ◆=最薄壁），右=中文指标与修复步骤；GIF 为对话内旋转预览。
+
+![诊断报告图](docs/img/diagnostic_sheet.png)
+
+![旋转预览](docs/img/turntable.gif)
+
+## MCP 接入（Server Config）
+
+两种接入方式，工具完全一致：**方式一**把服务跑在你本机；**方式二**免安装，直接用
+魔搭社区的免费算力（2vCPU/8GB）。
+
+### 方式一：本机运行（stdio，uvx 自动安装）
+
+在支持 MCP 的客户端（Claude Desktop / Cursor / OpenCode 等）配置中添加以下 JSON
+（需先安装 [uv](https://docs.astral.sh/uv/)：`curl -LsSf https://astral.sh/uv/install.sh | sh`，
+首次调用时 uv 自动拉取并安装本仓库）：
+
+```text
+{
+  "mcpServers": {
+    "printguard": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/milu348/PrintGuard_Aholo", "printguard-mcp"],
+      "env": {
+        "AHOLO_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+- 环境变量 `AHOLO_API_KEY` 可留空：检测/修复已有模型完全不需要 key；仅生成新模型需要
+  （免费申请：labs.aholo3d.cn），也可在每次工具调用的 `api_key` 参数中提供
+- 产物以本地绝对路径交付
+
+### 方式二：云端托管（Streamable HTTP，免安装）
+
+服务运行在魔搭社区创空间上，客户端只需配置远程地址：
+
+```json
+{
+  "mcpServers": {
+    "printguard": {
+      "type": "streamable_http",
+      "url": "https://studio-miluzzz-printguard.api-inference.modelscope.net/mcp",
+      "headers": {
+        "Authorization": "Bearer <你的 ModelScope 访问令牌>"
+      }
+    }
+  }
+}
+```
+
+- 需要一个 ModelScope 访问令牌（免费）：modelscope.cn → 访问令牌 页面获取，
+  填入上方 `Authorization` 请求头
+- 产物为签名限时下载链接；生成新模型同样在工具参数 `api_key` 中自带 AHOLO key
+
+接入后对 Agent 说：**"帮我做一个能打印的手机支架，高 10 厘米"**。
+
+## 两种质量档
+
+| | `fast`（默认） | `fine` |
+|---|---|---|
+| 适用 | 结构件/支架 | **手办/细节件** |
+| 配方 | G1-Turbo + 100k + 自适应 pitch | G1 + 300k + 0.3mm 细 pitch |
+| 耗时 | ~2 分钟 | ~10 分钟 |
+
+Agent 会按场景自动选择；交付物为 `printable.3mf` + `turntable.gif`（渲染预览；诊断图作为内部诊断件供 agent 讲解）。
+
+## 本地开发（Linux / WSL）
+
+```bash
+uv venv --python 3.13 .venv          # 或 python3 -m venv .venv（需 3.11+）
+.venv/bin/python -m pip install -e . # 或 uv pip install -e .
+.venv/bin/python printguard.py selftest        # 8 个检查用例
+.venv/bin/python pipeline.py "测试" --height-mm 100
+.venv/bin/python mcp_server.py                 # MCP stdio（本机桌面宿主）
+.venv/bin/python mcp_server.py --transport streamable-http --port 8000   # MCP HTTP（云端托管；魔搭创空间用 7860）
+```
+
+协议回归（Linux 版）：
+
+```bash
+.venv/bin/python test_mcp_client.py   # stdio 形态：instructions / enum / 错误语义
+.venv/bin/python test_mcp_http.py     # HTTP 形态：MCP over HTTP + 签名下载链接
+```
+
+详见 `PrintGuard.md`（技术方案）、`docs/deploy-modelscope.md`（云端部署）与
+`.dsh/skills/printguard/SKILL.md`（Agent 编排规约）。

printguard_aholo-0.5.0/PrintGuard_Aholo.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+lux3d_client.py
+mcp_server.py
+pipeline.py
+printguard.py
+pyproject.toml
+PrintGuard_Aholo.egg-info/PKG-INFO
+PrintGuard_Aholo.egg-info/SOURCES.txt
+PrintGuard_Aholo.egg-info/dependency_links.txt
+PrintGuard_Aholo.egg-info/entry_points.txt
+PrintGuard_Aholo.egg-info/requires.txt
+PrintGuard_Aholo.egg-info/top_level.txt

printguard_aholo-0.5.0/PrintGuard_Aholo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

printguard_aholo-0.5.0/PrintGuard_Aholo.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+printguard-aholo = mcp_server:main
+printguard-mcp = mcp_server:main

printguard_aholo-0.5.0/PrintGuard_Aholo.egg-info/requires.txt

@@ -0,0 +1,15 @@
+numpy
+scipy
+trimesh
+manifold3d
+scikit-image
+requests
+matplotlib
+lxml
+pillow
+uvicorn
+mcp<2,>=1
+
+[aholo]
+manycore-aholo-sdk-lux3d
+manycore-aholo-sdk-asset

printguard_aholo-0.5.0/PrintGuard_Aholo.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+lux3d_client
+mcp_server
+pipeline
+printguard

printguard_aholo-0.5.0/README.md

@@ -0,0 +1,100 @@
+# PrintGuard
+
+面向 FDM 打印件的 **"生成 → 可制造性校核 → 修复 → 交付"** MCP 能力包。
+Lux3D 生成模型 + 确定性几何工具链（水密/悬垂/壁厚检测，体素重构/增厚/自动摆向），
+交付可直接切片的 3MF、诊断报告图（缺陷着色+中文指标）与旋转预览 GIF。
+
+> 运行环境：**Linux / WSL**（Python ≥ 3.11，推荐 3.13）。不再兼容 Windows。
+
+## 交付示例
+
+九尾狐手办（anime / G1-Turbo / 130mm，fast 档端到端 ~2min）：风险 D→S，水密，悬垂 16%→5%。
+诊断图左=缺陷着色 3D（灰=正常 · 蓝=贴床 · 红=悬垂 · ◆=最薄壁），右=中文指标与修复步骤；GIF 为对话内旋转预览。
+
+![诊断报告图](docs/img/diagnostic_sheet.png)
+
+![旋转预览](docs/img/turntable.gif)
+
+## MCP 接入（Server Config）
+
+两种接入方式，工具完全一致：**方式一**把服务跑在你本机；**方式二**免安装，直接用
+魔搭社区的免费算力（2vCPU/8GB）。
+
+### 方式一：本机运行（stdio，uvx 自动安装）
+
+在支持 MCP 的客户端（Claude Desktop / Cursor / OpenCode 等）配置中添加以下 JSON
+（需先安装 [uv](https://docs.astral.sh/uv/)：`curl -LsSf https://astral.sh/uv/install.sh | sh`，
+首次调用时 uv 自动拉取并安装本仓库）：
+
+```text
+{
+  "mcpServers": {
+    "printguard": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/milu348/PrintGuard_Aholo", "printguard-mcp"],
+      "env": {
+        "AHOLO_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+- 环境变量 `AHOLO_API_KEY` 可留空：检测/修复已有模型完全不需要 key；仅生成新模型需要
+  （免费申请：labs.aholo3d.cn），也可在每次工具调用的 `api_key` 参数中提供
+- 产物以本地绝对路径交付
+
+### 方式二：云端托管（Streamable HTTP，免安装）
+
+服务运行在魔搭社区创空间上，客户端只需配置远程地址：
+
+```json
+{
+  "mcpServers": {
+    "printguard": {
+      "type": "streamable_http",
+      "url": "https://studio-miluzzz-printguard.api-inference.modelscope.net/mcp",
+      "headers": {
+        "Authorization": "Bearer <你的 ModelScope 访问令牌>"
+      }
+    }
+  }
+}
+```
+
+- 需要一个 ModelScope 访问令牌（免费）：modelscope.cn → 访问令牌 页面获取，
+  填入上方 `Authorization` 请求头
+- 产物为签名限时下载链接；生成新模型同样在工具参数 `api_key` 中自带 AHOLO key
+
+接入后对 Agent 说：**"帮我做一个能打印的手机支架，高 10 厘米"**。
+
+## 两种质量档
+
+| | `fast`（默认） | `fine` |
+|---|---|---|
+| 适用 | 结构件/支架 | **手办/细节件** |
+| 配方 | G1-Turbo + 100k + 自适应 pitch | G1 + 300k + 0.3mm 细 pitch |
+| 耗时 | ~2 分钟 | ~10 分钟 |
+
+Agent 会按场景自动选择；交付物为 `printable.3mf` + `turntable.gif`（渲染预览；诊断图作为内部诊断件供 agent 讲解）。
+
+## 本地开发（Linux / WSL）
+
+```bash
+uv venv --python 3.13 .venv          # 或 python3 -m venv .venv（需 3.11+）
+.venv/bin/python -m pip install -e . # 或 uv pip install -e .
+.venv/bin/python printguard.py selftest        # 8 个检查用例
+.venv/bin/python pipeline.py "测试" --height-mm 100
+.venv/bin/python mcp_server.py                 # MCP stdio（本机桌面宿主）
+.venv/bin/python mcp_server.py --transport streamable-http --port 8000   # MCP HTTP（云端托管；魔搭创空间用 7860）
+```
+
+协议回归（Linux 版）：
+
+```bash
+.venv/bin/python test_mcp_client.py   # stdio 形态：instructions / enum / 错误语义
+.venv/bin/python test_mcp_http.py     # HTTP 形态：MCP over HTTP + 签名下载链接
+```
+
+详见 `PrintGuard.md`（技术方案）、`docs/deploy-modelscope.md`（云端部署）与
+`.dsh/skills/printguard/SKILL.md`（Agent 编排规约）。

printguard_aholo-0.5.0/lux3d_client.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Aholo 开放平台 API 客户端：生成任务/轮询/下载、Asset 上传，
+以及概念图能力（schema 直译自官方 OpenAPI，已实测）。
+常规一条龙走 pipeline.py；概念图可独立导入调用（与生成同串行规则）。"""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import requests
+
+BASE = "https://api.aholo3d.cn"
+KEY_FILE = "secrets.local.json"
+OUT_DIR = Path("output/smoke")
+POLL_SEC = 15
+TIMEOUT_SEC = 20 * 60
+
+
+def load_key(explicit: str | None = None) -> str:
+    """取 API Key，优先级：显式入参（公网部署由用户填写）> 环境变量 > 本地 secrets.local.json。
+
+    公网部署（魔搭等托管平台）里不能把 key 写进镜像/环境变量，必须由调用方
+    通过工具参数 api_key 传入；本地开发仍可用环境变量或 secrets.local.json。"""
+    import os
+    for cand in (explicit, os.environ.get("AHOLO_API_KEY", "")):
+        s = (cand or "").strip()
+        if s:
+            return s
+    p = Path(KEY_FILE)
+    if p.exists():
+        raw = p.read_text(encoding="utf-8").strip()
+        s = json.loads(raw) if raw.startswith('"') else raw
+        if ":" in s:
+            s = s.split(":", 1)[1].strip()
+        if s:
+            return s
+    raise SystemExit(
+        "缺少 AHOLO API Key：公网调用请在工具参数 api_key 传入，"
+        "本地可设置环境变量 AHOLO_API_KEY 或填 secrets.local.json")
+
+
+def create_task(key: str, prompt: str, version: str = "G1-Turbo",
+                face_count: int = 100000, style: str | None = None,
+                output_format: list | None = None,
+                image: str | None = None) -> int:
+    body = {
+        "prompt": prompt,
+        "version": version,
+        "faceCount": face_count,
+        "outputFormat": output_format or ["glb"],
+        "enablePbr": False,       # 白模（仅 G1-Turbo 生效）
+        "aiPredictSize": False,   # 尺寸策略：本地确定性缩放
+    }
+    if style:
+        body["style"] = style
+    if image:  # 可选参考图（图+文同时输入）：URL 直传，本地文件先走 Asset 上传
+        body["img"] = image if image.startswith(("http://", "https://")) else upload_mesh(image, key=key)
+    for attempt in range(3):
+        r = requests.post(f"{BASE}/lux3d/v1/generate/text-to-3d/task/create",
+                          headers={"Authorization": key}, json=body, timeout=30)
+        d = r.json()
+        if d.get("c") == "0":
+            return int(d["d"])
+        code = str(d.get("c", ""))
+        print(f"[create] attempt{attempt} c={code} m={d.get('m')}", flush=True)
+        if "CONCURRENCY" in code:
+            time.sleep(30)
+            continue
+        if r.status_code >= 500:
+            time.sleep(10)
+            continue
+        raise SystemExit(f"create failed: {d}")
+    raise SystemExit("create: 重试耗尽")
+
+
+def poll_task(key: str, taskid: int) -> dict:
+    t0 = time.time()
+    last = None
+    while time.time() - t0 < TIMEOUT_SEC:
+        r = requests.get(f"{BASE}/lux3d/v1/generate/task/get",
+                         headers={"Authorization": key},
+                         params={"taskid": taskid}, timeout=30)
+        d = r.json()
+        if d.get("c") != "0":
+            print(f"[poll] c={d.get('c')} m={d.get('m')}", flush=True)
+            time.sleep(POLL_SEC)
+            continue
+        data = d["d"]
+        st = data["status"]
+        if st != last:
+            print(f"[poll] task={taskid} status={st} elapsed={time.time()-t0:.0f}s", flush=True)
+            last = st
+        if st in (3, 4, 6):
+            data["elapsed_sec"] = round(time.time() - t0)
+            return data
+        time.sleep(POLL_SEC)
+    raise SystemExit(f"task {taskid} 轮询超时")
+
+
+def download_glbs(outputs: list, name: str,
+                  out_dir: Path | None = None) -> list[Path]:
+    out_dir = Path(out_dir) if out_dir else OUT_DIR
+    out_dir.mkdir(parents=True, exist_ok=True)
+    paths = []
+    for o in outputs:
+        url = o.get("content") or ""
+        if not url.startswith("http"):
+            continue  # 跳过 NOT_REQUESTED 等
+        ext = url.split("?")[0].rsplit(".", 1)[-1].lower() or "glb"
+        fn = out_dir / f"{name}_{len(paths)}.{ext}"  # 按真实扩展名命名（G1 会同时给 ZIP+GLB）
+        with requests.get(url, stream=True, timeout=120) as r:
+            r.raise_for_status()
+            with open(fn, "wb") as f:
+                for chunk in r.iter_content(1 << 16):
+                    f.write(chunk)
+        paths.append(fn)
+        print(f"[download] {fn.name} {fn.stat().st_size/1e6:.1f}MB", flush=True)
+    return paths
+
+
+# ---------- Asset 上传（本地文件 -> 公网 URL；参考图上传用） ----------
+
+def _client_config(key: str | None = None):
+    """SDK v1.9+：create_*_client(config)，config 显式带 key 与 region。"""
+    from manycore.aholo_sdk_core import AholoClientConfig
+    return AholoClientConfig(api_key=load_key(key), region="cn")
+
+
+def upload_mesh(path, key: str | None = None) -> str:
+    """本地文件 -> 公网 URL（官方 Asset SDK，内置分块上传）。"""
+    from manycore.aholo_sdk_asset import create_asset_client
+    asset = create_asset_client(_client_config(key))
+    res = asset.upload_file(str(path))
+    return res.url
+
+
+# ---------- 群核能力扩展（概念图）——官方 OpenAPI schema 直译，已实测（v0.3.1），未接入交付链 ----------
+
+def _wait_and_download(key: str, tid: int, dest_dir, want_ext: set) -> list:
+    """Lux3D 任务通用：轮询至终态 + 按扩展名下载。"""
+    data = poll_task(key, tid)
+    if data["status"] != 3:
+        raise RuntimeError(f"task {tid} 未成功: status={data['status']}")
+    out_dir = Path(dest_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    paths = []
+    for o in data.get("outputs", []):
+        u = (o or {}).get("content") or ""
+        if not u.startswith("http"):
+            continue
+        ext = u.split("?")[0].rsplit(".", 1)[-1].lower()
+        if ext not in want_ext:
+            continue
+        dest = out_dir / f"{tid}_{len(paths)}.{ext}"
+        with requests.get(u, stream=True, timeout=180) as r:
+            r.raise_for_status()
+            with open(dest, "wb") as f:
+                for chunk in r.iter_content(1 << 16):
+                    f.write(chunk)
+        paths.append(dest)
+    return paths
+
+
+def concept_image(key: str, prompt: str, image: str | None = None,
+                  dest_dir="output/concept") -> Path:
+    """multimodal-to-image：概念图（纯文案或图文）。返回图片路径。"""
+    body = {"prompt": prompt}
+    if image:
+        body["img"] = image if image.startswith(("http://", "https://")) else upload_mesh(image, key=key)
+    r = requests.post(f"{BASE}/lux3d/v1/generate/multimodal-to-image/task/create",
+                      headers={"Authorization": key}, json=body, timeout=30)
+    d = r.json()
+    if d.get("c") != "0":
+        raise RuntimeError(f"concept create failed: {d}")
+    paths = _wait_and_download(key, int(d["d"]), dest_dir, {"png", "jpg", "jpeg", "webp"})
+    if not paths:
+        raise RuntimeError("concept: no image url in outputs")
+    return paths[0]