KawasakiAkasei
bd987a2222
- skill/run-hy3d/SKILL.md: user-level skill now versioned in repo - skill/install.sh: one-command install to ~/.claude/skills/run-hy3d - README/README_CN: document skill install/uninstall
91 lines
4.1 KiB
Markdown
91 lines
4.1 KiB
Markdown
---
|
||
name: run-hy3d
|
||
description: 运行并驱动腾讯混元 3D（hy3d）。当用户要求：跑 hy3d、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证 hy3d 能否工作时使用。
|
||
---
|
||
|
||
hy3d 是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 CLI 与 Python 客户端，通过 `pipx install hy3d`（或 `pip install hy3d`）全局安装，**独立于任何仓库工作**。命令入口即 PATH 上的 **`hy3d`**（源码仓库 bin/hy3d shim 是免安装备选，一般不需要）。
|
||
|
||
## 前置条件
|
||
|
||
```bash
|
||
hy3d auth status # 先跑这个——验证安装与登录状态
|
||
# 退出码 0 + "登录有效 ✓" 即一切就绪
|
||
```
|
||
|
||
若命令不存在（未发布 PyPI，需从仓库安装）：
|
||
```bash
|
||
pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"
|
||
# 或克隆后 pipx install ".[browser]"；纯源码运行见 README 安装节
|
||
```
|
||
|
||
## Setup
|
||
|
||
无安装步骤。唯一需要的文件：登录 cookie `~/.config/hy3d/cookies.txt`（2026-08-15 曾登录，可能随时过期，过期按下方"重新登录"处理）。
|
||
|
||
## Run（agent 路径）
|
||
|
||
```bash
|
||
hy3d auth status # 登录体检（最先跑）
|
||
hy3d quota # 配额（2026-08-15 实测 20/20）
|
||
hy3d list # 作品列表（实测 7 个作品）
|
||
hy3d formats <creationsId>
|
||
hy3d download <creationsId> --format glb -o model.glb
|
||
hy3d text "a ceramic teapot" --wait # 文生 3D（消耗 4 配额）轮询到完成
|
||
# 更多: status/user/count/image/sketch/animate/texture/topo/cancel/share
|
||
# 全部支持 --json；生成命令支持 --wait/--style/--title
|
||
```
|
||
|
||
**退出码**（agent 分支判断依据，已实测）：
|
||
|
||
| 码 | 含义 | 处理 |
|
||
|---|---|---|
|
||
| 0 | 成功 | — |
|
||
| 1 | 环境/网络/参数/4xx | 看 stderr |
|
||
| 2 | 认证失败（token 无效/过期） | 重新登录（需人工，见下） |
|
||
| 3 | cookie 缺失 | 重新登录（需人工，见下） |
|
||
|
||
实测记录（2026-08-15）：`auth status`/`quota`/`list`/`count`/`user`/`formats`/`download`（下载预览图验证过）全部通过；`text --wait` 已验证提交+轮询框架，未跑完整生成（消耗配额）。
|
||
|
||
## 重新登录（退出码 2/3 时唯一出路）
|
||
|
||
**必须由人类用户在真实终端**（Claude 的 `!` 前缀 stdin 非交互，`input()` 会 EOF）运行：
|
||
|
||
```bash
|
||
hy3d-login # 邮箱验证码登录（browser 扩展）
|
||
```
|
||
|
||
输邮箱 → 收验证码 → 输验证码，cookie 自动存回 `~/.config/hy3d/cookies.txt`。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
|
||
|
||
## Python API（同一安装）
|
||
|
||
```python
|
||
from hy3d import Hunyuan3DAPIComplete, upload_image
|
||
api = Hunyuan3DAPIComplete()
|
||
print(api.get_quota_info())
|
||
```
|
||
|
||
## Test（离线自检）
|
||
|
||
```bash
|
||
python -m hy3d.sign # 在 pipx venv 内（~/.local/share/pipx/venvs/hy3d/bin/python3）
|
||
# 输出含「派生密钥: Hf6d6KFB3D」即签名算法正确
|
||
```
|
||
|
||
---
|
||
|
||
## Gotchas
|
||
|
||
- **`!` 前缀跑登录必 EOF** —— `input()` 在管道 stdin 上直接 `EOFError`。登录必须真实终端；agent 只能引导用户。
|
||
- **401 两种码都证明签名正确** —— `"code":"20001"`=token 过期（重登）；`"code":"999"`=cookie 无用户。
|
||
- **不存在的 creationsId → HTTP 400 空 body**（CLI 归为退出码 1），不是 JSON 错误。
|
||
- **文生 3D 一次消耗 4 次配额**（`count=4` 固定）；图生 3D 等消耗 1 次。
|
||
- **配置目录 `~/.config/hy3d` 独立于仓库**——卸载重装/删仓库不影响登录态。
|
||
- **generation 类命令（text/image/animate/...）未完整跑通过**——验证到提交与轮询框架；大规模使用前先 `hy3d auth status`。
|
||
|
||
## Troubleshooting
|
||
|
||
- **`hy3d auth status` 退出码 2**：token 过期。让人在真实终端跑 `hy3d-login`。
|
||
- **退出码 3**：cookie 缺失。同上，或检查 `HY3D_COOKIES` 是否指向错误路径。
|
||
- **`command not found: hy3d`**：`pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"`（browser 扩展可选，见 README）。
|
||
- **`EOFError`（登录时）**：stdin 非交互，换真实终端。
|
||
- **`401` + 'token无效'**：重登，不是代码 bug。 |