tripocli/SKILL.md

name, description

name	description
tripo-3d	用 Tripo AI 生成与加工 3D 模型资产：文生3D、图生3D、多视图、批量生成，以及重拓扑、绑定、动画、分割、纹理、PBR、UV、格式导出与下载。适用于需要 3D 模型、角色、道具、建筑或格式转换的场景。

Tripo 3D 生成与加工技能

当用户需要生成 3D 模型、角色、道具、建筑，或对已有模型做重拓扑/绑定/动画/贴图/导出时使用本技能。

调用方式

本技能对应命令行工具 tripocli。按环境选择其一：

tripocli --version                       # 1) 已安装到 PATH（推荐）
<项目目录>/tripocli --version             # 2) 直接用仓库里的入口（零依赖，无需安装）

若尚未安装，进到项目目录后安装（纯标准库，无第三方依赖）：

cd <项目目录>
pip install .        # 用 pyenv 的话，装完执行一次 pyenv rehash

所有命令都支持 --json（放命令前或后都可以），Agent 调用时建议加上。

凭据（只需一次）

CLI 需要 Tripo 的 session cookie 才能换 JWT。不需要浏览器常驻：cookie 约 30 天有效， CLI 每次调用会用 cookie 自动续期 15 分钟的 JWT。

tripocli account add --cookie "ory_kratos_session=..."   # 添加账号（粘贴浏览器 cookie）
tripocli account list                                     # 多账号查看/切换
tripocli serve --open                                     # 网页版账号管理（看积分/有效期）
# 也可用环境变量：export TRIPO_COOKIE="ory_kratos_session=..."

cookie 获取：浏览器 DevTools → Network → 任意 api.tripo3d.ai 请求 → Request Headers → 整条 Cookie。 若命令报 no-credentials，按上面的 account add 提供 cookie 即可。

常用命令

# 账户
tripocli --json balance
tripocli --json quota
tripocli --json assets --size 10

# 文生图（参考图生成，默认 --amount 1 每次只出 1 张以节省额度；人形角色建议加 --t-pose）
tripocli --json img -p "<提示词>" --amount 1 --t-pose --wait -o /abs/path/refs
tripocli --json imgs --size 5
tripocli --json imgmv -i /abs/path/ref.png --wait -o /abs/path/views

# 文生 3D（⚠️ 游戏场景务必加 --face-limit 控制面数或用 --smart-mesh，避免默认 200 万面撑爆显存！）
tripocli --json text -p "<提示词>" --face-limit 15000 --wait -o /abs/path/out.glb
tripocli --json text -p "<提示词>" --smart-mesh --face-limit 20000 --wait -o /abs/path/out.glb

# 图生 3D / 导入模型
tripocli --json image -i /abs/path/photo.png --face-limit 25000 --wait -o /abs/path/out.glb
tripocli --json import -i /abs/path/my_model.glb --wait -o /abs/path/normalized.glb

# 多视角（必须 4 张：前/左/右/后）
tripocli --json multiview --front f.png --left l.png --right r.png --back b.png --wait -o /abs/path/mv.glb

# 批量图生 3D（多结果，-o 传目录）
tripocli --json batch -i a.png,b.png --wait -o /abs/path/outdir

# 后处理（作用于已有项目，需要 project_id）
tripocli --json remesh  -p <project_id> --face-limit 10000 --wait -o low.glb
tripocli --json rig     -p <project_id> --type biped --spec mixamo --wait -o hero_rigged.glb
tripocli --json animate --list
tripocli --json animate -p <project_id> --preset idle --wait -o anim_idle.glb
tripocli --json motion  -p "让角色挥手打招呼" --duration 5 --project <project_id> --wait -o anim_wave.glb
tripocli --json segment -p <project_id> --wait
tripocli --json stylize -p <project_id> --style clay --wait
tripocli --json texture -p <project_id> --resolution 2K --wait
tripocli --json pbr     -p <project_id> --wait
tripocli --json upscale -p <project_id> --wait
tripocli --json uv      -p <project_id> --wait
tripocli --json fill    -p <project_id> --parts all --wait
tripocli --json edit    -p <project_id> --bbox "-1,-1,-1,1,1,1" --face-limit 8000 --wait

# 导出 / 下载 / 本地体检与减面 / 查询 / 取消 / 重命名
tripocli --json export   -p <project_id> -f glb --wait -o model.glb
tripocli --json download --operator <operator_id> -o model.glb
tripocli --json inspect  /abs/path/model.glb
tripocli --json optimize /abs/path/in.glb -o /abs/path/out.glb --faces 15000
tripocli --json optimize /abs/path/in.glb --lods
tripocli --json task status <operator_id>
tripocli --json project <project_id>
tripocli --json cancel --operator <operator_id> --type remesh
tripocli --json rename -p <project_id> --name "New Name"

生成类通用参数

• -m/--model：P2.0 / P1.0（智能网格）、H3.1 / v3.0 / v2.5（高精度）
• --face-limit：面数上限（智能网格默认 25000，高精度默认 2000000）
• --quad：四边面（智能网格默认开启）
• --count 1|2|4：候选数量
• --no-texture / --no-pbr / --no-delight
• --texture-quality standard|detailed、--geometry-quality standard|detailed
• --t-pose、--visibility shareable|private

重要约束

1. 后处理算子会新建 operator：同一项目必须等上一个算子 success 后才能做下一个，否则报 2021 the status of task is not success。用 --wait，或换项目。
2. 图片自动走「上传 S3 + 审核」：image / multiview / batch 内部已处理，无需手工调用审核接口。
3. 智能 UV 需要低模：模型须先 remesh 到 ≤8 万三角面才能使用。
4. 生成的模型 URL 带签名且有时效，需要长期保存时用 --wait -o 落盘。

游戏与 3D 大场景构建必读规范（防卡顿 / 防陷地 / 骨骼动画）

当用 tripocli 生成多个资产组装游戏场景（Three.js / Godot / Unity / Unreal）时，必须遵守以下 5 条铁律：

1. 严控面数（防止 6000 万面撑爆显存卡顿）：
   • 高精度模式（v3.1）默认 face_limit=2,000,000，单个建筑/树木可达 70 万～95 万三角面！若在主城里克隆几十份，总面数会突破 6,000 万面 导致严重掉帧。
   • 源头控面（首选，省积分）：生成建筑/树木/道具时直接传 --face-limit 15000（或加 --smart-mesh 走 P2.0 智能网格四边面低模）。
   • 本地真减面（已有高模救火 / 生成多级 LOD，0 积分秒级完成）： 入场前先用 tripocli inspect *.glb 检查面数，再用内置的 tripocli optimize 一键减面压缩（内部已自动区分静态模型 --error 0.06 与骨骼角色 --error 0.02，避免直接调 gltf-transform optimize 时默认 --simplify-error 0.0001 导致只压缩不减面的坑）：

     tripocli inspect /abs/path/assets/*.glb
     tripocli optimize in.glb -o out.glb --faces 15000
     tripocli optimize in.glb --lods
     

2. 模型接地封装（防止建筑/树木半截埋入地下）：
   • Tripo 导出的 GLB 模型原点位于几何中心（y ∈ [-H/2, +H/2]），不在底部。
   • 若直接修改模型自身的 obj.position.y -= box.min.y 后又在外部调用 obj.position.set(x, 0, z)，会把 y 重置回 0，导致所有房屋、城门、树木整整下半截 50% 埋进地里！
   • 正确做法：将缩放并偏移好底部高度（rawObj.position.y = -box.min.y）的模型包裹进一个外层 const wrap = new THREE.Group()，使 wrap 的 (0,0,0) 严格位于模型底部中心，外部只移动 wrap.position.set(x, groundY, z)。
3. 骨骼动画加载（本体 Mesh + 纯骨骼轨道分离架构）：
   • tripocli rig 产出的 GLB 含完整网格与 65 根骨骼（SkinnedMesh）；
   • tripocli animate（retarget_model）产出的 GLB 仅含 65 根骨骼的动画轨道（约 100～500KB），不含任何 Mesh！
   • 在引擎中应以 rig 导出的 hero.glb 作为渲染网格，再加载各个 anim_*.glb 提取其中的 gltf.animations 挂到同一个 AnimationMixer(heroModel) 上播放。
4. 带骨骼角色（SkinnedMesh）的包围盒测量：
   • Three.js 的 Box3.setFromObject() 对 SkinnedMesh 默认按绑定初始网格算，不含骨骼根变换，会导致算出的角色高度翻倍或悬空。应遍历 o.isBone 的骨骼世界坐标 o.getWorldPosition() 计算角色真实高度与脚底 min.y。
5. 渲染管线与阴影减负：
   • 场景中有上百个建筑/道具时，只让主要建筑和角色开启 castShadow = true，关闭复杂模型之间的 receiveShadow（仅地面、广场、台阶开启 receiveShadow = true），并将高分屏像素比限制在 Math.min(devicePixelRatio, 1.5)，可让 WebGL 稳定跑满 120 FPS。

详细文档

命令全集与接口契约见 README.md 与 TRIPO_API_SPEC.md。