dsh-gen3d

Readme

# dsh-gen3d

DeepSeek Harness（DSH）的 **3D 角色生成插件**：把一句需求 / 一张参考图变成带贴图、游戏可用的 3D 角色资产。直连 **Meshy / 腾讯混元 3D / Tripo3D / Rodin（Hyper3D）四家官方 API**，凭证由用户自行配置，插件不内置任何 key；未配置 key 时自动回退**确定性 mock**（能跑通全链路，但不产生真实模型、不消耗配额）。

## 安装

**推荐从 npm registry 安装**（已发布、自带构建产物，唯一推荐方式）：

```bash
dsh plugin --profile web add dsh-gen3d
```

> **新版本发布后的数小时内**，profile 侧 pnpm 的发布冷却机制（minimumReleaseAge）
> 可能把最新版排除在解析外——bare `add dsh-gen3d` 会回落到旧版（2026-08-25 实证：
> 0.2.0 发布当口装到了 0.1.0）。显式 `dsh plugin --profile web add dsh-gen3d@latest`
> 或指定版本号绕过。

> **git 安装（不推荐，仅备用）**：`dsh plugin --profile web add github:LuZhouheng/dsh-gen3d`。
> git 安装拉的是源码（`lib/` 不进 Git），包内已备自包含 `prepare` 脚本
> （`tsc -p tsconfig.build.json`，跨平台、无 shell 依赖）在安装时自动构建；
> 但 pnpm ≥10 默认拦截 git 依赖的构建脚本，还需按 DSH publish 文档在该 profile
> 的 `pnpm-workspace.yaml` 中为 `dsh-gen3d` 声明 `allowBuilds` 构建许可后才生效。
> 第三方插件目录站自动生成的 `github:` 安装命令即此路径——照抄前请知悉。

## 凭证配置

> 本插件**不含任何 API key**。所有真实生成调用都使用你自己购买并配置的官方 key；未配置时回退 mock，不会偷偷调用任何第三方服务。

插件直连四家官方 API，各配各的 key（变量名与 `src/config.ts` 注册表一致，详见 [docs/CREDENTIALS.md](docs/CREDENTIALS.md)）：

| 供应商 | 凭证变量名 | 获取入口 | 备注 |
| --- | --- | --- | --- |
| Meshy | `MESHY_API_KEY` | [platform.meshy.ai](https://platform.meshy.ai) 登录后 **Settings → API（API settings 页）** Create API Key | 注册即可建 key；key 只显示一次，可随时吊销 |
| 腾讯混元 3D（生成） | `HUNYUAN3D_API_KEY` | **TokenHub 控制台**创建 API Key（[混元调用指南](https://cloud.tencent.com/document/product/1823/132252)） | 官方主推路径，Bearer 直用；首次开通送 100 免费积分 |
| 腾讯混元 3D（后处理） | `HUNYUAN3D_SECRET_ID` + `HUNYUAN3D_SECRET_KEY` | 腾讯云控制台 **访问管理 → API 密钥管理**（CAM） | 可选；TC3 签名路径（腾讯云 API 3.0），**绑骨 / 文生动作 / 智能拓扑等后处理能力必需** |
| Tripo3D | `TRIPO3D_API_KEY` | [platform.tripo3d.ai/api-keys](https://platform.tripo3d.ai/api-keys) 生成 | key 以 `tsk_` 开头；`tcli_` 开头的 Client ID 仅标识应用，**不能用于认证** |
| Rodin（Hyper3D） | `RODIN_API_KEY` | [hyper3d.ai](https://hyper3d.ai) 登录后 **API Key Management** 页面 "+Create new API Keys" | 需 **Business 订阅（$120/月）** 才有 API access；key 只显示一次，可吊销 |

### 配置方式

推荐写入 `$DSH_HOME/.credentials.yaml`（`$DSH_HOME` 未设置时默认 `~/.dsh`）。解析器兼容两种写法，**根映射**为权威 DSH 形态（文档仅一个扁平映射），**`credentials:` 包裹层**为兼容形态（README 旧示例），二者等价：

```yaml
# 形态一（权威）：根映射
MESHY_API_KEY: "meshy-xxxxxxxx"
HUNYUAN3D_API_KEY: "xxxxxxxx"
TRIPO3D_API_KEY: "tsk_xxxxxxxx"
RODIN_API_KEY: "xxxxxxxx"
HUNYUAN3D_SECRET_ID: "AKIDxxxxxxxx"   # 可选：腾讯云后处理（TC3 签名）
HUNYUAN3D_SECRET_KEY: "xxxxxxxx"      # 可选：腾讯云后处理（TC3 签名）
```

```yaml
# 形态二（兼容）：顶层 credentials: 包裹一层，与根映射等价
credentials:
  MESHY_API_KEY: "meshy-xxxxxxxx"
```

或通过环境变量注入（**优先级最高**，遮蔽同名文件配置；也可用 `<cwd>/.env`、`$DSH_HOME/.env`）：

```bash
export MESHY_API_KEY="meshy-xxxxxxxx"
export HUNYUAN3D_API_KEY="xxxxxxxx"
```

读取优先级（与 DSH credentials-local 四层一致）：**环境变量 > `$DSH_HOME/.credentials.yaml` > `<cwd>/.env` > `$DSH_HOME/.env`**；空字符串视为未配置；每次调用实时重读文件，key 轮换**无需重启**。完整安全指引（掩码规则、key 不进仓库、文件权限）见 [docs/CREDENTIALS.md](docs/CREDENTIALS.md)。

配好后用 `gen3d:provider-status` 验证（只显示是否配置与脱敏尾缀，不打印完整 key）。

## 功能

21 个 DSH 工具（`src/tools/`，`allGen3dTools`），分五组：

**生成（11 个）**

| 工具 | 说明 |
| --- | --- |
| `gen3d_provider_status` | 供应商状态：四家 key 配置状态 / 模型 / 能力说明，零调用 |
| `gen3d_credentials_status` | 凭证状态：只读掩码查询各家 key 是否配置（前 4 后 4，绝不输出完整密钥） |
| `gen3d_list_assets` | 资产盘点：工作区 3D 资产清单 + 完整 sidecar 元数据 |
| `gen3d_delete_asset` | 删除资产：主 GLB + sidecar + 侧文件，缓存键打 tombstone（破坏性操作） |
| `gen3d_text_to_3d` | 文生 3D：一句需求生成带贴图角色（默认 Meshy，可切三家） |
| `gen3d_image_to_3d` | 图生 3D：一张参考图生成模型（URL / base64 / 本地文件三形态） |
| `gen3d_views_to_3d` | 多视图生 3D：多角度参考图生成（front 必填） |
| `gen3d_refine_mesh` | 精修：Meshy 两阶段精修（可追加贴图） |
| `gen3d_retopo_lowpoly` | 低模重拓扑：从高模源产出规整低面数新资产（源资产保留） |
| `gen3d_rename_asset` | 重命名：设置显示名（userLabel），不动磁盘 / 缓存键 |
| `gen3d_score_quality` | 质量评分：客观五维（geometry / topology / texture / pbr / prompt_fidelity），不调用 provider |

**动画（3 个）**

| 工具 | 说明 |
| --- | --- |
| `gen3d_auto_rig` | 自动绑骨：人形资产追加骨架（保贴图，Meshy 自带免费 walk/run 片段） |
| `gen3d_apply_motion` | 套动作：一次一个、按动作幂等追加动画 |
| `gen3d_list_motions` | 动作目录：Meshy 约 690 条 / Hunyuan 48 预设 / Tripo 16 个 `preset:*` |

**可玩角色（5 个）**

| 工具 | 说明 |
| --- | --- |
| `gen3d_get_playable_profile` | 读取动作档：内置 preset 锚 + 角色覆盖 + 映射草稿 + 交付快照 |
| `gen3d_set_playable_profile` | 设置动作档：写角色动作槽覆盖（DSH 无游戏级默认档） |
| `gen3d_set_playable_motion_mapping` | 动作映射：槽位 ↔ 已套动作绑定（导出前置条件） |
| `gen3d_export_playable_character` | 导出可玩角色：动作合并输出 `merged.glb` + `playable.json` |
| `gen3d_adopt_playable_character` | 采纳交付物：孤儿 `merged.glb` 补 clip 映射与交付快照 |

**资产（2 个）**

| 工具 | 说明 |
| --- | --- |
| `gen3d_inspect_asset` | 资产体检：对照预算档（hero-character / prop / environment）检查面数、贴图、材质三科 |
| `gen3d_render_preview` | 视口预览：纯 JS 软渲染出 PNG/GIF 预览并落盘；web 会话「3D 资产」页签可交互查看（three.js：IBL 环境光照 + ACES 色调映射 + 阴影；带动画资产自动播放、可暂停/切 clip；png/jpg 等图片资产直接内联预览） |

一句话产线：**生成 → 评分 → 命名 →（要会动才）绑骨 → 套动作 → 导出**；静态优先、会动 opt-in（按次计费）。注：legacy 的 `pose-standardization`（A/T-pose 标准化）**暂缓未迁移**——官方无独立等价 API，详见[已知缺口](#已知缺口)。

### 供应商能力矩阵

四家官方 API 能力对照（依据 `docs/providers/` 四份协议文档；2026-08-13 快照，meshy 已按 2026-08-24 官方文档刷新；✅ 官方支持 / ⚠️ 部分或近似 / ❌ 无）：

| 能力 | Meshy | 腾讯混元 3D | Tripo3D | Rodin |
| --- | --- | --- | --- | --- |
| 文生 3D | ✅ text-to-3d v2（两阶段 preview→refine） | ✅ TokenHub `hy-3d-3.0/3.1`，或 TC3 专业版 | ✅ `text_to_model`（H3/H2/P1 三产品线） | ✅ `/api/v2/rodin`（不传 images） |
| 图生 3D | ✅ image-to-3d（URL / base64） | ✅ `image_base64` / `image_url` | ✅ `image_to_model`（file_token / URL / STS object，**不支持 base64**） | ✅ `/api/v2/rodin`（1 张 images） |
| 多视图生 3D | ✅ multi-image-to-3d（1–4 张） | ✅ 3 视角（3.1 版 8 视角） | ✅ `multiview_to_model`（固定 4 视角 `front,left,back,right`，front 必填） | ✅ 2–5 张（form 保序，**首张固定用于材质生成**） |
| 自动绑骨 | ✅ rigging（人形带贴图，自带 walk/run） | ✅ `SubmitAutoRiggingJob`（A/T-pose 输入，可带 48 预设动作） | ✅ `animate_rig`（biped/quadruped 等 7 类，可先免费预检） | ❌ 无（`TAPose=true` + Quad 产绑骨就绪输入） |
| 动作 / 动画 | ✅ animations（静态动作目录 0–696，约 690 条） | ✅ 绑骨内置 48 预设动作 + 文生动作 | ✅ `animate_retarget`（16 个 `preset:*` 预设，一次最多 5 个） | ❌ 无 |
| 低模 / 重拓扑 | ✅ smart-topology（`meshy-t2`）+ 独立 Remesh API（`gen3d_retopo_lowpoly` 的 meshy 路由已接入：`input_task_id` / 本地 GLB Data URI 直传，无需公网 URL） | ✅ `Submit3DSmartTopologyJob` + 减面 + `GenerateType=LowPoly` | ✅ P1 产品线 / `smart_low_poly` / `highpoly_to_lowpoly` | ⚠️ 仅生成时控面数（quality / quality_override / Sketch 档），无独立端点 |
| 贴图精修 | ✅ refine 追加贴图（`texture_image_url`） | ⚠️ 无直接对应（纹理生成 / 编辑近似替代） | ✅ `texture_model` | ✅ `rodin_texture_only`（模型 ≤10MB） |
| 余额查询 | ✅ `GET /openapi/v1/balance` | ⚠️ 无独立接口（TC3 任务查询响应含 `ResultCreditConsumed` / `ResultCreditDetails` 明细） | ✅ `GET /v2/openapi/user/balance` | ✅ `GET /api/v2/check_balance` |
| 接入门槛 | 注册即可（积分制） | 首开通送 100 积分；新能力逐步迁往 TokenHub | 注册送 300 积分（两周有效），积分永不过期 | **Business 订阅 $120/月**（更低档无 API access） |

**要点**：Meshy 能力最全（生成 / 精修 / 绑骨 / 动作全链路，重拓扑本地资产可直接经 Remesh Data URI 直传）；腾讯混元后处理强（绑骨 + 文生动作 + 智能拓扑）但需 TC3 密钥对，且输入文件要公网 URL；Tripo 生成档位多（含 P1 结构化低模产品线）但图片输入不支持 base64、需先上传；Rodin 仅覆盖生成 + 拆分（Bang）+ 重贴图，无绑骨 / 动作，订阅门槛最高 —— 定位为可选增强供应商。详细协议见 `docs/providers/`。

### Mock 模式

未配置 key 的 provider 一律自动回退**确定性 mock**（调用结果带 `usedMock: true`，`provider_not_configured` 不中断链路）：生成 / 精修 / 绑骨 / 动作 / 重拓扑的链路、资产落地、评分、合并导出都能跑通，但产物不是真实模型。看到 `usedMock: true` 时提示用户配置对应 key。已配置的 provider 正常直连，互不影响。

## 已知缺口

当前实现的已知能力边界（十六条，每条含**影响 / 规避方式 / 后续计划**）见 [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md)。要点速览：

- **Hunyuan 套动作**：`apply-motion` 的 Hunyuan 路由暂不可用——官方 48 预设动作目前只能绑骨时经 `motionType` 顺带，独立套动作待挂接 `SubmitHunyuanTo3DMotionJob`
- **Tripo 绑骨**：仅限 Tripo 自身生成的资产；外部 GLB 的 `import_model` 导入链路未实现
- **低模重拓扑**：meshy 路由已落地（本地 GLB Data URI 直传 / Meshy 任务 `input_task_id`，5 积分/次）；hunyuan / tripo 路由仍需公网源 URL / Tripo 任务 id
- **Rodin**：无绑骨 / 动作 / 重拓扑端点，且 API access 需 Business 订阅（$120/月）——定位为可选增强供应商
- **pose-standardization 暂缓**：官方无独立等价 API，未迁移

## 开发

> 运行时依赖（如 `@gltf-transform/core` 等）随 legacy 代码收口按需补充；`typescript` / `vitest` / `@types/node` 等 devDependencies 已就位。

```bash
pnpm install
pnpm build     # tsc host + tsc client + tsdown → lib/（含浏览器半边 lib/client.js）
pnpm test      # vitest run
```

## 设置卡片（DSH Web UI）

0.1.1 起，插件在 DSH 的 Web 设置页注册一张「3D 生成供应商配置」卡片（官方
rc.7 起支持的插件自注册设置卡片，见 [docs/dsh-api.md](docs/dsh-api.md) 设置卡片章节）：

- **host 半边**（`src/settings.ts`）注册 `gen3d` 设置命名空间；schema 缺省引用即
  `PROVIDER_ENV_KEYS`，解析后的 `apiKeyEnv` 引用经 `setProviderRefSource` 接回
  `src/config.ts` 工具密钥解析——卡片改写引用后，工具随之改读对应变量名；
- **浏览器半边**（`src/client/`）以同 key 注册卡片：四家供应商 real/mock 状态徽标
  （configured → real，否则 mock 回退）+ 凭证变量名输入。configured/writable 事实
  经凭证域 `credentials.describe` 取得，永不含密钥值；
- 构建：`tsdown.config.ts` 自复刻官方 clientBundle 输出格式（lazy-CJS factory，
  入口固定 `lib/client.js`）；卡片由 DSH client-modules 按 `dsh.client` 声明自动
  服务到 Web 页面，无需重编 web 应用。
- 说明：Hunyuan3D 的 TC3 密钥对路径不经过凭证域，卡片只反映
  `HUNYUAN3D_API_KEY`（TokenHub）路径状态。

> 实测：2026-08-20 在 rc.8 web 部署（dsh-web-app@0.1.0-rc.8）端到端验证通过——
> 插件配置页渲染四行供应商状态、写路径往返正常、浏览器 console 零错误
> （证据见 [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md) §10）。

## 布局

```
dsh-gen3d/
├── AGENTS.md             # agent 交接：构建/测试命令 + 结构入口 + 红线（密钥零内置 / 宿主包 peer 化 / 计费不盲重试 / tarball 分发）
├── package.json          # npm 包 + dsh.bundle 元数据（patch → ./cordis.patch.yml）+ dsh.client（浏览器半边）
├── cordis.patch.yml      # DSH 服务注入：id: gen3d
├── tsconfig.json         # host 半边（node）
├── tsconfig.client.json  # 浏览器半边（DOM + JSX，→ lib/client/）
├── tsdown.config.ts      # 浏览器半边 bundle（自复刻官方 clientBundle 格式 → lib/client.js）
├── src/                  # 工具实现（ctx.tools.register(defineTool(...))）
│   ├── config.ts         # 凭证四层读取（readProviderKey 等，唯一密钥入口；设置节引用接线）
│   ├── settings.ts       # 设置卡片 host 半边（gen3d 命名空间 + schema）
│   ├── storage.ts        # Gen3dStore 资产落盘 / 缓存 / 审计 / 锁
│   ├── client/           # 设置卡片浏览器半边（注册 / 控制器 / 组件）
│   └── providers/        # 四家官方 API 直连（types 契约 + meshy / hunyuan3d / tripo3d / rodin）
├── skills/               # 随包分发的 agent 技能（generate-3d-character / game-3d-assets）
└── docs/
    ├── KNOWN-GAPS.md     # 已知能力缺口（影响 / 规避 / 后续计划）
    ├── CREDENTIALS.md    # 凭证安全配置详细指南
    ├── dsh-api.md        # DSH 插件 API 精读
    └── providers/        # 四家官方 API 协议文档（meshy / hunyuan3d / tripo3d / rodin）
```

## 许可

MIT