KawasakiAkasei/hy3d
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: move config dir to ~/.config/hy3d, replace skill with run-hy3d

Browse Source 
- 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)
This commit is contained in:
KawasakiAkasei
2026-08-15 22:44:56 +08:00
parent acfe5e7ac2
commit 3e85d6f987
9 changed files with 26 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/run-hunyuan3dweb/SKILL.md → .claude/skills/run-hy3d/SKILL.md
+8 -8
View File
@@ -1,11 +1,11 @@
---
name: run-hunyuan3dweb
name: run-hy3d
description: 运行并驱动腾讯混元 3D（hy3d）。当用户要求：跑 hy3d、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证这个项目能否工作时使用。
---
本项目（仓库 gitea.akasei.top/KawasakiAkasei/hy3d）是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 CLI 与 Python 客户端：签名算法（HMAC-SHA256 密钥派生 `Hf6d6KFB3D`）、纯 HTTP API + CLI（`hy3d`）、浏览器登录工具。
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`。下文路径相对仓库根。
驱动入口只有一个：**`bin/hy3d`**（免安装 shim，自动设置 PYTHONPATH 转发到 `python3 -m hy3d.cli`）。也可 `pip install hy3d` 后直接用 PATH 上的 `hy3d`。下文路径相对仓库根。
## 前置条件
@@ -18,7 +18,7 @@ python3 -c "import requests" # 缺则: pip install requests
## Setup
无安装步骤。仅需登录 cookie：`~/.config/hunyuan3dweb/cookies.txt`（2026-08-15 曾登录，cookie 可能随时过期，过期用下方 auth 流程处理）。
无安装步骤。仅需登录 cookie：`~/.config/hy3d/cookies.txt`（2026-08-15 曾登录并随目录改名搬迁保留，可能随时过期，过期用下方 auth 流程处理）。
## Run（agent 路径）
@@ -41,7 +41,7 @@ bin/hy3d text "a ceramic teapot" --wait # 文生 3D（消耗 4 配额）轮
| 2 | 认证失败（token 无效/过期） | `hy3d auth login`（需人工，见下） |
| 3 | cookie 缺失 | `hy3d auth login`（需人工，见下） |
典型工作流（2026-08-15 全部实测通过）：`auth status` → `quota` → `list` → 对历史作品 `formats`/`download`（下载 512×512 PNG 预览验证过）；`text --wait` 已验证提交+轮询框架，未在容器内跑完整生成（消耗配额）。
典型工作流（2026-08-15 全部实测通过）：`auth status` → `quota` → `list` → 对历史作品 `formats`/`download`（下载预览图验证过）；`text --wait` 已验证提交+轮询框架，未在容器内跑完整生成（消耗配额）。
## 重新登录（退出码 2/3 时唯一出路）
@@ -51,7 +51,7 @@ bin/hy3d text "a ceramic teapot" --wait # 文生 3D（消耗 4 配额）轮
python -m hy3d.browser.login # 或安装后: hy3d-login
```
输邮箱 → 收验证码 → 输验证码，cookie 自动存回 `~/.config/hunyuan3dweb/cookies.txt`。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
输邮箱 → 收验证码 → 输验证码，cookie 自动存回 `~/.config/hy3d/cookies.txt`。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
## Run（人类路径）
@@ -75,8 +75,8 @@ python3 -m hy3d.sign
- **401 两种码都证明签名正确** —— `"code":"20001"`=token 过期（重登）；`"code":"999"`=cookie 无用户。服务端能分类错误说明请求格式被完全接受。
- **不存在的 creationsId → HTTP 400 空 body**（CLI 归为退出码 1），不是 JSON 错误。
- **文生 3D 一次消耗 4 次配额**（`count=4` 固定）；图生 3D 等消耗 1 次。
- **配置目录刻意保持 `~/.config/hunyuan3dweb` 不变**——改名后路径改了会丢掉已登录的 cookie。
- **生成类命令（text/image/animate/...）未在容器内完整跑通**——验证到提交与轮询框架；正式大规模使用前先 `hy3d auth status` 确认在线，并接受首单可能失败的调试成本。
- **配置目录是 `~/.config/hy3d`**（2026-08-15 由旧名 `~/.config/hunyuan3dweb` 整体搬迁，cookie 原样保留）。
- **generation 类命令（text/image/animate/...）未在容器内完整跑通**——验证到提交与轮询框架；正式大规模使用前先 `hy3d auth status` 确认在线。
## Troubleshooting
README.md
+3 -3
View File
@@ -27,7 +27,7 @@ PYTHONPATH=$PWD python3 -m hy3d.cli quota
```bash
hy3d auth login
# → 按提示: 输邮箱 → 收验证码 → 输验证码
# → cookie 自动保存到 ~/.config/hunyuan3dweb/cookies.txt
# → cookie 自动保存到 ~/.config/hy3d/cookies.txt
```
验证登录与配额：
@@ -141,8 +141,8 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
## 配置文件与目录
- cookie：`~/.config/hunyuan3dweb/cookies.txt`（路径保持不变，避免重新登录）
- 浏览器 profile：`~/.config/hunyuan3dweb/profile`
- cookie：`~/.config/hy3d/cookies.txt`（全新目录，cookie 已随搬迁保留）
- 浏览器 profile：`~/.config/hy3d/profile`
- 环境变量：`HY3D_COOKIES`（cookie 路径）、`HY3D_JSON=1`（等同 `--json`）
## 文件结构
README_CN.md
+3 -3
View File
@@ -27,7 +27,7 @@ PYTHONPATH=$PWD python3 -m hy3d.cli quota
```bash
hy3d auth login
# → 按提示: 输邮箱 → 收验证码 → 输验证码
# → cookie 自动保存到 ~/.config/hunyuan3dweb/cookies.txt
# → cookie 自动保存到 ~/.config/hy3d/cookies.txt
```
验证登录与配额：
@@ -141,8 +141,8 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
## 配置与目录
- cookie：`~/.config/hunyuan3dweb/cookies.txt`（路径保持不变，避免重新登录）
- 浏览器 profile：`~/.config/hunyuan3dweb/profile`
- cookie：`~/.config/hy3d/cookies.txt`（全新目录，cookie 已随搬迁保留）
- 浏览器 profile：`~/.config/hy3d/profile`
- 环境变量：`HY3D_COOKIES`（cookie 路径）、`HY3D_JSON=1`（等同 `--json`）
## 文件结构
README_REVERSE_ENGINEERING.md
+3 -3
View File
@@ -90,8 +90,8 @@ resource_url = upload_image("/path/to/image.png")
```bash
hy3d-login
# Follow prompts to enter email and verification code
# Login state is automatically saved to ~/.config/hunyuan3dweb/profile
# Cookies are also exported to ~/.config/hunyuan3dweb/cookies.txt
# Login state is automatically saved to ~/.config/hy3d/profile
# Cookies are also exported to ~/.config/hy3d/cookies.txt
```
**Login State Detection Logic** (dual verification):
@@ -104,7 +104,7 @@ hy3d-login
```python
from hy3d import Hunyuan3DAPI
# Automatically load cookie from ~/.config/hunyuan3dweb/cookies.txt
# Automatically load cookie from ~/.config/hy3d/cookies.txt
api = Hunyuan3DAPI()
# Check quota
README_REVERSE_ENGINEERING_CN.md
+3 -3
View File
@@ -90,8 +90,8 @@ resource_url = upload_image("/path/to/image.png")
```bash
hy3d-login
# 按提示输入邮箱和验证码
# 登录状态自动保存到 ~/.config/hunyuan3dweb/profile
# Cookie 同时导出到 ~/.config/hunyuan3dweb/cookies.txt
# 登录状态自动保存到 ~/.config/hy3d/profile
# Cookie 同时导出到 ~/.config/hy3d/cookies.txt
```
**登录状态检测逻辑**（双重验证）：
@@ -104,7 +104,7 @@ hy3d-login
```python
from hy3d import Hunyuan3DAPI
# 自动从 ~/.config/hunyuan3dweb/cookies.txt 加载 cookie
# 自动从 ~/.config/hy3d/cookies.txt 加载 cookie
api = Hunyuan3DAPI()
# 查询配额
doc/api.md
+1 -1
View File
@@ -8,7 +8,7 @@
Cookie 会话认证。登录后由浏览器自动携带 `sessionid` 等 Cookie。
持久化数据保存在 `~/.config/hunyuan3dweb/profile`，CloakBrowser 复用该目录即可保持登录态。
持久化数据保存在 `~/.config/hy3d/profile`，CloakBrowser 复用该目录即可保持登录态。
---
hy3d/browser/login.py
+1 -1
View File
@@ -3,7 +3,7 @@
腾讯混元3D 邮箱验证码登录 CLI 工具 (CloakBrowser 持久化版本)
第一次输入邮箱回车后自动发送验证码
第二次输入验证码后回车自动点击登录按钮
登录状态会自动保存到 ~/.config/hunyuan3dweb/profile，下次运行无需重新登录
登录状态会自动保存到 ~/.config/hy3d/profile，下次运行无需重新登录
"""
import argparse
hy3d/cli.py
+2 -2
View File
@@ -6,7 +6,7 @@ hy3d — 腾讯混元 3D 非官方 CLI
全局选项（必须放在命令前）:
--json 机器可读输出（默认 human 格式）
--cookies PATH 指定 cookie 文件（默认 ~/.config/hunyuan3dweb/cookies.txt，可用环境变量 HY3D_COOKIES 覆盖）
--cookies PATH 指定 cookie 文件（默认 ~/.config/hy3d/cookies.txt，可用环境变量 HY3D_COOKIES 覆盖）
退出码:
0 成功
@@ -347,7 +347,7 @@ def build_parser() -> argparse.ArgumentParser:
prog="hy3d",
description="腾讯混元 3D 非官方 CLI（需要登录 cookie，见 hy3d auth login）")
p.add_argument("--json", action="store_true", help="机器可读 JSON 输出")
p.add_argument("--cookies", default=None, help="cookie 文件路径（默认 ~/.config/hunyuan3dweb/cookies.txt）")
p.add_argument("--cookies", default=None, help="cookie 文件路径（默认 ~/.config/hy3d/cookies.txt）")
sub = p.add_subparsers(dest="command", required=True)
sub.add_parser("quota", help="查询配额")
hy3d/config.py
+2 -2
View File
@@ -6,10 +6,10 @@ from typing import Optional, Tuple
def get_config_dir() -> Path:
"""Return the user configuration directory (kept as `hunyuan3dweb` for path stability)."""
"""Return the user configuration directory (~/.config/hy3d)."""
xdg = os.environ.get("XDG_CONFIG_HOME")
base = Path(xdg) if xdg else Path.home() / ".config"
path = base / "hunyuan3dweb"
path = base / "hy3d"
path.mkdir(parents=True, exist_ok=True)
return path