KawasakiAkasei
3e85d6f987
- config dir renamed hunyuan3dweb -> hy3d (cookies/profile moved intact, auth re-verified: quota 20/20) - cli.py/login.py/READMEs/doc paths updated to ~/.config/hy3d - skill: delete run-hunyuan3dweb, add run-hy3d pointing at bin/hy3d - zero stale old-name references remain (one historical note in skill)
4.3 KiB
4.3 KiB
name, description
| name | description |
|---|---|
| run-hy3d | 运行并驱动腾讯混元 3D（hy3d）。当用户要求：跑 hy3d、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证这个项目能否工作时使用。 |
hy3d（仓库 gitea.akasei.top/KawasakiAkasei/hy3d）是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 CLI 与 Python 客户端：签名算法（HMAC-SHA256，密钥派生 Hf6d6KFB3D）、纯 HTTP API + 18 条子命令的 CLI、浏览器登录工具。
驱动入口只有一个：bin/hy3d（免安装 shim，自动设置 PYTHONPATH 转发到 python3 -m hy3d.cli）。也可 pip install hy3d 后直接用 PATH 上的 hy3d。下文路径相对仓库根。
前置条件
python3 --version # ≥3.9 ✅ (本机 3.13.12)
python3 -c "import requests" # 缺则: pip install requests
浏览器功能（登录/抓包）另需 playwright、cloakbrowser、chromium、xvfb-run——本机均已装好。
Setup
无安装步骤。仅需登录 cookie：~/.config/hy3d/cookies.txt（2026-08-15 曾登录并随目录改名搬迁保留，可能随时过期，过期用下方 auth 流程处理）。
Run（agent 路径）
bin/hy3d auth status # 登录体检（最先跑这个）
bin/hy3d quota # 配额
bin/hy3d list # 作品列表（2026-08-15 实测 7 个作品）
bin/hy3d formats <creationsId>
bin/hy3d download <creationsId> --format glb -o model.glb
bin/hy3d text "a ceramic teapot" --wait # 文生 3D（消耗 4 配额）轮询到完成
# 更多: status/user/count/image/sketch/animate/texture/topo/cancel/share
退出码（agent 分支判断的依据，已实测）：
| 码 | 含义 | 处理 |
|---|---|---|
| 0 | 成功 | — |
| 1 | 环境/网络/参数/4xx | 看 stderr |
| 2 | 认证失败（token 无效/过期） | hy3d auth login（需人工，见下） |
| 3 | cookie 缺失 | hy3d auth login（需人工，见下） |
典型工作流（2026-08-15 全部实测通过）：auth status → quota → list → 对历史作品 formats/download（下载预览图验证过）；text --wait 已验证提交+轮询框架，未在容器内跑完整生成（消耗配额）。
重新登录（退出码 2/3 时唯一出路）
必须由人类用户在真实终端（Claude 的 ! 前缀 stdin 非交互，input() 会 EOF）运行：
python -m hy3d.browser.login # 或安装后: hy3d-login
输邮箱 → 收验证码 → 输验证码，cookie 自动存回 ~/.config/hy3d/cookies.txt。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
Run（人类路径）
pip install -e ".[browser]" # 可选，装好后 hy3d 直接进 PATH
hy3d quota
Test（离线自检）
python3 -m hy3d.sign
# 输出含「派生密钥: Hf6d6KFB3D」即签名算法正确
Gotchas
!前缀跑登录必 EOF ——input()在管道 stdin 上直接EOFError: EOF when reading a line。登录必须真实终端；agent 只能引导用户。- 401 两种码都证明签名正确 ——
"code":"20001"=token 过期（重登）；"code":"999"=cookie 无用户。服务端能分类错误说明请求格式被完全接受。 - 不存在的 creationsId → HTTP 400 空 body（CLI 归为退出码 1），不是 JSON 错误。
- 文生 3D 一次消耗 4 次配额（
count=4固定）；图生 3D 等消耗 1 次。 - 配置目录是
~/.config/hy3d（2026-08-15 由旧名~/.config/hunyuan3dweb整体搬迁，cookie 原样保留）。 - generation 类命令（text/image/animate/...）未在容器内完整跑通——验证到提交与轮询框架；正式大规模使用前先
hy3d auth status确认在线。
Troubleshooting
hy3d auth status退出码 2：token 过期。让人在真实终端跑python -m hy3d.browser.login。- 退出码 3：cookie 文件不存在/为空。同上，或检查
HY3D_COOKIES是否指向了错误路径。 EOFError（登录时）：stdin 非交互，换真实终端。401+ 'token无效'：重登，不是代码 bug。python3 -m hy3d.sign的 RuntimeWarning：runpy 与__init__.py重复导入的假警报，无害。