tripo-cli 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# tripo-cli
+
+Turn a sentence or an image into an engine-ready 3D asset from your terminal, powered by the [Tripo](https://www.tripo3d.ai) V3 API.
+
+```bash
+npx tripo-cli make "a cute low poly fox"
+# → generates, polls, downloads: ./tripo-out/a-cute-low-poly-fox-xxxxxxxx/{model.glb, preview.png, task.json}
+```
+
+The binary is `tripo` once installed:
+
+```bash
+npm install -g tripo-cli
+tripo login          # browser approves, key arrives automatically; or --paste / TRIPO_API_KEY
+tripo make knight.png --for game-mobile --then texture,rig,convert:fbx
+```
+
+Works with both Tripo regions from the same install — international (`openapi.tripo3d.ai`, console `developers.tripo3d.ai`, email login + Stripe) and China mainland (`openapi.tripo3d.com`, console `developers.tripo3d.com`, SMS login + Alipay). `tripo login` runs an RFC 8628 device flow: the terminal shows a short code, the browser signs in (each console's own method) and approves, and the key lands in the CLI automatically — with graceful fallback to open-the-keys-page-and-paste when the device-auth backend is unavailable. You never pick a region when a key is in hand: the key is probed against both regions and whichever accepts it wins; `tripo topup` then opens the matching billing page (`/billing` on ov, `/billing/recharge` on cn). If a config was moved between machines, `tripo doctor` detects the mismatch and prints the one-line fix.
+
+## 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.
+- **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
+
+| command | what it does |
+| --- | --- |
+| `tripo make <input...>` | the magic command: generate → chain → download |
+| `tripo ai [description]` | plan with a wizard (no LLM needed) or multi-expert conversation (BYO LLM), confirm a plan card, execute |
+| `tripo view [task\|file]` | interactive 3D preview in your browser (local server, model-viewer) |
+| `tripo redo [task]` | re-run with a fresh seed |
+| `tripo login / logout / whoami` | device flow: browser approves, key arrives automatically (paste fallback); stored 0600 in `~/.tripo/config.json` |
+| `tripo topup / balance / usage` | open the billing page + detect the credits arriving; check spend |
+| `tripo generate <endpoint>` | deterministic access to all 8 generation endpoints |
+| `tripo model / anim / mesh <step>` | refine, texture, stylize, convert, import, rig-check, rig, retarget, segment, complete, decimate, smartsegment |
+| `tripo task get/list/watch` | query and stream task progress (NDJSON in `--json` mode) |
+| `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 mcp` | run as an MCP server (Cursor / Claude Desktop) |
+| `tripo completion <shell>` | bash/zsh/fish completion |
+
+Every task-producing command supports `-o/--out`, `--no-wait`, `--no-download`, `--name`, `--timeout`, `--notify`, and repeatable `--param key=value` passthrough. Global flags: `--json`, `--yes`, `--quiet`, `--no-open`.
+
+## Scenario presets
+
+```bash
+tripo make "sci-fi crate" --for game-mobile   # P1 low-poly → texture → FBX
+tripo make hero.png --for film                # v3.1, quad topology, 4K PBR → USDZ/OBJ
+tripo make "chess knight" --for print         # no textures, watertight → STL, flat bottom
+tripo make sofa.jpg --for ar-web              # decimate to mobile budget → GLB + USDZ
+tripo make "orc warrior" --for anim           # rig-check gate → rig → FBX
+```
+
+## Pipelines
+
+```bash
+# human shorthand
+tripo make cat.png --then texture,rig,convert:fbx
+
+# shell pipes (each stage reads the upstream task from stdin)
+tripo make cat.png --json | tripo model texture --json | tripo anim rig --json
+
+# batch with resume
+tripo batch run assets.yaml --concurrency 2
+```
+
+`@last`, `@2`, and `@name` reference your task history everywhere a task id is accepted (history lives in `~/.tripo/history.jsonl`; every artifact directory gets a reproducible `task.json`).
+
+## For AI coding agents
+
+- `make`/`watch` are blocking: run them, wait for exit, read the single JSON line on stdout. Do not poll yourself.
+- 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`.
+
+## Environment variables
+
+| var | meaning |
+| --- | --- |
+| `TRIPO_API_KEY` | API key (`tsk_...`), highest precedence |
+| `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_LLM_BASE_URL` / `TRIPO_LLM_API_KEY` / `TRIPO_LLM_MODEL` | optional OpenAI-compatible LLM for `tripo ai` conversation mode |
+
+## Development
+
+```bash
+npm install
+npm run dev -- make "a cat" --no-wait   # run from source (tsx)
+npm test                                # vitest (mock API, no credits spent)
+npm run typecheck && npm run lint
+npm run build && npm run pack:check     # dist + tarball self-check
+TRIPO_API_KEY=tsk_... npm run e2e       # real-API smoke (spends ~10 credits)
+```
+
+Node.js ≥ 20. Issues & source: [vast-enterprise/Tripo-API-CLI](https://github.com/vast-enterprise/Tripo-API-CLI).
+
+## License
+
+MIT

package/dist/ai/experts.js

@@ -0,0 +1,115 @@
+/**
+ * Multi-expert agent orchestration (conversation mode).
+ *
+ * Producer (router) → domain specialist(s) → plan card. The LLM only parses
+ * intent and phrases advice; every decision it may make is constrained to the
+ * knowledge base (scenario ids, step names, parameter windows), and the
+ * 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 { 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 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.
+
+Scenarios:
+${SCENARIO_TABLE}
+
+Rules:
+- "prompt" must describe the object to generate (translate to English, keep it concrete, <= 200 chars).
+- Set "face_limit" only when the user states a face/polygon budget.
+- Set "needs_animation" true only when the user wants skeleton/animations.
+- If one critical piece of information is missing and materially changes the plan, set "question" (one short question in the user's language). Otherwise omit it.
+Respond with JSON only: {"scenario","prompt","face_limit","needs_animation","question","notes"}`;
+const SPECIALIST_PROMPTS = {
+    'game-mobile': `You are a senior game technical artist (mobile). Budgets: 500–20000 faces, 1–2K textures, clean topology, FBX/GLB delivery. P1 model is used (no quad/parts/geometry_quality).`,
+    'game-pc': `You are a senior game technical artist (PC/console). PBR detailed textures, optional decimate for LODs (bake=true), FBX delivery with engine presets.`,
+    film: `You are a film/offline-rendering artist. quad=true subdivision-friendly topology (FBX output), geometry_quality=detailed, texture_quality=detailed, 4K textures, USD/OBJ handoff via convert.`,
+    print: `You are a 3D-printing engineer. Geometry only (texture=false,pbr=false), watertight meshes, flatten_bottom for FDM, STL or colored 3MF via convert, real-world sizing via scale_factor/auto_size.`,
+    'ar-web': `You are a realtime AR/Web 3D engineer. Keep faces <= 20000 via decimate, 2K textures, deliver GLB + USDZ (iOS QuickLook).`,
+    anim: `You are a character animation TD. Chain: rig-check → rig (v2.5 rig, spec tripo|mixamo) → retarget (<=5 preset animations, billed per animation). Mixamo/Unity Humanoid → spec=mixamo.`,
+    toy: `You are a stylized collectible designer. P1 low-poly or stylize steps (lego/voxel/voronoi/minecraft). STL via convert for physical prints.`,
+};
+function specialistSystem(scenarioId) {
+    const persona = SPECIALIST_PROMPTS[scenarioId] ?? SPECIALIST_PROMPTS['game-mobile'];
+    return `${persona}
+You fine-tune a Tripo generation plan. You may adjust generation params and the processing chain.
+Valid chain steps: ${STEP_TABLE}. Chain syntax: "step:key=value,step2" (e.g. "texture,rig,convert:format=FBX").
+Constraints: pbr=>texture; generate_parts excludes texture/pbr/quad; P1 face_limit 50-20000 and forbids quad/smart_low_poly/generate_parts/geometry_quality; retarget <= 5 animations.
+Respond with JSON only: {"params":{...},"chain":"...","notes":["short practical notes in ${getLocale() === 'zh' ? 'Chinese' : 'English'}"]}. Omit fields you don't want to change.`;
+}
+/**
+ * Run the expert pipeline. `askUser` is called when the producer needs one
+ * clarification (interactive mode only); return undefined to skip.
+ */
+export async function buildExpertPlan(request, askUser) {
+    const messages = [
+        { role: 'system', content: PRODUCER_SYSTEM },
+        { role: 'user', content: request },
+    ];
+    let producer = await chatJson(messages);
+    if (producer.question && askUser) {
+        const answer = await askUser(producer.question);
+        if (answer) {
+            messages.push({ role: 'assistant', content: JSON.stringify(producer) });
+            messages.push({ role: 'user', content: `Additional info: ${answer}. Re-classify with the complete picture; do not ask again.` });
+            producer = await chatJson(messages);
+        }
+    }
+    const scenario = getScenario(producer.scenario) ?? getScenario('game-mobile');
+    const specialist = await chatJson([
+        { role: 'system', content: specialistSystem(scenario.id) },
+        {
+            role: 'user',
+            content: `User request: ${request}\nPrompt: ${producer.prompt}\nBase plan: model=${scenario.model} params=${JSON.stringify(scenario.genParams)} chain=${scenario.chain.map((c) => c.step).join('→') || 'none'}\nneeds_animation=${producer.needs_animation ?? false} face_limit=${producer.face_limit ?? 'default'}`,
+        },
+    ]).catch(() => ({}));
+    // Merge + re-validate everything the LLM produced.
+    const params = { ...scenario.genParams, ...(specialist.params ?? {}) };
+    if (producer.face_limit)
+        params.face_limit = producer.face_limit;
+    let chain = scenario.chain;
+    if (specialist.chain) {
+        try {
+            chain = parseThenExpression(specialist.chain);
+        }
+        catch {
+            chain = scenario.chain; // discard invalid expert chain, keep the preset
+        }
+    }
+    if (producer.needs_animation && !chain.some((s) => s.step === 'rig')) {
+        chain = [
+            ...chain.filter((s) => s.step !== 'convert'),
+            { step: 'rig-check', args: {} },
+            { step: 'rig', args: { model: RIG_MODEL_V25 } },
+            { step: 'retarget', args: { animations: ['preset:idle', 'preset:walk'] } },
+        ];
+    }
+    const choice = chooseModel({
+        explicit: scenario.model,
+        faceLimit: typeof params.face_limit === 'number' ? params.face_limit : undefined,
+        lowPoly: detectLowPolyIntent(request),
+    });
+    try {
+        validateChain(chain, 'text_to_model');
+    }
+    catch {
+        chain = scenario.chain;
+    }
+    const card = {
+        inputSummary: producer.prompt,
+        scenario: scenario.id,
+        model: choice.model,
+        modelReason: t({ zh: '制片人路由 + 场景预设', en: 'producer routing + scenario preset' }),
+        genParams: params,
+        chain,
+        deliverables: scenario.deliverables,
+        notes: tList(scenario.notes),
+        expertNotes: [...(producer.notes ?? []), ...(specialist.notes ?? [])],
+    };
+    return { card, scenarioId: scenario.id, prompt: producer.prompt, chain, params };
+}

package/dist/ai/llm.js

@@ -0,0 +1,88 @@
+/**
+ * BYO-LLM client: any OpenAI-compatible /chat/completions endpoint.
+ * Configure via `tripo config set llm.base_url/llm.api_key/llm.model`
+ * or env TRIPO_LLM_BASE_URL / TRIPO_LLM_API_KEY / TRIPO_LLM_MODEL.
+ */
+import { loadConfig } from '../config/config.js';
+import { CliError } from '../core/errors.js';
+import { EXIT } from '../knowledge/error-catalog.js';
+export function resolveLlmConfig() {
+    const env = {
+        base_url: process.env.TRIPO_LLM_BASE_URL,
+        api_key: process.env.TRIPO_LLM_API_KEY,
+        model: process.env.TRIPO_LLM_MODEL,
+    };
+    if (env.base_url && env.model)
+        return { base_url: env.base_url, api_key: env.api_key, model: env.model };
+    const config = loadConfig().llm;
+    if (config?.base_url && config.model)
+        return config;
+    return undefined;
+}
+export async function chatCompletion(messages, options = {}) {
+    const config = resolveLlmConfig();
+    if (!config)
+        throw new CliError('no LLM configured', EXIT.USAGE);
+    const url = `${config.base_url.replace(/\/$/, '')}/chat/completions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 60_000);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(config.api_key ? { Authorization: `Bearer ${config.api_key}` } : {}),
+            },
+            body: JSON.stringify({
+                model: config.model,
+                messages,
+                temperature: 0.2,
+                ...(options.json ? { response_format: { type: 'json_object' } } : {}),
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new CliError(`LLM request failed: ${err instanceof Error ? err.message : String(err)}`, EXIT.NETWORK);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new CliError(`LLM endpoint returned HTTP ${response.status}: ${body.slice(0, 300)}`, EXIT.NETWORK);
+    }
+    const data = (await response.json());
+    const content = data.choices?.[0]?.message?.content;
+    if (!content)
+        throw new CliError('LLM returned an empty response', EXIT.NETWORK);
+    return content;
+}
+/** Chat expecting a JSON object back; tolerates markdown fences. */
+export async function chatJson(messages) {
+    const raw = await chatCompletion(messages, { json: true }).catch(async (err) => {
+        // Some endpoints reject response_format; retry without it.
+        if (err instanceof CliError && err.exitCode === EXIT.NETWORK) {
+            return chatCompletion(messages, { json: false });
+        }
+        throw err;
+    });
+    return extractJson(raw);
+}
+export function extractJson(raw) {
+    const trimmed = raw.trim();
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+    const candidate = fenced ? fenced[1] : trimmed;
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start) {
+        throw new CliError(`LLM did not return JSON: ${raw.slice(0, 200)}`, EXIT.NETWORK);
+    }
+    try {
+        return JSON.parse(candidate.slice(start, end + 1));
+    }
+    catch {
+        throw new CliError(`LLM returned invalid JSON: ${candidate.slice(0, 200)}`, EXIT.NETWORK);
+    }
+}

package/dist/ai/plan-card.js

@@ -0,0 +1,79 @@
+/**
+ * The plan card: one shared "here is what I will do and what it costs"
+ * confirmation format used by both the wizard (zero-LLM) and the expert
+ * conversation mode. Decisions come from the knowledge base either way.
+ */
+import pc from 'picocolors';
+import { t } from '../i18n.js';
+import { getScenario } from '../knowledge/scenarios.js';
+/** Cost-impact annotations derived from the parameter set. */
+export function costNotes(card) {
+    const notes = [];
+    const params = card.genParams;
+    if (params.texture === false) {
+        notes.push(t({ zh: '白模生成:不消耗贴图积分', en: 'bare geometry: no texture credits' }));
+    }
+    if (params.texture_quality === 'detailed' || params.texture_quality === 'extreme') {
+        notes.push(t({ zh: `贴图质量 ${params.texture_quality}:价签更高`, en: `texture_quality ${params.texture_quality}: higher price tier` }));
+    }
+    if (params.geometry_quality === 'detailed') {
+        notes.push(t({ zh: 'geometry detailed(Ultra):加收 HD credit', en: 'geometry detailed (Ultra): extra HD credit' }));
+    }
+    if (params.quad === true) {
+        notes.push(t({ zh: 'quad 四边面:价签更高,输出 FBX', en: 'quad topology: higher price tier, FBX output' }));
+    }
+    if (params.generate_parts === true) {
+        notes.push(t({ zh: '分件生成:价签更高,出裸几何', en: 'part generation: higher price tier, bare geometry' }));
+    }
+    for (const step of card.chain) {
+        if (step.step === 'convert' && Object.keys(step.args).length > 1) {
+            notes.push(t({ zh: 'convert 非默认参数:按 complex 价签计费', en: 'non-default convert options bill as complex convert' }));
+        }
+        if (step.step === 'retarget') {
+            const count = Array.isArray(step.args.animations) ? step.args.animations.length : 1;
+            notes.push(t({ zh: `retarget ${count} 条动画:按条计费`, en: `retarget ${count} animation(s): billed per animation` }));
+        }
+    }
+    return notes;
+}
+/** Render the card for terminal display (stderr). */
+export function renderPlanCard(card) {
+    const scenario = card.scenario ? getScenario(card.scenario) : undefined;
+    const lines = [];
+    const title = t({ zh: '方案卡', en: 'Plan' });
+    lines.push(pc.bold(`── ${title} ──────────────────────────`));
+    lines.push(`${t({ zh: '输入', en: 'input' })}: ${card.inputSummary}`);
+    if (scenario)
+        lines.push(`${t({ zh: '场景', en: 'scenario' })}: ${scenario.id} (${t(scenario.label)})`);
+    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(' ')}`);
+    }
+    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(', ')}`);
+    }
+    const cost = costNotes(card);
+    if (cost.length > 0) {
+        lines.push(`${t({ zh: '成本影响', en: 'cost impact' })}:`);
+        for (const note of cost)
+            lines.push(`  · ${note}`);
+    }
+    for (const note of card.notes)
+        lines.push(pc.dim(`  ${note}`));
+    if (card.expertNotes && card.expertNotes.length > 0) {
+        lines.push(`${t({ zh: '专家意见', en: 'expert notes' })}:`);
+        for (const note of card.expertNotes)
+            lines.push(`  · ${note}`);
+    }
+    lines.push(pc.bold('──────────────────────────────────'));
+    return lines.join('\n');
+}

package/dist/ai/wizard.js

@@ -0,0 +1,105 @@
+/**
+ * Wizard mode (zero-LLM): 3–4 multiple-choice questions drive the same
+ * knowledge-base decision tree that experts use. Every user gets 80% of the
+ * intelligence with no LLM configured.
+ */
+import * as p from '@clack/prompts';
+import { CliError, UsageError } from '../core/errors.js';
+import { isInteractive } from '../core/output.js';
+import { t, tList } from '../i18n.js';
+import { EXIT } from '../knowledge/error-catalog.js';
+import { RIG_MODEL_V25 } from '../knowledge/models.js';
+import { getScenario, SCENARIOS } from '../knowledge/scenarios.js';
+export async function runWizard(initialPrompt) {
+    if (!isInteractive()) {
+        throw new UsageError(t({
+            zh: '向导需要交互终端;无头环境请直接用 tripo make --for <场景> 或配置 LLM 后用 tripo ai --yes',
+            en: 'the wizard needs an interactive terminal; headless callers should use "tripo make --for <scenario>" instead',
+        }));
+    }
+    p.intro('tripo ai');
+    let prompt = initialPrompt?.trim() ?? '';
+    if (!prompt) {
+        const answer = await p.text({
+            message: t({ zh: '想做个什么?一句话描述(或图片路径)', en: 'What do you want to make? one sentence (or an image path)' }),
+            validate: (v) => (v && v.trim().length > 0 ? undefined : t({ zh: '说点什么吧', en: 'say something' })),
+        });
+        if (p.isCancel(answer))
+            throw new CliError('cancelled', EXIT.FATAL);
+        prompt = answer.trim();
+    }
+    const scenarioAnswer = await p.select({
+        message: t({ zh: '用在什么地方?', en: 'What is it for?' }),
+        options: SCENARIOS.map((s) => ({ value: s.id, label: `${t(s.label)} — ${t(s.description)}` })),
+    });
+    if (p.isCancel(scenarioAnswer))
+        throw new CliError('cancelled', EXIT.FATAL);
+    const scenario = getScenario(scenarioAnswer);
+    let engine;
+    if (scenarioAnswer === 'game-mobile' || scenarioAnswer === 'game-pc') {
+        const engineAnswer = await p.select({
+            message: t({ zh: '目标引擎/软件?', en: 'Target engine/software?' }),
+            options: [
+                { value: 'unity', label: 'Unity' },
+                { value: 'unreal', label: 'Unreal' },
+                { value: 'blender', label: 'Blender' },
+                { value: 'any', label: t({ zh: '不确定/通用', en: 'not sure / generic' }) },
+            ],
+        });
+        if (p.isCancel(engineAnswer))
+            throw new CliError('cancelled', EXIT.FATAL);
+        engine = engineAnswer;
+    }
+    let animations = false;
+    if (scenarioAnswer !== 'print' && scenarioAnswer !== 'film') {
+        const animAnswer = await p.confirm({
+            message: t({ zh: '需要骨骼/动画吗?', en: 'Do you need a skeleton / animations?' }),
+            initialValue: scenarioAnswer === 'anim',
+        });
+        if (p.isCancel(animAnswer))
+            throw new CliError('cancelled', EXIT.FATAL);
+        animations = animAnswer;
+    }
+    const { chain, notes } = adjustChain(scenario.id, engine, animations);
+    const card = {
+        inputSummary: prompt,
+        scenario: scenario.id,
+        model: scenario.model,
+        modelReason: t({ zh: '场景预设', en: 'scenario preset' }),
+        genParams: scenario.genParams,
+        chain,
+        deliverables: scenario.deliverables,
+        notes: [...tList(scenario.notes), ...notes],
+    };
+    return { card, options: { prompt, scenario: scenario.id, chain } };
+}
+/** Engine/animation adjustments on top of the scenario chain. */
+export function adjustChain(scenarioId, engine, animations) {
+    const scenario = getScenario(scenarioId);
+    let chain = scenario.chain.map((s) => ({ step: s.step, args: { ...s.args } }));
+    const notes = [];
+    if (animations && !chain.some((s) => s.step === 'rig')) {
+        const rigArgs = { model: RIG_MODEL_V25, out_format: 'fbx' };
+        if (engine === 'unity') {
+            rigArgs.spec = 'mixamo';
+            notes.push(t({ zh: 'Unity Humanoid → spec=mixamo', en: 'Unity Humanoid → spec=mixamo' }));
+        }
+        chain = [
+            ...chain.filter((s) => s.step !== 'convert'),
+            { step: 'rig-check', args: {} },
+            { step: 'rig', args: rigArgs },
+            { step: 'retarget', args: { animations: ['preset:idle', 'preset:walk'], out_format: 'fbx' } },
+        ];
+        notes.push(t({ zh: '动画链输出 FBX(骨骼+动画)', en: 'animation chain outputs FBX (skeleton + animations)' }));
+    }
+    if (engine && !animations) {
+        const convert = chain.find((s) => s.step === 'convert');
+        if (convert && convert.args.format === 'FBX') {
+            if (engine === 'blender')
+                convert.args.fbx_preset = 'blender';
+            if (engine === 'unreal' || engine === 'unity')
+                convert.args.export_orientation = '+x';
+        }
+    }
+    return { chain, notes };
+}

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from './program.js';
+process.on('SIGINT', () => {
+    process.stderr.write('\n');
+    process.exit(130);
+});
+void runCli(process.argv);

package/dist/commands/account.js

@@ -0,0 +1,27 @@
+/** `tripo balance` / `tripo usage` — account visibility. */
+import { TripoClient } from '../core/client.js';
+import { emitResult } from '../core/output.js';
+import { t } from '../i18n.js';
+export function registerAccountCommands(program) {
+    program
+        .command('balance')
+        .description('show available and frozen credits')
+        .action(async () => {
+        const data = await new TripoClient().getBalance();
+        emitResult(data, t({
+            zh: `余额 ${data.balance} 积分(冻结 ${data.frozen})`,
+            en: `balance: ${data.balance} credits (${data.frozen} frozen)`,
+        }));
+    });
+    program
+        .command('usage')
+        .description('recent task credit usage')
+        .option('--limit <n>', 'max rows to show', (v) => Number(v), 20)
+        .action(async (opts) => {
+        const items = (await new TripoClient().getUsage()).slice(0, opts.limit);
+        const human = items
+            .map((i) => `${(i.created_at ?? '').slice(0, 19).padEnd(20)} ${i.type.padEnd(24)} ${String(i.credits_consumed ?? 0).padStart(6)} cr  ${i.task_id}`)
+            .join('\n');
+        emitResult(items, human || t({ zh: '暂无用量记录', en: 'no usage yet' }));
+    });
+}

package/dist/commands/ai.js

@@ -0,0 +1,114 @@
+/**
+ * `tripo ai` — dual mode:
+ *   wizard (default without an LLM): knowledge-base decision-tree Q&A
+ *   conversation (with an LLM configured): producer + specialist agents
+ * Both produce the same plan card; confirmed plans execute through the same
+ * deterministic engine as `tripo make`.
+ */
+import * as p from '@clack/prompts';
+import { resolveReference } from '../config/history.js';
+import { CliError } from '../core/errors.js';
+import { isInteractive, isYes, log, warn } from '../core/output.js';
+import { t } from '../i18n.js';
+import { EXIT } from '../knowledge/error-catalog.js';
+import { executeMake, planMake } from '../pipeline/make.js';
+import { renderPlanCard } from '../ai/plan-card.js';
+import { resolveLlmConfig } from '../ai/llm.js';
+import { buildExpertPlan } from '../ai/experts.js';
+import { runWizard } from '../ai/wizard.js';
+import { emitMakeOutcome } from './make.js';
+import { newClient, withTaskOptions } from './shared.js';
+export function registerAiCommand(program) {
+    const cmd = program
+        .command('ai')
+        .description('describe what you want in natural language; experts plan it, you confirm, it runs')
+        .argument('[request...]', 'e.g. "给我的手游做一个低模骑士,要跑步动画"')
+        .option('--wizard', 'force wizard mode even when an LLM is configured');
+    withTaskOptions(cmd);
+    cmd.action(async (request, flags) => {
+        const text = expandHistoryRefs(request.join(' ').trim());
+        const llm = resolveLlmConfig();
+        let card;
+        let makeOptions;
+        if (llm && !flags.wizard && text) {
+            log(t({ zh: `对话模式(${llm.model})…`, en: `conversation mode (${llm.model})…` }));
+            try {
+                const plan = await buildExpertPlan(text, isInteractive() ? askUser : undefined);
+                card = plan.card;
+                makeOptions = {
+                    inputs: [plan.prompt],
+                    scenario: plan.scenarioId,
+                    chain: plan.chain,
+                    params: plan.params,
+                    name: flags.name,
+                    outDir: flags.out,
+                    notify: flags.notify,
+                    timeoutMs: flags.timeout ? flags.timeout * 1000 : undefined,
+                };
+            }
+            catch (err) {
+                warn(t({
+                    zh: `LLM 编排失败(${err instanceof Error ? err.message : err}),回落到向导模式`,
+                    en: `LLM planning failed (${err instanceof Error ? err.message : err}); falling back to the wizard`,
+                }));
+                const wizard = await runWizard(text);
+                card = wizard.card;
+                makeOptions = wizardToOptions(wizard.options, flags);
+            }
+        }
+        else {
+            // The wizard is interactive by nature — never enter it headless.
+            if (!isInteractive()) {
+                throw new CliError(t({
+                    zh: '向导模式需要交互终端;无头环境请用 tripo make --for <场景>(或配置 llm.base_url/llm.model 走对话模式)',
+                    en: 'wizard mode needs an interactive terminal; headless callers should use "tripo make --for <scenario>" (or configure llm.base_url/llm.model for conversation mode)',
+                }), EXIT.USAGE);
+            }
+            const wizard = await runWizard(text || undefined);
+            card = wizard.card;
+            makeOptions = wizardToOptions(wizard.options, flags);
+        }
+        process.stderr.write(renderPlanCard(card) + '\n');
+        if (!isYes()) {
+            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;
+            }
+        }
+        const client = newClient();
+        const plan = await planMake(client, makeOptions);
+        const outcome = await executeMake(client, plan, makeOptions);
+        emitMakeOutcome({ results: [outcome.primary], chainResults: outcome.chainResults, stoppedEarly: outcome.stoppedEarly });
+    });
+}
+function wizardToOptions(options, flags) {
+    return {
+        inputs: [options.prompt],
+        scenario: options.scenario,
+        chain: options.chain,
+        params: flags.param,
+        name: flags.name,
+        outDir: flags.out,
+        notify: flags.notify,
+        timeoutMs: flags.timeout ? flags.timeout * 1000 : undefined,
+    };
+}
+async function askUser(question) {
+    const answer = await p.text({ message: question });
+    if (p.isCancel(answer))
+        return undefined;
+    return answer;
+}
+/** Replace @task-name references in a prompt with their task ids. */
+export function expandHistoryRefs(text) {
+    return text.replace(/@[\w\u4e00-\u9fff-]+/g, (ref) => {
+        try {
+            const entry = resolveReference(ref);
+            return entry ? entry.task_id : ref;
+        }
+        catch {
+            return ref; // ambiguity is reported when the value is actually used
+        }
+    });
+}