@remixmate/cli 0.9.13 → 0.9.14

package/dist/handlers/gen-digital-human.js

@@ -91,6 +91,7 @@ export async function genDigitalHuman(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl: input.api_base_url,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     // ── Mode 1: list avatars ────────────────────────────────────────────────
     if (isTrue(input.list_avatars)) {

package/dist/handlers/gen-image.js

@@ -90,6 +90,7 @@ export async function genImage(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     emitProgress({ phase: 'gen-image:request', model, size, n });
     const data = await mmPost(ctx, '/model/genImg', payload, { timeoutMs: 120_000 });

package/dist/handlers/gen-video.js

@@ -85,6 +85,7 @@ export async function genVideo(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     const payload = {
         model,

package/dist/handlers/gen-voice.js

@@ -56,6 +56,7 @@ export async function genVoice(input, ctxIn) {
         const ctx = await resolveHttpContext(ctxIn.skillName, {
             apiBaseUrl: input.api_base_url,
             privateToken: input.priv_token,
+            preflightToken: ctxIn.auth?.token,
         });
         return listVoicesRemote(ctx);
     }
@@ -74,6 +75,7 @@ export async function genVoice(input, ctxIn) {
     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 });

package/dist/handlers/index.d.ts

@@ -4,10 +4,17 @@
  * Only `entry.type` in ('http' | 'builtin') uses this registry; python
  * skills go through spawn() in runner.ts and bypass handlers entirely.
  */
+import type { AuthPreflight } from '../auth/ensure.js';
 export type HandlerInput = Record<string, unknown>;
 export interface HandlerContext {
     /** ISO-style skill name from the registry (e.g. `gen-image`). Used for x-invoke-skill. */
     skillName: string;
+    /**
+     * Credential resolved by the dispatcher's preflight (runner.ts). Handlers pass
+     * `auth.token` into resolveHttpContext so the device flow can't run twice for
+     * a single invocation.
+     */
+    auth?: AuthPreflight;
 }
 export type SkillHandler = (input: HandlerInput, ctx: HandlerContext) => Promise<void>;
 export declare const HANDLERS: Record<string, SkillHandler>;

package/dist/http.d.ts

@@ -15,13 +15,18 @@
  * Base URL resolution:
  *   1. opts.apiBaseUrl                  — caller override
  *   2. process.env.MM_API_BASE_URL      — process env (point at local/staging here)
- *   3. https://api.remixmate.com/api    — production default (zero-config)
+ *   3. process.env.MM_BACKEND_API_URL   — ab-agent's convention (back-compat)
+ *   4. https://api.remixmate.com/api    — production default (zero-config)
+ */
+export { SkillError, EXIT } from './errors.js';
+/**
+ * Resolve the ab-api base URL the same way for authenticated and device-flow calls.
+ *
+ * `MM_BACKEND_API_URL` is honored because several Python skills already fall back
+ * to it (registry_loader, render_job_client, _vod_polling). Since runner.ts now
+ * injects the resolved base URL into those child processes, leaving it out here
+ * would let a prod default silently override an ab-agent-injected backend.
  */
-export declare class SkillError extends Error {
-    readonly exitCode: number;
-    constructor(message: string, exitCode?: number);
-}
-/** Resolve the ab-api base URL the same way for authenticated and device-flow calls. */
 export declare function resolveApiBaseUrl(flag?: string): string;
 export interface HttpContext {
     apiBaseUrl: string;
@@ -33,6 +38,12 @@ export interface HttpContext {
 export declare function resolveHttpContext(skillName: string, opts?: {
     apiBaseUrl?: string;
     privateToken?: string;
+    /**
+     * Token already resolved by the dispatcher's auth preflight (runner.ts).
+     * Reusing it avoids a second credential-store read — and, more importantly,
+     * a second device-flow attempt — per skill invocation.
+     */
+    preflightToken?: string;
 }): Promise<HttpContext>;
 export interface MmResponse<T = unknown> {
     code: number;

package/dist/http.js

@@ -15,26 +15,36 @@
  * Base URL resolution:
  *   1. opts.apiBaseUrl                  — caller override
  *   2. process.env.MM_API_BASE_URL      — process env (point at local/staging here)
- *   3. https://api.remixmate.com/api    — production default (zero-config)
+ *   3. process.env.MM_BACKEND_API_URL   — ab-agent's convention (back-compat)
+ *   4. https://api.remixmate.com/api    — production default (zero-config)
  */
 import { resolvePrivToken, NOT_AUTHENTICATED_HINT } from './auth/resolve.js';
 import { attemptAutoLogin } from './auth/auto-login.js';
+import { EXIT, SkillError } from './errors.js';
 const DEFAULT_API_BASE_URL = 'https://api.remixmate.com/api';
-export class SkillError extends Error {
-    exitCode;
-    constructor(message, exitCode = 1) {
-        super(message);
-        this.exitCode = exitCode;
-        this.name = 'SkillError';
-    }
-}
-/** Resolve the ab-api base URL the same way for authenticated and device-flow calls. */
+// Re-exported so the many `import { SkillError } from '../http.js'` call sites
+// stay valid; the definition moved to errors.ts to break an import cycle with
+// the auth gateway (see errors.ts).
+export { SkillError, EXIT } from './errors.js';
+/**
+ * Resolve the ab-api base URL the same way for authenticated and device-flow calls.
+ *
+ * `MM_BACKEND_API_URL` is honored because several Python skills already fall back
+ * to it (registry_loader, render_job_client, _vod_polling). Since runner.ts now
+ * injects the resolved base URL into those child processes, leaving it out here
+ * would let a prod default silently override an ab-agent-injected backend.
+ */
 export function resolveApiBaseUrl(flag) {
-    return (flag ?? process.env.MM_API_BASE_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+    const fromEnv = (process.env.MM_API_BASE_URL ?? '').trim() || (process.env.MM_BACKEND_API_URL ?? '').trim();
+    return ((flag ?? '').trim() || fromEnv || DEFAULT_API_BASE_URL).replace(/\/+$/, '');
 }
 export async function resolveHttpContext(skillName, opts = {}) {
     const apiBaseUrl = resolveApiBaseUrl(opts.apiBaseUrl);
-    let resolved = await resolvePrivToken({ flag: opts.privateToken, apiBaseUrl });
+    // An explicit --token flag still wins over the preflight result.
+    let resolved = await resolvePrivToken({
+        flag: opts.privateToken ?? opts.preflightToken,
+        apiBaseUrl,
+    });
     // Only when flag/env/store are all empty do we try automatic browser auth.
     // attemptAutoLogin self-gates (cloud env / headless / disabled → returns null
     // immediately), so the env-injected path never reaches it (zero regression).
@@ -42,7 +52,7 @@ export async function resolveHttpContext(skillName, opts = {}) {
         resolved = await attemptAutoLogin(apiBaseUrl);
     }
     if (!resolved) {
-        throw new SkillError(NOT_AUTHENTICATED_HINT);
+        throw new SkillError(NOT_AUTHENTICATED_HINT, EXIT.NOT_AUTHENTICATED);
     }
     return {
         apiBaseUrl,
@@ -83,15 +93,24 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
     }
     catch (err) {
         if (err instanceof Error && err.name === 'AbortError') {
-            throw new SkillError(`❌ request timed out: ${url}`);
+            throw new SkillError(`❌ request timed out: ${url}`, EXIT.BACKEND_UNREACHABLE);
         }
-        throw new SkillError(`❌ network error: ${err.message}`);
+        throw new SkillError(`❌ network error: ${err.message}`, EXIT.BACKEND_UNREACHABLE);
     }
     finally {
         clearTimeout(timeout);
     }
     const text = await resp.text();
     if (!resp.ok) {
+        // 401/403 is not a generic API failure — it means the credential is missing,
+        // expired or revoked. Surfacing it as such (with exit code 4) is what lets a
+        // host offer to re-authorize instead of reporting an opaque backend error.
+        if (resp.status === 401 || resp.status === 403) {
+            throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 HTTP ${resp.status}）`, EXIT.NOT_AUTHENTICATED);
+        }
+        if (resp.status >= 500) {
+            throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`, EXIT.BACKEND_UNREACHABLE);
+        }
         throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`);
     }
     let parsed;
@@ -102,6 +121,11 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
         throw new SkillError(`❌ failed to parse response, body is not JSON: ${text.slice(0, 200)}`);
     }
     if (parsed.code !== 0) {
+        // ab-api reports auth failures in the envelope (HTTP 200 + code=401), so the
+        // business-code path needs the same 401 → "re-authorize" mapping as above.
+        if (parsed.code === 401 || parsed.code === 403) {
+            throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 code=${parsed.code}${parsed.msg ? `: ${parsed.msg}` : ''}）`, EXIT.NOT_AUTHENTICATED);
+        }
         throw new SkillError(`❌ API returned a business error: ${parsed.msg ?? 'unknown error'} (code=${parsed.code})`);
     }
     return parsed.data ?? undefined;

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.13",
-  "generatedAt": "2026-08-12T07:37:17.101Z",
+  "version": "0.9.14",
+  "generatedAt": "2026-08-12T07:37:21.011Z",
   "skills": [
     {
       "id": "export-jianying",

package/dist/registry.d.ts

@@ -5,15 +5,17 @@
  * the build-time manifest generator and smoke test). A record that fails
  * validation is skipped with a warning rather than crashing the whole CLI.
  */
-import { type SkillEntry } from './skill-schema.js';
+import { type SkillAuthMode, type SkillEntry } from './skill-schema.js';
 export declare const SKILLS_DIR: string;
-export type { SkillEntry } from './skill-schema.js';
+export type { SkillEntry, SkillAuthMode } from './skill-schema.js';
 export interface SkillDef {
     name: string;
     toolName: string;
     description: string;
     parameters: Record<string, unknown>;
     entry: SkillEntry;
+    /** Authorization requirement enforced by the dispatcher before invocation. */
+    auth: SkillAuthMode;
     skillDir: string;
     /** Absolute path to the python entry script (only when entry.type === 'python'). */
     scriptAbsolutePath?: string;

package/dist/registry.js

@@ -8,7 +8,7 @@
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { normalizeEntry, validateSkillJson, } from './skill-schema.js';
+import { normalizeEntry, resolveAuthMode, validateSkillJson, } from './skill-schema.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
 function loadOne(skillDir) {
@@ -37,6 +37,7 @@ function loadOne(skillDir) {
         description: raw.description,
         parameters: raw.parameters ?? {},
         entry,
+        auth: resolveAuthMode(raw),
         skillDir,
     };
     if (entry.type === 'python') {

package/dist/runner.d.ts

@@ -3,6 +3,10 @@
  *   - spawn `python3 <scriptAbsolutePath> --flag value ...` (entry.type === 'python')
  *   - call a TS handler from handlers/ (entry.type === 'http' | 'builtin')
  *
+ * Authorization happens HERE, once, before either path — see auth/ensure.ts for
+ * why. Python children receive the resolved credential through their environment
+ * and never read the credential store themselves.
+ *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
 import type { ParsedArgs } from './argv.js';

package/dist/runner.js

@@ -3,26 +3,41 @@
  *   - spawn `python3 <scriptAbsolutePath> --flag value ...` (entry.type === 'python')
  *   - call a TS handler from handlers/ (entry.type === 'http' | 'builtin')
  *
+ * Authorization happens HERE, once, before either path — see auth/ensure.ts for
+ * why. Python children receive the resolved credential through their environment
+ * and never read the credential store themselves.
+ *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { findSkill, SKILLS_DIR } from './registry.js';
 import { HANDLERS } from './handlers/index.js';
-import { SkillError } from './http.js';
+import { EXIT, SkillError } from './errors.js';
+import { authChildEnv, ensureAuth } from './auth/ensure.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;
+    return typeof value === 'string' ? value : undefined;
+}
 export async function runSkill(skillName, opts) {
     const skill = findSkill(skillName, opts.baseDir ?? SKILLS_DIR);
     if (!skill) {
         process.stderr.write(`❌ skill not found: ${skillName}\n`);
-        return 2;
+        return EXIT.USAGE;
     }
     try {
+        const auth = await ensureAuth({
+            mode: skill.auth,
+            apiBaseUrl: typeof opts.parsedArgs.api_base_url === 'string' ? opts.parsedArgs.api_base_url : undefined,
+            flagToken: tokenFlag(opts.parsedArgs),
+        });
         switch (skill.entry.type) {
             case 'python':
-                return await runPython(skill, opts.rawArgs);
+                return await runPython(skill, opts.rawArgs, auth);
             case 'http':
             case 'builtin':
-                return await runHandler(skill, opts.parsedArgs);
+                return await runHandler(skill, opts.parsedArgs, auth);
         }
     }
     catch (err) {
@@ -31,10 +46,10 @@ export async function runSkill(skillName, opts) {
             return err.exitCode;
         }
         process.stderr.write(`❌ unexpected error: ${err.message}\n`);
-        return 1;
+        return EXIT.ERROR;
     }
 }
-async function runPython(skill, rawArgs) {
+async function runPython(skill, rawArgs, auth) {
     if (!skill.scriptAbsolutePath) {
         throw new SkillError(`skill ${skill.name} has entry.type=python but no scriptAbsolutePath`);
     }
@@ -43,21 +58,21 @@ async function runPython(skill, rawArgs) {
         const proc = spawn('python3', [skill.scriptAbsolutePath, ...rawArgs], {
             cwd,
             stdio: 'inherit',
-            env: { ...process.env, PYTHONUNBUFFERED: '1' },
+            env: { ...process.env, ...authChildEnv(auth), PYTHONUNBUFFERED: '1' },
         });
-        proc.on('exit', (code) => resolve(code ?? 1));
+        proc.on('exit', (code) => resolve(code ?? EXIT.ERROR));
         proc.on('error', (err) => {
             process.stderr.write(`❌ failed to spawn python3: ${err.message}\n`);
-            resolve(127);
+            resolve(EXIT.SPAWN_FAILED);
         });
     });
 }
-async function runHandler(skill, args) {
+async function runHandler(skill, args, auth) {
     const handlerKey = skill.entry.handler;
     const handler = HANDLERS[handlerKey];
     if (!handler) {
         throw new SkillError(`handler not registered: ${handlerKey} (skill ${skill.name})`);
     }
-    await handler(args, { skillName: skill.name });
-    return 0;
+    await handler(args, { skillName: skill.name, auth });
+    return EXIT.OK;
 }

package/dist/skill-schema.d.ts

@@ -38,6 +38,14 @@ export type SkillEntry = {
  */
 export type SkillCategory = 'authoring' | 'consuming' | 'asset' | 'meta';
 export declare const CATEGORY_VALUES: readonly ["authoring", "consuming", "asset", "meta"];
+/**
+ * Authorization requirement — consumed by the dispatcher's auth preflight.
+ * Semantics are documented on `AuthMode` in src/auth/ensure.ts (kept there so
+ * the runtime behavior and its description live together); this file only owns
+ * the literal values and their validation.
+ */
+export type SkillAuthMode = 'required' | 'optional' | 'none';
+export declare const AUTH_VALUES: readonly ["required", "optional", "none"];
 export interface RawSkillJson {
     name: string;
     toolName: string;
@@ -45,11 +53,22 @@ export interface RawSkillJson {
     title?: string;
     tier?: string;
     category?: SkillCategory;
+    auth?: SkillAuthMode;
     parameters?: Record<string, unknown>;
     scriptPath?: string;
     entry?: SkillEntry;
     envVars?: string[];
 }
+/**
+ * Resolve a skill's auth mode, defaulting for records that predate the field.
+ *
+ * The default is derived from `envVars` rather than hardcoded to `'required'`:
+ * a skill that never declared PRIV_TOKEN cannot possibly need a credential, and
+ * defaulting it to `required` would make a purely local skill (web-screenshot)
+ * pop a browser. Every skill shipped in this package declares `auth` explicitly,
+ * so this only covers externally supplied skill dirs (SKILL_BASE_DIR).
+ */
+export declare function resolveAuthMode(raw: Pick<RawSkillJson, 'auth' | 'envVars'>): SkillAuthMode;
 export declare const TIER_VALUES: readonly ["atomic", "orchestration", "tool"];
 export declare const REQUIRED_SKILL_JSON_FIELDS: readonly ["name", "tier", "title", "description"];
 /**

package/dist/skill-schema.js

@@ -12,6 +12,21 @@
  * the build treats them as fatal.
  */
 export const CATEGORY_VALUES = ['authoring', 'consuming', 'asset', 'meta'];
+export const AUTH_VALUES = ['required', 'optional', 'none'];
+/**
+ * Resolve a skill's auth mode, defaulting for records that predate the field.
+ *
+ * The default is derived from `envVars` rather than hardcoded to `'required'`:
+ * a skill that never declared PRIV_TOKEN cannot possibly need a credential, and
+ * defaulting it to `required` would make a purely local skill (web-screenshot)
+ * pop a browser. Every skill shipped in this package declares `auth` explicitly,
+ * so this only covers externally supplied skill dirs (SKILL_BASE_DIR).
+ */
+export function resolveAuthMode(raw) {
+    if (raw.auth)
+        return raw.auth;
+    return raw.envVars?.includes('PRIV_TOKEN') ? 'required' : 'none';
+}
 export const TIER_VALUES = ['atomic', 'orchestration', 'tool'];
 export const REQUIRED_SKILL_JSON_FIELDS = ['name', 'tier', 'title', 'description'];
 /**
@@ -43,6 +58,9 @@ export function validateSkillJson(raw, skillId) {
     if (raw.category != null && !CATEGORY_VALUES.includes(raw.category)) {
         errors.push(`skill.json.category must be one of ${CATEGORY_VALUES.join(' | ')}, got '${raw.category}'`);
     }
+    if (raw.auth != null && !AUTH_VALUES.includes(raw.auth)) {
+        errors.push(`skill.json.auth must be one of ${AUTH_VALUES.join(' | ')}, got '${raw.auth}'`);
+    }
     if (raw.name && raw.name !== skillId) {
         errors.push(`skill.json.name='${raw.name}' does not match directory name '${skillId}'`);
     }

package/dist/text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Terminal text helpers shared by the human-facing commands.
+ */
+/**
+ * Pad to a target terminal width. CJK characters occupy two columns but count as
+ * one code unit, so String.padEnd misaligns any column that contains them.
+ */
+export declare function padDisplay(text: string, width: number): string;

package/dist/text.js

@@ -0,0 +1,15 @@
+/**
+ * Terminal text helpers shared by the human-facing commands.
+ */
+// Ranges covering the CJK / fullwidth blocks the CLI's Chinese output uses.
+const WIDE = /[ᄀ-ᅟ⺀-䳿一-鿿가-힣豈-﫿︰-﹏＀-｠￠-￦]/;
+/**
+ * Pad to a target terminal width. CJK characters occupy two columns but count as
+ * one code unit, so String.padEnd misaligns any column that contains them.
+ */
+export function padDisplay(text, width) {
+    let cols = 0;
+    for (const ch of text)
+        cols += WIDE.test(ch) ? 2 : 1;
+    return text + ' '.repeat(Math.max(1, width - cols));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.13",
+  "version": "0.9.14",
   "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",
@@ -21,7 +21,7 @@
     "smoke": "node scripts/smoke.mjs",
     "test:cli": "npm run build && node --test test/*.test.mjs",
     "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
-    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-template-pipeline.py",
+    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.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/export-jianying/skill.json

@@ -5,6 +5,7 @@
   "category": "consuming",
   "title": "Jianying (CapCut) Draft Export",
   "description": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. Supports automatic conversion from a RenderPlan.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
   "scriptPath": "scripts/gen_jianying_draft.py",
   "parameters": {

package/skills/gen-digital-human/skill.json

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "Digital-Human Talking-Head",
   "description": "Digital-human video: list available avatars; produce a talking-head video from text via TTS, or drive an avatar from an existing audio URL.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
   "entry": { "type": "http", "handler": "gen-digital-human" },
   "parameters": {

package/skills/gen-image/skill.json

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "AI Image Generation",
   "description": "AI image generation: produce an image from a text prompt. Supports Seedream and Gemini models, plus image-to-image with reference images.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME", "MM_IMAGE_MODEL"],
   "entry": { "type": "http", "handler": "gen-image" },
   "parameters": {

package/skills/gen-script/skill.json

@@ -5,6 +5,7 @@
   "category": "authoring",
   "title": "Video Script Generation",
   "description": "Video script generation: turn a topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.",
+  "auth": "none",
   "envVars": ["DEFAULT_IMAGE_MODEL", "DEFAULT_VIDEO_MODEL", "STUB_IMAGE_URL", "STUB_VIDEO_URL"],
   "scriptPath": "scripts/gen_script.py",
   "parameters": {

package/skills/gen-video/skill.json

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "AI Video Generation",
   "description": "AI video generation: produce a short video clip from a text prompt. Supports Seedance and Veo models, plus first/last frame and reference images.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME", "MM_VIDEO_MODEL"],
   "entry": { "type": "http", "handler": "gen-video" },
   "parameters": {

package/skills/gen-voice/skill.json

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "Text-to-Speech (Minimax)",
   "description": "Text-to-speech (TTS): synthesize narration audio from text via the Minimax TTS model. Returns the persisted audio URL — no download needed.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
   "entry": { "type": "http", "handler": "gen-voice" },
   "parameters": {

package/skills/prepare-video-assets/skill.json

@@ -5,6 +5,7 @@
   "category": "authoring",
   "title": "Video Asset Preparation",
   "description": "Resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a job_id for the subsequent render_video call. This is Phase 1 of the two-phase video pipeline; Phase 3 (Remotion render) lives in render_video.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "MM_BACKEND_API_URL", "AGENT_NAME", "REMOTION_RENDER_API_URL", "REMOTION_RENDER_MODE", "REMOTION_OUTPUT_DIR", "ASSET_CACHE_DIR"],
   "scriptPath": "scripts/prepare_video_assets.py",
   "parameters": {

package/skills/render-video/skill.json

@@ -5,6 +5,7 @@
   "category": "authoring",
   "title": "Remotion Video Renderer",
   "description": "Loads a persisted RenderPlan by job_id and drives the Remotion engine to produce the final video. Assets must already be generated via prepare_video_assets — this skill never resolves or regenerates assets.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "MM_BACKEND_API_URL", "AGENT_NAME", "REMOTION_RENDER_API_URL", "REMOTION_RENDER_MODE", "REMOTION_OUTPUT_DIR", "ASSET_CACHE_DIR"],
   "scriptPath": "scripts/render_video.py",
   "parameters": {

package/skills/template-registry/scripts/list_templates.py

@@ -39,7 +39,13 @@ from pathlib import Path
 
 # When run as `python3 <skillDir>/scripts/list_templates.py`, this script's own
 # directory is sys.path[0], so the sibling shared modules import directly.
-from registry_loader import list_templates as load_visible_templates  # noqa: E402
+from registry_loader import (  # noqa: E402
+    EXIT_BACKEND_UNREACHABLE,
+    EXIT_NOT_AUTHENTICATED,
+    RegistryAuthError,
+    RegistryUnreachableError,
+    list_templates as load_visible_templates,
+)
 
 
 def _matches(tpl: dict, tag: str | None, aspect: str | None, language: str | None) -> bool:
@@ -166,6 +172,15 @@ def main() -> None:
 
     try:
         templates = load_visible_templates()
+    except RegistryAuthError as exc:
+        # 退出码 4 = 需要授权（见 registry_loader.EXIT_NOT_AUTHENTICATED），宿主
+        # 据此引导用户重新登录，而不是把它当成一次普通失败。
+        print(f"❌ {exc}", file=sys.stderr)
+        sys.exit(EXIT_NOT_AUTHENTICATED)
+    except RegistryUnreachableError as exc:
+        # 退出码 5 = 后端不可达；重试或修配置即可，不需要重新登录。
+        print(f"❌ {exc}", file=sys.stderr)
+        sys.exit(EXIT_BACKEND_UNREACHABLE)
     except RuntimeError as exc:
         print(f"❌ {exc}", file=sys.stderr)
         sys.exit(1)