tripo-cli 0.1.0

package/dist/src/knowledge/models.js

@@ -0,0 +1,110 @@
+/**
+ * Dual-model strategy — the single source of truth for 3D model selection.
+ *
+ * Rule (one branch, no exceptions): explicit low-poly intent or a face budget
+ * <= 20000 selects P1; everything else selects v3.1. Explicit --model wins but
+ * still goes through constraint validation.
+ */
+export const MODEL_V31 = 'tripo-v3.1';
+export const MODEL_P1 = 'tripo-p1';
+/** Wire aliases accepted by the API for the two production models. */
+export const MODEL_ALIASES = {
+    'v3.1': MODEL_V31,
+    'v3.1-20260211': MODEL_V31,
+    'tripo-v3.1': MODEL_V31,
+    p1: MODEL_P1,
+    P1: MODEL_P1,
+    'P1-20260311': MODEL_P1,
+    'tripo-p1': MODEL_P1,
+};
+/** Other versions the API accepts; the CLI passes them through when explicit. */
+export const LEGACY_3D_MODELS = ['tripo-turbo', 'tripo-v3.0', 'tripo-v2.5', 'tripo-v2.0'];
+export const P1_FACE_LIMIT = { min: 48, max: 20000 };
+/** Parameters the server rejects for P1 — stripped locally with a warning. */
+export const P1_FORBIDDEN_PARAMS = [
+    'quad',
+    'smart_low_poly',
+    'generate_parts',
+    'geometry_quality',
+];
+/** Default versions for non-generation capabilities. */
+export const CAPABILITY_DEFAULTS = {
+    texture: 'v3.0-20250812',
+    /** Server default is rig-v1.0 (biped-only presets); the CLI defaults to
+     *  rig-v2.0 which has presets for all seven body types. */
+    rig: 'rig-v2.0',
+    segment: 'v1.0-20250506',
+    textToImage: 'seedream_v4',
+    imageToImage: 'seedream_v5',
+};
+export const RIG_TYPES = [
+    'biped',
+    'quadruped',
+    'hexapod',
+    'octopod',
+    'avian',
+    'serpentine',
+    'aquatic',
+];
+export const RIG_SPECS = ['tripo', 'mixamo'];
+export const IMAGE_MODELS = [
+    'seedream_v4',
+    'seedream_v5',
+    'banana',
+    'banana_pro',
+    'banana2',
+    'chat_image_1',
+    'chat_image_1.5',
+    'chat_image_2',
+];
+export const IMAGE_TEMPLATES = [
+    'asset_extraction',
+    'character_completion',
+    't_pose',
+    'head_extraction',
+    '3d_enhance',
+    'variants',
+    'print_clay',
+    'figure',
+];
+export const CONVERT_FORMATS = ['GLTF', 'USDZ', 'FBX', 'OBJ', 'STL', '3MF'];
+export const TEXTURE_FORMATS = [
+    'BMP',
+    'DPX',
+    'HDR',
+    'JPEG',
+    'OPEN_EXR',
+    'PNG',
+    'TARGA',
+    'TIFF',
+    'WEBP',
+];
+export const FBX_PRESETS = ['blender', '3dsmax', 'mixamo'];
+export const EXPORT_ORIENTATIONS = ['+x', '-x', '+y', '-y'];
+export const STYLIZE_STYLES = ['lego', 'voxel', 'voronoi', 'minecraft'];
+export const TEXTURE_QUALITIES = ['standard', 'detailed', 'extreme'];
+/** Normalize any accepted alias to the canonical wire value; unknown values pass through. */
+export function normalizeModel(input) {
+    return MODEL_ALIASES[input] ?? input;
+}
+export function isP1(model) {
+    return normalizeModel(model) === MODEL_P1;
+}
+/** The one rule. Returns the model plus a human-readable reason. */
+export function chooseModel(intent) {
+    if (intent.explicit) {
+        return { model: normalizeModel(intent.explicit), reason: 'explicit --model' };
+    }
+    if (intent.lowPoly) {
+        return { model: MODEL_P1, reason: 'low-poly intent → P1' };
+    }
+    if (intent.faceLimit !== undefined && intent.faceLimit <= P1_FACE_LIMIT.max) {
+        return { model: MODEL_P1, reason: `face budget ${intent.faceLimit} ≤ ${P1_FACE_LIMIT.max} → P1` };
+    }
+    return { model: MODEL_V31, reason: 'default high-fidelity → v3.1' };
+}
+/** Keywords that signal low-poly intent in a prompt (used by make/ai). */
+const LOW_POLY_HINTS = [/low[\s_-]?poly/i, /低模/, /低面/, /手游/, /voxel/i, /像素风/];
+export function detectLowPolyIntent(text) {
+    return LOW_POLY_HINTS.some((re) => re.test(text));
+}

package/dist/src/knowledge/params.js

@@ -0,0 +1,174 @@
+/**
+ * Parameter linkage rules distilled from server-side validation
+ * (TextImageModelValidation / ModelPostProcessValidation / handlers).
+ *
+ * Every rule here prevents a guaranteed 400 or a silently wasted credit.
+ * Rules marked [hard] mirror server enforcement; [soft] are CLI smart defaults.
+ */
+import { CONVERT_FORMATS, EXPORT_ORIENTATIONS, FBX_PRESETS, P1_FACE_LIMIT, P1_FORBIDDEN_PARAMS, TEXTURE_FORMATS, TEXTURE_QUALITIES, isP1, } from './models.js';
+const PROMPT_MAX = 1024;
+const NEGATIVE_PROMPT_MAX = 255;
+/** Validate + auto-fix parameters for 3D generation (text/image/multiview-to-model). */
+export function validateGenerationParams(model, input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    if (typeof params.prompt === 'string' && params.prompt.length > PROMPT_MAX) {
+        errors.push(`prompt exceeds ${PROMPT_MAX} characters (${params.prompt.length})`);
+    }
+    if (typeof params.negative_prompt === 'string' && params.negative_prompt.length > NEGATIVE_PROMPT_MAX) {
+        errors.push(`negative_prompt exceeds ${NEGATIVE_PROMPT_MAX} characters`);
+    }
+    // [hard] pbr=true forces texture=true (PBR is a superset of texturing).
+    if (params.pbr === true && params.texture === false) {
+        params.texture = true;
+        warnings.push('pbr=true forces texture=true (adjusted)');
+    }
+    // [hard] generate_parts outputs bare geometry: texture/pbr/quad must be off.
+    if (params.generate_parts === true) {
+        for (const key of ['texture', 'pbr', 'quad']) {
+            if (params[key] === true) {
+                params[key] = false;
+                warnings.push(`generate_parts=true disables ${key} (adjusted; run "tripo model texture" afterwards)`);
+            }
+        }
+    }
+    // [hard] P1 constraints: strip forbidden params, enforce face_limit range.
+    if (isP1(model)) {
+        for (const key of P1_FORBIDDEN_PARAMS) {
+            if (params[key] !== undefined) {
+                delete params[key];
+                warnings.push(`P1 does not support ${key} (removed)`);
+            }
+        }
+        const face = params.face_limit;
+        if (typeof face === 'number') {
+            if (face < P1_FACE_LIMIT.min || face > P1_FACE_LIMIT.max) {
+                errors.push(`P1 face_limit must be within ${P1_FACE_LIMIT.min}–${P1_FACE_LIMIT.max} (got ${face}); ` +
+                    `use tripo-v3.1 for higher budgets`);
+            }
+        }
+    }
+    else {
+        // [hard] smart_low_poly face_limit windows: 500–20000 tri / 500–10000 quad.
+        if (params.smart_low_poly === true && typeof params.face_limit === 'number') {
+            const max = params.quad === true ? 10000 : 20000;
+            if (params.face_limit < 500 || params.face_limit > max) {
+                errors.push(`smart_low_poly requires face_limit 500–${max}${params.quad === true ? ' (quad halves the budget)' : ''}`);
+            }
+        }
+    }
+    if (params.texture_quality !== undefined &&
+        !TEXTURE_QUALITIES.includes(params.texture_quality)) {
+        errors.push(`texture_quality must be one of ${TEXTURE_QUALITIES.join('/')}`);
+    }
+    // [hard] quad topology cannot be stored in GLB → output will be FBX.
+    if (params.quad === true) {
+        warnings.push('quad=true forces FBX output (quad topology cannot be stored in GLB)');
+    }
+    return { params, warnings, errors };
+}
+/** Validate parameters for models/convert. */
+export function validateConvertParams(input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    const format = typeof params.format === 'string' ? params.format.toUpperCase() : undefined;
+    if (!format) {
+        errors.push(`convert requires format (${CONVERT_FORMATS.join('/')})`);
+    }
+    else if (!CONVERT_FORMATS.includes(format)) {
+        errors.push(`unsupported format "${params.format}" (${CONVERT_FORMATS.join('/')})`);
+    }
+    else {
+        params.format = format;
+    }
+    // [hard] quad topology cannot live in GLTF/GLB.
+    if (params.quad === true && format === 'GLTF') {
+        errors.push('quad=true cannot export GLTF (quad topology is not storable in glTF); use FBX/OBJ/USDZ');
+    }
+    if (params.force_symmetry === true && params.quad !== true) {
+        delete params.force_symmetry;
+        warnings.push('force_symmetry only applies with quad=true (removed)');
+    }
+    if (params.texture_format !== undefined &&
+        !TEXTURE_FORMATS.includes(String(params.texture_format).toUpperCase())) {
+        errors.push(`texture_format must be one of ${TEXTURE_FORMATS.join('/')}`);
+    }
+    else if (typeof params.texture_format === 'string') {
+        params.texture_format = params.texture_format.toUpperCase();
+    }
+    // [hard] vertex colors only survive in OBJ/GLTF exports.
+    if (params.export_vertex_colors === true && format && !['OBJ', 'GLTF'].includes(format)) {
+        delete params.export_vertex_colors;
+        warnings.push(`export_vertex_colors only applies to OBJ/GLTF (removed for ${format})`);
+    }
+    if (params.fbx_preset !== undefined) {
+        if (!FBX_PRESETS.includes(params.fbx_preset)) {
+            errors.push(`fbx_preset must be one of ${FBX_PRESETS.join('/')}`);
+        }
+        else if (format !== 'FBX') {
+            delete params.fbx_preset;
+            warnings.push('fbx_preset only applies to FBX exports (removed)');
+        }
+    }
+    if (params.export_orientation !== undefined &&
+        !EXPORT_ORIENTATIONS.includes(params.export_orientation)) {
+        errors.push(`export_orientation must be one of ${EXPORT_ORIENTATIONS.join('/')}`);
+    }
+    // [soft] cost transparency: any non-default option upgrades billing to
+    // convert_model_complex.
+    const defaults = {
+        texture_size: 4096,
+        texture_format: 'JPEG',
+        bake: true,
+        pack_uv: false,
+        export_vertex_colors: false,
+        pivot_to_center_bottom: false,
+        scale_factor: 1,
+        with_animation: true,
+        animate_in_place: false,
+        export_orientation: '+x',
+        fbx_preset: 'blender',
+        quad: false,
+        flatten_bottom: false,
+        force_symmetry: false,
+    };
+    const complex = Object.entries(defaults).some(([k, dv]) => params[k] !== undefined && params[k] !== dv) || params.face_limit !== undefined || params.part_names !== undefined;
+    if (complex) {
+        warnings.push('non-default convert options use the "complex convert" price tier');
+    }
+    return { params, warnings, errors };
+}
+/** Validate parameters for mesh/decimate. */
+export function validateDecimateParams(input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    if (typeof params.face_limit === 'number' && (params.face_limit < 500 || params.face_limit > 20000)) {
+        errors.push('decimate face_limit must be within 500–20000');
+    }
+    return { params, warnings, errors };
+}
+/** Validate retarget animations list. */
+export function validateRetargetParams(input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    const anims = params.animations;
+    if (Array.isArray(anims)) {
+        if (anims.length === 0)
+            errors.push('animations must not be empty');
+        if (anims.length > 5)
+            errors.push(`retarget accepts at most 5 animations per task (got ${anims.length}); billing is per animation`);
+        if (anims.length === 1) {
+            // Server accepts either `animation` (single) or `animations` (list).
+            params.animation = anims[0];
+            delete params.animations;
+        }
+    }
+    else if (typeof params.animation !== 'string') {
+        errors.push('retarget requires animation (single) or animations (list)');
+    }
+    return { params, warnings, errors };
+}

package/dist/src/knowledge/scenarios.js

@@ -0,0 +1,112 @@
+/**
+ * Scenario decision matrix: --for presets and the AI wizard both read this
+ * table. Changing production strategy means editing data here, not logic.
+ */
+import { MODEL_P1, MODEL_V31 } from './models.js';
+export const SCENARIOS = [
+    {
+        id: 'game-mobile',
+        label: { zh: '手游/低模', en: 'Mobile game / low-poly' },
+        description: { zh: '移动端游戏资产,面数预算严格,干净拓扑', en: 'Mobile game assets with strict face budgets and clean topology' },
+        model: MODEL_P1,
+        genParams: { texture: true, pbr: true, texture_quality: 'standard', face_limit: 15000 },
+        chain: [{ step: 'convert', args: { format: 'FBX', texture_size: 2048 } }],
+        deliverables: ['FBX', 'GLB'],
+        notes: {
+            zh: ['P1 原生低模,拓扑干净', '2K 贴图适配移动端', '需要骨骼时追加 --then rig'],
+            en: ['P1 native low-poly with clean topology', '2K textures for mobile budgets', 'append --then rig if you need a skeleton'],
+        },
+    },
+    {
+        id: 'game-pc',
+        label: { zh: '端游/主机', en: 'PC / console game' },
+        description: { zh: '高预算引擎资产,PBR 全开', en: 'High-budget engine assets with full PBR' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true, texture_quality: 'detailed' },
+        chain: [{ step: 'convert', args: { format: 'FBX' } }],
+        deliverables: ['FBX', 'GLTF'],
+        notes: {
+            zh: ['v3.1 高精度 + detailed 贴图', '需要 LOD 时追加 --then decimate:5000', '进 Blender/3dsMax 用 fbx_preset 对齐'],
+            en: ['v3.1 high fidelity + detailed textures', 'append --then decimate:5000 for LODs', 'use fbx_preset to match Blender/3dsMax'],
+        },
+    },
+    {
+        id: 'film',
+        label: { zh: '影视/离线渲染', en: 'Film / offline rendering' },
+        description: { zh: '细分友好四边面,规格拉满', en: 'Subdivision-friendly quads, maximum quality' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true, quad: true, geometry_quality: 'detailed', texture_quality: 'detailed' },
+        chain: [],
+        deliverables: ['FBX (quad)', 'USDZ/OBJ via convert'],
+        notes: {
+            zh: ['quad=true 输出 FBX(quad 进不了 GLB)', 'geometry detailed 加收 HD credit', '进 USD 管线追加 --then convert:usdz'],
+            en: ['quad=true outputs FBX (quads cannot be stored in GLB)', 'geometry detailed bills an extra HD credit', 'append --then convert:usdz for USD pipelines'],
+        },
+    },
+    {
+        id: 'print',
+        label: { zh: '3D 打印', en: '3D printing' },
+        description: { zh: '水密可打印几何,免贴图省积分', en: 'Watertight printable geometry, skipping textures saves credits' },
+        model: MODEL_V31,
+        genParams: { texture: false, pbr: false },
+        chain: [{ step: 'convert', args: { format: 'STL', flatten_bottom: true } }],
+        deliverables: ['STL', '3MF (colored)'],
+        notes: {
+            zh: ['白模生成,不花贴图积分', 'flatten_bottom 平底利于 FDM', '彩色打印改 --then convert:3mf,export_vertex_colors=true'],
+            en: ['bare geometry: no texture credits spent', 'flatten_bottom helps FDM adhesion', 'for color prints use --then convert:3mf,export_vertex_colors=true'],
+        },
+    },
+    {
+        id: 'ar-web',
+        label: { zh: 'AR/Web/电商', en: 'AR / Web / e-commerce' },
+        description: { zh: '移动端性能预算,glb+usdz 双交付', en: 'Mobile performance budgets with dual glb+usdz delivery' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true },
+        chain: [
+            { step: 'decimate', args: { face_limit: 20000 } },
+            { step: 'convert', args: { format: 'USDZ' } },
+        ],
+        deliverables: ['GLB', 'USDZ'],
+        notes: {
+            zh: ['v3.1 生成后减面到 2 万内', 'iOS QuickLook 需要 USDZ', 'decimate 默认 bake 烘焙贴图到低模'],
+            en: ['generate with v3.1, then decimate under 20k faces', 'iOS QuickLook requires USDZ', 'decimate bakes textures onto the low-poly by default'],
+        },
+    },
+    {
+        id: 'anim',
+        label: { zh: '角色动画', en: 'Character animation' },
+        description: { zh: '绑骨+动作重定向全链路', en: 'Full rig + retarget pipeline' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true },
+        chain: [
+            { step: 'rig-check', args: {} },
+            { step: 'rig', args: { model: 'rig-v2.0', spec: 'tripo', out_format: 'glb' } },
+            { step: 'retarget', args: { animations: ['preset:idle', 'preset:walk'] } },
+        ],
+        deliverables: ['GLB', 'FBX'],
+        notes: {
+            zh: ['先 rig-check 预检,不可绑骨即止损', '接 Mixamo/Unity Humanoid 用 rig:spec=mixamo', '提示词建议 T-pose 站姿,或先 text-to-image template=t_pose'],
+            en: ['rig-check first: stop early if not riggable', 'use rig:spec=mixamo for Mixamo/Unity Humanoid', 'prompt for a T-pose, or pre-generate with text-to-image template=t_pose'],
+        },
+    },
+    {
+        id: 'toy',
+        label: { zh: '风格化摆件', en: 'Stylized toy / desk piece' },
+        description: { zh: '低模可爱风或积木/体素风格化', en: 'Cute low-poly or brick/voxel stylization' },
+        model: MODEL_P1,
+        genParams: { texture: true, pbr: true, face_limit: 20000 },
+        chain: [],
+        deliverables: ['GLB', 'STL via convert'],
+        notes: {
+            zh: ['P1 出干净低模', '积木/体素风追加 --then stylize:lego 或 stylize:voxel', '要打印实物追加 --then convert:stl'],
+            en: ['P1 produces clean low-poly', 'append --then stylize:lego or stylize:voxel for brick/voxel looks', 'append --then convert:stl to print it'],
+        },
+    },
+];
+const byId = new Map(SCENARIOS.map((s) => [s.id, s]));
+export function getScenario(id) {
+    return byId.get(id);
+}
+export function scenarioIds() {
+    return SCENARIOS.map((s) => s.id);
+}

package/dist/src/pipeline/make.js

@@ -0,0 +1,233 @@
+/**
+ * The `make` orchestrator — one entry point that turns any input (text /
+ * image / multiview / model file / task ref) into finished artifacts,
+ * applying the dual-model rule, scenario presets, and the processing chain.
+ * Shared by `tripo make`, `tripo ai`, `tripo redo`, batch, and the MCP server.
+ */
+import { basename } from 'node:path';
+import { UsageError } from '../core/errors.js';
+import { log, warn } from '../core/output.js';
+import { buildImageToModel, buildMultiviewToModel, buildStepRequest, buildTextToModel, } from '../core/requests.js';
+import { precheckBalance, resolveInputValue, runTask } from '../core/task-service.js';
+import { t } from '../i18n.js';
+import { validateChain, ChainError } from '../knowledge/chains.js';
+import { chooseModel, detectLowPolyIntent } from '../knowledge/models.js';
+import { getScenario } from '../knowledge/scenarios.js';
+import { classifyInputs } from '../util/input-detect.js';
+import { runChain, assertSourceReady } from './runner.js';
+/** Build the full plan (no network calls except none): what model, what chain, why. */
+export async function planMake(client, options) {
+    const classified = classifyInputs(options.inputs);
+    const scenario = options.scenario ? getScenario(options.scenario) : undefined;
+    if (options.scenario && !scenario) {
+        throw new UsageError(`unknown scenario "${options.scenario}" (valid: game-mobile, game-pc, film, print, ar-web, anim, toy)`);
+    }
+    const userParams = options.params ?? {};
+    const genParams = { ...(scenario?.genParams ?? {}), ...userParams };
+    const chain = options.chain && options.chain.length > 0 ? options.chain : (scenario?.chain ?? []);
+    const warnings = [];
+    if (options.chain && options.chain.length > 0 && scenario && scenario.chain.length > 0) {
+        warnings.push(t({
+            zh: `--then 覆盖了 ${scenario.id} 场景默认加工链`,
+            en: `--then overrides the default ${scenario.id} processing chain`,
+        }));
+    }
+    switch (classified.kind) {
+        case 'text': {
+            const prompt = classified.values[0].value;
+            const choice = chooseModel({
+                explicit: options.model ?? scenario?.model,
+                faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
+                lowPoly: detectLowPolyIntent(prompt),
+            });
+            const generation = buildTextToModel(prompt, choice.model, genParams);
+            return {
+                generation,
+                chain,
+                model: choice.model,
+                modelReason: choice.reason,
+                name: options.name ?? prompt,
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'image':
+        case 'url-image': {
+            const raw = classified.values[0].value;
+            const { value } = await resolveInputValue(client, raw);
+            const choice = chooseModel({
+                explicit: options.model ?? scenario?.model,
+                faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
+            });
+            const generation = buildImageToModel(value, choice.model, genParams);
+            return {
+                generation,
+                chain,
+                model: choice.model,
+                modelReason: choice.reason,
+                name: options.name ?? basename(raw),
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'multiview': {
+            const views = await assignViews(client, classified.values.map((v) => v.value));
+            const choice = chooseModel({
+                explicit: options.model ?? scenario?.model,
+                faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
+            });
+            const generation = buildMultiviewToModel(views, choice.model, genParams);
+            return {
+                generation,
+                chain,
+                model: choice.model,
+                modelReason: choice.reason,
+                name: options.name ?? basename(classified.values[0].value),
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'model': {
+            const raw = classified.values[0].value;
+            const { value } = await resolveInputValue(client, raw);
+            const generation = buildStepRequest('import', value, {});
+            if (chain.length === 0) {
+                warnings.push(t({
+                    zh: '导入模型后没有加工步骤;用 --then 指定(如 --then texture,rig)',
+                    en: 'importing a model with no processing steps; add --then (e.g. --then texture,rig)',
+                }));
+            }
+            return {
+                generation,
+                chain,
+                name: options.name ?? basename(raw),
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'task': {
+            const { value, sourceTaskType } = await resolveInputValue(client, classified.values[0].value);
+            if (chain.length === 0) {
+                throw new UsageError('a task reference needs processing steps: add --then (e.g. tripo make @last --then texture,convert:fbx)');
+            }
+            return {
+                sourceTaskId: value,
+                sourceType: sourceTaskType,
+                chain,
+                name: options.name ?? value.slice(0, 8),
+                warnings,
+            };
+        }
+    }
+}
+/** Execute a plan produced by planMake. */
+export async function executeMake(client, plan, options) {
+    for (const w of plan.warnings)
+        warn(w);
+    // Validate chain legality up front so an illegal plan spends zero credits.
+    if (plan.chain.length > 0) {
+        const upstream = plan.generation?.taskType ?? plan.sourceType;
+        if (upstream) {
+            try {
+                validateChain(plan.chain, upstream);
+            }
+            catch (error) {
+                if (error instanceof ChainError)
+                    throw new UsageError(error.message);
+                throw error;
+            }
+        }
+    }
+    await precheckBalance(client);
+    let sourceTaskId;
+    let sourceType;
+    let primary;
+    if (plan.generation) {
+        if (plan.model && plan.modelReason) {
+            log(t({ zh: `模型选择:${plan.model}(${plan.modelReason})`, en: `model: ${plan.model} (${plan.modelReason})` }));
+        }
+        primary = await runTask({
+            client,
+            request: plan.generation.request,
+            taskType: plan.generation.taskType,
+            name: plan.name,
+            outDir: options.outDir,
+            noWait: options.noWait,
+            noDownload: options.noDownload || plan.chain.length > 0,
+            timeoutMs: options.timeoutMs,
+            notify: options.notify && plan.chain.length === 0,
+            precheckBalance: false,
+        });
+        if (options.noWait)
+            return { primary, chainResults: [] };
+        sourceTaskId = primary.task_id;
+        sourceType = plan.generation.taskType;
+    }
+    else {
+        sourceTaskId = plan.sourceTaskId;
+        sourceType = plan.sourceType ?? (await assertSourceReady(client, sourceTaskId));
+        primary = { task_id: sourceTaskId, type: sourceType, status: 'success' };
+    }
+    if (plan.chain.length === 0) {
+        return { primary, chainResults: [] };
+    }
+    const { results, stoppedEarly } = await runChain({
+        client,
+        chain: plan.chain,
+        sourceTaskId,
+        sourceType,
+        namePrefix: plan.name,
+        outDir: options.outDir,
+        notify: false,
+        timeoutMs: options.timeoutMs,
+    });
+    // If the chain stopped early (not riggable) and nothing was downloaded yet,
+    // fetch the source artifacts so the user still gets their model.
+    if (stoppedEarly && plan.generation && !options.noDownload) {
+        const detail = await client.getTask(sourceTaskId);
+        const { downloadArtifacts, defaultOutputDir } = await import('../core/download.js');
+        const { slugify } = await import('../config/history.js');
+        const dir = defaultOutputDir(options.outDir ?? process.cwd(), slugify(plan.name), sourceTaskId);
+        const artifacts = await downloadArtifacts(detail, dir);
+        primary.output_dir = artifacts.outputDir;
+        primary.model_file = artifacts.modelFile;
+        primary.preview = artifacts.preview;
+    }
+    return { primary, chainResults: results, stoppedEarly };
+}
+/**
+ * Map 2–4 images to views. Filename hints (front/back/left/right, 前/后/左/右)
+ * win; remaining slots fill positionally in [front, left, back, right] order.
+ */
+export async function assignViews(client, files) {
+    if (files.length < 2 || files.length > 4) {
+        throw new UsageError(`multiview needs 2–4 images (got ${files.length})`);
+    }
+    const hints = {
+        front: /front|正面|前/i,
+        back: /back|背面|后/i,
+        left: /left|左/i,
+        right: /right|右/i,
+    };
+    const views = {};
+    const unassigned = [];
+    for (const file of files) {
+        const name = basename(file);
+        const hit = Object.entries(hints).find(([view, re]) => !views[view] && re.test(name));
+        if (hit)
+            views[hit[0]] = file;
+        else
+            unassigned.push(file);
+    }
+    const order = ['front', 'left', 'back', 'right'];
+    for (const file of unassigned) {
+        const slot = order.find((v) => !views[v]);
+        if (!slot)
+            throw new UsageError('too many images for 4 view slots');
+        views[slot] = file;
+    }
+    if (!views.front) {
+        throw new UsageError('multiview requires a front view — name one file with "front" or pass it first');
+    }
+    const resolved = {};
+    for (const [view, file] of Object.entries(views)) {
+        resolved[view] = (await resolveInputValue(client, file)).value;
+    }
+    return resolved;
+}