diff --git a/.claude/skills/run-hunyuan3dweb/SKILL.md b/.claude/skills/run-hy3d/SKILL.md similarity index 71% rename from .claude/skills/run-hunyuan3dweb/SKILL.md rename to .claude/skills/run-hy3d/SKILL.md index 6ae6319..ddb2276 100644 --- a/.claude/skills/run-hunyuan3dweb/SKILL.md +++ b/.claude/skills/run-hy3d/SKILL.md @@ -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 diff --git a/README.md b/README.md index 4ab840c..e9cfb5b 100644 --- a/README.md +++ b/README.md @@ -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`） ## 文件结构 diff --git a/README_CN.md b/README_CN.md index 98698e4..216a393 100644 --- a/README_CN.md +++ b/README_CN.md @@ -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`） ## 文件结构 diff --git a/README_REVERSE_ENGINEERING.md b/README_REVERSE_ENGINEERING.md index 71652ff..7c5d966 100644 --- a/README_REVERSE_ENGINEERING.md +++ b/README_REVERSE_ENGINEERING.md @@ -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 diff --git a/README_REVERSE_ENGINEERING_CN.md b/README_REVERSE_ENGINEERING_CN.md index fc03fff..6fb52c9 100644 --- a/README_REVERSE_ENGINEERING_CN.md +++ b/README_REVERSE_ENGINEERING_CN.md @@ -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() # 查询配额 diff --git a/doc/api.md b/doc/api.md index 490be96..4d27d28 100644 --- a/doc/api.md +++ b/doc/api.md @@ -8,7 +8,7 @@ Cookie 会话认证。登录后由浏览器自动携带 `sessionid` 等 Cookie。 -持久化数据保存在 `~/.config/hunyuan3dweb/profile`，CloakBrowser 复用该目录即可保持登录态。 +持久化数据保存在 `~/.config/hy3d/profile`，CloakBrowser 复用该目录即可保持登录态。 --- diff --git a/hy3d/browser/login.py b/hy3d/browser/login.py index c007f38..f4f66bb 100644 --- a/hy3d/browser/login.py +++ b/hy3d/browser/login.py @@ -3,7 +3,7 @@ 腾讯混元3D 邮箱验证码登录 CLI 工具 (CloakBrowser 持久化版本) 第一次输入邮箱回车后自动发送验证码 第二次输入验证码后回车自动点击登录按钮 -登录状态会自动保存到 ~/.config/hunyuan3dweb/profile，下次运行无需重新登录 +登录状态会自动保存到 ~/.config/hy3d/profile，下次运行无需重新登录 """ import argparse diff --git a/hy3d/cli.py b/hy3d/cli.py index 18d66b5..eda1090 100644 --- a/hy3d/cli.py +++ b/hy3d/cli.py @@ -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="查询配额") diff --git a/hy3d/config.py b/hy3d/config.py index ec4b2b6..6fdb91a 100644 --- a/hy3d/config.py +++ b/hy3d/config.py @@ -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