tripo-cli 0.1.0

package/dist/src/commands/process-groups.js

@@ -0,0 +1,164 @@
+/**
+ * Processing command groups: `tripo model`, `tripo anim`, `tripo mesh`.
+ * Input resolution order: explicit argument > piped NDJSON from stdin > @last.
+ * That makes both human implicit-context and shell pipelines work:
+ *   tripo make cat.png | tripo anim rig | tripo anim retarget --param animation=preset:walk
+ */
+import { UsageError } from '../core/errors.js';
+import { log, warn } from '../core/output.js';
+import { buildStepRequest } from '../core/requests.js';
+import { resolveInputValue, runTask } from '../core/task-service.js';
+import { t } from '../i18n.js';
+import { getStep } from '../knowledge/chains.js';
+import { readPipedTask } from '../pipeline/stdin.js';
+import { newClient, printTaskResult, withTaskOptions } from './shared.js';
+async function resolveStepInput(client, raw) {
+    if (raw)
+        return resolveInputValue(client, raw);
+    const piped = await readPipedTask();
+    if (piped) {
+        log(t({ zh: `使用管道输入任务 ${piped.task_id}`, en: `using piped task ${piped.task_id}` }));
+        return { value: piped.task_id, sourceType: piped.type };
+    }
+    const fallback = await resolveInputValue(client, '@last');
+    log(t({ zh: `未指定输入,使用上一个成功任务 @last`, en: `no input given; defaulting to the last successful task (@last)` }));
+    return fallback;
+}
+function makeStepAction(stepName, extraDefaults = {}) {
+    return async (input, flags) => {
+        const client = newClient();
+        const resolved = await resolveStepInput(client, input);
+        // Local chain legality: catch e.g. retarget-on-non-rig before spending credits.
+        const def = getStep(stepName);
+        if (Array.isArray(def.accepts) && resolved.sourceType && !def.accepts.includes(resolved.sourceType)) {
+            throw new UsageError(`${def.name} only accepts ${def.accepts.join('/')} tasks (input is a ${resolved.sourceType} task)`);
+        }
+        const args = { ...extraDefaults, ...collectStepArgs(stepName, flags), ...flags.param };
+        const built = buildStepRequest(stepName, resolved.value, args);
+        for (const w of built.warnings)
+            warn(w);
+        const result = await runTask({
+            client,
+            request: built.request,
+            taskType: built.taskType,
+            name: flags.name ?? `${stepName}`,
+            outDir: flags.out,
+            noWait: flags.wait === false,
+            noDownload: flags.download === false,
+            notify: flags.notify,
+            timeoutMs: flags.timeout ? flags.timeout * 1000 : undefined,
+        });
+        printTaskResult(result);
+    };
+}
+/** Map first-class flags (e.g. --format) into step args. */
+function collectStepArgs(step, flags) {
+    const pick = (keys) => {
+        const out = {};
+        for (const key of keys) {
+            const flagKey = key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+            const v = flags[flagKey] ?? flags[key];
+            if (v !== undefined)
+                out[key] = v;
+        }
+        return out;
+    };
+    switch (step) {
+        case 'convert':
+            return pick(['format', 'texture_size', 'texture_format', 'face_limit', 'quad', 'flatten_bottom', 'fbx_preset', 'export_orientation', 'scale_factor', 'auto_size', 'pivot_to_center_bottom', 'export_vertex_colors']);
+        case 'texture':
+            return pick(['model', 'texture_quality', 'texture_alignment', 'pbr']);
+        case 'stylize':
+            return pick(['style', 'block_size']);
+        case 'rig':
+            return pick(['model', 'rig_type', 'spec', 'out_format']);
+        case 'retarget':
+            return pick(['animation', 'out_format', 'animate_in_place']);
+        case 'decimate':
+            return pick(['face_limit', 'quad', 'bake']);
+        case 'segment':
+            return pick(['model']);
+        case 'complete':
+            return pick(['completion_mode']);
+        case 'smartsegment':
+            return pick(['seg_type', 'granularity', 'hint']);
+        default:
+            return {};
+    }
+}
+export function registerProcessCommands(program) {
+    // ---- tripo model ----
+    const model = program.command('model').description('model processing: refine / texture / stylize / convert / import');
+    withTaskOptions(model.command('refine [input]').description('refine a draft text-to-model task (task id / @last)')).action(makeStepAction('refine'));
+    withTaskOptions(model
+        .command('texture [input]')
+        .description('re-texture a model (task/@last/file/url)')
+        .option('--texture-quality <q>', 'standard|detailed|extreme')
+        .option('--texture-alignment <a>', 'original_image|geometry')).action(makeStepAction('texture'));
+    withTaskOptions(model
+        .command('stylize [input]')
+        .description('stylize a model (lego/voxel/voronoi/minecraft)')
+        .option('--style <style>', 'lego|voxel|voronoi|minecraft')
+        .option('--block-size <n>', 'minecraft block size 32-128', (v) => Number(v))).action(makeStepAction('stylize'));
+    withTaskOptions(model
+        .command('convert [input]')
+        .description('convert format (GLTF/USDZ/FBX/OBJ/STL/3MF)')
+        .option('--format <format>', 'target format', 'GLTF')
+        .option('--texture-size <n>', 'texture size in px', (v) => Number(v))
+        .option('--texture-format <f>', 'JPEG/PNG/OPEN_EXR/...')
+        .option('--face-limit <n>', 'face limit', (v) => Number(v))
+        .option('--quad', 'quad remesh')
+        .option('--flatten-bottom', 'flatten the bottom (3D printing)')
+        .option('--fbx-preset <p>', 'blender|3dsmax|mixamo')
+        .option('--export-orientation <o>', '+x|-x|+y|-y')
+        .option('--scale-factor <n>', 'scale factor', (v) => Number(v))
+        .option('--auto-size', 'scale to real-world size')
+        .option('--pivot-to-center-bottom', 'pivot at center bottom')
+        .option('--export-vertex-colors', 'include vertex colors (OBJ/GLTF)')).action(makeStepAction('convert'));
+    withTaskOptions(model.command('import <input>').description('import an external model file/url (GLB/GLTF/FBX/OBJ/STL ≤150MB)')).action(makeStepAction('import'));
+    // ---- tripo anim ----
+    const anim = program.command('anim').description('animation: check (riggability) / rig / retarget');
+    withTaskOptions(anim.command('check [input]').description('rig-check: is this model riggable? (GLB input)')).action(makeStepAction('rig-check'));
+    withTaskOptions(anim
+        .command('rig [input]')
+        .description('rig a model (skeleton binding)')
+        .option('--rig-type <type>', 'biped|quadruped|hexapod|octopod|avian|serpentine|aquatic')
+        .option('--spec <spec>', 'tripo|mixamo')
+        .option('--out-format <f>', 'glb|fbx')).action(makeStepAction('rig'));
+    withTaskOptions(anim
+        .command('retarget [input]')
+        .description('apply preset animations to a rigged task')
+        .option('--animation <name...>', 'preset:walk preset:run ... (≤5, billed per animation)')
+        .option('--out-format <f>', 'glb|fbx')
+        .option('--animate-in-place', 'no root motion')).action(async (input, flags) => {
+        // --animation may be a list → map to animations[]
+        const anims = flags.animation;
+        if (Array.isArray(anims) && anims.length > 1) {
+            flags.param = { ...flags.param, animations: anims };
+            delete flags.animation;
+        }
+        else if (Array.isArray(anims)) {
+            flags.animation = anims[0];
+        }
+        await makeStepAction('retarget')(input, flags);
+    });
+    // ---- tripo mesh ----
+    const mesh = program.command('mesh').description('mesh ops: segment / complete / decimate / smartsegment');
+    withTaskOptions(mesh.command('segment [input]').description('segment a model into parts').option('--model <v>', 'v1.0-20250506|v2.0-20260430')).action(makeStepAction('segment'));
+    withTaskOptions(mesh
+        .command('complete [input]')
+        .description('complete/fill segmented parts (needs a segment task)')
+        .option('--completion-mode <m>', 'ai_completion|quick_cap')).action(makeStepAction('complete'));
+    withTaskOptions(mesh
+        .command('decimate [input]')
+        .description('high-poly → low-poly (bakes textures by default)')
+        .option('--face-limit <n>', 'target faces 500–20000', (v) => Number(v))
+        .option('--quad', 'quad output')
+        .option('--no-bake', 'skip baking textures onto the low-poly')).action(makeStepAction('decimate'));
+    withTaskOptions(mesh
+        .command('smartsegment [input]')
+        .description('smart segmentation (image or model pipeline)')
+        .option('--seg-type <t>', 'image|model', 'model')
+        .option('--granularity <g>', 'coarse|medium|fine')
+        .option('--hint <text>', 'hint for the parts to find')).action(makeStepAction('smartsegment'));
+}

package/dist/src/commands/shared.js

@@ -0,0 +1,75 @@
+/** Helpers shared by task-producing commands: flag parsing and result output. */
+import { loadConfig } from '../config/config.js';
+import { TripoClient } from '../core/client.js';
+import { UsageError } from '../core/errors.js';
+import { emitResult } from '../core/output.js';
+import { t } from '../i18n.js';
+import { parseThenExpression } from '../knowledge/chains.js';
+/** repeatable --param key=value collector */
+export function collectParam(value, previous) {
+    const eq = value.indexOf('=');
+    if (eq <= 0)
+        throw new UsageError(`--param expects key=value (got "${value}")`);
+    const key = value.slice(0, eq).trim();
+    const raw = value.slice(eq + 1).trim();
+    previous[key] = coerceValue(raw);
+    return previous;
+}
+export function coerceValue(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);
+    if ((raw.startsWith('[') && raw.endsWith(']')) || (raw.startsWith('{') && raw.endsWith('}'))) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch { }
+    }
+    return raw;
+}
+/** Attach the common generation/processing option set to a command. */
+export function withTaskOptions(cmd) {
+    return cmd
+        .option('-o, --out <dir>', 'output directory (default ./tripo-out/...)')
+        .option('--no-wait', 'submit only; do not wait for completion')
+        .option('--no-download', 'wait but skip downloading artifacts')
+        .option('--notify', 'desktop notification when done')
+        .option('--timeout <seconds>', 'watch timeout in seconds', (v) => Number(v))
+        .option('--name <name>', 'history name for @references')
+        .option('-p, --param <key=value>', 'extra API parameter (repeatable)', collectParam, {});
+}
+export function newClient() {
+    return new TripoClient({ baseUrl: undefined, apiKey: undefined });
+}
+export function parseChainFlag(value) {
+    if (!value)
+        return undefined;
+    return parseThenExpression(value);
+}
+/** Standard result output for a finished task (human + JSON modes). */
+export function printTaskResult(result) {
+    const lines = [];
+    lines.push(t({
+        zh: `任务 ${result.task_id} ${result.status === 'success' ? '完成' : result.status}`,
+        en: `task ${result.task_id} ${result.status}`,
+    }));
+    if (result.credits_consumed !== undefined) {
+        lines.push(t({ zh: `消耗积分: ${result.credits_consumed}`, en: `credits consumed: ${result.credits_consumed}` }));
+    }
+    if (result.output_dir) {
+        lines.push(t({ zh: `产物目录: ${result.output_dir}`, en: `artifacts: ${result.output_dir}` }));
+    }
+    if (result.model_file)
+        lines.push(t({ zh: `模型文件: ${result.model_file}`, en: `model file: ${result.model_file}` }));
+    if (result.preview)
+        lines.push(t({ zh: `预览图: ${result.preview}`, en: `preview: ${result.preview}` }));
+    emitResult(result, lines.join('\n'));
+}
+export function llmConfigured() {
+    return Boolean(loadConfig().llm?.base_url && loadConfig().llm?.model);
+}

package/dist/src/commands/task.js

@@ -0,0 +1,127 @@
+/** `tripo task get|list|watch` and `tripo files upload`. */
+import { readHistory, resolveReference, updateHistoryStatus } from '../config/history.js';
+import { TripoClient } from '../core/client.js';
+import { defaultOutputDir, downloadArtifacts } from '../core/download.js';
+import { emitNdjson, emitResult, isJsonMode, isQuiet, log } from '../core/output.js';
+import { watchTask } from '../core/watch.js';
+import { uploadLocalFile } from '../core/upload.js';
+import { t } from '../i18n.js';
+import { createSpinner } from '../util/spinner.js';
+import { newClient } from './shared.js';
+function resolveTaskId(target) {
+    if (target.startsWith('@')) {
+        const entry = resolveReference(target);
+        if (entry)
+            return entry.task_id;
+    }
+    return target;
+}
+function humanTask(task) {
+    const lines = [
+        `${task.task_id}  ${task.type}  ${task.status}${typeof task.progress === 'number' ? ` ${task.progress}%` : ''}`,
+    ];
+    if (task.credits_consumed !== undefined)
+        lines.push(t({ zh: `消耗积分 ${task.credits_consumed}`, en: `credits ${task.credits_consumed}` }));
+    const output = task.output ?? {};
+    for (const [key, value] of Object.entries(output)) {
+        if (typeof value === 'string' && value.startsWith('http'))
+            lines.push(`${key}: ${value}`);
+    }
+    return lines.join('\n');
+}
+export function registerTaskCommands(program) {
+    const task = program.command('task').description('query, list, and watch tasks');
+    task
+        .command('get <task-id>')
+        .description('fetch one task (accepts @last/@name)')
+        .option('--step', 'include pipeline step details')
+        .option('--download', 'download artifacts if successful')
+        .option('-o, --out <dir>', 'output directory for --download')
+        .action(async (target, opts) => {
+        const client = new TripoClient();
+        const taskId = resolveTaskId(target);
+        const detail = await client.getTask(taskId, opts.step);
+        if (opts.download && detail.status === 'success') {
+            const entry = readHistory().find((e) => e.task_id === taskId);
+            const dir = opts.out ?? entry?.output_dir ?? defaultOutputDir(process.cwd(), entry?.name ?? 'task', taskId);
+            const artifacts = await downloadArtifacts(detail, dir);
+            emitResult({ ...detail, output_dir: artifacts.outputDir, files: artifacts.files }, `${humanTask(detail)}\n${t({ zh: `产物目录: ${artifacts.outputDir}`, en: `artifacts: ${artifacts.outputDir}` })}`);
+            return;
+        }
+        emitResult(detail, humanTask(detail));
+    });
+    task
+        .command('list [task-ids...]')
+        .description('batch-query tasks (default: recent history)')
+        .option('--limit <n>', 'how many from history', (v) => Number(v), 10)
+        .action(async (targets, opts) => {
+        const client = new TripoClient();
+        const ids = targets.length > 0
+            ? targets.map(resolveTaskId)
+            : readHistory().slice(-opts.limit).map((e) => e.task_id);
+        if (ids.length === 0) {
+            emitResult([], t({ zh: '本地历史为空', en: 'no local history yet' }));
+            return;
+        }
+        const list = await client.listTasks(ids);
+        const human = list
+            .map((d) => `${d.task_id}  ${(d.type ?? '').padEnd(24)} ${d.status}${typeof d.progress === 'number' ? ` ${d.progress}%` : ''}`)
+            .join('\n');
+        emitResult(list, human);
+    });
+    task
+        .command('watch <task-id>')
+        .description('block until a task finishes (streams NDJSON progress in --json mode)')
+        .option('--download', 'download artifacts on success')
+        .option('-o, --out <dir>', 'output directory for --download')
+        .option('--timeout <seconds>', 'timeout in seconds', (v) => Number(v))
+        .action(async (target, opts) => {
+        const client = new TripoClient();
+        const taskId = resolveTaskId(target);
+        const spinner = isJsonMode() ? undefined : createSpinner(`watch ${taskId}`, isQuiet());
+        let lastProgress = -1;
+        const detail = await watchTask(client, taskId, {
+            timeoutMs: opts.timeout ? opts.timeout * 1000 : undefined,
+            onProgress: (d) => {
+                if (spinner) {
+                    spinner.update(`${d.type ?? 'task'} · ${d.status}${typeof d.progress === 'number' ? ` ${d.progress}%` : ''}`);
+                }
+                else if (isJsonMode() && typeof d.progress === 'number' && d.progress !== lastProgress) {
+                    lastProgress = d.progress;
+                    emitNdjson({ event: 'progress', task_id: d.task_id, status: d.status, progress: d.progress });
+                }
+            },
+        });
+        spinner?.succeed(`${detail.type} · success`);
+        updateHistoryStatus(taskId, detail.status, { credits_consumed: detail.credits_consumed });
+        if (opts.download) {
+            const entry = readHistory().find((e) => e.task_id === taskId);
+            const dir = opts.out ?? entry?.output_dir ?? defaultOutputDir(process.cwd(), entry?.name ?? 'task', taskId);
+            log(t({ zh: '下载产物…', en: 'downloading artifacts…' }));
+            const artifacts = await downloadArtifacts(detail, dir);
+            emitResult({ ...detail, output_dir: artifacts.outputDir, files: artifacts.files, model_file: artifacts.modelFile, preview: artifacts.preview }, `${humanTask(detail)}\n${t({ zh: `产物目录: ${artifacts.outputDir}`, en: `artifacts: ${artifacts.outputDir}` })}`);
+            return;
+        }
+        emitResult(detail, humanTask(detail));
+    });
+    const files = program.command('files').description('file uploads');
+    files
+        .command('upload <path>')
+        .description('upload a local image/model and print the file_token')
+        .action(async (path) => {
+        const client = newClient();
+        const token = await uploadLocalFile(client, path);
+        emitResult({ file_token: token }, token);
+    });
+    program
+        .command('history')
+        .description('recent tasks created by this CLI (@name references)')
+        .option('--limit <n>', 'rows', (v) => Number(v), 20)
+        .action((opts) => {
+        const entries = readHistory().slice(-opts.limit);
+        const human = entries
+            .map((e) => `${e.created_at.slice(0, 19)}  ${(e.name ?? '').padEnd(24)} ${e.type.padEnd(22)} ${e.status.padEnd(9)} ${e.task_id}`)
+            .join('\n');
+        emitResult(entries, human || t({ zh: '本地历史为空', en: 'no local history yet' }));
+    });
+}

package/dist/src/commands/topup.js

@@ -0,0 +1,61 @@
+/**
+ * `tripo topup` — payment stays in the browser (Stripe/Alipay pages already
+ * handle it); the CLI opens the billing page and then polls the balance so
+ * the user sees "credits arrived" without leaving the terminal.
+ */
+import { resolvePlatformBaseUrl } from '../config/config.js';
+import { sleep, TripoClient } from '../core/client.js';
+import { emitResult, log, shouldOpen } from '../core/output.js';
+import { t } from '../i18n.js';
+import { createSpinner } from '../util/spinner.js';
+import { openExternal } from '../util/open.js';
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 10 * 60 * 1000;
+export function registerTopupCommand(program) {
+    program
+        .command('topup')
+        .description('open the billing page and watch for the credits to arrive')
+        .option('--no-watch', 'just open the page; skip balance polling')
+        .action(async (opts) => {
+        const client = new TripoClient();
+        const before = await client.getBalance();
+        const url = `${resolvePlatformBaseUrl()}/billing`;
+        if (shouldOpen()) {
+            openExternal(url);
+            log(t({ zh: `已打开充值页面: ${url}`, en: `opened the billing page: ${url}` }));
+        }
+        else {
+            log(t({ zh: `充值页面: ${url}`, en: `billing page: ${url}` }));
+        }
+        log(t({ zh: `当前余额 ${before.balance} 积分`, en: `current balance: ${before.balance} credits` }));
+        if (!opts.watch || !shouldOpen()) {
+            emitResult({ billing_url: url, balance: before.balance }, url);
+            return;
+        }
+        const spinner = createSpinner(t({ zh: '等待到账…(Ctrl+C 退出,不影响支付)', en: 'waiting for credits… (Ctrl+C is safe; payment continues in the browser)' }));
+        const deadline = Date.now() + POLL_TIMEOUT_MS;
+        let current = Number(before.balance);
+        while (Date.now() < deadline) {
+            await sleep(POLL_INTERVAL_MS);
+            try {
+                const now = await client.getBalance();
+                const value = Number(now.balance);
+                if (value > current) {
+                    spinner.succeed(t({
+                        zh: `到账 +${value - current} 积分,当前余额 ${value}`,
+                        en: `+${value - current} credits arrived; balance is now ${value}`,
+                    }));
+                    emitResult({ billing_url: url, balance: value, delta: value - current });
+                    return;
+                }
+                current = value;
+            }
+            catch {
+                // transient polling errors are fine; keep waiting
+            }
+        }
+        spinner.stop();
+        log(t({ zh: '未检测到到账(超时 10 分钟);支付完成后余额会自动生效', en: 'no balance change detected within 10 minutes; credits apply automatically once payment completes' }));
+        emitResult({ billing_url: url, balance: current });
+    });
+}

package/dist/src/commands/view.js

@@ -0,0 +1,97 @@
+/**
+ * `tripo view [task|@last|file.glb]` — local model-viewer preview.
+ * `tripo redo [task|@last]` — re-roll the same request with a fresh seed.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { readHistory, resolveReference } from '../config/history.js';
+import { TripoClient } from '../core/client.js';
+import { downloadArtifacts, defaultOutputDir } from '../core/download.js';
+import { UsageError } from '../core/errors.js';
+import { emitResult, log, shouldOpen } from '../core/output.js';
+import { startViewer } from '../core/viewer.js';
+import { t } from '../i18n.js';
+import { runTask } from '../core/task-service.js';
+import { openExternal } from '../util/open.js';
+import { printTaskResult, newClient } from './shared.js';
+const VIEWABLE = new Set(['.glb', '.gltf']);
+export function registerViewCommands(program) {
+    program
+        .command('view')
+        .description('preview a 3D result in the browser (model-viewer, local server)')
+        .argument('[target]', 'task id, @last, @name, or a local .glb path (default @last)', '@last')
+        .option('--keep', 'keep the preview server running until Ctrl+C')
+        .action(async (target, opts) => {
+        const modelFile = await resolveModelFile(target);
+        const handle = await startViewer(modelFile, target);
+        if (shouldOpen()) {
+            openExternal(handle.url);
+            log(t({ zh: `预览已打开: ${handle.url}`, en: `preview opened: ${handle.url}` }));
+        }
+        emitResult({ url: handle.url, model_file: modelFile }, `${handle.url}\n${modelFile}`);
+        if (opts.keep || shouldOpen()) {
+            log(t({ zh: 'Ctrl+C 关闭预览服务', en: 'Ctrl+C to stop the preview server' }));
+            await new Promise(() => { }); // hold until interrupted
+        }
+        else {
+            handle.close();
+        }
+    });
+    program
+        .command('redo')
+        .description('re-run a previous task with a fresh model_seed (same everything else)')
+        .argument('[target]', 'task id or @reference (default @last)', '@last')
+        .option('--seed <n>', 'explicit model_seed', (v) => Number(v))
+        .action(async (target, opts) => {
+        const entry = target.startsWith('@')
+            ? resolveReference(target)
+            : readHistory().find((e) => e.task_id === target);
+        if (!entry)
+            throw new UsageError(`no history entry for ${target} — redo only works for tasks created by this CLI`);
+        if (!entry.endpoint || !entry.payload) {
+            throw new UsageError(`history entry ${target} has no recorded request payload`);
+        }
+        const payload = { ...entry.payload, model_seed: opts.seed ?? Math.floor(Math.random() * 2 ** 31) };
+        const client = newClient();
+        const result = await runTask({
+            client,
+            request: { endpoint: entry.endpoint, payload },
+            taskType: entry.type,
+            name: `${entry.name ?? 'redo'}-redo`,
+        });
+        printTaskResult(result);
+    });
+}
+async function resolveModelFile(target) {
+    // Direct file path
+    if (VIEWABLE.has(extname(target).toLowerCase()) && existsSync(target))
+        return target;
+    const entry = target.startsWith('@')
+        ? resolveReference(target)
+        : readHistory().find((e) => e.task_id === target);
+    // Local artifacts already downloaded?
+    if (entry?.output_dir && existsSync(entry.output_dir)) {
+        const glb = readdirSync(entry.output_dir).find((f) => VIEWABLE.has(extname(f).toLowerCase()));
+        if (glb)
+            return join(entry.output_dir, glb);
+    }
+    // Fetch fresh (URLs expire ~5min, so always re-query then download).
+    const taskId = entry?.task_id ?? target;
+    if (!/^(task_[A-Za-z0-9_-]+|[0-9a-f-]{36})$/i.test(taskId)) {
+        throw new UsageError(`cannot resolve "${target}" to a viewable model (.glb path, task id, or @ref)`);
+    }
+    const client = new TripoClient();
+    const task = await client.getTask(taskId);
+    if (task.status !== 'success')
+        throw new UsageError(`task ${taskId} is ${task.status}, nothing to view yet`);
+    log(t({ zh: '正在下载模型用于预览…', en: 'downloading the model for preview…' }));
+    const dir = entry?.output_dir ?? defaultOutputDir(process.cwd(), entry?.name ?? 'view', taskId);
+    const artifacts = await downloadArtifacts(task, dir);
+    if (!artifacts.modelFile || !VIEWABLE.has(extname(artifacts.modelFile).toLowerCase())) {
+        const fallback = artifacts.files.find((f) => VIEWABLE.has(extname(f).toLowerCase()));
+        if (!fallback)
+            throw new UsageError(`task ${taskId} has no glb/gltf artifact to preview (files: ${artifacts.files.join(', ') || 'none'})`);
+        return fallback;
+    }
+    return artifacts.modelFile;
+}

package/dist/src/config/config.js

@@ -0,0 +1,79 @@
+/**
+ * Global config at ~/.tripo/config.json (mode 0600 — it holds the API key).
+ * Precedence for every setting: env var > directory context > global config.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const REGION_DEFAULTS = {
+    ov: { api: 'https://openapi.tripo3d.ai', platform: 'https://platform.tripo3d.ai' },
+    cn: { api: 'https://openapi.tripo3d.com', platform: 'https://platform.tripo3d.ai' },
+};
+export function tripoHome() {
+    return process.env.TRIPO_HOME || join(homedir(), '.tripo');
+}
+function configPath() {
+    return join(tripoHome(), 'config.json');
+}
+export function loadConfig() {
+    try {
+        return JSON.parse(readFileSync(configPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(config) {
+    const dir = tripoHome();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = configPath();
+    writeFileSync(file, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    // writeFileSync mode only applies on creation; enforce on every save.
+    chmodSync(file, 0o600);
+}
+export function updateConfig(patch) {
+    const next = { ...loadConfig(), ...patch };
+    saveConfig(next);
+    return next;
+}
+export function deleteApiKey() {
+    const config = loadConfig();
+    delete config.api_key;
+    if (Object.keys(config).length === 0) {
+        try {
+            unlinkSync(configPath());
+        }
+        catch { }
+    }
+    else {
+        saveConfig(config);
+    }
+}
+/** Resolve the API key: env wins, then global config. */
+export function resolveApiKey(config = loadConfig()) {
+    return process.env.TRIPO_API_KEY || config.api_key;
+}
+export function resolveRegion(config = loadConfig()) {
+    const env = process.env.TRIPO_REGION;
+    if (env === 'cn' || env === 'ov')
+        return env;
+    return config.region ?? 'ov';
+}
+export function resolveApiBaseUrl(config = loadConfig()) {
+    return (process.env.TRIPO_API_BASE_URL ||
+        config.api_base_url ||
+        REGION_DEFAULTS[resolveRegion(config)].api);
+}
+export function resolvePlatformBaseUrl(config = loadConfig()) {
+    return (process.env.TRIPO_PLATFORM_BASE_URL ||
+        config.platform_base_url ||
+        REGION_DEFAULTS[resolveRegion(config)].platform);
+}
+export function configFileExists() {
+    return existsSync(configPath());
+}
+export function maskKey(key) {
+    if (key.length <= 10)
+        return key.slice(0, 4) + '…';
+    return `${key.slice(0, 8)}…${key.slice(-4)}`;
+}

package/dist/src/config/context.js

@@ -0,0 +1,44 @@
+/**
+ * Directory-level context at .tripo/context.json — project defaults that
+ * apply when the CLI runs inside that directory (like .git discovery).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Walk up from cwd to find the nearest .tripo/context.json. */
+export function findContextFile(from = process.cwd()) {
+    let dir = from;
+    for (;;) {
+        const candidate = join(dir, '.tripo', 'context.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+export function loadContext(from = process.cwd()) {
+    const file = findContextFile(from);
+    if (!file)
+        return {};
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Update (or create) the context file in the current directory. */
+export function updateContext(patch, cwd = process.cwd()) {
+    const existing = findContextFile(cwd);
+    const file = existing ?? join(cwd, '.tripo', 'context.json');
+    let current = {};
+    if (existing) {
+        try {
+            current = JSON.parse(readFileSync(existing, 'utf8'));
+        }
+        catch { }
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ ...current, ...patch }, null, 2) + '\n');
+}