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