@gitruck/cli 1.0.5 → 1.0.7

package/skills/gtrk-talking-head/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: gtrk-talking-head
+description: 通用口播视频创作图纸（口播链）——把一条或一组真人出镜的口播毛片，做成完整包装的可出片工程：外录音轨对齐换轨 → 多段拼接 → oralcut 粗剪 → 拆分派单 → B-roll/MG 字卡 → BGM → 字幕 → 客户端出片。当用户想「口播视频从毛片做到成片 / 口播完整包装 / 我拍了几段口播帮我做成一期 / 领夹麦音轨怎么合进去 / 口播加 B-roll 加字卡 / talking head 成片」时使用本 skill。凡涉及真人口播的完整成片编排，优先用本图纸驱动全链，别只跑一句 oralcut 了事、也别手搓 ffmpeg。
+---
+
+# gtrk-talking-head（通用口播 · 组合成片图纸）
+
+把**真人出镜的口播毛片**（一条或一组）变成**完整包装的可出片工程**：双轨换声 → 拼段 → 粗剪 → 检查点① → 拆分 → B-roll → 字卡 → BGM → 字幕 → 客户端出片。
+
+> **定位**：第四张 **structure 级组合图纸**。本图纸自身不新增命令，只编排零件（audio align / oralcut / split / matrix / mg / audio lay / subtitle lay——其中对轨零件 `gtrk audio align` 与本图纸同批交付）。零件参数细节以各自 skill（`/gtrk-oralcut`、`/gtrk-splitter`、`/gtrk-matrix`、`/gtrk-mg`）与 `--help` 为准，**本图纸引用不复制**；编排次序、检查点、双轨与多段规约以本图纸为准。**CLI 是手，你是脑。**
+
+**与另外三张图纸的分野**（先对号入座再开工）：
+
+| 图纸 | 内容从哪来 | 产物 |
+|---|---|---|
+| 旅拍解说 | 素材 + **AI 写稿 + TTS 配音**（无真人出镜） | 完整包装工程 |
+| 直播切片 | 直播回放，**只粗剪不包装** | 一批粗剪工程 |
+| **口播链（本图纸）** | **真人已把内容讲完**，AI 只做剪与包装 | 完整包装工程 |
+
+> 用户只要「剪干净」不要包装 → 那是一句 `/gtrk-oralcut` 的事，别拉全链。
+
+## 一、输入契约与开工五问
+
+**输入**：口播毛片本地文件（一条或多条），可带独立外录音轨（wav / MP3 / m4a / flac），可带文稿 txt。
+
+| # | 问 | 怎么取证 | 决定什么 |
+|---|---|---|---|
+| ① | 一条还是多条？多条是**一期分段**还是**各自成片**？ | **问用户，MUST NOT 代猜**（同日多条两种都常见） | 走不走拼段（§三） |
+| ② | 有无独立外录音轨？ | 看目录配对（每条视频旁的音频文件）+ ffprobe 时长比对 | 走不走双轨换声（§二） |
+| ③ | 有没有文稿？ | 问用户。**⚠️ 即兴内容禁传事后整理稿**——oralcut 会把「终稿外内容」当废话剪掉，即兴场景必须走无稿智能重建 | `--script` 传不传 |
+| ④ | 毛片几何 | ffprobe | 画幅随片（**非拍板项**，与旅拍不同——那边是无中生有须拍板画幅）；非标帧率会被吸附到标准值，属预期 |
+| ⑤ | **B-roll 素材来源**（主理人 2026-08-27 真机挑刺拍板） | **问用户，MUST NOT 硬塞**：有没有本地素材文件夹（要路径）？要不要用云端素材填充？ | §五 matrix 走法三选一：本地（`--local --dirs`）/ 云端 / **都不要 = 不铺 B-roll**（纯 A_ROLL + MG 字卡也是完整成片形态） |
+
+## 二、双轨收音：对轨 → 换轨（本图纸最大的新东西）
+
+真实口播几乎都是**双轨收音**：相机内录只是参考声，领夹麦/录音笔的外录才是成片要用的。而粗剪链吃的是视频文件里的音轨 ⇒ **先把外录换进去，转写和成片就都是外录声**。
+
+**对轨是可选前置**：用户给的毛片若已换好轨（或本就单轨无外录），本节整体跳过、后续零差别——链路不检查任何「对轨凭据」。
+
+### 一条命令，不用人判两态
+
+```bash
+gtrk audio align "<毛片>" "<外录>"
+```
+
+已对齐、未对齐**都直接跑自动分支**——已对齐的素材会测出 offset≈0 且高置信（真机实证：三段等长 wav
+全测得 0、置信度 8.8–13.6）。**测出 0 比假设 0 更稳**：万一素材其实没对齐，假设 0 会静默错轨。
+`--offset 0` 只在你确知偏移时用（跳过检测省几秒）。
+
+命令自动互相关测偏移并给**置信度**，按置信度分流：
+
+1. **置信度 ≥ 阈值** → 直接换轨产 `<名>_extaudio.mp4`，回执打印偏移/置信度，**零人工**。
+2. **置信度 < 阈值** → 不猜、不硬上：命令产一个**对齐工程** `<名>_align.gtrk`（视频 + 外录双素材）——让用户在**客户端时间线上拖音轨对齐**（有波形有预览，比任何抽听都直观），保存后：
+
+```bash
+gtrk audio align --resume "<名>_align.gtrk"
+```
+
+　　读回人工确认的偏移，完成换轨。
+
+> 命令面细节（`--offset` / `--threshold` / `-o` / `--json`）以 `gtrk audio align --help` 为准，本节不搬手册。
+
+### 三条纪律
+
+- ⚠️ **换轨产物是新文件，且是后续工程的素材——用户必须留存**，删了工程就素材脱机（同直播切片的切段警告）。
+- **内录不丢弃**：原毛片原地不动就是保底轨，外录出问题（爆音/断录）随时回退重跑。
+- 闭环：oralcut 产的工程本来就进客户端 ⇒ **对齐效果（唇音同步）最终以客户端预览为准**——兜底与验收用同一个工具。
+
+## 三、多段一期：concat-first
+
+一期内容由多段毛片构成时（分场景拍摄、换机位重启录制），**先拼后剪**：
+
+1. **参数一致性四查**：编码 / 几何 / 帧率 / 音频采样率（`ffprobe` 逐段比对）。同机位同期拍摄基本都一致。
+2. 一致 → `-c copy` 无损拼接（先逐段完成 §二 换轨再拼）：
+
+```bash
+printf "file '%s'\n" seg1_extaudio.mp4 seg2_extaudio.mp4 seg3_extaudio.mp4 > list.txt
+ffmpeg -f concat -safe 0 -i list.txt -c copy "<工作区>/inputs/<期名>_full.mp4"
+```
+
+3. 对拼接产物跑**一次** oralcut——一份工程、一次计费、粗剪自然跨段（段间的重录/垫场会被当停顿剪掉）。
+4. **参数不一致**（罕见）→ 逐段各跑 oralcut 出 N 份工程、拼接归用户在客户端做。**MUST NOT 静默转码统一参数**。
+5. 拼接产物同受「留存」警告。
+
+## 四、粗剪与检查点①（必停）
+
+```bash
+gtrk oralcut "<inputs/…_full.mp4>" --lang zh-CN [--script 稿.txt] [--preset concise]
+```
+
+命令与参数细节归 `/gtrk-oralcut`，本节只管**走查什么**：
+
+1. **粗剪回执走查**：时长压缩比是否合理（口播毛片通常剪去 20–50%）、report 剪除项抽查 2–3 处是否真是废话。**剪错了真内容** → 换 `--preset steady` 或开 `--visual-assist` 重跑，MUST NOT 带着错误粗剪往下铺。
+2. **BGM 拍板（双来源，推荐必附试听链接）**：用户自带音乐 → 问是否 `audio_separation` 分离取伴奏；没带 → 素材矩阵按内容基调搜 3–5 首附试听直链。
+3. **字幕样式拍板**：给样式候选，用户没选用 default。
+
+以上三项一次确认完 = 检查点①收口。
+
+## 五、拆分与铺轨：三车道，无 AI 再现
+
+口播链拆分**只派三车道**（拍板：口播场景不需要 AI_DRAMA）：
+
+- **A_ROLL 主导**：真人出镜是叙事主体——大部分 beat 就该是 A_ROLL，别为了「丰富」硬切走人。
+- **FILM_BROLL 辅助**：只在**需要视觉支撑**处切出（提到具体事物/场景/数据来源时），切出必回。
+- **MG 字卡强调**：金句、要点列举、数字——叠加强调，不抢主体。
+
+流程与制片顺序（遵既有定序，细节归各车道 skill）。**B-roll 步按开工⑤的确认结果走**：
+用户给了本地素材夹 → `gtrk matrix --local --dirs`；同意云端 → `gtrk matrix`；都不要 →
+**跳过 matrix，拆分稿不派 FILM_BROLL**（对应 beat 改 A_ROLL + MG 强调）——别给用户硬塞素材。
+
+```
+gtrk split（投影 → 你写拆分稿 → 落地）→ gtrk matrix（按⑤走或跳过）
+→ 全局抽帧检查构图 → gtrk mg（字卡，§六风格）→ gtrk audio lay（BGM，-20dB 口径）
+→ gtrk subtitle lay（检查点①拍板样式）→ 客户端打开出片
+```
+
+拆分稿写完自查两条：
+- **lane 里出现 AI_DRAMA 即改派**（机检 grep 即可）；
+- **字卡要产颗粒的，aux 必须用 `type:"overlay"` + handoff（含 duration_hint）**——`quote-card` 等
+  前七类 aux 只是语义标注、**不产派单**（真机踩过：五张字卡全写成 quote-card，dispatch.mg 为空）。
+
+## 六、MG 风格：内容驱动的临场泛化（成片型图纸通用条款）
+
+> 横切原则**正本已迁仓内《成片型图纸公约》§三**（`docs/成片型图纸公约.md`，主理人 2026-08-27 拍板，射程 = 所有含 MG 铺轨面的成片型图纸）；本节是口播链的执行文本，改公约须同批同步。旅拍图纸 §六「因势象形」是它的旅拍实例。
+
+- **有栏目风格 skill** → 走栏目（经栏目配置注入），本节不适用。
+- **没有栏目风格 skill** → **按当下这片的内容，现场泛化一套自洽风格直接用**：
+  1. 先从内容调性推**风格基调**：讲什么（严肃知识 / 情感陪伴 / 轻快种草）→ 定配色倾向（沉稳深色系 / 暖色低饱和 / 高亮对比）、字体气质（书卷 / 圆润 / 利落）、动效克制度（知识类稳、情绪类柔、种草类快）；
+  2. 基调定了**全片贯彻**：同片所有颗粒同一套色板与字体气质，MUST NOT 逐颗粒各自为政；
+  3. **两个 MUST NOT**：不把某套固定「通用默认风格」死板套在所有片子上（那是换了个形态的强行锚定）；不因为没有栏目 skill 就放弃风格一致性（那是没有风格）。
+- 一句话：**风格必须有，但不强行锚定**——锚在这一片的内容上，而非某个预设模板上。
+
+## 七、文风铁律（继承通用框架层，射程 = 一切 AI 产文本）
+
+口播链**没有写稿环节**（内容是用户自己讲的），三段式写稿规约不适用。但你产出的**每一段文本**——字卡文案、标题、HashTag、简报——全量适用通用框架层的文风铁律（正本见 `gtrk-travel-recap` §三通用框架层）：
+
+- **禁「否定—转折」对举句式家族**（「不是 X 而是 Y」「不仅…更是」「与其…不如」及全部变体；含标题与 HashTag）——能直接陈述的事实绝不用对举包装；
+- 禁模板连接词、拒翻译腔、禁幼稚拟声；
+- **裁剪版自校验**（产出前逐项过）：对举句式零命中 / 重复字错字扫描 / 字卡文案与用户原话事实一致（**别替用户改口径**——他说「大概三成」你别写「30.2%」）。
+
+## 八、双模式
+
+| 模式 | 停点 |
+|---|---|
+| **快速成片** | 开工五问 → 检查点①（§四，必停一次）→ 一杆到底（含 SOP 既有的「B-roll 铺完抽帧检查」，归入快速语义不再单独打扰用户） |
+| **逐步推进模式** | 每步停：对齐/拼段确认 → 粗剪回执 → 拆分稿 → B-roll 候选 → 字卡 → BGM/字幕逐项确认 |
+
+双轨低置信度兜底（§二）在两种模式下都会停——那是数据正确性问题，不归模式管。
+
+## 九、计费与排错
+
+- 跑前 CLI 自动查实时价并打印，**原样转述**；计费按上传物音频时长（≈毛片时长）。
+- **concat-first 的计费含义**：拼成一条跑一次 ≈ 各段分别跑的总和（时长相加），差别在**工程份数与人的操作量**，价钱差别不大——别拿「省钱」当拼段理由，拿「一份工程」当理由。
+- 排错以 `/gtrk-oralcut` 排错节为准，本图纸只补双轨/多段特有的：
+  - **成片人声与口型错位** → 偏移错了。回 §二用客户端对齐工程重测，换轨重跑；
+  - **拼接产物在某段交界处画面卡顿/音画渐飘** → 段参数其实不一致（四查漏了帧率的分数形式差异），改走逐段兜底；
+  - **粗剪把段间垫场剪得太狠/不够** → 那是节奏预设的事，回 §四换 preset。

package/skills/gtrk-tools/SKILL.md

@@ -48,7 +48,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `piano_audio_to_midi` | 「钢琴扒谱 / 钢琴音频转 MIDI / 提取 MIDI」 | 单条音频 | MIDI 文件 `.mid` | 运行前实时查询 | 已上线 |
 | `piano_audio_enhance` | 「钢琴录音修复 / 增强钢琴音质」 | 单条音频 | 高质量 WAV + 配套 MIDI（双产物） | 运行前实时查询 | 已上线 |
 | `image_to_square` | 「长图转方图 / 把长图变方的」 | 单张图片；可选 `--max-line`（≤20000） | 方形图片 | 运行前实时查询 | 已上线 |
-| `image_to_live` | 「图片变 LivePhoto / 静图微动 / 让照片动起来」 | 单张图片 | 约 4 秒短视频 `.mp4`（无声，产物是视频） | 运行前实时查询 | 已上线 |
+| `image_to_live` | 「图片变 LivePhoto / 静图微动 / 让照片动起来 / 要能长按播放的动态照片」 | 单张图片；可选 `--output-format`（见下文） | 约 4 秒短视频 `.mp4`（无声）；或安卓动态照片 `.jpg` + 附带同一条 `.mp4` | 运行前实时查询 | 已上线 |
 | `image_classic_template` | 「做封面 / 智能拼图 / 标题配图出封面图」 | **多张图片**（可传多个路径，文件顺序即拼装顺序）；**`--main-title <标题>` 必填**；可选 `--sub-title`、`--template-mode`、`--aspect`、`--quality`、`--output-pic-count`（服务端钳制 ≤20）、`--output-text-count`（≤20）、`--title-layout` | 封面/拼图成品（text/pic/render 三组、各组可空可多张） | 运行前实时查询 | 已上线 |
 | `image_vertical_stitch` | 「拼长图 / 多图竖拼 / 截图接成一张长图」 | **多张图片**（可传多个路径，顺序=自上而下拼接顺序） | 一张垂直拼接长图 | 运行前实时查询 | 已上线 |
 | `audio_tts_clone` | 「配音 / 文字转语音 / TTS / 用 xx 音色念这段 / 把这段稿子合成音频」 | **无文件**：`--text <短文本>` 或 `--text-file <txt>` 二选一（≤2000 字，服务端为真相）+ **`--speaker <音色代号>` 必填**（可用音色见官网文档，传错时报错会列出全部可用项）；可选 `--text-lang`/`--output-format wav\|mp3`/`--speed`/`--split-method`/`--batch-size`（speed/切分法缺省跟随该音色调好的参数）。**计费按文本字数折算分钟（约 200 字/分钟）** | 配音音频（wav/mp3） | 运行前实时查询 | 已上线 |
@@ -108,6 +108,17 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | 放大 9（值=画布锚点方位） | `zoom_in_center` `zoom_in_up` `zoom_in_down` `zoom_in_left` `zoom_in_right` `zoom_in_left_up` `zoom_in_right_up` `zoom_in_left_down` `zoom_in_right_down` | 以中心 / 边中点 / 角为锚点推近 |
 | 缩小 9（锚点同上） | `zoom_out_center` 及 `zoom_out_` 同九方位 | 以对应锚点拉远 |
 
+智能 LivePhoto 可选交付格式：`gtrk tool image_to_live ./photo.jpg --output-format motion_photo --json`。两个取值——
+
+| 取值 | 产物 | 什么时候用 |
+|---|---|---|
+| `mp4`（缺省，不传即此） | 一个约 4 秒的短视频（无声） | 要拿去剪辑、投放、当 B-roll 素材 |
+| `motion_photo` | **一个 `.jpg`**（静图末尾内嵌该视频，相册里长按即播）**外加**同一条 `.mp4` | 用户明说要「像手机拍的那种动态照片」「能长按播放的一张图」「发相册/发朋友的一个文件」 |
+
+两种格式**同价**（交付格式只决定产物怎么封装，不改生成参数、不改计费），所以选哪个纯看用户想要什么形态。`motion_photo` 时那条附带的 `.mp4` 是白给的，不必为了拿视频再跑一次。
+
+⚠️ **兼容边界，用户问起时如实说，别打包票**：支持该标准的安卓相册可识别并长按播放；**iOS 不识别**，在 iPhone 上就是一张普通静态图片（能正常打开、不报错）；少数安卓机型可能只显示静图。用户若明确要 iPhone 上能动的，这个格式满足不了，如实讲。
+
 这七个公共视频工具（去黑边、比例转换、防抖、蒸汽波、净化、超分、插帧）都只接本地文件，允许扩展名为 `.mp4/.avi/.mpg/.mov/.flv/.mxf/.mpeg/.ogg/.3gp/.wmv/.h264/.m4v/.ts`；不要把 `.mkv`、`.webm` 或 URL 交给它们。
 
 - 视频比例转换：`gtrk tool video_canvas_adapt ./clip.mp4 --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --clip-start 12 --clip-end 60 --without-audio --json`。`--clip-start/--clip-end` 传起止帧序号；省略选项就沿用服务端默认，需要保留音轨时不要传 `--without-audio`。

package/skills/gtrk-travel-recap/SKILL.md

@@ -9,6 +9,8 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 
 > **定位**：本 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、挑候选信号、产字卡颗粒、管检查点，都是你的活。
 >
+> **家族归位（2026-08-27 主理人拍板）**：本图纸是**解说链**（`gtrk-narration` 正本）的先行垂类实例——解说 = 把素材语料自带的叙事时序提炼看点后重述；时序铺排三档、引用段、出处对齐等链级条款以 `gtrk-narration` 为正本，本图纸的旅拍要素层（贵大奇多钩子/攻略 tips/升华笔法）为垂类专属。素材无自带时序的题材（科普/情感/带货）属配音链，走 `gtrk-voiceover`。
+>
 > **本 skill 已含跑通全链需要的全部编排信息**。打样验证：2026-08-19 黄石公园 20 分钟长视频二创，双轮真机全链通过。
 
 ## 一、输入契约与双场景识别
@@ -28,7 +30,14 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 - **原创**：用户自己拍的素材集（通常无解说语音）→ 素材理解（describe）是写稿主料。
 - 拿不准就 ffprobe 看时长与条数：单条 10 分钟以上大概率二创；几十条短素材大概率原创。仍拿不准，问用户一句。
 
-## 二、全链总览（快速模式）
+**稿源与声音基座两问**（⟲ 2026-08-27 解说链家族回炉，开工时与双场景识别一并问清、MUST NOT 代猜）：
+
+| 问 | 选项与走法 |
+|---|---|
+| 稿从哪来 | **AI 代写**（缺省，§三 规约写）/ **用户自备稿**——跳过写稿，稿直接进检查点①过目（文风铁律不强加于用户手稿，只提示明显硬伤） |
+| 声音怎么来 | **TTS 配音**（缺省，检查点①挑音色）/ **用户自己念**——拿念稿毛片先走 `gtrk oralcut` 粗剪（带稿最准；外录收音先 `gtrk audio align` 对轨），产出的粗剪工程即时间基座，§五 的「配音④→建工程⑤」两步跳过，从拆分⑥接入，后续铺排/字卡/BGM/字幕照旧 |
+
+## 二、全链总览（快速成片）
 
 ```
 ① 理解        transcript 原片（二创）/ matrix index + describe（原创）
@@ -45,7 +54,7 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 ⑫ 交付        客户端打开工程出片（gtrk render 仅主轨快照预览，见 §八）
 ```
 
-检查点①之后一路跑完不再打扰用户（快速模式默认）；用户要精修则按 §七 逐步停。
+检查点①之后一路跑完不再打扰用户——**垂类示例的承诺面就是快速成片一杆到底**（⟲ 2026-08-27 公约分层拍板）。交付后对个别环节不满意走 §七 增量重跑，对垂类玩法本身不满意走 §七 个性化出路。
 
 ## 三、三段式写稿规约
 
@@ -53,6 +62,12 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 
 **结构三段式**：第一部分「钩子」抓眼球保留存 → 第二部分「干货」给内容价值 → 第三部分「升华」给情绪价值。爆款四属性贯穿：快乐+知识+共鸣+节奏。
 
+**背景检索建议（⟲ 2026-08-28 主理人拍板）**：写稿信息源除了画面与音频（字幕不一定有），
+**建议**执行 agent 对素材主题的关键词做一轮背景/上下文检索（地名典故、店家来历、片名与
+公开报道等），检索所得须与素材内可见事实互证后才可入稿、并在拍板档案里标注来源。
+有检索能力就做、没有不强求（能力缺席按纯素材信息写，不算违约）；检索到的**外部数字与
+争议性说法宁缺勿滥**。
+
 **文风铁律**：
 - 禁模板连接词：让我们/首先/然后/最后/此外 等一律不用；
 - 拒翻译腔：全部短句中文语感，无欧化从句；
@@ -88,6 +103,27 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 - **升华笔法**（第三部分）：思考/感悟/启发/感动，正能量收束；第一人称历数、物象隐喻收尾都是成熟笔法；
 - 有文化衍生空间（历史典故/风俗人文）可适当发挥，但以原素材内容为锚。
 
+## 三′、L1 看点 rubric · 画面投影版（260828 新增，供 `--highlight-weight` 用）
+
+`highlight` 是**镜头看点分**——服务端 VLM 对着一帧画面打 0–100。旅拍这一档的准则
+（`highlight_rubric`）：
+
+```
+判这一帧对旅拍短视频有没有「看点」，0-100：
+- 奇观地貌：雅丹/冰川/星空/沙漠/峡谷等罕见地形
+- 极端天候光线：日出日落、逆光、雪雾、暴雨、极光
+- 人文场面密度：市集、节庆、宗教仪式、当地人劳作
+- 反差罕见：人与巨大景观的比例、无人区里的人造物、动物
+- 规模感：能看出「有多大/有多高/有多远」的构图
+低分：车内挡风玻璃前方公路、酒店房间、无主体的天空、拍糊的中间帧
+```
+
+> **分工注记（MUST 遵守）**：本 rubric 只判**镜头可见之物**。知识侧要素——地名典故、
+> 历史事件、人文背景——**不进画面 rubric**，它们归写稿与背景检索（§三 通用框架层已列）。
+>
+> 分工是：**画面 rubric 管「这一帧值不值得看」，写稿管「这件事值不值得讲」。**
+> 平淡的过渡帧判低分不等于不可用——降权不排除，候选稀疏时照样上（留空更难看）。
+
 ## 四、检查点①（双模式共有，必停）
 
 写完稿**必须停下**，把以下五项一次给用户拍板。**未经确认 MUST NOT 发起 TTS 计费动作**。
@@ -97,12 +133,14 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 3. **TTS 音色**：拉 catalog（`GET {apiBase}/task/tts/voices`，免鉴权）按内容调性挑 2-4 个候选，**每个附试听链接**（catalog 的 audition_url 字段，api.ai-mcn.tv:9000 静态直链）——用户在对话框里直接点开听。internal 标注的音色注明「仅内部成员」。也可按用户描述语义挑（「要个温柔女声」）；
 4. **BGM 处置（双来源）**：
    - 用户有本地音乐 → 询问是否 `gtrk tool audio_separation` 伴奏分离后取伴奏（缺省建议分离——TTS 配音不与歌曲人声打架）；
-   - 用户未提供 → **搜同和素材矩阵**：`gtrk matrix material "<按稿件情绪+地理文化写的检索词>" --scope audio --top-k 5 --diversity --json`（按成片时长挑可加 `--min-duration <秒>`）。身份路由（矩阵成员搜全库 / 非成员搜公开库）、版权范围、计费口径全由零件持有，你只管写好检索词并从结果里挑；出参 `results[]` 直接用，`upsell` 是独立顶层字段（非成员且没搜够时才有，原样转述给用户即可，**不要**把它当候选）。
+   - 用户未提供 → **搜同和素材矩阵**：`gtrk matrix material "<按稿件情绪+地理文化写的检索词>" --scope audio --top-k 5 --diversity --json`
+     （检索词口径见公约 §三′：**内容驱动、禁通用词、至少含一个只有这一片才成立的词**；候选
+     MUST 给用户挑不许默认 top1；跨片避让由 `audio lay` 记账 + 检索缺省 `--exclude-recent` 自动完成）（按成片时长挑可加 `--min-duration <秒>`）。身份路由（矩阵成员搜全库 / 非成员搜公开库）、版权范围、计费口径全由零件持有，你只管写好检索词并从结果里挑；出参 `results[]` 直接用，`upsell` 是独立顶层字段（非成员且没搜够时才有，原样转述给用户即可，**不要**把它当候选）。
      推荐 3-5 首、**每首附试听链接**（结果的 `download_url`）；`audio_type:"pure"` 纯音乐直接用，`"song"` 直接取 `accompaniment_url` 现成伴奏（零处理成本，两档都有）；注意曲长 vs 成片时长（`duration` 字段，audio lay 不循环，短曲只垫前段）；
    - **试听链接义务（MUST）**：音色与 BGM 的推荐没有试听链接=未完成推荐。
 5. **字幕样式**：7 种样式（default/outline/cinema_yellow/immersive_box/wide_spacing/deep_shadow/boxed）× 11 色（雅黑/淡绿/森林绿/湖蓝/道奇蓝/钢蓝/浅粉红/深橙/珊瑚橙/橙红/土豪金）挑选；**用户没选就用 default+雅黑**（不追问不阻塞）。拍板值在 ⑪ `gtrk subtitle lay` 落地，客户端里仍可整轨换样式（悔棋通道）。
 
-## 五、快速模式逐步编排（打样验证过的真实命令）
+## 五、快速成片编排（打样验证过的真实命令）
 
 ```bash
 # ① 理解（二创：转写原片，--json 顺产 transcript.json 备用）
@@ -134,7 +172,7 @@ gtrk split "<拆分稿>" --project "<工程目录>" --json
 gtrk matrix --project "<工程目录>" --local --dirs "<素材夹>" --lay 0 --json
 gtrk matrix describe --plan "<工程目录>/split/broll-plan.json" --yes --json
 #   ↑ describe 结果里的 usable_flags 由你裁定（text_overlay 命中=撞原片字幕区,考虑换段或保留交客户端悔棋）
-gtrk matrix lay --project "<工程目录>" --mark-weight 0.3 --gap-fill fast --json
+gtrk matrix lay --project "<工程目录>" --mark-weight 0.3 --highlight-weight 0.2 --gap-fill fast --json
 
 # ⑧⑨ 字卡（§六 规约产颗粒 → lint → 铺）
 gtrk mg lint "<工程目录>/mg/<composition_id>.html" --dispatch "<工程目录>/split/dispatch.json"
@@ -149,7 +187,12 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 
 **配方级参数口径**（打样标定）：
 - `--mark-weight 0.3`：美观度加权起步值（mark 缺失素材中性不受罚）；
-- `--gap-fill fast`（★ 主理人 2026-08-21 拍板：快速模式不留空）：主轨空洞放宽地板随便填候选→延长相邻颗粒→黑片兜底——客户端主轨磁吸开启时 gap 会被吸除、画面与配音错位，快速成片以画面连续性优先；CLI 缺省是 solid（黑片垫齐，精修可见），本配方须**显式传 fast**；
+- `--highlight-weight 0.2`（260828 新增）：看点加权，配 §三′ 的 rubric。与 mark 正交——
+  mark 判「好不好看」、highlight 判「有没有看点」。两权之和 0.5，语义仍占一半，
+  **MUST NOT 加到语义压不住**（那会变成「专挑好看的，不管说的是什么」）。
+  ⚠️ 两个权重与 blurry 降权**都依赖 `matrix describe --plan` 跑过**（编排 ⑦ 那一步）；
+  没跑就是全部候选中性、排序与不开权重逐字节一致——lay 会就此打告警，看到就说明漏了；
+- `--gap-fill fast`（★ 主理人 2026-08-21 拍板：快速成片不留空）：主轨空洞放宽地板随便填候选→延长相邻颗粒→黑片兜底——客户端主轨磁吸开启时 gap 会被吸除、画面与配音错位，快速成片以画面连续性优先；CLI 缺省是 solid（黑片垫齐，精修可见），本配方须**显式传 fast**；
 - 句界吸附（`--cut-align`）默认 0.7 即三七开拍板值，不用传——约七成字幕句起点恰逢镜头切点、三成有意错开；
 - **BGM 音量口径 = -20dB（线性 0.10，★ 主理人 2026-08-19 拍板定值）**：配音主导原则——BGM 是垫底不是主角，成品音乐响度天然高于 TTS 电平。⚠️ 契约 volume 字段**只写线性增益、MUST NOT 写 dB**（composition-contract-v1 §4 明文，dB 残档曾致客户端打不开工程）——-20dB 换算=10^(-20/20)=0.10 写入。**客户端音量面板显示的就是 dB 值（标准 20·log10 换算，两侧同一标尺）**：写 0.10 打开面板即显示 -20.0，主理人实测该值听感最佳且偏保守（宁小声不大声）。用户嫌低在客户端拉高（终调权在客户端）；
 - 时间窗（`--source-window`）：二创场景解说序≈素材序时按 beat 对应的原片区间约束检索（可选增强，全库检索在几百场景规模下命中率已够）；
@@ -157,7 +200,9 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 
 ## 六、MG 轻量字卡规约（旅拍向最小集，不建栏目 skill）
 
-快速模式**禁留白**（★ 打样修正）——字卡按下述规约**先斩后奏**直接产好叠上，用户不满意在客户端删，别等确认。
+> ⟲ 2026-08-27 注：本节「因势象形、不建栏目 skill」是**成片型图纸通用原则「MG 风格 = 内容驱动的临场泛化」的旅拍实例**——风格必须有，但不强行锚定（锚在这一片的内容上，而非预设模板）。原则正本在仓内《成片型图纸公约》§三（`docs/成片型图纸公约.md`），后续新图纸引用正本。
+
+快速成片**禁留白**（★ 打样修正）——字卡按下述规约**先斩后奏**直接产好叠上，用户不满意在客户端删，别等确认。
 
 - **内容**：地名字卡为主（地标名中文+英文/头衔副标），可加里程/价格数字卡；每片 2-4 颗、挂在地标出场句（拆分稿 aux_layers overlay）；
 - **形态**：左下安全区地名条——竖色条装饰+半透明深色衬底圆角条+主标题（60px 级粗体白字）+副标题（28px 级 75% 白）；透明叠加不挡画面主体；
@@ -166,9 +211,9 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 - **产前抽帧**（overlay 必做）：对挂点用本地 ffmpeg 抽 1 帧看底轨明暗与主体位置（临时文件落系统 temp 用完即删）；
 - 产物存 `<工程目录>/mg/<composition_id>.html`，逐颗 lint 过了再铺。
 
-## 七、精修模式（用户要逐步确认时切换）
+## 七、增量调整与个性化出路（垂类示例定位）
 
-每步完成即停、报告产物、等确认再推进。增量重跑通道：
+**本图纸是解说链的垂类示例，承诺面只有快速成片**（检查点①一次拍板后一杆到底；决策前置三条腿照公约执行，单模式不豁免）。交付后对**个别环节**不满意，用下表增量重跑悔棋——改哪步跑哪步，不整链重来：
 
 | 环节 | 暂停点产物 | 调整方式 | 增量重跑 |
 |---|---|---|---|
@@ -181,6 +226,8 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 
 改口播轨后 matrix/mg 消费侧自带现场重投影，无需回跑 split。
 
+**个性化出路**：对垂类玩法/审美**本身**不满意（想要另一套写稿腔调、字卡风格、节奏观），MUST NOT 在示例图纸上堆个性化补丁——引导用户用 `gtrk-style-maker` 建**他自己的**垂类 skill。示例图纸演示的是链路怎么跑，真正个性化的项目工程归用户自建的 skill 持有；示例对它差着火候是**定位使然**，这句丑话开工时就说。
+
 ## 八、交付与出片
 
 - **成片出口 = 客户端**（OpenCut Gitruck Edition「打开工程」选 `gtrk/project.gtrk`）：多轨合成（B-roll+字卡+黑底+双音轨混音）只有客户端出片链完整支持；
@@ -210,3 +257,21 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 - describe 的 `text_overlay` 信号命中多为撞上原片烧录字幕区（片头片尾高发）——裁定换段或保留交客户端；
 - `matrix lay` 拒铺（`tracks_edited`）不是失败：用户在客户端动过候选轨，plan 照产（`planReusable:true`），提示用户后按其意愿 `--replace-all` 或保留；
 - BGM 曲长 < 成片：audio lay 不循环，垫不满如实告知（客户端可复制 clip 补尾）。
+
+---
+
+## 改工程：走 `gtrk patch`，不要裸手改 JSON
+
+跑完之后要**微调某个片段**（挪位置 / 改时长 / 切开 / 改音量）时，一律用 `gtrk patch`：
+
+```bash
+gtrk patch move --project <dir> --clip <clip_id> --to 5.0
+gtrk patch trim --project <dir> --clip <clip_id> --out -1s
+```
+
+**MUST NOT 直接编辑 `.gtrk` 的 JSON。** 片段时码是两套并存的（`clip_st`+`clip_ed` 与
+`clip_st`+`duration`）：改一份不改另一份，客户端优先读 `clip_ed`、后端又不强校验它 ⇒
+**没人报错，成片却用了陈旧出点**。`gtrk patch` 替你做恒等式同步 + 帧对齐 + 写前全档校验。
+
+> 参数手册在 `AGENT.md` 的「元素级编辑：`gtrk patch`」一节与 README 命令参考。
+> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。