@remixmate/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aibearer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# @remixmate/cli
+
+> 原名 `ab-skill-cli`（bin `ab-skill`），现已更名为 **`@remixmate/cli`**（bin **`remixmate`**）。旧包已在 npm 标记弃用，请迁移到新包。
+
+AI media generation skills for Claude Code / Codex.
+
+9 skills covering the full short-video production pipeline: image / video / voice / digital-human asset generation, script planning, template binding, Remotion rendering, and Jianying (CapCut) draft export.
+
+## Install
+
+```bash
+npm install -g @remixmate/cli
+remixmate --help
+remixmate --list
+```
+
+## Use in Claude Code
+
+Copy the bundled `skills/` into your project-level or global `.claude/skills/` directory and Claude Code will pick them up:
+
+```bash
+# project-level
+mkdir -p .claude/skills
+cp -R "$(npm root -g)/@remixmate/cli/skills/." .claude/skills/
+
+# or global
+mkdir -p ~/.claude/skills
+cp -R "$(npm root -g)/@remixmate/cli/skills/." ~/.claude/skills/
+```
+
+## Use in Codex
+
+Codex does not load `SKILL.md` natively. Tell Codex about the CLI in your system prompt and let it invoke `remixmate <skill> ...` when it needs media generation:
+
+> When you need AI media generation (image / video / voice / talking-head / Jianying export), prefer running `remixmate <skill-id> --help` first to discover the flags, then `remixmate <skill-id> --json-output ...` to execute. Available skills: `remixmate --list`.
+
+See the full intro page (Claude Code / Codex setup, env vars, end-to-end workflow examples) at the project homepage.
+
+## Environment
+
+Most skills authenticate against ab-api with a `PRIV_TOKEN`. Without a valid token (and network access to ab-api) the template / media-generation skills are unavailable — the code is open-source, but the generation capabilities are hosted on the ab-api service. Copy `.env.example` to `.env` and source it before running:
+
+```bash
+cp .env.example .env
+# edit values
+source .env
+```
+
+Python skills (6 of 9) require `python3 >= 3.10`. `video-parser` additionally requires `ffmpeg`.
+
+---
+
+## AI 媒体生成 Agent Skills（中文）
+
+本项目包含 9 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
+
+### 技能分层
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 编排层 Skills                                                │
+│  gen-script           主题 → Video DSL（脚本生成）           │
+│  template-bind        DSL → TemplateBinding（模板列表）      │
+│  prepare-video-assets DSL + Binding → 素材补齐（Phase 1）    │
+│  render-video         RenderPlan → Remotion 渲染（Phase 3）  │
+│  export-jianying      素材 → 剪映草稿 ZIP                    │
+├─────────────────────────────────────────────────────────────┤
+│ 原子层 Skills                                                │
+│  gen-image         文生图 / 图生图（Seedream / Gemini）      │
+│  gen-video         文生视频（Seedance / Veo）                │
+│  gen-voice         语音合成（Minimax TTS）                   │
+│  gen-digital-human 数字人口播（即梦 / 飞影）                 │
+├─────────────────────────────────────────────────────────────┤
+│ 工具层 Skills                                                │
+│  video-parser      视频解构（音频提取 / ASR / 关键帧）       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 目录结构
+
+```
+├── docs/
+│   └── video-production-architecture.md   # 架构文档
+├── skills/
+│   ├── gen-image/              # 原子: AI 生图
+│   ├── gen-video/              # 原子: AI 生视频
+│   ├── gen-voice/              # 原子: 语音合成
+│   ├── gen-digital-human/      # 原子: 数字人口播
+│   ├── gen-script/             # 编排: 主题 → Video DSL
+│   ├── template-bind/          # 编排: 模板列表（含模板注册表 + DSL Schema）
+│   ├── prepare-video-assets/   # 编排: Phase 1 素材准备（thin wrapper）
+│   ├── render-video/           # 编排: Phase 3 Remotion 渲染（含 render_video.py 实现）
+│   ├── export-jianying/        # 编排: 导出剪映草稿 ZIP
+│   └── video-parser/           # 工具: 视频解构与分析
+└── README.md
+```
+
+### 技能说明
+
+| 技能 | 类型 | 说明 | 核心脚本 |
+|------|------|------|----------|
+| gen-image | 原子 | 文生图 / 图生图（Seedream、Gemini） | `gen_image.py` |
+| gen-video | 原子 | 文生视频（Seedance、Veo） | `gen_video.py` |
+| gen-voice | 原子 | 语音合成（Minimax TTS） | `gen_voice.py` |
+| gen-digital-human | 原子 | 数字人口播（即梦 / 飞影） | `gen_digital_human_video.py` |
+| gen-script | 编排 | 主题 → Video DSL JSON | `gen_script.py` |
+| template-bind | 编排 | 模板列表（绑定逻辑内嵌于 prepare-video-assets） | `match_template.py` |
+| prepare-video-assets | 编排 | DSL + Binding → 素材补齐 → 落库 RenderPlan | `render_video.py --resolve-only`（wrapper） |
+| render-video | 编排 | job_id → Remotion 渲染 → 上传 | `render_video.py` |
+| export-jianying | 编排 | 素材 URL → 剪映草稿 ZIP（支持从 RenderPlan 自动转换） | `gen_jianying_draft.py` |
+| video-parser | 工具 | 视频 → 音频 + ASR + 关键帧 + 场景分段 | `deconstruct_video.py` |
+
+### 核心链路
+
+详见 [视频内容生产架构文档](docs/video-production-architecture.md) 和 [编排流程指南](docs/orchestration-guide.md)。
+
+**链路 A：主题 → Remotion 视频**
+```
+gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
+→ ✅用户确认素材 → render-video(--job-id) → MP4
+```
+
+**链路 B：主题 → 剪映草稿**
+```
+gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
+→ ✅用户确认素材 → export-jianying(--from-job-id) → 剪映 ZIP
+```
+
+### 测试
+
+```bash
+# 各脚本 --help 可正常运行
+python3 skills/gen-image/scripts/gen_image.py --help
+python3 skills/gen-video/scripts/gen_video.py --help
+python3 skills/gen-voice/scripts/gen_voice.py --help
+python3 skills/gen-digital-human/scripts/gen_digital_human_video.py --help
+python3 skills/gen-script/scripts/gen_script.py --help
+python3 skills/template-bind/scripts/match_template.py --help
+python3 skills/render-video/scripts/render_video.py --help
+python3 skills/prepare-video-assets/scripts/prepare_video_assets.py --help
+python3 skills/export-jianying/scripts/gen_jianying_draft.py --help
+python3 skills/video-parser/scripts/deconstruct_video.py --help
+
+# 查看可用音色
+python3 skills/gen-voice/scripts/gen_voice.py --list-voices
+
+# 查看可用模板
+python3 skills/template-bind/scripts/match_template.py --list-templates
+```
+
+### 开发流程
+
+- 克隆此项目到本地
+- 在 skills 目录下各技能文件夹中开发
+- 每个技能包含 `SKILL.md`（技能说明）、`version.json`（元数据）和 `scripts/`（脚本）
+
+### 快速体验
+
+```
+@skills/gen-image/SKILL.md 生成一张熊猫的图片，9:16，调用gemini 3.1，国画风 + 严格按该文档执行
+@skills/gen-video/SKILL.md 生成一段熊猫在竹林奔跑的视频，9:16，长度6秒，调用veo + 严格按该文档执行
+@skills/gen-voice/SKILL.md 生成一段语音，介绍熊猫的习性，大概100字左右 + 严格按该文档执行
+@skills/gen-digital-human/SKILL.md 获取数字人列表 + 严格按该文档执行
+@skills/template-bind/SKILL.md 获取模版列表 + 严格按该文档执行
+@skills/gen-script/SKILL.md 基于模版 image-slide，创作一个关于AI学习方法的视频 + 严格按该文档执行
+```

package/dist/argv.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Argv parser shared by cli.ts and python passthrough.
+ *
+ * Convention (matches ab-agent's buildCliArgs):
+ *   --foo-bar value     →  foo_bar: 'value'
+ *   --foo-bar           →  foo_bar: true
+ *   --foo-bar a --foo-bar b → foo_bar: ['a', 'b']
+ *   -p value            →  short flags also supported as-is (kebab → snake)
+ *
+ * Booleans are detected when the next token starts with '--' or is absent.
+ * Negative number values (-1.5) are NOT supported as flag values in this
+ * parser — Python skills handle them via argparse downstream when needed.
+ */
+export type ParsedArgs = Record<string, string | boolean | string[]>;
+export declare function parseArgv(argv: string[]): ParsedArgs;

package/dist/argv.js

@@ -0,0 +1,51 @@
+/**
+ * Argv parser shared by cli.ts and python passthrough.
+ *
+ * Convention (matches ab-agent's buildCliArgs):
+ *   --foo-bar value     →  foo_bar: 'value'
+ *   --foo-bar           →  foo_bar: true
+ *   --foo-bar a --foo-bar b → foo_bar: ['a', 'b']
+ *   -p value            →  short flags also supported as-is (kebab → snake)
+ *
+ * Booleans are detected when the next token starts with '--' or is absent.
+ * Negative number values (-1.5) are NOT supported as flag values in this
+ * parser — Python skills handle them via argparse downstream when needed.
+ */
+function flagToKey(flag) {
+    return flag.replace(/^--?/, '').replace(/-/g, '_');
+}
+export function parseArgv(argv) {
+    const out = {};
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (!token.startsWith('-')) {
+            i++;
+            continue;
+        }
+        const key = flagToKey(token);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            out[key] = true;
+            i++;
+            continue;
+        }
+        // Treat next token as value.
+        const existing = out[key];
+        if (existing === undefined) {
+            out[key] = next;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(next);
+        }
+        else if (typeof existing === 'string') {
+            out[key] = [existing, next];
+        }
+        else {
+            // Was boolean — overwrite (last write wins; unusual case)
+            out[key] = next;
+        }
+        i += 2;
+    }
+    return out;
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * remixmate CLI entrypoint.
+ *
+ *   remixmate --list                          list registered skills
+ *   remixmate <name> --help                   forward --help to underlying skill
+ *   remixmate <name> [--flag value ...]       invoke the skill
+ *
+ * For python skills (entry.type === 'python') we spawn the script and inherit
+ * its stdio so progress / errors flow through unchanged.
+ * For http / builtin skills we dispatch in-process to handlers/.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * remixmate CLI entrypoint.
+ *
+ *   remixmate --list                          list registered skills
+ *   remixmate <name> --help                   forward --help to underlying skill
+ *   remixmate <name> [--flag value ...]       invoke the skill
+ *
+ * For python skills (entry.type === 'python') we spawn the script and inherit
+ * its stdio so progress / errors flow through unchanged.
+ * For http / builtin skills we dispatch in-process to handlers/.
+ */
+import path from 'node:path';
+import { loadSkills, SKILLS_DIR } from './registry.js';
+import { parseArgv } from './argv.js';
+import { runSkill } from './runner.js';
+/**
+ * SKILL_BASE_DIR can arrive as a relative path (e.g. from a developer .env or
+ * from ab-agent's spawn env). The cli script's cwd isn't a stable anchor for
+ * that — it's whatever the caller set, often the bundled `skills-cli/`
+ * directory. Resolve against process.cwd() (= the caller's intended root) up
+ * front so any later existsSync / readdirSync call sees an absolute,
+ * predictable path.
+ */
+function resolveBaseDir() {
+    const raw = process.env.SKILL_BASE_DIR;
+    if (!raw)
+        return SKILLS_DIR;
+    return path.isAbsolute(raw) ? raw : path.resolve(process.cwd(), raw);
+}
+function describeEntryTail(s) {
+    if (s.entry.type === 'python') {
+        return `(scripts/${s.entry.scriptPath.replace(/^scripts\//, '')})`;
+    }
+    return `[${s.entry.handler}]`;
+}
+function printUsage() {
+    // Match runSkill: honor SKILL_BASE_DIR so `remixmate --help` and the
+    // subsequent `remixmate <name>` invocation list / run from the same tree.
+    const skills = loadSkills(resolveBaseDir());
+    process.stdout.write('Usage:\n');
+    process.stdout.write('  remixmate --list                      List all skills\n');
+    process.stdout.write('  remixmate <name> [--flag value ...]   Invoke a skill\n');
+    process.stdout.write('  remixmate <name> --help               Show skill-specific help\n');
+    process.stdout.write('\nAvailable skills:\n');
+    for (const s of skills) {
+        const summary = s.description.split('\n')[0].slice(0, 60);
+        process.stdout.write(`  ${s.name.padEnd(22)} ${s.entry.type.padEnd(8)} ${summary}\n`);
+    }
+}
+function printList() {
+    for (const s of loadSkills(resolveBaseDir())) {
+        process.stdout.write(`${s.name}\t${s.toolName}\t${s.entry.type}\t${describeEntryTail(s)}\n`);
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        printUsage();
+        process.exit(0);
+    }
+    if (argv[0] === '--list' || argv[0] === 'list') {
+        printList();
+        process.exit(0);
+    }
+    if (argv[0].startsWith('-')) {
+        process.stderr.write(`❌ unknown option: ${argv[0]}\n`);
+        printUsage();
+        process.exit(2);
+    }
+    const skillName = argv[0];
+    const rest = argv.slice(1);
+    const code = await runSkill(skillName, {
+        baseDir: resolveBaseDir(),
+        rawArgs: rest,
+        parsedArgs: parseArgv(rest),
+    });
+    process.exit(code);
+}
+main().catch((err) => {
+    process.stderr.write(`❌ fatal: ${err?.stack ?? err?.message ?? String(err)}\n`);
+    process.exit(1);
+});

package/dist/handlers/gen-image.d.ts

@@ -0,0 +1,13 @@
+/**
+ * gen-image handler — POST ab-api /model/genImg.
+ *
+ * Mirrors the previous `scripts/gen_image.py` behavior:
+ *   - Seedream models accept width/height (via SIZE_PRESETS lookup or WxH parse)
+ *   - Gemini models accept aspectRatio + size (1K/2K/4K)
+ *   - Reference images: HTTPS URLs and data: URIs pass through; local paths
+ *     are read and base64-encoded into a data: URI
+ *   - Async response (generationId + status:'generating'/'pending') is polled
+ *     against /model/getImgStatus until completed/failed/timeout
+ */
+import type { HandlerContext, HandlerInput } from './index.js';
+export declare function genImage(input: HandlerInput, ctxIn: HandlerContext): Promise<void>;

package/dist/handlers/gen-image.js

@@ -0,0 +1,161 @@
+/**
+ * gen-image handler — POST ab-api /model/genImg.
+ *
+ * Mirrors the previous `scripts/gen_image.py` behavior:
+ *   - Seedream models accept width/height (via SIZE_PRESETS lookup or WxH parse)
+ *   - Gemini models accept aspectRatio + size (1K/2K/4K)
+ *   - Reference images: HTTPS URLs and data: URIs pass through; local paths
+ *     are read and base64-encoded into a data: URI
+ *   - Async response (generationId + status:'generating'/'pending') is polled
+ *     against /model/getImgStatus until completed/failed/timeout
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { mmPost, pollUntil, resolveHttpContext, SkillError } from '../http.js';
+import { emitProgress } from '../progress.js';
+const DEFAULT_IMAGE_MODEL = 'doubao/doubao-seedream-5-0-260128';
+// Maps aspect-ratio shorthand → (width, height) for Seedream models.
+const SIZE_PRESETS = {
+    '1:1': [2048, 2048],
+    '16:9': [2848, 1600],
+    '9:16': [1600, 2848],
+    '4:3': [2304, 1728],
+    '3:4': [1728, 2304],
+    '2:3': [1664, 2496],
+};
+const MIME_BY_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+};
+// Per-model reference-image caps (matches ab-api validation).
+const SEEDREAM_REF_LIMIT = 14;
+const GEMINI_REF_LIMIT = 4;
+function isSeedreamModel(model) {
+    const lower = model.toLowerCase();
+    return lower.includes('seedream') || lower.includes('seedance');
+}
+function resolveImageInput(pathOrUrl) {
+    const trimmed = pathOrUrl.trim();
+    if (!trimmed)
+        return '';
+    const lower = trimmed.toLowerCase();
+    if (lower.startsWith('http://') || lower.startsWith('https://') || lower.startsWith('data:')) {
+        return trimmed;
+    }
+    if (!existsSync(trimmed) || !statSync(trimmed).isFile()) {
+        throw new SkillError(`❌ image path does not exist or is not a file: ${trimmed}`);
+    }
+    const ext = path.extname(trimmed).toLowerCase();
+    const mime = MIME_BY_EXT[ext] ?? 'image/jpeg';
+    const b64 = readFileSync(trimmed).toString('base64');
+    return `data:${mime};base64,${b64}`;
+}
+/** Coerce a CLI flag value (string|string[]|boolean) into an array of strings. */
+function toStringArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value))
+        return value.map(String);
+    return [String(value)];
+}
+function toNumber(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        throw new SkillError(`❌ ${name} must be a number, received: ${value}`);
+    return n;
+}
+/** Resolve {width, height} for Seedream from --size (preset key or WxH). */
+function resolveSeedreamSize(size) {
+    if (SIZE_PRESETS[size]) {
+        const [w, h] = SIZE_PRESETS[size];
+        return { width: w, height: h };
+    }
+    if (/^\d+x\d+$/i.test(size)) {
+        const [w, h] = size.toLowerCase().split('x').map((v) => parseInt(v, 10));
+        return { width: w, height: h };
+    }
+    throw new SkillError(`❌ Seedream model does not support size format: ${size} (use 1:1 / 9:16 / 16:9 ... or WxH like 1600x2848)`);
+}
+async function pollImageStatus(ctx, generationId) {
+    return pollUntil(async () => {
+        const data = await mmPost(ctx, '/model/getImgStatus', { generationId }, { timeoutMs: 30_000 });
+        const status = data.status ?? 'unknown';
+        emitProgress({ phase: 'gen-image:poll', generationId, status });
+        if (status === 'completed' || status === 'succeeded') {
+            return (data.imageUrls ?? []).filter((u) => !!u);
+        }
+        if (status === 'failed') {
+            const err = data.errorMsg ?? data.error ?? 'unknown error';
+            throw new SkillError(`❌ image generation failed: ${err}`);
+        }
+        return null;
+    }, { intervalMs: 5_000, timeoutMs: 120_000 });
+}
+export async function genImage(input, ctxIn) {
+    const prompt = input.prompt;
+    if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
+        throw new SkillError('❌ Please provide --prompt to describe the image');
+    }
+    const ctx = resolveHttpContext(ctxIn.skillName, {
+        apiBaseUrl: input.api_base_url,
+        privateToken: input.priv_token,
+    });
+    const model = input.model ?? process.env.MM_IMAGE_MODEL ?? DEFAULT_IMAGE_MODEL;
+    const size = input.size ?? '1:1';
+    const n = toNumber(input.n, 'n') ?? 1;
+    const resolution = input.resolution ?? '1K';
+    const seed = toNumber(input.seed, 'seed');
+    const imageStrength = toNumber(input.image_strength, 'image_strength');
+    const guidanceScale = toNumber(input.guidance_scale, 'guidance_scale');
+    const negativePrompt = input.negative_prompt;
+    // --watermark / --no-watermark — parseArgv only sees `--watermark true` style;
+    // when ab-agent's buildCliArgs passes booleans, only the truthy flag appears.
+    // Treat presence as true; explicit `--no-watermark` isn't supported here.
+    const watermark = input.watermark === true ? true : undefined;
+    const seedream = isSeedreamModel(model);
+    const references = toStringArray(input.reference).map(resolveImageInput).filter(Boolean);
+    const refLimit = seedream ? SEEDREAM_REF_LIMIT : GEMINI_REF_LIMIT;
+    if (references.length > refLimit) {
+        throw new SkillError(`❌ ${seedream ? 'Seedream' : 'Gemini'} model accepts at most ${refLimit} reference images, got ${references.length}`);
+    }
+    const payload = { model, prompt, imageCount: n };
+    if (guidanceScale !== undefined)
+        payload.guidanceScale = guidanceScale;
+    if (references.length > 0)
+        payload.referenceImages = references;
+    if (imageStrength !== undefined)
+        payload.imageStrength = imageStrength;
+    if (negativePrompt)
+        payload.negativePrompt = negativePrompt;
+    if (seed !== undefined)
+        payload.seed = seed;
+    if (watermark !== undefined)
+        payload.watermark = watermark;
+    if (seedream) {
+        Object.assign(payload, resolveSeedreamSize(size));
+    }
+    else {
+        payload.aspectRatio = size;
+        payload.size = resolution;
+    }
+    emitProgress({ phase: 'gen-image:request', model, size, n });
+    const data = await mmPost(ctx, '/model/genImg', payload, { timeoutMs: 120_000 });
+    let imageUrls = (data.imageUrls ?? []).filter((u) => !!u);
+    if (imageUrls.length === 0 && data.generationId && (data.status === 'generating' || data.status === 'pending')) {
+        emitProgress({ phase: 'gen-image:async', generationId: data.generationId });
+        imageUrls = await pollImageStatus(ctx, data.generationId);
+    }
+    if (imageUrls.length === 0) {
+        throw new SkillError(`❌ API response did not contain any image URL: ${JSON.stringify(data)}`);
+    }
+    process.stdout.write(`\n📸 Generated ${imageUrls.length} image(s)\n`);
+    process.stdout.write(`\n🔗 Image URLs (renders directly, no download needed):\n`);
+    for (const url of imageUrls)
+        process.stdout.write(`${url}\n`);
+    process.stdout.write(`\n🎉 Image generation done!\n`);
+}

package/dist/handlers/gen-voice.d.ts

@@ -0,0 +1,16 @@
+/**
+ * gen-voice handler — Minimax TTS via ab-api /tool/minimaxT2aV2.
+ *
+ * Operations:
+ *   --list-voices true                 → GET available voice IDs from /voice/page (live)
+ *   --list-voices true --local true    → print the built-in language-tagged
+ *                                        fallback catalog (offline, no API call)
+ *   default                            → synthesize text into an MP3 URL
+ *
+ * The previous Python script also offered `--download` to write the MP3 to
+ * disk. That's intentionally dropped here: the agent flow never used it (the
+ * audio URL is persisted in cloud) and removing local file I/O keeps the
+ * handler stateless.
+ */
+import type { HandlerContext, HandlerInput } from './index.js';
+export declare function genVoice(input: HandlerInput, ctxIn: HandlerContext): Promise<void>;

package/dist/handlers/gen-voice.js

@@ -0,0 +1,110 @@
+/**
+ * gen-voice handler — Minimax TTS via ab-api /tool/minimaxT2aV2.
+ *
+ * Operations:
+ *   --list-voices true                 → GET available voice IDs from /voice/page (live)
+ *   --list-voices true --local true    → print the built-in language-tagged
+ *                                        fallback catalog (offline, no API call)
+ *   default                            → synthesize text into an MP3 URL
+ *
+ * The previous Python script also offered `--download` to write the MP3 to
+ * disk. That's intentionally dropped here: the agent flow never used it (the
+ * audio URL is persisted in cloud) and removing local file I/O keeps the
+ * handler stateless.
+ */
+import { mmPost, resolveHttpContext, SkillError } from '../http.js';
+import { emitProgress } from '../progress.js';
+const DEFAULT_VOICE_ID = 'Chinese (Mandarin)_Male_Announcer';
+/**
+ * Fallback voice catalog printed when `--list-voices --local` is passed.
+ * Mirrors the language-keyed defaults that gen_script.py uses, kept in sync
+ * by hand because the two callers live on different runtimes.
+ *
+ * Promote to a JSON config once this grows beyond a handful of entries.
+ */
+const LOCAL_VOICE_CATALOG = [
+    { id: 'Chinese (Mandarin)_Male_Announcer', language: 'zh', name: 'Mandarin Male Announcer (legacy default)' },
+    // TODO: replace once gen-voice service confirms an English default voice id.
+    { id: 'english-male-friendly-01', language: 'en', name: 'Friendly Male (English, TBD)' },
+];
+function toNumber(value, name, defaultValue) {
+    if (value === undefined || value === null || value === '')
+        return defaultValue;
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        throw new SkillError(`❌ ${name} must be a number, received: ${value}`);
+    return n;
+}
+function isTrue(value) {
+    return value === true || value === 'true';
+}
+async function listVoicesRemote(ctx) {
+    const data = await mmPost(ctx, '/voice/page', { current: 1, pageSize: 100 }, { timeoutMs: 30_000 });
+    const voices = data.list ?? [];
+    if (voices.length === 0) {
+        process.stdout.write('⚠️  No voices available\n');
+        return;
+    }
+    process.stdout.write(`\n${'Voice ID'.padEnd(30)} Name\n`);
+    process.stdout.write(`${'-'.repeat(30)} ${'-'.repeat(20)}\n`);
+    for (const v of voices) {
+        process.stdout.write(`${(v.uniqId ?? '').padEnd(30)} ${v.name ?? ''}\n`);
+    }
+    process.stdout.write(`\n${voices.length} voice(s) available\n`);
+    process.stdout.write(`💡 Use --voice-id <id> to select a voice for synthesis\n`);
+}
+function listVoicesLocal() {
+    for (const v of LOCAL_VOICE_CATALOG) {
+        process.stdout.write(`${v.id}\t${v.language}\t${v.name}\n`);
+    }
+}
+export async function genVoice(input, ctxIn) {
+    // ── --list-voices: catalog mode (no synthesis) ──────────────────────────
+    if (isTrue(input.list_voices)) {
+        if (isTrue(input.local))
+            return listVoicesLocal();
+        const ctx = resolveHttpContext(ctxIn.skillName, {
+            apiBaseUrl: input.api_base_url,
+            privateToken: input.priv_token,
+        });
+        return listVoicesRemote(ctx);
+    }
+    // ── synthesize ──────────────────────────────────────────────────────────
+    const text = input.text;
+    if (!text || typeof text !== 'string' || !text.trim()) {
+        throw new SkillError('❌ Please provide --text to specify the text to synthesize');
+    }
+    const voiceId = input.voice_id ?? DEFAULT_VOICE_ID;
+    const speed = toNumber(input.speed, 'speed', 1.0);
+    if (speed < 0.5 || speed > 2.0) {
+        throw new SkillError('❌ speed must be in the range 0.5~2.0');
+    }
+    const ctx = resolveHttpContext(ctxIn.skillName, {
+        apiBaseUrl: input.api_base_url,
+        privateToken: input.priv_token,
+    });
+    emitProgress({ phase: 'gen-voice:request', voiceId, speed });
+    const data = await mmPost(ctx, '/tool/minimaxT2aV2', { text, voiceSetting: { voiceId, speed }, outputFormat: 'url' }, { timeoutMs: 120_000 });
+    const audioUrl = data.audio;
+    if (!audioUrl) {
+        throw new SkillError(`❌ API response did not contain an audio URL: ${JSON.stringify(data)}`);
+    }
+    if (isTrue(input.json_output)) {
+        process.stdout.write(JSON.stringify({
+            url: audioUrl,
+            audio_length_ms: data.extraInfo?.audioLength ?? null,
+            subtitles: (data.subtitles ?? []).map((s) => ({
+                text: s.text ?? '',
+                timeBegin: s.timeBegin ?? 0,
+                timeEnd: s.timeEnd ?? 0,
+            })),
+        }) + '\n');
+        return;
+    }
+    const lengthMs = data.extraInfo?.audioLength;
+    if (typeof lengthMs === 'number') {
+        process.stdout.write(`\n🕐 Audio length: ${(lengthMs / 1000).toFixed(1)} s\n`);
+    }
+    process.stdout.write(`\n🔗 Audio URL (plays directly, no download needed):\n${audioUrl}\n`);
+    process.stdout.write(`\n🎉 TTS synthesis done!\n`);
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Handler registry — maps `entry.handler` strings to their implementation.
+ *
+ * Only `entry.type` in ('http' | 'builtin') uses this registry; python
+ * skills go through spawn() in runner.ts and bypass handlers entirely.
+ */
+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;
+}
+export type SkillHandler = (input: HandlerInput, ctx: HandlerContext) => Promise<void>;
+export declare const HANDLERS: Record<string, SkillHandler>;