@remixmate/cli 0.9.17 → 0.9.19

package/dist/project/host.d.ts

@@ -46,7 +46,21 @@ export interface HostSession {
 }
 /** Identify the host and its root session id, or null when unrecognised. */
 export declare function detectHostSession(env?: NodeJS.ProcessEnv): HostSession | null;
-/** Host label for provenance, even when no session id could be read. */
+/**
+ * Normalise a declared host label.
+ *
+ * `video_project.client_host` is `varchar(32)`, and the value is rendered as a
+ * badge, so free-form input gets slugified rather than trusted: lowercase,
+ * non-alphanumerics collapsed to `-`, capped at 32. Anything that normalises to
+ * empty is treated as absent — an unusable label should degrade to "no badge",
+ * never to a garbage one.
+ */
+export declare function normaliseHostLabel(raw: string | undefined): string;
+/**
+ * Host label for provenance, even when no session id could be read.
+ *
+ * Declaration wins over detection: the declaring party knows, the table guesses.
+ */
 export declare function detectHostLabel(env?: NodeJS.ProcessEnv): string;
 export interface TakeKey {
     /** `<host>:<sessionId>`, or '' when nothing groups this invocation. */

package/dist/project/host.js

@@ -62,8 +62,51 @@ export function detectHostSession(env = process.env) {
     }
     return null;
 }
-/** Host label for provenance, even when no session id could be read. */
+/**
+ * Explicit host declaration, checked *before* the detection table.
+ *
+ * Two callers, both of which detection cannot serve:
+ *
+ *   - **WorkBuddy (ab-agent)** spawns this CLI itself. Sniffing our own process
+ *     would turn a fact we already know into a guess — and a fragile one, since
+ *     the generic variables it injects (CONVERSATION_ID …) are exactly the kind
+ *     another host might also set. It declares `REMIXMATE_HOST=workbuddy`.
+ *   - **Codex** does not expose anything: per the appendix-A survey it
+ *     "官方明确不通过环境变量暴露". No `detect()` we could write would be honest.
+ *     A user or the host itself can export `REMIXMATE_HOST=codex` and get the
+ *     provenance label without waiting for a CLI release.
+ *
+ * Symmetric with `REMIXMATE_TAKE_KEY`: that one overrides *grouping*, this one
+ * overrides *identity*. They are independent — declaring a host does not group,
+ * and grouping does not imply a host.
+ */
+const HOST_OVERRIDE_VAR = 'REMIXMATE_HOST';
+/**
+ * Normalise a declared host label.
+ *
+ * `video_project.client_host` is `varchar(32)`, and the value is rendered as a
+ * badge, so free-form input gets slugified rather than trusted: lowercase,
+ * non-alphanumerics collapsed to `-`, capped at 32. Anything that normalises to
+ * empty is treated as absent — an unusable label should degrade to "no badge",
+ * never to a garbage one.
+ */
+export function normaliseHostLabel(raw) {
+    return (raw ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32);
+}
+/**
+ * Host label for provenance, even when no session id could be read.
+ *
+ * Declaration wins over detection: the declaring party knows, the table guesses.
+ */
 export function detectHostLabel(env = process.env) {
+    const declared = normaliseHostLabel(env[HOST_OVERRIDE_VAR]);
+    if (declared)
+        return declared;
     return HOST_PROVIDERS.find((p) => p.detect(env))?.host ?? '';
 }
 /**
@@ -83,7 +126,9 @@ export function resolveTakeKey(jobId, env = process.env) {
     const host = detectHostLabel(env);
     const detected = detectHostSession(env);
     if (detected) {
-        return { key: `${detected.host}:${detected.sessionId}`, host: detected.host, source: 'host' };
+        // key 的命名空间用**探测到的**宿主，不用声明值：它是既有分组的命名空间，
+        // 跟着声明变会把同一会话的 take 拆成两组。而 host（溯源标签）以声明为准。
+        return { key: `${detected.host}:${detected.sessionId}`, host, source: 'host' };
     }
     const override = (env.REMIXMATE_TAKE_KEY ?? '').trim();
     if (override)

package/dist/registry.d.ts

@@ -20,6 +20,8 @@ export interface SkillDef {
     createsTake: boolean;
     /** Attach to an existing take, never create one — see skill-schema.ts. */
     joinsTake: boolean;
+    /** Argv keys that downgrade createsTake to joinsTake — see skill-schema.ts. */
+    createsTakeUnless: string[];
     skillDir: string;
     /** Absolute path to the python entry script (only when entry.type === 'python'). */
     scriptAbsolutePath?: string;

package/dist/registry.js

@@ -40,6 +40,7 @@ function loadOne(skillDir) {
         auth: resolveAuthMode(raw),
         createsTake: raw.createsTake === true,
         joinsTake: raw.joinsTake === true,
+        createsTakeUnless: Array.isArray(raw.createsTakeUnless) ? raw.createsTakeUnless : [],
         skillDir,
     };
     if (entry.type === 'python') {

package/dist/runner.d.ts

@@ -9,6 +9,7 @@
  *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
+import { type SkillDef } from './registry.js';
 import type { ParsedArgs } from './argv.js';
 export interface RunOptions {
     /** Override the skills directory (defaults to the package's bundled skills/). */
@@ -19,3 +20,20 @@ export interface RunOptions {
     parsedArgs: ParsedArgs;
 }
 export declare function runSkill(skillName: string, opts: RunOptions): Promise<number>;
+/** What this invocation is allowed to do about attribution. */
+export type TakeMode = 'create' | 'join' | 'none';
+/**
+ * Decide the take mode from the skill's declaration *and* what this particular
+ * invocation was asked to do.
+ *
+ * The manifest flags alone are not enough, because they describe the skill, not
+ * the call: `render-video --help` prints usage and exits, and
+ * `render-video --resolve-only` stops after asset resolution. Both used to run
+ * the full createsTake path, so a help query was enough to mint an empty take
+ * and lazily create 「未分类」 — the exact clutter project/take.ts sets out to
+ * avoid ("an empty VideoProject is worse clutter than an unattributed image").
+ *
+ * Note that a downgraded run still *joins*: when its own pipeline already
+ * started a take under the same grouping key, assets it generates stay attached.
+ */
+export declare function resolveTakeMode(skill: Pick<SkillDef, 'createsTake' | 'joinsTake' | 'createsTakeUnless'>, args: ParsedArgs): TakeMode;

package/dist/runner.js

@@ -61,6 +61,31 @@ export async function runSkill(skillName, opts) {
         emitBillingFooter();
     }
 }
+/**
+ * Decide the take mode from the skill's declaration *and* what this particular
+ * invocation was asked to do.
+ *
+ * The manifest flags alone are not enough, because they describe the skill, not
+ * the call: `render-video --help` prints usage and exits, and
+ * `render-video --resolve-only` stops after asset resolution. Both used to run
+ * the full createsTake path, so a help query was enough to mint an empty take
+ * and lazily create 「未分类」 — the exact clutter project/take.ts sets out to
+ * avoid ("an empty VideoProject is worse clutter than an unattributed image").
+ *
+ * Note that a downgraded run still *joins*: when its own pipeline already
+ * started a take under the same grouping key, assets it generates stay attached.
+ */
+export function resolveTakeMode(skill, args) {
+    // Introspection — the skill prints its usage and exits without producing
+    // anything, so it must not touch the backend at all.
+    if (args.help === true || args.h === true)
+        return 'none';
+    if (skill.createsTake) {
+        const downgraded = (skill.createsTakeUnless ?? []).some((key) => args[key] === true);
+        return downgraded ? 'join' : 'create';
+    }
+    return skill.joinsTake ? 'join' : 'none';
+}
 /**
  * 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
@@ -83,7 +108,8 @@ export async function runSkill(skillName, opts) {
  *     asset still uploads, just unattributed — exactly the old behaviour.
  */
 async function applyTakeContext(skill, opts, auth) {
-    if (!skill.createsTake && !skill.joinsTake)
+    const mode = resolveTakeMode(skill, opts.parsedArgs);
+    if (mode === 'none')
         return;
     if ((process.env.CONVERSATION_ID ?? '').trim())
         return;
@@ -95,7 +121,7 @@ async function applyTakeContext(skill, opts, auth) {
             preflightToken: auth.token,
         });
         let take;
-        if (skill.createsTake) {
+        if (mode === 'create') {
             const jobIdArg = opts.parsedArgs.job_id;
             const jobId = typeof jobIdArg === 'number' ? jobIdArg : Number(jobIdArg);
             const flagProject = opts.parsedArgs.project;

package/dist/skill-schema.d.ts

@@ -46,6 +46,28 @@ export declare const CATEGORY_VALUES: readonly ["authoring", "consuming", "asset
  */
 export type SkillAuthMode = 'required' | 'optional' | 'none';
 export declare const AUTH_VALUES: readonly ["required", "optional", "none"];
+/**
+ * 参数的**展示分级** —— 给人填表用的，不影响调度。
+ *
+ * `parameters` 是给 agent 的完整契约（十几个字段很正常）；把它整份渲染成表单
+ * 就是把门槛从"不知道说什么"换成"不知道填什么"。所以每个 skill 自己声明哪些
+ * 字段该直出、哪些折叠、哪些**根本不该给人看见**（`json_output` / `seed` 这类
+ * 是给调用方的开关，不是给人的选项）。
+ *
+ * 它和 schema 同住 skill.json，是刻意的：跨仓库的第二份名单必然漂移——
+ * ab-web 曾经用硬编码的 `ARCHETYPES` 常量对着后端字典表，最后两边对不上。
+ *
+ * 未声明的字段自动落进 `advanced`（见 build-manifest 的 resolveUiHints）：
+ * 新加一个参数时，最坏情况是它多显示了一层，而不是静默消失。
+ */
+export interface SkillUiHints {
+    /** 表单展开即可见 */
+    primary?: string[];
+    /** 折叠在「高级」里 */
+    advanced?: string[];
+    /** 不渲染给人类 */
+    hidden?: string[];
+}
 export interface RawSkillJson {
     name: string;
     toolName: string;
@@ -55,6 +77,8 @@ export interface RawSkillJson {
     category?: SkillCategory;
     auth?: SkillAuthMode;
     parameters?: Record<string, unknown>;
+    /** 参数的展示分级；缺省时按 required → primary、其余 → advanced 推导。 */
+    ui?: SkillUiHints;
     scriptPath?: string;
     entry?: SkillEntry;
     envVars?: string[];
@@ -72,6 +96,15 @@ export interface RawSkillJson {
      * worse clutter than an unattributed asset.
      */
     joinsTake?: boolean;
+    /**
+     * Parsed-argv keys (snake_case, as produced by argv.ts) whose presence means
+     * *this* invocation won't finish a video — `render-video --resolve-only`
+     * resolves assets and stops. Such a run degrades from createsTake to
+     * joinsTake: it still attaches to a take its own pipeline already started,
+     * but never brings one — nor the lazily created 「未分类」 — into being for a
+     * pass that may end in a contract error and no video at all.
+     */
+    createsTakeUnless?: string[];
 }
 /**
  * Resolve a skill's auth mode, defaulting for records that predate the field.
@@ -91,6 +124,13 @@ export declare const REQUIRED_SKILL_JSON_FIELDS: readonly ["name", "tier", "titl
  * skills keep working untouched. Returns null when neither is present.
  */
 export declare function normalizeEntry(raw: Pick<RawSkillJson, 'entry' | 'scriptPath'>): SkillEntry | null;
+/**
+ * 把 `ui` 声明补全成三个互斥的完整分桶。没声明 `ui` 时按 required 推导。
+ *
+ * **未提及的字段一律落进 advanced**：新增参数时最坏是多折一层，而不是消失。
+ * 返回 null 表示这个 skill 没有可填的参数（不该弹表单）。
+ */
+export declare function resolveUiHints(raw: Pick<RawSkillJson, 'parameters' | 'ui'>): Required<SkillUiHints> | null;
 /**
  * Validate a parsed skill.json against the directory it lives in. Returns an
  * array of problem strings; an empty array means the record is well-formed.

package/dist/skill-schema.js

@@ -41,6 +41,97 @@ export function normalizeEntry(raw) {
         return { type: 'python', scriptPath: raw.scriptPath };
     return null;
 }
+/** `parameters.properties` 的键；非对象 / 无 properties 时返回空数组。 */
+function parameterKeys(parameters) {
+    if (!parameters || typeof parameters !== 'object')
+        return [];
+    const props = parameters.properties;
+    if (!props || typeof props !== 'object')
+        return [];
+    return Object.keys(props);
+}
+/** `parameters.required`；缺失或格式不对时返回空数组。 */
+function requiredKeys(parameters) {
+    if (!parameters || typeof parameters !== 'object')
+        return [];
+    const req = parameters.required;
+    return Array.isArray(req) ? req.filter((k) => typeof k === 'string') : [];
+}
+/**
+ * 把 `ui` 声明补全成三个互斥的完整分桶。没声明 `ui` 时按 required 推导。
+ *
+ * **未提及的字段一律落进 advanced**：新增参数时最坏是多折一层，而不是消失。
+ * 返回 null 表示这个 skill 没有可填的参数（不该弹表单）。
+ */
+export function resolveUiHints(raw) {
+    const keys = parameterKeys(raw.parameters);
+    if (keys.length === 0)
+        return null;
+    if (!raw.ui) {
+        const required = new Set(requiredKeys(raw.parameters));
+        return {
+            primary: keys.filter((k) => required.has(k)),
+            advanced: keys.filter((k) => !required.has(k)),
+            hidden: [],
+        };
+    }
+    const declared = raw.ui;
+    const keySet = new Set(keys);
+    // 只保留真实存在的字段：schema 删了某个参数但 ui 忘了同步时，
+    // 不至于让下游渲染出一个没有定义的表单项。
+    const keep = (list) => (list ?? []).filter((k) => keySet.has(k));
+    const primary = keep(declared.primary);
+    const advanced = keep(declared.advanced);
+    const hidden = keep(declared.hidden);
+    const mentioned = new Set([...primary, ...advanced, ...hidden]);
+    return {
+        primary,
+        advanced: [...advanced, ...keys.filter((k) => !mentioned.has(k))],
+        hidden,
+    };
+}
+/**
+ * `ui` 分级的自检。三条规则，每条都对应一种"表单看起来正常但填不出东西"的坏状态。
+ */
+function validateUiHints(raw) {
+    if (raw.ui == null)
+        return [];
+    const errors = [];
+    if (typeof raw.ui !== 'object' || Array.isArray(raw.ui)) {
+        return ['skill.json.ui must be an object with primary / advanced / hidden arrays'];
+    }
+    const keys = new Set(parameterKeys(raw.parameters));
+    const seen = new Map(); // 字段 → 首次出现的桶
+    for (const bucket of ['primary', 'advanced', 'hidden']) {
+        const list = raw.ui[bucket];
+        if (list == null)
+            continue;
+        if (!Array.isArray(list) || list.some((k) => typeof k !== 'string' || k === '')) {
+            errors.push(`skill.json.ui.${bucket} must be an array of non-empty parameter names`);
+            continue;
+        }
+        for (const key of list) {
+            // 引用了不存在的参数：多半是 schema 改名后 ui 没跟着改。
+            if (!keys.has(key)) {
+                errors.push(`skill.json.ui.${bucket} references unknown parameter '${key}'`);
+            }
+            const first = seen.get(key);
+            if (first) {
+                errors.push(`skill.json.ui lists '${key}' in both '${first}' and '${bucket}'`);
+            }
+            else {
+                seen.set(key, bucket);
+            }
+        }
+    }
+    // 必填字段被藏起来 = 表单永远填不完整，且没有任何提示。
+    for (const key of requiredKeys(raw.parameters)) {
+        if (raw.ui.hidden?.includes(key)) {
+            errors.push(`skill.json.ui.hidden contains required parameter '${key}' — it could never be filled`);
+        }
+    }
+    return errors;
+}
 /**
  * Validate a parsed skill.json against the directory it lives in. Returns an
  * array of problem strings; an empty array means the record is well-formed.
@@ -67,6 +158,22 @@ export function validateSkillJson(raw, skillId) {
     if (raw.joinsTake != null && typeof raw.joinsTake !== 'boolean') {
         errors.push(`skill.json.joinsTake must be a boolean, got '${String(raw.joinsTake)}'`);
     }
+    if (raw.createsTakeUnless != null) {
+        if (!Array.isArray(raw.createsTakeUnless) ||
+            raw.createsTakeUnless.some((f) => typeof f !== 'string' || f === '')) {
+            errors.push("skill.json.createsTakeUnless must be an array of non-empty argv keys");
+        }
+        else if (raw.createsTake !== true) {
+            // It only ever downgrades createsTake; on any other skill it would read as
+            // working while doing nothing.
+            errors.push("skill.json.createsTakeUnless requires createsTake=true");
+        }
+        else if (raw.createsTakeUnless.some((f) => f.includes('-'))) {
+            // argv.ts hands the dispatcher snake_case keys, so `--resolve-only`
+            // arrives as `resolve_only`. A kebab entry would silently never match.
+            errors.push("skill.json.createsTakeUnless entries must be snake_case argv keys (e.g. 'resolve_only', not 'resolve-only')");
+        }
+    }
     if (raw.createsTake === true && raw.joinsTake === true) {
         errors.push("skill.json cannot set both 'createsTake' and 'joinsTake' — createsTake already implies joining");
     }
@@ -76,6 +183,7 @@ export function validateSkillJson(raw, skillId) {
     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");
     }
+    errors.push(...validateUiHints(raw));
     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.17",
+  "version": "0.9.19",
   "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/skill.json

@@ -6,21 +6,73 @@
   "title": "Jianying (CapCut) Draft Export",
   "description": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. Supports automatic conversion from a RenderPlan.",
   "auth": "required",
-  "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
+  "envVars": [
+    "PRIV_TOKEN",
+    "MM_API_BASE_URL",
+    "AGENT_NAME"
+  ],
   "scriptPath": "scripts/gen_jianying_draft.py",
   "parameters": {
     "type": "object",
     "properties": {
-      "from_render_plan": { "type": "string", "description": "Build the draft from a RenderPlan JSON (replaces --scenes)" },
-      "scenes": { "type": "string", "description": "Scene array as JSON (inline string or file path)" },
-      "title": { "type": "string", "description": "Draft title" },
-      "width": { "type": "number", "description": "Canvas width in pixels (default 1080)" },
-      "height": { "type": "number", "description": "Canvas height in pixels (default 1920)" },
-      "system": { "type": "string", "enum": ["mac", "windows"], "description": "Draft-root preset" },
-      "draft_root_path": { "type": "string", "description": "Explicit Jianying draft root path (overrides --system)" },
-      "no_download": { "type": "boolean", "description": "Do not download the ZIP; print the URL only" },
-      "output": { "type": "string", "description": "Local download path" }
+      "from_render_plan": {
+        "type": "string",
+        "description": "Build the draft from a RenderPlan JSON (replaces --scenes)"
+      },
+      "scenes": {
+        "type": "string",
+        "description": "Scene array as JSON (inline string or file path)"
+      },
+      "title": {
+        "type": "string",
+        "description": "Draft title"
+      },
+      "width": {
+        "type": "number",
+        "description": "Canvas width in pixels (default 1080)"
+      },
+      "height": {
+        "type": "number",
+        "description": "Canvas height in pixels (default 1920)"
+      },
+      "system": {
+        "type": "string",
+        "enum": [
+          "mac",
+          "windows"
+        ],
+        "description": "Draft-root preset"
+      },
+      "draft_root_path": {
+        "type": "string",
+        "description": "Explicit Jianying draft root path (overrides --system)"
+      },
+      "no_download": {
+        "type": "boolean",
+        "description": "Do not download the ZIP; print the URL only"
+      },
+      "output": {
+        "type": "string",
+        "description": "Local download path"
+      }
     },
     "required": []
+  },
+  "ui": {
+    "primary": [
+      "title"
+    ],
+    "advanced": [
+      "system",
+      "width",
+      "height",
+      "output"
+    ],
+    "hidden": [
+      "from_render_plan",
+      "scenes",
+      "draft_root_path",
+      "no_download"
+    ]
   }
 }

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

@@ -89,5 +89,28 @@
       }
     },
     "required": []
+  },
+  "ui": {
+    "primary": [
+      "avatar_id",
+      "text"
+    ],
+    "advanced": [
+      "source",
+      "voice_id",
+      "aspect_ratio",
+      "prompt",
+      "audio_url"
+    ],
+    "hidden": [
+      "json_output",
+      "list_avatars",
+      "mine",
+      "name",
+      "gender",
+      "check_status",
+      "generation_id",
+      "voice_name"
+    ]
   }
 }

package/skills/gen-image/skill.json

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