DeepSeek Harness 插件：騰訊雲混元生3D (ai3d)

在 DeepSeek Harness (DSH) 的開發中，對接外部生成式模型通常涉及任務提交、狀態輪詢和結果下載三個環節。騰訊雲混元生3D (ai3d) 提供了文本轉3D和圖像轉3D的能力，jjtovo/dsh-hunyuan-3d 插件封裝了這一過程，將模型 API 調用轉化爲 DSH 可直接使用的工具函數，並將下載的資產寫入本地文件路徑，供後續工具（如 Blender）消費。

核心功能¶

該插件主要處理以下任務：

• 任務提交與執行：支持通過文本提示或圖像輸入提交 3D 建模任務。
• 結果管理：自動輪詢任務狀態，並在任務完成後下載資產文件到本地。
• 雙 API 模式：同時支持 OpenAI 兼容接口和騰訊雲原生 API 兩種模式。
• 併發與隊列控制：內置本地併發控制邏輯，管理與服務端的作業槽位和排隊行爲。
• 憑證管理：集成 Host 端憑證存儲，支持環境變量或 Host 憑證配置。

配置與憑證¶

插件通過設置卡片進行配置。進入 Settings → Plugins → Configurable，找到“騰訊雲混元生3D”卡片。

憑證配置¶

憑證值僅在 Host 端存儲，不會發送到瀏覽器。配置方式如下：

• OpenAI 兼容模式：配置 API Key（從控制台“API KEY”頁面獲取）。
• 原生雲 API 模式：配置 SecretId 和 SecretKey（以及可選的 STS Token）。

憑證優先級：Host 憑證存儲 > 環境變量。

通用設置¶

在設置卡片中可調整以下參數，這些配置寫入 settings.yaml 的 hunyuan-3d 命名空間下：

• 併發控制：
  • maxConcurrency：本地允許的最大併發作業數，默認爲 3。
  • queueLimit：隊列允許的最大等待數，默認爲 32。
  • queueTimeoutMs：排隊等待超時時間（毫秒），默認爲 600000。
• 輪詢與超時：
  • pollIntervalMs：輪詢任務狀態的間隔。
  • defaultWaitMs：默認等待結果的時間。
  • httpTimeoutMs：HTTP 請求超時時間。
• 結果存儲：
  • resultDir：結果文件的存儲目錄。

API 模式說明¶

騰訊雲混元生3D 服務通過兩個不同的接口暴露，插件支持兩者並在設置中切換：

併發與隊列策略¶

服務端限制最多 3 個併發作業。超出限制的請求會被本地隊列攔截，避免無效的 API 調用。

• 提交限制：當併發數達到 maxConcurrency，新的提交請求會被拒絕並返回 concurrency-queue-full。
• 排隊等待：在 queueLimit 範圍內的請求會進入等待隊列。如果等待時間超過 queueTimeoutMs，請求將失敗並返回 concurrency-wait-timeout。
• 資源釋放：提交任務後，即使使用了 wait: false 模式（立即返回），其佔用的併發槽位也會持續直到通過 hunyuan_3d_query 檢查到任務結束（DONE 或 FAIL）。

典型用法¶

插件註冊了兩個工具函數：

1. hunyuan_3d_model：提交任務並默認等待結果下載。
   • 輸入：文本提示或圖像 URL。
   • 行爲：默認等待任務完成並下載文件，返回本地文件路徑。
2. hunyuan_3d_query：查詢任務狀態或恢復結果。
   • 輸入：任務 ID。
   • 行爲：用於恢復之前以 wait: false 提交的任務，或檢查後臺任務進度。

注意事項¶

• 結果有效期：生成的結果 URL 有效期爲 24 小時。如果任務完成很久，需重新運行任務，無法直接重新下載舊結果。
• 前置要求：
  • 需要激活騰訊雲混元生3D 服務。
  • Node.js 版本要求 >= 22.19.0。
• 環境依賴：插件運行依賴 Host 端的憑證存儲機制，確保 Host 進程有權限讀寫憑證配置。

參考資料¶

• 插件目錄：SkillHub 目錄頁
• 源碼倉庫：GitHub - jjtovo/dsh-hunyuan-3d