gitruck/cli/gtrk-tools

gtrk 工具族（gtrk-tools）

飞书使用教程统一入口：gtrk CLI 使用教程。

gtrk tool <name> [输入...] 是 gtrk 的单点能力族：一个工具 = 单发单收（给一份输入、出一份产物；多文件图片工具的「一份输入」是一组图片路径，顺序即拼装顺序），没有成片 SOP 次序；视频去水印必须先完成下文的用户模式选择——与成片管线的车道命令（oralcut / split / matrix / mg）是两回事。本 skill 是这个族的统一调用向导：认清有哪些工具、按纪律驱动 gtrk tool 命令、把产物和计费如实回给用户。

本 skill 已含你需要的全部信息（工具清单、调用纪律、恢复语义、排错话术）。工具清单以 gtrk tool list --json 为唯一真相——本文件与它漂移时以命令输出为准并回来修本文件。参数细节以 gtrk tool --help 为准。

工具清单（与 gtrk tool list 同源）

字幕这两条要提前讲给用户（video_ai_subtitle 专属）：

- --need-render（烧录）在本地跑 ffmpeg，成片不从云端下行。字幕模板用 思源黑体 CN Bold，本机没装就直接报错（不拿替代字体顶——观感会与模板设计不符且用户难以察觉）。装上后重跑即可，字幕文件已落地、无需重新提交任务。4K/长片本地烧录要重编码，耗时可观，先跟用户打招呼。

- --need-pure（去原字幕）是画面操作，加了这个 flag 就会整片上传（CLI 会打一行说明）。只要字幕文件时别加。

清单随 CLI 版本增补。动手前先跑 `gtrk tool list --json` 拿最新清单，别凭记忆——新工具、状态变化都在那里。

video_translate_dub（视频译制配音）要提前讲给用户的

• 克隆声音须本人同意：--speaker clone（或 --ref 给的是别人的录音）会克隆说话人的声音。克隆别人的声音 MUST 先取得那个人的同意，发起任务即视为已取得；不确定就先问用户，别替他默认。
• 只换音轨，画面保持原样：不做口型同步，镜头也不动。缺省拟合策略下，个别译句过长时画面可能短暂定格来让出时间；用户要成片与原片严格等长，传 --fit-policy strict（超出部分截尾）。
• 时长与耗时：单条最长 120 分钟，超了 CLI 在上传前直接拒并提示分段；长片耗时十几分钟起，CLI 最多等 4 小时。中途断开别直接重跑（会重新计费），凭产物目录里 task.json 的任务号取回。
• 工程文件怎么打开：CLI 提交时自动带上原片与产物目录的本机路径，各格式工程里的素材都指向本机的原片与产物目录里的 dub.wav / bgm.wav / base.mp4，打开即用。要剪映草稿加 --project-formats gtrk,jianying：草稿自动放进剪映草稿目录，打开剪映就在列表里；CLI 提示「没找到剪映草稿目录」或「草稿缺 draft_meta_info.json」时，让用户给出剪映草稿目录再用 --jianying-draft-dir 重跑，或先用客户端工程。CapCut 草稿留在产物目录 capcut/，需要时手动放进 CapCut 草稿目录。
• 附带产物偶尔缺项不算失败：字幕、逐句对齐记录、工程文件某一项没生成时，成片与配音轨照出、ok=true，终端打一行「部分附带产物未生成」，原因在 result-output.json 的 errors。照实告诉用户少了哪样。
• 常用形态：gtrk tool video_translate_dub ./talk.mp4 --language zh-CN --translate-language en-US --speaker clone --json；用自己另录的干净人声做参考加 --ref ./me.m4a；要剪映草稿加 --project-formats gtrk,jianying，要 PR 工程加 --project-formats gtrk,xml。

打开 PR 工程时的重链提醒照 gtrk-oralcut「回给用户（三端打开方式）」PR/FCP 条，引用不复制。

mad（一键剪 MAD）的特殊之处

mad 是族内首个 local 型「纯本地工具、可选云端加料」成员，与 cloud 型工具不同：

• 无 Key 可跑：不带 --bgm 时全程只走免鉴权数据面（技法数据经云端 manifest 下发 + ~/.gitruck/mad-cache 缓存），首拉联网一次性下载、缓存命中后离线可跑；不要求 API Key、不触发计费任务。
• `--bgm` 才需 Key 且计费一次：带 --bgm 且已配 Key → BGM 卡点到 downbeat（调一次云端节拍分析计费）；没配 Key → 温和提示 `gtrk init` 可解锁卡点，不阻断，BGM 仍入轨、按固定节奏出片；坏 BGM/云端失败一律降级不崩。
• 产物只有 `.jsx`、只支持 AE：完成后引导「装 AE 2020+ → 文件›脚本›运行脚本文件 选它」。不承诺 `.amproj`/Alight Motion 等本命令未产出的形态。
• 可复现：--seed <n> 固定选窗序列（同素材同种子同数据版本 → 同结果）；result.json 记录 seed、数据版本、降级档位、选中技法清单。
• 常用：gtrk tool mad ./素材 --bgm 歌.mp3 --duration 20 --json。

用户描述了想要的效果时：你先查目录、再点名

不带技法参数时，选技法是纯规则抽样（类目轮转 + 频次加权），用户说的「我要那种切到鼓点屏幕震一下的感觉」不会进到命令里。想让效果对上用户的描述，走两步：

1. gtrk tool mad --search <关键词> --json —— 只查技法目录，不出片、不要素材文件夹、零计费不需 Key。回来的每条带 name / cat / pid / n_seen（该技法在图鉴收录工程里出现过多少次）/ windows（技法池里有几个可用窗口，0 = 点了也用不上）。
2. gtrk tool mad ./素材 --technique <技法名[,技法名…]> —— 只用点名的技法出片。取值接受技法名、别名或 pid。

把用户的话翻译成关键词是你的活，命令那头只做纯字符串包含匹配（无分词无模型）。「屏幕震一下」→ 搜「震屏」/「抖动」；「一闪一闪的」→ 搜「闪白」/「频闪」；「字一个个蹦出来」→ 搜「打字机」。搜不到就换更短的词，别硬塞整句。

三条要如实转述给用户，别替它圆场：

• 名字歧义（比如只写「卡点」命中一片）命令会报错并列候选，不会自己挑一个——把候选念给用户听，让他选。
• 点名的技法里有 windows: 0 的，命令会跳过它并说明原因，用剩下的继续出片；全是 0 才报错。
• 白名单里只有一两个技法时，成片会反复用同一个技法的不同实例（运动曲线不同），这是设计，不是 bug。

⚠️ 长剪短有两条线，别选错（名字很像，产物完全不同）

用户说「把这条长视频剪成短片」时，开工先问两件事、一张表一次问完（MUST NOT 碎问、MUST NOT 代猜）：

分屏是点缀不是主体：只挑多人同框段做，单段最长 8 秒、每条最多 3 处，不会整条变分屏。

单人素材开了也不会出现分屏画面，但仍会多付一段说话人检测的等待——不是零副作用，别这么跟用户说。

跑完 clips.md 头部会回显「分屏：开/关」（只是请求态，报告不知道实际做了几处）。

判断句：「剪完还要不要再动？」要动 → 粗剪；不动 → 精剪。

精剪的润色（运镜 / 调速 / 接缝 / 分屏 / 字幕）都是 best-effort——单项失败会降级，成片照出。跑完 MUST 看一眼产物根的 clips.md，里面有「⚠️ 润色降级」小节点名哪条片的哪些效果没做成；有降级就如实告诉用户，别让他拿着不完整的效果去发布。

调用纪律（每次都照做）