@remixmate/cli 0.9.35 → 0.9.37

package/dist/diagnostics.d.ts

@@ -1,4 +1,24 @@
 export declare function traceHeaders(): Record<string, string>;
-export declare function cleanDiagnosticText(value: string): string;
+/**
+ * Redact a string for anything that leaves this process (diagnostic lines,
+ * execution traces).
+ *
+ * Kept in lockstep with ab-agent's `lib/telemetry.cleanText` — the two feed the
+ * same `media_chat_turn_trace` table, and a table whose rows were sanitized by
+ * two different rulesets is a table nobody can reason about. ANSI stripping,
+ * e-mail and phone redaction were added here to close that gap.
+ *
+ * `max` caps the result in BYTES, keeping the head. Callers that need the tail
+ * (a command's decisive line is its last one) slice before calling.
+ */
+export declare function cleanDiagnosticText(value: string, max?: number): string;
+/**
+ * Exit code → the outcome vocabulary of the logging contract.
+ *
+ * Exported because the execution trace (project/trace.ts) reports the same
+ * verdict for the same run: two mappings would let a run be `failure` in the
+ * diagnostic line and `success` in the database.
+ */
+export declare function outcomeOf(exitCode: number): 'success' | 'cancelled' | 'rejected' | 'failure';
 /** Opt-in line framing for hosts; stdout is exclusively the existing skill protocol. */
 export declare function diagnostic(exitCode: number, durationMs: number, error?: unknown): void;

package/dist/diagnostics.js

@@ -8,8 +8,22 @@ export function traceHeaders() {
     process.env.AB_OPERATION_ID ||= randomUUID();
     return { traceparent: header };
 }
-export function cleanDiagnosticText(value) {
-    let text = value.replace(/https?:\/\/[^\s"'<>]+/g, raw => {
+/**
+ * Redact a string for anything that leaves this process (diagnostic lines,
+ * execution traces).
+ *
+ * Kept in lockstep with ab-agent's `lib/telemetry.cleanText` — the two feed the
+ * same `media_chat_turn_trace` table, and a table whose rows were sanitized by
+ * two different rulesets is a table nobody can reason about. ANSI stripping,
+ * e-mail and phone redaction were added here to close that gap.
+ *
+ * `max` caps the result in BYTES, keeping the head. Callers that need the tail
+ * (a command's decisive line is its last one) slice before calling.
+ */
+export function cleanDiagnosticText(value, max = 2048) {
+    let text = value
+        .replace(/\x1b\[[0-9;]*m/g, '')
+        .replace(/https?:\/\/[^\s"'<>]+/g, raw => {
         try {
             const url = new URL(raw);
             return url.origin + url.pathname;
@@ -17,19 +31,36 @@ export function cleanDiagnosticText(value) {
         catch {
             return '[url]';
         }
-    }).replace(/(Bearer\s+|(?:token|secret|password|api[_-]?key)\s*[=:]\s*)[^\s,;}]+/gi, '$1[redacted]');
+    })
+        .replace(/(Bearer\s+|(?:token|secret|password|api[_-]?key)\s*[=:]\s*)[^\s,;}]+/gi, '$1[redacted]')
+        .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[email]')
+        .replace(/\b1[3-9]\d{9}\b/g, '[phone]');
     for (const [key, secret] of Object.entries(process.env)) {
         if (/TOKEN|SECRET|PASSWORD|API_KEY/i.test(key) && secret && secret.length >= 6)
             text = text.split(secret).join('[redacted]');
     }
-    return Buffer.from(text).subarray(0, 2048).toString('utf8');
+    return Buffer.from(text).subarray(0, max).toString('utf8');
+}
+/**
+ * Exit code → the outcome vocabulary of the logging contract.
+ *
+ * Exported because the execution trace (project/trace.ts) reports the same
+ * verdict for the same run: two mappings would let a run be `failure` in the
+ * diagnostic line and `success` in the database.
+ */
+export function outcomeOf(exitCode) {
+    if (exitCode === 0)
+        return 'success';
+    if (exitCode === 130)
+        return 'cancelled';
+    return [2, 3, 4].includes(exitCode) ? 'rejected' : 'failure';
 }
 /** Opt-in line framing for hosts; stdout is exclusively the existing skill protocol. */
 export function diagnostic(exitCode, durationMs, error) {
     if (process.env.AB_DIAGNOSTICS !== '1')
         return;
     traceHeaders();
-    const outcome = exitCode === 0 ? 'success' : exitCode === 130 ? 'cancelled' : [2, 3, 4].includes(exitCode) ? 'rejected' : 'failure';
+    const outcome = outcomeOf(exitCode);
     const record = { schema_version: 1, timestamp: new Date().toISOString(), service: 'remixmate-cli', environment: process.env.APP_ENV ?? 'dev',
         level: outcome === 'failure' ? 'error' : 'info', event: 'cli.execution.completed', message: 'CLI execution completed', outcome,
         trace_id: process.env.AB_TRACEPARENT?.split('-')[1], operation_id: process.env.AB_OPERATION_ID,

package/dist/handlers/gen-voice.js

@@ -88,13 +88,26 @@ export async function genVoice(input, ctxIn) {
     if (speed < voice.speedMin || speed > voice.speedMax) {
         throw new SkillError(`❌ speed must be in the range ${voice.speedMin}~${voice.speedMax}`);
     }
+    // Language hint for mixed-script narration. Like `local`, this is deliberately
+    // absent from skill.json's `parameters`: the service already applies a sane
+    // default for every caller, so handing the model a 40-value enum only invites
+    // it to guess. Reachable from the DSL (global/scene `narration.languageBoost`,
+    // forwarded by render_video) and by typing the flag yourself. Omitted =
+    // the service default.
+    const languageBoost = input.language_boost?.trim() || undefined;
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
         preflightToken: ctxIn.auth?.token,
     });
     emitProgress({ phase: 'gen-voice:request', voiceId, speed });
-    const data = await mmPost(ctx, '/tool/tts', { provider: voice.provider, text, voiceSetting: { voiceId, speed }, outputFormat: 'url' }, { timeoutMs: 120_000 });
+    const data = await mmPost(ctx, '/tool/tts', {
+        provider: voice.provider,
+        text,
+        voiceSetting: { voiceId, speed },
+        outputFormat: 'url',
+        ...(languageBoost ? { languageBoost } : {}),
+    }, { timeoutMs: 120_000 });
     const audioUrl = data.audio;
     if (!audioUrl) {
         throw new SkillError(`❌ API response did not contain an audio URL: ${JSON.stringify(data)}`);

package/dist/install.d.ts

@@ -37,6 +37,7 @@ export declare function detectHosts(): Host[];
  * 完全看不到它，只会以为这个 CLI 不支持 —— 正是这次 WorkBuddy 的翻车方式。
  */
 export declare function projectOnlyHosts(): HostId[];
+export declare function packageVersion(): string;
 export declare function installUsage(): void;
 export declare function uninstallUsage(): void;
 export declare function runInstall(argv: string[]): number;

package/dist/install.js

@@ -147,7 +147,7 @@ export function detectHosts() {
 export function projectOnlyHosts() {
     return HOST_IDS.filter((id) => isInstalled(id) && !spec(id).userDirName);
 }
-function packageVersion() {
+export function packageVersion() {
     try {
         const raw = readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8');
         return JSON.parse(raw).version ?? 'unknown';

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.35",
-  "generatedAt": "2026-09-18T05:50:52.540Z",
+  "version": "0.9.37",
+  "generatedAt": "2026-09-21T03:49:51.210Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -350,18 +350,6 @@
             "type": "string",
             "description": "Video topic (required)"
           },
-          "platform": {
-            "type": "string",
-            "enum": [
-              "douyin",
-              "xiaohongshu",
-              "bilibili",
-              "wechat",
-              "youtube",
-              "generic"
-            ],
-            "description": "Target platform"
-          },
           "duration": {
             "type": "number",
             "description": "Target duration in seconds"
@@ -442,7 +430,6 @@
         ],
         "advanced": [],
         "hidden": [
-          "platform",
           "duration",
           "style",
           "ratio",

package/dist/project/take.d.ts

@@ -23,6 +23,10 @@ export interface EnsuredTake {
     projectId: string;
     created: boolean;
     attempt: number;
+    /** The grouping key this take was resolved under — reused as the trace's session id. */
+    sessionKey: string;
+    /** Provenance label of the host we're running inside ('' when unknown). */
+    host: string;
 }
 /**
  * Look up the take for the current grouping key without creating anything.

package/dist/project/take.js

@@ -62,6 +62,8 @@ export async function findTake(ctx) {
         projectId: res.projectId ?? '',
         created: false,
         attempt: res.attempt ?? 0,
+        sessionKey: takeKey.key,
+        host: takeKey.host,
     };
 }
 /**
@@ -98,5 +100,7 @@ export async function ensureTake(ctx, opts) {
         projectId,
         created: res.created,
         attempt: res.attempt,
+        sessionKey: takeKey.key,
+        host: takeKey.host,
     };
 }

package/dist/project/trace.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Execution-trace self-reporting — tell the backend what this invocation
+ * actually did, so a locally-run pipeline is not a blind spot.
+ *
+ * Why this exists: the cloud agent records every tool call, its arguments AND
+ * its result into `media_chat_turn_trace` (ab-agent/src/trace-persist.ts). The
+ * local path records nothing — a take created from codex / claude code has an
+ * empty conversation, zero tool calls and zero credits in the analytics tables,
+ * so every session-level metric silently excludes it.
+ *
+ * What we can honestly report and what we cannot: the CLI is a child process
+ * spawned once per skill call. It never sees the user's prompt or the host's
+ * reply — those live in the host's own transcript. So this module reports the
+ * one thing it genuinely observes: the invocation itself.
+ *
+ * See docs/cli-session-record-design.md §5.
+ */
+import { type HttpContext } from '../http.js';
+import type { ParsedArgs } from '../argv.js';
+import type { EnsuredTake } from './take.js';
+export interface TraceOptions {
+    skillName: string;
+    args: ParsedArgs;
+    take: EnsuredTake;
+    ctx: HttpContext;
+}
+/**
+ * Whether this invocation should report at all.
+ *
+ * The rule is deliberately narrow: report only when THIS process resolved the
+ * take. Everything else is already covered by someone else —
+ *   - under the cloud agent, CONVERSATION_ID arrives pre-set and ab-agent's own
+ *     TurnTracer already recorded the very same call;
+ *   - a nested `gen-image` spawned by prepare-video-assets inherits its
+ *     parent's CONVERSATION_ID, and the parent's row already covers it.
+ * Since runner.ts only builds a tracer after resolving a take itself, this
+ * function just honours the kill switch.
+ */
+export declare function tracingEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Collects one invocation's evidence and posts it as a single turn.
+ *
+ * Lifecycle (runner.ts): `begin()` → output flows through the tap → `finish()`
+ * in a finally block. Every failure mode ends in a warning on stderr: a lost
+ * trace row must never cost the user a render they already paid for.
+ */
+export declare class InvocationTrace {
+    private readonly opts;
+    private chunks;
+    private restore;
+    private flushed;
+    private constructor();
+    /** Returns null when tracing is off — callers can then skip output capture entirely. */
+    static begin(opts: TraceOptions): InvocationTrace | null;
+    /**
+     * Tap both output streams.
+     *
+     * One tap covers both dispatch paths: in-process handlers write here
+     * directly, and the Python child's piped output is re-emitted through the
+     * same `write` (see runner.ts). Restored in finish().
+     */
+    installCapture(): void;
+    /** Feed captured output. Keeps a bounded tail — the decisive line is the last one. */
+    absorb(chunk: unknown): void;
+    /**
+     * Emit the turn. Idempotent; never throws.
+     *
+     * `error` is the dispatcher's caught exception when there is one — a Python
+     * child that exits non-zero gives us no exception, only its output, which is
+     * exactly why the tail buffer exists.
+     */
+    finish(exitCode: number, durationMs: number, error?: unknown): Promise<void>;
+}
+/**
+ * Flags → a trace-safe object.
+ *
+ * Credentials are dropped outright; long strings are cut to their opening
+ * because an argument like `--prompt` is *content*, and this table is evidence,
+ * not an archive of what the user wrote.
+ */
+export declare function sanitiseArgs(args: ParsedArgs): Record<string, unknown>;
+/**
+ * Captured output → the tail we store.
+ *
+ * Two transformations before truncating, both about spending the 16KB on
+ * things a human would read:
+ *   - progress lines are the machine protocol — one fat JSON object per phase,
+ *     marked by a `__progress__` field (progress.ts, and the same shape from the
+ *     Python skills). Their payload is noise here, but WHICH PHASE a failed run
+ *     reached is the single most useful fact about it, so the line collapses to
+ *     its phase name instead of being dropped.
+ *   - `__diagnostic_v1__` lines are our own structured log of this very run;
+ *     keeping them would store the same verdict twice.
+ *
+ * Then keeps the TAIL, unlike ab-agent's head-first cleanText: a command's
+ * verdict — the error, or the URL it produced — is its last line.
+ */
+export declare function condense(raw: string): string;

package/dist/project/trace.js

@@ -0,0 +1,278 @@
+/**
+ * Execution-trace self-reporting — tell the backend what this invocation
+ * actually did, so a locally-run pipeline is not a blind spot.
+ *
+ * Why this exists: the cloud agent records every tool call, its arguments AND
+ * its result into `media_chat_turn_trace` (ab-agent/src/trace-persist.ts). The
+ * local path records nothing — a take created from codex / claude code has an
+ * empty conversation, zero tool calls and zero credits in the analytics tables,
+ * so every session-level metric silently excludes it.
+ *
+ * What we can honestly report and what we cannot: the CLI is a child process
+ * spawned once per skill call. It never sees the user's prompt or the host's
+ * reply — those live in the host's own transcript. So this module reports the
+ * one thing it genuinely observes: the invocation itself.
+ *
+ * See docs/cli-session-record-design.md §5.
+ */
+import os from 'node:os';
+import { cleanDiagnosticText, outcomeOf } from '../diagnostics.js';
+import { billingSummary } from '../billing.js';
+import { packageVersion } from '../install.js';
+import { mmPost } from '../http.js';
+/** Same ceiling ab-agent uses for a tool result — one table, one limit. */
+const TOOL_RESULT_MAX = 16 * 1024;
+/** Raw bytes held before trimming. Generous: trimming is the tail, cleaning is cheap. */
+const RAW_CAPTURE_MAX = 64 * 1024;
+/** Per-argument ceiling. Prompts and narration bodies are content, not evidence. */
+const ARG_VALUE_MAX = 512;
+/** `error_summary` is varchar(1024). */
+const ERROR_SUMMARY_MAX = 1024;
+const FLUSH_TIMEOUT_MS = 10_000;
+const SENSITIVE_KEY = /token|secret|password|api[_-]?key|authorization/i;
+/**
+ * Whether this invocation should report at all.
+ *
+ * The rule is deliberately narrow: report only when THIS process resolved the
+ * take. Everything else is already covered by someone else —
+ *   - under the cloud agent, CONVERSATION_ID arrives pre-set and ab-agent's own
+ *     TurnTracer already recorded the very same call;
+ *   - a nested `gen-image` spawned by prepare-video-assets inherits its
+ *     parent's CONVERSATION_ID, and the parent's row already covers it.
+ * Since runner.ts only builds a tracer after resolving a take itself, this
+ * function just honours the kill switch.
+ */
+export function tracingEnabled(env = process.env) {
+    return (env.REMIXMATE_TRACE ?? '').trim() !== '0';
+}
+/**
+ * Collects one invocation's evidence and posts it as a single turn.
+ *
+ * Lifecycle (runner.ts): `begin()` → output flows through the tap → `finish()`
+ * in a finally block. Every failure mode ends in a warning on stderr: a lost
+ * trace row must never cost the user a render they already paid for.
+ */
+export class InvocationTrace {
+    opts;
+    chunks = '';
+    restore = null;
+    flushed = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Returns null when tracing is off — callers can then skip output capture entirely. */
+    static begin(opts) {
+        if (!tracingEnabled())
+            return null;
+        if (!opts.take.conversationId)
+            return null;
+        return new InvocationTrace(opts);
+    }
+    /**
+     * Tap both output streams.
+     *
+     * One tap covers both dispatch paths: in-process handlers write here
+     * directly, and the Python child's piped output is re-emitted through the
+     * same `write` (see runner.ts). Restored in finish().
+     */
+    installCapture() {
+        if (this.restore)
+            return;
+        const out = process.stdout.write.bind(process.stdout);
+        const err = process.stderr.write.bind(process.stderr);
+        const tap = (original) => ((chunk, ...rest) => {
+            this.absorb(chunk);
+            return original(chunk, ...rest);
+        });
+        process.stdout.write = tap(out);
+        process.stderr.write = tap(err);
+        this.restore = () => {
+            process.stdout.write = out;
+            process.stderr.write = err;
+        };
+    }
+    /** Feed captured output. Keeps a bounded tail — the decisive line is the last one. */
+    absorb(chunk) {
+        try {
+            const text = typeof chunk === 'string'
+                ? chunk
+                : chunk instanceof Uint8Array
+                    ? Buffer.from(chunk).toString('utf8')
+                    : '';
+            if (!text)
+                return;
+            this.chunks += text;
+            if (this.chunks.length > RAW_CAPTURE_MAX * 2) {
+                this.chunks = this.chunks.slice(-RAW_CAPTURE_MAX);
+            }
+        }
+        catch {
+            // Capturing must never break the thing being captured.
+        }
+    }
+    /**
+     * Emit the turn. Idempotent; never throws.
+     *
+     * `error` is the dispatcher's caught exception when there is one — a Python
+     * child that exits non-zero gives us no exception, only its output, which is
+     * exactly why the tail buffer exists.
+     */
+    async finish(exitCode, durationMs, error) {
+        this.restore?.();
+        this.restore = null;
+        if (this.flushed)
+            return;
+        this.flushed = true;
+        const { skillName, args, take, ctx } = this.opts;
+        const output = condense(this.chunks);
+        const outcome = outcomeOf(exitCode);
+        const isError = exitCode !== 0;
+        const rows = [];
+        let stepSeq = 0;
+        // One env row per take, not per call: it describes the toolchain, and the
+        // toolchain does not change between two calls of the same pipeline.
+        if (take.created) {
+            rows.push({ sessionId: take.sessionKey, stepSeq: stepSeq++, kind: 'env', env: envSnapshot(take) });
+        }
+        rows.push({
+            sessionId: take.sessionKey,
+            stepSeq: stepSeq++,
+            kind: 'tool_call',
+            toolName: `cli__${skillName.replace(/-/g, '_')}`,
+            toolUseId: (process.env.AB_OPERATION_ID ?? '').slice(0, 64),
+            toolInput: sanitiseArgs(args),
+            toolResult: output || '[no output captured]',
+            isError,
+            durationMs: Math.round(durationMs),
+        });
+        rows.push({
+            sessionId: take.sessionKey,
+            stepSeq: stepSeq++,
+            kind: 'turn_result',
+            outcome,
+            errorSummary: isError ? summariseError(error, output) : '',
+            credits: billingSummary()?.credits ?? 0,
+        });
+        try {
+            await mmPost(ctx, `/chat/conversation/${encodeURIComponent(take.conversationId)}/trace`, 
+            // appendTurn: the server allocates turn_seq. N unrelated processes
+            // cannot number themselves, and cli-project-binding §5.1 already ruled
+            // out keeping local state. Older backends ignore the field and every
+            // row lands on turn 0 — still ordered, just ungrouped.
+            { appendTurn: true, traces: rows }, { timeoutMs: FLUSH_TIMEOUT_MS });
+        }
+        catch (err) {
+            process.stderr.write(`⚠️  执行轨迹未能上报（不影响本次产物）: ${cleanDiagnosticText(err.message, 256)}\n`);
+        }
+    }
+}
+/** Which rung of the grouping ladder produced this key (cli-project-binding §5.1). */
+function keySource(key) {
+    if (key.startsWith('custom:'))
+        return 'env-override';
+    if (key.startsWith('job:'))
+        return 'render-job';
+    return 'host';
+}
+/**
+ * What this take was produced by. Mirrors ab-agent's envSnapshot() in purpose:
+ * answer "which version started failing" without storing anything large.
+ */
+function envSnapshot(take) {
+    return {
+        // The discriminator every cross-channel metric needs — a CLI "turn" is one
+        // skill call, a cloud turn is a whole user request. Never compare blindly.
+        channel: 'cli',
+        cli_version: packageVersion(),
+        host: take.host || 'unknown',
+        take_key_source: keySource(take.sessionKey),
+        node: process.version,
+        platform: `${os.platform()}-${os.arch()}`,
+    };
+}
+/**
+ * Flags → a trace-safe object.
+ *
+ * Credentials are dropped outright; long strings are cut to their opening
+ * because an argument like `--prompt` is *content*, and this table is evidence,
+ * not an archive of what the user wrote.
+ */
+export function sanitiseArgs(args) {
+    const out = {};
+    for (const [key, value] of Object.entries(args).slice(0, 40)) {
+        if (SENSITIVE_KEY.test(key)) {
+            out[key] = '[redacted]';
+            continue;
+        }
+        if (typeof value === 'boolean') {
+            out[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            out[key] = value.slice(0, 20).map((v) => cleanDiagnosticText(String(v), ARG_VALUE_MAX));
+            continue;
+        }
+        out[key] = cleanDiagnosticText(String(value), ARG_VALUE_MAX);
+    }
+    return out;
+}
+/**
+ * Captured output → the tail we store.
+ *
+ * Two transformations before truncating, both about spending the 16KB on
+ * things a human would read:
+ *   - progress lines are the machine protocol — one fat JSON object per phase,
+ *     marked by a `__progress__` field (progress.ts, and the same shape from the
+ *     Python skills). Their payload is noise here, but WHICH PHASE a failed run
+ *     reached is the single most useful fact about it, so the line collapses to
+ *     its phase name instead of being dropped.
+ *   - `__diagnostic_v1__` lines are our own structured log of this very run;
+ *     keeping them would store the same verdict twice.
+ *
+ * Then keeps the TAIL, unlike ab-agent's head-first cleanText: a command's
+ * verdict — the error, or the URL it produced — is its last line.
+ */
+export function condense(raw) {
+    if (!raw)
+        return '';
+    const compacted = raw
+        .split('\n')
+        .map((line) => {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('__diagnostic_v1__'))
+            return null;
+        if (!trimmed.startsWith('{') || !trimmed.includes('"__progress__"'))
+            return line;
+        try {
+            const phase = JSON.parse(trimmed).phase;
+            return typeof phase === 'string' ? `· phase=${phase}` : '· progress';
+        }
+        catch {
+            return '· progress';
+        }
+    })
+        .filter((line) => line !== null)
+        .join('\n')
+        .trim();
+    // Slice the tail before cleaning: cleanDiagnosticText truncates head-first.
+    const tail = compacted.length > TOOL_RESULT_MAX ? compacted.slice(-TOOL_RESULT_MAX) : compacted;
+    return cleanDiagnosticText(tail, TOOL_RESULT_MAX);
+}
+/**
+ * The one-line verdict.
+ *
+ * A thrown SkillError carries it directly. A Python child does not throw — it
+ * just exits non-zero, so fall back to the last line it printed, which is where
+ * argparse errors, tracebacks and our own ❌ messages end up.
+ */
+function summariseError(error, output) {
+    if (error instanceof Error && error.message) {
+        return cleanDiagnosticText(error.message, ERROR_SUMMARY_MAX);
+    }
+    const lastLine = output
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('· phase='))
+        .pop();
+    return lastLine ? cleanDiagnosticText(lastLine, ERROR_SUMMARY_MAX) : '';
+}

package/dist/runner.js

@@ -19,6 +19,7 @@ import { authChildEnv, ensureAuth } from './auth/ensure.js';
 import { emitBillingFooter } from './billing.js';
 import { resolveHttpContext } from './http.js';
 import { ensureTake, findTake } from './project/take.js';
+import { InvocationTrace } from './project/trace.js';
 /** Read the token override accepted by both the TS handlers and the Python skills. */
 function tokenFlag(args) {
     const value = args.token ?? args.priv_token;
@@ -28,6 +29,7 @@ export async function runSkill(skillName, opts) {
     const started = performance.now();
     let exitCode = EXIT.ERROR;
     let failure;
+    let trace = null;
     traceHeaders();
     const skill = findSkill(skillName, opts.baseDir ?? SKILLS_DIR);
     if (!skill) {
@@ -41,25 +43,43 @@ export async function runSkill(skillName, opts) {
             apiBaseUrl: typeof opts.parsedArgs.api_base_url === 'string' ? opts.parsedArgs.api_base_url : undefined,
             flagToken: tokenFlag(opts.parsedArgs),
         });
-        await applyTakeContext(skill, opts, auth);
+        const attached = await applyTakeContext(skill, opts, auth);
+        if (attached) {
+            // Only a take THIS process resolved gets reported — see trace.ts for why
+            // the cloud path and nested pipeline children must stay silent.
+            trace = InvocationTrace.begin({
+                skillName: skill.name,
+                args: opts.parsedArgs,
+                take: attached.take,
+                ctx: attached.ctx,
+            });
+            trace?.installCapture();
+        }
         switch (skill.entry.type) {
             case 'python':
                 // Python children talk to ab-api themselves and print their own billing
                 // footer; nothing was charged through this process.
-                return exitCode = await runPython(skill, opts.rawArgs, auth);
+                exitCode = await runPython(skill, opts.rawArgs, auth, trace);
+                break;
             case 'http':
             case 'builtin':
-                return exitCode = await runHandler(skill, opts.parsedArgs, auth);
+                exitCode = await runHandler(skill, opts.parsedArgs, auth);
+                break;
         }
     }
     catch (err) {
         failure = err;
         if (err instanceof SkillError) {
             process.stderr.write(cleanDiagnosticText(err.message) + '\n');
-            return exitCode = err.exitCode;
+            exitCode = err.exitCode;
         }
-        process.stderr.write(`❌ unexpected error: ${cleanDiagnosticText(err.stack ?? err.message)}\n`);
-        return EXIT.ERROR;
+        else {
+            process.stderr.write(`❌ unexpected error: ${cleanDiagnosticText(err.stack ?? err.message)}\n`);
+            exitCode = EXIT.ERROR;
+        }
+        // Single exit point below: the trace flush in `finally` must run before the
+        // value leaves, and an `await` there defeats TS's reachability analysis on
+        // returns made from inside the try/catch.
     }
     finally {
         // In `finally` because a run can fail *after* a billed step (e.g. the image
@@ -67,7 +87,12 @@ export async function runSkill(skillName, opts) {
         // reported either way. No-ops when nothing was charged.
         diagnostic(exitCode, performance.now() - started, failure);
         emitBillingFooter();
+        // Last, so the billing footer is still inside the captured tail. Never
+        // throws and never changes the exit code — a lost trace row must not cost
+        // the user a render they already paid for.
+        await trace?.finish(exitCode, performance.now() - started, failure);
     }
+    return exitCode;
 }
 /**
  * Decide the take mode from the skill's declaration *and* what this particular
@@ -118,11 +143,11 @@ export function resolveTakeMode(skill, args) {
 async function applyTakeContext(skill, opts, auth) {
     const mode = resolveTakeMode(skill, opts.parsedArgs);
     if (mode === 'none')
-        return;
+        return null;
     if ((process.env.CONVERSATION_ID ?? '').trim())
-        return;
+        return null;
     if (!auth.token)
-        return;
+        return null;
     try {
         const ctx = await resolveHttpContext(skill.name, {
             apiBaseUrl: auth.apiBaseUrl,
@@ -142,16 +167,32 @@ async function applyTakeContext(skill, opts, auth) {
             take = await findTake(ctx);
         }
         if (!take)
-            return;
+            return null;
         process.env.CONVERSATION_ID = take.conversationId;
         process.stdout.write(`📁 take ${take.created ? 'created' : 'reused'}: ${take.videoProjectId} ` +
             `(project ${take.projectId}${take.attempt ? `, attempt ${take.attempt}` : ''})\n`);
+        return { take, ctx };
     }
     catch (err) {
         process.stderr.write(`⚠️  无法归属本次产物（内容仍会正常生成，但不会出现在项目里）: ${cleanDiagnosticText(err.message)}\n`);
+        return null;
     }
 }
-async function runPython(skill, rawArgs, auth) {
+/**
+ * Spawn the Python skill.
+ *
+ * `stdio: 'inherit'` is the default and stays the default: the child writes
+ * straight to the terminal, which is exactly what a CLI should do. It does mean
+ * the parent sees nothing, so a failed render can only ever be reported as
+ * "exit code 1" — for the most valuable step in the pipeline.
+ *
+ * So when (and only when) we are tracing, stdout/stderr are piped and re-emitted
+ * verbatim, which routes them through the capture tap. stdin stays inherited so
+ * interactive prompts still work. Resolving on `close` rather than `exit` in
+ * that mode matters: `exit` can fire while the last chunk is still in the pipe,
+ * which is precisely the chunk holding the error message.
+ */
+async function runPython(skill, rawArgs, auth, trace) {
     if (!skill.scriptAbsolutePath) {
         throw new SkillError(`skill ${skill.name} has entry.type=python but no scriptAbsolutePath`);
     }
@@ -159,10 +200,14 @@ async function runPython(skill, rawArgs, auth) {
     return await new Promise((resolve) => {
         const proc = spawn('python3', [skill.scriptAbsolutePath, ...rawArgs], {
             cwd,
-            stdio: 'inherit',
+            stdio: trace ? ['inherit', 'pipe', 'pipe'] : 'inherit',
             env: { ...process.env, ...authChildEnv(auth), PYTHONUNBUFFERED: '1' },
         });
-        proc.on('exit', (code) => resolve(code ?? EXIT.ERROR));
+        if (trace) {
+            proc.stdout?.on('data', (chunk) => process.stdout.write(chunk));
+            proc.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+        }
+        proc.on(trace ? 'close' : 'exit', (code) => resolve(code ?? EXIT.ERROR));
         proc.on('error', (err) => {
             process.stderr.write(`❌ failed to spawn python3: ${err.message}\n`);
             resolve(EXIT.SPAWN_FAILED);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.35",
+  "version": "0.9.37",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,6 +26,7 @@
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
     "test:card-array-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-card-array-keys.py",
     "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",
+    "test:narration-tts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-tts.py",
     "test:render-resume": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-resume.py",
     "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
     "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",

package/skills/gen-script/SKILL.md

@@ -171,7 +171,7 @@ The agent should show the following in clear Markdown:
 
 ### Video info
 - Topic: 3 AI study hacks
-- Platform: douyin | Aspect ratio: 9:16 | Estimated duration: 45s
+- Aspect ratio: 9:16 | Estimated duration: 45s
 
 ### Scene structure
 | # | Purpose | Duration | Narration |
@@ -374,7 +374,7 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 ## Steps
 
 1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Every command below uses `<SkillDir>/scripts/gen_script.py`; never hard-code paths.
-2. **Understand the request**: extract topic, target platform, duration, style, audience, etc.
+2. **Understand the request**: extract topic, duration, style, audience, etc.
 3. **If the user specifies a template, read it first**: load the matching `template.json` via `template-registry` and confirm its template-specific fields and asset requirements. Do not skip this step.
 4. **Generate the DSL**: pick the right command or DSL shape for the target template (see the per-template commands below).
 5. **Schema validation**: make sure the output DSL conforms to v1alpha1.
@@ -385,7 +385,6 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "3 AI hacks that double your study efficiency" \
-  --platform douyin \
   --duration 30 \
   --style "tech" \
   --ratio "9:16"
@@ -416,7 +415,6 @@ python3 <SkillDir>/scripts/gen_script.py \
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--topic` | Video topic (required unless `--validate`). | — |
-| `--platform` | Target platform: `douyin` / `xiaohongshu` / `bilibili` / `wechat` / `youtube` / `generic`. | `generic` |
 | `--headline` | On-screen main title (4–12 chars / ~3 words). Written to `meta.headline` + `textLayers[role=headline]`. **Pass it whenever the user gave a title** — otherwise headline falls back to the long-form topic and overflows the top text layer. | falls back to `--topic` |
 | `--subheadline` | On-screen subtitle / slogan. Written to `meta.subheadline` + `textLayers[role=subheadline]`. Multi-line via `\n`; how many lines survive and whether `**emphasis**` renders is declared per template — see its `llmHint`. Not the same thing as CC subtitles (`global.subtitle`). | `""` |
 | `--duration` | Target duration (seconds). Templates whose `durationStrategy` is `fit-caption` / `fit-narration` recompute the real duration and ignore this value. | `30` |
@@ -474,7 +472,6 @@ prefix and version — not a short alias:
 
 - **Schema validation failed**: check the DSL JSON shape and required fields against the schema.
 - **Scene duration mismatch**: adjust the narration length or the scene duration.
-- **Invalid platform**: look at the supported-platform list.
 - **`carousel-caption template ... needs visual or text content`**: you passed neither `--carousel-items` nor `--caption-lines`. Pass the user's media URLs (and caption lines where the template requires them).
 - **`template ... is typewriter-driven ... but --caption-lines is empty`**: a `fit-caption` template got no caption. Write the copy yourself if the user did not supply it, then pass one `--caption-lines` per line.
 - **`duration Ns is below/above template ... supportedDurations`**: the assembled DSL falls outside the range the template declares it was designed for. Below the minimum usually means the content is too thin (add caption lines / narration / scenes); above the maximum means trimming content or lowering `--duration`. This is enforced at generation time on purpose — a degenerate video still costs full render credits.

package/skills/gen-script/scripts/gen_script.py

@@ -3,8 +3,8 @@
 Video script generator — turns a topic into Video DSL v1alpha1 JSON.
 
 Default behavior:
-  Produces a structured Video DSL JSON to stdout based on the topic, platform,
-  duration, and other constraints.
+  Produces a structured Video DSL JSON to stdout based on the topic, duration,
+  and other constraints.
 
 Usage:
   python gen_script.py --topic "3 AI hacks that double study efficiency" --duration 30 --ratio "9:16"
@@ -56,7 +56,6 @@ try:
 except ImportError:
     _HAS_REGISTRY_LOADER = False
 
-VALID_PLATFORMS = ["douyin", "xiaohongshu", "bilibili", "wechat", "youtube", "generic"]
 VALID_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
 VALID_PURPOSES = ["opening", "point", "example", "explanation", "highlight", "cta", "ending"]
 
@@ -761,7 +760,6 @@ def _build_carousel_caption_dsl(
     carousel_items: list[str],
     caption_lines: list[str],
     duration: int,
-    platform: str,
     style: str,
     ratio: str,
     resolution: str,
@@ -910,7 +908,6 @@ def _build_carousel_caption_dsl(
             "topic": topic,
             "headline": effective_headline,
             "subheadline": effective_subheadline,
-            "platform": platform,
             "targetDuration": effective_duration,
             "language": LANGUAGE_TO_META.get(output_language, "zh-CN"),
             "outputLanguage": output_language,
@@ -987,7 +984,6 @@ def _build_custom_payload(template_config: dict | None) -> dict:
 
 def build_dsl(
         topic: str,
-        platform: str,
         duration: int,
         style: str,
         ratio: str,
@@ -1124,7 +1120,6 @@ def build_dsl(
             carousel_items=carousel_items or [],
             caption_lines=caption_lines or [],
             duration=duration,
-            platform=platform,
             style=style,
             ratio=ratio,
             resolution=resolution,
@@ -1419,7 +1414,6 @@ def build_dsl(
             "topic": topic,
             "headline": effective_headline,
             "subheadline": effective_subheadline,
-            "platform": platform,
             "targetDuration": duration,
             "language": LANGUAGE_TO_META[output_language],
             "outputLanguage": output_language,
@@ -1461,12 +1455,6 @@ Examples:
         """,
     )
     parser.add_argument("--topic", help="Video topic (required for generation mode)")
-    parser.add_argument(
-        "--platform",
-        default="generic",
-        choices=VALID_PLATFORMS,
-        help="Target platform (default: generic)",
-    )
     parser.add_argument("--duration", type=int, default=30, help="Target duration in seconds (default: 30)")
     parser.add_argument("--style", default="", help="Style tag")
     parser.add_argument("--ratio", default=None, choices=VALID_RATIOS, help="Aspect ratio. When omitted: if --template-id is set, use the template's supportedAspectRatios[0]; otherwise default 16:9.")
@@ -1625,7 +1613,6 @@ Examples:
 
     print(f"📝 generating video script...", file=sys.stderr)
     print(f"   topic: {args.topic}", file=sys.stderr)
-    print(f"   platform: {args.platform}", file=sys.stderr)
     print(f"   duration: {args.duration}s", file=sys.stderr)
     print(f"   ratio: {args.ratio}", file=sys.stderr)
     if args.speed is not None:
@@ -1664,7 +1651,6 @@ Examples:
 
     dsl = build_dsl(
         topic=args.topic,
-        platform=args.platform,
         duration=args.duration,
         style=args.style,
         ratio=args.ratio,

package/skills/gen-script/skill.json

@@ -20,18 +20,6 @@
         "type": "string",
         "description": "Video topic (required)"
       },
-      "platform": {
-        "type": "string",
-        "enum": [
-          "douyin",
-          "xiaohongshu",
-          "bilibili",
-          "wechat",
-          "youtube",
-          "generic"
-        ],
-        "description": "Target platform"
-      },
       "duration": {
         "type": "number",
         "description": "Target duration in seconds"
@@ -112,7 +100,6 @@
     ],
     "advanced": [],
     "hidden": [
-      "platform",
       "duration",
       "style",
       "ratio",

package/skills/gen-voice/SKILL.md

@@ -84,6 +84,7 @@ remixmate gen-voice --text "<text-to-synthesize>" --json-output
 | `--text` | Text to synthesize (required, except with `--list-voices`) | — |
 | `--voice-id` | Voice id (use `--list-voices` to discover) | `Chinese (Mandarin)_Male_Announcer` |
 | `--speed` | Speech rate, 0.5–2.0 | `1.0` |
+| `--language-boost` | CLI-only. Language hint for MiniMax (`auto` / `Chinese` / `English` / …). Mixed-script narration ("只有四个字：Agent Loop") mispronounces the Latin terms without one, so the service already applies its own default — pass this only to pin a specific language. Usually set from the DSL (`global.narration.languageBoost`, scene-level overrides) rather than by hand. Not exposed to the agent — see the handler comment. | service default |
 | `--list-voices` | List available voices and exit | — |
 | `--local` | CLI-only. With `--list-voices`: print the 2-entry hardcoded fallback list instead of querying the service (offline dev). Not exposed to the agent — see the handler comment. | off |
 | `--json-output` | Emit JSON (url, audio_length_ms, subtitles) | off |

package/skills/render-video/scripts/render_video.py

@@ -175,6 +175,23 @@ def _narration_speed(narration: dict) -> Optional[float]:
     return float(raw) if raw > 0 else None
 
 
+def _narration_language_boost(narration: dict) -> Optional[str]:
+    """Read a narration block's language hint, or None when unset.
+
+    Same tolerance as _narration_speed: a malformed value must not take down an
+    otherwise fine render. The service applies its own default when we send
+    nothing, so "unset" is always a safe outcome — this flag exists to pin a
+    language when auto-detection is not good enough (e.g. an English-only
+    template whose narration still carries a Chinese brand name).
+    """
+    if not isinstance(narration, dict):
+        return None
+    raw = narration.get("languageBoost")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    return raw.strip()
+
+
 def extract_narration_lines(narration: dict) -> Optional[tuple[list[str], int, list[Optional[float]]]]:
     """If narration uses the structured {intro, items, outro} form, return
     (lines, intro_line_count, at_sec_list). `at_sec_list` is parallel to
@@ -650,6 +667,7 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
     dsl_assets_by_id = {a["assetId"]: a for a in dsl.get("assets", [])}
     global_narration = (dsl.get("global") or {}).get("narration") or {}
     global_speed = _narration_speed(global_narration)
+    global_language_boost = _narration_language_boost(global_narration)
     for scene in dsl.get("scenes", []):
         narration = (scene.get("audio") or {}).get("narration") or {}
         ref = narration.get("assetRef")
@@ -666,6 +684,13 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
             speed = global_speed
         if speed is not None:
             payload["speed"] = speed
+        # 语种提示走与语速完全相同的路线（场景覆盖全局，都不写就交给服务端默认）：
+        # resolve_asset_audio 只看得见 asset，看不见 scene。
+        language_boost = _narration_language_boost(narration)
+        if language_boost is None:
+            language_boost = global_language_boost
+        if language_boost is not None:
+            payload["languageBoost"] = language_boost
         extracted = extract_narration_lines(narration)
         if extracted:
             lines, intro_lines, _ = extracted
@@ -905,6 +930,10 @@ def resolve_asset_audio(asset: dict, private_token: str, timeout: int) -> dict:
     speed = _narration_speed(payload)
     if speed is not None:
         cmd.extend(["--speed", str(speed)])
+    # 同 speed：不带就**不传**这个 flag，默认值归服务端一处持有。
+    language_boost = _narration_language_boost(payload)
+    if language_boost is not None:
+        cmd.extend(["--language-boost", language_boost])
     if private_token:
         cmd.extend(["--priv-token", private_token])
 

package/skills/template-registry/SKILL.md

@@ -193,6 +193,7 @@ Rules:
 - Do not write `templateData.highlightMap`; `render_video.py` builds it automatically from the per-line timestamps that TTS returns.
 - If the author explicitly provides a `highlightMap`, the system keeps it as-is.
 - The legacy flat `narration.text` form still works but the author then has to keep `highlightMap` in sync with the subtitle segmentation (error-prone, not recommended).
+- `narration.languageBoost` (optional, also accepted at `global.narration`) pins the TTS language hint (`auto` / `Chinese` / `English` / …). Leave it unset unless auto-detection gets it wrong — the service applies its own default, and a scene-level value overrides the global one, exactly like `speed`.
 
 ## Image sources (picture-book-en and every other template)
 

package/skills/template-registry/video_dsl/runtime/dsl_validator.py

@@ -25,7 +25,6 @@ import re
 from typing import Iterable, Optional
 
 VALID_VERSIONS = {"v1alpha1"}
-VALID_PLATFORMS = {"douyin", "xiaohongshu", "bilibili", "wechat", "youtube", "generic"}
 VALID_RATIOS = {"16:9", "9:16", "1:1", "4:3", "3:4", "21:9"}
 VALID_RESOLUTIONS = {"480p", "720p", "1080p", "4k"}
 VALID_PURPOSES = {"opening", "intro", "point", "example", "explanation", "transition", "highlight", "cta", "ending"}
@@ -175,19 +174,6 @@ def _check_meta_presence(dsl: dict) -> list[ValidationError]:
     return errors
 
 
-def _check_meta_enums(dsl: dict) -> list[ValidationError]:
-    """完整版额外:meta.platform 必须是已知枚举。"""
-    errors: list[ValidationError] = []
-    meta = dsl.get("meta")
-    if isinstance(meta, dict):
-        platform = meta.get("platform", "generic")
-        if platform not in VALID_PLATFORMS:
-            errors.append(ValidationError(
-                "meta.platform", f"must be one of {sorted(VALID_PLATFORMS)}",
-            ))
-    return errors
-
-
 def _check_global_presence(dsl: dict) -> list[ValidationError]:
     """gen-script 历史:global 必须存在(只检查存在性)。"""
     if not isinstance(dsl.get("global"), dict):
@@ -358,6 +344,51 @@ def _check_assetbindings_deprecation(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+def _check_narration_items_text_coexist(dsl: dict) -> list[ValidationError]:
+    """分行旁白与整段 ``narration.text`` 并存 → warning(text 会被整个忽略)。
+
+    渲染侧是 **items 优先、text 完全忽略**:``extract_narration_lines`` 一旦拿到
+    items,TTS 文本就是 ``"\\n".join(items)``,字幕也改走 ``split_subtitle_from_lines``,
+    ``narration.text`` 既不喂 TTS 也不切字幕。
+
+    为什么值得报:gen_script 的骨架**总是**写一条 ``narration.text``,agent 之后为
+    逐行高亮补 items 时不会删它,于是两者并存几乎是这类模板的默认结局。留着的那
+    一份是死数据 —— 它曾经在旁白编辑面板里被当成"可以单独改、单独重新生成"的一
+    行摆出来(实测一个场景因此显示三行,其中一行是另外两行拼起来的),改它不影响
+    成片,生成它照样扣积分。
+
+    只报 warning 不拒绝:两者并存不会让画面出错,它只是让人误以为 text 还有用。
+    """
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        sid = scene.get("id", f"scenes[{idx}]")
+        narration = (scene.get("audio") or {}).get("narration") or {}
+        if not isinstance(narration, dict):
+            continue
+        items = narration.get("items")
+        has_items = isinstance(items, list) and any(
+            (isinstance(x, str) and x.strip()) or isinstance(x, dict) for x in items
+        )
+        has_intro_outro = any(
+            isinstance(narration.get(k), str) and narration[k].strip()
+            for k in ("intro", "outro")
+        )
+        text = narration.get("text")
+        if not (has_items or has_intro_outro):
+            continue
+        if not (isinstance(text, str) and text.strip()):
+            continue
+        errors.append(ValidationError(
+            f"scenes[{idx}].audio.narration.text",
+            f"scene '{sid}': this scene uses per-line narration (intro/items/outro), so "
+            "narration.text is ignored end to end — it is neither sent to TTS nor split "
+            "into subtitles. Leaving it here makes it look like editable copy that no "
+            "longer affects the video. Drop the text field and keep the lines.",
+            severity="warning",
+        ))
+    return errors
+
+
 def _check_narration_items_count(dsl: dict) -> list[ValidationError]:
     """render-video / 完整版:结构化 narration items 数与 templateData 的对应数组等长。
 
@@ -978,6 +1009,7 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     errors += _check_asset_duplicates(dsl)
     errors += _check_scene_asset_refs(dsl)
     errors += _check_narration_items_count(dsl)
+    errors += _check_narration_items_text_coexist(dsl)
     # 新增(非历史规则):多版式模板必须逐场景选定 slideId。放进 integrity 集合是因为
     # render-video 与 prepare_video_assets 都走这条 —— 而"没选版式"正是要在烧掉渲染
     # 积分之前拦住的东西。单版式模板不受影响,见 _check_slide_id_chosen。
@@ -1001,7 +1033,6 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors: list[ValidationError] = []
     errors += _check_version(dsl)
     errors += _check_meta_presence(dsl)
-    errors += _check_meta_enums(dsl)
     errors += _check_global_presence(dsl)
     errors += _check_global_enums(dsl)
     errors += _check_scenes_min(dsl)
@@ -1014,6 +1045,7 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_scene_asset_refs(dsl)
     errors += _check_assetbindings_deprecation(dsl)
     errors += _check_narration_items_count(dsl)
+    errors += _check_narration_items_text_coexist(dsl)
     errors += _check_narration_language_strict(dsl)
     errors += _check_slide_id_chosen(dsl)
     errors += _check_slide_payload_fields(dsl)

package/skills/template-registry/video_dsl/runtime/timeline_compiler.py

@@ -50,21 +50,70 @@ def resolve_dimensions(ratio: str, resolution: str) -> tuple[int, int]:
     return dims.get(resolution, dims.get("1080p", (1920, 1080)))
 
 
+def _is_latin_word_char(ch: str) -> bool:
+    return ch.isascii() and ch.isalnum()
+
+
+def _breakable(prev_token: str, next_token: str) -> bool:
+    """两个 token 之间断开是否安全 —— 拉丁↔拉丁即同一词组内部，不安全。
+
+    拆与并共用这一个判据：断的时候躲开的边界，并的时候就得把空格补回去。
+    """
+    if not prev_token or not next_token:
+        return True
+    return not (_is_latin_word_char(prev_token[-1]) and _is_latin_word_char(next_token[0]))
+
+
+def _concat_segments(left: str, right: str) -> str:
+    """拼接两个字幕段，必要时补回被切分吃掉的那个空格。
+
+    ``_split_at_spaces`` 在空格处断开，空格本身不属于任何一段；直接 ``+`` 拼回去
+    会把 ``capabilities and`` + ``more`` 粘成 ``capabilities andmore`` —— 这串同样会
+    原样进 TTS，读出来就是一个不存在的词。中文两侧不补空格（中文本来就不分词）。
+    """
+    if _breakable(left, right):
+        return left + right
+    return left + " " + right
+
+
 def _split_at_spaces(text: str, max_len: int) -> list[str]:
-    """Split long text at space boundaries to protect English words."""
+    """Split long text at space boundaries, keeping multi-word Latin terms whole.
+
+    These boundaries are not only subtitle cuts: ``segment_narration`` joins the
+    result with ``\\n`` and that is what goes to TTS, where each line is a hard
+    segment boundary. Cutting between two Latin words therefore breaks the term
+    apart in the *audio* — Minimax loses both the liaison and the context that
+    told it this was English at all.
+
+    实测(2026-09-20): ``最近刷爆科技圈的 AI Agent，`` 是 18 字、超过 16 的上限，而这
+    段里仅有的两个空格都在 "AI Agent" 中间,于是旧实现只能从词组中间下刀,切成
+    ``最近刷爆科技圈的 AI`` + ``Agent，`` —— 合成出来 "AI" 收在上一段末尾、"Agent"
+    孤零零起一段,那个词就读不准了。同句末尾的 "Agent Loop。" 因为没超上限反而完好,
+    用户听到的正是"中间那个 Agent 不对"。
+
+    所以断点优先选**中文↔拉丁**边界(回退到词组之前),找不到再退回"就近断开"。
+    纯英文旁白里根本不存在中文↔拉丁边界,每个断点都会走回退分支,行为与旧实现逐字
+    相同 —— picture-book-en 这类全英文模板不受影响。
+    """
     if len(text) <= max_len:
         return [text]
+
     parts: list[str] = []
-    current = ""
+    buf: list[str] = []  # 当前段已收的 token
     for word in text.split(" "):
-        candidate = f"{current} {word}" if current else word
-        if len(candidate) > max_len and current:
-            parts.append(current)
-            current = word
-        else:
-            current = candidate
-    if current:
-        parts.append(current)
+        if buf and len(" ".join(buf + [word])) > max_len:
+            # 从最靠后的边界往回找第一个安全断点;整段都没有就按旧行为就近断开。
+            cut = len(buf)
+            for i in range(len(buf), 0, -1):
+                following = word if i == len(buf) else buf[i]
+                if _breakable(buf[i - 1], following):
+                    cut = i
+                    break
+            parts.append(" ".join(buf[:cut]))
+            buf = buf[cut:]
+        buf.append(word)
+    if buf:
+        parts.append(" ".join(buf))
     return parts
 
 
@@ -83,17 +132,17 @@ def _merge_short(segments: list[str], min_len: int) -> list[str]:
         prev_is_sentence_end = bool(_PRIMARY_TAIL.search(merged[-1]))
         if len(merged[-1]) < min_len:
             # Previous fragment is short — always merge forward into it
-            merged[-1] += seg
+            merged[-1] = _concat_segments(merged[-1], seg)
         elif len(seg) < min_len and not prev_is_sentence_end:
             # Current fragment is short and prev is NOT a sentence end — merge backward
-            merged[-1] += seg
+            merged[-1] = _concat_segments(merged[-1], seg)
         else:
             # Either both are long enough, or seg is short but prev ends a sentence
             merged.append(seg)
     # Handle trailing short segment (avoid merging across sentence boundary)
     if len(merged) > 1 and len(merged[-1]) < min_len:
         if not _PRIMARY_TAIL.search(merged[-2]):
-            merged[-2] += merged.pop()
+            merged[-2] = _concat_segments(merged[-2], merged.pop())
     return merged
 
 

package/skills/template-registry/video_dsl/schema/video-dsl-v1alpha1.json

@@ -44,11 +44,6 @@
       "properties": {
         "title": { "type": "string" },
         "topic": { "type": "string" },
-        "platform": {
-          "type": "string",
-          "enum": ["douyin", "xiaohongshu", "bilibili", "wechat", "youtube", "generic"],
-          "default": "generic"
-        },
         "targetDuration": {
           "type": "number",
           "description": "目标总时长（秒）"
@@ -95,7 +90,8 @@
           "properties": {
             "voiceId": { "type": "string", "description": "Minimax 音色 ID" },
             "voiceName": { "type": "string" },
-            "speed": { "type": "number", "default": 1.0 }
+            "speed": { "type": "number", "default": 1.0 },
+            "languageBoost": { "type": "string", "description": "TTS 语种提示（auto / Chinese / English …）。中英混排的旁白不给提示时，英文词容易被按中文音系读出来；留空由服务端取默认值。" }
           }
         },
         "bgm": {
@@ -250,7 +246,8 @@
                   "description": "每行一个卡片的叙述句。长度必须等于 templateData 里对应数组（concepts/pillars/eras/items）的长度"
                 },
                 "outro": { "type": "string", "description": "可选：收尾句（此期间无卡片高亮）" },
-                "assetRef": { "type": "string", "description": "旁白音频 assetId" }
+                "assetRef": { "type": "string", "description": "旁白音频 assetId" },
+                "languageBoost": { "type": "string", "description": "TTS 语种提示（auto / Chinese / English …）。中英混排的旁白不给提示时，英文词容易被按中文音系读出来；覆盖 global.narration 的同名字段；留空则跟随全局/服务端默认。" }
               }
             },
             "bgm": {