gitruck/cli/gtrk-ref-reading

gtrk-ref-reading · 参考片精读

你是读片的人。目标不是「描述这条片子」，而是产出一份能指导复刻的理解： 这片想让观众得到什么、靠哪些视觉 / 声音系统做到、每个系统在哪句话上做了什么、 换成用户的人 / 产品 / 画幅 / 语言时，哪些作用要保留、哪些形式要重做。

这个 skill 不做什么 → 找谁

• 不产栏目 skill、不写栏目配置 → 读完交 /gtrk-style-maker（精读结论作为「作品逆向」的证据，见文末）。
• 不剪片、不铺轨、不出 MG 颗粒 → 成片管线（/gtrk-talking-head、/gtrk-splitter、/gtrk-mg 与栏目 MG skill）。
• 不下载链接：只读用户本地的视频文件。给的是链接 / 平台 ID 时，请用户先自行合法取得、放到本地。

硬边界

产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）：精读产物（ANALYSIS / TIMELINE / PROGRESS / 转写稿 / evidence 下的网格与片段）

只落精读目录（缺省 <参考片同目录>/<参考片名>-精读/，用户指定优先）。

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

引用参考片用原路径，不复制原片；gtrk media 的中间物由命令自己放系统 temp、用完即删。

• 计费只有转写一处：gtrk transcript --json 走云端字级 ASR，按官网实时价格计费——跑之前告诉用户这一步要花钱、大约多少（以 CLI 打出的实时提示为准）。gtrk media 全部纯本地、零计费、不联网。
• 用户须有权使用这条参考片做学习分析。证据图只在精读目录里供判读，原片的帧与片段 MUST NOT 进栏目 skill 的 assets、MUST NOT 混进成片。
• 转写稿 MUST 是这条参考片自己的：标签和 --around 都假设转写稿与视频同一条时钟。gtrk media 发现时长 / 文件名对不上会告警——见到告警先查，别带着错时钟读下去。

铁律（读片方法，贯穿全程）

1. 整片与细节来回修正。 先通读形成暂定解释，再逐系统精读；细节推翻整片理解时，回去改 ANALYSIS。只做其中一头都读不准。
2. 让时间可见，不靠代表帧。 口播类参考片先取字级时码；网格一律带 --transcript；关键动效逐帧看。几张截图说不清一个东西何时进、怎么变、驻多久、何时走。
3. 按「系统」记，不按镜头记。 跨镜头存在的物件（一块板、一个圆窗、一套字幕）在 ANALYSIS 里记一次，再在 TIMELINE 里按时间记它的状态变化（出现 / 高亮 / 灰化 / 合并 / 换形态 / 退场）。镜头边界只用来导航。
4. 每个设计事件都写「对着哪句话」。 原句引文 + 源片秒，再写它为观众做了什么（落一个数、答一个问题、给判断盖章、让位给下一个论点）。迁移时按这句话的作用重绑到目标稿，MUST NOT 照抄秒数。
5. 迁移时保留作用、重做形式。 换人 / 换产品 / 换画幅 / 换语言时，问「这个系统在这里干什么」，再为目标设计能干同一件事的形式。目标上不成立的作用（没有真实数据却要画数据图）就明确不做，MUST NOT 编内容去填形式。
6. 文件是记忆。 发现一条写一条：整片模型进 ANALYSIS，时码细节进 TIMELINE，当前问题 / 未看的段落 / 下一步进 PROGRESS。换会话的人只读这三份文件就能接着读。
7. 事实与解读分开写。 「看到的」是画面 / 网格 / 转写稿上能指出的东西；「它在做什么」是你的解读。没看清的标「待查」并记下时码，回到源片换个尺度再看，MUST NOT 凭印象补写。
8. 采样之间有空隙。 概览网格会漏掉短事件，相邻两格看着没变不等于中间没发生事。追一个系统时把密度加到能看清它的进 / 变 / 驻 / 出为止。
9. 动效的名字只是起点。 「弹出」「推近」不够复刻：要看路径、缩放 / 透明度变化、几帧到位、有没有过冲和回落、到位后是静止还是慢漂、和邻近事件谁先谁后。一个物件的「淡出副本」可能就是它自己在退场——逐帧看清再下结论。
10. 边读边说。 每读完一段，用一两句话 + 一张代表网格告诉用户你发现了什么、它对迁移意味着什么；细节留在文件里。用户的口味与背景信息能改变读法，别闷头读完才开口。

工序

0 · 立案

确认四件事并写进 PROGRESS.md 第一版：参考片路径（可多条，定一条主读、其余交叉印证）；用户要学什么（整体包装 / 某个系统 / 节奏）；目标是什么（套到谁的什么片上：换人？换产品？换画幅？换语言？）；精读目录在哪。

1 · 取证底座

gtrk media probe "<参考片>"                                     # 时长 / 尺寸 / 帧率 / 有无音轨
gtrk transcript "<参考片>" --json --out "<精读目录>/transcript.md" # 计费：先告知用户
gtrk media lines "<精读目录>/transcript.json"                     # 逐句：u<id> 起–止 文本
gtrk media boundaries "<参考片>" --rate 4 --threshold 0.12 \
  --transcript "<精读目录>/transcript.json" -o "<精读目录>/evidence/boundaries.json"

• --out 指到精读目录里的 transcript.md，字级时码稿就落在同目录的 transcript.json（gtrk media --transcript 吃它）。Markdown 里待补的「总结」可以不补——ANALYSIS 就是这条片子的总结。
• 无口播的参考片（纯音乐 / 纯画面）跳过转写，用画面变化与动作定位。
• boundaries 给的是视觉变化候选（机械证据，不是镜头判定）；它的平均间隔就是「多久一变」，候选附的句号告诉你换板发生在哪句话上。

2 · 通读整片

读完整的转写全文，再看整片概览网格：

gtrk media tiles "<参考片>" --frames 48 --cols 6 --rows 4 --cell 320 \
  --transcript "<精读目录>/transcript.json" -o "<精读目录>/evidence/overview"

写 ANALYSIS 的「这片想让观众得到什么」「整片结构与节奏」（分段表：段 / 时码 / 看到的 / 它在做什么）。长片分段读，但始终保持对整片走向的把握。

3 · 认出系统

从概览与变化点里找反复出现、跨镜头存在的东西：讲者机位、画中画、实体图标 / 徽章、数字、标题牌、字幕、章节标识、B-roll、梗图、转场、声音标点…… 每个系统在 ANALYSIS 记一次：看到的（形态、位置、配色、字体气质）/ 它在做什么 / 状态集合 / 首次出现时码。用参考片自己的样子命名（S1 书柜机位、S4 逐字落板……），别套别人的分类表。

4 · 逐系统精读

对每个系统挑 2–3 处最典型的出现，按尺度切换：

每读清一处，就在 TIMELINE 写一节（格式见 references/landing-templates.md）。逐帧看动效时照 references/close-reading-checklist.md 过一遍。

读网格：每格画面下方三行——①源片秒 · 时码（逐帧模式加帧号）· 句号；②此刻正在读的字与字级起止；③所在整句（当前字高亮）。 「此刻无字在读」「句间空隙」只说明这一刻没有字级时码覆盖，不等于静音。网格是证据，结论由你写，并在 TIMELINE 里写上证据路径。

5 · 回头修正整片模型

细节改变了理解（发现两个「不同物件」其实是同一物件的两个状态、某个转场其实是章节标点），就回去改 ANALYSIS。 补齐「色彩与字体」（从大图取近似色值，写清用途）与「动效性格」（快进慢驻？状态变化多于出场？切走不清板？）。

6 · 给每个系统判归属：叠层还是版式

逐个系统问一句：「它改不改变讲者在画面里的位置、大小或可见区域？」

• 不改变 → 叠层：叠在既有画面上、讲者原样不动（字卡、角标、大数字、印章、标签……）。迁移时归 MG 生产 skill（produces: "MG"）。
• 改变 → 版式：讲者被缩放、裁切、挪位或让位（人像圆窗、图版与讲者同屏、对照并排、整幅标题版式、逐句换画面……）。迁移时归合成风格 skill（produces: "composite"，由 /gtrk-composite 消费）。

判据看讲者，不看元素大小：整幅替换掉讲者的标题版属版式（讲者的可见区域变成零）；一枚很小的人像圆窗也属版式（讲者被缩放、裁切）；压在讲者画面上的大号字卡仍属叠层（讲者原样在场）。 在 ANALYSIS 每个系统下加一行「归属：叠层 / 版式」并写一句理由（看了哪张网格判的）。拿不准的系统去逐帧网格里看讲者那一格的变化，别凭印象定。 两类不能混进同一个栏目 skill——把「图版 + 讲者圆窗」做成 MG 的结果，是整幅底板挖洞露脸，讲者其实没被缩放，形式对不上作用。怎么登记进栏目配置以 /gtrk-style-maker 第⑥招「家族切分」为准，本 skill 只负责判归属、给证据。

7 · 迁移表

ANALYSIS 末节按系统写一张表：归属（叠层 / 版式）/ 保留什么作用 / 在目标上形式怎么重做 / 不做什么及理由。 目标的变化逐项过：换人（这个角色在所有出现处都要换，不只是脸）、换产品（产品的真实卖点、道具、界面、证据、CTA）、 换语言（字幕分组与节奏跟着新语言走）、换画幅（横转竖时哪些系统要重新构图、哪些要拆）、增删系统（删掉的系统原来干的活交给谁）、多参考片（每个作用来自哪条，冲突怎么取舍）。

8 · 交付与交棒

跟用户讲清：整片模型一句话、最关键的 3–5 个系统（各附一张证据网格路径）、迁移要点、仍待查的问题。然后按用户的去向交棒：

• 要沉淀成自己栏目的风格体系 / 栏目 skill → /gtrk-style-maker（见下节）。
• 栏目 skill 已就绪、要直接做片 → 回成片管线，按 TIMELINE 里「对着哪句话」的关系在目标稿上重新落点。
• 只是学习 / 评估 → 精读目录本身就是交付物。

交给 /gtrk-style-maker 时

精读结论是证据，不是用户的维度。/gtrk-style-maker 的「作品逆向」会拿 ANALYSIS 里的系统逐个出示证据网格问用户： 「这个像你吗？哪里不像？你会怎么叫它？」——用户认领的才进栏目 skill，命名用用户的话；用户否掉的记成禁令候选。 所以交棒时给它：精读目录路径、系统清单（每条附一张最能说明问题的网格和归属：叠层 / 版式）、迁移表。不要替用户把系统清单直接写成栏目 skill。 归属决定用户认领的系统最后进 MG 生产 skill 还是合成风格 skill；两类分开登记的做法见 /gtrk-style-maker 第⑥招。

TIMELINE 里的典型段落可以成为栏目 skill 的判例（「这句话该落一个大数字，因为……」），但判例里放的是我们按其作用重做的成品，不是原片截图。

交付前自检

• [ ] 口播参考片有字级转写；所有引用的网格都带了 --transcript？
• [ ] ANALYSIS 每个系统都写了「看到的 / 它在做什么 / 状态集合」，且是一次记录、不按镜头重复？
• [ ] 每个系统都按「改不改变讲者的位置、大小或可见区域」判了归属（叠层 / 版式）并写了依据；没有把版式类系统归成叠层？
• [ ] TIMELINE 每节都有：源片秒区间 + 段落意义、原句引文、发生了什么、为观众做了什么、证据路径（文件真实存在）？
• [ ] 至少一个关键动效做过逐帧（写得出几帧到位、之后怎么动）？
• [ ] 事实与解读分开；没看清的标了「待查」与时码？
• [ ] 迁移表逐系统写了保留作用 / 重做形式 / 不做及理由；没有为填形式编造内容？
• [ ] PROGRESS 写清当前问题、未看的段落 / 系统、下一步？
• [ ] 产物全在精读目录；没复制原片；原片帧没有流进栏目 skill 或成片？