用 Tripo API 为 Three.js 游戏生成…

通过 Tripo API 生成并处理适用于 Three.js 的 3D 资产（文生 3D、图生 3D、贴图、绑定、动画重定向、风格化、格式转换与下载）时的完整操作流程。

适用场景

解决思路

1. 从实际加载的技能文件解析 `<this-skill-dir>`，优先解析其同级技能目录，再使用运行器发现的路径；不要混用已安装版本，也不要假设某个固定的 home 目录。
2. 按需读取参考文件：`references/api-notes.md` 用于 endpoint 与任务决策、模型版本、轮询、后处理、转换、绑定、动画、下载；`references/threejs-integration.md` 用于将输出导入浏览器游戏、GLB/FBX 加载、root motion、动画接线；`references/image-generator-workflows.md` 用于搭配 `threejs-image-generator` 生成概念、贴图、UI 美术或图生 3D 输入。
3. API key 通过 `--api-key` 或 `TRIPO_API_KEY` 读取；key 绝不写入技能文件、游戏代码或报告中。用 `python3 <this-skill-dir>/scripts/threejs_3d_asset.py probe` 检查（输出 TRIPO_API_KEY=SET|MISSING）。若仅在 shell profile 中定义的 key 在进程环境中缺失，改用 `threejs-game-director/scripts/probe_asset_credentials.sh`，它会 source profile 并一次性探测三个 provider。
4. 下载 URL 过期很快——任务成功后立即下载。
5. 文生 3D（默认用于高级主角模型）：运行 `text` 子命令，传入 `--prompt`（描述游戏可用模型、清晰剪影、PBR 材质、干净拓扑、居中 pivot、正面朝向、无文字）、`--model-version v3.1-20260211`、`--texture-quality detailed`、`--geometry-quality detailed`、`--checkpoint`、`--wait --download --out-dir`。
6. 图生 3D：运行 `image` 子命令，传入 `--image`、`--model-version v3.1-20260211`、`--enable-image-autofix`、`--texture-alignment original_image`、`--texture-quality detailed`、`--wait --download --out-dir`。
7. 用 `status TASK_ID` 查询状态，用 `download TASK_ID --out-dir` 下载，用 `postprocess --type conversion --original-task-id TASK_ID --format GLTF --face-limit 20000 --wait --download --out-dir` 做后处理；后处理类型包括 `texture_model`、`animate_prerigcheck`、`animate_rig`、`animate_retarget`、`conversion`、`stylize_model`。
8. 动画角色流水线：运行 `character-pipeline`，传入 `--prompt`、`--animations preset:idle,preset:walk,preset:run,preset:jump`、`--checkpoint`、`--stop-after model`、`--out-dir`；检查下载的模型/预览后用 `resume CHECKPOINT --stop-after rig` 继续；检查验证过的 rig 后用 `resume CHECKPOINT --stop-after animations` 继续。
9. 四足角色：运行 `character-pipeline`，传入 `--rig-type quadruped`、`--animations preset:quadruped:walk`、`--checkpoint`、`--stop-after model`、`--out-dir`。
10. `--checkpoint PATH` 在 `text`、`image`、`postprocess`、`character-pipeline` 上可选；它立即记录已接受的任务 ID、阶段状态和已下载文件指纹；checkpoint 中不写 API key 或签名输出 URL。每个任务使用独立 checkpoint。已存在的 checkpoint 必须 resume，不能覆盖；并发使用会被锁定。
11. 后台单任务生成时省略 `--wait`，保留打印的任务 ID/checkpoint，稍后运行 `resume CHECKPOINT`。单任务 resume 只等待/下载该任务，不会添加绑定。角色 resume 复用已完成阶段并继续到动画，除非用 `--stop-after model|rig|animations` 限制本次调用。凭据仍来自当前环境。checkpoint 记录绝对本地路径，因此保持其引用的文件在原位。
12. 辅助脚本对安全的状态/下载读取做有界退避重试，绝不重试付费任务提交。缺失凭据、额度耗尽、无效输入、瞬时错误和不确定提交会被分别报告。中断时 resume 现有任务而不是重新开始。若 POST 可能已成功但未收到任务 ID，在 provider 历史中查找并用 `resume CHECKPOINT --task-id RECOVERED_ID`；不要编造 ID 或盲目# 提交替代任务。若无可恢复 ID，在任何可能重复扣费前报告不确定性。
13. 协调型游戏遵循 director 的 `references/asset-recovery.md`；生成运行期间继续独立实现。明确要求程序化或无外部服务的请求覆盖生成资产默认值。在项目笔记中记录待处理任务和用户修正，保留已完成资产而不是重复生成。
14. 绑定与动画规则：将角色生成为单一融合网格——保持 `--quad` 和 `--generate-parts` 关闭（`generate_parts` 会禁用贴图，`quad` 强制 FBX 输出）。
15. 要求全身 T-pose 或 A-pose，手臂远离身体，对称，剪影上不融合道具。在绑定前检查渲染预览确实处于该姿势；若不是则重新生成。
16. 先运行 `animate_prerigcheck`（它不接受模型版本，不花钱）并使用检测到的 `rig_type`。`riggable=false` 意味着用更清晰的姿势重新生成，而不是强行绑定。
17. Rig 版本按体型路由：人形使用 `v1.0-20240301`——带 twist 骨骼的解剖骨架和大型 `preset:biped:*` 库。v2.x 肢体链绑定器在人形网格上 0/16 成功，无论是否装甲，总是产生不对称链。生物使用 `v2.5-20260210`。`character-pipeline` 自动路由。
18. `riggable=true` 不保证可用 rig。在重定向前验证骨架——`validate-rig rig-model.glb --rig-type biped`——同时检查骨骼存在性和链深度，因为 1 骨骼的腿会扭曲每个 clip。缺失或畸形的 rig GLB 即为失败，包括使用 `--force-rig` 时。自动绑定是非确定性的：失败时在选定预算内重试 rig 任务（约 25 credits）再重新生成模型。装甲硬表面角色需要最多重试。
19. `animate_retarget` 接受 **rig** 任务 ID，不是生成任务 ID。非 biped rig 每任务最多批量 5 个 preset；批量 clip 按请求顺序返回为 `NlaTrack`、`NlaTrack.001`、…，因此按索引映射并在导入后重命名。
20. 用 `--model-version default` 重定向 v1.0 rig——枚举会以 HTTP 400 code 2017 拒绝显式 `v1.0-20240301`，但服务器默认能处理它们。
21. v1.0 重定向必须使用 `--out-format fbx`（脚本强制）：Tripo 在此路径上的 GLB bake 会把 twist 骨骼变换写入错误空间，导致肢体塌陷进躯干。v2.5 生物重定向用 GLB 没问题。
22. **绝不传 `--animate-in-place`。** 它会破坏 bake——v1.0 上肢体镜像和交叉，v2.5 上蒙皮爆炸。保持 root motion 烘焙并在导入时剥离；引擎代码片段在 `references/threejs-integration.md`。
23. 生物每种获得一个移动 preset，且没有 `preset:attack`（使用 `preset:slash` 或 `preset:shoot`）。生物的网格站姿决定 preset 的读感——直立龙上的四足行走看起来像人走路，因此按动画期望的站姿生成生物。
24. 多模式生物（既爬行又飞行的龙）需要同一模型绑定两次：地面 rig 类型用于移动，`avian` 用于翼链。
25. 当将重定向 Tripo preset 时使用 `--spec tripo`（默认）；`--spec mixamo` rig 无法被 Tripo 重定向，仅用于外部流水线。
26. 下载后运行 `validate-animation clip.glb`（标记缩放轨道、肢体拉伸位移、极端旋转、每 clip 时长和通道覆盖），然后在接线 `AnimationMixer` 前检查 `gltf.animations` 名称和数量。
27. 质量：用材质、剪影、相机可读性、比例和游戏用途约束改进用户 prompt。请求 GLB/PBR 并让面数限制和贴图质量匹配性能预算；移动端倾向 `smart_low_poly`、`face_limit` 或后续低多边形后处理。将生成的 3D 用作主角内容，周围道具套件程序化构建。
28. 集成后检查未暂停的游戏内运动：clip 过渡、变形、root motion、脚滑和攻击/接触时机。对动画工作使用 QA 运动检查；成功下载或骨架检查不是好动画的证明。
29. 报告任务 ID、checkpoint/输出路径、模型版本、贴图和几何设置、动画、转换设置、Three.js 导入说明、观察到的运动以及任何失败。将详细证据放入项目产物供 lead 的合并报告使用。

适用边界 · 注意事项

• 需要 Tripo API key 和付费额度，不适用于无外部服务或纯程序化资产需求。
• 不适用于非 Three.js 引擎或不需要浏览器游戏资产的场景。
• 绑定和动画重定向对非人形/非四足体型支持有限，且自动绑定非确定性、可能反复失败。