tripo-cli 0.4.0 → 0.5.1

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`; opt into the P-series preview with `--model tripo-p2` for quad low-poly), 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.
+- **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,8 @@ 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 update [--check]` | upgrade to the latest release (`npm install -g tripo-cli@latest`); every command also hints when a newer version exists |
+| `tripo docs [--topic t]` | print the bundled agent/skill docs (`--topic commands/generate` has the model versions / P series table) |
 | `tripo mcp` | run as an MCP server (Cursor / Claude Desktop) |
 | `tripo completion <shell>` | bash/zsh/fish completion |
 
@@ -88,6 +90,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`.
@@ -101,6 +104,8 @@ tripo batch run assets.yaml --concurrency 2
 | `TRIPO_REGION` | `ov` or `cn` — normally unnecessary: `tripo login` probes both regions with your key and stores the right one automatically |
 | `TRIPO_API_BASE_URL` / `TRIPO_PLATFORM_BASE_URL` | endpoint overrides |
 | `TRIPO_HOME` | config/history directory (default `~/.tripo`) |
+| `TRIPO_NO_UPDATE_CHECK` | disable the startup "new version available" hint (also off when `CI` is set, headless, or `--json`) |
+| `TRIPO_NPM_REGISTRY` | npm registry used by `tripo update` and the version check (default `https://registry.npmjs.org`; e.g. a mirror) |
 | `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | standard proxy variables, honored for all CLI traffic (plain Node fetch ignores them) |
 | `TRIPO_LLM_BASE_URL` / `TRIPO_LLM_API_KEY` / `TRIPO_LLM_MODEL` | optional OpenAI-compatible LLM for `tripo ai` conversation mode |
 

package/dist/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

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

package/dist/commands/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
@@ -20,15 +26,38 @@ export function registerMakeCommand(program) {
         .option('--then <steps>', 'processing chain, e.g. "texture,rig,convert:fbx"')
         .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/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/commands/update.js

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

package/dist/core/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 };
         }

package/dist/knowledge/chains.js

@@ -21,23 +21,23 @@ export const MODEL_PRODUCING_TYPES = new Set([
     '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: 'refine', endpoint: '/v3/models/refine', produces: 'refine_model', accepts: ['text_to_model'], acceptsFile: false, describe: { zh: '精修文生模型的几何细节', en: 'refine geometry of a text-to-model result' } },
+    { name: 'texture', endpoint: '/v3/models/texture', produces: 'texture_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '重新生成贴图 / PBR 材质', en: 'regenerate textures / PBR materials' } },
+    { name: 'stylize', endpoint: '/v3/models/stylize', produces: 'stylize_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '按风格重塑模型(lego/voxel/...)', en: 'restyle the model (lego/voxel/...)' } },
+    { name: 'convert', endpoint: '/v3/models/convert', produces: 'convert_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '转换输出格式 / 贴图尺寸 / 朝向', en: 'convert format / texture size / orientation' } },
+    { name: 'import', endpoint: '/v3/models/import', produces: 'import_model', accepts: [], acceptsFile: true, describe: { zh: '导入本地模型文件作为加工起点', en: 'import a local model file as the chain source' } },
+    { name: 'rig-check', endpoint: '/v3/animations/rig-check', produces: 'animate_prerigcheck', accepts: 'any-model', acceptsFile: true, passthrough: true, aliases: ['check', 'rigcheck'], describe: { zh: '检查是否可绑骨(不产出模型,不可绑则止损)', en: 'check riggability (no model output; stops the chain if not riggable)' } },
+    { name: 'rig', endpoint: '/v3/animations/rig', produces: 'animate_rig', accepts: 'any-model', acceptsFile: true, describe: { zh: '自动绑定骨骼', en: 'auto-rig a skeleton' } },
+    { name: 'retarget', endpoint: '/v3/animations/retarget', produces: 'animate_retarget', accepts: ['animate_rig'], acceptsFile: false, aliases: ['animate'], describe: { zh: '把预设动画重定向到绑骨模型', en: 'retarget preset animations onto the rigged model' } },
+    { name: 'segment', endpoint: '/v3/mesh/segment', produces: 'mesh_segmentation', accepts: 'any-model', acceptsFile: true, describe: { zh: '把网格分割成部件', en: 'segment the mesh into parts' } },
+    { name: 'complete', endpoint: '/v3/mesh/complete', produces: 'mesh_completion', accepts: ['mesh_segmentation'], acceptsFile: false, describe: { zh: '补全分割后的部件', en: 'complete the segmented parts' } },
+    { name: 'decimate', endpoint: '/v3/mesh/decimate', produces: 'highpoly_to_lowpoly', accepts: 'any-model', acceptsFile: true, aliases: ['lowpoly'], describe: { zh: '减面到目标面数', en: 'decimate to a target face count' } },
     // mesh/edit: local retry/refine inside a bbox, P2 pipeline (model fixed to P2-20260801).
-    { name: 'edit', endpoint: '/v3/mesh/edit', produces: 'mesh_edit', accepts: 'any-model', acceptsFile: true },
+    { name: 'edit', endpoint: '/v3/mesh/edit', produces: 'mesh_edit', accepts: 'any-model', acceptsFile: true, describe: { zh: '在 bbox 区域内局部重做(P2 管线)', en: 'redo one bbox region locally (P2 pipeline)' } },
     // smartsegment's `input` is file_token/URL only (the server does not resolve
     // task ids here), so it cannot chain after a task. Type is refined to
     // smartsegment_image|smartsegment_model at request-build time per seg_type.
-    { name: 'smartsegment', endpoint: '/v3/mesh/smartsegment', produces: 'smartsegment_model', accepts: [], acceptsFile: true },
+    { name: 'smartsegment', endpoint: '/v3/mesh/smartsegment', produces: 'smartsegment_model', accepts: [], acceptsFile: true, describe: { zh: '智能语义分割', en: 'smart semantic segmentation' } },
 ];
 const stepIndex = new Map();
 for (const s of STEPS) {

package/dist/pipeline/make.js

@@ -53,7 +53,7 @@ export async function planMake(client, options) {
         case 'image':
         case 'url-image': {
             const raw = classified.values[0].value;
-            const { value } = await resolveInputValue(client, raw);
+            const { value } = await resolveInputValue(client, raw, { dryRun: options.dryRun });
             const choice = chooseModel({
                 explicit: options.model ?? scenario?.model,
                 faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
@@ -69,7 +69,7 @@ export async function planMake(client, options) {
             };
         }
         case 'multiview': {
-            const views = await assignViews(client, classified.values.map((v) => v.value));
+            const views = await assignViews(client, classified.values.map((v) => v.value), { dryRun: options.dryRun });
             const choice = chooseModel({
                 explicit: options.model ?? scenario?.model,
                 faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
@@ -86,7 +86,7 @@ export async function planMake(client, options) {
         }
         case 'model': {
             const raw = classified.values[0].value;
-            const { value } = await resolveInputValue(client, raw);
+            const { value } = await resolveInputValue(client, raw, { dryRun: options.dryRun });
             const generation = buildStepRequest('import', value, {});
             if (chain.length === 0) {
                 warnings.push(t({
@@ -116,24 +116,31 @@ export async function planMake(client, options) {
         }
     }
 }
+/**
+ * Chain legality against the plan's upstream task type (throws UsageError).
+ * Skipped when the upstream type is unknown (raw task id without local history).
+ */
+export function checkPlanChain(plan) {
+    if (plan.chain.length === 0)
+        return;
+    const upstream = plan.generation?.taskType ?? plan.sourceType;
+    if (!upstream)
+        return;
+    try {
+        validateChain(plan.chain, upstream);
+    }
+    catch (error) {
+        if (error instanceof ChainError)
+            throw new UsageError(error.message);
+        throw error;
+    }
+}
 /** 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;
-            }
-        }
-    }
+    checkPlanChain(plan);
     await precheckBalance(client);
     let sourceTaskId;
     let sourceType;
@@ -195,7 +202,7 @@ export async function executeMake(client, plan, options) {
  * 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) {
+export async function assignViews(client, files, opts = {}) {
     if (files.length < 2 || files.length > 4) {
         throw new UsageError(`multiview needs 2–4 images (got ${files.length})`);
     }
@@ -227,7 +234,7 @@ export async function assignViews(client, files) {
     }
     const resolved = {};
     for (const [view, file] of Object.entries(views)) {
-        resolved[view] = (await resolveInputValue(client, file)).value;
+        resolved[view] = (await resolveInputValue(client, file, { dryRun: opts.dryRun })).value;
     }
     return resolved;
 }

package/dist/program.js

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

package/package.json

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

package/skill/SKILL.md

@@ -30,13 +30,14 @@ Regions (ov = international, cn = China mainland) share one CLI: `tripo login --
 
 ## Behavior rules (read first)
 
-1. **`tripo make` is synchronous and blocking.** It submits the task, polls, downloads artifacts, then exits. Wait for the process to finish and read the final JSON from stdout. Do NOT re-implement polling, do NOT add your own timeout shorter than 15 minutes, do NOT stop just because you saw a task_id in the logs.
+1. **`tripo make` is synchronous and blocking.** It prints a plan card on stderr (one numbered line per API call: endpoint, purpose, args), then submits, polls, downloads artifacts, and exits. In a TTY it asks "Run this plan?" first; `--yes` (auto-enabled when headless) skips the prompt but still prints the card. Wait for the process to finish and read the final JSON from stdout. Do NOT re-implement polling, do NOT add your own timeout shorter than 15 minutes, do NOT stop just because you saw a task_id in the logs.
 2. **stdout is the contract; stderr is commentary.** With `--json` (auto-enabled when piped), stdout carries exactly one final JSON line. Progress/logs go to stderr.
 3. **Artifacts are local files.** The result JSON has `output_dir`, `model_file`, `preview`. Look at `preview.png` to judge quality; re-roll with `tripo redo` if needed.
 4. **Exit codes are stable** — branch on them:
    - 0 success · 2 usage/params · 3 auth · 4 insufficient credits (tell the human to run `tripo topup`) · 5 content policy · 6 task failed (credits auto-refunded) · 7 network · 8 not found · 9 rate limit (retry with backoff)
 5. **Never invent parameters.** Unknown `--param key=value` pairs pass through to the API; stick to documented ones. The full parameter/model/preset reference from the official API docs is bundled: `tripo docs --topic commands/generate` (3D + image generation) and `tripo docs --topic commands/process` (texture/convert/rig/retarget/mesh) — read those instead of browsing the website.
-6. **Don't pick legacy model versions.** The CLI auto-selects `tripo-v3.1` (high fidelity) or `tripo-p1` (low-poly, face budget ≤ 20000). Only override `--model` when the human asks (e.g. `--model tripo-p2` for the P-series preview with quad support, or `tripo-v3.0` / `tripo-v2.5` for reproducing old projects).
+6. **Validate before spending: `--dry-run --json`.** Same command plus `--dry-run` prints the plan as JSON with zero network calls and no credits: the chosen `model`, the completed `steps[].payload` for every API call, `warnings` (auto-adjustments) and `errors` (blocking; exit 2). When `valid` is true, re-run without `--dry-run`. Details: `tripo docs --topic commands/make` § "Dry run".
+7. **Don't pick legacy model versions.** The CLI auto-selects `tripo-v3.1` (high fidelity) or `tripo-p1` (low-poly, face budget ≤ 20000). Only override `--model` when the human asks (e.g. `--model tripo-p2` for the P-series **Preview** with quad support, or `tripo-v3.0` / `tripo-v2.5` for reproducing old projects). `tripo-*` names are CLI aliases — the CLI sends the dated wire value (`tripo-p2` → `P2-20260801`); the API rejects the alias itself with 1004. Alias ↔ wire ↔ status table: `tripo docs --topic commands/generate` ("Models & Versions").
 
 ## The one command you usually need
 
@@ -51,7 +52,7 @@ tripo make @last --then convert:fbx --json --yes          # continue from last t
 - `--for` scenario presets: `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`
 - `--then` chain steps: `refine texture stylize convert import rig-check rig retarget segment complete decimate smartsegment`
   - step args: `convert:format=FBX,texture_size=2048` (bare value = primary arg: `convert:fbx`, `stylize:lego`, `decimate:5000`)
-- Output JSON: `{"task_id","type","status","credits_consumed","output_dir","files",["model_file"],["preview"],["chain"]}`
+- Output JSON: `{"task_id","type","status","credits_consumed","output_dir","files",["model_file"],["preview"],["chain"],["credits_breakdown"]}` — with `--then`, `credits_consumed` is the **total** for the run and `credits_breakdown` itemizes every task (`[{task_id,type,credits_consumed}]`, generation first)
 
 ## Pipes (composing steps yourself)
 
@@ -77,6 +78,7 @@ tripo make cat.png --json | tripo anim rig --json | tripo anim retarget --param
 ## Detailed docs in this package
 
 - `commands/` — one file per command with every flag and parameter
+  - model versions · H series (`tripo-v3.x`) · P series (`tripo-p1`, `tripo-p2` Preview) · alias → wire value · GA / Preview / Legacy status · quad → `commands/generate` § "Models & Versions" (also the P Series endpoint entry points)
 - `examples/` — copy-paste recipes per scenario (game/print/animation/...)
 - `common-errors.md` — error table with fixes
 

package/skill/commands/generate.md

@@ -6,21 +6,46 @@ Everything below is the full parameter reference from the official API docs —
 ## 3D
 
 ```bash
-tripo generate text-to-model "a ceramic teapot" [--model tripo-v3.1|tripo-p1] [-p face_limit=15000] ...
+tripo generate text-to-model "a ceramic teapot" [--model tripo-v3.1|tripo-p1|tripo-p2] [-p face_limit=15000] ...
 tripo generate image-to-model photo.png [-p texture_alignment=original_image] [-p orientation=align_image]
 tripo generate multiview-to-model front.png back.png [left.png right.png]
 ```
 
-### 3D models (`--model`)
+### P Series (`tripo-p1` / `tripo-p2`) — same endpoints, different model
 
-| alias | wire value sent | positioning | notes |
-| --- | --- | --- | --- |
-| `tripo-v3.1` (default) | `v3.1-20260211` | latest high-precision; AAA / 3D printing | full feature set |
-| `tripo-p1` | `P1-20260311` | best low-poly; games / UGC / mobile | face_limit 48–20000 (CLI enforces ≥50); **no** `quad` `smart_low_poly` `generate_parts` `geometry_quality`; ~2s mesh; extra `export_uv` |
-| `tripo-p2` | `P2-20260801` | P1 upgrade (P series, Preview) | adds `quad` (forces FBX); face_limit 48–50000 tri / 48–25000 quad (validated locally); still **no** `smart_low_poly` `generate_parts` `geometry_quality` (stripped with a warning); credits 100 (no texture) / 110 / 120 / 130 for standard / detailed / extreme. Explicit `--model` only — the CLI never auto-selects it |
-| `tripo-v3.0` / `tripo-v2.5` | `v3.0-20250812` / `v2.5-20250123` | legacy | only when the human asks |
+The P series (low-poly, clean topology) uses the **same three endpoints**; only the `model` value changes. The official docs document it as a separate "P Series" tab on each generation page — this is the direct entry point:
+
+```bash
+tripo generate text-to-model "a low poly knight" --model tripo-p1 -p face_limit=8000          # → model: P1-20260311
+tripo generate image-to-model photo.png --model tripo-p2 -p quad=true -p face_limit=12000      # → model: P2-20260801 (Preview)
+tripo generate multiview-to-model front.png back.png --model tripo-p1
+```
+
+| endpoint | H series (standard) page | P series page |
+| --- | --- | --- |
+| `POST /v3/generation/text-to-model` | `…/docs/generation-text-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-text-to-model/p> |
+| `POST /v3/generation/image-to-model` | `…/docs/generation-image-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-image-to-model/p> |
+| `POST /v3/generation/multiview-to-model` | `…/docs/generation-multiview-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-multiview-to-model/p> |
+
+(cn: replace `developers.tripo3d.ai/en` with `developers.tripo3d.com/zh`.) P-series constraints — face_limit ranges, unsupported params, P2's `quad` — are in the table below; the CLI enforces them locally.
 
-`tripo-turbo` / `tripo-v2.0` appear in some docs but are **not** on the v3 server whitelist (400).
+### 3D models (`--model`) — Models & Versions
+
+Keywords: model versions · H series (v3.x) · P series (P1 / P2) · Preview · quad · alias → wire value.
+
+| alias (what you type) | wire value (what the API receives) | status | positioning | notes |
+| --- | --- | --- | --- | --- |
+| `tripo-v3.1` (default) | `v3.1-20260211` | GA | latest high-precision; AAA / 3D printing | full feature set |
+| `tripo-p1` | `P1-20260311` | GA | best low-poly; games / UGC / mobile | face_limit 48–20000 (CLI enforces ≥50); **no** `quad` `smart_low_poly` `generate_parts` `geometry_quality`; ~2s mesh; extra `export_uv` |
+| `tripo-p2` | `P2-20260801` | **Preview** (2026-08) | P1 upgrade (P series) | adds `quad` (forces FBX); face_limit 48–50000 tri / 48–25000 quad (validated locally); still **no** `smart_low_poly` `generate_parts` `geometry_quality` (stripped with a warning); credits 100 (no texture) / 110 / 120 / 130 for standard / detailed / extreme. Explicit `--model` only — the CLI never auto-selects it |
+| `tripo-v3.0` / `tripo-v2.5` | `v3.0-20250812` / `v2.5-20250123` | Legacy | previous generations | only when the human asks |
+
+**Alias vs wire value.** `tripo-*`, `p1`, `p2`, `v3.1` … are CLI-side aliases; the CLI always sends the dated wire value in the `model` field (`--model tripo-p2` → `"model": "P2-20260801"`). The v3 server whitelist accepts wire values only — sending an alias straight to the API returns 1004 `invalid model` with the allowed list. `task.json` records the wire value that was actually used. `tripo-turbo` / `tripo-v2.0` appear in some docs but are **not** on the v3 whitelist (400).
+
+Official docs (ov / cn):
+- Models & Versions: <https://developers.tripo3d.ai/en/docs/models-and-versions> · <https://developers.tripo3d.com/zh/docs/models-and-versions>
+- P Series model detail: <https://developers.tripo3d.ai/en/models/p1> · <https://developers.tripo3d.com/zh/models/p1>
+- P Series endpoints: `…/docs/generation-text-to-model/p`, `…/docs/generation-image-to-model/p`, `…/docs/generation-multiview-to-model/p` (the `/standard` tab on each page is the H-series version)
 
 ### Parameters (text / image / multiview-to-model)
 
@@ -77,12 +102,15 @@ tripo generate image-to-splat photo.png         # gaussian splat
 
 ### Image models (`--model`)
 
-| model | provider | notes |
-| --- | --- | --- |
-| `seedream_v4` | ByteDance | text-to-image default (balanced); **not accepted by image-to-image** |
-| `seedream_v5` | ByteDance | image-to-image default; higher quality |
-| `gemini-2.5-flash` / `gemini-3-pro` / `gemini-3.1-flash` | Google | fast / high quality / latest fast. Backend aliases `banana` / `banana_pro` / `banana2` are also accepted |
-| `chat_image_1` / `chat_image_1.5` / `chat_image_2` | OpenAI | GPT image; 1.5 = higher quality, 2 = latest |
+| model | provider | status | notes |
+| --- | --- | --- | --- |
+| `seedream_v4` | ByteDance | GA | text-to-image default (balanced); **not accepted by image-to-image** |
+| `seedream_v5` | ByteDance | GA | image-to-image default; higher quality |
+| `gemini-2.5-flash` / `gemini-3-pro` / `gemini-3.1-flash` | Google | GA | fast / high quality / latest fast. Backend aliases `banana` / `banana_pro` / `banana2` are also accepted |
+| `chat_image_1` / `chat_image_1.5` | OpenAI | retiring 2026-10-23 / 2026-12-01 | GPT image; 1.5 = higher quality — move to `chat_image_2` |
+| `chat_image_2` | OpenAI | GA | GPT latest |
+
+Image model ids are sent as-is (no alias normalization). Full list with retirement dates: <https://developers.tripo3d.ai/en/docs/models-and-versions>.
 
 ### Image parameters
 

package/skill/commands/make.md

@@ -6,6 +6,27 @@ The magic command: input in, finished local 3D artifacts out. Blocking; exits wh
 tripo make <input...> [options]
 ```
 
+## Before anything is spent: the plan card
+
+`make` first prints a plan card on stderr — input, scenario, model, then **one numbered line per API call** (endpoint, what it does, its args), deliverables and cost notes:
+
+```
+── Plan ──────────────────────────
+input: a medieval knight
+scenario: game-mobile (Mobile game / low-poly)
+model: P1-20260311 — scenario game-mobile
+steps:
+  1. text-to-model  POST /v3/generation/text-to-model — generate a 3D model from text
+     model="P1-20260311" texture=true pbr=true texture_quality="standard" face_limit=15000
+  2. texture  POST /v3/models/texture — regenerate textures / PBR materials
+  3. convert  POST /v3/models/convert — convert format / texture size / orientation
+     format="FBX" texture_size=2048
+deliverables: FBX, GLB
+──────────────────────────────────
+```
+
+In a TTY it then asks `Run this plan?`; answering no exits 0 with `cancelled; no credits spent`. `--yes` (auto-enabled when stdin/stdout are not TTYs, i.e. for agents and pipes) skips the question but still prints the card, so the log shows exactly what ran. `--quiet` hides it.
+
 ## Inputs (auto-detected)
 
 | you pass | it runs |
@@ -20,7 +41,7 @@ tripo make <input...> [options]
 
 - `--for <scenario>` — `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`. Sets model+params+chain+format from the domain knowledge base.
 - `--then <steps>` — processing chain, comma-separated. Steps: `refine texture stylize convert import rig-check rig retarget segment complete decimate smartsegment`. Args: `step:key=value,...`; bare value maps to the step's primary arg (`convert:fbx` → format, `stylize:lego` → style, `decimate:5000` → face_limit, `retarget:preset:walk` → animation). Overrides the scenario chain.
-- `--model <m>` — force `tripo-v3.1` (high fidelity, default), `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped) or `tripo-p2` (P-series preview; adds quad, face_limit 48–50000 tri / 48–25000 quad; never auto-selected). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311` / `P2-20260801`) the server actually accepts.
+- `--model <m>` — force `tripo-v3.1` (high fidelity, default), `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped) or `tripo-p2` (P-series preview; adds quad, face_limit 48–50000 tri / 48–25000 quad; never auto-selected). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311` / `P2-20260801`) the server actually accepts. Full table with status (GA / Preview / Legacy) and official links: `tripo docs --topic commands/generate` → "Models & Versions".
 - `-n, --candidates <n>` — up to 4 parallel candidates with different seeds (interactive pick when chaining).
 - `--seed <n>` — fixed model_seed for reproducible geometry.
 - `-p, --param key=value` — extra API parameter, repeatable. Common: `texture=false pbr=false` (bare geometry, cheaper), `texture_quality=detailed`, `face_limit=15000`, `quad=true` (forces FBX), `auto_size=true`, `negative_prompt=...`.
@@ -30,18 +51,62 @@ tripo make <input...> [options]
 - `--name <name>` — history name for `@name` references.
 - `--notify` — desktop notification when done.
 - `--timeout <seconds>` — watch timeout (default 1800).
+- `--yes` (global) — skip the plan-card confirmation; implied when headless.
+- `--dry-run` — plan + validate only; nothing is uploaded or submitted, no credits spent. See below.
+
+## Dry run (agents: validate before spending)
+
+`tripo make ... --dry-run --json` runs the whole planning stage with **zero network calls** and prints the plan as the result on stdout: the model the dual-model rule picked, the completed request body for every call (scenario defaults merged, aliases normalized to wire values, illegal params stripped, step defaults filled in), and the outcome of every local validation. Works without an API key.
+
+```bash
+tripo make concept.png --for game-mobile --then rig,convert:fbx --dry-run --json
+```
+
+```json
+{"dry_run":true,"valid":true,
+ "input":"concept.png","scenario":"game-mobile",
+ "model":"P1-20260311","model_reason":"explicit --model",
+ "steps":[
+   {"name":"image-to-model","endpoint":"/v3/generation/image-to-model","task_type":"image_to_model",
+    "payload":{"input":"<upload:concept.png>","model":"P1-20260311","texture":true,"pbr":true,"texture_quality":"standard","face_limit":15000}},
+   {"name":"rig","endpoint":"/v3/animations/rig","task_type":"animate_rig","payload":{"input":"<upstream>","model":"v2.5-20260210"}},
+   {"name":"convert","endpoint":"/v3/models/convert","task_type":"convert_model","payload":{"input":"<upstream>","format":"FBX"}}],
+ "pending_uploads":["concept.png"],
+ "deliverables":["FBX","GLB"],
+ "candidates":1,
+ "warnings":["--then overrides the default game-mobile processing chain"],
+ "errors":[],
+ "cost_notes":[]}
+```
+
+- `valid` / `errors` — `errors` are blocking (illegal chain order, out-of-range `face_limit`, quad + GLTF, missing `animation` for retarget, ...). The real run would exit 2 on them before spending anything; the dry run exits 2 too, so branch on the exit code or on `valid`.
+- `warnings` — adjustments the CLI applies automatically (e.g. `P1 does not support quad (removed)`); safe to proceed, but check they match your intent.
+- `steps[].payload` — the exact body that would be POSTed. Local files show as `<upload:path>` (also listed in `pending_uploads`); chain steps use `<upstream>` for the task id that does not exist yet.
+- A bare task id with no local history entry cannot have its type checked offline: chain legality is reported as unverified in `warnings` and checked by the real run.
+- Without `--json` the same plan card as the real run is printed on stdout, followed by the warnings/errors and a verdict line.
+
+Typical agent loop: dry-run → fix `errors` / adjust params → dry-run again until `valid` → drop `--dry-run` and run for real.
 
 ## Output (stdout, --json)
 
 ```json
-{"task_id":"...","type":"convert_model","status":"success","credits_consumed":25,
+{"task_id":"...","type":"convert_model","status":"success",
+ "credits_consumed":145,
+ "credits_breakdown":[
+   {"task_id":"<generation>","type":"text_to_model","credits_consumed":110},
+   {"task_id":"<texture>","type":"texture_model","credits_consumed":30},
+   {"task_id":"<convert>","type":"convert_model","credits_consumed":5}],
  "output_dir":"tripo-out/knight-1a2b3c4d","files":["model.fbx","preview.png","task.json"],
  "model_file":".../model.fbx","preview":".../preview.png",
- "chain":[{"task_id":"...","type":"texture_model"}]}
+ "source_task_id":"<generation>",
+ "chain":[{"task_id":"<texture>","type":"texture_model","credits_consumed":30},{"task_id":"<convert>","type":"convert_model","credits_consumed":5}]}
 ```
 
+- Single task (no `--then`): `credits_consumed` is that task's spend; no `credits_breakdown`.
+- Chained run: `credits_consumed` is the **total** across generation + every step, and `credits_breakdown` lists each task in run order (generation first). Human mode prints the same as `credits consumed (total): 145` followed by one indented line per task.
+
 Exit codes: 0 ok · 2 params · 3 auth · 4 credits · 5 content policy · 6 task failed · 7 network · 9 rate limit.
 
 ## Cost behavior
 
-Balance is pre-checked before submitting; failed tasks auto-refund frozen credits. `texture=false pbr=false` skips texture credits entirely (right for 3D printing).
+The plan card shows every call before anything is submitted; balance is pre-checked before submitting; failed tasks auto-refund frozen credits. After the run, `credits_consumed` / `credits_breakdown` report what was actually billed per task. `texture=false pbr=false` skips texture credits entirely (right for 3D printing).

package/skill/common-errors.md

@@ -4,7 +4,7 @@
 | --- | --- | --- | --- |
 | 3 | 1002 | authentication failed (invalid/missing API key) | set `TRIPO_API_KEY` or run `tripo login`; check the key wasn't revoked |
 | 3 | 1005 | forbidden (no permission for this resource) | check account permissions |
-| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params. Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `quad=true` on P1, non-GLB input to smartsegment `model` / rig-check |
+| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params. Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `quad=true` on P1, non-GLB input to smartsegment `model` / rig-check. `invalid model`: the API only accepts dated wire values (`P2-20260801`, `v3.1-20260211`…) — pass the CLI alias (`--model tripo-p2`) and let the CLI normalize, or the wire value itself; never `tripo-*` straight to the API. Table: `commands/generate` § "Models & Versions" |
 | 9 | 1007 | per-API-key rate limit | wait and retry with backoff; honour `Retry-After` / `X-RateLimit-Reset` headers |
 | 9 | 2000 | per-account concurrency pool full (see table below) | wait for a task in that category to finish, or lower `--concurrency` in batch; other categories are unaffected |
 | 8 | 2001 | task not found | task ids are account-scoped — same key that created it? right region (ov/cn)? |
@@ -45,6 +45,8 @@ Pools are independent: a full H-series pool does not block P-series or image tas
 - multiview without a front view → rejected (name a file "front" or pass it first)
 - `-n` with `--then` needs an interactive terminal (pick the winner first, then chain)
 
+All of these surface in `tripo make ... --dry-run --json` as `errors` (blocking) or `warnings` (auto-adjusted) before anything is uploaded or submitted.
+
 ## Weird-but-normal
 
 - `model_url` in task output points to a file that may be named `pbr_model` etc. — normal, just download it (the CLI does).