---
name: run-hunyuan3dweb
description: 运行并驱动腾讯混元 3D Python 客户端。当用户要求：跑 hunyuan3dweb、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证这个项目能否工作时使用。
---

本项目是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 Python 客户端：签名算法（HMAC-SHA256 + 密钥派生）、纯 HTTP API 调用、浏览器登录工具。**无需 pip install**——通过 `PYTHONPATH` 从源码直接运行。

唯一驱动入口：`.claude/skills/run-hunyuan3dweb/driver.sh`（下文所有路径相对仓库根 `/opt/hunyuan3dweb`）。

## 前置条件

```bash
python3 --version        # ≥3.8 ✅ (本机 3.13.12)
python3 -c "import requests"   # 缺则: pip install requests
```

浏览器功能（登录/抓包）另需 `playwright`、`cloakbrowser`、`chromium`、`xvfb-run`——本机均已装好。

## Setup

无安装步骤。依赖的两个东西：

1. **仓库路径**：driver 已内置（`PYTHONPATH` 自动指向仓库根）。
2. **登录 cookie**：`~/.config/hunyuan3dweb/cookies.txt`（已存在，2026-08-15 登录过，当前有效）。过期后用下面"重新登录"一节处理。

## Run（agent 路径）——driver.sh

```bash
.claude/skills/run-hunyuan3dweb/driver.sh verify   # 三重自检（最快确认能用）
```

| 命令 | 作用 |
|---|---|
| `driver.sh verify` | 环境 + 离线签名 + 在线配额 三重自检 |
| `driver.sh quota` | 查配额，输出 `remainQuota/totalQuota` |
| `driver.sh list` | 作品列表（JSON，含 `totalCount`/`creations`） |
| `driver.sh status <creationsId>` | 生成状态（json/轮询用 `state` 字段） |
| `driver.sh text "<prompt>"` | 文生 3D 提交（**消耗配额**，出 4 个） |
| `driver.sh formats <creationsId>` | 可用下载格式（glb/obj/fbx/stl/usdz/mp4/gif…） |
| `driver.sh download <creationsId> [--format glb] [--output PATH]` | 下载模型到当前目录 |

其余 API（图生 3D、多视角、动画、贴图、减面）直接 import 客户端调用
（`api_complete.py` 的 `Hunyuan3DAPIComplete`），10+ 种生成模式同签名同会话。
本容器内已实测：`quota`/`list`/`status`/`formats`/`download`（2026-08-15，7 个作品齐全）；
`text` 只验证到请求构造层（消耗配额，未实测全流程）。

**退出码**：`0` 成功 · `1` 环境/其他 · `2` 认证失败（需重新登录）· `3` cookie 缺失。
收到 2/3 时按下面"重新登录"处理，不要把栈当 bug 报告。

典型工作流（文生 3D + 轮询）：

```bash
.claude/skills/run-hunyuan3dweb/driver.sh quota                       # 先看余额
.claude/skills/run-hunyuan3dweb/driver.sh text "a ceramic teapot"     # → creationsId
.claude/skills/run-hunyuan3dweb/driver.sh status <creationsId>        # 轮询到 state=success
.claude/skills/run-hunyuan3dweb/driver.sh download <creationsId> --format glb
```

## 重新登录（认证失败时唯一出路）

收到退出码 2（`"code":"20001"` token 无效 / `"999"` cookie 无用户）时：
**必须由人类用户在真实终端**（不是 Claude 的 `!` 前缀——stdin 非交互，`input()` 会 EOF）运行：

```bash
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.browser.login
```

按提示输邮箱 → 收验证码 → 输验证码，登录态自动存回 `cookies.txt`。
登录完成后浏览器进程**自动退出，无资源残留**（2026-08-15 验证：登录后零残留进程）。

## Run（人类路径）

```bash
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.cli quota     # 等价 CLI
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.cli list
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.cli text "a red apple"
```

## Test（离线自检）

```bash
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.sign
# 派生密钥: Hf6d6KFB3D  ← 输出里有这行即签名算法正确
```

---

## Gotchas

- **`!` 前缀跑登录必 EOF** —— `input()` 在管道 stdin 打开即 EOF（`EOFError: EOF when reading a line`）。登录必须真实终端；agent 只能引导用户去跑。
- **401 有两种，别混** —— `"code":"20001"`=token 过期（重登）；`"code":"999"`=cookie 无用户（重登或检查 cookie 文件）。两者都证明**签名本身是对的**（服务端能分类错误）。
- **不存在的 creationsId → HTTP 400 空 body**，不是 JSON 错误（2026-08-15 实测）。
- **`python3 -m hunyuan3dweb.sign` 有 RuntimeWarning**（`'hunyuan3dweb.sign' found in sys.modules...`）——runpy 与 `__init__.py` 重复导入的假警报，无害，输出仍正确。
- **文生 3D 固定出 4 个模型**（`count=4`），一次消耗 4 次配额；`generate_from_text` 的 `count` 参数会覆盖 UI 行为。
- **`download` 输出到 CWD**——某次下载 86KB 预览图实测 2–3 秒；GLB 可能几十 MB，注意磁盘和时间。正式大规模跑之前先 `quota` 确认登录态在线。

## Troubleshooting

- **`driver.sh verify` 打印 AUTH_EXPIRED / 退出码 2**：token 过期。让人在真实终端跑 `PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.browser.login`，成功后再 verify。
- **`EOFError: EOF when reading a line`**（登录时）：stdin 非交互。换真实终端，不要用 `!`。
- **`requests.exceptions.HTTPError: 401` + 中文消息 'token无效'**：同上，重登。不是代码 bug，别改代码。
- **cookie 想换账号**：`HUNYUAN3D_COOKIES=/path/to/other/cookies.txt driver.sh quota`。
- **driver 里 python 找不到模块**：确认 `PYTHONPATH` 含仓库根（driver 会自动设置）。