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

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。