tripocli/AGENTS.md

AGENTS.md

给接手这个项目的 AI Agent / 开发者看的说明。要做任何事之前先读完本文件。

---

1. 这是什么

tripocli —— 把 Tripo AI 的 3D 生成与加工能力封装成命令行工具，供 Agent 与开发者调用。 纯 Python 3 标准库，零第三方依赖。

覆盖能力：文生 3D、图生 3D、多视图、批量生成，以及重拓扑、绑定、动画、智能分割、纹理、PBR、 智能 UV、部件补全、格式导出与下载。

2. 代码结构（重要约定）

一个功能 = 一个文件。 新增能力不要往单个大文件里塞。

tripocli.py             # 入口薄壳（只有十几行）
tripo/
├── cli.py              # argparse 装配 + 分发 + 错误处理
├── client.py           # HTTP：请求头、重试、凭据解析、轮询、下载
├── auth.py             # cookie → JWT（纯 HTTP）
├── accounts.py         # 多账号凭据存储
├── config.py           # 全局设置（API 地址 / device id）
├── s3.py               # SigV4 直传
├── server.py + web/    # tripocli serve（本地账号管理页）
├── update.py           # 自我更新（tripocli update）
└── features/           # 每个功能一个模块

新增一个命令的标准做法：

1. 在 tripo/features/ 下新建 xxx.py；
2. 模块里定义 NAME、HELP、add_arguments(parser)、run(ctx)（多子命令的模块改用 register(subparsers)）；
3. 在 tripo/features/__init__.py 的 import 和 MODULES 列表里各加一行；
4. 用真实请求验证后再交付。

3. 安装

cd <项目目录>
pip install .            # 装成全局命令
pyenv rehash             # ← pyenv 用户必须执行，否则报 tripocli: command not found

不想安装也可以直接用项目里的入口：<项目目录>/tripocli --version。

若 pip install . 报 invalid command 'bdist_wheel'，说明环境缺打包后端，执行 pip install wheel 后重试。 （tripocli 本体零依赖，这只影响安装过程。）

4. 更新（本节是「更新怎么做」的唯一依据）

首选：一条命令。

tripocli update                 # 从记住的源码目录重装全局 CLI（pyenv 会自动 rehash）
tripocli update --check         # 只看状态：源码目录 / 已安装版本 / 是否需要更新
tripocli update --dry-run       # 只打印将执行的命令
tripocli update --from <项目目录>   # 首次指定源码目录（会记住，之后不用再传）

改完源码后跑一次 tripocli update，全局命令就更新到最新。 源码目录首次自动识别（运行 tripocli 时所处的项目目录），并记录在 ~/.tripo/config.json 的 install_source。

4.1 手工方式（等价，update 不可用时）

cd <项目目录>
git pull                          # 若有 git 仓库
pip install . && pyenv rehash     # 重新安装

只拿到新目录/压缩包（未用 git）时：用新目录整体覆盖旧目录，再执行上面的安装命令； 如果一直是「直接用项目里的入口」的方式，覆盖完即生效，无需安装。

4.2 更新后必须做的验证

tripocli --version          # 版本号是否为预期
tripocli account list       # 凭据是否仍在（在 ~/.tripo/accounts.json，更新代码不会动它）
tripocli balance            # 能否正常调通接口

4.3 两个容易踩的坑

• 副本优先级：在项目目录内执行 tripocli 会优先用项目里的代码（cwd 优先）； 在其它目录执行才用 pip 装的那份。所以「更新后行为没变」多半是在项目目录里跑到了旧副本，或没重新安装。
• pyenv rehash：装/卸命令后不 rehash，pyenv 的 shim 找不到新命令（tripocli update 会自动做）。

5. 凭据

凭据在 ~/.tripo/accounts.json（权限 600），与代码分离，更新代码不会丢失。 只需一次浏览器 cookie，CLI 自行续期 15 分钟的 JWT（cookie 约 30 天有效）。

tripocli account add --cookie "ory_kratos_session=..."
tripocli account list
tripocli serve --open          # 网页版账号管理

多账号时默认会在「当前账号额度不足」时自动切换下一个账号重试；如需关闭，传 --no-fallback（或设 TRIPO_AUTO_FALLBACK=0）。

永远不要把 cookie / token 写进代码、文档或提交记录。

6. 验证改动（真实调用，不要只做静态检查）

tripocli --json balance                                   # 最快连通性检查
tripocli --json text -p "a wooden crate" --smart-mesh --wait -o /tmp/t.glb
tripocli --json project <project_id>                      # 拿 model_url

注意：后处理算子（remesh/rig/pbr/texture/uv…）会为项目新建 operator， 同一项目必须等上一个算子 success 才能提交下一个，否则报 2021。

7. 构建游戏场景与 3D 应用的性能与工程红线（必读）

当用户要求用 tripocli 生成资产并搭建游戏场景（Web Three.js / Godot / Unity）时，必须遵守以下已验证规范：

1. 严禁把未减面的 200 万面默认高模直接批量塞进场景：
   • 生成场景建筑/树木/道具时优先加 --face-limit 15000 或 --smart-mesh 从源头控制面数；
   • 对已下载的高模做本地减面时，不要只跑 gltf-transform optimize（其默认 --simplify-error 0.0001 过严，几乎不减面，只做 Draco 压缩，解压后显存里仍是七八十万面/个）；必须显式执行 npx gltf-transform simplify in.glb tmp.glb --ratio 0.025 --error 0.06 && npx gltf-transform draco tmp.glb out.glb（角色蒙皮网格用 --ratio 0.12 --error 0.02）。
2. 严禁在 normalize 后用 position.set(x, 0, z) 覆盖 position.y：
   • Tripo 模型原点在几何中心，必须用外层 Group 包装后再设 (x, groundY, z)，否则所有建筑和树木会半截埋入地下。
3. 骨骼动画：animate 产出的 GLB 在 project.operator.retarget[] 中，且只含骨骼轨道不含 Mesh，需与 rig 本体模型合并播放；测量 SkinnedMesh 高度时必须用 isBone 的世界坐标而非默认 Box3.setFromObject。
4. 文生图额度保护：tripocli img 默认 --amount 1（一次一张），除非用户明确要求多张，否则不要调高。

8. 建议的下一步（尚未做，需项目所有者决定）

1. git init + 首次提交，推到私有仓库 → 更新变成 git pull；
2. 需要对外分发时发布到 PyPI → 别人可用 pip install -U tripocli（当前该名字在 PyPI 上未被占用）；
3. 接口契约见 TRIPO_API_SPEC.md；命令说明见 README.md。