tripo-cli 0.5.0 → 0.5.2

package/README.md

@@ -40,6 +40,7 @@ Works with both Tripo regions from the same install — international (`openapi.
 | `tripo files upload` | upload a file, print the `file_token` |
 | `tripo batch run <manifest.yaml>` | bulk pipelines with concurrency, retries, and resume |
 | `tripo config / doctor` | settings (global + per-directory `.tripo/context.json`) and self-diagnosis |
+| `tripo update [--check]` | upgrade to the latest release (`npm install -g tripo-cli@latest`); every command also hints when a newer version exists |
 | `tripo docs [--topic t]` | print the bundled agent/skill docs (`--topic commands/generate` has the model versions / P series table) |
 | `tripo mcp` | run as an MCP server (Cursor / Claude Desktop) |
 | `tripo completion <shell>` | bash/zsh/fish completion |
@@ -90,7 +91,7 @@ tripo batch run assets.yaml --concurrency 2
 
 - `make`/`watch` are blocking: run them, wait for exit, read the single JSON line on stdout. Do not poll yourself.
 - The plan card on stderr lists every call before it runs; the final JSON carries `credits_consumed` (total for the run) plus `credits_breakdown` (per task) when a chain ran.
-- Exit codes: `0` ok · `2` usage · `3` auth · `4` insufficient credits · `5` content policy · `6` task failed (credits auto-refunded) · `7` network · `8` not found · `9` rate limit.
+- Exit codes: `0` ok · `2` usage · `3` auth · `4` insufficient credits · `5` content policy · `6` task failed (credits auto-refunded; a `timeout` means it is still running) · `7` network (a failed submit is never resent — check `tripo balance` before re-running) · `8` not found · `9` rate limit.
 - `preview.png` in every output directory is your eyes: look at it, then decide to `tripo redo` or continue the chain.
 - Full behavior rules: `tripo docs --llm`, per-command docs via `tripo docs --topic commands/make`.
 
@@ -103,6 +104,8 @@ tripo batch run assets.yaml --concurrency 2
 | `TRIPO_REGION` | `ov` or `cn` — normally unnecessary: `tripo login` probes both regions with your key and stores the right one automatically |
 | `TRIPO_API_BASE_URL` / `TRIPO_PLATFORM_BASE_URL` | endpoint overrides |
 | `TRIPO_HOME` | config/history directory (default `~/.tripo`) |
+| `TRIPO_NO_UPDATE_CHECK` | disable the startup "new version available" hint (also off when `CI` is set, headless, or `--json`) |
+| `TRIPO_NPM_REGISTRY` | npm registry used by `tripo update` and the version check (default `https://registry.npmjs.org`; e.g. a mirror) |
 | `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | standard proxy variables, honored for all CLI traffic (plain Node fetch ignores them) |
 | `TRIPO_LLM_BASE_URL` / `TRIPO_LLM_API_KEY` / `TRIPO_LLM_MODEL` | optional OpenAI-compatible LLM for `tripo ai` conversation mode |
 

package/dist/commands/completion.js

@@ -5,7 +5,7 @@ const COMMANDS = [
     'login', 'logout', 'whoami', 'use', 'balance', 'usage', 'topup',
     'make', 'view', 'redo', 'ai',
     'generate', 'model', 'anim', 'mesh', 'task', 'files', 'batch', 'history',
-    'config', 'doctor', 'docs', 'completion', 'mcp',
+    'config', 'doctor', 'update', 'docs', 'completion', 'mcp',
 ];
 const SUBS = {
     generate: ['text-to-model', 'image-to-model', 'multiview-to-model', 'text-to-image', 'image-to-image', 'image-to-multiview', 'edit-multiview', 'image-to-splat'],

package/dist/commands/update.js

@@ -0,0 +1,138 @@
+/**
+ * `tripo update` — self-update via npm, plus the startup "new version
+ * available" hint (like Claude Code / Codex CLI).
+ *
+ * The startup check never blocks a command: it reads a 24h cache at
+ * ~/.tripo/update-check.json and only refreshes it in the background when
+ * stale. The hint is printed to stderr, TTY-only, and never in --json mode,
+ * so agents and pipes are unaffected.
+ */
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+import { tripoHome } from '../config/config.js';
+import { CliError, NetworkError } from '../core/errors.js';
+import { emitResult, isJsonMode, log, success } from '../core/output.js';
+import { t } from '../i18n.js';
+import { EXIT } from '../knowledge/error-catalog.js';
+import { cliVersion } from '../version.js';
+const PACKAGE_NAME = 'tripo-cli';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+function registryUrl() {
+    const base = process.env.TRIPO_NPM_REGISTRY || 'https://registry.npmjs.org';
+    return `${base.replace(/\/+$/, '')}/${PACKAGE_NAME}/latest`;
+}
+function cachePath() {
+    return join(tripoHome(), 'update-check.json');
+}
+function readCache() {
+    try {
+        const raw = JSON.parse(readFileSync(cachePath(), 'utf8'));
+        if (typeof raw.checked_at === 'number' && typeof raw.latest === 'string')
+            return raw;
+    }
+    catch { }
+    return undefined;
+}
+function writeCache(latest) {
+    try {
+        mkdirSync(tripoHome(), { recursive: true, mode: 0o700 });
+        writeFileSync(cachePath(), JSON.stringify({ checked_at: Date.now(), latest }) + '\n');
+    }
+    catch { }
+}
+/** Numeric major.minor.patch comparison; pre-release tags are ignored. */
+export function isNewerVersion(candidate, current) {
+    const parse = (v) => v.replace(/^v/, '').split('-')[0].split('.').map((x) => Number(x) || 0);
+    const a = parse(candidate);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    return false;
+}
+/** Ask the npm registry for the latest published version. */
+export async function fetchLatestVersion() {
+    const url = registryUrl();
+    let response;
+    try {
+        response = await fetch(url, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    }
+    catch (err) {
+        throw new NetworkError(`cannot reach the npm registry (${url}): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!response.ok)
+        throw new NetworkError(`npm registry answered HTTP ${response.status} for ${url}`);
+    const body = (await response.json());
+    if (typeof body.version !== 'string')
+        throw new NetworkError(`unexpected npm registry response for ${url}`);
+    writeCache(body.version);
+    return body.version;
+}
+/**
+ * Startup hook: print a one-line hint when a newer version is known.
+ * Cheap on every run (one small file read); refreshes the cache in the
+ * background at most once a day. Skipped headless, in --json mode, and when
+ * TRIPO_NO_UPDATE_CHECK is set.
+ */
+export function notifyIfOutdated() {
+    if (process.env.TRIPO_NO_UPDATE_CHECK || process.env.CI)
+        return;
+    if (isJsonMode() || !process.stderr.isTTY)
+        return;
+    const current = cliVersion();
+    const cache = readCache();
+    if (cache && isNewerVersion(cache.latest, current)) {
+        process.stderr.write(pc.yellow(t({
+            zh: `! 有新版本 tripo-cli ${cache.latest} 可用(当前 ${current}),运行 tripo update 升级`,
+            en: `! a new version of tripo-cli is available: ${cache.latest} (current ${current}) — run "tripo update" to upgrade`,
+        })) + '\n');
+    }
+    if (!cache || Date.now() - cache.checked_at > CHECK_INTERVAL_MS) {
+        // Fire-and-forget; the result shows up on the next run.
+        fetchLatestVersion().catch(() => { });
+    }
+}
+function runNpmInstall() {
+    return new Promise((resolve, reject) => {
+        const child = spawn('npm', ['install', '-g', `${PACKAGE_NAME}@latest`], {
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        child.on('error', (err) => reject(new CliError(`failed to run npm: ${err.message}`, EXIT.FATAL)));
+        child.on('exit', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new CliError(`npm install exited with code ${code}`, EXIT.FATAL, t({ zh: `手动执行: npm install -g ${PACKAGE_NAME}@latest`, en: `run manually: npm install -g ${PACKAGE_NAME}@latest` })));
+        });
+    });
+}
+export function registerUpdateCommand(program) {
+    program
+        .command('update')
+        .description('update tripo-cli to the latest version (npm install -g tripo-cli@latest)')
+        .option('--check', 'only check for a newer version; do not install')
+        .action(async (opts) => {
+        const current = cliVersion();
+        const latest = await fetchLatestVersion();
+        const available = isNewerVersion(latest, current);
+        if (!available) {
+            success(t({ zh: `已是最新版本 ${current}`, en: `already up to date (${current})` }));
+            emitResult({ current, latest, update_available: false, updated: false }, current);
+            return;
+        }
+        if (opts.check) {
+            log(t({ zh: `有新版本 ${latest} 可用(当前 ${current}),运行 tripo update 升级`, en: `new version ${latest} available (current ${current}); run "tripo update" to upgrade` }));
+            emitResult({ current, latest, update_available: true, updated: false }, `${current} → ${latest}`);
+            return;
+        }
+        log(t({ zh: `正在升级 ${current} → ${latest}…`, en: `updating ${current} → ${latest}…` }));
+        await runNpmInstall();
+        success(t({ zh: `已升级到 tripo-cli ${latest}`, en: `updated to tripo-cli ${latest}` }));
+        emitResult({ current, latest, update_available: true, updated: true }, `${current} → ${latest}`);
+    });
+}

package/dist/core/client.js

@@ -1,10 +1,12 @@
 /**
  * Lightweight V3 API client on top of global fetch (Node 20+).
  * Handles the response envelope, error translation, timeouts, and
- * exponential-backoff retries for transient failures (429/5xx/network).
+ * exponential-backoff retries for transient failures (429/5xx/network;
+ * task creation is only resent on 429).
  */
 import { activeProfileName, DEFAULT_PROFILE, listProfiles, loadConfig, resolveApiBaseUrl, resolveApiKey } from '../config/config.js';
 import { t } from '../i18n.js';
+import { EXIT } from '../knowledge/error-catalog.js';
 import { ApiError, AuthError, NetworkError } from './errors.js';
 export class TripoClient {
     baseUrl;
@@ -37,10 +39,11 @@ export class TripoClient {
         this.maxRetries = options.maxRetries ?? 3;
         this.onRetry = options.onRetry;
     }
-    async request(method, path, body) {
+    async request(method, path, body, options = {}) {
         return this.send(method, path, {
             headers: { 'Content-Type': 'application/json' },
             body: body === undefined ? undefined : JSON.stringify(body),
+            idempotent: options.idempotent,
         });
     }
     async uploadFile(fileName, data) {
@@ -61,7 +64,11 @@ export class TripoClient {
             }
             catch (err) {
                 lastError = err;
-                const retryable = err instanceof NetworkError || (err instanceof ApiError && err.retryable);
+                // A create that timed out or hit a 5xx may already be accepted (and
+                // billed); only a rate-limit rejection proves the server did nothing.
+                const retryable = init.idempotent === false
+                    ? err instanceof ApiError && err.exitCode === EXIT.RATE_LIMIT
+                    : err instanceof NetworkError || (err instanceof ApiError && err.retryable);
                 if (!retryable || attempt === this.maxRetries)
                     throw err;
             }
@@ -134,8 +141,19 @@ export class TripoClient {
     }
     /** Create a task; returns its id. Response may be {task_id} or a full detail. */
     async createTask(endpoint, payload) {
-        const data = await this.request('POST', endpoint, payload);
-        return data.task_id;
+        try {
+            const data = await this.request('POST', endpoint, payload, { idempotent: false });
+            return data.task_id;
+        }
+        catch (err) {
+            if (err instanceof NetworkError || (err instanceof ApiError && err.exitCode === EXIT.NETWORK)) {
+                err.suggestion = t({
+                    zh: '任务可能已在服务端创建并冻结积分;重试前先用 tripo balance 查看冻结额或到控制台确认,避免重复扣费',
+                    en: 'the task may already exist server-side (credits frozen); check "tripo balance" or the console before retrying, to avoid a duplicate charge',
+                });
+            }
+            throw err;
+        }
     }
 }
 export function sleep(ms) {

package/dist/core/errors.js

@@ -45,13 +45,17 @@ export class NetworkError extends CliError {
 }
 export class TaskFailedError extends CliError {
     taskId;
+    status;
     constructor(taskId, status, detail) {
         const refundNote = t({
             zh: '预扣积分已自动退还',
             en: 'frozen credits have been refunded automatically',
         });
-        super(`task ${taskId} ${status}${detail ? `: ${detail}` : ''} (${refundNote})`, EXIT.TASK_FAILED);
+        super(
+        // A timed-out task is still running server-side: nothing has been refunded.
+        `task ${taskId} ${status}${detail ? `: ${detail}` : ''}${status === 'timeout' ? '' : ` (${refundNote})`}`, EXIT.TASK_FAILED);
         this.taskId = taskId;
+        this.status = status;
     }
 }
 /** Decorate insufficient-balance errors with the topup path and the gap. */

package/dist/core/task-service.js

@@ -13,7 +13,7 @@ import { detectInput } from '../util/input-detect.js';
 import { notifyDone } from '../util/notify.js';
 import { createSpinner } from '../util/spinner.js';
 import { defaultOutputDir, downloadArtifacts } from './download.js';
-import { ApiError, UsageError, balanceSuggestion } from './errors.js';
+import { ApiError, CliError, TaskFailedError, UsageError, balanceSuggestion } from './errors.js';
 import { isQuiet, log, warn } from './output.js';
 import { uploadLocalFile } from './upload.js';
 /** Placeholder `input` value for a local file that a dry run would upload. */
@@ -115,7 +115,15 @@ export async function runTask(options) {
     }
     catch (err) {
         spinner.fail(`${taskType} · ${taskId}`);
-        updateHistoryStatus(taskId, 'failed');
+        if (err instanceof TaskFailedError && err.status !== 'timeout') {
+            updateHistoryStatus(taskId, 'failed');
+        }
+        else if (err instanceof CliError) {
+            err.suggestion = t({
+                zh: `任务仍在服务端运行,成功后照常扣费;用 tripo task watch ${taskId} --download 继续等待,不要重新提交`,
+                en: `the task keeps running server-side and is billed if it succeeds; resume with "tripo task watch ${taskId} --download" instead of resubmitting`,
+            });
+        }
         throw err;
     }
     updateHistoryStatus(taskId, 'success', { credits_consumed: task.credits_consumed });

package/dist/program.js

@@ -16,6 +16,7 @@ import { registerMcpCommand } from './commands/mcp.js';
 import { registerProcessCommands } from './commands/process-groups.js';
 import { registerTaskCommands } from './commands/task.js';
 import { registerTopupCommand } from './commands/topup.js';
+import { notifyIfOutdated, registerUpdateCommand } from './commands/update.js';
 import { registerViewCommands } from './commands/view.js';
 import { loadConfig } from './config/config.js';
 import { RefError } from './config/history.js';
@@ -55,6 +56,10 @@ export function buildProgram() {
         const lang = loadConfig().language;
         if (lang)
             setLocale(lang);
+        // Startup version hint (cached, non-blocking). `update` reports on its
+        // own; `mcp` speaks JSON-RPC over stdio and must stay silent.
+        if (actionCommand.name() !== 'update' && actionCommand.name() !== 'mcp')
+            notifyIfOutdated();
     });
     registerMakeCommand(program);
     registerAiCommand(program);
@@ -68,6 +73,7 @@ export function buildProgram() {
     registerBatchCommand(program);
     registerConfigCommands(program);
     registerDoctorCommand(program);
+    registerUpdateCommand(program);
     registerDocsCommand(program);
     registerCompletionCommand(program);
     registerMcpCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tripo-cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Tripo 3D intelligent CLI — turn a prompt or an image into engine-ready 3D assets from your terminal (Tripo V3 API)",
   "keywords": [
     "tripo",

package/skill/SKILL.md

@@ -34,7 +34,7 @@ Regions (ov = international, cn = China mainland) share one CLI: `tripo login --
 2. **stdout is the contract; stderr is commentary.** With `--json` (auto-enabled when piped), stdout carries exactly one final JSON line. Progress/logs go to stderr.
 3. **Artifacts are local files.** The result JSON has `output_dir`, `model_file`, `preview`. Look at `preview.png` to judge quality; re-roll with `tripo redo` if needed.
 4. **Exit codes are stable** — branch on them:
-   - 0 success · 2 usage/params · 3 auth · 4 insufficient credits (tell the human to run `tripo topup`) · 5 content policy · 6 task failed (credits auto-refunded) · 7 network · 8 not found · 9 rate limit (retry with backoff)
+   - 0 success · 2 usage/params · 3 auth · 4 insufficient credits (tell the human to run `tripo topup`) · 5 content policy · 6 task failed (credits auto-refunded; on `timeout` it is still running — `tripo task watch <id>`, never redo) · 7 network (a failed submit is never resent and may already exist — check `tripo balance` before re-running) · 8 not found · 9 rate limit (retry with backoff)
 5. **Never invent parameters.** Unknown `--param key=value` pairs pass through to the API; stick to documented ones. The full parameter/model/preset reference from the official API docs is bundled: `tripo docs --topic commands/generate` (3D + image generation) and `tripo docs --topic commands/process` (texture/convert/rig/retarget/mesh) — read those instead of browsing the website.
 6. **Validate before spending: `--dry-run --json`.** Same command plus `--dry-run` prints the plan as JSON with zero network calls and no credits: the chosen `model`, the completed `steps[].payload` for every API call, `warnings` (auto-adjustments) and `errors` (blocking; exit 2). When `valid` is true, re-run without `--dry-run`. Details: `tripo docs --topic commands/make` § "Dry run".
 7. **Don't pick legacy model versions.** The CLI auto-selects `tripo-v3.1` (high fidelity) or `tripo-p1` (low-poly, face budget ≤ 20000). Only override `--model` when the human asks (e.g. `--model tripo-p2` for the P-series **Preview** with quad support, or `tripo-v3.0` / `tripo-v2.5` for reproducing old projects). `tripo-*` names are CLI aliases — the CLI sends the dated wire value (`tripo-p2` → `P2-20260801`); the API rejects the alias itself with 1004. Alias ↔ wire ↔ status table: `tripo docs --topic commands/generate` ("Models & Versions").

package/skill/commands/task.md

@@ -12,7 +12,7 @@ tripo task get @last --download --json
 
 Block until the task finishes. In `--json` mode, progress streams as NDJSON events on stdout (`{"event":"progress",...}` lines) and the final task detail is the last line. `--download` grabs artifacts on success. `--timeout <seconds>` (default 1800).
 
-Rules for agents: treat `watch` as synchronous; read lines until process exit; exit code 6 means the task failed (credits refunded).
+Rules for agents: treat `watch` as synchronous; read lines until process exit; exit code 6 means the task failed (credits refunded) — or, if the error says `timeout`, that it is still running (watch it again; do not resubmit).
 
 ## tripo task list [ids...]
 

package/skill/common-errors.md

@@ -19,9 +19,9 @@
 | 2 | 2018 | too complex to remesh | lower `face_limit` or simplify the input model |
 | 8 | 2019 | file not found (token expired?) | re-upload; file tokens are short-lived |
 | 2 | 2020/2021/2022 | bad image URL / file too large / image too large | fix the URL or shrink the file |
-| 7 | 1000/1001 | server-side error | 1000 auto-retries; if persistent, contact support with the `request_id` |
-| 6 | — | task failed server-side | frozen credits auto-refund; `tripo redo` often succeeds with a new seed |
-| 7 | — | network/5xx | auto-retried 3×; check `tripo doctor`; region mismatch (ov/cn) is a common cause |
+| 7 | 1000/1001 | server-side error | queries auto-retry on 1000, task creation does not (the task may already exist and be billed — check `tripo balance` frozen credits before re-running); if persistent, contact support with the `request_id` |
+| 6 | — | task failed server-side, or the watch timed out | failed: frozen credits auto-refund; `tripo redo` often succeeds with a new seed. `timeout`: the task is still running and is billed if it succeeds — `tripo task watch <id> --download`, never redo |
+| 7 | — | network/5xx | queries auto-retried 3×, task creation is not (follow the `suggestion`: check `tripo balance` before re-running); check `tripo doctor`; region mismatch (ov/cn) is a common cause |
 
 ## Concurrency pools (default per account; error 2000 when full)