feat: ship Claude Code skill in repo with install script

- 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

.claude/skills/run-hunyuan3dweb/SKILL.md

@@ -1,87 +0,0 @@
----
-name: run-hunyuan3dweb
-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`）、浏览器登录工具。
-
-驱动入口只有一个：**`bin/hy3d`**（免安装 shim，自动设置 PYTHONPATH 并转发到 `python3 -m hy3d.cli`）。也可 `pip install hy3d` 后用 PATH 上的 `hy3d`。下文路径相对仓库根。
-
-## 前置条件
-
-```bash
-python3 --version                      # ≥3.9 ✅ (本机 3.13.12)
-python3 -c "import requests"           # 缺则: pip install requests
-```
-
-浏览器功能（登录/抓包）另需 `playwright`、`cloakbrowser`、`chromium`、`xvfb-run`——本机均已装好。
-
-## Setup
-
-无安装步骤。仅需登录 cookie：`~/.config/hunyuan3dweb/cookies.txt`（2026-08-15 曾登录，cookie 可能随时过期，过期用下方 auth 流程处理）。
-
-## Run（agent 路径）
-
-```bash
-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`（下载 512×512 PNG 预览验证过）；`text --wait` 已验证提交+轮询框架，未在容器内跑完整生成（消耗配额）。
-
-## 重新登录（退出码 2/3 时唯一出路）
-
-**必须由人类用户在真实终端**（Claude 的 `!` 前缀 stdin 非交互，`input()` 会 EOF）运行：
-
-```bash
-python -m hy3d.browser.login    # 或安装后: hy3d-login
-```
-
-输邮箱 → 收验证码 → 输验证码，cookie 自动存回 `~/.config/hunyuan3dweb/cookies.txt`。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
-
-## Run（人类路径）
-
-```bash
-pip install -e ".[browser]"      # 可选，装好后 hy3d 直接进 PATH
-hy3d quota
-```
-
-## Test（离线自检）
-
-```bash
-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/hunyuan3dweb` 不变**——改名后路径改了会丢掉已登录的 cookie。
-- **生成类命令（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` 重复导入的假警报，无害。

README.md

@@ -8,12 +8,32 @@
 
 ## 安装
 
+本项目**不发布到 PyPI**——通过克隆仓库安装（推荐先用 [pipx](https://pipx.pypa.io/) 隔离环境；或用 venv + pip）：
+
 ```bash
-pip install hy3d          # 纯 API 客户端
+# 1. 克隆仓库
-pip install "hy3d[browser]"  # 额外安装浏览器工具（登录/抓包/浏览器自动化）
+git clone https://gitea.akasei.top/KawasakiAkasei/hy3d.git
+cd hy3d
+
+# 2. 安装（pipx 装进独立 venv，hy3d 命令进 PATH）
+pipx install ".[browser]"
+
+# 3. 验证
+hy3d auth status
 ```
 
-不安装也能用——克隆仓库后直接用源码跑（无需 `pip install`）：
+不想保留仓库副本也能直接装：
+
+```bash
+pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"
+```
+
+> **「browser」扩展**提供登录/抓包/浏览器自动化（cloakbrowser + playwright）；
+> 只调用 API 可以省略。已装过纯客户端、想补 browser 扩展：
+> `cd hy3d && pipx install --force ".[browser]"`。
+> **私有仓库**场景：clone 用 SSH —— `git clone git@gitea.akasei.top:KawasakiAkasei/hy3d.git`；git 直装同理。
+
+不安装也能用——直接以源码方式运行（无需 pip install）：
 
 ```bash
 cd hy3d
@@ -27,7 +47,7 @@ PYTHONPATH=$PWD python3 -m hy3d.cli quota
 ```bash
 hy3d auth login
 # → 按提示: 输邮箱 → 收验证码 → 输验证码
-# → cookie 自动保存到 ~/.config/hunyuan3dweb/cookies.txt
+# → cookie 自动保存到 ~/.config/hy3d/cookies.txt
 ```
 
 验证登录与配额：
@@ -137,12 +157,12 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
 | `hy3d-sniffer` | API 请求/响应抓包（`api_requests.log.json`） |
 | `hy3d-generate <img> [wait]` | 浏览器内图生 3D（走浏览器签名，适合对照验证） |
 
-需要 `pip install "hy3d[browser]"`（cloakbrowser + playwright）。
+需要 browser 扩展（安装时加 `[browser]`，见上文安装节）。
 
 ## 配置文件与目录
 
-- cookie：`~/.config/hunyuan3dweb/cookies.txt`（路径保持不变，避免重新登录）
+- cookie：`~/.config/hy3d/cookies.txt`（全新目录，cookie 已随搬迁保留）
-- 浏览器 profile：`~/.config/hunyuan3dweb/profile`
+- 浏览器 profile：`~/.config/hy3d/profile`
 - 环境变量：`HY3D_COOKIES`（cookie 路径）、`HY3D_JSON=1`（等同 `--json`）
 
 ## 文件结构
@@ -157,6 +177,16 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
 | `hy3d/config.py` | 配置路径管理 |
 | `hy3d/browser/` | 登录 / 抓包 / 浏览器自动化工具 |
 
+## Claude Code Skill（可选）
+
+`skill/run-hy3d/` 附带一个 Claude Code skill：让 agent 直接驱动 `hy3d`（查配额、文生 3D、下载模型、诊断登录状态与退出码）。安装：
+
+```bash
+./skill/install.sh        # 安装到 ~/.claude/skills/run-hy3d
+```
+
+新会话中可用 `/run-hy3d` 调用，或当描述命中时自动加载。卸载：`rm -rf ~/.claude/skills/run-hy3d`。
+
 ## 相关文档
 
 - [reverse engineering 文档](README_REVERSE_ENGINEERING.md) — 签名算法逆向过程与关键常量

README_CN.md

@@ -8,12 +8,32 @@
 
 ## 安装
 
+本项目**不发布到 PyPI**——通过克隆仓库安装（推荐先用 [pipx](https://pipx.pypa.io/) 隔离环境；或用 venv + pip）：
+
 ```bash
-pip install hy3d             # 纯 API 客户端
+# 1. 克隆仓库
-pip install "hy3d[browser]"  # 额外安装浏览器工具（登录/抓包/浏览器自动化）
+git clone https://gitea.akasei.top/KawasakiAkasei/hy3d.git
+cd hy3d
+
+# 2. 安装（pipx 装进独立 venv，hy3d 命令进 PATH）
+pipx install ".[browser]"
+
+# 3. 验证
+hy3d auth status
 ```
 
-不安装也能用——克隆仓库后直接用源码跑（无需 `pip install`）：
+不想保留仓库副本也能直接装：
+
+```bash
+pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"
+```
+
+> **「browser」扩展**提供登录/抓包/浏览器自动化（cloakbrowser + playwright）；
+> 只调用 API 可以省略。已装过纯客户端、想补 browser 扩展：
+> `cd hy3d && pipx install --force ".[browser]"`。
+> **私有仓库**场景：clone 用 SSH —— `git clone git@gitea.akasei.top:KawasakiAkasei/hy3d.git`；git 直装同理。
+
+不安装也能用——直接以源码方式运行（无需 pip install）：
 
 ```bash
 cd hy3d
@@ -27,7 +47,7 @@ PYTHONPATH=$PWD python3 -m hy3d.cli quota
 ```bash
 hy3d auth login
 # → 按提示: 输邮箱 → 收验证码 → 输验证码
-# → cookie 自动保存到 ~/.config/hunyuan3dweb/cookies.txt
+# → cookie 自动保存到 ~/.config/hy3d/cookies.txt
 ```
 
 验证登录与配额：
@@ -137,12 +157,12 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
 | `hy3d-sniffer` | API 请求/响应抓包（`api_requests.log.json`） |
 | `hy3d-generate <img> [wait]` | 浏览器内图生 3D（走浏览器签名，适合对照验证） |
 
-需要 `pip install "hy3d[browser]"`（cloakbrowser + playwright）。
+需要 browser 扩展（安装时加 `[browser]`，见上文安装节）。
 
 ## 配置与目录
 
-- cookie：`~/.config/hunyuan3dweb/cookies.txt`（路径保持不变，避免重新登录）
+- cookie：`~/.config/hy3d/cookies.txt`（全新目录，cookie 已随搬迁保留）
-- 浏览器 profile：`~/.config/hunyuan3dweb/profile`
+- 浏览器 profile：`~/.config/hy3d/profile`
 - 环境变量：`HY3D_COOKIES`（cookie 路径）、`HY3D_JSON=1`（等同 `--json`）
 
 ## 文件结构
@@ -157,6 +177,16 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
 | `hy3d/config.py` | 配置路径管理 |
 | `hy3d/browser/` | 登录 / 抓包 / 浏览器自动化工具 |
 
+## Claude Code Skill（可选）
+
+`skill/run-hy3d/` 附带一个 Claude Code skill：让 agent 直接驱动 `hy3d`（查配额、文生 3D、下载模型、诊断登录状态与退出码）。安装：
+
+```bash
+./skill/install.sh        # 安装到 ~/.claude/skills/run-hy3d
+```
+
+新会话中可用 `/run-hy3d` 调用，或当描述命中时自动加载。卸载：`rm -rf ~/.claude/skills/run-hy3d`。
+
 ## 相关文档
 
 - [逆向工程文档](README_REVERSE_ENGINEERING_CN.md) — 签名算法逆向过程与关键常量

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
+# Login state is automatically saved to ~/.config/hy3d/profile
-# Cookies are also exported to ~/.config/hunyuan3dweb/cookies.txt
+# 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

@@ -90,8 +90,8 @@ resource_url = upload_image("/path/to/image.png")
 ```bash
 hy3d-login
 # 按提示输入邮箱和验证码
-# 登录状态自动保存到 ~/.config/hunyuan3dweb/profile
+# 登录状态自动保存到 ~/.config/hy3d/profile
-# Cookie 同时导出到 ~/.config/hunyuan3dweb/cookies.txt
+# 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

@@ -8,7 +8,7 @@
 
 Cookie 会话认证。登录后由浏览器自动携带 `sessionid` 等 Cookie。
 
-持久化数据保存在 `~/.config/hunyuan3dweb/profile`，CloakBrowser 复用该目录即可保持登录态。
+持久化数据保存在 `~/.config/hy3d/profile`，CloakBrowser 复用该目录即可保持登录态。
 
 ---
 

hy3d/browser/login.py

@@ -3,7 +3,7 @@
 腾讯混元3D 邮箱验证码登录 CLI 工具 (CloakBrowser 持久化版本)
 第一次输入邮箱回车后自动发送验证码
 第二次输入验证码后回车自动点击登录按钮
-登录状态会自动保存到 ~/.config/hunyuan3dweb/profile，下次运行无需重新登录
+登录状态会自动保存到 ~/.config/hy3d/profile，下次运行无需重新登录
 """
 
 import argparse

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="查询配额")
@@ -468,4 +468,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

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
 

pyproject.toml

@@ -26,4 +26,4 @@ hy3d-generate = "hy3d.browser.generator:main"
 
 [tool.setuptools.packages.find]
 where = ["."]
-include = ["hy3d*"]
+include = ["hy3d*"]

skill/install.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# 安装 hy3d 的 Claude Code skill 到用户级目录（~/.claude/skills/run-hy3d）
+# 用法: ./skill/install.sh
+set -euo pipefail
+
+SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/run-hy3d" && pwd)"
+DEST="$HOME/.claude/skills/run-hy3d"
+
+mkdir -p "$(dirname "$DEST")"
+rm -rf "$DEST"
+cp -r "$SRC" "$DEST"
+echo "✓ skill 已安装到 $DEST"
+echo "  新会话中即可用 /run-hy3d；描述命中时自动加载"

skill/run-hy3d/SKILL.md

@@ -0,0 +1,91 @@
+---
+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。