@remixmate/cli 0.9.15 → 0.9.17

package/dist/project/store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Persistent project binding — which Project should this machine's CLI output
+ * belong to?
+ *
+ * Stored at ~/.config/remixmate/projects.json, NOT in credentials.json: that
+ * file is a 0600 secret store keyed by API base URL, with different lifetime
+ * and different blast radius on corruption.
+ *
+ * Two layers, because host cwd semantics are not uniform:
+ *   - `byPath`  — keyed by absolute cwd. Hosts that run inside the user's real
+ *                 repo (Codex, Claude Code) get per-repo bindings.
+ *   - `default` — a single fallback. Hosts that spawn a throwaway working
+ *                 directory per conversation (WorkBuddy uses
+ *                 ~/WorkBuddy/<timestamp>) would never hit a byPath entry, so a
+ *                 cwd-only design silently degrades to nothing for them.
+ *
+ * See docs/cli-project-binding-design.md §3.
+ */
+export declare const CONFIG_DIR: string;
+export declare const PROJECTS_FILE: string;
+export interface StoredBinding {
+    projectId: string;
+    /** Which layer matched — surfaced by `project show` / `doctor`. */
+    scope: 'path' | 'default';
+}
+/** Look up the binding for a cwd: exact byPath match first, then the default. */
+export declare function readBinding(apiBaseUrl: string, cwd?: string): Promise<StoredBinding | null>;
+/** Bind a project to this cwd (`scope: 'path'`) or as the fallback (`'default'`). */
+export declare function writeBinding(apiBaseUrl: string, projectId: string, scope: 'path' | 'default', cwd?: string): Promise<void>;
+/** Drop a binding. Returns true when something was actually removed. */
+export declare function clearBinding(apiBaseUrl: string, scope: 'path' | 'default', cwd?: string): Promise<boolean>;

package/dist/project/store.js

@@ -0,0 +1,97 @@
+/**
+ * Persistent project binding — which Project should this machine's CLI output
+ * belong to?
+ *
+ * Stored at ~/.config/remixmate/projects.json, NOT in credentials.json: that
+ * file is a 0600 secret store keyed by API base URL, with different lifetime
+ * and different blast radius on corruption.
+ *
+ * Two layers, because host cwd semantics are not uniform:
+ *   - `byPath`  — keyed by absolute cwd. Hosts that run inside the user's real
+ *                 repo (Codex, Claude Code) get per-repo bindings.
+ *   - `default` — a single fallback. Hosts that spawn a throwaway working
+ *                 directory per conversation (WorkBuddy uses
+ *                 ~/WorkBuddy/<timestamp>) would never hit a byPath entry, so a
+ *                 cwd-only design silently degrades to nothing for them.
+ *
+ * See docs/cli-project-binding-design.md §3.
+ */
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { promises as fs } from 'node:fs';
+export const CONFIG_DIR = join(homedir(), '.config', 'remixmate');
+export const PROJECTS_FILE = join(CONFIG_DIR, 'projects.json');
+/**
+ * Must build a NEW object every call, not spread a shared constant: `backends`
+ * would then be one object aliased by every "empty" read, and writeBinding
+ * mutates it — so a later read of a missing/corrupt file would hand back
+ * bindings accumulated earlier in the process instead of nothing.
+ */
+function emptyFile() {
+    return { version: 1, backends: {} };
+}
+async function readFile() {
+    try {
+        const raw = await fs.readFile(PROJECTS_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.backends)
+            return emptyFile();
+        return parsed;
+    }
+    catch {
+        // Missing or corrupt → behave as unbound. A broken binding file must never
+        // block a render; the resolution ladder just falls through to the default project.
+        return emptyFile();
+    }
+}
+async function writeFile(data) {
+    await fs.mkdir(dirname(PROJECTS_FILE), { recursive: true, mode: 0o700 });
+    await fs.writeFile(PROJECTS_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+}
+/** Look up the binding for a cwd: exact byPath match first, then the default. */
+export async function readBinding(apiBaseUrl, cwd = process.cwd()) {
+    const file = await readFile();
+    const entry = file.backends[apiBaseUrl];
+    if (!entry)
+        return null;
+    const byPath = entry.byPath?.[resolve(cwd)];
+    if (byPath)
+        return { projectId: byPath, scope: 'path' };
+    if (entry.default)
+        return { projectId: entry.default, scope: 'default' };
+    return null;
+}
+/** Bind a project to this cwd (`scope: 'path'`) or as the fallback (`'default'`). */
+export async function writeBinding(apiBaseUrl, projectId, scope, cwd = process.cwd()) {
+    const file = await readFile();
+    const entry = file.backends[apiBaseUrl] ?? {};
+    if (scope === 'default') {
+        entry.default = projectId;
+    }
+    else {
+        entry.byPath = { ...(entry.byPath ?? {}), [resolve(cwd)]: projectId };
+    }
+    file.backends[apiBaseUrl] = entry;
+    await writeFile(file);
+}
+/** Drop a binding. Returns true when something was actually removed. */
+export async function clearBinding(apiBaseUrl, scope, cwd = process.cwd()) {
+    const file = await readFile();
+    const entry = file.backends[apiBaseUrl];
+    if (!entry)
+        return false;
+    let removed = false;
+    if (scope === 'default') {
+        removed = entry.default != null;
+        delete entry.default;
+    }
+    else {
+        const key = resolve(cwd);
+        removed = entry.byPath?.[key] != null;
+        if (entry.byPath)
+            delete entry.byPath[key];
+    }
+    if (removed)
+        await writeFile(file);
+    return removed;
+}

package/dist/project/take.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Take creation — turn a render invocation into a VideoProject the web app can
+ * show, and hand its conversation id down to the skill.
+ *
+ * Why this exists at all: ab-web derives a video's project from
+ * `file.conversation_id → media_video_project → media_project`. A render whose
+ * upload carries no conversation id is stored correctly but belongs to nothing,
+ * so it shows up only in the raw asset list. The cloud agent injects
+ * CONVERSATION_ID for its own runs; locally, nobody did — that is the bug this
+ * module fixes.
+ *
+ * Idempotency lives on the server (`/video-project/ensure` is get-or-create on
+ * `(user_id, client_session_key)`), not in a local state file: a pipeline is N
+ * separate CLI processes, sometimes concurrent, and a local cache would have to
+ * solve staleness and write races that a unique index solves for free.
+ *
+ * See docs/cli-project-binding-design.md §5.
+ */
+import { type HttpContext } from '../http.js';
+export interface EnsuredTake {
+    conversationId: string;
+    videoProjectId: string;
+    projectId: string;
+    created: boolean;
+    attempt: number;
+}
+/**
+ * Look up the take for the current grouping key without creating anything.
+ *
+ * Used by pipeline skills that should attach to a take when one exists but must
+ * never bring one into being: someone running `remixmate gen-image` on its own
+ * isn't making a video, and an empty VideoProject is worse clutter than an
+ * unattributed image.
+ *
+ * Deliberately does NOT resolve a project — resolveProject()'s last rung
+ * lazily *creates* 「未分类」, which a read-only lookup has no business doing.
+ */
+export declare function findTake(ctx: HttpContext): Promise<EnsuredTake | null>;
+/**
+ * Resolve project + grouping key, then get-or-create the take.
+ * Returns null when this invocation shouldn't own a take.
+ */
+export declare function ensureTake(ctx: HttpContext, opts: {
+    jobId?: number;
+    flagProjectId?: string;
+}): Promise<EnsuredTake | null>;

package/dist/project/take.js

@@ -0,0 +1,102 @@
+/**
+ * Take creation — turn a render invocation into a VideoProject the web app can
+ * show, and hand its conversation id down to the skill.
+ *
+ * Why this exists at all: ab-web derives a video's project from
+ * `file.conversation_id → media_video_project → media_project`. A render whose
+ * upload carries no conversation id is stored correctly but belongs to nothing,
+ * so it shows up only in the raw asset list. The cloud agent injects
+ * CONVERSATION_ID for its own runs; locally, nobody did — that is the bug this
+ * module fixes.
+ *
+ * Idempotency lives on the server (`/video-project/ensure` is get-or-create on
+ * `(user_id, client_session_key)`), not in a local state file: a pipeline is N
+ * separate CLI processes, sometimes concurrent, and a local cache would have to
+ * solve staleness and write races that a unique index solves for free.
+ *
+ * See docs/cli-project-binding-design.md §5.
+ */
+import { mmPost } from '../http.js';
+import { resolveTakeKey } from './host.js';
+import { resolveProject } from './resolve.js';
+/**
+ * Pull title / aspectRatio / templateId off the persisted render job.
+ *
+ * The VideoProject row needs them at creation time, but this runs in Node
+ * before the Python renderer is spawned, so the DSL itself isn't in reach —
+ * `render_jobs.dsl_meta` is the summary of exactly those fields. Best-effort:
+ * a take with a placeholder title beats no take at all.
+ */
+async function fetchJobMeta(ctx, jobId) {
+    try {
+        const detail = await mmPost(ctx, '/renderJob/get', { jobId });
+        return detail?.dslMeta ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Look up the take for the current grouping key without creating anything.
+ *
+ * Used by pipeline skills that should attach to a take when one exists but must
+ * never bring one into being: someone running `remixmate gen-image` on its own
+ * isn't making a video, and an empty VideoProject is worse clutter than an
+ * unattributed image.
+ *
+ * Deliberately does NOT resolve a project — resolveProject()'s last rung
+ * lazily *creates* 「未分类」, which a read-only lookup has no business doing.
+ */
+export async function findTake(ctx) {
+    const takeKey = resolveTakeKey(undefined);
+    if (!takeKey.key)
+        return null;
+    const res = await mmPost(ctx, '/video-project/find-by-session', {
+        clientSessionKey: takeKey.key,
+    });
+    if (!res?.conversationId)
+        return null;
+    return {
+        conversationId: res.conversationId,
+        videoProjectId: res.id,
+        projectId: res.projectId ?? '',
+        created: false,
+        attempt: res.attempt ?? 0,
+    };
+}
+/**
+ * Resolve project + grouping key, then get-or-create the take.
+ * Returns null when this invocation shouldn't own a take.
+ */
+export async function ensureTake(ctx, opts) {
+    const jobId = opts.jobId && opts.jobId > 0 ? opts.jobId : undefined;
+    const takeKey = resolveTakeKey(jobId);
+    // No grouping key at all → don't create. Only reachable for a take-creating
+    // skill that has no jobId (prepare-video-assets) on a host that exposes no
+    // session id. Creating here would produce an ungrouped take that the later
+    // render-video call — which *does* have a jobId, hence the `job:N` key —
+    // could not join, leaving two takes for one video.
+    if (!takeKey.key)
+        return null;
+    const { projectId } = await resolveProject(ctx, { flagProjectId: opts.flagProjectId });
+    const meta = jobId ? await fetchJobMeta(ctx, jobId) : {};
+    const res = await mmPost(ctx, '/video-project/ensure', {
+        projectId,
+        clientSessionKey: takeKey.key,
+        clientHost: takeKey.host,
+        jobId: jobId ?? 0,
+        title: meta?.title ?? '',
+        archetype: meta?.archetype ?? '',
+        aspectRatio: meta?.aspectRatio ?? '',
+        templateId: meta?.templateId ?? '',
+    });
+    if (!res?.conversationId)
+        return null;
+    return {
+        conversationId: res.conversationId,
+        videoProjectId: res.id,
+        projectId,
+        created: res.created,
+        attempt: res.attempt,
+    };
+}

package/dist/registry.d.ts

@@ -16,6 +16,10 @@ export interface SkillDef {
     entry: SkillEntry;
     /** Authorization requirement enforced by the dispatcher before invocation. */
     auth: SkillAuthMode;
+    /** Ensure a take (VideoProject + conversation) before running — see skill-schema.ts. */
+    createsTake: boolean;
+    /** Attach to an existing take, never create one — see skill-schema.ts. */
+    joinsTake: boolean;
     skillDir: string;
     /** Absolute path to the python entry script (only when entry.type === 'python'). */
     scriptAbsolutePath?: string;

package/dist/registry.js

@@ -38,6 +38,8 @@ function loadOne(skillDir) {
         parameters: raw.parameters ?? {},
         entry,
         auth: resolveAuthMode(raw),
+        createsTake: raw.createsTake === true,
+        joinsTake: raw.joinsTake === true,
         skillDir,
     };
     if (entry.type === 'python') {

package/dist/runner.js

@@ -16,6 +16,8 @@ import { HANDLERS } from './handlers/index.js';
 import { EXIT, SkillError } from './errors.js';
 import { authChildEnv, ensureAuth } from './auth/ensure.js';
 import { emitBillingFooter } from './billing.js';
+import { resolveHttpContext } from './http.js';
+import { ensureTake, findTake } from './project/take.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;
@@ -33,6 +35,7 @@ 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);
         switch (skill.entry.type) {
             case 'python':
                 // Python children talk to ab-api themselves and print their own billing
@@ -58,6 +61,62 @@ export async function runSkill(skillName, opts) {
         emitBillingFooter();
     }
 }
+/**
+ * Attach this invocation to a take, publishing the result as `CONVERSATION_ID`.
+ * That variable is the only thing that makes an uploaded asset reachable from
+ * the web app — it rides the upload as `x-conversation-id` and lands in
+ * `file.conversation_id`.
+ *
+ * Writes `process.env` rather than returning a child-env patch, because the two
+ * dispatch paths consume it differently: spawned Python inherits the process
+ * environment, while http/builtin handlers run in-process and read it via
+ * resolveHttpContext(). Four of the seven take-joining skills are in-process
+ * handlers, so a child-env-only patch would silently do nothing for them.
+ * Safe here because the CLI runs exactly one skill per process.
+ *
+ * Two deliberate non-behaviours:
+ *   - An already-set CONVERSATION_ID is left alone. The cloud agent injects its
+ *     own, and so does our own parent when prepare-video-assets shells out to
+ *     gen-image / gen-voice. Re-deriving would fork the conversation.
+ *   - Any failure is downgraded to a warning. Attribution is a convenience;
+ *     losing it must never cost the user a render they already paid for. The
+ *     asset still uploads, just unattributed — exactly the old behaviour.
+ */
+async function applyTakeContext(skill, opts, auth) {
+    if (!skill.createsTake && !skill.joinsTake)
+        return;
+    if ((process.env.CONVERSATION_ID ?? '').trim())
+        return;
+    if (!auth.token)
+        return;
+    try {
+        const ctx = await resolveHttpContext(skill.name, {
+            apiBaseUrl: auth.apiBaseUrl,
+            preflightToken: auth.token,
+        });
+        let take;
+        if (skill.createsTake) {
+            const jobIdArg = opts.parsedArgs.job_id;
+            const jobId = typeof jobIdArg === 'number' ? jobIdArg : Number(jobIdArg);
+            const flagProject = opts.parsedArgs.project;
+            take = await ensureTake(ctx, {
+                jobId: Number.isFinite(jobId) ? jobId : undefined,
+                flagProjectId: typeof flagProject === 'string' ? flagProject : undefined,
+            });
+        }
+        else {
+            take = await findTake(ctx);
+        }
+        if (!take)
+            return;
+        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`);
+    }
+    catch (err) {
+        process.stderr.write(`⚠️  无法归属本次产物（内容仍会正常生成，但不会出现在项目里）: ${err.message}\n`);
+    }
+}
 async function runPython(skill, rawArgs, auth) {
     if (!skill.scriptAbsolutePath) {
         throw new SkillError(`skill ${skill.name} has entry.type=python but no scriptAbsolutePath`);

package/dist/skill-schema.d.ts

@@ -58,6 +58,20 @@ export interface RawSkillJson {
     scriptPath?: string;
     entry?: SkillEntry;
     envVars?: string[];
+    /**
+     * Declares that this skill produces a finished video, so the dispatcher should
+     * ensure a "take" (VideoProject + conversation) before running it and inject the
+     * resulting CONVERSATION_ID. Declarative rather than a hardcoded skill name in
+     * runner.ts, so the pipeline's shape stays visible in the skill's own manifest.
+     */
+    createsTake?: boolean;
+    /**
+     * Declares that this skill contributes to a video but must never *start* one:
+     * attach to an existing take if there is one, otherwise carry on unattributed.
+     * A standalone `gen-image` run isn't a video, and an empty VideoProject is
+     * worse clutter than an unattributed asset.
+     */
+    joinsTake?: boolean;
 }
 /**
  * Resolve a skill's auth mode, defaulting for records that predate the field.

package/dist/skill-schema.js

@@ -61,6 +61,21 @@ export function validateSkillJson(raw, skillId) {
     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.createsTake != null && typeof raw.createsTake !== 'boolean') {
+        errors.push(`skill.json.createsTake must be a boolean, got '${String(raw.createsTake)}'`);
+    }
+    if (raw.joinsTake != null && typeof raw.joinsTake !== 'boolean') {
+        errors.push(`skill.json.joinsTake must be a boolean, got '${String(raw.joinsTake)}'`);
+    }
+    if (raw.createsTake === true && raw.joinsTake === true) {
+        errors.push("skill.json cannot set both 'createsTake' and 'joinsTake' — createsTake already implies joining");
+    }
+    // Attribution means calling ab-api as a specific user. An `auth: none` skill
+    // never touches the backend and produces no server-side file, so there is
+    // nothing to attribute — the flag would be dead config that reads as working.
+    if ((raw.createsTake === true || raw.joinsTake === true) && resolveAuthMode(raw) === 'none') {
+        errors.push("skill.json declares createsTake/joinsTake but auth='none' — a purely local skill has nothing to attribute");
+    }
     if (raw.name && raw.name !== skillId) {
         errors.push(`skill.json.name='${raw.name}' does not match directory name '${skillId}'`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.15",
+  "version": "0.9.17",
   "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",

package/skills/export-jianying/version.json

@@ -3,5 +3,5 @@
   "repoName": "agent-skill-media-maker",
   "skillId": "554",
   "version": "V3",
-  "skillDescription": "剪映草稿生成技能，将素材URL打包为剪映可导入的草稿ZIP，支持从 RenderPlan 自动转换（调用 ab-api /file/generateJianYing）。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- 导出剪映、剪映草稿、打包剪映、导入剪映\n- 将素材导出为剪映格式、生成剪映工程\n- 把视频/图片/音频打包成剪映草稿\n- 从 RenderPlan 导出剪映草稿\n\n即使用户没有明确说「剪映」，只要他们想要将素材打包为可在剪映中编辑的草稿格式，也要使用本 skill。"
+  "skillDescription": "Jianying (CapCut) draft-generation skill. Packages asset URLs into a draft ZIP that Jianying can import; supports automatic conversion from a RenderPlan (calls ab-api /file/generateJianYing).\n\nUse this skill as soon as the user mentions any of these intents:\n- Export to Jianying, Jianying draft, package for Jianying, import into Jianying\n- Export materials to the Jianying format, generate a Jianying project\n- Bundle video / image / audio into a Jianying draft\n- Export a Jianying draft from a RenderPlan\n\nEven when the user does not say \"Jianying\" explicitly, use this skill whenever they want to package materials into a draft that can be edited in Jianying."
 }

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

@@ -6,20 +6,87 @@
   "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" },
+  "joinsTake": true,
+  "envVars": [
+    "PRIV_TOKEN",
+    "MM_API_BASE_URL",
+    "AGENT_NAME"
+  ],
+  "entry": {
+    "type": "http",
+    "handler": "gen-digital-human"
+  },
   "parameters": {
     "type": "object",
     "properties": {
-      "list_avatars": { "type": "boolean", "description": "List available digital-human avatars" },
-      "source": { "type": "string", "enum": ["jimeng", "hifly"], "description": "Filter by source" },
-      "gender": { "type": "string", "enum": ["male", "female"], "description": "Filter by gender" },
-      "avatar_id": { "type": "number", "description": "Avatar id" },
-      "text": { "type": "string", "description": "Narration text (TTS mode)" },
-      "audio_url": { "type": "string", "description": "Audio URL (audio-driven mode)" },
-      "voice_id": { "type": "string", "description": "Voice id" },
-      "aspect_ratio": { "type": "string", "description": "Aspect ratio" },
-      "json_output": { "type": "boolean", "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }) instead of human-readable output" }
+      "list_avatars": {
+        "type": "boolean",
+        "description": "List available digital-human avatars"
+      },
+      "mine": {
+        "type": "boolean",
+        "description": "With list_avatars=true: list the caller's own custom avatars instead of the public catalog. Custom avatars do not appear without this."
+      },
+      "name": {
+        "type": "string",
+        "description": "With list_avatars=true: fuzzy-filter avatars by name"
+      },
+      "source": {
+        "type": "string",
+        "enum": [
+          "jimeng",
+          "hifly"
+        ],
+        "description": "Provider: jimeng is image-driven, hifly is video-driven. Usually inferred from the avatar; pass it explicitly when the avatar declares no source."
+      },
+      "gender": {
+        "type": "string",
+        "enum": [
+          "male",
+          "female"
+        ],
+        "description": "Filter by gender"
+      },
+      "avatar_id": {
+        "type": "number",
+        "description": "Avatar id"
+      },
+      "text": {
+        "type": "string",
+        "description": "Narration text (TTS mode)"
+      },
+      "audio_url": {
+        "type": "string",
+        "description": "Audio URL (audio-driven mode)"
+      },
+      "voice_id": {
+        "type": "string",
+        "description": "Voice id (TTS mode). Shares the Minimax catalog with gen-voice — call gen_voice with list_voices=true to see available ids rather than inventing one."
+      },
+      "voice_name": {
+        "type": "string",
+        "description": "Voice display name, recorded alongside voice_id for bookkeeping. Does not affect synthesis."
+      },
+      "aspect_ratio": {
+        "type": "string",
+        "description": "Aspect ratio: 9:16 / 16:9 / 3:4 / 1:1. Defaults to the avatar's own ratio."
+      },
+      "prompt": {
+        "type": "string",
+        "description": "Action prompt describing how the avatar should perform, e.g. 'more hand gestures'"
+      },
+      "check_status": {
+        "type": "boolean",
+        "description": "Status-check mode: poll an earlier job instead of starting a new one. Requires generation_id. Use this when a generate call timed out."
+      },
+      "generation_id": {
+        "type": "number",
+        "description": "Job id to poll (required when check_status=true)"
+      },
+      "json_output": {
+        "type": "boolean",
+        "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }) instead of human-readable output"
+      }
     },
     "required": []
   }

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

@@ -3,5 +3,5 @@
   "repoName": "agent-skill-media-maker",
   "skillId": "336",
   "version": "V8",
-  "skillDescription": "数字人口播视频技能，支持查询形象、TTS 口播、音频驱动口播和查询生成状态（调用 ab-api 数字人接口，即梦 / 飞影）。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- 数字人、数字人视频、数字人口播、生成数字人视频\n- 用户提供已有音频 URL（MP3 等）、用外链音频驱动数字人口型\n- AI 主播、虚拟主播、虚拟人物视频、口播视频\n- 让数字人说话、让虚拟人说一段话、让 AI 人物播报\n- 查看/列出数字人形象、有哪些数字人可以用\n- 使用即梦/飞影数字人\n\n即使用户没有明确说「使用 AI」，只要他们想要让一个虚拟人物朗读/播报一段文字并生成视频，也要使用本 skill。"
+  "skillDescription": "Digital-human (talking-head) skill: list available avatars, run TTS-based or audio-driven lip-sync, and check the status of pending jobs. Backed by ab-api's digital-human endpoints (Jimeng / HiFly providers).\n\nUse this skill immediately whenever the user asks for any of:\n- Digital human, talking-head video, AI presenter, virtual host\n- \"Make a talking-head video out of this script / this audio file\"\n- List or browse digital-human avatars\n- Use Jimeng or HiFly to drive an avatar\n\nEven without an explicit \"use AI\", any request that turns text or audio into a synthesized presenter video should route here."
 }

package/skills/gen-image/SKILL.md

@@ -23,21 +23,28 @@ Wraps ab-api's `POST /model/genImg` (the same endpoint the web studio uses), aut
 
 ## Models and sizes
 
-Aligned with the gen-image handler's model presets and the backend `ModelGenImgDTO`:
-
-| LiteLLM `model` | Display name | Provider |
-|-----------------|--------------|----------|
-| `doubao/doubao-seedream-4-5-251128` | Seedream 4.5 | Volcano |
-| `doubao/doubao-seedream-5-0-260128` | Seedream 5.0 Lite | Volcano |
-| `gemini-3-pro-image` | Gemini 3 Pro | Google |
-| `gemini-3.1-flash-image-preview` | Gemini 3.1 Flash | Google |
-
-- **Seedream**: `--size` is an aspect ratio (e.g. `1:1`, `9:16`) or `WxH`; the backend may auto-upscale the 4.5 model to meet a minimum pixel count.
-- **Gemini**: `--size` is a backend-allowed aspect ratio (e.g. `1:1`, `16:9`); add `--resolution`: `1K` / `2K` / `4K` (default `1K`).
+Pass `--model` a short name. The authoritative roster — ids, aliases, per-model limits —
+lives in the backend catalog (`/model/capabilities`), which the CLI fetches at runtime;
+the names below are the stable aliases to use.
+
+| `--model` | What it is | Reference images |
+|-----------|------------|------------------|
+| `seedream` | Default. General-purpose, highest output resolution. | up to 14 |
+| `seedream-pro` | High-fidelity variant: better placement/element control, more faithful text rendering. Costs more per image. | up to 10 |
+| `gemini` | Gemini 3 Pro. | up to 4 |
+
+- **Seedream**: `--size` is an aspect ratio (e.g. `1:1`, `9:16`) or `WxH`. The backend maps the
+  ratio to that model's own pixel preset and rescales out-of-range sizes, so prefer a ratio
+  over explicit pixels.
+- **`seedream-pro`** additionally supports `3:2` / `2:3` / `21:9`, and caps output at ~2K
+  (about 4.6 MP). Asking it for 4K pixels gets scaled down, not rejected — use `seedream`
+  when you need a genuinely larger image.
+- **Gemini**: `--size` is a backend-allowed aspect ratio (e.g. `1:1`, `16:9`); add
+  `--resolution`: `1K` / `2K` / `4K` (default `1K`). `--resolution` is ignored by Seedream.
 
 ## Auth & environment
 
-No skill-local env file — the executing process inherits the system environment. Examples say `python`; on macOS you may need `python3`.
+No skill-local env file — the executing process inherits the system environment.
 
 - **Enterprise OpenClaw**: auth is already injected, **no need** for `PRIV_TOKEN` / `--priv-token`.
 - **Other environments**: configure the token. Without a token, non-interactive runs fail; interactive ones may prompt.
@@ -45,7 +52,7 @@ No skill-local env file — the executing process inherits the system environmen
 | Env var | Description | Default |
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
-| `MM_IMAGE_MODEL` | Default model id | `doubao/doubao-seedream-4-5-251128` |
+| `MM_IMAGE_MODEL` | Default model, as a `--model` value | backend default (`seedream`) |
 | `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.com/api` |
 | `AGENT_NAME` | Optional `x-invoke-agent` header | none |
 
@@ -67,17 +74,30 @@ remixmate gen-image \
 ```bash
 remixmate gen-image \
   --prompt "<image description>" \
-  --model gemini-3-pro-image \
+  --model gemini \
   --size "16:9" \
   --resolution "2K"
 ```
 
+```bash
+# High-fidelity: precise placement, legible on-image text
+remixmate gen-image \
+  --prompt "<image description>" \
+  --model seedream-pro \
+  --size "16:9"
+```
+
 ### Image-to-image (reference image)
 
 Reference images accept local file paths, HTTPS URLs, or data URIs. Pass `--reference` multiple times for multiple references.
 
-- **Seedream**: up to **14** reference images, `--image-strength` controls reference influence.
-- **Gemini**: up to **4** reference images.
+- **`seedream`**: up to **14** reference images, `--image-strength` controls reference influence.
+- **`seedream-pro`**: up to **10** reference images. Best choice when the edit has to land in a
+  specific spot — describe the target region in the prompt (e.g. "in the marked area at the
+  bottom left") and it holds position far better than `seedream`.
+- **`gemini`**: up to **4** reference images.
+
+Over-the-limit runs fail fast in the CLI, before spending credits.
 
 ```bash
 # URL reference
@@ -109,7 +129,7 @@ remixmate gen-image \
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p` / `--prompt` | Description (required) | — |
-| `-m` / `--model` | Model id | see `MM_IMAGE_MODEL` |
+| `-m` / `--model` | `seedream` / `seedream-pro` / `gemini` | see `MM_IMAGE_MODEL` |
 | `-s` / `--size` | Seedream: ratio or WxH; Gemini: ratio | `1:1` |
 | `--resolution` | Gemini only: `1K` / `2K` / `4K` | `1K` |
 | `-n` | Number of images, 1–4 | `1` |
@@ -124,7 +144,9 @@ remixmate gen-image \
 
 ## Credits
 
-Every run charges credits. The CLI prints a footer on stdout when it does:
+Every run charges credits, per image and **per model** — `seedream-pro` costs noticeably more
+per image than `seedream`, so don't reach for it by default. The CLI prints a footer on stdout
+when it charges:
 
 ```
 💳 Charged 31 credits · balance 1,240