tripo-cli 0.1.0

package/dist/src/core/task-service.js

@@ -0,0 +1,161 @@
+/**
+ * The shared task engine: resolve inputs, pre-check balance, submit, record
+ * history, watch progress, download artifacts, notify. Every task-producing
+ * command (make/generate/model/anim/mesh/pipeline/batch) runs through here so
+ * behavior is identical everywhere.
+ */
+import { basename } from 'node:path';
+import { resolvePlatformBaseUrl } from '../config/config.js';
+import { loadContext, updateContext } from '../config/context.js';
+import { RefError, appendHistory, readHistory, resolveReference, slugify, updateHistoryStatus } from '../config/history.js';
+import { t } from '../i18n.js';
+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 { isQuiet, log, warn } from './output.js';
+import { uploadLocalFile } from './upload.js';
+/** Resolve a user input string into the API `input` value (upload as needed). */
+export async function resolveInputValue(client, raw) {
+    const detected = detectInput(raw);
+    switch (detected.kind) {
+        case 'history-ref': {
+            let entry;
+            try {
+                entry = resolveReference(detected.value);
+            }
+            catch (err) {
+                if (err instanceof RefError)
+                    throw new UsageError(err.message);
+                throw err;
+            }
+            if (!entry)
+                throw new UsageError(`cannot resolve reference ${raw}`);
+            return { value: entry.task_id, sourceTaskType: entry.type };
+        }
+        case 'image-file':
+        case 'model-file': {
+            const token = await uploadLocalFile(client, detected.value);
+            return { value: token };
+        }
+        case 'task-id':
+            return { value: detected.value };
+        case 'file-token':
+        case 'url':
+            return { value: detected.value };
+        case 'text':
+            throw new UsageError(`expected a file/url/task reference, got text: "${raw}"`);
+    }
+}
+/** Balance pre-check: warns when low, errors when empty. */
+export async function precheckBalance(client) {
+    let balance;
+    try {
+        const data = await client.getBalance();
+        balance = Number(data.balance);
+    }
+    catch {
+        return; // pre-check must never block task creation on transient errors
+    }
+    if (Number.isNaN(balance))
+        return;
+    if (balance <= 0) {
+        throw new ApiError({ apiCode: 2010, suggestion: balanceSuggestion(undefined, balance) });
+    }
+    if (balance < 30) {
+        warn(t({
+            zh: `余额仅剩 ${balance} 积分,任务可能因余额不足失败(tripo topup 充值)`,
+            en: `balance is down to ${balance} credits; tasks may fail (run "tripo topup")`,
+        }));
+    }
+}
+/** Submit one task and (by default) watch it to completion + download. */
+export async function runTask(options) {
+    const { client, request, taskType } = options;
+    if (options.precheckBalance !== false)
+        await precheckBalance(client);
+    const taskId = await client.createTask(request.endpoint, request.payload);
+    const name = uniqueName(slugify(options.name));
+    const entry = {
+        task_id: taskId,
+        type: taskType,
+        name,
+        status: 'queued',
+        created_at: new Date().toISOString(),
+        endpoint: request.endpoint,
+        payload: request.payload,
+    };
+    appendHistory(entry);
+    updateContext({ last_task_id: taskId });
+    log(t({ zh: `任务已创建 ${taskId} (@${name})`, en: `task created ${taskId} (@${name})` }));
+    if (options.noWait) {
+        return { task_id: taskId, type: taskType, status: 'queued' };
+    }
+    const spinner = createSpinner(`${taskType} · queued`, isQuiet());
+    let task;
+    try {
+        task = await (await import('./watch.js')).watchTask(client, taskId, {
+            timeoutMs: options.timeoutMs,
+            onProgress: (detail) => {
+                const pct = typeof detail.progress === 'number' ? ` ${detail.progress}%` : '';
+                spinner.update(`${taskType} · ${detail.status}${pct} · ${taskId.slice(0, 8)}`);
+            },
+        });
+    }
+    catch (err) {
+        spinner.fail(`${taskType} · ${taskId}`);
+        updateHistoryStatus(taskId, 'failed');
+        throw err;
+    }
+    updateHistoryStatus(taskId, 'success', { credits_consumed: task.credits_consumed });
+    spinner.succeed(`${taskType} · ${taskId}` +
+        (task.credits_consumed !== undefined
+            ? t({ zh: ` · 消耗 ${task.credits_consumed} 积分`, en: ` · ${task.credits_consumed} credits` })
+            : ''));
+    const result = {
+        task_id: taskId,
+        type: taskType,
+        status: task.status,
+        credits_consumed: task.credits_consumed,
+    };
+    if (!options.noDownload) {
+        const baseDir = options.outDir ?? loadContext().output_dir ?? process.cwd();
+        const dir = defaultOutputDir(baseDir, name, taskId);
+        const dlSpinner = createSpinner(t({ zh: '下载产物…', en: 'downloading artifacts…' }), isQuiet());
+        try {
+            const artifacts = await downloadArtifacts(task, dir, entry, {
+                onFile: (f) => dlSpinner.update(t({ zh: `下载 ${f}`, en: `downloading ${f}` })),
+            });
+            dlSpinner.succeed(t({ zh: `产物已保存 ${artifacts.outputDir}`, en: `artifacts saved to ${artifacts.outputDir}` }));
+            result.output_dir = artifacts.outputDir;
+            result.files = artifacts.files.map((f) => basename(f));
+            result.model_file = artifacts.modelFile;
+            result.preview = artifacts.preview;
+            updateHistoryStatus(taskId, 'success', { output_dir: artifacts.outputDir });
+        }
+        catch (err) {
+            dlSpinner.fail(t({ zh: '产物下载失败(任务本身已成功)', en: 'artifact download failed (the task itself succeeded)' }));
+            warn(String(err instanceof Error ? err.message : err));
+            warn(t({ zh: `可重试:tripo task get ${taskId} --download`, en: `retry with: tripo task get ${taskId} --download` }));
+        }
+    }
+    if (options.notify) {
+        notifyDone('Tripo', t({ zh: `${taskType} 完成`, en: `${taskType} finished` }));
+    }
+    return result;
+}
+/** Ensure history names stay unique by appending -2, -3, ... on collision. */
+function uniqueName(base) {
+    const names = new Set(readHistory().map((e) => e.name));
+    if (!names.has(base))
+        return base;
+    for (let i = 2;; i++) {
+        const candidate = `${base}-${i}`;
+        if (!names.has(candidate))
+            return candidate;
+    }
+}
+export function topupUrl() {
+    return `${resolvePlatformBaseUrl()}/billing`;
+}

package/dist/src/core/upload.js

@@ -0,0 +1,36 @@
+/** Local file → file_token upload with size/type guards. */
+import { readFile, stat } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { UsageError } from './errors.js';
+import { IMAGE_EXTS, MODEL_EXTS } from '../util/input-detect.js';
+const IMAGE_MAX = 20 * 1024 * 1024;
+const MODEL_MAX = 150 * 1024 * 1024;
+const MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+    '.glb': 'model/gltf-binary',
+    '.gltf': 'model/gltf+json',
+    '.fbx': 'application/octet-stream',
+    '.obj': 'text/plain',
+    '.stl': 'application/octet-stream',
+};
+export async function uploadLocalFile(client, filePath) {
+    const ext = extname(filePath).toLowerCase();
+    const isImage = IMAGE_EXTS.has(ext);
+    const isModel = MODEL_EXTS.has(ext);
+    if (!isImage && !isModel) {
+        throw new UsageError(`unsupported file type "${ext}" for upload`);
+    }
+    const info = await stat(filePath);
+    const limit = isImage ? IMAGE_MAX : MODEL_MAX;
+    if (info.size > limit) {
+        throw new UsageError(`${basename(filePath)} is ${(info.size / 1024 / 1024).toFixed(1)}MB, exceeding the ${limit / 1024 / 1024}MB ${isImage ? 'image' : 'model'} limit`);
+    }
+    const bytes = await readFile(filePath);
+    const blob = new Blob([bytes], { type: MIME[ext] ?? 'application/octet-stream' });
+    const { file_token } = await client.uploadFile(basename(filePath), blob);
+    return file_token;
+}

package/dist/src/core/viewer-assets.js

@@ -0,0 +1,24 @@
+/** Static HTML template for the local model-viewer preview page. */
+export function viewerHtml(modelFileName, title) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)} · Tripo</title>
+<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.5.0/model-viewer.min.js"></script>
+<style>
+  html, body { margin: 0; height: 100%; background: #101014; color: #e8e8ec; font: 14px/1.5 system-ui, sans-serif; }
+  model-viewer { width: 100%; height: 100%; --poster-color: transparent; }
+  .bar { position: fixed; top: 0; left: 0; right: 0; display: flex; justify-content: space-between; padding: 10px 16px; font-size: 13px; color: #9a9aa6; pointer-events: none; }
+</style>
+</head>
+<body>
+<div class="bar"><span>${escapeHtml(title)}</span><span>drag to rotate · scroll to zoom</span></div>
+<model-viewer src="${encodeURI(modelFileName)}" camera-controls auto-rotate shadow-intensity="1" exposure="0.9" ar></model-viewer>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+}

package/dist/src/core/viewer.js

@@ -0,0 +1,59 @@
+/**
+ * Local 3D preview: serve the model file + a model-viewer page on an
+ * ephemeral localhost port. The browser is an optional enhancement — the
+ * files are already on disk; headless callers just get the file path.
+ */
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { viewerHtml } from './viewer-assets.js';
+const CONTENT_TYPES = {
+    '.glb': 'model/gltf-binary',
+    '.gltf': 'model/gltf+json',
+    '.html': 'text/html; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.usdz': 'model/vnd.usdz+zip',
+};
+/** Start a one-model preview server; resolves once listening. */
+export async function startViewer(modelFile, title) {
+    const fileName = basename(modelFile);
+    const server = createServer((req, res) => {
+        void (async () => {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            try {
+                if (url.pathname === '/') {
+                    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(viewerHtml(fileName, title));
+                    return;
+                }
+                if (decodeURIComponent(url.pathname.slice(1)) === fileName) {
+                    const data = await readFile(modelFile);
+                    res.writeHead(200, {
+                        'Content-Type': CONTENT_TYPES[extname(fileName).toLowerCase()] ?? 'application/octet-stream',
+                        'Content-Length': data.length,
+                    });
+                    res.end(data);
+                    return;
+                }
+                res.writeHead(404);
+                res.end('not found');
+            }
+            catch {
+                res.writeHead(500);
+                res.end('error');
+            }
+        })();
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : 0;
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        close: () => server.close(),
+    };
+}

package/dist/src/core/watch.js

@@ -0,0 +1,41 @@
+/**
+ * Adaptive task polling: start at 2s; when the API reports running_left_time
+ * take max(2, left*0.5); otherwise back off exponentially capped at 30s.
+ */
+import { sleep } from './client.js';
+import { TaskFailedError } from './errors.js';
+export async function watchTask(client, taskId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30 * 60 * 1000;
+    const deadline = Date.now() + timeoutMs;
+    let interval = 2000;
+    let backoff = 2000;
+    for (;;) {
+        const task = await client.getTask(taskId);
+        options.onProgress?.(task);
+        if (task.status === 'success')
+            return task;
+        if (task.status === 'failed' || task.status === 'cancelled') {
+            if (options.throwOnFailure === false)
+                return task;
+            throw new TaskFailedError(taskId, task.status, extractFailureReason(task));
+        }
+        if (Date.now() > deadline) {
+            throw new TaskFailedError(taskId, 'timeout', `still ${task.status} after ${Math.round(timeoutMs / 1000)}s (task keeps running server-side; check later with "tripo task get ${taskId}")`);
+        }
+        const left = task.running_left_time ?? task.output?.running_left_time;
+        if (typeof left === 'number' && left > 0) {
+            interval = Math.max(2000, left * 500);
+            backoff = 2000;
+        }
+        else {
+            interval = backoff;
+            backoff = Math.min(backoff * 1.5, 30_000);
+        }
+        await sleep(interval);
+    }
+}
+function extractFailureReason(task) {
+    const out = task.output ?? {};
+    const candidate = out.message ?? out.error ?? out.reason;
+    return typeof candidate === 'string' ? candidate : undefined;
+}

package/dist/src/i18n.js

@@ -0,0 +1,19 @@
+/** Minimal bilingual UX strings. Locale: config override > env (LANG/LC_ALL). */
+let currentLocale;
+export function setLocale(locale) {
+    currentLocale = locale;
+}
+export function getLocale() {
+    if (currentLocale)
+        return currentLocale;
+    const env = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
+    return /^zh/i.test(env) ? 'zh' : 'en';
+}
+/** Pick the localized variant of a bilingual pair. */
+export function t(pair) {
+    return getLocale() === 'zh' ? pair.zh : pair.en;
+}
+/** Pick the localized variant of a bilingual string list. */
+export function tList(pair) {
+    return getLocale() === 'zh' ? pair.zh : pair.en;
+}

package/dist/src/knowledge/chains.js

@@ -0,0 +1,152 @@
+/**
+ * Task-chain legality — which processing step may consume which upstream task.
+ * Mirrors server-side handler constraints; violations are rejected locally
+ * before any credits are spent.
+ */
+/** Task types that produce a downloadable 3D model. */
+export const MODEL_PRODUCING_TYPES = new Set([
+    'text_to_model',
+    'image_to_model',
+    'multiview_to_model',
+    'refine_model',
+    'texture_model',
+    'stylize_model',
+    'convert_model',
+    'import_model',
+    'highpoly_to_lowpoly',
+    'mesh_segmentation',
+    'mesh_completion',
+    'animate_rig',
+    'animate_retarget',
+]);
+export const STEPS = [
+    { name: 'refine', endpoint: '/v3/models/refine', produces: 'refine_model', accepts: ['text_to_model'], acceptsFile: false },
+    { name: 'texture', endpoint: '/v3/models/texture', produces: 'texture_model', accepts: 'any-model', acceptsFile: true },
+    { name: 'stylize', endpoint: '/v3/models/stylize', produces: 'stylize_model', accepts: 'any-model', acceptsFile: true },
+    { name: 'convert', endpoint: '/v3/models/convert', produces: 'convert_model', accepts: 'any-model', acceptsFile: true },
+    { name: 'import', endpoint: '/v3/models/import', produces: 'import_model', accepts: [], acceptsFile: true },
+    { name: 'rig-check', endpoint: '/v3/animations/rig-check', produces: 'animate_prerigcheck', accepts: 'any-model', acceptsFile: true, passthrough: true, aliases: ['check', 'rigcheck'] },
+    { name: 'rig', endpoint: '/v3/animations/rig', produces: 'animate_rig', accepts: 'any-model', acceptsFile: true },
+    { name: 'retarget', endpoint: '/v3/animations/retarget', produces: 'animate_retarget', accepts: ['animate_rig'], acceptsFile: false, aliases: ['animate'] },
+    { name: 'segment', endpoint: '/v3/mesh/segment', produces: 'mesh_segmentation', accepts: 'any-model', acceptsFile: true },
+    { name: 'complete', endpoint: '/v3/mesh/complete', produces: 'mesh_completion', accepts: ['mesh_segmentation'], acceptsFile: false },
+    { name: 'decimate', endpoint: '/v3/mesh/decimate', produces: 'highpoly_to_lowpoly', accepts: 'any-model', acceptsFile: true, aliases: ['lowpoly'] },
+    { name: 'smartsegment', endpoint: '/v3/mesh/smartsegment', produces: 'smart_segmentation', accepts: 'any-model', acceptsFile: true },
+];
+const stepIndex = new Map();
+for (const s of STEPS) {
+    stepIndex.set(s.name, s);
+    for (const a of s.aliases ?? [])
+        stepIndex.set(a, s);
+}
+export function getStep(name) {
+    return stepIndex.get(name);
+}
+/**
+ * Parse a --then expression: "texture,rig,convert:fbx" or
+ * "convert:format=fbx,texture_size=2048". A bare value after ":" is sugar for
+ * the step's primary argument (convert→format, retarget→animation,
+ * stylize→style, decimate→face_limit).
+ */
+export function parseThenExpression(expr) {
+    const out = [];
+    // Split on commas that are not inside a step's arg list (args use "=", so a
+    // comma always separates either steps or key=value pairs; a segment with "="
+    // and no known step prefix belongs to the previous step).
+    const rawParts = expr.split(',').map((p) => p.trim()).filter(Boolean);
+    for (const part of rawParts) {
+        const [head, ...rest] = part.split(':');
+        const stepName = (head ?? '').trim().toLowerCase();
+        const def = getStep(stepName);
+        if (!def) {
+            if (part.includes('=') && out.length > 0) {
+                // continuation of previous step's args: "k=v"
+                const prev = out[out.length - 1];
+                applyArg(prev.args, part);
+                continue;
+            }
+            throw new ChainError(`unknown step "${stepName}" (valid: ${STEPS.map((s) => s.name).join(', ')})`);
+        }
+        const args = {};
+        const argStr = rest.join(':').trim();
+        if (argStr) {
+            for (const token of argStr.split(/[,;]/).map((t) => t.trim()).filter(Boolean)) {
+                if (token.includes('='))
+                    applyArg(args, token);
+                else
+                    applyPrimaryArg(def.name, args, token);
+            }
+        }
+        out.push({ step: def.name, args });
+    }
+    return out;
+}
+function applyArg(args, token) {
+    const eq = token.indexOf('=');
+    const key = token.slice(0, eq).trim();
+    const raw = token.slice(eq + 1).trim();
+    args[key] = coerce(raw);
+}
+function applyPrimaryArg(step, args, value) {
+    const primary = {
+        convert: 'format',
+        retarget: 'animation',
+        stylize: 'style',
+        decimate: 'face_limit',
+        texture: 'texture_quality',
+        rig: 'rig_type',
+        segment: 'model',
+        smartsegment: 'granularity',
+    };
+    const key = primary[step];
+    if (!key)
+        throw new ChainError(`step "${step}" does not take a bare argument ("${value}")`);
+    args[key] = coerce(value);
+}
+function coerce(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+$/.test(raw))
+        return Number(raw);
+    if (/^-?\d*\.\d+$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+export class ChainError extends Error {
+}
+/**
+ * Validate that a chain is legal given the type of the first (source) task.
+ * Returns the list of task types the chain will produce, in order.
+ */
+export function validateChain(chain, sourceType) {
+    let currentType = sourceType;
+    const produced = [];
+    for (const { step } of chain) {
+        const def = getStep(step);
+        if (!def)
+            throw new ChainError(`unknown step "${step}"`);
+        if (def.accepts === 'any-model') {
+            if (!MODEL_PRODUCING_TYPES.has(currentType)) {
+                throw new ChainError(`step "${def.name}" needs a model-producing upstream task, but the previous step produces "${currentType}"`);
+            }
+        }
+        else if (!def.accepts.includes(currentType)) {
+            throw new ChainError(`step "${def.name}" only accepts ${def.accepts.join('/')} tasks, but the previous step produces "${currentType}"` +
+                hintFor(def.name));
+        }
+        if (!def.passthrough)
+            currentType = def.produces;
+        produced.push(def.produces);
+    }
+    return produced;
+}
+function hintFor(step) {
+    const hints = {
+        refine: ' (refine only accepts a successful text-to-model task)',
+        complete: ' (run "segment" first: complete only accepts mesh segmentation tasks)',
+        retarget: ' (run "rig" first: retarget only accepts rigged tasks)',
+    };
+    return hints[step] ?? '';
+}

package/dist/src/knowledge/error-catalog.js

@@ -0,0 +1,91 @@
+/**
+ * V3 error-code catalog: human translations (zh/en), retryability, and the
+ * CLI exit code each error maps to.
+ *
+ * Source of truth: backend ErrorCode enum (platform-common .../error/ErrorCode.java,
+ * itself aligned with openapi-server errors.gen.go). Note the public docs page
+ * is stale for 1000/1001 — the server actually sends 1002 for auth failures;
+ * 1000/1001 are 5xx server-side errors.
+ */
+export const EXIT = {
+    OK: 0,
+    FATAL: 1,
+    USAGE: 2,
+    AUTH: 3,
+    BALANCE: 4,
+    CONTENT_POLICY: 5,
+    TASK_FAILED: 6,
+    NETWORK: 7,
+    NOT_FOUND: 8,
+    RATE_LIMIT: 9,
+};
+export const ERROR_CATALOG = [
+    { code: 1000, zh: '服务端未知错误,请携带 request_id 联系支持', en: 'Unknown server-side error; contact support with the request id', retryable: true, exitCode: EXIT.NETWORK },
+    { code: 1001, zh: '服务端严重错误,请携带 request_id 联系支持', en: 'Fatal server-side error; contact support with the request id', retryable: false, exitCode: EXIT.NETWORK },
+    { code: 1002, zh: '认证失败:API Key 无效或未正确设置', en: 'Authentication failed: the API key is invalid or not set correctly', retryable: false, exitCode: EXIT.AUTH },
+    { code: 1003, zh: '请求体格式不合法', en: 'The request body is malformed', retryable: false, exitCode: EXIT.USAGE },
+    { code: 1004, zh: '一个或多个参数不合法,请对照文档检查', en: 'One or more parameters are invalid (check the docs)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 1005, zh: '无权访问该资源,请检查账号权限', en: 'Not allowed to access this resource (check permissions)', retryable: false, exitCode: EXIT.AUTH },
+    { code: 1007, zh: '请求过于频繁,触发全局速率限制', en: 'Rate limit exceeded — too many requests in a short time', retryable: true, exitCode: EXIT.RATE_LIMIT },
+    { code: 2000, zh: '触发生成并发上限,同系列任务共享并发池', en: 'Generation concurrency limit hit (task families share a pool)', retryable: true, exitCode: EXIT.RATE_LIMIT },
+    { code: 2001, zh: '任务不存在(确认任务属于当前 Key、区域正确)', en: 'Task not found (same key that created it? right region?)', retryable: false, exitCode: EXIT.NOT_FOUND },
+    { code: 2002, zh: '该任务类型不受支持', en: 'This task type is not supported', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2003, zh: '输入图片文件为空,请检查文件是否损坏', en: 'The image file is empty (corrupted upload?)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2004, zh: '不支持的图片文件类型', en: 'Unsupported image file type', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2005, zh: 'draft 任务不是成功状态,请用成功的任务重试', en: 'The draft task is not a success; retry with a successful one', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2006, zh: '上游任务类型不受支持,请检查任务链', en: 'The original task type is not supported for this operation', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2007, zh: '上游任务不是成功状态', en: 'The original task has not succeeded', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2008, zh: '输入违反内容政策,请更换输入', en: 'Input violates the content policy; change the input', retryable: false, exitCode: EXIT.CONTENT_POLICY },
+    { code: 2009, zh: 'prompt 含有非法字符,请修改后重试', en: 'The prompt contains invalid characters', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2010, zh: '积分不足', en: 'Insufficient credits', retryable: false, exitCode: EXIT.BALANCE },
+    { code: 2011, zh: 'rig-check 的输入任务没有模型产物', en: 'The rig-check input task has no model output', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2012, zh: 'retarget 只接受 rig 任务作为输入', en: 'retarget only accepts a rig task as input', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2013, zh: 'priority 取值无效(更高优先级需联系支持)', en: 'Invalid priority (contact support for higher priority)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2014, zh: '内容审核过程出错,请联系支持', en: 'Error occurred during content auditing; contact support', retryable: false, exitCode: EXIT.FATAL },
+    { code: 2015, zh: '模型版本已弃用,请升级 model 参数', en: 'Model version deprecated; upgrade the model parameter', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2016, zh: '该请求类型已弃用,请改用其他类型', en: 'This request type is deprecated; use an alternative', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2017, zh: 'model 版本取值无效', en: 'The model version value is invalid', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2018, zh: '模型太复杂无法重网格化,降低 face_limit 或简化输入', en: 'Model too complex to remesh; lower face_limit or simplify input', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2019, zh: '文件不存在,请确认上传是否成功、file_token 是否过期', en: 'File not found (upload succeeded? token expired?)', retryable: false, exitCode: EXIT.NOT_FOUND },
+    { code: 2020, zh: '图片 URL 无效,请确认可公开访问', en: 'The image URL is invalid (must be publicly reachable)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2021, zh: '文件大小超过上限,请压缩后重试', en: 'File size exceeds the limit; reduce and retry', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2022, zh: '图片尺寸超过上限,请缩小后重试', en: 'Image size exceeds the limit; reduce and retry', retryable: false, exitCode: EXIT.USAGE },
+    { code: 4001, zh: '请求的接口不存在,请检查 API 路径', en: 'The requested endpoint does not exist (check the API path)', retryable: false, exitCode: EXIT.NOT_FOUND },
+];
+const byCode = new Map(ERROR_CATALOG.map((e) => [e.code, e]));
+export function lookupError(code) {
+    return byCode.get(code);
+}
+/** Map an API error code + HTTP status to a stable CLI exit code. */
+export function exitCodeFor(apiCode, httpStatus) {
+    if (apiCode !== undefined) {
+        const info = byCode.get(apiCode);
+        if (info)
+            return info.exitCode;
+    }
+    if (httpStatus === 401)
+        return EXIT.AUTH;
+    if (httpStatus === 403)
+        return EXIT.AUTH;
+    if (httpStatus === 404)
+        return EXIT.NOT_FOUND;
+    if (httpStatus === 429)
+        return EXIT.RATE_LIMIT;
+    if (httpStatus !== undefined && httpStatus >= 500)
+        return EXIT.NETWORK;
+    if (httpStatus !== undefined && httpStatus >= 400)
+        return EXIT.USAGE;
+    return EXIT.FATAL;
+}
+export function isRetryable(apiCode, httpStatus) {
+    if (apiCode !== undefined) {
+        const info = byCode.get(apiCode);
+        if (info)
+            return info.retryable;
+    }
+    if (httpStatus === 429)
+        return true;
+    if (httpStatus !== undefined && httpStatus >= 500)
+        return true;
+    return false;
+}