tripo-cli 0.3.2 → 0.5.0

package/README.md

@@ -20,7 +20,8 @@ Works with both Tripo regions from the same install — international (`openapi.
 ## Why this CLI
 
 - **One magic command.** `tripo make <anything>` detects what you gave it — prompt text, an image, 2–4 view images, a model file, a URL, a task id, or `@last` — picks the right endpoint, model, and parameters, then waits and downloads the artifacts. No file_token, no polling loops.
-- **A 3D domain brain, not a thin API wrapper.** Model choice is a fixed rule (low-poly intent or face budget ≤ 20000 → `tripo-p1`, everything else → `tripo-v3.1`), P1's illegal parameters are stripped locally, quad + GLB is rejected before it costs you credits, and 7 scenario presets (`--for game-mobile|game-pc|film|print|ar-web|anim|toy`) encode sane parameters + processing chains + delivery formats.
+- **A 3D domain brain, not a thin API wrapper.** Model choice is a fixed rule (low-poly intent or face budget ≤ 20000 → `tripo-p1`, everything else → `tripo-v3.1`; opt into the P-series **Preview** with `--model tripo-p2` for quad low-poly). Those are CLI aliases — the wire value the API receives is `P1-20260311` / `v3.1-20260211` / `P2-20260801` (full alias ↔ wire ↔ status table: `tripo docs --topic commands/generate`; official [Models & Versions](https://developers.tripo3d.ai/en/docs/models-and-versions) and [P Series](https://developers.tripo3d.ai/en/models/p1) pages). P-series illegal parameters are stripped locally, quad + GLB is rejected before it costs you credits, and 7 scenario presets (`--for game-mobile|game-pc|film|print|ar-web|anim|toy`) encode sane parameters + processing chains + delivery formats.
+- **You see the plan before you pay.** `tripo make` prints a plan card — one numbered line per API call (endpoint, what it does, its arguments) — and asks before submitting; afterwards it reports the total credits **and** a per-task breakdown. `--yes` (automatic when headless) skips the question but keeps the card in the log.
 - **Agent-native.** Non-TTY runs are automatically headless (`--json --yes --no-open`), stdout carries exactly one JSON line per command, progress goes to stderr, exit codes are stable, and NDJSON pipes compose: `tripo make cat.png | tripo model texture | tripo anim rig`. An LLM-facing skill package ships inside the npm package (`tripo docs --llm`).
 
 ## Commands
@@ -39,7 +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 docs [--topic t]` | print the bundled agent/skill docs |
+| `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 |
 
@@ -88,6 +89,7 @@ tripo batch run assets.yaml --concurrency 2
 ## For AI coding agents
 
 - `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.
 - `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`.

package/dist/ai/experts.js

@@ -7,12 +7,12 @@
  * result is re-validated locally before anything is spent.
  */
 import { getLocale, t, tList } from '../i18n.js';
-import { parseThenExpression, validateChain, STEPS } from '../knowledge/chains.js';
+import { availableSteps, parseThenExpression, validateChain } from '../knowledge/chains.js';
 import { chooseModel, detectLowPolyIntent, RIG_MODEL_V25 } from '../knowledge/models.js';
 import { getScenario, SCENARIOS } from '../knowledge/scenarios.js';
 import { chatJson } from './llm.js';
 const SCENARIO_TABLE = SCENARIOS.map((s) => `- ${s.id}: ${s.description.en} | model=${s.model} | chain=${s.chain.map((c) => c.step).join('→') || 'none'} | deliver=${s.deliverables.join('/')}`).join('\n');
-const STEP_TABLE = STEPS.map((s) => s.name).join(', ');
+const STEP_TABLE = availableSteps().map((s) => s.name).join(', ');
 const PRODUCER_SYSTEM = `You are the producer/router of the Tripo 3D generation CLI.
 Classify the user's request into exactly one scenario and extract a clean English 3D generation prompt.
 

package/dist/ai/plan-card.js

@@ -5,7 +5,71 @@
  */
 import pc from 'picocolors';
 import { t } from '../i18n.js';
+import { getStep } from '../knowledge/chains.js';
 import { getScenario } from '../knowledge/scenarios.js';
+const GENERATION_DESCRIBE = {
+    text_to_model: { zh: '文本生成 3D 模型', en: 'generate a 3D model from text' },
+    image_to_model: { zh: '单图生成 3D 模型', en: 'generate a 3D model from one image' },
+    multiview_to_model: { zh: '多视图生成 3D 模型', en: 'generate a 3D model from multiple views' },
+};
+/** Keys that describe the input itself (already shown on the "input" line). */
+const INPUT_KEYS = new Set(['prompt', 'input', 'inputs']);
+/** Build the pre-run card for `tripo make` from the plan it is about to execute. */
+export function cardFromMakePlan(plan, opts) {
+    const steps = [];
+    const genParams = {};
+    if (plan.generation) {
+        const { taskType, request } = plan.generation;
+        const args = {};
+        for (const [k, v] of Object.entries(request.payload)) {
+            if (INPUT_KEYS.has(k))
+                continue;
+            args[k] = v;
+            if (k !== 'model')
+                genParams[k] = v;
+        }
+        const importDef = taskType === 'import_model' ? getStep('import') : undefined;
+        steps.push({
+            name: importDef ? importDef.name : taskType.replace(/_/g, '-'),
+            endpoint: request.endpoint,
+            describe: importDef ? t(importDef.describe) : t(GENERATION_DESCRIBE[taskType] ?? { zh: '生成', en: 'generate' }),
+            args,
+        });
+    }
+    for (const spec of plan.chain) {
+        const def = getStep(spec.step);
+        steps.push({
+            name: spec.step,
+            endpoint: def?.endpoint ?? '',
+            describe: def ? t(def.describe) : '',
+            args: spec.args,
+        });
+    }
+    const scenario = opts.scenario ? getScenario(opts.scenario) : undefined;
+    const notes = [];
+    if (opts.candidates && opts.candidates > 1) {
+        notes.push(t({
+            zh: `并行生成 ${opts.candidates} 个候选(不同 seed),选中一个后再继续加工链`,
+            en: `${opts.candidates} candidates in parallel (distinct seeds); pick one before the chain continues`,
+        }));
+    }
+    // Task refs (@last / @name) resolve to an id the human has not seen yet — show it.
+    let inputSummary = opts.inputs.join(' ');
+    if (plan.sourceTaskId && inputSummary !== plan.sourceTaskId) {
+        inputSummary += ` → ${plan.sourceTaskId}${plan.sourceType ? ` (${plan.sourceType})` : ''}`;
+    }
+    return {
+        inputSummary,
+        scenario: opts.scenario,
+        model: plan.model,
+        modelReason: plan.modelReason,
+        genParams,
+        chain: plan.chain,
+        deliverables: scenario?.deliverables ?? [],
+        notes,
+        steps,
+    };
+}
 /** Cost-impact annotations derived from the parameter set. */
 export function costNotes(card) {
     const notes = [];
@@ -48,15 +112,27 @@ export function renderPlanCard(card) {
     if (card.model) {
         lines.push(`${t({ zh: '模型', en: 'model' })}: ${card.model}${card.modelReason ? pc.dim(` — ${card.modelReason}`) : ''}`);
     }
-    const params = Object.entries(card.genParams);
-    if (params.length > 0) {
-        lines.push(`${t({ zh: '参数', en: 'params' })}: ${params.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(' ')}`);
+    const fmtArgs = (args) => Object.entries(args).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(' ');
+    if (card.steps && card.steps.length > 0) {
+        // Numbered step list: what each call does, which endpoint, with which args.
+        lines.push(`${t({ zh: '步骤', en: 'steps' })}:`);
+        card.steps.forEach((step, i) => {
+            lines.push(`  ${i + 1}. ${step.name}  ${pc.dim(`POST ${step.endpoint}`)}${step.describe ? ` — ${step.describe}` : ''}`);
+            if (Object.keys(step.args).length > 0)
+                lines.push(pc.dim(`     ${fmtArgs(step.args)}`));
+        });
     }
-    if (card.chain.length > 0) {
-        const chainStr = card.chain
-            .map((s) => (Object.keys(s.args).length > 0 ? `${s.step}(${Object.entries(s.args).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(',')})` : s.step))
-            .join(' → ');
-        lines.push(`${t({ zh: '加工链', en: 'chain' })}: ${chainStr}`);
+    else {
+        const params = Object.entries(card.genParams);
+        if (params.length > 0) {
+            lines.push(`${t({ zh: '参数', en: 'params' })}: ${fmtArgs(card.genParams)}`);
+        }
+        if (card.chain.length > 0) {
+            const chainStr = card.chain
+                .map((s) => (Object.keys(s.args).length > 0 ? `${s.step}(${Object.entries(s.args).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(',')})` : s.step))
+                .join(' → ');
+            lines.push(`${t({ zh: '加工链', en: 'chain' })}: ${chainStr}`);
+        }
     }
     if (card.deliverables.length > 0) {
         lines.push(`${t({ zh: '交付物', en: 'deliverables' })}: ${card.deliverables.join(', ')}`);

package/dist/commands/completion.js

@@ -1,5 +1,6 @@
 /** `tripo completion <shell>` — static shell completion scripts. */
 import { UsageError } from '../core/errors.js';
+import { isMeshEditEnabled } from '../knowledge/chains.js';
 const COMMANDS = [
     'login', 'logout', 'whoami', 'use', 'balance', 'usage', 'topup',
     'make', 'view', 'redo', 'ai',
@@ -10,7 +11,7 @@ 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'],
     model: ['refine', 'texture', 'stylize', 'convert', 'import'],
     anim: ['check', 'rig', 'retarget'],
-    mesh: ['segment', 'complete', 'decimate', 'smartsegment'],
+    mesh: ['segment', 'complete', 'decimate', ...(isMeshEditEnabled() ? ['edit'] : []), 'smartsegment'],
     task: ['get', 'list', 'watch'],
     files: ['upload'],
     batch: ['run'],

package/dist/commands/make.js

@@ -4,12 +4,18 @@
  * model, the parameters, runs the chain, and downloads the artifacts.
  */
 import * as p from '@clack/prompts';
-import { UsageError } from '../core/errors.js';
+import { TripoClient } from '../core/client.js';
+import { AuthError, UsageError } from '../core/errors.js';
 import { emitResult, isInteractive, log, warn } from '../core/output.js';
+import { buildStepRequest } from '../core/requests.js';
 import { t } from '../i18n.js';
+import { ChainError, getStep } from '../knowledge/chains.js';
+import { EXIT } from '../knowledge/error-catalog.js';
 import { scenarioIds } from '../knowledge/scenarios.js';
-import { executeMake, planMake } from '../pipeline/make.js';
-import { newClient, parseChainFlag, printTaskResult, withTaskOptions } from './shared.js';
+import { cardFromMakePlan, costNotes, renderPlanCard } from '../ai/plan-card.js';
+import { checkPlanChain, executeMake, planMake } from '../pipeline/make.js';
+import { detectInput, InputDetectError } from '../util/input-detect.js';
+import { newClient, parseChainFlag, printTaskResult, summarizeCredits, withTaskOptions } from './shared.js';
 import { printInlineImage } from '../util/term-image.js';
 export function registerMakeCommand(program) {
     const cmd = program
@@ -18,17 +24,40 @@ export function registerMakeCommand(program) {
         .argument('<input...>', 'prompt text, image file(s), model file, URL, task id, or @last')
         .option('--for <scenario>', `scenario preset: ${scenarioIds().join('|')}`)
         .option('--then <steps>', 'processing chain, e.g. "texture,rig,convert:fbx"')
-        .option('--model <model>', 'force model version (tripo-v3.1 / tripo-p1 / ...)')
+        .option('--model <model>', 'force model version (tripo-v3.1 / tripo-p1 / tripo-p2 / ...)')
         .option('-n, --candidates <n>', 'generate N candidates in parallel', (v) => Number(v), 1)
-        .option('--seed <n>', 'model_seed for reproducible geometry', (v) => Number(v));
+        .option('--seed <n>', 'model_seed for reproducible geometry', (v) => Number(v))
+        .option('--dry-run', 'plan + validate only: print model, completed params and chain steps; no upload, no submit, no credits');
     withTaskOptions(cmd);
     cmd.action(async (inputs, flags) => {
         const result = await runMake(inputs, flags);
+        if (result.cancelled)
+            return;
         emitMakeOutcome(result);
     });
 }
+/**
+ * Show what is about to run (one numbered line per API call) and ask before
+ * spending credits. `--yes` / headless callers see the card on stderr but are
+ * not prompted. Returns false when the human declines.
+ *
+ * Gate on isInteractive() (both stdin and stdout TTYs), not just --yes: when
+ * stdout is a pipe (`tripo make x | tripo model texture`) the clack prompt
+ * would land in the pipe, corrupt the JSON contract and block forever.
+ */
+async function confirmPlan(plan, inputs, flags) {
+    const card = cardFromMakePlan(plan, { inputs, scenario: flags.for, candidates: flags.candidates });
+    log(renderPlanCard(card));
+    if (!isInteractive())
+        return true;
+    const go = await p.confirm({ message: t({ zh: '按方案执行?', en: 'Run this plan?' }) });
+    if (p.isCancel(go) || !go) {
+        log(t({ zh: '已取消,未消耗积分', en: 'cancelled; no credits spent' }));
+        return false;
+    }
+    return true;
+}
 export async function runMake(inputs, flags) {
-    const client = newClient();
     const params = { ...flags.param };
     if (flags.seed !== undefined)
         params.model_seed = flags.seed;
@@ -45,9 +74,18 @@ export async function runMake(inputs, flags) {
         notify: flags.notify,
         timeoutMs: flags.timeout ? flags.timeout * 1000 : undefined,
     };
+    const cancelled = { results: [], chainResults: [], cancelled: true };
+    if (flags.dryRun) {
+        // The plan itself is the result; nothing is submitted.
+        await dryRunMake(inputs, flags, options);
+        return cancelled;
+    }
+    const client = newClient();
     const n = flags.candidates;
     if (n <= 1) {
         const plan = await planMake(client, options);
+        if (!(await confirmPlan(plan, inputs, flags)))
+            return cancelled;
         const outcome = await executeMake(client, plan, options);
         return { results: [outcome.primary], chainResults: outcome.chainResults, stoppedEarly: outcome.stoppedEarly };
     }
@@ -63,6 +101,8 @@ export async function runMake(inputs, flags) {
     if (chain.length > 0 && !interactive) {
         throw new UsageError('-n with --then needs an interactive terminal to pick the winner; run the chain afterwards with "tripo make <task-id> --then ..."');
     }
+    if (!(await confirmPlan(basePlan, inputs, flags)))
+        return cancelled;
     log(t({ zh: `并行生成 ${n} 个候选…`, en: `generating ${n} candidates in parallel…` }));
     const seeds = Array.from({ length: n }, () => Math.floor(Math.random() * 2 ** 31));
     const runs = seeds.map((seed, i) => (async () => {
@@ -118,8 +158,156 @@ export async function runMake(inputs, flags) {
     }
     return { results, chainResults, stoppedEarly };
 }
+const UPSTREAM_PLACEHOLDER = '<upstream>';
+/** Dry runs never send a request, so a missing API key must not block them. */
+function dryRunClient() {
+    try {
+        return newClient();
+    }
+    catch (err) {
+        if (err instanceof AuthError)
+            return new TripoClient({ apiKey: 'dry-run' });
+        throw err;
+    }
+}
+/**
+ * `--dry-run`: build and validate the plan with zero network calls, then emit
+ * it as the business result (JSON or the plan card). Blocking problems set
+ * exit code 2 so an agent can fix the request before spending credits.
+ */
+async function dryRunMake(inputs, flags, options) {
+    const warnings = [];
+    const errors = [];
+    const pendingUploads = inputs.filter((raw) => {
+        try {
+            const kind = detectInput(raw).kind;
+            return kind === 'image-file' || kind === 'model-file';
+        }
+        catch {
+            return false;
+        }
+    });
+    let plan;
+    try {
+        plan = await planMake(dryRunClient(), { ...options, dryRun: true });
+    }
+    catch (err) {
+        if (!(err instanceof UsageError || err instanceof InputDetectError || err instanceof ChainError))
+            throw err;
+        errors.push(err.message);
+    }
+    if (!plan) {
+        emitDryRun({
+            dry_run: true,
+            valid: false,
+            input: inputs.join(' '),
+            scenario: flags.for,
+            steps: [],
+            pending_uploads: pendingUploads,
+            deliverables: [],
+            candidates: flags.candidates,
+            warnings,
+            errors,
+            cost_notes: [],
+        });
+        return;
+    }
+    warnings.push(...plan.warnings);
+    try {
+        checkPlanChain(plan);
+    }
+    catch (err) {
+        if (!(err instanceof UsageError))
+            throw err;
+        errors.push(err.message);
+    }
+    if (plan.chain.length > 0 && !plan.generation && !plan.sourceType) {
+        warnings.push(`chain legality unverified: upstream task type unknown (no local history for ${plan.sourceTaskId}); the real run checks it via the API`);
+    }
+    if (flags.candidates > 4)
+        errors.push('at most 4 candidates per run (-n 4)');
+    if (flags.candidates > 1 && !plan.generation) {
+        errors.push('-n only applies to generation inputs (text/image), not task references');
+    }
+    // Same card the real run shows; chain-step args are replaced by the
+    // normalized payloads so the human sees the completed parameters too.
+    const card = cardFromMakePlan(plan, { inputs, scenario: flags.for, candidates: flags.candidates });
+    const cardSteps = card.steps ?? [];
+    const steps = [];
+    if (plan.generation) {
+        steps.push({
+            name: cardSteps[0]?.name ?? plan.generation.taskType,
+            endpoint: plan.generation.request.endpoint,
+            task_type: plan.generation.taskType,
+            payload: plan.generation.request.payload,
+        });
+    }
+    plan.chain.forEach((spec, i) => {
+        const cardStep = cardSteps[(plan.generation ? 1 : 0) + i];
+        try {
+            const built = buildStepRequest(spec.step, UPSTREAM_PLACEHOLDER, spec.args);
+            warnings.push(...built.warnings);
+            if (cardStep) {
+                const args = { ...built.request.payload };
+                delete args.input;
+                cardStep.args = args;
+            }
+            steps.push({ name: spec.step, endpoint: built.request.endpoint, task_type: built.taskType, payload: built.request.payload });
+        }
+        catch (err) {
+            if (!(err instanceof UsageError))
+                throw err;
+            errors.push(`${spec.step}: ${err.message}`);
+            steps.push({
+                name: spec.step,
+                endpoint: cardStep?.endpoint ?? '',
+                task_type: getStep(spec.step)?.produces ?? '',
+                payload: { input: UPSTREAM_PLACEHOLDER, ...spec.args },
+            });
+        }
+    });
+    emitDryRun({
+        dry_run: true,
+        valid: errors.length === 0,
+        input: card.inputSummary,
+        source_task_id: plan.sourceTaskId,
+        source_type: plan.sourceType,
+        scenario: flags.for,
+        model: plan.model,
+        model_reason: plan.modelReason,
+        steps,
+        pending_uploads: pendingUploads,
+        deliverables: card.deliverables,
+        candidates: flags.candidates,
+        warnings,
+        errors,
+        cost_notes: costNotes(card),
+    }, renderPlanCard(card));
+}
+/** stdout: one JSON line, or the card followed by warnings/errors and the verdict. */
+function emitDryRun(result, cardText) {
+    const lines = cardText ? [cardText] : [];
+    if (result.warnings.length > 0) {
+        lines.push(t({ zh: '警告(已自动调整):', en: 'warnings (auto-adjusted):' }));
+        for (const w of result.warnings)
+            lines.push(`  ! ${w}`);
+    }
+    if (result.errors.length > 0) {
+        lines.push(t({ zh: '错误(阻断):', en: 'errors (blocking):' }));
+        for (const e of result.errors)
+            lines.push(`  ✗ ${e}`);
+    }
+    lines.push(result.valid
+        ? t({ zh: 'dry run:方案有效;未提交任务,未消耗积分', en: 'dry run: plan is valid; nothing submitted, no credits spent' })
+        : t({ zh: 'dry run:方案无效;修正上述错误后重试', en: 'dry run: plan is invalid; fix the errors above and retry' }));
+    emitResult(result, lines.join('\n'));
+    if (!result.valid)
+        process.exitCode = EXIT.USAGE;
+}
 export function emitMakeOutcome(outcome) {
     const finalChain = outcome.chainResults[outcome.chainResults.length - 1];
+    // Every task this run paid for: generation(s) first, then each chain step.
+    const credits = summarizeCredits([...outcome.results, ...outcome.chainResults]);
     if (outcome.results.length === 1) {
         const primary = outcome.results[0];
         const merged = finalChain
@@ -129,14 +317,26 @@ export function emitMakeOutcome(outcome) {
             merged.chain = outcome.chainResults;
         if (outcome.stoppedEarly)
             merged.stopped_early = outcome.stoppedEarly;
+        if (credits.breakdown.length > 1) {
+            merged.credits_consumed = credits.total;
+            merged.credits_breakdown = credits.breakdown;
+        }
         printTaskResult(merged);
         if (merged.preview)
             printInlineImage(merged.preview);
     }
     else {
-        const human = outcome.results
-            .map((r, i) => `#${i + 1} ${r.task_id} ${r.output_dir ?? r.status}`)
-            .join('\n');
-        emitResult({ candidates: outcome.results, chain: outcome.chainResults }, human);
+        const lines = outcome.results.map((r, i) => `#${i + 1} ${r.task_id} ${r.output_dir ?? r.status}`);
+        if (credits.breakdown.length > 0) {
+            lines.push(t({ zh: `消耗积分合计: ${credits.total}`, en: `credits consumed (total): ${credits.total}` }));
+            for (const line of credits.breakdown)
+                lines.push(`  ${line.type}  ${line.task_id}  ${line.credits_consumed}`);
+        }
+        emitResult({
+            candidates: outcome.results,
+            chain: outcome.chainResults,
+            credits_consumed: credits.total,
+            credits_breakdown: credits.breakdown,
+        }, lines.join('\n'));
     }
 }

package/dist/commands/mcp.js

@@ -26,7 +26,7 @@ const TOOLS = [
                 input: { type: 'string', description: 'prompt text, image file path, image URL, or task id' },
                 scenario: { type: 'string', enum: scenarioIds(), description: 'production scenario preset' },
                 then: { type: 'string', description: 'processing chain, e.g. "texture,rig,convert:fbx"' },
-                model: { type: 'string', description: 'force model: tripo-v3.1 or tripo-p1' },
+                model: { type: 'string', description: 'force model: tripo-v3.1, tripo-p1 or tripo-p2 (P-series preview with quad)' },
                 output_dir: { type: 'string', description: 'directory for artifacts' },
             },
             required: ['input'],

package/dist/commands/process-groups.js

@@ -9,7 +9,7 @@ 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 { getStep, isMeshEditEnabled } from '../knowledge/chains.js';
 import { readPipedTask } from '../pipeline/stdin.js';
 import { newClient, printTaskResult, withTaskOptions } from './shared.js';
 async function resolveStepInput(client, raw) {
@@ -84,6 +84,8 @@ function collectStepArgs(step, flags) {
             return pick(['completion_mode']);
         case 'smartsegment':
             return pick(['seg_type', 'granularity', 'hint']);
+        case 'edit':
+            return pick(['bbox', 'face_limit', 'ref_image', 'model']);
         default:
             return {};
     }
@@ -157,6 +159,22 @@ export function registerProcessCommands(program) {
         .option('--face-limit <n>', 'target faces 500–20000 tri / 500–10000 quad', (v) => Number(v))
         .option('--quad', 'quad output')
         .option('--no-bake', 'skip baking textures onto the low-poly')).action(makeStepAction('decimate'));
+    // Hidden until /v3/mesh/edit is live server-side (see isMeshEditEnabled).
+    if (isMeshEditEnabled()) {
+        withTaskOptions(mesh
+            .command('edit [input]')
+            .description('local retry/refine inside a bounding box (P2 pipeline, model P2-20260801)')
+            .option('--bbox <x1,y1,z1,x2,y2,z2>', 'required 2×3 axis-aligned bbox in model space')
+            .option('--face-limit <n>', 'output face limit (≥100)', (v) => Number(v))
+            .option('--ref-image <file-or-url>', 'reference image for semantic guidance')
+            .option('--model <v>', 'P2-20260801 (only supported value)')).action(async (input, flags) => {
+            // --ref-image may be a local file: upload it to a file_token first.
+            if (typeof flags.refImage === 'string') {
+                flags.refImage = (await resolveInputValue(newClient(), flags.refImage)).value;
+            }
+            await makeStepAction('edit')(input, flags);
+        });
+    }
     withTaskOptions(mesh
         .command('smartsegment [input]')
         .description('smart segmentation (image or model pipeline)')

package/dist/commands/shared.js

@@ -51,6 +51,21 @@ export function parseChainFlag(value) {
         return undefined;
     return parseThenExpression(value);
 }
+/**
+ * Sum the spend of every task in a run and keep the per-task lines. Tasks
+ * without a settled `credits_consumed` (e.g. --no-wait) are skipped.
+ */
+export function summarizeCredits(tasks) {
+    const breakdown = [];
+    let total = 0;
+    for (const task of tasks) {
+        if (task.credits_consumed === undefined)
+            continue;
+        breakdown.push({ task_id: task.task_id, type: task.type, credits_consumed: task.credits_consumed });
+        total += task.credits_consumed;
+    }
+    return { total, breakdown };
+}
 /** Standard result output for a finished task (human + JSON modes). */
 export function printTaskResult(result) {
     const lines = [];
@@ -58,7 +73,14 @@ export function printTaskResult(result) {
         zh: `任务 ${result.task_id} ${result.status === 'success' ? '完成' : result.status}`,
         en: `task ${result.task_id} ${result.status}`,
     }));
-    if (result.credits_consumed !== undefined) {
+    if (result.credits_breakdown && result.credits_breakdown.length > 1) {
+        lines.push(t({ zh: `消耗积分合计: ${result.credits_consumed}`, en: `credits consumed (total): ${result.credits_consumed}` }));
+        const typeWidth = Math.max(...result.credits_breakdown.map((l) => l.type.length));
+        for (const line of result.credits_breakdown) {
+            lines.push(`  ${line.type.padEnd(typeWidth)}  ${line.task_id}  ${line.credits_consumed}`);
+        }
+    }
+    else if (result.credits_consumed !== undefined) {
         lines.push(t({ zh: `消耗积分: ${result.credits_consumed}`, en: `credits consumed: ${result.credits_consumed}` }));
     }
     if (result.output_dir) {

package/dist/core/requests.js

@@ -5,7 +5,7 @@
  * `parameters`), so new API options work without a CLI release.
  */
 import { getStep } from '../knowledge/chains.js';
-import { validateConvertParams, validateDecimateParams, validateGenerationParams, validateRetargetParams, } from '../knowledge/params.js';
+import { validateConvertParams, validateDecimateParams, validateGenerationParams, validateMeshEditParams, validateRetargetParams, } from '../knowledge/params.js';
 import { CAPABILITY_DEFAULTS, SEGMENT_MODELS, TEXTURE_MODELS, normalizeModel, normalizeRigModel, } from '../knowledge/models.js';
 import { UsageError } from './errors.js';
 function ensure(result) {
@@ -135,6 +135,13 @@ export function buildStepRequest(stepName, input, args) {
             warnings.push(...v.warnings);
             break;
         }
+        case 'edit': {
+            const v = validateMeshEditParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
         case 'rig': {
             // Marketing names (rig-v1.0/rig-v2.0) are rejected by the server; normalize to wire versions.
             params.model = params.model === undefined

package/dist/core/task-service.js

@@ -16,8 +16,16 @@ 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) {
+/** Placeholder `input` value for a local file that a dry run would upload. */
+export function uploadPlaceholder(path) {
+    return `<upload:${path}>`;
+}
+/**
+ * Resolve a user input string into the API `input` value (upload as needed).
+ * `dryRun` skips the upload and returns a `<upload:path>` placeholder so the
+ * plan can be built with zero network calls.
+ */
+export async function resolveInputValue(client, raw, opts = {}) {
     const detected = detectInput(raw);
     switch (detected.kind) {
         case 'history-ref': {
@@ -36,6 +44,8 @@ export async function resolveInputValue(client, raw) {
         }
         case 'image-file':
         case 'model-file': {
+            if (opts.dryRun)
+                return { value: uploadPlaceholder(detected.value) };
             const token = await uploadLocalFile(client, detected.value);
             return { value: token };
         }