@remixmate/cli 0.9.20 → 0.9.22

package/README.md

@@ -11,32 +11,32 @@ AI media generation skills for Claude Code / Codex.
 ## Install
 
 ```bash
-npm install -g @remixmate/cli
-remixmate --help
-remixmate --list
+npm install -g @remixmate/cli && remixmate install
 ```
 
-## Use in Claude Code
-
-Copy the bundled `skills/` into your project-level or global `.claude/skills/` directory and Claude Code will pick them up:
+`npm install` gives you the `remixmate` binary. `remixmate install` is what makes an
+agent *discover* the skills on its own: it copies the bundled `skills/` into every
+agent home it finds — Claude Code (`~/.claude/skills`) and Codex (`$CODEX_HOME/skills`,
+default `~/.codex/skills`), which share the same `SKILL.md` format. Restart the agent
+afterwards.
 
 ```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/
+remixmate install --host codex     # only one host
+remixmate install --project        # ./.claude/skills (Claude Code only)
+remixmate install --dir <path>     # explicit target
+remixmate uninstall                # remove exactly what was installed
 ```
 
-## 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`.
+The install is *managed*, not a `cp -R`: each skills directory gets a
+`.remixmate-install.json` receipt recording the version and the skill list. That is
+what lets a re-run upgrade in place, lets `uninstall` remove only our own directories,
+and lets `remixmate doctor` warn when a global `npm update` has left the installed
+copies behind. A same-named skill that this CLI did not install is never overwritten
+without `--force`.
 
-See the full intro page (Claude Code / Codex setup, env vars, end-to-end workflow examples) at the project homepage.
+Without installing, the CLI still works — you just have to name it (`remixmate --list`,
+or tell the agent to run `remixmate <skill> --help`). The agent will not reach for it
+unprompted.
 
 ## Authentication
 

package/README.zh-CN.md

@@ -11,32 +11,28 @@
 ## 安装
 
 ```bash
-npm install -g @remixmate/cli
-remixmate --help
-remixmate --list
+npm install -g @remixmate/cli && remixmate install
 ```
 
-## 在 Claude Code 中使用
-
-把内置的 `skills/` 拷贝到项目级或全局的 `.claude/skills/` 目录，Claude Code 会自动识别：
+`npm install` 装的是 `remixmate` 这个命令；`remixmate install` 才让 agent **自己发现**
+这些 skill —— 它把内置的 `skills/` 铺进检测到的每个 agent 目录：Claude Code
+（`~/.claude/skills`）与 Codex（`$CODEX_HOME/skills`，默认 `~/.codex/skills`），两者
+用的是同一套 `SKILL.md` 格式。装完重启 agent 生效。
 
 ```bash
-# 项目级
-mkdir -p .claude/skills
-cp -R "$(npm root -g)/@remixmate/cli/skills/." .claude/skills/
-
-# 或全局
-mkdir -p ~/.claude/skills
-cp -R "$(npm root -g)/@remixmate/cli/skills/." ~/.claude/skills/
+remixmate install --host codex     # 只装某一个宿主
+remixmate install --project        # 装到 ./.claude/skills（仅 Claude Code）
+remixmate install --dir <path>     # 指定目录
+remixmate uninstall                # 按装机记录精确卸载
 ```
 
-## 在 Codex 中使用
-
-Codex 不会原生加载 `SKILL.md`。在系统提示里告诉 Codex 这个 CLI，让它在需要媒体生成时调用 `remixmate <skill> ...`：
-
-> 当你需要 AI 媒体生成（图片 / 视频 / 语音 / 数字人 / 剪映导出）时，先运行 `remixmate <skill-id> --help` 查看参数，再用 `remixmate <skill-id> --json-output ...` 执行。可用技能：`remixmate --list`。
+这里的安装是**受管**的，不是 `cp -R`：每个 skills 目录下会写一份
+`.remixmate-install.json` 回执，记录版本与本次铺下去的 skill 名单。靠它，重跑即原地升级、
+`uninstall` 只删自己装的目录、`remixmate doctor` 能在 `npm update -g` 之后提示铺出去的副本
+已经落后。同名但不是本 CLI 装的 skill，不加 `--force` 绝不覆盖。
 
-完整介绍页（Claude Code / Codex 配置、环境变量、端到端工作流示例）见项目主页。
+不装也能用，只是得点名（`remixmate --list`，或让 agent 去跑 `remixmate <skill> --help`）；
+agent 不会主动想到它。
 
 ## 认证
 

package/dist/capabilities.d.ts

@@ -18,6 +18,9 @@ export interface ModelConstraints {
     durationMax?: number;
     durationDefault?: number;
     refImageMax?: number;
+    /** Omni-modal reference caps (Seedance 2.0): videos and audio clips per request. */
+    refVideoMax?: number;
+    refAudioMax?: number;
     sizes?: string[];
     /** aspect-ratio → [width, height] pixel preset (Seedream). Per model: the same
      *  ratio maps to different pixels on different Seedream variants. */

package/dist/cli.js

@@ -16,6 +16,7 @@ import { parseArgv } from './argv.js';
 import { runSkill } from './runner.js';
 import { runAuthCommand } from './auth/commands.js';
 import { HOST_VERB, PROJECT_VERB, runHostCommand, runProjectCommand } from './project/commands.js';
+import { INSTALL_VERB, UNINSTALL_VERB, runInstall, runUninstall } from './install.js';
 import { runExec } from './exec.js';
 import { authStatusLine, runDoctor } from './doctor.js';
 import { padDisplay } from './text.js';
@@ -51,6 +52,8 @@ function printUsage() {
     const skills = loadSkills(resolveBaseDir());
     process.stdout.write('Usage:\n');
     process.stdout.write('  remixmate --list                      List all skills\n');
+    process.stdout.write('  remixmate install [--host <h>]        Install the skills into Claude Code / Codex\n');
+    process.stdout.write('  remixmate uninstall                   Remove skills installed by this CLI\n');
     process.stdout.write('  remixmate doctor                      Diagnose environment, credentials, backend\n');
     process.stdout.write('  remixmate login                       Authorize this CLI via the browser\n');
     process.stdout.write('  remixmate login --start | --wait      Non-blocking authorization (for agent hosts)\n');
@@ -128,6 +131,14 @@ async function main() {
             await printAuthFooter();
         process.exit(EXIT.OK);
     }
+    // Host-install verbs, like the auth verbs, resolve before skill dispatch so a
+    // future skill named `install` could never shadow them.
+    if (argv[0] === INSTALL_VERB) {
+        process.exit(runInstall(argv.slice(1)));
+    }
+    if (argv[0] === UNINSTALL_VERB) {
+        process.exit(runUninstall(argv.slice(1)));
+    }
     if (argv[0] === 'doctor') {
         const code = await runDoctor({ skipNetwork: argv.includes('--offline') });
         process.exit(code);

package/dist/doctor.js

@@ -20,6 +20,7 @@ import { listCredentials } from './auth/credential-store.js';
 import { resolveTakeKey } from './project/host.js';
 import { readBinding } from './project/store.js';
 import { canAutoAuth, isHeadless } from './auth/environment.js';
+import { installStates } from './install.js';
 import { padDisplay } from './text.js';
 /**
  * Short auth status suitable for a footer. Never performs network I/O — a
@@ -100,6 +101,22 @@ export async function runDoctor(opts = {}) {
         detail: playwright ?? '当前解释器下未安装 —— 仅 web-screenshot / web-record 需要，首次运行会自动装',
     });
     checks.push({ name: '后端地址', status: 'ok', detail: apiBaseUrl });
+    // 宿主安装状态。这套方案唯一的静默失败模式是漂移：`npm update -g` 只动包，不动
+    // 已经铺进 ~/.claude/skills、~/.codex/skills 的副本,用户会拿着旧 SKILL.md 打新
+    // 后端,而且第一个症状往往是某个参数「莫名其妙不认」。
+    for (const s of installStates()) {
+        checks.push({
+            // 只取宿主名的第一段（Claude Code → Claude）——检查名要留在 padDisplay 的
+            // 对齐宽度内，宿主目录已经写在 detail 里，不会有歧义。
+            name: `${s.label.split(' ')[0]} skill`,
+            status: s.installedVersion == null ? 'warn' : s.drifted ? 'warn' : 'ok',
+            detail: s.installedVersion == null
+                ? `未安装 —— 该 agent 不会自动发现这些 skill（remixmate install 可安装到 ${s.skillsDir}）`
+                : s.drifted
+                    ? `已装 ${s.installedVersion}，当前包 ${s.currentVersion} → 运行 remixmate install 覆盖`
+                    : `${s.installedVersion}（${s.skillsDir}）`,
+        });
+    }
     // Where will this machine's renders land, and will repeated renders group?
     // Both were previously invisible — the first sign of trouble was a finished
     // video that appeared nowhere in the web app.

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

@@ -11,7 +11,9 @@
  * server-side, so an unknown value still passes through to the backend.
  *
  * Local image paths for first/last/reference frames are read and base64-encoded
- * into a data: URI; https / data: URIs pass through unchanged.
+ * into a data: URI; https / data: URIs pass through unchanged. Reference videos
+ * and audio are the exception — they must already be public URLs, see
+ * `requirePublicUrls`.
  */
 import type { HandlerContext, HandlerInput } from './index.js';
 export declare function genVideo(input: HandlerInput, ctxIn: HandlerContext): Promise<void>;

package/dist/handlers/gen-video.js

@@ -11,14 +11,16 @@
  * server-side, so an unknown value still passes through to the backend.
  *
  * Local image paths for first/last/reference frames are read and base64-encoded
- * into a data: URI; https / data: URIs pass through unchanged.
+ * into a data: URI; https / data: URIs pass through unchanged. Reference videos
+ * and audio are the exception — they must already be public URLs, see
+ * `requirePublicUrls`.
  */
 import { mmPost, pollUntil, resolveHttpContext, SkillError } from '../http.js';
 import { getCapabilities, matchModel, defaultModel } from '../capabilities.js';
 import { emitProgress } from '../progress.js';
 import { isTrue, resolveImageInput, toNumber, toStringArray } from './shared.js';
 /** Generic, catalog-driven validation. No model names live here. */
-function validateAgainstConstraints(descriptor, duration, ratio, resolution, refCount) {
+function validateAgainstConstraints(descriptor, duration, ratio, resolution, refs) {
     const c = descriptor.constraints;
     const label = descriptor.label || descriptor.id;
     if (c.durations && c.durations.length > 0) {
@@ -37,12 +39,35 @@ function validateAgainstConstraints(descriptor, duration, ratio, resolution, ref
     if (c.resolutions && c.resolutions.length > 0 && !c.resolutions.includes(resolution)) {
         throw new SkillError(`❌ ${label} resolution must be one of: ${c.resolutions.join(', ')}; got: ${resolution}`);
     }
-    if (c.refImageMax !== undefined && refCount > c.refImageMax) {
+    if (c.refImageMax !== undefined && refs.images > c.refImageMax) {
         if (c.refImageMax === 0) {
             throw new SkillError(`❌ ${label} does not support a reference-image array; use --first-frame / --last-frame instead`);
         }
-        throw new SkillError(`❌ ${label} accepts at most ${c.refImageMax} reference images; got: ${refCount}`);
+        throw new SkillError(`❌ ${label} accepts at most ${c.refImageMax} reference images; got: ${refs.images}`);
     }
+    if (c.refVideoMax !== undefined && refs.videos > c.refVideoMax) {
+        throw new SkillError(`❌ ${label} accepts at most ${c.refVideoMax} reference videos; got: ${refs.videos}`);
+    }
+    if (c.refAudioMax !== undefined && refs.audios > c.refAudioMax) {
+        throw new SkillError(`❌ ${label} accepts at most ${c.refAudioMax} reference audio clips; got: ${refs.audios}`);
+    }
+}
+/**
+ * Reference videos / audio must be public https URLs.
+ *
+ * Unlike images, they are NOT inlined as data URIs: the caps are 50 MB per video
+ * and 15 MB per clip, and base64 inflates that by a third before it ever reaches
+ * the gateway. Failing here with the offending path beats a truncated upload or
+ * an opaque 413 three hops downstream.
+ */
+function requirePublicUrls(values, flag) {
+    return values.map((value) => {
+        const url = value.trim();
+        if (!/^https?:\/\//i.test(url)) {
+            throw new SkillError(`❌ ${flag} needs a public http(s) URL (local files are not uploaded), received: ${value}`);
+        }
+        return url;
+    });
 }
 async function pollVideoStatus(ctx, taskId) {
     return pollUntil(async () => {
@@ -69,10 +94,26 @@ export async function genVideo(input, ctxIn) {
     const firstFrame = input.first_frame ? resolveImageInput(String(input.first_frame)) : '';
     const lastFrame = input.last_frame ? resolveImageInput(String(input.last_frame)) : '';
     const references = toStringArray(input.reference).map(resolveImageInput).filter(Boolean);
+    const referenceVideos = requirePublicUrls(toStringArray(input.reference_video).filter(Boolean), '--reference-video');
+    const referenceAudios = requirePublicUrls(toStringArray(input.reference_audio).filter(Boolean), '--reference-audio');
     const prompt = (input.prompt ?? '').trim();
-    const hasVisual = Boolean(firstFrame || lastFrame || references.length > 0);
+    const hasVisual = Boolean(firstFrame || lastFrame || references.length > 0 || referenceVideos.length > 0);
     if (!prompt && !hasVisual) {
-        throw new SkillError('❌ Provide at least one of: a non-empty --prompt, or --first-frame / --last-frame / --reference');
+        throw new SkillError('❌ Provide at least one of: a non-empty --prompt, or --first-frame / --last-frame / --reference / --reference-video');
+    }
+    /**
+     * Two shapes the backend rejects outright; catching them here saves a round
+     * trip and names the flag that caused it.
+     *
+     * - first/last frame pins exact frames, omni-modal reference lets the model
+     *   re-cut — the API has no meaning for both at once;
+     * - audio-only (or text + audio) input is not a supported modality mix.
+     */
+    if ((firstFrame || lastFrame) && (referenceVideos.length > 0 || referenceAudios.length > 0)) {
+        throw new SkillError('❌ --reference-video / --reference-audio cannot be combined with --first-frame / --last-frame; use --reference for images instead');
+    }
+    if (referenceAudios.length > 0 && references.length === 0 && referenceVideos.length === 0) {
+        throw new SkillError('❌ --reference-audio needs at least one --reference image or --reference-video alongside it');
     }
     const ratio = input.ratio ?? '16:9';
     const resolution = input.resolution ?? '720p';
@@ -80,7 +121,11 @@ export async function genVideo(input, ctxIn) {
     const seed = toNumber(input.seed, 'seed');
     // Pre-flight validation only when we recognize the model (have its constraints).
     if (descriptor) {
-        validateAgainstConstraints(descriptor, duration, ratio, resolution, references.length);
+        validateAgainstConstraints(descriptor, duration, ratio, resolution, {
+            images: references.length,
+            videos: referenceVideos.length,
+            audios: referenceAudios.length,
+        });
     }
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
@@ -103,6 +148,16 @@ export async function genVideo(input, ctxIn) {
         payload.lastFrameImage = lastFrame;
     if (references.length > 0)
         payload.referenceImages = references;
+    if (referenceVideos.length > 0)
+        payload.referenceVideos = referenceVideos;
+    if (referenceAudios.length > 0)
+        payload.referenceAudios = referenceAudios;
+    // Web search only fires on text-only input; sending it alongside attachments
+    // would be a knob the model silently ignores.
+    if (isTrue(input.web_search) && !hasVisual)
+        payload.webSearch = true;
+    if (isTrue(input.return_last_frame))
+        payload.returnLastFrame = true;
     if (input.negative_prompt && String(input.negative_prompt).trim()) {
         payload.negativePrompt = String(input.negative_prompt).trim();
     }

package/dist/install.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `remixmate install` / `remixmate uninstall` — 把包内 skills/ 铺进 agent 宿主。
+ *
+ * 为什么需要一条命令，而不是让站点给出 `cp -R "$(npm root -g)/…/skills/." ~/.claude/skills/`：
+ *
+ *   1. 目标已经不止一个。Claude Code 与 Codex 现在用同一套 SKILL.md 格式
+ *      （Codex 装到 $CODEX_HOME/skills/<name>），手工 cp 的心智成本直接翻倍。
+ *   2. 拷贝出去的副本没有主人。`npm update -g` 之后包升了级、副本停在旧版；
+ *      `npm uninstall -g` 之后副本原地变成孤儿。两种都是静默的 —— 本项目作者机器上
+ *      就留着一批 5 月建的、指向早已不存在路径的 skill 目录，没有任何东西负责清理。
+ *
+ * 所以这里的安装是**受管**的：每个宿主的 skills 目录下写一份装机回执
+ * (.remixmate-install.json)，记下版本、来源与这次铺下去的 skill 名单。升级照名单
+ * 覆盖、卸载照名单删除、doctor 照名单比对版本 —— 三件事都不靠猜目录里哪些是我们的。
+ *
+ * 刻意不做的两件事：
+ *   - 不挂 npm postinstall。`npm i -g` 时往 ~/.claude、~/.codex 写东西太越界，
+ *     且 `--ignore-scripts` 下会静默失效。安装必须是用户显式发起的动作。
+ *   - 不用软链。指向 $(npm root -g) 看着优雅，但 node 版本管理器一切换路径就变，
+ *     全部断掉且极难排查。拷贝 + 回执 + doctor 漂移检查更稳。
+ */
+export declare const INSTALL_VERB = "install";
+export declare const UNINSTALL_VERB = "uninstall";
+export type HostId = 'claude' | 'codex';
+interface Host {
+    id: HostId | 'custom';
+    label: string;
+    /** skill 的父目录 —— 安装写到 <skillsDir>/<skill-name>/。 */
+    skillsDir: string;
+}
+/**
+ * 检测「这台机器上用了哪些 agent」。判据是配置根目录存在，而不是 skills/ 存在 ——
+ * 从没装过 skill 的用户 skills/ 本来就没有，那恰恰是最需要装的人。
+ */
+export declare function detectHosts(): Host[];
+export declare function installUsage(): void;
+export declare function uninstallUsage(): void;
+export declare function runInstall(argv: string[]): number;
+export declare function runUninstall(argv: string[]): number;
+export interface InstallState {
+    label: string;
+    skillsDir: string;
+    /** 回执里的版本；null = 该宿主下没有本 CLI 的安装。 */
+    installedVersion: string | null;
+    /** 当前包的版本，供报告直接引用。 */
+    currentVersion: string;
+    /** 回执版本与当前包版本不一致。 */
+    drifted: boolean;
+}
+/**
+ * 供 doctor 使用：每个宿主的安装状态。
+ *
+ * 漂移是这套方案唯一的静默失败模式 —— `npm update -g` 只动包，不动铺出去的副本，
+ * 用户会拿着旧 SKILL.md 打新后端。doctor 是「为什么跑不起来」的统一入口，检查放这里。
+ */
+export declare function installStates(): InstallState[];
+export {};

package/dist/install.js

@@ -0,0 +1,292 @@
+/**
+ * `remixmate install` / `remixmate uninstall` — 把包内 skills/ 铺进 agent 宿主。
+ *
+ * 为什么需要一条命令，而不是让站点给出 `cp -R "$(npm root -g)/…/skills/." ~/.claude/skills/`：
+ *
+ *   1. 目标已经不止一个。Claude Code 与 Codex 现在用同一套 SKILL.md 格式
+ *      （Codex 装到 $CODEX_HOME/skills/<name>），手工 cp 的心智成本直接翻倍。
+ *   2. 拷贝出去的副本没有主人。`npm update -g` 之后包升了级、副本停在旧版；
+ *      `npm uninstall -g` 之后副本原地变成孤儿。两种都是静默的 —— 本项目作者机器上
+ *      就留着一批 5 月建的、指向早已不存在路径的 skill 目录，没有任何东西负责清理。
+ *
+ * 所以这里的安装是**受管**的：每个宿主的 skills 目录下写一份装机回执
+ * (.remixmate-install.json)，记下版本、来源与这次铺下去的 skill 名单。升级照名单
+ * 覆盖、卸载照名单删除、doctor 照名单比对版本 —— 三件事都不靠猜目录里哪些是我们的。
+ *
+ * 刻意不做的两件事：
+ *   - 不挂 npm postinstall。`npm i -g` 时往 ~/.claude、~/.codex 写东西太越界，
+ *     且 `--ignore-scripts` 下会静默失效。安装必须是用户显式发起的动作。
+ *   - 不用软链。指向 $(npm root -g) 看着优雅，但 node 版本管理器一切换路径就变，
+ *     全部断掉且极难排查。拷贝 + 回执 + doctor 漂移检查更稳。
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SKILLS_DIR } from './registry.js';
+import { EXIT } from './errors.js';
+import { padDisplay } from './text.js';
+export const INSTALL_VERB = 'install';
+export const UNINSTALL_VERB = 'uninstall';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+/** 装机回执。升级 / 卸载 / 漂移检查都只认它。 */
+const RECEIPT = '.remixmate-install.json';
+const PACKAGE_NAME = '@remixmate/cli';
+/**
+ * 宿主的配置根目录。两个 agent 都允许用环境变量改位置，检测必须跟着走 ——
+ * 否则把 CODEX_HOME 指到别处的用户会看到「未检测到 Codex」。
+ */
+function hostHome(id) {
+    return id === 'claude'
+        ? process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')
+        : process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+const HOST_LABEL = {
+    claude: 'Claude Code',
+    codex: 'Codex',
+};
+function hostOf(id) {
+    return { id, label: HOST_LABEL[id], skillsDir: path.join(hostHome(id), 'skills') };
+}
+/**
+ * 检测「这台机器上用了哪些 agent」。判据是配置根目录存在，而不是 skills/ 存在 ——
+ * 从没装过 skill 的用户 skills/ 本来就没有，那恰恰是最需要装的人。
+ */
+export function detectHosts() {
+    return ['claude', 'codex'].filter((id) => existsSync(hostHome(id))).map(hostOf);
+}
+function packageVersion() {
+    try {
+        const raw = readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8');
+        return JSON.parse(raw).version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * 包内可安装的 skill 名单。
+ *
+ * 用 SKILLS_DIR 而不是 resolveBaseDir()：install 铺的永远是**本包自带**的那份，
+ * SKILL_BASE_DIR 是给 ab-agent 之类宿主在运行期改 skill 树用的，不该改变安装来源。
+ */
+function bundledSkills() {
+    if (!existsSync(SKILLS_DIR))
+        return [];
+    return readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(path.join(SKILLS_DIR, e.name, 'SKILL.md')))
+        .map((e) => e.name)
+        .sort();
+}
+function readReceipt(skillsDir) {
+    const file = path.join(skillsDir, RECEIPT);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        // 回执损坏时按「没装过」处理:那样只会退化成需要 --force,而不是把用户的目录删错。
+        return null;
+    }
+}
+function parseArgs(argv, verb) {
+    const out = { hosts: [], force: false, help: false };
+    const picked = [];
+    let dir = '';
+    let project = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const eq = a.indexOf('=');
+        const key = eq > 0 ? a.slice(0, eq) : a;
+        const inline = eq > 0 ? a.slice(eq + 1) : null;
+        const next = () => inline ?? argv[++i] ?? '';
+        switch (key) {
+            case '--host': {
+                const v = next();
+                if (v === 'all')
+                    picked.push('claude', 'codex');
+                else if (v === 'claude' || v === 'codex')
+                    picked.push(v);
+                else {
+                    out.unknown = `--host ${v}`;
+                    return out;
+                }
+                break;
+            }
+            case '--dir':
+                dir = next();
+                break;
+            case '--project':
+                project = true;
+                break;
+            case '--force':
+                out.force = true;
+                break;
+            case '-h':
+            case '--help':
+                out.help = true;
+                return out;
+            default:
+                out.unknown = a;
+                return out;
+        }
+    }
+    if (dir) {
+        out.hosts = [{ id: 'custom', label: '自定义目录', skillsDir: path.resolve(dir) }];
+    }
+    else if (project) {
+        // 只有 Claude Code 有项目级 skill 目录。Codex 的官方安装位置只有
+        // $CODEX_HOME/skills(见其内置 skill-installer),没有项目级约定,不臆造一个。
+        out.hosts = [{ id: 'claude', label: 'Claude Code（项目级）', skillsDir: path.join(process.cwd(), '.claude', 'skills') }];
+    }
+    else if (picked.length > 0) {
+        out.hosts = [...new Set(picked)].map(hostOf);
+    }
+    else {
+        out.hosts = verb === UNINSTALL_VERB ? ['claude', 'codex'].map(hostOf) : detectHosts();
+    }
+    return out;
+}
+export function installUsage() {
+    process.stdout.write('Usage: remixmate install [options]\n' +
+        '\n' +
+        '把本包自带的 skill 装进已检测到的 agent 宿主，让它们能自动发现这些能力\n' +
+        '（Claude Code: ~/.claude/skills，Codex: ~/.codex/skills）。重复运行即升级。\n' +
+        '\n' +
+        'Options:\n' +
+        '  --host <claude|codex|all>  只装指定宿主（默认：装到所有检测到的宿主）\n' +
+        '  --project                  装到当前目录 ./.claude/skills（仅 Claude Code）\n' +
+        '  --dir <path>               自定义 skills 父目录（覆盖上面两者）\n' +
+        '  --force                    覆盖同名的、非本 CLI 安装的 skill 目录\n');
+}
+export function uninstallUsage() {
+    process.stdout.write('Usage: remixmate uninstall [options]\n' +
+        '\n' +
+        '按装机回执删除本 CLI 装过的 skill —— 只删回执里列出的目录，不碰其它 skill。\n' +
+        '\n' +
+        'Options:\n' +
+        '  --host <claude|codex|all>  只卸载指定宿主（默认：两个宿主都查）\n' +
+        '  --project                  卸载当前目录 ./.claude/skills 下的安装\n' +
+        '  --dir <path>               自定义 skills 父目录\n');
+}
+function installInto(host, names, version, force) {
+    const prev = readReceipt(host.skillsDir);
+    const owned = new Set(prev?.skills ?? []);
+    // 目录已存在、又不在上一次的回执里 —— 那是别人的 skill(同名很容易撞:gen-image
+    // 这种名字一点也不独特)。默认拒绝而不是覆盖,让用户显式 --force。
+    const conflicts = names.filter((n) => existsSync(path.join(host.skillsDir, n)) && !owned.has(n));
+    if (conflicts.length > 0 && !force) {
+        return (`${host.skillsDir} 下已存在同名目录，且不是本 CLI 装的：${conflicts.join('、')}\n` +
+            '   确认可以覆盖后加 --force 重跑。');
+    }
+    mkdirSync(host.skillsDir, { recursive: true });
+    // 上一版装过、这一版没有了的 skill（上游改名或下线）要一并清掉，否则宿主会一直
+    // 加载一个已经没有后端支撑的 SKILL.md。
+    for (const stale of owned) {
+        if (!names.includes(stale))
+            rmSync(path.join(host.skillsDir, stale), { recursive: true, force: true });
+    }
+    for (const name of names) {
+        const dest = path.join(host.skillsDir, name);
+        // 先删再拷:直接覆盖会把上一版多出来的文件留在原地,攒出一个既非旧版也非新版的目录。
+        rmSync(dest, { recursive: true, force: true });
+        cpSync(path.join(SKILLS_DIR, name), dest, { recursive: true });
+    }
+    const receipt = {
+        package: PACKAGE_NAME,
+        version,
+        installedAt: new Date().toISOString(),
+        source: SKILLS_DIR,
+        skills: names,
+    };
+    writeFileSync(path.join(host.skillsDir, RECEIPT), JSON.stringify(receipt, null, 2) + '\n', 'utf-8');
+    return null;
+}
+export function runInstall(argv) {
+    const opts = parseArgs(argv, INSTALL_VERB);
+    if (opts.help) {
+        installUsage();
+        return EXIT.OK;
+    }
+    if (opts.unknown) {
+        process.stderr.write(`❌ 未知参数: ${opts.unknown}\n`);
+        installUsage();
+        return EXIT.USAGE;
+    }
+    const names = bundledSkills();
+    if (names.length === 0) {
+        process.stderr.write(`❌ 包内没有可安装的 skill（${SKILLS_DIR}）\n`);
+        return EXIT.ERROR;
+    }
+    if (opts.hosts.length === 0) {
+        process.stderr.write('❌ 没有检测到任何 agent 宿主。找过这两个位置：\n' +
+            `     Claude Code  ${hostHome('claude')}\n` +
+            `     Codex        ${hostHome('codex')}\n` +
+            '   先把 agent 装好再重跑，或用 --dir <path> 指定目录。\n');
+        return EXIT.USAGE;
+    }
+    const version = packageVersion();
+    let failures = 0;
+    for (const host of opts.hosts) {
+        const err = installInto(host, names, version, opts.force);
+        if (err) {
+            failures += 1;
+            process.stderr.write(`❌ ${padDisplay(host.label, 16)}${err}\n`);
+            continue;
+        }
+        process.stdout.write(`✅ ${padDisplay(host.label, 16)}${host.skillsDir}（${names.length} 个 skill，${version}）\n`);
+    }
+    if (failures > 0)
+        return EXIT.ERROR;
+    process.stdout.write('\n重启 agent 后即可生效。升级后重跑 remixmate install 覆盖即可。\n');
+    return EXIT.OK;
+}
+export function runUninstall(argv) {
+    const opts = parseArgs(argv, UNINSTALL_VERB);
+    if (opts.help) {
+        uninstallUsage();
+        return EXIT.OK;
+    }
+    if (opts.unknown) {
+        process.stderr.write(`❌ 未知参数: ${opts.unknown}\n`);
+        uninstallUsage();
+        return EXIT.USAGE;
+    }
+    let removed = 0;
+    for (const host of opts.hosts) {
+        const receipt = readReceipt(host.skillsDir);
+        if (!receipt)
+            continue;
+        for (const name of receipt.skills) {
+            rmSync(path.join(host.skillsDir, name), { recursive: true, force: true });
+        }
+        rmSync(path.join(host.skillsDir, RECEIPT), { force: true });
+        removed += 1;
+        process.stdout.write(`✅ ${padDisplay(host.label, 16)}已移除 ${receipt.skills.length} 个 skill（${host.skillsDir}）\n`);
+    }
+    if (removed === 0) {
+        process.stdout.write('没有找到本 CLI 的装机记录，无需卸载。\n');
+    }
+    return EXIT.OK;
+}
+/**
+ * 供 doctor 使用：每个宿主的安装状态。
+ *
+ * 漂移是这套方案唯一的静默失败模式 —— `npm update -g` 只动包，不动铺出去的副本，
+ * 用户会拿着旧 SKILL.md 打新后端。doctor 是「为什么跑不起来」的统一入口，检查放这里。
+ */
+export function installStates() {
+    const current = packageVersion();
+    return detectHosts().map((h) => {
+        const receipt = readReceipt(h.skillsDir);
+        return {
+            label: h.label,
+            skillsDir: h.skillsDir,
+            installedVersion: receipt?.version ?? null,
+            currentVersion: current,
+            drifted: receipt != null && receipt.version !== current,
+        };
+    });
+}

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.20",
-  "generatedAt": "2026-09-05T03:37:29.567Z",
+  "version": "0.9.22",
+  "generatedAt": "2026-09-06T10:24:59.463Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -302,21 +302,21 @@
       "ui": {
         "primary": [
           "prompt",
+          "reference",
           "model",
-          "size"
+          "size",
+          "n"
         ],
         "advanced": [
-          "n",
-          "reference",
-          "negative_prompt",
-          "image_strength"
+          "negative_prompt"
         ],
         "hidden": [
           "json_output",
+          "watermark",
+          "resolution",
           "seed",
           "guidance_scale",
-          "watermark",
-          "resolution"
+          "image_strength"
         ]
       }
     },
@@ -427,11 +427,12 @@
       },
       "ui": {
         "primary": [
-          "topic",
-          "platform",
-          "duration"
+          "topic"
         ],
-        "advanced": [
+        "advanced": [],
+        "hidden": [
+          "platform",
+          "duration",
           "style",
           "ratio",
           "scenes",
@@ -440,9 +441,7 @@
           "headline",
           "subheadline",
           "carousel_items",
-          "caption_lines"
-        ],
-        "hidden": [
+          "caption_lines",
           "stub_image_url",
           "stub_video_url",
           "skip_asset_generation"
@@ -459,7 +458,8 @@
       "triggers": [
         "Text-to-video, AI-generated clip, \"make a short video of ...\"",
         "Generate video with Doubao / Seedance",
-        "Image-to-video, first-frame / last-frame, reference-image-to-video"
+        "Image-to-video, first-frame / last-frame, reference-image-to-video",
+        "Reference video / reference audio, \"same camera move as this clip\", \"use this track\""
       ],
       "entry": {
         "type": "http",
@@ -510,6 +510,28 @@
             },
             "description": "Reference images: local file path, https URL, or data URI. Up to 9; combinable with first_frame / last_frame."
           },
+          "reference_video": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Reference videos (https URL only, must be publicly reachable). Up to 3. The model borrows their subject, camera work and style. Cannot be combined with first_frame / last_frame."
+          },
+          "reference_audio": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Reference audio (https URL only, must be publicly reachable). Up to 3. Borrows timbre, melody or dialogue. Needs at least one reference image or video alongside it; cannot be combined with first_frame / last_frame."
+          },
+          "web_search": {
+            "type": "boolean",
+            "description": "Let the model search the web for up-to-date subjects before generating. Text-only input — ignored once any image / video / audio is attached."
+          },
+          "return_last_frame": {
+            "type": "boolean",
+            "description": "Also return the generated clip's last frame, to chain it into the next shot"
+          },
           "generate_audio": {
             "type": "boolean",
             "description": "Generate native audio"
@@ -524,7 +546,7 @@
           },
           "seed": {
             "type": "number",
-            "description": "Random seed. Pass the same seed with the same prompt and model to make a run reproducible."
+            "description": "Random seed, -1 for random. Pass the same seed with the same prompt and model to make a run reproducible."
           },
           "person_generation": {
             "type": "string",
@@ -548,19 +570,23 @@
           "prompt",
           "model",
           "duration",
-          "ratio"
+          "ratio",
+          "resolution"
         ],
         "advanced": [
-          "resolution",
           "first_frame",
           "last_frame",
           "reference",
+          "reference_video",
+          "reference_audio",
           "generate_audio",
-          "camera_fixed"
+          "camera_fixed",
+          "web_search",
+          "return_last_frame",
+          "seed"
         ],
         "hidden": [
           "json_output",
-          "seed",
           "negative_prompt",
           "person_generation"
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.20",
+  "version": "0.9.22",
   "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/gen-image/skill.json

@@ -84,21 +84,21 @@
   "ui": {
     "primary": [
       "prompt",
+      "reference",
       "model",
-      "size"
+      "size",
+      "n"
     ],
     "advanced": [
-      "n",
-      "reference",
-      "negative_prompt",
-      "image_strength"
+      "negative_prompt"
     ],
     "hidden": [
       "json_output",
+      "watermark",
+      "resolution",
       "seed",
       "guidance_scale",
-      "watermark",
-      "resolution"
+      "image_strength"
     ]
   }
 }

package/skills/gen-script/skill.json

@@ -97,11 +97,12 @@
   },
   "ui": {
     "primary": [
-      "topic",
-      "platform",
-      "duration"
+      "topic"
     ],
-    "advanced": [
+    "advanced": [],
+    "hidden": [
+      "platform",
+      "duration",
       "style",
       "ratio",
       "scenes",
@@ -110,9 +111,7 @@
       "headline",
       "subheadline",
       "carousel_items",
-      "caption_lines"
-    ],
-    "hidden": [
+      "caption_lines",
       "stub_image_url",
       "stub_video_url",
       "skip_asset_generation"

package/skills/gen-video/SKILL.md

@@ -7,12 +7,14 @@ description: |
   - Text-to-video, AI-generated clip, "make a short video of ..."
   - Generate video with Doubao / Seedance
   - Image-to-video, first-frame / last-frame, reference-image-to-video
+  - Omni-modal reference: borrow the look of a reference image, the camera work of a reference video, or the voice / music of a reference audio clip
 
   Even without an explicit "use AI", any request that turns a description into a moving clip should route here.
 triggers:
   - Text-to-video, AI-generated clip, "make a short video of ..."
   - Generate video with Doubao / Seedance
   - Image-to-video, first-frame / last-frame, reference-image-to-video
+  - Reference video / reference audio, "same camera move as this clip", "use this track"
 ---
 
 # AI Video Generation Skill
@@ -52,10 +54,34 @@ so they are absent from the catalog and `--model veo` will fail.
 | **Duration** | 4–15 seconds (continuous integers) |
 | **First / last frame** | yes |
 | **Reference images** | yes, up to 9 |
+| **Reference videos** | yes, up to 3 (public https URLs) |
+| **Reference audio** | yes, up to 3 (public https URLs) |
 | **Generated audio** | yes |
 | **Fixed camera** | yes |
+| **Web search** | yes, text-only input |
 | **Negative prompt** | ignored (Veo-only parameter) |
 
+4k output exists on the standard tier upstream but is **not offered here** — the credit
+pricing table has no 4k row, so a 4k run would be billed at the 720p rate.
+
+### Two input modes, and they do not mix
+
+- **Pinned frames** — `--first-frame` / `--last-frame` fix the exact opening and closing
+  images. Reference images may be added alongside.
+- **Omni-modal reference** — `--reference` (images) / `--reference-video` / `--reference-audio`
+  hand the model material to borrow from; it decides the framing.
+
+Combining a pinned frame with a reference video or audio is rejected (by the CLI, and by the
+backend). Audio alone is not a valid input either: `--reference-audio` needs at least one
+reference image or video with it.
+
+In the prompt, refer to attachments as **"image 1" / "video 2" / "audio 1"**, numbered per
+type in the order you passed them. That is the only way the model can tell them apart —
+file names and asset ids mean nothing to it.
+
+Reference images and videos containing **real human faces are rejected upstream** by the
+Seedance 2.0 content filter; the run fails before it charges.
+
 ## Auth & environment
 
 No skill-local env file — the executing process inherits the system environment.
@@ -123,6 +149,31 @@ remixmate gen-video \
   --duration 8
 ```
 
+### Omni-modal reference (image + video + audio)
+
+Videos and audio must be public https URLs — unlike images they are not uploaded.
+
+```bash
+remixmate gen-video \
+  --prompt "Keep the first-person framing of video 1 and use audio 1 as the score; the product from image 1 is lifted toward the lens" \
+  --reference ./product.png \
+  --reference-video https://example.com/handheld.mp4 \
+  --reference-audio https://example.com/score.mp3 \
+  --duration 8 \
+  --generate-audio
+```
+
+### Fresh subjects (web search)
+
+Only fires on text-only input; attaching any image / video / audio turns it off.
+
+```bash
+remixmate gen-video \
+  --prompt "<a subject the model may not know: a new product, a current event>" \
+  --web-search \
+  --duration 5
+```
+
 ## Common CLI flags
 
 | Flag | Description | Default |
@@ -135,10 +186,14 @@ remixmate gen-video \
 | `--first-frame` | First-frame image: local path, https URL, or data URI | none |
 | `--last-frame` | Last-frame image | none |
 | `--reference` | Reference image (repeatable, max 9) | none |
+| `--reference-video` | Reference video, public https URL (repeatable, max 3) | none |
+| `--reference-audio` | Reference audio, public https URL (repeatable, max 3) | none |
 | `--generate-audio` | Generate native audio | off |
 | `--camera-fixed` | Fixed camera | off |
+| `--web-search` | Search the web first (text-only input) | off |
+| `--return-last-frame` | Also return the clip's last frame, to chain shots | off |
 | `--negative-prompt` | Negative prompt (Veo only; ignored by Seedance) | none |
-| `--seed` | Random seed | none |
+| `--seed` | Random seed; `-1` = random | none |
 | `--person-generation` | Person policy: `allow_all` / `dont_allow` (Veo) | none |
 | `--api-base-url` | Override API root | see above |
 | `--priv-token` | Override token | see above |

package/skills/gen-video/skill.json

@@ -55,6 +55,28 @@
         },
         "description": "Reference images: local file path, https URL, or data URI. Up to 9; combinable with first_frame / last_frame."
       },
+      "reference_video": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Reference videos (https URL only, must be publicly reachable). Up to 3. The model borrows their subject, camera work and style. Cannot be combined with first_frame / last_frame."
+      },
+      "reference_audio": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Reference audio (https URL only, must be publicly reachable). Up to 3. Borrows timbre, melody or dialogue. Needs at least one reference image or video alongside it; cannot be combined with first_frame / last_frame."
+      },
+      "web_search": {
+        "type": "boolean",
+        "description": "Let the model search the web for up-to-date subjects before generating. Text-only input — ignored once any image / video / audio is attached."
+      },
+      "return_last_frame": {
+        "type": "boolean",
+        "description": "Also return the generated clip's last frame, to chain it into the next shot"
+      },
       "generate_audio": {
         "type": "boolean",
         "description": "Generate native audio"
@@ -69,7 +91,7 @@
       },
       "seed": {
         "type": "number",
-        "description": "Random seed. Pass the same seed with the same prompt and model to make a run reproducible."
+        "description": "Random seed, -1 for random. Pass the same seed with the same prompt and model to make a run reproducible."
       },
       "person_generation": {
         "type": "string",
@@ -93,19 +115,23 @@
       "prompt",
       "model",
       "duration",
-      "ratio"
+      "ratio",
+      "resolution"
     ],
     "advanced": [
-      "resolution",
       "first_frame",
       "last_frame",
       "reference",
+      "reference_video",
+      "reference_audio",
       "generate_audio",
-      "camera_fixed"
+      "camera_fixed",
+      "web_search",
+      "return_last_frame",
+      "seed"
     ],
     "hidden": [
       "json_output",
-      "seed",
       "negative_prompt",
       "person_generation"
     ]