混元生3D建模 JJTovo/dsh-hunyuan-3d

dsh-hunyuan-3d

腾讯云混元生3D（ai3d OpenAPI）接入 dsh 智能体工具：提交文生3D 与图生3D 任务、轮询结果、把资产下载到磁盘，这样后续轮次和其他工具（Blender、格式转换器）就能拿到真实文件路径。

工具

| 工具 | 用途 |
| hunyuan_3d_model | 提交建模任务，默认等待完成并下载资产。 |
| hunyuan_3d_query | 重新检查用 wait: false 启动的任务，或稍后取回结果。 |

两者返回同一份规范结果：job_id、mode、status（WAIT/RUN/FAIL/DONE）、message，可选的 error_code / error_message / credits_consumed / credit_details，以及 files[]，其中包含已下载的 path、bytes、type、source_url 和 preview_image_url。

结果 URL 在生成后 24 小时过期，所以早就完成的任务必须重新跑，不能重新下载。

两个 API 入口

腾讯把同一套 3D 服务放在两个入口后面，插件两个都支持——在设置卡片里选一个：

| | OpenAI 兼容（默认） | 原生云 API |
| Base URL | https://api.ai3d.cloud.tencent.com | https://ai3d.tencentcloudapi.com |
| 提交 | POST /v1/ai3d/submit | POST / + X-TC-Action: SubmitHunyuanTo3DProJob |
| 查询 | POST /v1/ai3d/query | POST / + X-TC-Action: QueryHunyuanTo3DProJob |
| 鉴权 | Authorization: <api key>（控制台「API KEY」页面） | TC3-HMAC-SHA256（SecretId/SecretKey/Region） |
| 凭据 | 一个 key，HUNYUAN3D_API_KEY | TENCENTCLOUD_SECRET_ID + TENCENTCLOUD_SECRET_KEY（可选 token） |
| 模式 | 仅 pro——兼容层没有发布 rapid 端点 | pro 和 rapid |

API key 直接作为 Authorization 的值发送，文档里的 cURL 示例就是这么用的。如果网关拒绝这种形式，会用 Bearer 重试一次，OpenAI 风格的客户端不用改就能用。

Base URL 可以填 origin、…/v1、…/v1/ai3d，或者完整的 …/v1/ai3d/submit：API 路径会被剥掉而不是重复拼接，因为路径重复会导致路由失败，服务只会回一个没什么用的 4xx。

失败时会报告服务自己的响应体和状态码，所以被拒绝的调用在设置卡片里就能诊断，不用另开请求日志。

两个入口共用同一套请求/响应词汇（Prompt、ImageUrl、MultiViewImages、FaceCount、Status、ResultFile3Ds……），所以不管你选哪个，工具参数和结果都一样。响应解析很宽容：裸响应体和包在 Response 里的都能解析，key 大小写也忽略。

应用内配置

插件在 Settings → Plugins → Configurable 下注册了一张设置卡片（「腾讯云混元生3D」）。它编辑插件的 hunyuan-3d 设置命名空间，并且，对于凭据通过宿主凭据存储写入。

| 卡片控件 | 落点 |
| API Key（兼容模式）或 SecretId / SecretKey / STS Token（原生模式） | dsh 凭据存储（.credentials.yaml），只写 |
| provider、baseUrl、region、endpoint | settings.yaml 中的 hunyuan-3d 段 |
| resultDir、pollIntervalMs、defaultWaitMs、httpTimeoutMs | settings.yaml 中的 hunyuan-3d 段 |

卡片遵循两条规则，与 dsh 自带的配置卡片一致：

- 凭据值绝不从宿主流向浏览器。 卡片只知道某个引用是否已配置、是否可写；输入值只会单向提交。未改动的字段绝不会清空已存储的密钥。
- 设置立即生效。 工具在每次调用时读取解析后的配置段，因此保存的改动无需重启即可作用于下一次调用。

卡片通过回环限制的桥接与宿主通信：

| 路由 | 用途 |
| GET/POST /api/dsh-hunyuan-3d/settings | 读取解析后的配置段 + 凭据状态；保存补丁 |
| POST /api/dsh-hunyuan-3d/credentials | { role, action: set \| unset, value? } |
| POST /api/dsh-hunyuan-3d/test | 对线上端点做鉴权，不产生计费（兼容模式：对不可能存在的 job id 发 POST /v1/ai3d/query；原生模式：同样对不可能存在的 job id 调 QueryHunyuanTo3DProJob） |

非回环调用方（外部主机、非回环对端地址、cross-site fetch 元数据）会收到 403；其他方法会收到 405。

凭据

卡片是常规路径；环境变量仍然可用，两者都设置时环境变量优先。插件按以下顺序解析：

1. dsh 凭据存储（ctx.credentials.resolve），然后
2. 进程环境。

| 设置项 | 默认引用 |
| SecretId | TENCENTCLOUD_SECRET_ID |
| SecretKey | TENCENTCLOUD_SECRET_KEY |
| STS token（可选） | TENCENTCLOUD_TOKEN |

贡献账号需要为你调用的地域开通混元生3D；未开通或操作无权限会以 API 错误码暴露，而不是静默失败。

请求在进程内用 TC3-HMAC-SHA256（src/tc3.js）签名，因此不附带也不需要腾讯云 SDK。

并发

服务授予固定数量的并发任务——按产品文档为 三个——超出部分一律返回 RequestLimitExceeded。因此插件在本地对提交做闸控，而不是花一次往返去确认它已经知道的事。

- 最多 maxConcurrency 个任务占用服务槽位。更多调用会排队。
- 槽位在任务占用服务期间一直持有，而不只是在调用进行中。wait: false 立即返回，任务会一直保留槽位，直到后续某次 hunyuan_3d_query 观察到 DONE 或 FAIL。
- 等待预算耗尽的调用同样保留槽位，原因相同；状态消息会说明这一点，并指出哪个查询会释放它。
- 队列满时以可重试的 concurrency-queue-full 拒绝；排队的超过 queueTimeoutMs 的调用会失败，报 concurrency-wait-timeout，并说明没有提交任何内容。

| 设置 | 默认值 | 含义 |
| maxConcurrency | 3 | 同时执行的任务数。改成 1 即可串行执行。 |
| queueLimit | 32 | 允许排队等待的调用数，超出后新调用会被拒绝。 |
| queueTimeoutMs | 600000 | 排队调用等待多久后放弃。 |

这三项都能在设置卡片里修改，卡片还会显示实时用量（占用 1/3，排队 2）。限制在每次调用时读取，所以改完对下一次提交立即生效，不用重启。

被遗弃的任务。 用 wait: false 启动、之后又从不查询的任务，会一直占着它的槽位。按「服务还在处理它」来理解这没错，但有一点值得知道：要么去查询后台任务，要么让 queueTimeoutMs 限制它后面那些等待者。

验证

npm test # 26 tests, no network, no credits

第 1 部分锁定传输格式：手写的 schema 必须能通过 dsh 自己的 schema 编译器和 assertSupportedJsonSchema，注册的定义也必须能通过 dsh 的 register() 校验。

第 2 部分拿真实插件跑 tests/mock-ai3d.mjs——一个本地替身，实现了已验证的信封契约，并会拒绝签名错误的请求——覆盖提交、轮询、下载、后台模式、快速模式、本地图片内联、取消、任务失败、凭据缺失和参数非法。

浏览器那一半不用浏览器也能验证：tests/client.test.mjs 拿真实构建产物 lib/client.js 跑一个 loader 替身，用真实 React 渲染卡片，并断言字段集合、只写的凭据输入框，以及 React 保持 external。

提供 schema 编译器的 dsh 检出目录默认是 E:/deepseek_harness/packages/core/tools/lib/index.js；用 DSH_TOOLS_LIB 覆盖，否则这些断言会跳过。

不依赖 dsh 的验收检查

node tests/mock-ai3d.mjs --port 1731 --delay-ms 400 &
TENCENTCLOUD_SECRET_ID=AKIDmock TENCENTCLOUD_SECRET_KEY=SECRETmock \
DSH_HUNYUAN3D_ENDPOINT=127.0.0.1:1731 DSH_HUNYUAN3D_SCHEME=http \
DSH_HUNYUAN3D_POLL_MS=150 DSH_HUNYUAN3D_RESULT_DIR=/tmp/hy3d-out \
node bin/model.mjs --prompt "一只低多边形风格的宝箱" --format GLB

退出码 0 表示调用完成，且返回值满足模型看到的同一份 schema。--dry-run 只打印参数和 schema，不调用任何东西；--query --job <JobId> 走恢复路径。

对接真实账号时，去掉 DSH_HUNYUAN3D_* 覆盖项，换成真实凭据——这会消耗额度。

安装到 dsh 配置档

在本仓库里：

git clone git@github.com:JJTovo/dsh-hunyuan-3d.git
or, without an SSH key: https://github.com/JJTovo/dsh-hunyuan-3d.git

cd "$DSH_HOME/profiles/web"
pnpm add "github:JJTovo/dsh-hunyuan-3d"

git 依赖会运行包的 prepare 脚本，所以 lib/client.js 是
安装时会从 src/client/index.js 重新构建。

从本地检出安装：

cd "$DSH_HOME/profiles/web"
pnpm add "file:/absolute/path/to/dsh-hunyuan-3d"

然后把 bundle（或插件那一行）加到 cordis.patch.yml：

- insert:
- id: hunyuan-3d
name: 'dsh-hunyuan-3d'
config:
region: ap-guangzhou

file: 依赖会在安装时复制一份，所以改完插件源码后要重新跑 pnpm add（或重装）。本包里的 cordis.patch.yml 有同样一行，写成了 bundle 补丁的形式。

跨机器可移植性

插件以 vendor 形式放在配置档内部，用相对路径引用：

"dsh-hunyuan-3d": "file:./plugins/dsh-hunyuan-3d"

因此 pnpm-lock.yaml 记录的是 directory: plugins/dsh-hunyuan-3d —— 这个路径不含盘符、用户名或绝对位置。把 harness home 挪到另一台机器（或同一台机器的另一个盘）依然有效。

迁移到新机器

1. 复制整个 harness home（$DSH_HOME，默认 ~/.dsh）—— 里面有配置档、本插件的源码、settings.yaml 和 .credentials.yaml。
2. 在 profiles/web 里重装依赖：

cd "$DSH_HOME/profiles/web"
pnpm install

node_modules 可以复制也可以重建，两种都行。先删掉最干净，因为 pnpm 的 store 路径是本机专属的。
3. 如果你没有复制 .credentials.yaml，在 Settings > Plugins > 腾讯云混元生3D 里重新填 API key。

不需要构建步骤：lib/client.js（浏览器那一半）和源码一起提交了，插件开箱即用。npm run build 只在改完 src/client/ 之后重新生成它。

与机器无关的部分

| 部分 | 可移植？ |
| src/、lib/、cordis.patch.yml | 是 —— 没有绝对路径，没有运行时依赖 |
| 配置档依赖声明 | 是 —— 相对路径（file:./plugins/dsh-hunyuan-3d） |
| settings.yaml（provider、baseUrl） | 是 —— 非机密，不含路径 |
| .credentials.yaml 里的 API key | 跟着 $DSH_HOME 走；否则重新填 |
| node_modules/ | 天然是本机专属；重装即可 |
| resultDir | 运行时从 $DSH_HOME 解析，从不存成绝对路径 |

已知的本机专属例外

bin/validate-result.mjs 和 tests/hunyuan3d.test.mjs 把 DSH_TOOLS_LIB 默认指向开发者检出路径（E:/deepseek_harness/packages/core/tools/lib/index.js）。这只影响测试：没有它，那两条断言会跳过，其余照常运行。想要严格的 schema 断言时，把 DSH_TOOLS_LIB 指向你自己的检出。

什么时候需要重启

改 src/ 会改动磁盘上的文件，但正在运行的宿主仍然持有它已经导入的模块。dsh 的 patchReload: live 会重新读取补丁文件；它不会重新导入插件的模块。改完插件代码后：

cd "$DSH_HOME/profiles/web" && pnpm install # re-materialize the vendored copy
then restart dsh
设置变更不一样——工具每次调用都会读取解析后的配置段，所以保存后的设置对下一次调用立即生效，无需重启。

验证改动 bash
cd "$DSH_HOME/profiles/web/plugins/dsh-hunyuan-3d"
npm test # 27 tests, no network, no credits
dsh --profile web --no-open --port 0

expect: zero "did not activate" warnings, and the settings card lists 腾讯云混元生3D

边界

- 计费。 每个完成的任务都会消耗额度；失败的任务会返回 error_code，而不是重试，由调用方决定下一步。
- 不循环重试。 超时和网络错误会标记为 retryable 并上报；插件绝不自行重新提交，因为重试提交可能计费两次。
- 并发。 服务对每个账号的同时任务数有限制；RequestLimitExceeded 会作为 API 错误返回。
- 结果过期。 下载发生在观察到 DONE 的同一次调用内，这样插件就始终处于 24 小时的 URL 有效窗口内。
- 图像输入。 prompt 和图像互斥，除非 generate_type: Sketch；pro 模式还额外接受 multi_view_images。
- 格式。 result_format 只是偏好：服务可能返回 OBJ 加 GLB，也可能返回 data: URL，两种情况下载时都能处理。