gitruck/cli/gtrk-vlog-docu

gtrk-vlog-docu（Vlog 纪实类 · 组合成片图纸）

审片与脚本的实际工作顺序

先建立全批素材概览，包含视频、照片和原声，再提出影响主线的关键问题。已有回答直接沿用，不重复问。不要先定故事，再只找支持它的几张画面。

视觉部分沿用 gtrk-matrix 的当前 Agent 优先通路：describe --materials ... --prepare <工程目录/visual-overview> → 当前 Agent 按时码看图、记录事实与不确定项 → --review <回执> 导入。长场景多个观察点；动作、表情、剪辑入出点在相关窗口内加密查看。原声有内容时结合转写/试听；不能把抽帧概览称为完整看过原片。Agent 无视觉能力或单项无法完成时才由豆包补齐，注明回退原因。

概览后组织可审阅的视听脚本：每段表达什么、采用哪条素材的哪个时间区间、保留什么同期声、哪里需要旁白、照片如何进入。交给用户审阅；有异议则多轮修改同一份脚本，认可后继续成片。照片可由既有图片运镜能力进入时间线，但不能虚构照片之外的事件。

明确脚本的取材由语义与实际画面证据主导；泛高光发现只是探索素材的一种工具，其分数不能覆盖脚本意图。下方云端 describe 示例仅在当前 Agent 无法完成时直接使用；有视觉能力时先 prepare/review，交接由 Agent 完成，不让用户填逐帧表格。

把一批现场素材变成一条纪实成片工程：素材理解 → 选档写稿 → 检查点①一次拍板 → 同期声骨架 + 旁白配音 + B-roll + 字幕层 + BGM 全自动 → 客户端出片。

定位：structure 级组合图纸，不新增命令，只编排既有原子零件。零件参数以各自 skill（gtrk-transcript / gtrk-matrix / gtrk-splitter / gtrk-mg）与 --help 为准，本图纸引用不复制；编排次序、检查点、配方参数以本图纸为准。CLI 是手，你是脑。

本体定性：

纪实 Vlog 是散文的载体——用有限的素材，把一个故事、或一个几个思想，最终串联起来。

三个推论，构成本图纸的全部决策原点：

- 形散神不散：素材可以跳跃、场景可以断裂、时间可以不连续，但必须有一根线。没有那根线的片子叫「相册」不叫作品。

- 素材有限是前提不是缺陷：创作力体现在「用手上这些素材能串出什么」，不是「还差什么素材」。先看素材里有什么，再决定串什么——这是散文与说明文的分野。

- 先立神，再选材：写稿的第一步不是排素材顺序，是找到那根线（§3.2）。顺序反了就会写成流水账。

表达形态上的定义性特征：纪实类是双声道交替——现场同期声承载真实感与人格，后期旁白承载知识与升华。同期声片段是内容本体，不是可替换的配画。这是它区别于口播链与配音链的根本。

当前实现状态：本地候选 CLI 已支持 gtrk project compose，按清单组装视频、图片和已合成旁白。先用 gtrk project --help 核对当前安装版本是否提供 compose；旧版不支持时停在图纸，不手写工程冒充链路。声音仍经检查点确认后生成。

高光发现与失败兜底（仅本图纸使用）

在全批概览之后，用户只说“挑高光”或某段值得探索但缺少明确事件线索时，按需执行：

gtrk tool video_highlight "<本地视频>" --out "<工程目录>/highlight/<素材名>" --json

该入口当前仅供内部验收。只上传本地生成的448p/4fps分析代理，缺省附单声道低码率原声，原片不上传；用户在意对话隐私时加 --no-audio，只少一项声音信号，候选照常产出。若报错要求短边224或无音频，说明云端尚未升级到新版代理，如实告知用户，不要重试或自行改参数。结果在 result-output.json。groups 各自的 top3 只代表该请求内的三秒候选；不可跨素材、跨分块混排分数。用 matrix describe --materials <原片> --source-window <起秒,止秒> --prepare <目录> 查看候选前后过程，再结合原声判定它能否进入脚本。不要用三秒评分推断整段事件完整性。已有明确脚本时优先语义检索，不自动调用视频高光算法，也不覆盖语义 best 或 VLM highlight。

服务忙、冷却、超时、坏响应、无候选或接口未部署时，记录素材、任务号（若有）、失败原因和后续来源 agent_semantic_overview，继续从已观察素材按故事选材。视觉项当前 Agent 确实无法完成才标 unavailable 交豆包；两者都不可用则保留缺口，不写成已看过。纯粹请求“高光评分结果”时，原子失败就如实报告未完成。已有任务号优先查询原任务；提交状态未知时用同一素材、输出目录恢复，不换身份盲目建单。

脚本验收交付物

在工程目录维护一份可持续修改的视听脚本，按顺序列出：段落目的、源素材、源入出点、预计片长、画面事实、同期声或环境声、旁白、照片运镜、证据覆盖与待核对项。素材时间轴与成片时间轴分列。旁白草稿不当作录音事实，未听清的同期声不编台词，文件名日期不自动当作真实行程日期。

连同全批素材概览、采用/舍弃理由、高光调用与回退记录一起交付。先审这份完整图纸；用户认可后再合成旁白、组装工程和渲染。组装必须走 project compose，不能手写 .gtrk；图纸确认和成片验收分别记账。

一、输入契约与三档识别

用户给一个素材文件夹（多个用逗号分隔）：

MUST NOT 执行任何网络下载：素材从哪来归用户（版权责任边界）。

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

1.1 配比档位识别（本类型独有的第一决策）

先听素材里有没有可用的同期声，再定档——档位决定写多少稿、TTS 花多少钱、成片什么质感：

判别动作：gtrk transcript 抽听 1-2 条代表素材——转写出大量口语碎句、语气词、对话接话 → A 档；几乎无人声或只有环境音 → B 档；有对话但用户明显想表达观点 → C 档。拿不准问用户一句：「你是想让现场的声音说话，还是你来讲？」

C 档适合需要升华观点的自制片：以纪实同期声承载事件，中后程切入议论式旁白，把当天经历升华为观点与私人自白，落一句可摘录的态度句。有条件优先推 C。

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

① 理解        transcript 抽听定档 + matrix index/describe 建素材索引
② 立神        ★【多轮对话·必问】与创作者访谈找出那根线，问够为止（§3.2）
③ 选材串珠    按「神」挑素材、定幕结构（服务于神，不是按时间流水排）
④ 写稿        只写定调层旁白（§三）→ 稿 + 标题 + HashTag
⑤ 检查点①    【必停】神 · 配比档 · 稿件 · 画幅 · 音色 · BGM · 字幕样式（§四）
⑥ 配音        gtrk tool audio_tts_clone（仅旁白段，★ 分段合成）
⑦ 拼主轨      gtrk project compose（分段清单 → live 段引用原片区间 + narration 段落位）
⑧ 拆分派单    gtrk split：live 段=A_ROLL/真人出镜|口播继续；narration 段=FILM_BROLL|MG/旁白主导
⑨ B-roll      matrix --local --dirs → describe → lay（只铺 narration 段空档）
⑩ 字幕层      吐槽/观察/进度/梗卡进 MG 派单（§六）→ mg lint → mg --project
⑪ BGM         gtrk audio lay --volume 0.1 --beat-align（-20dB 口径）
⑫ 字幕        gtrk subtitle lay --style <拍板样式>
⑫′ 精剪包装   交棒 /gtrk-composite（公约 §三⁵：auto ≤ 25% → 复核 → 构建机检 → 铺轨烘焙，不停）
⑬ 交付        客户端打开工程出片

快速成片的「免打扰」只覆盖 ⑥ 之后的执行环节：①–⑤ 沿用已有创作意图，补问必要信息并保留检查点①，MUST NOT 因为用户选了快速成片就跳过立神对话自行拍板——那是把创作者的片子做成 agent 的片子。用户要精修按 §七 逐步停。

三、写稿规约

3.1 通用框架层（原样继承旅拍图纸，勿改）

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

文风铁律：

• 禁模板连接词：让我们/首先/然后/最后/此外；
• 拒翻译腔：短句中文语感，无欧化从句；
• 禁「否定—转折」对举句式（最高优先级）：八成的 AI 厌恶感来自这一种句式。禁整个家族：「这不是 X，而是 Y」「与其说是 X，不如说是 Y」「X 不仅仅是 Y，更是 Z」「重要的不是 X，而是 Y」「不是因为 X，而是因为 Y」。识别特征=先立一个没人主张过的靶子再推翻它、用对偶结构制造顿悟感。改法=把后半句直接说出来，删掉假靶子。能直接陈述的事实，绝不用对举包装。也适用于标题与 HashTag。
• 禁幼稚拟声与过度儿化：换成真实事实——数字与事实比拟声词有力。
• 风格贴着素材走：素材什么气质，稿子就什么气质，不加分不减分。

成片时长 = min(内容支撑, 素材支撑)；旁白折算用挂钟语速（按检查点①选定的音色取，取不到用缺省 ≈330 字/分钟）——口径与标定档案见 skills/gtrk-travel-recap/references/speech-rate.md，MUST NOT 复制数值表。

3.2 立神：找出那根线（★ 本类型的第一步，先于选材）

纪实 Vlog 是散文的载体——用有限的素材，把一个故事、或一个几个思想，串联起来。「神」就是那根线。没有神的片子是相册，不是作品。

主线由创作者决定：先利用已有回答和素材概览，只有仍影响主线的缺失信息才提问。用户已经讲清经历、重点和感受，或授权其余内容按素材编排时，直接写出可审阅脚本，不机械增加访谈轮数。多轮修改围绕同一份脚本进行，快速成片也保留脚本确认。

访谈协议（写稿前必做）：

第一步，agent 自答素材侧一问：这堆素材里反复出现的东西是什么？（一个地方的衰败痕迹、一群人的某种状态、一件事的三次反复）——据此提名 1–3 个候选神。

第二步，向创作者开问（每轮 1–2 个问题，别一次倒完；按回答追问）：

第三步，收敛判据（满足其一即立住）：创作者用自己的话说出了神；或对 agent 提名的候选明确说「就是这个」。agent MUST NOT 单凭素材分析自立神；创作者的说法与素材分析冲突时，以创作者为准（可以提醒「素材可能撑不住这个神」，但决定权不在你）。

神的确认不止一次：立神访谈初确认 → 检查点①随稿件终确认（此时创作者看得见神落在稿子上的样子，常会修正）→ 精修中仍可推翻重立（神变 = 稿全变，如实告知代价再动）。

神的三种类型（选一，也可故事线套思想线）：

立神后 MUST 一句话写下来（写进检查点①给用户确认）：

「这条片是关于 ______ 的。」

写不出来 = 神没立住，MUST NOT 进入写稿——回去重看素材或问用户。

形散神不散的操作含义：

• 允许素材跳跃、场景断裂、时间不连续（散文的自由）；
• 要求每一段都能回答「它为神做了什么」——是铺垫、是印证、是转折、还是留白？答不上来的段砍掉，哪怕画面好看；
• 素材有限是前提不是缺陷：不要为「素材不够」而注水或强行拉长。手上有什么，就串什么——这正是本类型的创作力所在。

⚠️ 主要失败模式：素材拍得不差却没有串成一条神，记录了一天的见闻，每段都成立，合起来仍像相册。它比文笔差、素材糙更致命。

3.3 纪实要素层（本类型专属）

★ 第一铁律：旁白只写定调层，同期声段不写稿。

这是新手最易犯的错——把全片写成解说稿，旁白盖住现场声，纪实感当场消失。写稿前先在素材序列上标出哪几段留给现场（有对话、有反应、有笑点的），旁白只写：

站点模块化循环（可选结构件，不是默认）：结构服务于神——神是「攻略/巡礼」型（信息即价值）时，站点循环是最优结构；神是故事线或情绪线时，MUST NOT 套站点模板（会把散文切成说明书）。攻略型每站跑一遍——

到场定位（口播或旁白一句）→ 背景科普（旁白）→ 现场体验（同期声，让开）→ 攻略数字（旁白/字卡）→ 转场（车程字卡）

攻略信息件标准化（收藏钩）：凡有地点/消费属性，每站必报车程 + 价格 + 免费与否 + 避坑，缺一项就少一分收藏价值。数字进字卡比进旁白更好用。

Resonance 素材优先（有则必用、无则不硬造）：用坦白脆弱（落榜、心碎、没钱、亲人离世）与集体记忆锚点（城市旧地标、经典电影、老游戏）建立共鸣。写稿前问用户一句：这趟有没有什么真话想说？有就放进升华段，没有就老实做知识与快乐，不要编情绪。

态度金句是收尾硬指标：升华段必须落一句可摘录的话（能被观众截图、能当评论区引用）。写完自问：这句话单独拎出来，有人愿意转发吗？

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

神（第一组，先过这组）：

• [ ] 神一句话在位：「这条片是关于 ______ 的」写得出来且用户已确认
• [ ] 逐段问责：每段都能回答「为神做了什么」（铺垫/印证/转折/留白），答不上的已砍
• [ ] 无注水：没有为凑时长保留的与神无关段

结构与文风：

• [ ] 三段结构完整、时长在 min 公式内
• [ ] 禁词零命中、无翻译腔、无幼稚拟声
• [ ] 「否定—转折」对举句式零命中（含标题与 HashTag）
• [ ] 重复字/错字扫描（TTS 会照念）
• [ ] 旁白零覆盖同期声段：逐段核对，现场段是否被旁白盖住
• [ ] 旁白零描述画面：删掉所有「可以看到」「画面中」

HKRR 四维（缺哪补哪）：

• [ ] H 快乐：现场层有没有笑点/反差/失控瞬间被保住
• [ ] K 知识：定调层有没有硬数据或即兴科普（无 K = 相册式记录）
• [ ] R 共鸣：有没有坦白段或集体记忆锚点（无素材则跳过，不硬造）
• [ ] R 节奏：有没有语音形态换挡、数字进度条、名场面前置、空镜留白

抖音四目标（各至少命中一项）：

• [ ] 评论：开放式提问收尾 / 评论区点单机制 / 争议性观察
• [ ] 收藏：攻略信息件是否标准化（车程/价格/避坑）
• [ ] 分享：态度金句是否可摘录
• [ ] 关注：固定自称/口头禅/系列预告/署名卡是否在位

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

写完稿必须停下，把以下七项一次给用户拍板。未经确认 MUST NOT 发起 TTS 计费动作。

1. 神（那根线）· 终确认：一句话「这条片是关于 ______ 的」+ 神的类型（故事线/思想线/情绪线）。此处是 §3.2 访谈初确认之后的第二次确认——创作者此时第一次看见神落在稿子上的样子，常会修正，这是正常且被鼓励的。这是最上位的拍板项：神错了，稿再好也是别人的片；
2. 配比档位（本类型独有）：明确告诉用户你判的是 A/B/C 哪档、旁白占比多少、哪几段留给现场声。这一项拍错，后面全白跑；
3. 旁白稿 + 标题：正文全文贴给用户（不是给路径），标注每段旁白挂在哪个位置；标题候选列出；
4. 画幅：横屏 B 站/西瓜=1920x1080，竖屏抖音=1080x1920。素材几何与画幅不一致时明确提示；
5. TTS 音色：拉 catalog（GET {apiBase}/task/tts/voices，免鉴权）挑 2–4 个候选，每个附试听链接（audition_url）。⚠️ 纪实类的旁白与现场同期声会交替出现，音色应贴近用户本人音色或明显区分（避免观众困惑「这是谁在说」）——如用户本人出镜说话，优先建议同性别接近音色；
6. BGM 处置（双来源）：用户自带 → 询问是否 audio_separation 取伴奏；未提供 → gtrk matrix material "<按内容情绪写的检索词>" --scope audio --top-k 5 --diversity --json，推荐 3–5 首每首附试听链接（download_url），audio_type:"song" 取 accompaniment_url。⚠️ 版权状态如实转述：is_copyright 的语义是 1/true=可商用、0/false=不可商用（反直觉，MUST NOT 把 false 读成「无版权、可随便用」）；矩阵成员档缺省搜全库，MUST NOT 默认加 --commercial-only、也 MUST NOT 擅自剔掉 false 的候选，但推荐时 MUST 逐条带上派生位 copyright_label 的中文标签（不追问不阻塞）——用户特意说明只要可商用 / 要商用发布时才加 --commercial-only 收紧。⚠️ 纪实类 BGM 要给同期声让路，音量口径同旅拍（-20dB）；
7. 字幕样式：7 样式 × 11 色；用户没选用 default+雅黑（不追问不阻塞）。

试听链接义务（MUST）：音色与 BGM 的推荐没有试听链接=未完成推荐。

五、快速成片编排

链路形态：C 分段拼接——全片切 N 段，每段声明 live（同期声段，引用原片区间，内容本体）或 narration（旁白段，TTS + B-roll 空档），由 gtrk project compose 按序拼主轨。设计草案见探索工件 §四之二。

compose 只引用本地文件：TTS 先合成落地，再以 narration 的 source 引用；需要旁白叠在已确认画面上时，用既有 audio lay --offset 另铺音轨。图片要运动，先用 image_move 产视频再入 live；image 段本身只显示静帧。

分段旁白铺完后，使用 gtrk patch set --clip <旁白片段ID> --audio-track <首条旁白轨的track_index> --project <工程目录> 将同一讲述者的各段收进同一条旁白轨，保持原时间位置；同期声与 BGM 各自独立。重铺旁白后也要归轨，不能把“一段一轨”的阶梯布局作为交付。目标时间段已有片段时先检查重叠，不强行合并。

大场景或活动转换处用简短 MG 交代叙事关系（如从游览转到参与体验），不按每个镜头机械加字卡，不杜撰日期/地点。手写 GSAP 颗粒须在 template 内先声明 gsap.min.js，再创建并注册 paused 时间线；静态 lint 通过不等于预览可见，交付前还应检查客户端播放环境内的入场与驻留。

# ① 理解与定档（抽听 1-2 条代表素材；live 段的 in/out 时码后面全从这份转写里读）
gtrk transcript "<代表素材>" --lang zh-CN --json
gtrk matrix index --dirs "<素材夹>" --json          # 建本地索引（素材本体不上传）
 
# ②③④ 立神 → 选材串珠 → 写稿（你执笔，§三规约）→ 检查点①拍板
gtrk matrix material "<情绪+题材检索词>" --scope audio --top-k 5 --diversity --json   # BGM 候选
 
# ⑥ 旁白配音（★ 纪实类分段 TTS，不是全片一条）
gtrk tool audio_tts_clone --text-file <旁白段1.txt> --speaker <voice_id> --json
gtrk tool audio_tts_clone --text-file <旁白段2.txt> --speaker <voice_id> --json
#   ↑ 每段单独合成，compose 按段落位；同参重合成走缓存不重复扣费
 
# ⑦ 拼主轨（新目录；不覆盖既有精修工程）
gtrk project compose --list <分段清单.json> --out <新工程目录> --canvas 1920x1080 --json
# 清单：{"version":1,"segments":[
#   {"kind":"live","source":"原片.mp4","in":3,"out":11},
#   {"kind":"narration","source":"旁白.wav","transcript":"旁白-transcript.json"},
#   {"kind":"image","source":"合影.jpg","duration":4}
# ]}
# live 默认保留原声；keep_audio:false 才关闭。旁白段留画面空档给 B-roll。
# 原片不上传；路径相对清单；in/out 单位秒。transcript 为源时基 st/ed/text 句表。
# 毛边由选段保留；compose 不做静默删除或自动精剪。
# 多源文稿逐句绑定素材，split/subtitle 根据当刻工程重投影。
# 没提供 transcript 的素材不生成猜测字幕，跨切点整句会省略并报告。
 
# ⑧ 拆分派单（★ 本类型的车道映射，词表无需扩展）
gtrk split --project "<工程目录>" --json          # 投影拿句表
# 你写 split/visual-split.json：
#   live 段      → lane:"A_ROLL"，base_track:"真人出镜"（出镜）或 "口播继续"（画面切走声音继续），无 handoff
#   narration 段 → lane:"FILM_BROLL" 或 "MG"，base_track:"旁白主导"，handoff 按 lane 分型
#   字幕层/字卡  → aux_layers type:"overlay"（进 dispatch.mg）
gtrk split "<拆分稿>" --project "<工程目录>" --json
 
# ⑨ B-roll（★ 只铺 narration 段空档，live 段 MUST NOT 覆盖）
gtrk matrix --project "<工程目录>" --local --dirs "<素材夹>" --lay 0 --json
gtrk matrix describe --plan "<工程目录>/split/broll-plan.json" --yes --json
gtrk matrix lay --project "<工程目录>" --mark-weight 0.3 --gap-fill fast --json
 
# ⑩ 字幕层字卡（§六 规约）
gtrk mg lint "<工程目录>/mg/<composition_id>.html" --dispatch "<工程目录>/split/dispatch.json"
gtrk mg --project "<工程目录>" --json