@gitruck/cli 0.2.10 → 0.2.12

package/dist/index.js

@@ -1892,11 +1892,11 @@ var require_index_umd = __commonJS((exports, module) => {
     };
     function __awaiter(thisArg, _arguments, P, generator) {
       function adopt(value) {
-        return value instanceof P ? value : new P(function(resolve3) {
-          resolve3(value);
+        return value instanceof P ? value : new P(function(resolve4) {
+          resolve4(value);
         });
       }
-      return new (P || (P = Promise))(function(resolve3, reject) {
+      return new (P || (P = Promise))(function(resolve4, reject) {
         function fulfilled(value) {
           try {
             step(generator.next(value));
@@ -1912,7 +1912,7 @@ var require_index_umd = __commonJS((exports, module) => {
           }
         }
         function step(result) {
-          result.done ? resolve3(result.value) : adopt(result.value).then(fulfilled, rejected);
+          result.done ? resolve4(result.value) : adopt(result.value).then(fulfilled, rejected);
         }
         step((generator = generator.apply(thisArg, _arguments || [])).next());
       });
@@ -4197,7 +4197,7 @@ var {
 
 // src/index.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import { join as join27 } from "node:path";
+import { join as join28 } from "node:path";
 
 // src/lib/paths.ts
 import { dirname, join } from "node:path";
@@ -4246,9 +4246,10 @@ function migrateLegacyHome() {
 }
 
 // src/commands/skills.ts
-import { homedir as homedir2 } from "node:os";
-import { join as join2 } from "node:path";
+import { spawnSync } from "node:child_process";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, cpSync as cpSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
 
 // src/lib/log.ts
 var c = {
@@ -4285,40 +4286,247 @@ var SKILL_NAMES = [
   "gtrk-ai-drama",
   "gtrk-style-maker",
   "gtrk-transcript",
-  "gtrk-tools"
+  "gtrk-tools",
+  "gtrk-music-visualizer"
 ];
-function installSkill(opts = {}) {
-  const destRoot = opts.dir ?? join2(homedir2(), ".claude", "skills");
+var SUPPLEMENTAL_AGENTS = [
+  {
+    id: "workbuddy",
+    displayName: "WorkBuddy",
+    dataDir: ".workbuddy"
+  },
+  {
+    id: "qoderwork",
+    displayName: "QoderWork",
+    dataDir: ".qoderwork"
+  },
+  {
+    id: "comate",
+    displayName: "Baidu Comate",
+    dataDir: ".comate"
+  }
+];
+var SUPPLEMENTAL_AGENT_IDS = new Set(SUPPLEMENTAL_AGENTS.map((agent) => agent.id));
+var AGENT_ALIASES = {
+  claude: "claude-code",
+  "trae-global": "trae",
+  "tencent-workbuddy": "workbuddy",
+  "qoder-work": "qoderwork",
+  "baidu-comate": "comate",
+  "wenxin-comate": "comate",
+  qwen: "qwen-code",
+  kimi: "kimi-code-cli",
+  "kimi-code": "kimi-code-cli",
+  iflow: "iflow-cli",
+  codearts: "codearts-agent",
+  "tongyi-lingma": "lingma",
+  "tencent-codebuddy": "codebuddy"
+};
+var SAFE_AGENT_ID = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
+var ANSI_ESCAPE = /\x1B\[[0-?]*[ -/]*[@-~]/gu;
+var PROMPTSCRIPT_GLOBAL_ERROR = "PromptScript: PromptScript does not support global skill installation";
+function parseAgentIds(input) {
+  const values = (input ?? "").split(/[\s,]+/u).map((value) => value.trim().toLowerCase()).filter(Boolean).map((value) => AGENT_ALIASES[value] ?? value);
+  const invalid = values.filter((value) => !SAFE_AGENT_ID.test(value));
+  if (invalid.length > 0) {
+    throw new Error(`Agent ID 格式不合法：${invalid.join(", ")}`);
+  }
+  return [...new Set(values)];
+}
+function splitAgentSelection(input) {
+  const requested = parseAgentIds(input);
+  return {
+    requested,
+    upstream: requested.filter((id) => !SUPPLEMENTAL_AGENT_IDS.has(id)),
+    supplemental: requested.filter((id) => SUPPLEMENTAL_AGENT_IDS.has(id))
+  };
+}
+function resolveSupplementalAgentTargets(opts = {}, home = homedir2(), pathExists = existsSync2) {
+  const selection = splitAgentSelection(opts.agents);
+  const explicitIds = new Set(selection.supplemental);
+  return SUPPLEMENTAL_AGENTS.filter((agent) => {
+    if (opts.all)
+      return true;
+    if (selection.requested.length > 0)
+      return explicitIds.has(agent.id);
+    return pathExists(join2(home, agent.dataDir));
+  }).map((agent) => ({
+    id: agent.id,
+    displayName: agent.displayName,
+    destRoot: join2(home, agent.dataDir, "skills")
+  }));
+}
+function plainTerminalLine(line2) {
+  return line2.replace(ANSI_ESCAPE, "").trim();
+}
+function filterKnownAdapterOutput(output) {
+  const newline = output.includes(`\r
+`) ? `\r
+` : `
+`;
+  const lines = output.split(/\r?\n/u);
+  const failureStart = lines.findIndex((line2) => plainTerminalLine(line2).includes("Failed to install"));
+  if (failureStart < 0)
+    return { output, suppressedPromptScriptFailures: 0 };
+  const doneIndex = lines.findIndex((line2, index) => index > failureStart && plainTerminalLine(line2).includes("Done!"));
+  if (doneIndex < 0)
+    return { output, suppressedPromptScriptFailures: 0 };
+  const failureLines = lines.slice(failureStart, doneIndex).map(plainTerminalLine).filter((line2) => line2.includes("✗"));
+  if (failureLines.length === 0 || failureLines.some((line2) => !line2.includes(PROMPTSCRIPT_GLOBAL_ERROR))) {
+    return { output, suppressedPromptScriptFailures: 0 };
+  }
+  let removeStart = failureStart;
+  while (removeStart > 0) {
+    const previous = plainTerminalLine(lines[removeStart - 1] ?? "");
+    if (previous !== "" && previous !== "│" && previous !== "|")
+      break;
+    removeStart -= 1;
+  }
+  let removeEnd = doneIndex + 1;
+  while (removeEnd < lines.length && plainTerminalLine(lines[removeEnd] ?? "") === "") {
+    removeEnd += 1;
+  }
+  return {
+    output: [...lines.slice(0, removeStart), ...lines.slice(removeEnd)].join(newline),
+    suppressedPromptScriptFailures: failureLines.length
+  };
+}
+function buildSkillsAdapterArgs(source, opts = {}) {
+  const args = ["-y", "skills", "add", source, "-g", "-y"];
+  if (opts.all) {
+    args.push("--all");
+  } else {
+    for (const agent of splitAgentSelection(opts.agents).upstream) {
+      args.push("--agent", agent);
+    }
+  }
+  if (opts.copy)
+    args.push("--copy");
+  return args;
+}
+function npxInvocation(args) {
+  const npmExecPath = process.env.npm_execpath;
+  const candidates = [
+    npmExecPath && join2(dirname2(npmExecPath), "npx-cli.js"),
+    join2(dirname2(process.execPath), "node_modules", "npm", "bin", "npx-cli.js"),
+    resolve(dirname2(process.execPath), "..", "lib", "node_modules", "npm", "bin", "npx-cli.js")
+  ].filter((value) => Boolean(value));
+  const npxCli = candidates.find((value) => existsSync2(value));
+  if (npxCli)
+    return { command: process.execPath, args: [npxCli, ...args], shell: false };
+  return { command: "npx", args, shell: process.platform === "win32" };
+}
+function validateBundledSkills(source) {
   let allOk = true;
   for (const name of SKILL_NAMES) {
-    const src = join2(packageRoot(), "skills", name);
-    if (!existsSync2(join2(src, "SKILL.md"))) {
-      log.warn(`找不到打包的 skill 源：${join2(src, "SKILL.md")}（跳过 ${name}，不影响命令行）`);
+    const manifest = join2(source, name, "SKILL.md");
+    if (!existsSync2(manifest)) {
+      log.warn(`找不到打包的 skill 源：${manifest}（跳过 ${name}，不影响命令行）`);
       allOk = false;
-      continue;
     }
+  }
+  return allOk;
+}
+function copySkillsToTarget(dir, source, targetLabel) {
+  const destRoot = resolve(dir);
+  let allOk = validateBundledSkills(source);
+  for (const name of SKILL_NAMES) {
+    const src = join2(source, name);
+    if (!existsSync2(join2(src, "SKILL.md")))
+      continue;
     const dest = join2(destRoot, name);
     try {
       mkdirSync2(dest, { recursive: true });
       cpSync2(src, dest, { recursive: true });
-      log.ok(`已安装 /${name} → ${join2(dest, "SKILL.md")}`);
-    } catch (e) {
+      log.ok(`已安装 ${name}${targetLabel ? ` → ${targetLabel}` : ""}：${join2(dest, "SKILL.md")}`);
+    } catch (error) {
       allOk = false;
-      log.warn(`skill 安装失败（${name}，不影响命令行使用）：${e instanceof Error ? e.message : String(e)}`);
+      log.warn(`skill 安装失败（${name}，不影响命令行使用）：${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  log.info("在 Claude Code 里打 /gtrk-oralcut、/gtrk-transcript 或 /gtrk-tools，也可直接说「帮我剪个口播 / 把本地视频转成文字稿 / 给视频声音降噪」触发（可能需重载会话）。");
+  if (targetLabel) {
+    log.info(`已写入 ${targetLabel}；若当前会话未出现新 Skill，请重启或刷新该 Agent。`);
+  } else {
+    log.info("已写入自定义 skills 目录；具体调用入口以该 Agent 的界面为准。");
+  }
   return allOk;
 }
+function copySkillsToDirectory(dir, source = join2(packageRoot(), "skills")) {
+  return copySkillsToTarget(dir, source);
+}
+function installSkill(opts = {}) {
+  const source = resolve(opts.source ?? join2(packageRoot(), "skills"));
+  if (opts.dir)
+    return copySkillsToDirectory(opts.dir, source);
+  let selection;
+  try {
+    selection = splitAgentSelection(opts.agents);
+  } catch (error) {
+    log.err(error instanceof Error ? error.message : String(error));
+    return false;
+  }
+  const sourcesOk = validateBundledSkills(source);
+  const shouldRunAdapter = opts.all || selection.requested.length === 0 || selection.upstream.length > 0;
+  let adapterOk = true;
+  if (shouldRunAdapter) {
+    const args = buildSkillsAdapterArgs(source, {
+      ...opts,
+      agents: selection.upstream.join(",")
+    });
+    log.info("使用通用 Agent Skills 适配器：自动探测宿主、统一存储，并链接到各 Agent。");
+    const invocation = npxInvocation(args);
+    const result = spawnSync(invocation.command, invocation.args, {
+      stdio: ["inherit", "pipe", "pipe"],
+      shell: invocation.shell,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024
+    });
+    const defaultAutoInstall = !opts.all && selection.requested.length === 0;
+    const filtered = defaultAutoInstall ? filterKnownAdapterOutput(result.stdout ?? "") : { output: result.stdout ?? "", suppressedPromptScriptFailures: 0 };
+    if (filtered.output) {
+      process.stdout.write(filtered.output);
+      if (!filtered.output.endsWith(`
+`))
+        process.stdout.write(`
+`);
+    }
+    if (result.stderr)
+      process.stderr.write(result.stderr);
+    if (filtered.suppressedPromptScriptFailures > 0) {
+      log.info("已跳过 PromptScript：它只支持项目级 Skill，不参与本次全局安装；其他 Agent 不受影响。");
+    }
+    if (result.error) {
+      adapterOk = false;
+      log.warn(`无法启动 skills 适配器：${result.error.message}`);
+      log.info(`可手动重试：npx -y skills add "${source}" -g -y`);
+    } else if (result.status !== 0) {
+      adapterOk = false;
+      log.warn(`skills 适配器安装失败（退出码 ${result.status ?? "未知"}）。`);
+      log.info(`可查看支持的 Agent ID：npx -y skills add "${source}" --list`);
+    }
+  }
+  let supplementalOk = true;
+  const supplementalTargets = resolveSupplementalAgentTargets(opts, opts.home ?? homedir2());
+  for (const target of supplementalTargets) {
+    log.info(`使用 gtrk 补充适配：${target.displayName} → ${target.destRoot}`);
+    if (!copySkillsToTarget(target.destRoot, source, target.displayName))
+      supplementalOk = false;
+  }
+  if (adapterOk && supplementalOk) {
+    log.info("若当前会话没有立刻出现新 skill，请刷新窗口或新开一个会话。");
+  }
+  return sourcesOk && adapterOk && supplementalOk;
+}
 function registerSkills(program2) {
-  const skills = program2.command("skills").description("管理 agent skill（安装到 Claude Code）");
-  skills.command("install").description("把 gtrk 全家框架 skill 安装到 ~/.claude/skills（对标飞书 skills add）").option("--dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").action((opts) => {
-    installSkill({ dir: opts.dir });
+  const skills = program2.command("skills").description("管理跨 Agent Skills（通用适配器 + gtrk 补充宿主）");
+  skills.command("install").description("把 gtrk 全家框架 skill 安装到自动检测或指定的 Agent").option("--agents <list>", "指定 Agent ID，逗号分隔，如 codex,trae-cn,workbuddy,comate").option("--all", "安装到上游和 gtrk 已登记的全部 Agent").option("--copy", "每个 Agent 各复制一份（默认统一存储 + symlink/junction）").option("--dir <dir>", "兼容模式：直接复制到单个 skills 目录，绕过 Agent 适配器").action((opts) => {
+    if (!installSkill(opts))
+      process.exitCode = 1;
   });
 }
 
 // src/commands/init.ts
-import { join as join9, resolve as resolve2 } from "node:path";
+import { join as join9, resolve as resolve3 } from "node:path";
 import { existsSync as existsSync8 } from "node:fs";
 
 // src/lib/user-config.ts
@@ -4346,7 +4554,7 @@ function writeUserConfig(patch) {
 }
 
 // src/lib/jianying.ts
-import { join as join4, resolve } from "node:path";
+import { join as join4, resolve as resolve2 } from "node:path";
 import { existsSync as existsSync4 } from "node:fs";
 function probeJianyingDraftDir() {
   const local = process.env.LOCALAPPDATA;
@@ -4360,7 +4568,7 @@ function probeJianyingDraftDir() {
 }
 function resolveJianyingDraftDir(opt) {
   if (opt && opt !== "auto")
-    return resolve(opt);
+    return resolve2(opt);
   const saved = readUserConfig().jianyingDraftDir;
   if (saved && existsSync4(saved))
     return saved;
@@ -4387,7 +4595,7 @@ function launch(cmd) {
 
 // src/lib/prompt.ts
 import { stdin, stdout } from "node:process";
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 var c2 = {
   dim: (s) => `\x1B[2m${s}\x1B[0m`,
   cyan: (s) => `\x1B[36m${s}\x1B[0m`
@@ -4395,24 +4603,24 @@ var c2 = {
 function readClipboard() {
   try {
     if (process.platform === "win32") {
-      const r = spawnSync("powershell", ["-NoProfile", "-Command", "Get-Clipboard"], {
+      const r = spawnSync2("powershell", ["-NoProfile", "-Command", "Get-Clipboard"], {
         encoding: "utf8"
       });
       return (r.stdout ?? "").replace(/\r?\n$/, "");
     }
     if (process.platform === "darwin") {
-      return spawnSync("pbpaste", { encoding: "utf8" }).stdout ?? "";
+      return spawnSync2("pbpaste", { encoding: "utf8" }).stdout ?? "";
     }
-    const x = spawnSync("xclip", ["-selection", "clipboard", "-o"], { encoding: "utf8" });
+    const x = spawnSync2("xclip", ["-selection", "clipboard", "-o"], { encoding: "utf8" });
     if (x.status === 0)
       return x.stdout ?? "";
-    return spawnSync("wl-paste", ["-n"], { encoding: "utf8" }).stdout ?? "";
+    return spawnSync2("wl-paste", ["-n"], { encoding: "utf8" }).stdout ?? "";
   } catch {
     return "";
   }
 }
 function ask(message, opts = {}) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const hint = opts.defaultValue ? c2.dim(` (${opts.defaultValue})`) : "";
     stdout.write(`${c2.cyan("?")} ${message}${hint} `);
     let value = "";
@@ -4433,7 +4641,7 @@ function ask(message, opts = {}) {
           stdout.write(`
 `);
           cleanup();
-          resolve2(value || opts.defaultValue || "");
+          resolve3(value || opts.defaultValue || "");
           return;
         }
         if (ch === "\x03") {
@@ -5140,7 +5348,7 @@ function effectiveVocab(config) {
 }
 
 // src/lib/ffmpeg.ts
-import { spawn as spawn2, spawnSync as spawnSync2 } from "node:child_process";
+import { spawn as spawn2, spawnSync as spawnSync3 } from "node:child_process";
 import { existsSync as existsSync6 } from "node:fs";
 import { join as join6 } from "node:path";
 var isWin = process.platform === "win32";
@@ -5149,7 +5357,7 @@ var FFMPEG_INSTALL_HINT = `未找到 ffmpeg/ffprobe。请把二者放到 ${ffmpe
 var _cache = new Map;
 function onSystemPath(cmd) {
   try {
-    return spawnSync2(cmd, ["-version"], { stdio: "ignore" }).status === 0;
+    return spawnSync3(cmd, ["-version"], { stdio: "ignore" }).status === 0;
   } catch {
     return false;
   }
@@ -5184,14 +5392,14 @@ function requireFfmpeg(ffmpegPath) {
   return r;
 }
 function ffprobeJson(ffprobePath, args) {
-  const r = spawnSync2(ffprobePath, args, { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+  const r = spawnSync3(ffprobePath, args, { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
   if (r.status !== 0) {
     throw new Error(`ffprobe 失败（code=${r.status}）：${(r.stderr || "").slice(-300)}`);
   }
   return JSON.parse(r.stdout || "{}");
 }
 function runFfmpeg(ffmpegPath, args, onLine) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const p = spawn2(ffmpegPath, args, { env: process.env });
     let tail = "";
     p.stderr.on("data", (buf) => {
@@ -5206,20 +5414,20 @@ function runFfmpeg(ffmpegPath, args, onLine) {
     p.on("error", (e) => reject(e));
     p.on("close", (code) => {
       if (code === 0)
-        resolve2();
+        resolve3();
       else
         reject(new Error(`ffmpeg 退出码 ${code}：${tail.slice(-600)}`));
     });
   });
 }
 function probeCapabilities(res) {
-  const ver = spawnSync2(res.ffmpeg, ["-version"], { encoding: "utf8" });
+  const ver = spawnSync3(res.ffmpeg, ["-version"], { encoding: "utf8" });
   const version = (ver.stdout || "").split(/\r?\n/)[0]?.trim() || "unknown";
-  const enc = spawnSync2(res.ffmpeg, ["-hide_banner", "-encoders"], {
+  const enc = spawnSync3(res.ffmpeg, ["-hide_banner", "-encoders"], {
     encoding: "utf8",
     maxBuffer: 16 * 1024 * 1024
   });
-  const fil = spawnSync2(res.ffmpeg, ["-hide_banner", "-filters"], {
+  const fil = spawnSync3(res.ffmpeg, ["-hide_banner", "-filters"], {
     encoding: "utf8",
     maxBuffer: 16 * 1024 * 1024
   });
@@ -5453,7 +5661,7 @@ async function runInit(opts) {
     const manual = (await promptText("剪映草稿根目录（…\\com.lveditor.draft），留空跳过：")).trim();
     if (manual) {
       if (existsSync8(manual))
-        jianyingDraftDir = resolve2(manual);
+        jianyingDraftDir = resolve3(manual);
       else
         log.warn(`目录不存在，已跳过：${manual}`);
     }
@@ -5476,7 +5684,7 @@ async function afterConfigDoctor() {
   if (healthy) {
     log.step("装好了！两种用法任选：");
     log.info('① 命令行直接剪：gtrk oralcut "<毛片.mp4>" --script "<文字稿.txt>"（无稿就别加 --script）');
-    log.info("② 重启你常用的 AI agent（Claude / Codex / Trae / WorkBuddy 等），用 /gtrk-oralcut <你的口播剪辑需求>，一句话交给它，体验更智能的剪辑~");
+    log.info("② 刷新你常用的 AI Agent，在它的 Skills 入口选择或点名 gtrk-oralcut；不同客户端也都可以直接描述剪辑需求触发。");
     log.info("想有自己栏目的风格体系？在 agent 里跑 /gtrk-style-maker 建一次「你的厨房」（skill 家族 + 栏目配置）；不建就直接用默认，照常开剪。");
   } else {
     log.warn("上面体检有项没通，按提示处理好再开剪（多半是 API Key 或剪映目录）。");
@@ -5494,7 +5702,7 @@ async function runInitNonInteractive(opts) {
   let jianyingDraftDir;
   const dirOpt = opts.jianyingDraftDir;
   if (dirOpt && dirOpt !== "auto")
-    jianyingDraftDir = resolve2(dirOpt);
+    jianyingDraftDir = resolve3(dirOpt);
   else if (dirOpt === "auto" || !existing.jianyingDraftDir)
     jianyingDraftDir = probeJianyingDraftDir();
   else
@@ -5510,16 +5718,23 @@ async function runInitNonInteractive(opts) {
 
 // src/commands/install.ts
 function registerInstall(program2) {
-  program2.command("install").description("一条命令装全：安装 /gtrk-oralcut skill + 配置（对标飞书 lark-cli install）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("--skills-dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").option("--reconfigure", "重走配置向导（默认：已配过则保留现有配置、只刷新 skill）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(async (opts) => {
+  program2.command("install").description("一条命令装全：安装 /gtrk-oralcut skill + 配置（对标飞书 lark-cli install）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("--skills-dir <dir>", "自定义单个 skills 目录（优先于 Agent 自动检测）").option("--skill-agents <list>", "skills CLI Agent ID，逗号分隔，如 codex,cursor,trae-cn").option("--all-agents", "把 skill 安装到上游和 gtrk 已登记的全部 Agent").option("--copy-skills", "每个 Agent 各复制一份（默认统一存储 + symlink/junction）").option("--reconfigure", "重走配置向导（默认：已配过则保留现有配置、只刷新 skill）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(async (opts) => {
     log.step("① 安装 / 刷新 agent skill…");
-    installSkill({ dir: opts.skillsDir });
+    const skillsOk = installSkill({
+      dir: opts.skillsDir,
+      agents: opts.skillAgents,
+      all: opts.allAgents,
+      copy: opts.copySkills
+    });
+    if (!skillsOk)
+      process.exitCode = 1;
     log.step("② 配置 + 体检…");
     await runInit(opts);
   });
 }
 
 // src/commands/oralcut.ts
-import { resolve as resolve3, join as join14, dirname as dirname2, basename as basename5, extname as extname2 } from "node:path";
+import { resolve as resolve4, join as join14, dirname as dirname3, basename as basename5, extname as extname2 } from "node:path";
 import { mkdir as mkdir4, writeFile as writeFile5, readFile as readFile3 } from "node:fs/promises";
 import { existsSync as existsSync12 } from "node:fs";
 
@@ -6007,7 +6222,7 @@ var defaultDeps = {
   uploadCached,
   invalidateUpload,
   submitTask,
-  sleep: (ms) => new Promise((resolve3) => setTimeout(resolve3, ms))
+  sleep: (ms) => new Promise((resolve4) => setTimeout(resolve4, ms))
 };
 async function submitFreshFile(cfg, taskType, fileId, buildPayload, backoffMs, deps) {
   for (let attempt = 0;; attempt++) {
@@ -6532,7 +6747,7 @@ async function runOralCut(input, opts) {
   if (opts.json)
     routeLogsToStderr();
   const cfg = loadConfig();
-  const inputAbs = resolve3(input);
+  const inputAbs = resolve4(input);
   if (!existsSync12(inputAbs))
     throw new Error(`毛片不存在：${inputAbs}`);
   const projName = basename5(inputAbs, extname2(inputAbs));
@@ -6540,10 +6755,10 @@ async function runOralCut(input, opts) {
   if (opts.render && !formats.includes("gtrk"))
     formats.push("gtrk");
   const wantJianying = formats.some((f) => f === "jianying" || f === "capcut");
-  const outDir = resolve3(opts.out ?? join14(dirname2(inputAbs), `${projName}-video-project-${timestamp()}`));
-  let scriptPath = opts.script ? resolve3(opts.script) : undefined;
+  const outDir = resolve4(opts.out ?? join14(dirname3(inputAbs), `${projName}-video-project-${timestamp()}`));
+  let scriptPath = opts.script ? resolve4(opts.script) : undefined;
   if (!scriptPath) {
-    const sibling = join14(dirname2(inputAbs), `${projName}.txt`);
+    const sibling = join14(dirname3(inputAbs), `${projName}.txt`);
     if (existsSync12(sibling)) {
       scriptPath = sibling;
       log.info(`自动识别到同名文稿：${sibling}（按有稿剪辑；不想用就改名或显式 --script）`);
@@ -6629,7 +6844,7 @@ async function runOralCut(input, opts) {
 }
 
 // src/commands/oralcut-result.ts
-import { resolve as resolve4, join as join15 } from "node:path";
+import { resolve as resolve5, join as join15 } from "node:path";
 var TASK_TYPE2 = "cli/video_oral_cut_for_cli";
 function timestamp2() {
   const d = new Date;
@@ -6663,7 +6878,7 @@ async function runOralCutResult(taskId, opts) {
     const pct = got.progress != null ? ` ${Math.round(got.progress)}%` : "";
     throw new Error(`任务尚未完成（当前 ${got.status || "未知"}${pct}），暂无法取回结果；请稍后再试。`);
   }
-  const outDir = resolve4(opts.out ?? join15(process.cwd(), `${taskId}-video-project-${timestamp2()}`));
+  const outDir = resolve5(opts.out ?? join15(process.cwd(), `${taskId}-video-project-${timestamp2()}`));
   const draftDir = resolveJianyingDraftDir(opts.jianyingDraftDir);
   await materializeResult({
     outDir,
@@ -6681,10 +6896,10 @@ async function runOralCutResult(taskId, opts) {
 }
 
 // src/commands/upgrade.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
+import { spawnSync as spawnSync4 } from "node:child_process";
 var CLIENT_UPGRADE = "irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex";
 function run(cmd) {
-  const r = spawnSync3(cmd, { stdio: "inherit", shell: true });
+  const r = spawnSync4(cmd, { stdio: "inherit", shell: true });
   return r.status ?? 1;
 }
 function registerUpgrade(program2) {
@@ -6713,7 +6928,7 @@ function registerUpgrade(program2) {
       process.exitCode = 1;
       return;
     }
-    log.step("② 刷新 /gtrk-oralcut skill…");
+    log.step("② 通过通用适配器刷新 Agent Skills…");
     if (run("gtrk skills install") !== 0) {
       log.warn("skill 没刷成，手动跑一次：gtrk skills install");
     }
@@ -6723,16 +6938,16 @@ function registerUpgrade(program2) {
 }
 
 // src/commands/render.ts
-import { resolve as resolve5, dirname as dirname3, join as join16, basename as basename6, extname as extname3 } from "node:path";
+import { resolve as resolve6, dirname as dirname4, join as join16, basename as basename6, extname as extname3 } from "node:path";
 import { existsSync as existsSync13 } from "node:fs";
 function registerRender(program2) {
   program2.command("render <gtrk>").description("本地渲染：gtrk 工程按 EDL 用本地 ffmpeg 渲染成片 mp4（素材取原片本地路径）").option("-o, --out <file>", "输出 mp4 路径（缺省 = <gtrk 同目录>/<gtrk 名>.mp4）").option("--crf <n>", "视频质量 CRF 14-28（越小越清晰/文件越大，默认 18）").option("--codec <c>", "视频编码（默认 h264）").option("--ffmpeg-path <dir>", "指定 ffmpeg/ffprobe 所在目录（缺省 ~/.gitruck/ffmpeg → 系统）").option("--no-open", "完成后不自动打开产物目录").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (gtrk, opts) => {
     if (opts.json)
       routeLogsToStderr();
-    const gtrkAbs = resolve5(gtrk);
+    const gtrkAbs = resolve6(gtrk);
     if (!existsSync13(gtrkAbs))
       throw new Error(`gtrk 工程不存在：${gtrkAbs}`);
-    const outMp4 = resolve5(opts.out ?? join16(dirname3(gtrkAbs), `${basename6(gtrkAbs, extname3(gtrkAbs))}.mp4`));
+    const outMp4 = resolve6(opts.out ?? join16(dirname4(gtrkAbs), `${basename6(gtrkAbs, extname3(gtrkAbs))}.mp4`));
     log.step(`▶ 本地渲染：${basename6(gtrkAbs)} → ${basename6(outMp4)}`);
     const project = await readGtrkFile(gtrkAbs);
     const result = await renderGtrk(project, outMp4, {
@@ -6748,7 +6963,7 @@ function registerRender(program2) {
     log.tickEnd();
     log.ok(`渲染完成：${outMp4}（${result.duration.toFixed(1)}s）`);
     if (opts.open)
-      openFolder(dirname3(outMp4));
+      openFolder(dirname4(outMp4));
     if (opts.json) {
       console.log(JSON.stringify({ ok: true, output: outMp4, duration: result.duration }));
     }
@@ -6756,7 +6971,7 @@ function registerRender(program2) {
 }
 
 // src/commands/split.ts
-import { resolve as resolve6, join as join18, dirname as dirname5, basename as basename8 } from "node:path";
+import { resolve as resolve7, join as join18, dirname as dirname6, basename as basename8 } from "node:path";
 import { existsSync as existsSync14 } from "node:fs";
 import { readFile as readFile4, writeFile as writeFile6, mkdir as mkdir5 } from "node:fs/promises";
 import { createHash } from "node:crypto";
@@ -6881,7 +7096,7 @@ function projectTranscript(transcript, gtrk, opts = {}) {
 
 // src/lib/gtrk-writeback.ts
 import { readFileSync as readFileSync4, statSync, writeFileSync as writeFileSync2, renameSync, unlinkSync } from "node:fs";
-import { dirname as dirname4, join as join17, basename as basename7 } from "node:path";
+import { dirname as dirname5, join as join17, basename as basename7 } from "node:path";
 import { randomBytes as randomBytes2 } from "node:crypto";
 function readGtrk(path) {
   const raw = readFileSync4(path, "utf8");
@@ -6908,7 +7123,7 @@ function writeStructMetaSplit(path, gtrk, splitObj, expectedMtimeMs) {
   }
   const nextStructMeta = { ...gtrk.struct_meta ?? {}, split: splitObj };
   const next = { ...gtrk, struct_meta: nextStructMeta };
-  const tmp = join17(dirname4(path), `.${basename7(path)}.${randomBytes2(6).toString("hex")}.tmp`);
+  const tmp = join17(dirname5(path), `.${basename7(path)}.${randomBytes2(6).toString("hex")}.tmp`);
   try {
     writeFileSync2(tmp, JSON.stringify(next, null, 2));
     renameSync(tmp, path);
@@ -6924,7 +7139,7 @@ function writeGtrkAtomic(path, next, expectedMtimeMs) {
   if (cur !== expectedMtimeMs) {
     throw new Error("工程文件在 matrix 运行期间被外部修改（保存冲突），已拒绝写入；请关闭客户端未保存的工程或重跑（plan 与已下载代理均保留）");
   }
-  const tmp = join17(dirname4(path), `.${basename7(path)}.${randomBytes2(6).toString("hex")}.tmp`);
+  const tmp = join17(dirname5(path), `.${basename7(path)}.${randomBytes2(6).toString("hex")}.tmp`);
   try {
     writeFileSync2(tmp, JSON.stringify(next, null, 2));
     renameSync(tmp, path);
@@ -6947,10 +7162,10 @@ function firstExisting(cands) {
   return cands.find((p) => existsSync14(p));
 }
 function resolvePaths(opts) {
-  const project = opts.project ? resolve6(opts.project) : undefined;
+  const project = opts.project ? resolve7(opts.project) : undefined;
   let gtrkPath;
   if (opts.gtrk) {
-    gtrkPath = resolve6(opts.gtrk);
+    gtrkPath = resolve7(opts.gtrk);
   } else if (project) {
     gtrkPath = firstExisting([join18(project, "gtrk", "project.gtrk"), join18(project, "project.gtrk")]) ?? join18(project, "gtrk", "project.gtrk");
   } else {
@@ -6960,14 +7175,14 @@ function resolvePaths(opts) {
     throw new Error(`找不到工程文件：${gtrkPath}`);
   let transcriptPath;
   if (opts.transcript)
-    transcriptPath = resolve6(opts.transcript);
+    transcriptPath = resolve7(opts.transcript);
   else if (project)
     transcriptPath = firstExisting([
       join18(project, "transcript", "transcript.json"),
       join18(project, "json", "transcript.json"),
       join18(project, "transcript.json")
     ]);
-  const baseDir = project ?? dirname5(gtrkPath);
+  const baseDir = project ?? dirname6(gtrkPath);
   return { baseDir, gtrkPath, transcriptPath };
 }
 function slugify(name) {
@@ -6987,7 +7202,7 @@ async function runSplit(splitdoc, opts) {
   if (opts.json)
     routeLogsToStderr();
   const { baseDir, gtrkPath, transcriptPath } = resolvePaths(opts);
-  return splitdoc ? runLand(resolve6(splitdoc), baseDir, gtrkPath, transcriptPath, opts) : runView(baseDir, gtrkPath, transcriptPath, opts);
+  return splitdoc ? runLand(resolve7(splitdoc), baseDir, gtrkPath, transcriptPath, opts) : runView(baseDir, gtrkPath, transcriptPath, opts);
 }
 async function runView(baseDir, gtrkPath, transcriptPath, opts) {
   if (!transcriptPath || !existsSync14(transcriptPath))
@@ -7093,7 +7308,7 @@ async function runLand(splitdocPath, baseDir, gtrkPath, transcriptPath, opts) {
 }
 
 // src/commands/matrix.ts
-import { resolve as resolve7, join as join19, dirname as dirname6, basename as basename9 } from "node:path";
+import { resolve as resolve8, join as join19, dirname as dirname7, basename as basename9 } from "node:path";
 import { existsSync as existsSync15 } from "node:fs";
 import { readFile as readFile5, writeFile as writeFile7, mkdir as mkdir6 } from "node:fs/promises";
 
@@ -7632,10 +7847,10 @@ async function runPlanMode(cfg, tier, broll, overrides, columnId, opts) {
   let dispatchPath;
   let baseDir;
   if (opts.dispatch) {
-    dispatchPath = resolve7(opts.dispatch);
-    baseDir = dirname6(dirname6(dispatchPath));
+    dispatchPath = resolve8(opts.dispatch);
+    baseDir = dirname7(dirname7(dispatchPath));
   } else if (opts.project) {
-    baseDir = resolve7(opts.project);
+    baseDir = resolve8(opts.project);
     dispatchPath = join19(baseDir, "split", "dispatch.json");
   } else {
     throw new Error('需 --project <目录> 或显式 --dispatch <path>（ad-hoc 检索用：gtrk matrix search "<query>"）');
@@ -7740,7 +7955,7 @@ async function layIntoProject(baseDir, plan, layN, scoreFloor) {
   const { fills, clipIds } = planBeatFills(plan, layN, scoreFloor);
   const slotCount = [...fills.values()].flat().reduce((n, s) => n + s.length, 0);
   log.step(`▶ 候选铺轨（${layN} 轨 · 平铺 ${slotCount} 槽位 · ${clipIds.size} 个 clip，preview 代理）…`);
-  const gtrkDir = dirname6(gtrkPath);
+  const gtrkDir = dirname7(gtrkPath);
   const previewDir = join19(gtrkDir, ...BROLL_PREVIEW_DIR.split("/"));
   await mkdir6(previewDir, { recursive: true });
   const prevSource = new Map;
@@ -7853,7 +8068,7 @@ async function runAdhoc(query, cfg, tier, broll, overrides, columnId, opts) {
     counts: { beats: 0, queries: 1, results: results.length, errors: 0 }
   };
   if (opts.out) {
-    const outPath = resolve7(opts.out);
+    const outPath = resolve8(opts.out);
     await writeFile7(outPath, JSON.stringify({ query, recalled: data.recalled, results }, null, 2));
     log.ok(`结果已落盘：${outPath}`);
     result.outPath = outPath;
@@ -7873,7 +8088,7 @@ function slugify2(name) {
 }
 
 // src/commands/mg.ts
-import { resolve as resolve8, join as join20, dirname as dirname7, basename as basename10 } from "node:path";
+import { resolve as resolve9, join as join20, dirname as dirname8, basename as basename10 } from "node:path";
 import { existsSync as existsSync16 } from "node:fs";
 import { readFile as readFile6, mkdir as mkdir7, copyFile } from "node:fs/promises";
 
@@ -8096,11 +8311,11 @@ async function runMg(words, opts) {
 }
 function resolveDispatch(opts) {
   if (opts.dispatch) {
-    const dispatchPath = resolve8(opts.dispatch);
-    return { dispatchPath, baseDir: dirname7(dirname7(dispatchPath)) };
+    const dispatchPath = resolve9(opts.dispatch);
+    return { dispatchPath, baseDir: dirname8(dirname8(dispatchPath)) };
   }
   if (opts.project) {
-    const baseDir = resolve8(opts.project);
+    const baseDir = resolve9(opts.project);
     return { dispatchPath: join20(baseDir, "split", "dispatch.json"), baseDir };
   }
   throw new Error("需 --project <目录> 或显式 --dispatch <path>");
@@ -8177,7 +8392,7 @@ async function runLay(opts) {
   }
   const { gtrk, mtimeMs } = readGtrk(gtrkPath);
   assertGtrkV1(gtrk);
-  const gtrkDir = dirname7(gtrkPath);
+  const gtrkDir = dirname8(gtrkPath);
   await mkdir7(join20(gtrkDir, ...MG_ASSET_DIR.split("/")), { recursive: true });
   for (const it of items) {
     await copyFile(srcByComp.get(it.composition_id), join20(gtrkDir, ...it.html_rel.split("/")));
@@ -8198,10 +8413,10 @@ async function runLint(args, opts) {
   const file = args[0];
   if (!file)
     throw new Error("用法：gtrk mg lint <particle.html> [--dispatch <path>]");
-  const html = await readFile6(resolve8(file), "utf8");
+  const html = await readFile6(resolve9(file), "utf8");
   let dispatchIds;
-  if (opts.dispatch && existsSync16(resolve8(opts.dispatch))) {
-    dispatchIds = (await readMgQueue(resolve8(opts.dispatch))).map((q) => q.composition_id);
+  if (opts.dispatch && existsSync16(resolve9(opts.dispatch))) {
+    dispatchIds = (await readMgQueue(resolve9(opts.dispatch))).map((q) => q.composition_id);
   }
   const lint = lintParticle(html, { dispatchIds });
   for (const vv of lint.violations)
@@ -8854,6 +9069,308 @@ var audioSilenceRemove = {
     return url ? [{ url, filename: `${ctx.baseName}-desilence${extFromUrl(url, ".wav")}` }] : [];
   }
 };
+var videoSegment = {
+  name: "video_segment",
+  title: "视频机械分镜",
+  description: "按画面变动率把视频切成分镜区间，输出结构化 JSON（场景数与各段起止/时长），不产切片文件。",
+  kind: "cloud",
+  input: { kind: "video", exts: PUBLIC_VIDEO_EXTS },
+  priceKey: "video_segment",
+  outputHint: "分镜区间结构（result-output.json）",
+  enabled: true,
+  taskType: "video_segment",
+  options: [
+    { flag: "--detector <content|adaptive>", desc: "切分算法（未传则使用服务端默认）" },
+    { flag: "--threshold <number>", desc: "切分阈值（未传则使用服务端默认）" }
+  ],
+  buildPayload(fileId, ctx) {
+    const payload = { file_id: fileId, only_struct: true };
+    if (ctx.opts.detector != null) {
+      const detector = String(ctx.opts.detector);
+      if (detector !== "content" && detector !== "adaptive") {
+        throw new Error("--detector 只支持 content 或 adaptive");
+      }
+      payload.detector = detector;
+    }
+    if (ctx.opts.threshold != null) {
+      const value = Number(ctx.opts.threshold);
+      if (!Number.isFinite(value))
+        throw new Error("--threshold 必须是数字");
+      payload.threshold = value;
+    }
+    return payload;
+  },
+  mapResult(out) {
+    return out;
+  }
+};
+var videoAiSegment = {
+  name: "video_ai_segment",
+  title: "视频智能分镜",
+  description: "按语义把视频切成带类目、景别、标签、描述的镜头结构，输出结构化 JSON，不产切片文件。",
+  kind: "cloud",
+  input: { kind: "video", exts: PUBLIC_VIDEO_EXTS },
+  priceKey: "video_ai_segment",
+  outputHint: "语义分镜结构（result-output.json）",
+  enabled: true,
+  taskType: "video_ai_segment",
+  options: [
+    { flag: "--segment-mode <scene|shot_type|narrative|subject>", desc: "分镜维度（未传则使用服务端默认）" }
+  ],
+  buildPayload(fileId, ctx) {
+    const payload = { file_id: fileId, only_struct: true };
+    if (ctx.opts.segmentMode != null) {
+      const mode = String(ctx.opts.segmentMode);
+      if (mode !== "scene" && mode !== "shot_type" && mode !== "narrative" && mode !== "subject") {
+        throw new Error("--segment-mode 只支持 scene、shot_type、narrative 或 subject");
+      }
+      payload.mode = mode;
+    }
+    return payload;
+  },
+  mapResult(out) {
+    return out;
+  }
+};
+var videoMotionCut = {
+  name: "video_motion_cut",
+  title: "视频运镜高光",
+  description: "用光流分析提取运镜/高光片段，输出结构化 JSON（每片帧号、秒级时码与运动特征），不产文件。",
+  kind: "cloud",
+  input: { kind: "video", exts: PUBLIC_VIDEO_EXTS },
+  priceKey: "video_motion_cut",
+  outputHint: "运镜高光片段结构（result-output.json）",
+  enabled: true,
+  taskType: "video_motion_cut",
+  buildPayload(fileId) {
+    return { file_id: fileId };
+  },
+  mapResult(out) {
+    return out;
+  }
+};
+var audioSpeakerSplit = {
+  name: "audio_speaker_split",
+  title: "按说话人分轨",
+  description: "把多说话人音频按说话人分成独立音轨，并产说话人时间线结构；--only-struct 只出结构不切文件。",
+  kind: "cloud",
+  input: { kind: "audio" },
+  priceKey: "audio_speaker_split",
+  outputHint: "各说话人音轨 + 时间线结构",
+  enabled: true,
+  taskType: "audio_speaker_split",
+  options: [{ flag: "--only-struct", desc: "只输出说话人时间线结构，不切分音轨文件" }],
+  buildPayload(fileId, ctx) {
+    return { file_id: fileId, only_struct: ctx.opts.onlyStruct === true };
+  },
+  mapOutputs(out, ctx) {
+    if (!Array.isArray(out.files))
+      return [];
+    const items = [];
+    for (const raw of out.files) {
+      if (!raw || typeof raw !== "object")
+        continue;
+      const file = raw;
+      const url = file.download_url;
+      if (typeof url !== "string" || !url.trim())
+        continue;
+      const speaker = typeof file.speaker === "string" && file.speaker.trim() ? file.speaker : `speaker_${items.length + 1}`;
+      items.push({ url, filename: `${ctx.baseName}-${speaker}${extFromUrl(url, ".wav")}` });
+    }
+    return items;
+  },
+  mapResult(out) {
+    return { spoken_list: Array.isArray(out.spoken_list) ? out.spoken_list : [] };
+  }
+};
+var audioStretch = {
+  name: "audio_stretch",
+  title: "音频变调变速",
+  description: "对音频独立调整音高（半音）与速度（倍率），输出处理后的音频。",
+  kind: "cloud",
+  input: { kind: "audio" },
+  priceKey: "audio_stretch",
+  outputHint: "变调变速音频",
+  enabled: true,
+  taskType: "audio_stretch",
+  options: [
+    { flag: "--semitones <n>", desc: "变调半音（升正降负；未传则不变调）" },
+    { flag: "--speed <n>", desc: "变速倍率（必须 > 0；未传则不变速）" }
+  ],
+  buildPayload(fileId, ctx) {
+    const payload = { file_id: fileId };
+    if (ctx.opts.semitones != null) {
+      const value = Number(ctx.opts.semitones);
+      if (!Number.isFinite(value))
+        throw new Error("--semitones 必须是数字");
+      payload.semitones = value;
+    }
+    if (ctx.opts.speed != null) {
+      const value = Number(ctx.opts.speed);
+      if (!Number.isFinite(value) || value <= 0)
+        throw new Error("--speed 必须是大于 0 的数字");
+      payload.speed = value;
+    }
+    return payload;
+  },
+  mapOutputs(out, ctx) {
+    const url = pickUrl(out, ["download_url"]);
+    return url ? [{ url, filename: `${ctx.baseName}-stretch${extFromUrl(url, ".wav")}` }] : [];
+  }
+};
+var pianoAudioToMidi = {
+  name: "piano_audio_to_midi",
+  title: "钢琴音频转 MIDI",
+  description: "把钢琴演奏音频扒谱为 MIDI 文件。",
+  kind: "cloud",
+  input: { kind: "audio" },
+  priceKey: "piano_audio_to_midi",
+  outputHint: "MIDI 文件（.mid）",
+  enabled: true,
+  taskType: "piano_audio_to_midi",
+  buildPayload(fileId) {
+    return { file_id: fileId };
+  },
+  mapOutputs(out, ctx) {
+    const url = pickUrl(out, ["download_url"]);
+    return url ? [{ url, filename: `${ctx.baseName}${extFromUrl(url, ".mid")}` }] : [];
+  }
+};
+var pianoAudioEnhance = {
+  name: "piano_audio_enhance",
+  title: "钢琴音频修复增强",
+  description: "修复并增强钢琴录音音质，产高质量 WAV 与配套 MIDI。",
+  kind: "cloud",
+  input: { kind: "audio" },
+  priceKey: "piano_audio_enhance",
+  outputHint: "高质量 WAV + MIDI",
+  enabled: true,
+  taskType: "piano_audio_enhance",
+  buildPayload(fileId) {
+    return { file_id: fileId };
+  },
+  mapOutputs(out, ctx) {
+    const files = [];
+    const main = pickUrl(out, ["download_url"]);
+    if (main)
+      files.push({ url: main, filename: `${ctx.baseName}-enhanced${extFromUrl(main, ".wav")}` });
+    const midi = pickUrl(out, ["midi_download_url"]);
+    if (midi)
+      files.push({ url: midi, filename: `${ctx.baseName}${extFromUrl(midi, ".mid")}` });
+    return files;
+  }
+};
+var imageToSquare = {
+  name: "image_to_square",
+  title: "长图转方图",
+  description: "把长图智能转为方形图，可指定最大边长（默认 4000，上限 20000）。",
+  kind: "cloud",
+  input: { kind: "image" },
+  priceKey: "image_to_square",
+  outputHint: "方形图片",
+  enabled: true,
+  taskType: "image_to_square",
+  options: [{ flag: "--max-line <px>", desc: "最大边长像素（默认 4000，上限 20000）" }],
+  buildPayload(fileId, ctx) {
+    const payload = { file_id: fileId };
+    if (ctx.opts.maxLine != null) {
+      const value = Number(ctx.opts.maxLine);
+      if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1 || value > 20000) {
+        throw new Error("--max-line 必须是 1 到 20000 之间的整数");
+      }
+      payload.max_line = value;
+    }
+    return payload;
+  },
+  mapOutputs(out, ctx) {
+    const url = pickUrl(out, ["download_url"]);
+    return url ? [{ url, filename: `${ctx.baseName}-square${extFromUrl(url, ".jpg")}` }] : [];
+  }
+};
+var imageToLive = {
+  name: "image_to_live",
+  title: "智能 LivePhoto",
+  description: "把一张静态图片生成微动的 LivePhoto 视频（产物是视频）。",
+  kind: "cloud",
+  input: { kind: "image" },
+  priceKey: "image_to_live",
+  outputHint: "微动视频（.mp4）",
+  enabled: true,
+  taskType: "image_to_live",
+  buildPayload(fileId) {
+    return { file_id: fileId };
+  },
+  mapOutputs(out, ctx) {
+    const url = pickUrl(out, ["download_url", "video_download_url", "url"]);
+    return url ? [{ url, filename: `${ctx.baseName}-live${extFromUrl(url, ".mp4")}` }] : [];
+  }
+};
+var AI_SUBTITLE_TYPES = ["default", "outline", "cinema_yellow", "immersive_box", "wide_spacing", "deep_shadow", "boxed"];
+var AI_SUBTITLE_COLORS = ["雅黑", "淡绿", "森林绿", "湖蓝", "道奇蓝", "钢蓝", "浅粉红", "深橙", "珊瑚橙", "橙红", "土豪金"];
+var videoAiSubtitle = {
+  name: "video_ai_subtitle",
+  title: "智能视频字幕",
+  description: "为视频（或音频）智能生成字幕，可选双语翻译、烧录进视频、去除原字幕；另产 LLM 摘要与字级时间轴。",
+  kind: "cloud",
+  input: { kind: "video", exts: [...PUBLIC_VIDEO_EXTS, ...AUDIO_EXTS] },
+  priceKey: "video_ai_subtitle",
+  outputHint: "字幕 .ass + 可选烧录/去字幕视频 + 摘要/字级时轴结构",
+  enabled: true,
+  taskType: "video_ai_subtitle",
+  pollTimeoutMs: 4 * 60 * 60 * 1000,
+  options: [
+    { flag: "--language <code>", desc: "源语种代码（必填；具体取值由服务端支持列表校验）" },
+    { flag: "--translate-language <code>", desc: "译文目标语种（未传则单语）" },
+    { flag: "--need-render", desc: "把字幕烧录进视频（仅视频输入有效）" },
+    { flag: "--need-pure", desc: "先去除原视频中的字幕" },
+    { flag: "--subtitle-type <style>", desc: `字幕样式：${AI_SUBTITLE_TYPES.join("/")}（未传则用服务端默认）` },
+    { flag: "--subtitle-color <color>", desc: `字幕颜色：${AI_SUBTITLE_COLORS.join("/")}（未传则用服务端默认）` }
+  ],
+  buildPayload(fileId, ctx) {
+    const language = ctx.opts.language == null ? "" : String(ctx.opts.language).trim();
+    if (!language)
+      throw new Error("--language 必填：请指定源语种代码（具体取值见云端 API 文档 / 服务端支持列表）");
+    const payload = { file_id: fileId, language };
+    if (ctx.opts.translateLanguage != null) {
+      const t = String(ctx.opts.translateLanguage).trim();
+      if (t)
+        payload.translate_language = t;
+    }
+    if (ctx.opts.needRender === true)
+      payload.need_render = true;
+    if (ctx.opts.needPure === true)
+      payload.need_pure = true;
+    if (ctx.opts.subtitleType != null) {
+      const v = String(ctx.opts.subtitleType);
+      if (!AI_SUBTITLE_TYPES.includes(v))
+        throw new Error(`--subtitle-type 只支持 ${AI_SUBTITLE_TYPES.join("、")}`);
+      payload.subtitle_type = v;
+    }
+    if (ctx.opts.subtitleColor != null) {
+      const v = String(ctx.opts.subtitleColor);
+      if (!AI_SUBTITLE_COLORS.includes(v))
+        throw new Error(`--subtitle-color 只支持 ${AI_SUBTITLE_COLORS.join("、")}`);
+      payload.subtitle_color = v;
+    }
+    return payload;
+  },
+  mapOutputs(out, ctx) {
+    const files = [];
+    const sub = pickUrl(out, ["subtitle_file_download_url"]);
+    if (sub)
+      files.push({ url: sub, filename: `${ctx.baseName}${extFromUrl(sub, ".ass")}` });
+    const rendered = pickUrl(out, ["rendered_file_download_url"]);
+    if (rendered)
+      files.push({ url: rendered, filename: `${ctx.baseName}-subtitled${extFromUrl(rendered, ".mp4")}` });
+    const pure = pickUrl(out, ["pure_file_download_url"]);
+    if (pure)
+      files.push({ url: pure, filename: `${ctx.baseName}-pure${extFromUrl(pure, ".mp4")}` });
+    return files;
+  },
+  mapResult(out) {
+    return { summary: typeof out.summary === "string" ? out.summary : "", asr: out.asr ?? null };
+  }
+};
 var mad = {
   name: "mad",
   title: "一键剪 MAD",
@@ -8889,6 +9406,16 @@ var TOOL_REGISTRY = [
   audioSeparation,
   audioNoiseReduce,
   audioSilenceRemove,
+  videoSegment,
+  videoAiSegment,
+  videoMotionCut,
+  audioSpeakerSplit,
+  audioStretch,
+  pianoAudioToMidi,
+  pianoAudioEnhance,
+  imageToSquare,
+  imageToLive,
+  videoAiSubtitle,
   mad
 ];
 function findTool(name, registry = TOOL_REGISTRY) {
@@ -8910,11 +9437,14 @@ function validateRegistry(registry = TOOL_REGISTRY) {
       throw new Error(`cloud 型工具缺 taskType：「${d.name}」`);
     if (d.kind === "cloud" && !d.priceKey)
       throw new Error(`cloud 型工具缺 priceKey：「${d.name}」`);
+    if (d.kind === "cloud" && !d.mapOutputs && !d.mapResult) {
+      throw new Error(`cloud 型工具须至少声明 mapOutputs 或 mapResult 之一：「${d.name}」`);
+    }
   }
 }
 
 // src/lib/tool-runner.ts
-import { resolve as resolve9, join as join21, dirname as dirname8, basename as basename11, extname as extname5 } from "node:path";
+import { resolve as resolve10, join as join21, dirname as dirname9, basename as basename11, extname as extname5 } from "node:path";
 import { mkdir as mkdir8, writeFile as writeFile8, stat as stat5 } from "node:fs/promises";
 import { createWriteStream, existsSync as existsSync17 } from "node:fs";
 import { Readable as Readable2 } from "node:stream";
@@ -9113,10 +9643,10 @@ function timestamp3() {
 }
 function resolveOutDir(descriptor, inputAbs, out) {
   if (out)
-    return resolve9(out);
+    return resolve10(out);
   if (inputAbs) {
     const base = basename11(inputAbs, extname5(inputAbs));
-    return join21(dirname8(inputAbs), `${base}-${descriptor.name}`);
+    return join21(dirname9(inputAbs), `${base}-${descriptor.name}`);
   }
   return join21(process.cwd(), `${descriptor.name}-${timestamp3()}`);
 }
@@ -9133,7 +9663,7 @@ function emitBilling(hint) {
 `);
 }
 async function runCloudTool(descriptor, inputArg, opts, deps) {
-  const inputAbs = inputArg ? resolve9(inputArg) : undefined;
+  const inputAbs = inputArg ? resolve10(inputArg) : undefined;
   const baseName = inputAbs ? basename11(inputAbs, extname5(inputAbs)) : descriptor.name;
   validateToolInput(descriptor, inputAbs);
   const probe = deps.probeDurationSec ?? probeDuration;
@@ -9171,7 +9701,7 @@ async function runCloudTool(descriptor, inputArg, opts, deps) {
     uploadCached: deps.uploadCached,
     invalidateUpload: deps.invalidateUpload,
     submitTask: deps.submitTask,
-    sleep: deps.sleep ?? ((ms) => new Promise((resolve10) => setTimeout(resolve10, ms)))
+    sleep: deps.sleep ?? ((ms) => new Promise((resolve11) => setTimeout(resolve11, ms)))
   });
   const { taskId } = submitted;
   const up = { fileId: submitted.fileId, cached: submitted.cached };
@@ -9185,11 +9715,10 @@ async function runCloudTool(descriptor, inputArg, opts, deps) {
     sleep: deps.sleep,
     now: deps.now
   });
-  const items = descriptor.mapOutputs ? descriptor.mapOutputs(output, ctx) : [];
+  const outputResult = output;
   const files = [];
   const errors = {};
-  if (items.length === 0)
-    errors["output"] = "任务完成但未解析到产物下载链接（output_result 形态异常）";
+  const items = descriptor.mapOutputs ? descriptor.mapOutputs(outputResult, ctx) : [];
   for (const it of items) {
     const dest = join21(outDir, it.filename);
     try {
@@ -9199,7 +9728,16 @@ async function runCloudTool(descriptor, inputArg, opts, deps) {
       errors[it.filename] = e instanceof Error ? e.message : String(e);
     }
   }
-  const ok = files.length > 0 && Object.keys(errors).length === 0;
+  let resultFile;
+  const structured = descriptor.mapResult ? descriptor.mapResult(outputResult, ctx) : undefined;
+  if (structured != null) {
+    resultFile = join21(outDir, "result-output.json");
+    await writeFile8(resultFile, JSON.stringify(structured, null, 2));
+  }
+  if (items.length === 0 && resultFile == null) {
+    errors["output"] = "任务完成但未解析到任何产物（下载链接与结构化结果均为空，output_result 形态异常）";
+  }
+  const ok = Object.keys(errors).length === 0 && (files.length > 0 || resultFile != null);
   const result = {
     ok,
     tool: descriptor.name,
@@ -9208,6 +9746,7 @@ async function runCloudTool(descriptor, inputArg, opts, deps) {
     fileId: up.fileId,
     outDir,
     files,
+    ...resultFile ? { resultFile } : {},
     ...Object.keys(errors).length ? { errors } : {}
   };
   await writeFile8(join21(outDir, "result.json"), JSON.stringify({ ...result, finishedAt: new Date().toISOString() }, null, 2));
@@ -9217,7 +9756,7 @@ async function runCloudTool(descriptor, inputArg, opts, deps) {
 // src/lib/mad/mad.ts
 import { mkdir as mkdir11, writeFile as writeFile10 } from "node:fs/promises";
 import { existsSync as existsSync20, statSync as statSync3 } from "node:fs";
-import { resolve as resolve10, join as join25 } from "node:path";
+import { resolve as resolve11, join as join25 } from "node:path";
 
 // src/lib/convert/types.ts
 function num(v, d = 0) {
@@ -10402,7 +10941,7 @@ async function analyzeBgm(cfg, bgmAbs, deps) {
     uploadCached: deps.uploadCached,
     invalidateUpload: deps.invalidateUpload,
     submitTask: deps.submitTask,
-    sleep: deps.sleep ?? ((ms) => new Promise((resolve10) => setTimeout(resolve10, ms)))
+    sleep: deps.sleep ?? ((ms) => new Promise((resolve11) => setTimeout(resolve11, ms)))
   });
   const { taskId } = submitted;
   const output = await deps.pollToolTask(cfg, ANALYZE_TASK, taskId, {});
@@ -10463,7 +11002,7 @@ async function runMad(inputArg, opts, deps = {}) {
   const probeDur = deps.probeDurationFn ?? probeDuration;
   if (!inputArg)
     throw new Error("用法：gtrk tool mad <素材文件夹> [--bgm 歌.mp3]");
-  const dirAbs = resolve10(inputArg);
+  const dirAbs = resolve11(inputArg);
   if (!existsSync20(dirAbs) || !statSync3(dirAbs).isDirectory()) {
     throw new Error(`素材文件夹不存在或不是目录：${dirAbs}`);
   }
@@ -10495,7 +11034,7 @@ async function runMad(inputArg, opts, deps = {}) {
   let level = 3;
   let analysis = null;
   let bgmForTrack;
-  const bgmAbs = opts.bgm ? resolve10(opts.bgm) : undefined;
+  const bgmAbs = opts.bgm ? resolve11(opts.bgm) : undefined;
   if (bgmAbs) {
     let dur = -1;
     try {
@@ -10578,7 +11117,7 @@ async function runMad(inputArg, opts, deps = {}) {
   const header = madHeader(version, now.toISOString());
   const bgm = level <= 2 && bgmForTrack ? { path: bgmForTrack, markers } : undefined;
   const { jsx } = madJsx({ master, windows, header, bgm });
-  const outDir = opts.out ? resolve10(opts.out) : join25(process.cwd(), `mad-${timestamp4(now)}`);
+  const outDir = opts.out ? resolve11(opts.out) : join25(process.cwd(), `mad-${timestamp4(now)}`);
   await mkdir11(outDir, { recursive: true });
   const jsxPath = join25(outDir, "mad.jsx");
   await writeFile10(jsxPath, jsx);
@@ -10726,7 +11265,7 @@ async function runMadInTool(inputArg, opts) {
 // src/commands/transcript.ts
 import { existsSync as existsSync21 } from "node:fs";
 import { mkdir as mkdir12, rename as rename2, rm as rm2, stat as stat6, writeFile as writeFile11 } from "node:fs/promises";
-import { basename as basename12, dirname as dirname9, extname as extname7, join as join26, resolve as resolve11 } from "node:path";
+import { basename as basename12, dirname as dirname10, extname as extname7, join as join26, resolve as resolve12 } from "node:path";
 
 // src/lib/transcript.ts
 var AGENT_SUMMARY_PENDING = "<!-- gtrk:agent-summary-pending -->";
@@ -10847,7 +11386,7 @@ function buildDeps(overrides = {}) {
     upload: overrides.upload ?? uploadCached,
     invalidate: overrides.invalidate ?? invalidateUpload,
     submit: overrides.submit ?? submitTask,
-    sleep: overrides.sleep ?? ((ms) => new Promise((resolve12) => setTimeout(resolve12, ms))),
+    sleep: overrides.sleep ?? ((ms) => new Promise((resolve13) => setTimeout(resolve13, ms))),
     poll: overrides.poll ?? (async (cfg, taskType, taskId, onTick) => await pollToolTask(cfg, taskType, taskId, { onTick })),
     writeMarkdown: overrides.writeMarkdown ?? writeMarkdownAtomic,
     now: overrides.now ?? (() => new Date)
@@ -10862,7 +11401,7 @@ async function validateTranscriptInput(input) {
   if (looksLikeRemote(input)) {
     throw new Error("视频转文字稿仅支持本地视频文件，不支持 URL、平台视频地址或远端下载");
   }
-  const inputAbs = resolve11(input);
+  const inputAbs = resolve12(input);
   if (!existsSync21(inputAbs))
     throw new Error(`本地视频不存在：${inputAbs}`);
   const info = await stat6(inputAbs);
@@ -10876,13 +11415,13 @@ async function validateTranscriptInput(input) {
 }
 function resolveTranscriptOutput(inputAbs, out) {
   const base = basename12(inputAbs, extname7(inputAbs));
-  const output = out ? resolve11(out) : join26(dirname9(inputAbs), `${base}-transcript.md`);
+  const output = out ? resolve12(out) : join26(dirname10(inputAbs), `${base}-transcript.md`);
   if (extname7(output).toLowerCase() !== ".md")
     throw new Error("--out 必须指向一个 .md 文件");
   return output;
 }
 async function writeMarkdownAtomic(path, markdown) {
-  await mkdir12(dirname9(path), { recursive: true });
+  await mkdir12(dirname10(path), { recursive: true });
   const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
   try {
     await writeFile11(temp, markdown, "utf8");
@@ -10958,12 +11497,226 @@ function registerTranscript(program2) {
   configureTranscriptCommand(program2.command("transcript <video>"));
 }
 
+// src/commands/music-visualizer.ts
+import { resolve as resolve13, join as join27, dirname as dirname11, basename as basename13, extname as extname8 } from "node:path";
+import { mkdir as mkdir13, writeFile as writeFile12 } from "node:fs/promises";
+import { existsSync as existsSync22 } from "node:fs";
+var TASK_TYPE4 = "music_visualizer";
+var PRICE_KEY2 = "music_visualizer";
+var HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+var AUDIO_EXTS2 = defaultExtsFor("audio") ?? [];
+var IMAGE_EXTS2 = defaultExtsFor("image") ?? [];
+var VIDEO_EXTS3 = defaultExtsFor("video") ?? [];
+var collectParam3 = (v, acc) => {
+  acc.push(v);
+  return acc;
+};
+function coerceValue3(v) {
+  if (v === "true")
+    return true;
+  if (v === "false")
+    return false;
+  if (v.trim() !== "" && !Number.isNaN(Number(v)))
+    return Number(v);
+  return v;
+}
+function parseExtraParams3(pairs, jsonStr) {
+  const out = {};
+  for (const pair of pairs) {
+    const i = pair.indexOf("=");
+    if (i < 0)
+      throw new Error(`--param 需要 key=value 格式：「${pair}」`);
+    out[pair.slice(0, i).trim()] = coerceValue3(pair.slice(i + 1));
+  }
+  if (jsonStr) {
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonStr);
+    } catch {
+      throw new Error(`--params-json 不是合法 JSON：${jsonStr}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("--params-json 必须是一个 JSON 对象");
+    }
+    Object.assign(out, parsed);
+  }
+  return out;
+}
+function timestamp5() {
+  const d = new Date;
+  const p = (n) => String(n).padStart(2, "0");
+  return `${p(d.getFullYear() % 100)}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+function assertExt(pathAbs, exts, label) {
+  if (!existsSync22(pathAbs))
+    throw new Error(`${label}不存在：${pathAbs}`);
+  const e = extname8(pathAbs).toLowerCase();
+  if (exts.length && !exts.includes(e)) {
+    throw new Error(`${label}扩展名不支持：${e}（支持 ${exts.join(" ")}）`);
+  }
+}
+function buildStyleFields(opts) {
+  const fields = {};
+  if (opts.track != null)
+    fields.track = String(opts.track);
+  if (opts.artist != null)
+    fields.artist = String(opts.artist);
+  if (opts.resolution != null) {
+    const m = /^(\d+)[xX](\d+)$/.exec(opts.resolution.trim());
+    if (!m)
+      throw new Error(`--resolution 必须是 <宽>x<高> 格式（如 1920x1080）：${opts.resolution}`);
+    const width = Number(m[1]);
+    const height = Number(m[2]);
+    if (!(width > 0) || !(height > 0))
+      throw new Error("--resolution 的宽高必须为正整数");
+    fields.resolution = { width, height };
+  }
+  if (opts.fps != null) {
+    const fps = Number(opts.fps);
+    if (!Number.isInteger(fps) || fps < 30 || fps > 60)
+      throw new Error("--fps 必须是 30 到 60 的整数");
+    fields.fps = fps;
+  }
+  if (opts.c1 != null) {
+    if (!HEX_RE.test(opts.c1))
+      throw new Error("--c1 必须是十六进制颜色（如 #ff0066 或 #f06）");
+    fields.c1 = opts.c1;
+  }
+  if (opts.c2 != null) {
+    if (!HEX_RE.test(opts.c2))
+      throw new Error("--c2 必须是十六进制颜色（如 #6600ff 或 #60f）");
+    fields.c2 = opts.c2;
+  }
+  if (opts.blur != null) {
+    const blur = Number(opts.blur);
+    if (!Number.isInteger(blur) || blur < 0 || blur > 40)
+      throw new Error("--blur 必须是 0 到 40 的整数");
+    fields.blur = blur;
+  }
+  return fields;
+}
+function registerMusicVisualizer(program2) {
+  program2.command("music-visualizer <audio>").description("音乐可视化：一首歌 → 频谱可视化成片（可选背景/封面 + 模板/配色样式）").option("-t, --template <id>", "可视化模板 id（必填；取值见云端 API 文档 / 服务端模板列表）").option("--background <图或视频>", "可选背景素材（图片或视频，独立上传）").option("--cover <图>", "可选封面图（仅图片，独立上传）").option("--track <名>", "曲名（叠加文字）").option("--artist <名>", "歌手名（叠加文字）").option("--resolution <WxH>", "输出分辨率（如 1080x1920；默认服务端 1920x1080）").option("--fps <n>", "帧率 30-60（默认服务端 30）").option("--c1 <hex>", "频谱主色十六进制（如 #ffffff；默认服务端白）").option("--c2 <hex>", "频谱第二色十六进制（给定则双色渐变）").option("--blur <n>", "背景模糊 0-40（默认服务端 16）").option("-o, --out <dir>", "产物目录（缺省 = <音频同目录>/<音频名>-visualizer-<时间戳>）").option("--param <k=v>", "透传任意云端参数（标量、可重复）", collectParam3, []).option("--params-json <json>", "透传任意云端参数（JSON 对象）").option("--reupload", "强制重新上传，忽略本地上传缓存").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (audio, opts) => {
+    await runMusicVisualizer(audio, opts);
+  });
+}
+async function runMusicVisualizer(audio, opts) {
+  if (opts.json)
+    routeLogsToStderr();
+  const cfg = loadConfig();
+  const audioAbs = resolve13(audio);
+  assertExt(audioAbs, AUDIO_EXTS2, "音频");
+  const template = opts.template == null ? "" : String(opts.template).trim();
+  if (!template)
+    throw new Error("--template 必填：请指定可视化模板 id（取值见云端 API 文档 / 服务端模板列表）");
+  const styleFields = buildStyleFields(opts);
+  const bgAbs = opts.background ? resolve13(opts.background) : undefined;
+  if (bgAbs)
+    assertExt(bgAbs, [...IMAGE_EXTS2, ...VIDEO_EXTS3], "背景素材");
+  const coverAbs = opts.cover ? resolve13(opts.cover) : undefined;
+  if (coverAbs)
+    assertExt(coverAbs, IMAGE_EXTS2, "封面图");
+  const extraParams = parseExtraParams3(opts.param, opts.paramsJson);
+  const projName = basename13(audioAbs, extname8(audioAbs));
+  const outDir = resolve13(opts.out ?? join27(dirname11(audioAbs), `${projName}-visualizer-${timestamp5()}`));
+  log.step(`▶ 音乐可视化：${basename13(audioAbs)}（模板 ${template}${bgAbs ? " · 背景" : ""}${coverAbs ? " · 封面" : ""}）`);
+  let billingHint;
+  try {
+    billingHint = (await resolveToolPricing(PRICE_KEY2)).billingHint;
+  } catch {
+    billingHint = "实时价格暂不可用，以服务端结算为准";
+  }
+  process.stderr.write(`\x1B[33m⚠️  计费提示：${billingHint}\x1B[0m
+`);
+  let backgroundFileId;
+  if (bgAbs) {
+    log.step("① 上传背景素材…");
+    backgroundFileId = (await uploadCached(cfg, bgAbs, { force: opts.reupload })).fileId;
+    log.info(`背景 file_id = ${backgroundFileId}`);
+  }
+  let coverFileId;
+  if (coverAbs) {
+    log.step("① 上传封面图…");
+    coverFileId = (await uploadCached(cfg, coverAbs, { force: opts.reupload })).fileId;
+    log.info(`封面 file_id = ${coverFileId}`);
+  }
+  const buildPayload = (fid) => {
+    const p = { file_id: fid, template_id: template };
+    if (backgroundFileId)
+      p.background_file_id = backgroundFileId;
+    if (coverFileId)
+      p.cover_file_id = coverFileId;
+    Object.assign(p, styleFields);
+    for (const [k, v] of Object.entries(extraParams)) {
+      const cur = p[k];
+      const bothObj = !!cur && !!v && typeof cur === "object" && typeof v === "object" && !Array.isArray(cur) && !Array.isArray(v);
+      p[k] = bothObj ? { ...cur, ...v } : v;
+    }
+    return p;
+  };
+  const submitted = await uploadAndSubmitTask(cfg, audioAbs, TASK_TYPE4, buildPayload, {
+    force: opts.reupload,
+    onUploaded: (u) => {
+      log.info(u.cached ? `命中上传缓存，复用主音频 file_id = ${u.fileId}` : `主音频 file_id = ${u.fileId}`);
+      log.step("② 提交音乐可视化任务…");
+    },
+    onCacheInvalid: () => log.warn("缓存的 file_id 在云端已失效，重新上传后重试…")
+  });
+  const { taskId } = submitted;
+  log.info(`task_id = ${taskId}`);
+  await mkdir13(outDir, { recursive: true });
+  await writeFile12(join27(outDir, "task.json"), JSON.stringify({ taskId, taskType: TASK_TYPE4, fileId: submitted.fileId, source: audioAbs, template, createdAt: new Date().toISOString() }, null, 2));
+  log.step("③ 云端处理中（每 5s 轮询）…");
+  const result = await pollTask(cfg, TASK_TYPE4, taskId, (status, progress) => {
+    log.tick(`${status}${progress != null ? ` ${Math.round(progress)}%` : ""}`);
+  });
+  log.tickEnd();
+  const out = result;
+  const url = [out.download_url, out.video_download_url, out.url].find((u) => typeof u === "string" && !!u.trim());
+  const files = [];
+  const errors = {};
+  if (url) {
+    const dest = join27(outDir, `${projName}-visualizer${extFromUrl(url, ".mp4")}`);
+    try {
+      await downloadStream(url, dest);
+      files.push(dest);
+    } catch (e) {
+      errors["output"] = e instanceof Error ? e.message : String(e);
+    }
+  } else {
+    errors["output"] = "任务完成但未解析到成片下载链接（output_result 形态异常）";
+  }
+  const ok = files.length > 0 && Object.keys(errors).length === 0;
+  const resultJson = {
+    ok,
+    command: "music-visualizer",
+    taskType: TASK_TYPE4,
+    taskId,
+    fileId: submitted.fileId,
+    outDir,
+    files,
+    ...Object.keys(errors).length ? { errors } : {},
+    finishedAt: new Date().toISOString()
+  };
+  await writeFile12(join27(outDir, "result.json"), JSON.stringify(resultJson, null, 2));
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(resultJson)}
+`);
+  }
+  if (!ok) {
+    log.err(`产物下载失败：${JSON.stringify(errors)}。可凭 task.json 的 taskId 稍后恢复。`);
+    process.exitCode = 1;
+    return;
+  }
+  log.ok(`完成。产物目录：${outDir}`);
+}
+
 // src/index.ts
 try {
   process.loadEnvFile?.();
 } catch {}
 migrateLegacyHome();
-var { version } = JSON.parse(readFileSync5(join27(packageRoot(), "package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync5(join28(packageRoot(), "package.json"), "utf8"));
 var program2 = new Command;
 program2.name("gtrk").description("同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通").version(version);
 registerInstall(program2);
@@ -10979,6 +11732,7 @@ registerMatrix(program2);
 registerMg(program2);
 registerTool(program2);
 registerTranscript(program2);
+registerMusicVisualizer(program2);
 program2.parseAsync(process.argv).catch((e) => {
   console.error(`
 ❌ ${e instanceof Error ? e.message : String(e)}`);