gitruck/cli/gtrk-travel-recap

gtrk-travel-recap（旅拍解说 · 组合成片图纸）

把一个旅拍素材文件夹变成一条中文解说成片工程：理解素材 → 三段式写稿 → 检查点①一次拍板 → 配音/建工程/拆分/B-roll/字卡/BGM/字幕 全自动 → 客户端出片。

定位：本 skill 是第一张 structure 级组合图纸——它不新增任何命令，只编排既有原子零件（transcript / matrix / project init / split / mg / audio lay / subtitle lay / TTS 工具）。零件的参数细节以各自 skill（gtrk-matrix / gtrk-splitter / gtrk-mg / gtrk-transcript）与 --help 为准，本图纸引用不复制；但编排次序、检查点、配方级参数以本图纸为准。CLI 是手，你是脑：写稿、切 beat、挑候选信号、产字卡颗粒、管检查点，都是你的活。

家族归位：本图纸是解说链（gtrk-narration 正本）的旅拍垂类实例。时序铺排、引用段、出处对齐等链级条款以 gtrk-narration 为正本；本图纸只补充旅拍要素层（贵大奇多钩子、攻略 tips、升华笔法）。素材无自带时序的题材（科普/情感/带货）走 gtrk-voiceover。

本 skill 已含跑通全链需要的编排信息。

一、输入契约与双场景识别

用户给一个素材文件夹（或多个，逗号分隔传 --dirs）：

一夹多片时检索域按场景分流：二创场景一个夹里常躺着好几条互不相干的片， B-roll 检索域 MUST 收窄到正在做的那一部片本身——--dirs 既吃文件夹也吃单个素材文件，传文件即把域收窄到该素材（见 §五 ⑦ 的★铁则）。 原创（自拍素材集）那一档整夹就是这一片的素材域，传夹正确。

MUST NOT 下载二创源片 / 主体素材：网络视频二创场景下，用户提供的文件夹就是输入，下载动作归用户。平台授权素材（素材矩阵的 BGM / 空镜）可按其签名直链落地；这条例外不适用于源片与主体画面素材。

双场景识别（决定理解编排走法）：

• 二创：文件夹里是网络旅行长视频（通常含博主解说语音）→ 原片文案是写稿主料；
• 原创：用户自己拍的素材集（通常无解说语音）→ 素材理解（describe）是写稿主料。
• 拿不准就 ffprobe 看时长与条数：单条 10 分钟以上大概率二创；几十条短素材大概率原创。仍拿不准，问用户一句。
• 原创场景的素材集常常通篇没有对白——那就不跑转写，下表的语种一问以「无对白 / 不转写」闭合，MUST NOT 因缺这个答案阻塞开工。

开工三问：稿源 · 声音基座 · 源片语种。三问开工时与双场景识别一并问清、一张表一次问完、MUST NOT 代猜：

推荐面（公约 §三‴）：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 gtrk skills recommend --scene <id> --json；用户拒绝后不执行推荐动作。

精剪包装（公约 §三⁵）：开工时告知一句「快速成片会在适合的段落做合成包装，最多全片四分之一，不要就说一声」——不是问题，用户说不要即零动作；gtrk composite bake --abi 报烘焙浏览器没装时，在这张问询表里多问一句装不装（不装用本机 Chrome / Edge）。

一′、素材适配闸（写稿前必过）

本闸判的是题材，与「有无自带时序」正交。剧情短片、摆拍表演和单一室内场景不能直接套用旅拍要素层。

取证零新增计费（读的都是编排里本来就要产的东西，MUST NOT 为这道闸新加一次 describe 或转写）：

• 原创场景：读 gtrk matrix index / gtrk matrix describe 已产的 desc（中文视觉描述）与 tags；
• 二创场景：读 gtrk transcript 全文。

判据（可判定，逐条素材过一遍）：

• 主判据——这一条能不能回答「这是在哪、看到了什么」（可辨认的地点 + 所见之物）。能答的占比过低 ⇒ 不适配；
• 反向命中任一即不适配：文本呈现剧情对白（人物一来一往推进情节）/ 摆拍表演（演出来的而非记录下来的）/ 单一室内场景（全片不出一个可辨认的地点）。

命中即硬停：MUST NOT 进入写稿（形制照 gtrk-vlog-docu 的立神闸）。 硬停位置是写稿之前 = TTS 计费之前——它与 §四 检查点①「未经确认 MUST NOT 发起计费动作」是同一条防线的前置一层： 检查点①拦的是「稿子对不对」，本闸拦的是「这活该不该接」。停下时 MUST 如实列出哪几条不适配 + 依据原文 （引 desc / tags / 转写里的原句，别只下结论），并给三条出路：

两条边界写死：agent MUST NOT 自行判死（决定权在用户，本闸只提名不宣判）、MUST NOT 静默照跑—— 静默照跑会让整条链在错误题材上完成并产生不必要的计费，因此必须在此停下。

二、全链总览（快速成片）

① 理解        transcript 原片（二创）/ matrix index + describe（原创）
①′ 适配闸【必过】读 ① 的既有产物判题材（见 §一′）——不是旅拍就硬停，MUST NOT 进入写稿
② 写稿        三段式规约（见 §三）→ 解说稿 + 标题 + HashTag
③ 检查点①     【必停】稿件确认 · 画幅 · 音色 · BGM（gtrk matrix material --scope audio）· 字幕样式 · B-roll 编排量预估（§四）
④ 配音        gtrk tool audio_tts_clone（≤5000 字，句级时码直出）
⑤ 建工程      gtrk project init --tts-task <id> --canvas <WxH>
⑥ 拆分派单    gtrk split 投影 → 你写拆分稿（含字卡 overlay aux）→ split 落地
⑦ B-roll      matrix --local --dirs（二创钉单片）→ describe --plan → lay --mark-weight 0.3 --yes
⑧ 抽帧检查    对字卡挂点抽帧看底轨构图（gtrk-mg SOP）
⑨ MG 字卡     按 §六 轻量规约产颗粒 → mg lint → gtrk mg --project
⑩ BGM        gtrk audio lay --volume 0.1 --beat-align（-20dB 口径）
⑪ 字幕        gtrk subtitle lay --style <检查点①拍板样式>（用户没选用 default）
⑪′ 精剪包装   交棒 /gtrk-composite（公约 §三⁵：auto ≤ 25% → 复核 → 构建机检 → 铺轨烘焙，不停）
⑫ 交付        客户端打开工程出片（gtrk render 仅主轨快照预览，见 §八）

检查点①之后一路跑完不再打扰用户——垂类示例的承诺面就是快速成片一杆到底。 ⚠️ 这条承诺以 ①′ 适配闸通过为前提：闸命中时的那次停顿不算「打扰用户」，它是在把钱花出去之前问一句「这活该不该接」。交付后对个别环节不满意走 §七 增量重跑，对垂类玩法本身不满意走 §七 个性化出路。

三、三段式写稿规约

通用框架层（可移植——其他垂类图纸原样复用本层）

结构三段式：第一部分「钩子」抓眼球保留存 → 第二部分「干货」给内容价值 → 第三部分「升华」给情绪价值。爆款四属性贯穿：快乐+知识+共鸣+节奏。

背景检索建议：写稿信息源除了画面与音频（字幕不一定有）， 建议执行 agent 对素材主题的关键词做一轮背景/上下文检索（地名典故、店家来历、片名与 公开报道等），检索所得须与素材内可见事实互证后才可入稿，并标注来源。 有检索能力就做、没有不强求（能力缺席按纯素材信息写，不算违约）；检索到的外部数字与 争议性说法宁缺勿滥。

文风铁律：

• 禁模板连接词：让我们/首先/然后/最后/此外 等一律不用；
• 拒翻译腔：全部短句中文语感，无欧化从句；
• 禁「否定—转折」对举句式（最高优先级）：禁的是整个家族，不只字面：
• 「这不是 X，而是 Y」／「与其说是 X，不如说是 Y」
• 「X 不仅仅是 Y，更是 Z」／「X 不只是 Y，它还是 Z」
• 「重要的不是 X，而是 Y」／「真正的 X 从来不是 Y」
• 「不是因为 X，而是因为 Y」／「X 靠的不是 Y，是 Z」
• 识别特征：先立一个没人主张过的靶子再推翻它、用对偶结构制造顿悟感、句子的信息量全在后半句而前半句只是垫脚。
• 改法：把后半句直接说出来，删掉前面那个假靶子。「这不是一条水渠，而是一条生命线」→「几百个村民用铁锤在悬崖上凿了三年，就为这一条水渠」。能直接陈述的事实，绝不用对举包装。
• 这条也适用于标题与 HashTag。
• 禁幼稚拟声与过度儿化（★ 打样校准）：「轰隆隆砸下来」这类拟声，换成真实事实（「从九十多米高处坠进谷底，比尼亚加拉还高出近一倍」）——数字与事实比拟声词有力得多；
• 风格目标 = 与原素材旗鼓相当：原片多吸引人，解说就得配得上——贴着原片气质走，不加分（加分是业务化的事，走栏目风格）不减分。

成片时长 = min(内容所支撑, 素材所支撑)：

• 内容支撑：有多少真东西说多少话，素材再多也不注水；
• 素材支撑：按「30% 图片×8 秒 + 70% 视频素材时长」估算上限，稿子在写稿阶段就按上限收敛（不要等铺轨时开天窗）；把这个秒数换算成字数用下一条的折算口径（公式本身不动）；
• 折算口径 = 挂钟语速（wall-clock：稿件字数 ÷ 合成音频总时长，含句间停顿），按检查点①选定的那条音色取值：读 catalog 该音色的 `speech_rate_cpm`（字/分钟），并把 `speech_rate_basis` 一并报给用户（`measured` = 实测 / `derived` = 由声学参数推算）；catalog 没给该字段（非中文音色）或拉不到 catalog 时才用缺省 ≈330 字/分钟，并明说这是缺省估值、不是该音色的实测值。3 分钟成片 ≈ 1000 字。

缺省 330 的依据与标定方法见 references/speech-rate.md，本图纸只引用该单一真值源。

• ⚠️ MUST NOT 拿计费折算常量（240 字/分钟）推稿子字数：计费口径与写稿口径分开，计费常量只用于估算费用。

写后自校验清单（逐项过，不过重写）：

• [ ] 三段结构完整、时长在 min 公式内
• [ ] 禁词零命中、无翻译腔、无幼稚拟声
• [ ] 「否定—转折」对举句式零命中（逐句扫「不是…而是」「不仅…更是」「与其…不如」及其变体；含标题与 HashTag）
• [ ] 重复字/错字扫描（★ 打样实锤：「下瀑布瀑布」重复字 TTS 会照念）
• [ ] 事实矫正：转写稿的明显错误（如数量级离谱的数字）按常识矫正或模糊处理，不确定的不引用
• [ ] 解说序 ≈ 素材序（二创场景：按原片游览顺序写，B-roll 时间窗天然可用）
• [ ] 同批产出：标题 3-5 个（≤30 字）+ HashTag 3-5 个

旅拍要素层（垂类专属）

• 钩子要素（第一部分重点找）：贵大奇多 / 热门 IP / 名人名著 / 知名历史事件 / 全球 TOP 榜 / 奇闻轶事 / 脍炙人口；
• 干货要素（第二部分）：攻略 tips / 游览流程 / 干货&经验 / 旅途见闻，幽默口吻、隔几句一个梗（谐音/反转/无厘头），在精不在多；
• 升华笔法（第三部分）：思考/感悟/启发/感动，正能量收束；第一人称历数、物象隐喻收尾都是成熟笔法；
• 有文化衍生空间（历史典故/风俗人文）可适当发挥，但以原素材内容为锚。

三′、L1 看点 rubric · 画面投影版（供 --highlight-weight 使用）

highlight 是镜头看点分——服务端 VLM 对着一帧画面打 0–100。旅拍这一档的准则 （highlight_rubric）：

判这一帧对旅拍短视频有没有「看点」，0-100：
- 奇观地貌：雅丹/冰川/星空/沙漠/峡谷等罕见地形
- 极端天候光线：日出日落、逆光、雪雾、暴雨、极光
- 人文场面密度：市集、节庆、宗教仪式、当地人劳作
- 反差罕见：人与巨大景观的比例、无人区里的人造物、动物
- 规模感：能看出「有多大/有多高/有多远」的构图
低分：车内挡风玻璃前方公路、酒店房间、无主体的天空、拍糊的中间帧

分工注记（MUST 遵守）：本 rubric 只判镜头可见之物。知识侧要素——地名典故、

历史事件、人文背景——不进画面 rubric，它们归写稿与背景检索（§三 通用框架层已列）。

分工是：画面 rubric 管「这一帧值不值得看」，写稿管「这件事值不值得讲」。

平淡的过渡帧判低分不等于不可用——降权不排除，候选稀疏时照样上（留空更难看）。

传入方式：把上面代码块原样存成工程目录下的 highlight-rubric.txt，理解那一步带上它——

gtrk matrix describe --plan <工程>/split/broll-plan.json --highlight-rubric @<工程>/highlight-rubric.txt

存成文件而非内联，除了免去多行转义，还留下「这条片用的是哪套准则」的可查痕迹。跑完 gtrk matrix lay 自动读 plan 里钉存的同一个桶，不必再传；真传了而且与 plan 钉的不同源，CLI 会硬失败（不静默择一）。 ⚠️ 换准则重新打分要重新看片（1 积分/张）：客观描述缓存不被覆盖，但看点分按准则分桶，新桶没分就得重打。

四、检查点①（双模式共有，必停）

写完稿必须停下，把以下六项一次给用户拍板。未经确认 MUST NOT 发起 TTS 与 B-roll 云端编排计费动作。

本地素材的编排缺省走云端并按编排量计费。matrix lay 跑前必须报告预估用量，取得同意后才能带 --yes；无 TTY 且未确认时整轮中止，工程不改动，plan 可重跑。

语种不在这六项里：它在 §一 开工三问就已定，检查点①对它最多做过目复核。

MUST NOT 把语种拖到这一步才问——此时 ① 的 gtrk transcript 已经跑完并已计费，稿子也已按错语种写出来了。

1. 解说稿 + 标题：正文全文贴给用户（不是给路径），标题候选列出；
2. 画幅：问目标平台——横屏 B 站/西瓜=1920x1080，竖屏抖音=1080x1920。素材几何与画幅不一致时明确提示（横素材→竖画布会裁切或留边）；
3. TTS 音色：拉 catalog（GET {apiBase}/task/tts/voices，免鉴权）按内容调性挑 2-4 个候选，每个附试听链接（catalog 的 audition_url 字段，api.ai-mcn.tv:9000 静态直链）——用户在对话框里直接点开听。internal 标注的音色注明「仅内部成员」。也可按用户描述语义挑（「要个温柔女声」）。

每个候选还 SHALL 附上该音色的挂钟语速与据此推的稿件字数区间（取同一份 catalog 载荷里的 speech_rate_cpm + speech_rate_basis，零额外往返；该字段缺席就明说「用缺省 330 估」；标定方法见 references/speech-rate.md）——挑音色的同时也是在挑稿子长度，别让用户回头才发现稿子长了三成。这条是加项，MUST NOT 削弱既有的「无试听链接 = 未完成推荐」义务；

1. BGM 处置（双来源）：

• 用户有本地音乐 → 询问是否 gtrk tool audio_separation 伴奏分离后取伴奏（缺省建议分离——TTS 配音不与歌曲人声打架）；
• 用户未提供 → 搜同和素材矩阵：gtrk matrix material "<按稿件情绪+地理文化写的检索词>" --scope audio --top-k 5 --diversity --json

（检索词口径见公约 §三′：内容驱动、禁通用词、至少含一个只有这一片才成立的词；候选 MUST 给用户挑不许默认 top1；跨片避让由 audio lay 记账 + 检索缺省 --exclude-recent 自动完成（按成片时长可加 --min-duration <秒>）。身份路由与计费口径由零件持有；版权状态要如实转述——is_copyright=true = 可商用、false = 不可商用。矩阵成员档缺省搜全库并逐条给 copyright_label；用户特意说明只要可商用或商用发布时才加 --commercial-only 收紧。upsell 是独立顶层字段，不是候选。 推荐 3-5 首、每首附试听链接（结果的 download_url）；audio_type:"pure" 纯音乐直接用，"song" 直接取 accompaniment_url 现成伴奏（零处理成本，两档都有）；注意曲长 vs 成片时长（duration 字段）：audio lay 缺省循环叠满至工程末尾、尾段裁齐（多 clip 首尾相接，命令会打 INFO 报段数），短曲只是接缝多一些、不会铺一半就静音（想少几道接缝，挑曲时加 --min-duration <秒>）；要单次铺请显式传 --no-loop；

• 试听链接义务（MUST）：音色与 BGM 的推荐没有试听链接=未完成推荐。
• BGM 落地一步（MUST）：检索出参只给签名 URL，而 gtrk audio lay --file 只收本地路径。拍板后先把选中曲落成本地文件：audio_type:"song" 取 accompaniment_url 伴奏版，"pure" 取 download_url。文件名按 bgm-<曲名>[-伴奏].<扩展名>，供跨片避让记账使用。

1. 字幕样式：7 种样式（default/outline/cinema_yellow/immersive_box/wide_spacing/deep_shadow/boxed）× 11 色（雅黑/淡绿/森林绿/湖蓝/道奇蓝/钢蓝/浅粉红/深橙/珊瑚橙/橙红/土豪金）挑选；用户没选就用 default+雅黑（不追问不阻塞）。拍板值在 ⑪ gtrk subtitle lay 落地，客户端里仍可整轨换样式（悔棋通道）。
2. B-roll 编排量预估（本地素材路必报）：本地素材产的 plan 走 matrix lay 时缺省即云端编排并按编排量计费（--arrange local 不受理）。先拿数再拍板：

``bash gtrk matrix lay --project "<工程目录>" --arrange-estimate-only --json # 停在计价确认之前：零云端调用、工程文件零改动 ``

把它与 TTS / describe 的预估同屏报给用户，一次拿到同意——§五 ⑦ 的 lay 才允许带 --yes。报不出这笔就不许开跑。

五、快速成片编排（打样验证过的真实命令）

产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）：文本产物写入 CLI 返回路径或用户显式指定的 -o, --out；交付物直接写入工程目录；引用媒体用原路径，不复制到 agent 工作目录；临时文件放系统 temp，用完即删。

交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。

# ① 理解（二创：转写原片，--json 顺产 transcript.json 备用）
gtrk transcript "<原片>" --lang <zh-CN 普通话 | zh-HK 粤语 | en-US | ja-JP …> --json -o "<工程目录>/transcript/<片名>-transcript.md"
#   ↑ 产物落点：不带 -o 时两个产物都落**源片同目录**（`<名>-transcript.md`；--json 另产 `<名>-transcript.json`，
#     .json 跟随 .md）。缺省本身是在案设计，但二创素材多在用户素材库里 ⇒ SHOULD 用 -o 挪进工程目录（见本节顶部纪律块）
#   ↑ 语种取开工三问的答案，MUST NOT 拿缺省 zh-CN 顶上去 —— **但这条对「非中文」素材才有钱可省**：
#     粤语 SHOULD 如实填 zh-HK（元数据诚实 + 备将来链路切换），当前链路下它与 zh-CN **对粤语无差别** ——
#     CLI 写死 word_level: true（src/commands/transcript.ts:178）⇒ 链路钉在豆包、到不了 Whisper
#     （infra utils/process/media/audio/asr.py:44-49 在 AsrFunc.Whisper 分支里仍把 word_level_handler 钉成豆包）；
#     而豆包字典里 zh-CN 与 zh-HK **都映射空串**（utils/partner/volcengine/doubao_llm_asr.py:36-37）
#     ⇒ 两种写法发出的请求逐字段相同。粤语能识别对，靠的是豆包空串模式自己的方言自适应，与这个参数无关。
#     "zh-HK": "yue" 那条映射真实存在（utils/partner/openai/__init__.py:18），但只在 word_level=false
#     走 Whisper 时生效，CLI 今天走不到那条路。
#   ↑ **MUST NOT 以「粤语语种传错」为由重跑转写**：la 进 ASR 缓存键（asr_result_cache.py:71-75），
#     换码必然 cache miss，白扣一次时长换回逐字段相同的请求与同一份结果。
# 原创场景改跑：gtrk matrix index --dirs "<素材夹>" && gtrk matrix describe --materials ...
#   ↑ **这个 `&&` 现在真的会拦住**：全域零枚举（一个素材都没枚举到）是**硬失败**（退出码 1），
#     `describe` 不会执行 —— 这是改对了：以前 index 报 0/0 也 exit 0，`describe` 会对着空清单空跑一趟。
#     报 0/0 先看两件事：路径里有没有**英文半角逗号**（有就把 --dirs 重复传 `--dirs "A" --dirs "B"`，累加不覆盖）、
#     素材夹里有没有断链。⚠️ 「个别素材处理失败」不算硬失败（那是既有 failed 计数口径，退出码仍 0）。
#   ↑ 原创（自拍素材集）这一档**整夹即该片素材域，传夹正确**，不受 ⑦ 那条「钉单片」铁则约束——
#     那条治的是二创：一个夹里躺着几条互不相干的片，才会互相抢候选
 
# ②③ 写稿（你执笔，§三规约）→ 检查点①拍板
#   BGM 候选（用户没自带音乐时，检查点①之前搜好一起拍板；试听链接=结果的 download_url）
gtrk matrix material "<情绪+地理文化检索词>" --scope audio --top-k 5 --diversity --json
 
# ④ 配音（音色 code 用 catalog 的 voice_id；稿子存 txt 传 --text-file）
gtrk tool audio_tts_clone --text-file <稿.txt> --speaker <voice_id> --json