@gitruck/cli 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitruck/cli",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
   "license": "MIT",
   "author": "Gitruck (同合云)",

package/skills/gtrk-matrix/SKILL.md

@@ -50,6 +50,8 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
   ```
 - **变奏点**：`--top-k` 控理解成本（1 积分/张，只理解你会认真考虑的那几条）；云端 plan 同样可 describe（帧从签名 url 现抽）；理解产物有本地缓存，反复迭代不重复扣费。
 - **裁定要点**：`usable_flags` 是信号不是判决——结合 `desc` 复核（水印在角落的航拍也许仍可用）；剔除动作=从 plan 删掉那条 result，CLI 不会替你剔。
+  另读 describe 输出的**剔除风险**清单：候选数 ≤1 的 beat 一删就掏空（音频驱动 ⇒ 整段黑屏或跨 beat 借片；口播 ⇒ 露 A-roll）。先补素材再剔，MUST NOT 见 flag 就删。
+  ——260902 真机 P3 八个 beat 里七个只有 1 条候选；该清单只是判据，剔不剔仍归你（铁律①「零件不裁定」，见 §四层架构与三条铁律）。
 
 ### 配方 C · 时间窗匹配（电影解说式）
 
@@ -181,6 +183,31 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 
 出参逐条：`{id, note, duration, audio_type, tags, score, download_url, cover_url}`；`audio_type`（`pure` 纯音乐 / `song` 歌曲）与 `accompaniment_url`（song 类现成伴奏直链，零处理成本）**两档通用**；**只有 `is_copyright`（及 clip 的 `material_class`）是成员口独有**——公开口**没有**这个字段，零件如实缺省不伪造，你也别把「没有该字段」读成「不可商用」。`download_url` 带 24h 签名（过期重跑即重签）。
 
+> ⚠️ **`is_copyright` = 能不能商用，不是「有没有被版权保护」**
+>
+> ```
+> is_copyright: true   → 可商用（自有 ∪ 已授权）      ← 挑 BGM 就挑这种
+> is_copyright: false  → 不可商用                      ← 别碰
+> ```
+>
+> **`false` MUST NOT 读作「无版权、可以随便用」——它恰恰相反。** 决定性反证：概念素材（他人版权物）
+> 入库时固定写 `is_copyright=0`；字段若真是「是否受版权保护」，那批必须是 1。
+>
+> **真机事故（2026-09-02，这条警示的由来）**：AI 执行方连续两轮**特意去挑 `is_copyright:false`**，
+> 以为那是「没版权、随便用」的安全选项，结果把**不可商用**素材铺进了 5 个工程；唯一安全的
+> `true` 反倒被主动避开。
+>
+> **所以选 BGM（以及任何要进成片的整条素材）MUST 按可商用口径判**：
+>
+> - **MUST 只从 `is_copyright: true` 的候选里挑**；`false` 的一律不推荐给用户、不落轨——
+>   除非用户在对话里明确说了这条片子只自用/不发布，且你把「这条不可商用」原话告诉他；
+> - 嫌手动挑麻烦就让服务端筛：成员口加 **`--commercial-only`**（传 `copyright_scope=commercial`），
+>   出参逐条 `is_copyright:true`；
+> - **公开口（external 档）没有这个字段**——那不是「不可商用」，而是「服务端已经在源头只放可商用素材」，
+>   缺席即无需判；
+> - `--json` 出参里 CLI 会**逐条派生一个人话标签 `copyright_label`**（`"可商用"` / `"不可商用"`），
+>   与 `is_copyright` 恒同向、缺席同缺席。**判读以这两个键中的任一为准，MUST NOT 靠字段名去猜。**
+
 **upsell 口径**：`--json` 出参可能带一个**独立顶层字段** `upsell`（人读模式则是末尾一行提示）——**当且仅当**公开口档位且结果不足（0 条或少于请求量一半）时才有，内容是「加入同和新媒体矩阵可免费搜全库」+ 链接。它**不在 `results` 里、不改写任何候选**：原样转述给用户，别把它当成一条素材。成员档恒无此字段。
 
 **本地素材零件**（`matrix index` / `--local`）：
@@ -206,7 +233,12 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 | 直接理解素材文件 | `--materials <a,b,...>` | 逗号分隔文件 · — | 视频按**场景中点**逐帧理解；图片文件直传；结果在 stdout JSON `items` |
 | 跳过确认 | `--yes` | 开关 · 关 | 将实际调用 >20 张才触发确认（预估积分明示）；internal 豁免免确认仅提示 |
 
-理解产物形态：`{desc(≤200字中文描述), tags[], mark(0-100 质量分), usable_flags{watermark, text_overlay, black_border, blurry}}`。**缓存即钱**：产物按（素材, 帧时刻）落本地索引库，同帧重复 describe 零调用零计费；素材内容变了（size:mtime 指纹变）该素材缓存自动作废。
+理解产物形态：`{desc(≤200字中文描述), tags[], mark(0-100 质量分), usable_flags{watermark, text_overlay, black_border, blurry}, at_sec(射程锚点)}`。**缓存即钱**：产物按（素材, 帧时刻）落本地索引库，同帧重复 describe 零调用零计费；素材内容变了（size:mtime 指纹变）该素材缓存自动作废。
+
+**⚠️ 一条 describe 只代表一段，不代表整条候选**（`--plan` 形态）：每个候选**只抽一帧**（`segments[0]` 的 `best`），这条判决的有效射程就是**那一帧所属的那一个 segment**。`at_sec` 就是那一帧的时刻（**素材时基**秒，与 `segments[].best` 同轴——注意与 `beats[].anchors[].at_sec` 的**工程轴**秒同名不同轴，别换算）。缺这个字段的旧 plan 按 `segments[0]` 推定，**不外推到全部段**。
+
+- 真机 260902 量级：32 个被理解候选共带 **843 段，只有 32 段（3.8%）被看过**；95 个落轨坑位里只有 12 个（12.6%）含那一帧。命令跑完会打一行「理解覆盖率：N 帧 / M 段 = X%」（`--json` 读 `describe_coverage`），**M 是段数不是候选数**——别把「注入 N 条 result.describe」读成「这 N 条候选都看过了」。
+- 转述给用户时 MUST 按段说：「这条候选的 X–Y 秒那一段有字幕」，MUST NOT 说成「这条素材有字幕」。要判更多段就得多抽帧 = 多花钱（1 积分/张），是否加抽由用户拍板，CLI 不替他加。
 
 **plan 消费零件**（`gtrk matrix lay`）：
 
@@ -228,7 +260,7 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 - `result.pinned: true`：**钉选**——是**落位保证**，不只是排序特权。它豁免四条自动护栏：①派单负词 `excluded_hint`、②`--score-floor` 分数地板、③不二用抢占（钉选段不会因为**别的候选**占了同一把消费键而落不上；但同一个「候选+段」对仍只落一次）、④紧邻跳剪避让（钉选相邻照落，也不计进 `dedup.adjacentWaived`）。
   **不豁免的三条**：`--no-image-broll`（零图片上云是硬承诺，图片候选连 pinned 也进不来）、同 beat 跨轨素材归属互斥（那条给的是备选面——钉选占满每条轨，`--lay N` 就退化成 N 条一样的轨）、主轨 gap 快速填充的兜底档。
   钉多了仍可能打架（供长不足/位置冲突），让位名单在结果 JSON `lay.pinned.yielded` 与告警里**逐段**明示。
-- beat 的 `anchors`：**关键词锚**（拆分稿圈定、plan 检索时内插 `at_sec`）——`[{keyword, utterance, at_sec, query}]`，lay 把锚 query 最高分命中钉在 `at_sec−0.5s`（时长 min(命中段, per_shot×2)），其余槽位在锚点分割的区间内序贯填充。可编辑：**挪 `at_sec`**（微调卡点时刻）、**换 `query`**（换锚画面）、**删锚**（整条删除）；`at_sec:null`=内插失败态，lay 按降级普通槽处置。锚 query 池内有 pinned 候选时**用户钉选优先占锚槽**。
+- beat 的 `anchors`：**关键词锚**（拆分稿圈定、plan 检索时内插 `at_sec`）——`[{keyword, utterance, at_sec, query}]`，lay 把锚 query **原始 sim 最高的合格命中**（原始检索相似度，**不是** mark/highlight 融合分——`--mark-weight`/`--highlight-weight` 在锚槽退为同 sim 时的 tie-break）钉在 `at_sec−0.5s`（时长 min(命中段, per_shot×2)），其余槽位在锚点分割的区间内序贯填充。**锚预留优先于普通序贯槽消费**：铺轨前先为每锚锁住其 sim 第一名（每锚至多 1 对，落位或降级后立即释放），前序 beat 的泛化普通槽拿不到它；取不到第一名时锚 outcome 会**如实报名次与去向**（落的是第几名、第一名被哪个 beat/query 取走），MUST NOT 静默当成钉准了。可编辑：**挪 `at_sec`**（微调卡点时刻）、**换 `query`**（换锚画面）、**删锚**（整条删除）；`at_sec:null`=内插失败态，lay 按降级普通槽处置。锚 query 池内有 pinned 候选时**用户钉选优先占锚槽**。
 - beat 的 `per_shot_sec`/`requested_shots`（节奏锚，影响槽长档位）。
 
 **不可编辑面**（动了会被 `matrix lay` 校验拒绝并指名字段）：
@@ -264,7 +296,7 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 
 **前置**：需要跑过 `gtrk split` 的产物目录（`split/dispatch.json`）。`film_broll` 空 = 本片没有影视/本地素材腿 → 跳过本步，看 AI 情景片段腿（`dispatch.ai_drama` 非空则交棒 `/gtrk-ai-drama`），两腿都空才直接进 ⑤。`gtrk` 找不到 → `npm i -g @gitruck/cli@latest`。用户先在 opencut 手调过切点也不怕——命令每次都现场重投影 beat 窗口，微调口播轨不用重跑 `gtrk split`，只有拆分稿本身变了才要。
 
-**业务分离**：本框架 skill 不硬编任何栏目审美。B-roll 的 `queries` 在 ② 拆分时已写进派单（不触发生产 skill）；栏目只供检索偏好（`--column`，internal 口生效）。档位由命令自己探（结果 JSON `memberType`），external 口固定 real_shot+有版权素材。
+**业务分离**：本框架 skill 不硬编任何栏目审美。B-roll 的 `queries` 在 ② 拆分时已写进派单（不触发生产 skill）；栏目只供检索偏好（`--column`，internal 口生效）。档位由命令自己探（结果 JSON `memberType`），external 口固定 real_shot + 可商用素材。
 
 ## 本地素材检索模式要点（`--local` / `matrix index`）
 
@@ -314,7 +346,7 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 
 - `--json`：人读日志走 stderr，成功时 stdout 只有一行结果 JSON：
   `{ ok, mode:"plan", memberType, columnId?, planPath, lay:{ refused, laidTracks:[…], laidClips, removedTracks:[…], keptEditedTracks:[…], blackTrack, blackBedHoleSec, blackBedHoles:[…], dedup:{scope,emptySlots,adjacentWaived}, signal_coverage?:{mark?:{hit,neutral,coverage},highlight?:{hit,neutral,coverage}}, pinned?:{requested,placed,yielded}, anchors?:{planned,pinned,degraded}, anchor_details?:[{beat,keyword,at_sec,track_st,clip_id,status,reason?}], downloads:{preview,raw,reused,failed} }, integrity:{…}, reprojection:{…}, counts:{ beats, queries, results, errors } }`
-  （`--lay 0` 时无 `lay`；`search` 模式 `{ ok, mode:"search", results:[…], counts, outPath? }`；`matrix lay` 模式 `mode:"lay"` 且 `counts.queries` 恒 0——零检索；`matrix describe` 模式 `{ ok, mode:"describe", described, cached, called, failed, credits_estimated, exempt?, planPath?/items? }`）
+  （`--lay 0` 时无 `lay`；`search` 模式 `{ ok, mode:"search", results:[…], counts, outPath? }`；`matrix lay` 模式 `mode:"lay"` 且 `counts.queries` 恒 0——零检索；`matrix describe` 模式 `{ ok, mode:"describe", described, cached, called, failed, credits_estimated, exempt?, planPath?/injected?, describe_coverage?:{frames,segments,ratio,image_candidates}, items? }`）
 - **拒铺结局**（候选轨已被用户编辑）：stdout 出 `{ ok:false, refused:[…], reason:"tracks_edited", planReusable:true, … }` 且非 0 退出——不是命令失败，plan 已产出，处置见下表。
 - **命令失败**（缺派单、鉴权失败、全部 query 失败、参数越界、坏 plan 被 lay 拒）→ 非 0 退出、报错在 stderr、stdout 无 JSON。先看退出码，把 stderr 报错如实回给用户。
 - 检索分钟级，耐心等返回。
@@ -324,7 +356,7 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 读 stdout 那行 JSON（字段按需读、读前判空），别只回「铺好了」：
 
 - `counts`：几个 beat、几条检索（几条失败）、几条候选——一句话概括盘子大小。
-- `memberType`：internal=矩阵成员口（栏目偏好/concept 生效）；external=通用口（固定 real_shot 有版权）。
+- `memberType`：internal=矩阵成员口（栏目偏好/concept 生效）；external=通用口（固定 real_shot + 可商用）。
 - `lay.laidTracks` / `lay.laidClips`：铺了几条候选轨、几个颗粒（不含黑底轨）。
 - `lay.blackTrack`：黑底垫轨轨号（未铺时 null）。
 - `lay.blackBedHoleSec` / `lay.blackBedHoles`：**黑底空洞**（纯黑压口播时段），恒全量不按阈值过滤——非零就主动报（哪个 beat、几秒、在哪），这是粗剪期既定取舍不是故障。
@@ -372,7 +404,7 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 | 预览看不了 / 想「重签」 | 别为此重跑铺轨：`preview_url`/`cover_url` 不带签名不过期；带签名 24h 过期的是原片 `url`——工程内走客户端「确认原片」重签；**脱离工程要原片落本地走 `gtrk matrix fetch <clip_id...>`（免费重签+下载，见「精剪补素材」节）** |
 | raw 原片回落 / 体积大 | 提示用户；服务端 backfill 后重跑可换回轻量代理 |
 | `reprojection.degraded:true` | 不是故障：命令算不出当刻窗口退回快照。`transcript_missing` → 补回 transcript.json 或新版 oralcut 重出；`no_project`/`gtrk_unreadable` → 工程放回位或 `--project` 指对 |
-| 期望 concept 却报 external 限制 | 如实说明当前身份只出 real_shot 有版权素材，concept 需矩阵成员口 |
+| 期望 concept 却报 external 限制 | 如实说明当前身份只出 real_shot 可商用素材，concept 需矩阵成员口 |
 | describe 报 `describe_endpoint_unreachable` | 服务端未上线/网络/配置指错：查 `describeUrl` / `GITRUCK_DESCRIBE_URL`；缓存与 plan 都在，修好重跑。describe 走异步任务（提交后轮询取结果）：任务提交成功后即便中途断网结果也不丢（服务端照跑），可重新轮询/稍后重跑取回；上游失败服务端自动退款，只需重跑 |
 
 > **搜词规范**（ad-hoc `search` 与理解派单 queries 通用）：英文长句场景描述（5–12 词，谁+在哪+做什么），一条只装一个场景意象，避多义/字面强的动词（"pointing"/"hunting" 会召回特写/猎人，改用 "giving suggestions in a meeting" 这类场景语义）。

package/skills/gtrk-narration/SKILL.md

@@ -22,7 +22,7 @@ description: 通用解说视频创作图纸（解说链正本）——把「一
 
 **素材来源边界**：解说的主体画面**只用本地素材**——素材就是被讲的对象本身，平台素材库在主体画面上是范畴错误；平台库最多补空镜/概念镜头作辅料，**缺省不掺、问了才加**。
 
-## 二、输入契约与开工六问
+## 二、输入契约与开工七问
 
 **输入**：本地素材语料（素材夹，或单条长片——影视/游戏实况先建索引拆条）±稿件 ± 用户自己念的口播毛片。**MUST NOT 执行任何网络下载**（版权责任归用户）。
 
@@ -34,8 +34,27 @@ description: 通用解说视频创作图纸（解说链正本）——把「一
 | ④ | 声音基座 | **问用户**：TTS 配音（挑音色附试听）/ 你自己念（给口播毛片） | §五 基座路由：TTS 走配音工程；口播毛片先走 `gtrk oralcut` 粗剪（外录先 `gtrk audio align` 对轨） |
 | ⑤ | 要不要引用段 | **问用户**，按题材给建议：影视/游戏强建议开，旅拍/探店可选 | §四；答不要 = 全程零引用动作 |
 | ⑥ | 画幅 | 按投放平台问；素材几何 ffprobe 取证 | 画布；横屏素材硬做竖屏有黑边/裁切，丑话先说 |
+| ⑦ | **源片语种 / 方言** | **问用户**：听一段 / 看片内有无内嵌字幕 / 看素材出处 | `gtrk transcript --lang`（`zh-CN` 普通话 / **`zh-HK` 粤语** / `en-US` / `ja-JP`…）；素材通篇无对白答「无对白 / 不转写」即闭合，MUST NOT 因缺这个答案阻塞开工 |
 
-> ②③④⑤ MUST 问用户、MUST NOT 代猜；一张表一次问完，不碎问。
+> ②③④⑤⑦ MUST 问用户、MUST NOT 代猜；一张表一次问完，不碎问。
+>
+> ⟲ **2026-09-02 六问补为七问（新增 ⑦ 语种）**：260902 真机一条**粤语对白**的片子按缺省 `zh-CN`
+> 静默转写跑完，整条链上无一处问过语种。⑦ MUST 早于 ① 的转写发起：转写是计费动作且在检查点①**之前**，
+> **非中文素材**（`en-US` / `ja-JP`…）语种传错，用户在检查点①拿到的稿子就是坏的、重来要再付一次 ASR
+> （真机 `--lang en-US` 出英文稿即实证）；且豆包 14 项白名单外的语种码在 `word_level=true` 下会裸
+> `KeyError` 炸任务。**MUST NOT 以缺省 `zh-CN` 静默开跑**，检查点①对语种只做过目复核。
+>
+> ⟲ **2026-09-02 同日订正（这一问的原粤语论证段已被求证推翻，问本身照旧成立）**：原文写
+> 「`zh-CN` 与 `zh-HK` 在后端是两个不同的识别语种（Whisper `zh` vs `yue`）」——**该因果论断错**。
+> `gtrk transcript` 写死 `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 今天走不到。
+> ⇒ 粤语 **SHOULD** 如实填 `zh-HK`（元数据诚实 + 备将来链路切换），但 **MUST NOT 以「粤语语种传错」
+> 为由重跑转写**：`la` 进 ASR 缓存键（`asr_result_cache.py:71-75`），换码必然 cache miss，
+> 白扣一次时长换回同一份结果。
 
 ## 三、时序铺排三档（本图纸的技术正本）
 
@@ -177,6 +196,7 @@ QC 反算重铺）；② 段带 `cuts`，端点残片收缩生效；③ 段带 `
 - **引用点在写稿时定**：稿件里显式留引用窗口（出处 = 甲档对照表里的区间），MUST NOT 铺轨时临时起意。
 - **切取用流拷贝**（`ffmpeg -c copy`，零重编码）；想让 AI 帮你海选可引用的高光，可先跑一遍 `gtrk long2short` 拿选段清单当候选（可选辅助，明示计费）。
 - **装配**：逐段 TTS + 引用段原声按稿序拼成总音频 → 合成 transcript（各段句级时码换算到拼接轴）→ `gtrk project init --audio <总音频> --transcript <合成转写>` 建工程（自备配音兜底路）；引用段画面 = 该源区间直排上轨。无引用段时装配退化为单条 TTS + `--tts-task` 主路（与旅拍同款）。
+  **产物文件名别硬拼（fix-tool-outdir-collision）**：多段 TTS 落**同一个 `--out`** 时，第二段起的产物会带 taskId 后 6 位后缀（`tts-narrator-a1b2c3.wav`），基名只有第一份是干净的。拼接清单 MUST 按每次回执的 `files` 取路径，MUST NOT 按 `tts-<speaker>.wav` 猜——猜出来的名字会一路指向第一段，拼出来的总音频会把某一段重复多遍而不报错。
   **主轨无缝铁则（260828 主理人挑刺定案）**：合成 transcript 里引用段 utterance 的 st/ed **MUST 写物理拼接位**（拼接轴上的真实起止），MUST NOT 加 ±0.1s 字幕 pad——dispatch 的 beat 轨窗派生自转写时刻，pad 会在主轨上留 0.1s 缝（三片实测各 4 处）。已有 pad 的存量工程修法：改转写引用句时刻→重导视图→重落拆分（hash 只随文本不失效）→重铺（plan 引用窗随之外扩，Δ=0 不破）→字幕重出。
 - **克制丑话**：引用段是佐料——时长占比失衡会让片子变成搬运，平台判定风险归用户（§八 一并告知）。
 
@@ -186,10 +206,18 @@ QC 反算重铺）；② 段带 `cuts`，端点残片收缩生效；③ 段带 `
 # ① 索引前置（第一步就起，不是可选项——它是质量信号的载体，见 §三 代价表）
 #    4K 长片索引慢，未提速期**与写稿/TTS/检查点①并行跑**，别串行干等
 gtrk matrix index --dirs "<这一部片的绝对路径>" &     # 后台起，写稿同时跑（索引侧同口径：也钉单片）
-gtrk transcript "<长片>" --json            # 影视/游戏类：台词与时码双锚（可选）
+gtrk transcript "<长片>" --lang <开工⑦所答语种> --json   # 影视/游戏类：台词与时码双锚（可选）
+#   ↑ 语种取开工⑦所答，MUST NOT 拿缺省顶上去 —— 但「传错就白花钱」只在**非中文**这一档成立；
+#     粤语 SHOULD 如实填 zh-HK（元数据诚实 + 备链路切换），当前链路下对粤语无差别：
+#     CLI 写死 word_level: true ⇒ 钉在豆包，豆包字典里 zh-CN 与 zh-HK 都映射空串 ⇒ 请求逐字段相同。
+#     MUST NOT 以「粤语传错」为由重跑（la 进 ASR 缓存键，换码必 cache miss、白扣一次时长）。详见 §二 ⑦ 注
 
 # ②③ 写稿（甲档出处共生 / 乙路对照表对齐）→ 检查点①拍板（§六）
-gtrk matrix material "<情绪 题材 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
+gtrk matrix material "<情绪 题材 检索词>" --scope audio --top-k 5 --commercial-only --json   # BGM 候选附试听
+#   ⚠️ 版权判断不在零件手里，在你手里：零件缺省 copyright_scope=all（**不筛**）。
+#   is_copyright 的权威语义是 1/true=可商用、0/false=**不可商用**——反直觉，MUST NOT 把 false
+#   读成「无版权、可随便用」。带 --commercial-only 就把不可商用的挡在候选之外；不带就 MUST
+#   逐条按 copyright_label（派生位，中文标签）自己判，别默认候选都能用。
 
 # ④ 声音基座（按开工④路由）
 gtrk tool audio_tts_clone --text-file <稿段.txt> --speaker <voice_id> --json   # TTS 路
@@ -271,7 +299,7 @@ gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 
 | 模式 | 停点 |
 |---|---|
-| **快速成片**（默认） | 开工六问 → 检查点①（必停一次）→ 一杆到底 |
+| **快速成片**（默认） | 开工七问 → 检查点①（必停一次）→ 一杆到底 |
 | **逐步推进** | 每步停等确认（索引结论 / 稿件 / 对照表 / 铺排结果 / 字卡 / BGM / 字幕逐项） |
 
 差别只在停几次；三条腿自检见《成片型图纸公约》§四。

package/skills/gtrk-splitter/SKILL.md

@@ -81,6 +81,7 @@ gtrk split --project "<oralcut产物目录>" --json
 
 关键：
 - `lane` 四选一 `A_ROLL | MG | AI_DRAMA | FILM_BROLL`；`base_track` 三选一 `真人出镜 | 口播继续 | 旁白主导`。
+- `irreplaceability` 四选一 `必须真人出镜 | 优先 MG | 可被 B-roll 替代 | 可降级处理`。
 - **handoff 按 lane 分型**（校验器会硬查）：
   - `MG` → `handoff:{slug_hint?, theme?, bg?, duration_hint}`，**`duration_hint`（秒）必填**；可选 `category`（overlay 透明叠加/fullscreen 不透明满屏,裁决⑩,供色带分层,详见 field-schema）。
   - `FILM_BROLL` → `handoff:{queries:[...非空], shots?, per_shot_sec?, exclude?, anchors?}`，**`queries` 非空必填**；queries 写**英文长句场景描述**（一条一个意象，避多义动词），**exclude 保持中文**；`anchors` 为关键词锚（圈定指引见下节，细则见 field-schema）。
@@ -89,7 +90,7 @@ gtrk split --project "<oralcut产物目录>" --json
 
 ### 关键词锚（FILM_BROLL 的 `handoff.anchors`，选配但强烈建议）
 
-**为什么**：beat 级 queries 只保证「这段有对的画面」，不保证「说到关键词的那一刻画面正好对上」——听到「野牛高速」的瞬间看到野牛，是解说视频的看点兑现契约。铺轨会把锚 query 的最高分命中**钉在关键词说出时刻**（句级时码字符比例内插 − 0.5s 提前量），其余槽位在锚点两侧照常序贯填充。
+**为什么**：beat 级 queries 只保证「这段有对的画面」，不保证「说到关键词的那一刻画面正好对上」——听到「野牛高速」的瞬间看到野牛，是解说视频的看点兑现契约。铺轨会把锚 query 的**原始 sim 最高的合格命中**（原始检索相似度，**不是** mark/highlight 融合分）**钉在关键词说出时刻**（句级时码字符比例内插 − 0.5s 提前量），其余槽位在锚点两侧照常序贯填充。**锚预留优先于普通序贯槽消费**：铺轨前先为每锚锁住它的 sim 第一名，前序 beat 的泛化槽抢不走（锚落位或降级后立即释放）。真取不到第一名时**不静默**——锚 outcome 会如实报名次与去向（落的是第几名、第一名被谁取走）。
 
 ```jsonc
 "handoff": {
@@ -104,7 +105,7 @@ gtrk split --project "<oralcut产物目录>" --json
 - **圈「贵大奇多」类看点实词**——地名/地标（黄石湖、老忠实）、奇观名物（野牛高速、间歇泉）、数字头衔（全球第一、三万美元）：观众听到会期待「给我看」的词。**虚词/泛词勿圈**（「非常」「其实」「这个地方」锚不出画面）。
 - **每 beat 至多 2 个**（校验硬拒超额）——锚过密会把序贯填充区间切碎，节奏反而乱。没有值得钉的词就不写 anchors，宁缺毋滥。
 - `keyword` **照原句抄写**（须为该句 text 的子串，勿改写勿增删标点）；`utterance` 是关键词所在句 id（须落在该 beat 的 span 内）——两者校验器都硬查。
-- `query` 写**该关键词的视觉描述**（同 queries 语言规范：英文长句场景描述）——它与 queries 同链检索，锚点钉的是它的最高分命中；写抽象词等于锚一张糊画面。
+- `query` 写**该关键词的视觉描述**（同 queries 语言规范：英文长句场景描述）——它与 queries 同链检索，锚点钉的是它**原始 sim 最高的合格命中**（不是融合分最高）；写抽象词等于锚一张糊画面。
 - 锚 query 无合格命中时铺轨自动降级普通槽并在 summary 明示（不硬锚烂画面）——你无需为素材库兜底，只管圈对词。
 
 ### 4. 落地校验

package/skills/gtrk-splitter/references/field-schema.md

@@ -69,7 +69,10 @@
 //   - **exclude 保持中文**：负向过滤匹配的是服务端返回的中文 note，写英文会失效
 //   anchors（可选，关键词锚 · add-keyword-anchored-broll）：[{ keyword, utterance, query }] ≤2 个/beat——
 //   - keyword 照原句抄写（须为所在句 text 子串）；utterance 为该句 id（须在本 beat span 内）；query 写该词的英文视觉描述
-//   - 语义：铺轨把锚 query 最高分命中钉在关键词说出时刻（句级时码内插 −0.5s 提前量）；无合格命中自动降级普通槽
+//   - 语义：铺轨把锚 query **原始 sim 最高的合格命中**（原始检索相似度，不是 mark/highlight 融合分）
+//     钉在关键词说出时刻（句级时码内插 −0.5s 提前量）；无合格命中自动降级普通槽
+//   - 锚预留**优先于**普通序贯槽消费（铺轨前先为每锚锁住 sim 第一名，落位或降级后立即释放）；
+//     取不到第一名时锚 outcome 如实报名次与去向（第几名 / 第一名被谁取走），不静默当成钉准
 //   - 圈「贵大奇多」类看点实词（地名/奇观/数字头衔），虚词泛词勿圈；圈定指引见 SKILL.md「关键词锚」节
 
 // lane === "AI_DRAMA"  —— 全可选（下游框架 skill /gtrk-ai-drama 有推断默认）

package/skills/gtrk-tools/SKILL.md

@@ -94,7 +94,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 3. **一律带 `--json`**：`gtrk tool <name> <输入> --json`。stdout 只会有一行结果 JSON（`{ ok, outDir, files, taskId, fileId, … }`），人读日志在 stderr。按 `ok` 判成败、从 `files` 拿产物路径、把 `outDir` 回给用户。
 4. **缺 API Key 先引导配置**：cloud 型工具没配 Key 会报错让先跑 `gtrk init`。遇到就引导用户 `gtrk init`（或设 `GITRUCK_API_KEY`），别反复重试。
 5. **瞬时网络错误退避后只重试 1 次**：若 `gtrk tool list --json` 或工具命令因 `fetch failed`、`ECONNRESET`、`ETIMEDOUT`、`ENOTFOUND`、`socket hang up`、网络不可达或 HTTP `502/503/504` 失败，先等 **2 秒**，再原样执行同一命令 **1 次且仅 1 次**（总尝试次数最多 2 次）。第二次仍失败就停止，如实说明网络波动并给出最后错误，绝不循环重试。参数/文件校验错误、缺 Key、HTTP 4xx、云端业务错误码、明确的任务失败/取消均**不重试**。重试前先检查日志及输出目录：一旦已出现 `taskId` 或 `task.json`，说明任务可能已经提交，禁止重跑整条以免重复计费，转入下一条恢复语义。
-6. **产物落地与恢复**：产物落在 `outDir`（缺省 = 输入同目录下 `<输入名>-<工具名>/`，可 `--out <dir>` 覆盖）。提交成功即写 `task.json`（含 `taskId`）、完成即写 `result.json`。**分析型工具**（`video_segment` / `video_ai_segment` / `video_motion_cut`）产的是**结构化数据不是下载文件**：结果落 `result-output.json`（分镜/运镜结构），`result.json` 的 `resultFile` 字段指向它、`files` 为空且 `ok=true` 属正常，别当成「没出产物」。**若 `ok=false`**（任务完成但产物下载失败，如链接过期；或既无文件也无结构）：`result.json` 的 `errors` 有明细、`task.json` 保留——凭其中的 `taskId` 可稍后人工恢复取回，别急着重跑整条（重跑会重新计费）。
+6. **产物落地与恢复**：产物落在 `outDir`（缺省 = 输入同目录下 `<输入名>-<工具名>/`，可 `--out <dir>` 覆盖）。**无输入文件的工具**（`input=none`，如纯文本转语音）缺省落**当前目录**下 `<工具名>-<时间戳>/`。该名撞上已有目录时自动带 `-2`/`-3` 序号后缀；同一目录内产物文件撞名时带 taskId 后 6 位后缀。**一律以回执的 `outDir` / `files` 为准，别按名字硬拼**——猜出来的路径会指向上一次那份产物。提交成功即写 `task.json`（含 `taskId`）、完成即写 `result.json`。**分析型工具**（`video_segment` / `video_ai_segment` / `video_motion_cut`）产的是**结构化数据不是下载文件**：结果落 `result-output.json`（分镜/运镜结构），`result.json` 的 `resultFile` 字段指向它、`files` 为空且 `ok=true` 属正常，别当成「没出产物」。**若 `ok=false`**（任务完成但产物下载失败，如链接过期；或既无文件也无结构）：`result.json` 的 `errors` 有明细、`task.json` 保留——凭其中的 `taskId` 可稍后人工恢复取回，别急着重跑整条（重跑会重新计费）。
 7. **透传高级参数**：命令没为某个云端参数开 flag 时，用 `--param k=v`（可重复）或 `--params-json '<对象>'` 直接透传（如 `image_move` 想指定输出几何 `--param width=1080 --param height=1920`）。
 8. **单发单收、批量靠循环**：一次一份输入；用户要批处理就你逐个循环调。例外是多文件图片工具（`image_classic_template` / `image_vertical_stitch`）——它们的一份输入天然是一组图片（一次任务一次计费），传参顺序即拼装顺序，别把它当批处理。
 

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

@@ -23,30 +23,68 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 | BGM 音频文件 | 可选 | 没有就走素材矩阵搜索（见检查点①） |
 | 介绍类文本（txt/md） | 可选 | 有则作写稿补充素材 |
 
-**MUST NOT 执行任何网络下载**：网络视频二创场景下，下载动作归用户（版权责任边界）——用户给的文件夹里是什么就用什么。
+**一夹多片时检索域按场景分流（★ 2026-09-02 补）**：二创场景一个夹里常躺着好几条互不相干的片，
+**B-roll 检索域 MUST 收窄到正在做的那一部片本身**——`--dirs` 既吃文件夹也吃**单个素材文件**，传文件即把域收窄到该素材（见 §五 ⑦ 的★铁则）。
+原创（自拍素材集）那一档整夹就是这一片的素材域，**传夹正确**。
+
+**MUST NOT 下载二创源片 / 主体素材**：网络视频二创场景下，下载动作归用户（版权责任边界）——用户给的文件夹里是什么就用什么。**射程只到源片与构成成片主体画面的素材**：平台授权素材（同和素材矩阵的 BGM / 空镜）的**签名直链不在此列**（⟲ 2026-09-02 收窄：原措辞写「任何网络下载」，严于本 skill 自己的规格，且让 §四.4 那步 BGM 落地在字面上不合法；家族口径见 `gtrk-narration` / `gtrk-food-recap`——那两份长期同时挂着同款禁令与「`song` MUST 下载 `accompaniment_url` 伴奏版」，并存即证禁令从来只指源片）。收窄 MUST NOT 被读作给源片下载开口子——那条版权边界一字不动。
 
 **双场景识别**（决定理解编排走法）：
 - **二创**：文件夹里是网络旅行长视频（通常含博主解说语音）→ 原片文案是写稿主料；
 - **原创**：用户自己拍的素材集（通常无解说语音）→ 素材理解（describe）是写稿主料。
 - 拿不准就 ffprobe 看时长与条数：单条 10 分钟以上大概率二创；几十条短素材大概率原创。仍拿不准，问用户一句。
+- 原创场景的素材集常常**通篇没有对白**——那就不跑转写，下表的语种一问以「无对白 / 不转写」闭合，MUST NOT 因缺这个答案阻塞开工。
 
-**稿源与声音基座两问**（⟲ 2026-08-27 解说链家族回炉，开工时与双场景识别一并问清、MUST NOT 代猜）：
+**开工三问：稿源 · 声音基座 · 源片语种**（⟲ 2026-08-27 解说链家族回炉先立稿源与声音基座；⟲ 2026-09-02 补语种这一问——260902 真机一条**粤语对白**的片子按缺省 `zh-CN` 静默转写跑完，全链无一处问过语种。三问开工时与双场景识别**一并问清、一张表一次问完、MUST NOT 代猜**）：
 
 | 问 | 选项与走法 |
 |---|---|
 | 稿从哪来 | **AI 代写**（缺省，§三 规约写）/ **用户自备稿**——跳过写稿，稿直接进检查点①过目（文风铁律不强加于用户手稿，只提示明显硬伤） |
 | 声音怎么来 | **TTS 配音**（缺省，检查点①挑音色）/ **用户自己念**——拿念稿毛片先走 `gtrk oralcut` 粗剪（带稿最准；外录收音先 `gtrk audio align` 对轨），产出的粗剪工程即时间基座，§五 的「配音④→建工程⑤」两步跳过，从拆分⑥接入，后续铺排/字卡/BGM/字幕照旧 |
+| **源片语种 / 方言** | 取证=**听一段 / 看片内有无内嵌字幕 / 看素材出处**；答案定 §五 ① 的 `gtrk transcript --lang`（`zh-CN` 普通话 / **`zh-HK` 粤语** / `en-US` / `ja-JP`…）。**MUST 问用户、MUST NOT 代猜、MUST NOT 以缺省 `zh-CN` 静默开跑转写**——转写是计费动作**且早于检查点①**：**非中文素材**（`en-US` / `ja-JP`…）语种传错，用户在检查点①拿到的稿子就是坏的、重来要再付一次 ASR（真机实证）。**中文这一档（`zh-CN` ↔ `zh-HK`）不在此列**：粤语 **SHOULD** 如实填 `zh-HK`（元数据诚实 + 备将来链路切换），但当前实现下该参数**对粤语无影响**——两种写法发出的请求逐字段相同，详见 §五 ① 注。素材无对白：答「无对白 / 不转写」即闭合 |
+
+## 一′、素材适配闸（写稿前必过 · ★ 2026-09-02 真机事故立）
+
+> **事故形态**：三条素材里有一条是**有剧情、有台词、有摆拍的学生短片**，本图纸从头到尾跑完（含 TTS 计费步骤）、**零提示**。
+> 根因不是漏写一句，是**唯一的路由条款判的是「时序」而不是「题材」**——§一 的家族归位按「素材有无自带时序」出链，
+> 而剧情短片**自带叙事时序**（剧情线），按解说链判据它不但不出链，**反而正落在射程内**，出链闸永远不会触发。
+> ⇒ **本闸判的是题材，与「有无自带时序」正交，MUST NOT 由后者代行。**
+
+**取证零新增计费**（读的都是编排里本来就要产的东西，MUST NOT 为这道闸新加一次 describe 或转写）：
+
+- **原创场景**：读 `gtrk matrix index` / `gtrk matrix describe` 已产的 `desc`（中文视觉描述）与 `tags`；
+- **二创场景**：读 `gtrk transcript` 全文。
+
+**判据（可判定，逐条素材过一遍）**：
+
+- 主判据——这一条**能不能回答「这是在哪、看到了什么」**（可辨认的地点 + 所见之物）。能答的占比过低 ⇒ 不适配；
+- 反向命中任一即不适配：文本呈现**剧情对白**（人物一来一往推进情节）/ **摆拍表演**（演出来的而非记录下来的）/ **单一室内场景**（全片不出一个可辨认的地点）。
+
+**命中即硬停：MUST NOT 进入写稿**（形制照 `gtrk-vlog-docu` 的立神闸「写不出来 = 神没立住，MUST NOT 进入写稿」）。
+硬停位置是**写稿之前 = TTS 计费之前**——它与 §四 检查点①「未经确认 MUST NOT 发起计费动作」是同一条防线的**前置一层**：
+检查点①拦的是「稿子对不对」，本闸拦的是「**这活该不该接**」。停下时 MUST 如实列出**哪几条不适配 + 依据原文**
+（引 `desc` / `tags` / 转写里的原句，别只下结论），并给三条出路：
+
+| 出路 | 怎么走 |
+|---|---|
+| ① **剔除** | 把不适配的那几条摘出去，用剩下的素材继续跑本图纸 |
+| ② **改投** | 剧情 / 影视 / 游戏这类有时序但非旅拍的题材走 `gtrk-narration`（解说链正本）；素材无自带时序的题材（科普/情感/带货）走 `gtrk-voiceover` |
+| ③ **照跑** | 用户坚持就照办，但 **MUST 在交付说明里如实登记**「素材与旅拍垂类不匹配、要素层（贵大奇多钩子 / 攻略 tips）多半落空」（降档路径如实登记，口径同《成片型图纸公约》） |
+
+**两条边界写死**：agent **MUST NOT 自行判死**（决定权在用户，本闸只提名不宣判）、**MUST NOT 静默照跑**——
+后者正是 260902 那次事故的形态：全链跑完、零提示、钱已经花了。
 
 ## 二、全链总览（快速成片）
 
 ```
 ① 理解        transcript 原片（二创）/ matrix index + describe（原创）
+①′ 适配闸【必过】读 ① 的既有产物判题材（见 §一′）——不是旅拍就硬停，MUST NOT 进入写稿
 ② 写稿        三段式规约（见 §三）→ 解说稿 + 标题 + HashTag
-③ 检查点①     【必停】稿件确认 · 画幅 · 音色 · BGM（gtrk matrix material --scope audio）· 字幕样式（§四）
+③ 检查点①     【必停】稿件确认 · 画幅 · 音色 · 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
+⑦ 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 口径）
@@ -54,7 +92,8 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 ⑫ 交付        客户端打开工程出片（gtrk render 仅主轨快照预览，见 §八）
 ```
 
-检查点①之后一路跑完不再打扰用户——**垂类示例的承诺面就是快速成片一杆到底**（⟲ 2026-08-27 公约分层拍板）。交付后对个别环节不满意走 §七 增量重跑，对垂类玩法本身不满意走 §七 个性化出路。
+检查点①之后一路跑完不再打扰用户——**垂类示例的承诺面就是快速成片一杆到底**（⟲ 2026-08-27 公约分层拍板）。
+⚠️ 这条承诺**以 ①′ 适配闸通过为前提**：闸命中时的那次停顿不算「打扰用户」，它是在把钱花出去之前问一句「这活该不该接」。交付后对个别环节不满意走 §七 增量重跑，对垂类玩法本身不满意走 §七 个性化出路。
 
 ## 三、三段式写稿规约
 
@@ -84,8 +123,10 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 
 **成片时长 = min(内容所支撑, 素材所支撑)**：
 - 内容支撑：有多少真东西说多少话，素材再多也不注水；
-- 素材支撑：按「30% 图片×8 秒 + 70% 视频素材时长」估算上限，稿子在写稿阶段就按上限收敛（不要等铺轨时开天窗）；
-- 折算口径：约 200-240 字/分钟（TTS 实测，语速快的音色偏 270）。3 分钟成片 ≈ 700-800 字。
+- 素材支撑：按「30% 图片×8 秒 + 70% 视频素材时长」估算上限，稿子在写稿阶段就按上限收敛（不要等铺轨时开天窗）；把这个秒数换算成字数用下一条的折算口径（**公式本身不动**）；
+- **折算口径 = 挂钟语速**（wall-clock：稿件字数 ÷ 合成音频总时长，**含**句间停顿），**按检查点①选定的那条音色取值**；取不到该音色的语速就用**缺省 ≈330 字/分钟**，并明说这是缺省估值、**不是该音色的实测值**。3 分钟成片 ≈ **1000 字**。
+  缺省 330 的出处（★ 2026-09-02 立，`fix-speech-rate-calibration`）：全库 49 条 zh-CN 音色挂钟中位 308.7、`narrator` 349.3（**单点实测，未覆盖全库**）、260902 真机三条片 316–342 —— 逐条档案与标定方法见 `references/speech-rate.md`，**MUST NOT 把那张表贴回本图纸**（单一真值源，垂类只许引用）。
+- ⚠️ **MUST NOT 拿计费折算常量（240 字/分钟）推稿子字数**：那是**计费**用的保守下界（volc 单点实测 260 再下调留余量），与写稿侧的保守方向**正好相反**——计费侧低估语速只是「分钟数变大、不少收」，写稿侧低估语速却会让稿子写短、成片缩水（按 240 写 3 分钟 = 720 字，用 349 的挂钟语速实播只有 2.06 分钟，**缩水 31%**）。计费那一栏见 §九，两个数 MUST NOT 互相冒充。
 
 **写后自校验清单**（逐项过，不过重写）：
 - [ ] 三段结构完整、时长在 min 公式内
@@ -126,26 +167,70 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 
 ## 四、检查点①（双模式共有，必停）
 
-写完稿**必须停下**，把以下五项一次给用户拍板。**未经确认 MUST NOT 发起 TTS 计费动作**。
+写完稿**必须停下**，把以下六项一次给用户拍板。**未经确认 MUST NOT 发起 TTS 与 B-roll 云端编排计费动作**。
+
+> ⟲ **2026-08-31 订正**（口径抄齐 `gtrk-narration` 正本 §六 与 `gtrk-food-recap` §五，同一条口径只许有一种说法）：
+> 本节原以「TTS 是唯一计费闸」立论，已不成立——**本地素材的编排自该日起默认走云端并按「编排量」计费**，
+> `matrix lay` **跑前会再停一次**报预估（那次不是拍板，是花费确认）。
+> **agent 纪律**：MUST 先把预估用量告诉用户、**拿到同意再带 `--yes`**；**MUST NOT 未经同意就带 `--yes`**。
+> 不带 `--yes` 且无 TTY 时本步**整轮铺轨中止**、工程零改动（plan 照常可用、可重跑）——
+> **MUST NOT 把它描述成「回落本机编排」**：那是 2026-08-31 二次拍板前的旧行为，家族里还有过期字面在流传。
+> （260902 真机三条片全部停在第 ⑦ 步，就是「图纸没带 `--yes`、也没地方报预估」这一处漏的形态。）
+
+> **语种不在这六项里**（⟲ 2026-09-02）：它在 §一 开工三问就已定，检查点①对它最多做**过目复核**。
+> 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 标注的音色注明「仅内部成员」。也可按用户描述语义挑（「要个温柔女声」）；
+3. **TTS 音色**：拉 catalog（`GET {apiBase}/task/tts/voices`，免鉴权）按内容调性挑 2-4 个候选，**每个附试听链接**（catalog 的 audition_url 字段，api.ai-mcn.tv:9000 静态直链）——用户在对话框里直接点开听。internal 标注的音色注明「仅内部成员」。也可按用户描述语义挑（「要个温柔女声」）。
+   **每个候选还 SHALL 附上该音色的挂钟语速与据此推的稿件字数区间**（查 `references/speech-rate.md`；档案里没有就明说「用缺省 330 估」）——挑音色的同时也是在挑稿子长度，别让用户回头才发现稿子长了三成。这条是**加项**，MUST NOT 削弱既有的「无试听链接 = 未完成推荐」义务；
 4. **BGM 处置（双来源）**：
    - 用户有本地音乐 → 询问是否 `gtrk tool audio_separation` 伴奏分离后取伴奏（缺省建议分离——TTS 配音不与歌曲人声打架）；
    - 用户未提供 → **搜同和素材矩阵**：`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 给用户挑不许默认 top1；跨片避让由 `audio lay` 记账 + 检索缺省 `--exclude-recent` 自动完成）（按成片时长挑可加 `--min-duration <秒>`）。身份路由（矩阵成员搜全库 / 非成员搜公开库）与计费口径由零件持有；**版权判断不在零件手里，在你手里**——零件缺省 `copyright_scope=all`，**不筛**。挑 BGM MUST 按**可商用**口径判：出参 `is_copyright` 的权威语义是 `1/true` = **可商用**、`0/false` = **不可商用**（反直觉：`is_copyright:false` MUST NOT 读成「无版权、可随便用」，它恰恰是不可用的那一档；概念素材固定 `is_copyright=0` 即此意）。派生位 `copyright_label` 直接给了中文标签，照它转述即可。省事路是检索时就带 `--commercial-only`，把不可商用的挡在候选之外；出参 `results[]` 直接用，`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，别留悬空 · ⟲ 2026-09-02 补）**：检索出参只给**签名 URL**，而 §五 ⑩ 的 `gtrk audio lay --file` **只收本地路径**（传 URL 必炸）——拍板之后、上轨之前，agent MUST 把选中曲**落成本地文件**。口径照解说链正本 `gtrk-narration` §五 原文对齐：`audio_type:"song"` **MUST 取 `accompaniment_url` 伴奏版上轨**、**MUST NOT 用 `download_url` 原曲**（人声与配音打架，260827 美食批踩坑）；`"pure"` 取 `download_url`。文件名按 **`bgm-<曲名>[-伴奏].<扩展名>`** 约定——跨片避让记账按**标题归一化键**匹配（剥 `bgm-` 前缀与 伴奏 / instrumental / off-vocal 后缀），命名不合规会让下一轮 `--exclude-recent` 避让失准。这一步不违反 §一 的下载禁令：那条禁令的射程只到二创源片 / 主体素材，平台授权素材的签名直链不在其内。
 5. **字幕样式**：7 种样式（default/outline/cinema_yellow/immersive_box/wide_spacing/deep_shadow/boxed）× 11 色（雅黑/淡绿/森林绿/湖蓝/道奇蓝/钢蓝/浅粉红/深橙/珊瑚橙/橙红/土豪金）挑选；**用户没选就用 default+雅黑**（不追问不阻塞）。拍板值在 ⑪ `gtrk subtitle lay` 落地，客户端里仍可整轨换样式（悔棋通道）。
+6. **B-roll 编排量预估（★ 2026-09-02 补，本地素材路必报）**：本地素材产的 plan 走 `matrix lay` 时**缺省即云端编排、按「编排量」计费**（`--arrange local` 已不受理，逃生舱是关死的）。先拿数再拍板：
+
+   ```bash
+   gtrk matrix lay --project "<工程目录>" --arrange-estimate-only --json   # 停在计价确认之前：零云端调用、工程文件零改动
+   ```
+
+   把它与 TTS / describe 的预估**同屏**报给用户，一次拿到同意——§五 ⑦ 的 lay 才允许带 `--yes`。**报不出这笔就不许开跑**（图纸原来既没这一项、也没那个 flag，于是既报不出、又必断链）。
 
 ## 五、快速成片编排（打样验证过的真实命令）
 
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> 文本产物只落 CLI 返回的路径或**用户显式指定的 `-o, --out`**；`transcript` / `oralcut` / `long2short`
+> 的缺省落点都是**源文件同目录**，这是在案设计、不是 bug（`skills/gtrk-transcript/SKILL.md:21`、
+> `README.md:343`·`:351`、`test/transcript-cmd.test.mjs:63` 三处独立在案）。
+> 但二创的源片通常躺在**用户自己的素材库**里，落进去每跑一条污染一次
+> （260902 真机在 `旅拍素材原片/` 下留了 4 个裸产物）⇒ 本图纸 §五 ① **SHOULD 带 `-o`
+> 把文本产物挪进工程 / 文稿目录**；用户明说就要放源片旁，不传即可——那是缺省，不算违纪。
+> **MUST NOT** 把原片或任何大媒体复制进 agent 自有工作目录（会话工作区 / agent 家目录缓存）——
+> 需要引用媒体时**用原路径引用**，不做副本；临时文件一律放系统 temp 且**用完即删**（含中断 / 失败路径）。
+
 ```bash
 # ① 理解（二创：转写原片，--json 顺产 transcript.json 备用）
-gtrk transcript "<原片>" --lang <原片语言 en-US/zh-CN> --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 ...
+#   ↑ 原创（自拍素材集）这一档**整夹即该片素材域，传夹正确**，不受 ⑦ 那条「钉单片」铁则约束——
+#     那条治的是二创：一个夹里躺着几条互不相干的片，才会互相抢候选
 
 # ②③ 写稿（你执笔，§三规约）→ 检查点①拍板
 #   BGM 候选（用户没自带音乐时，检查点①之前搜好一起拍板；试听链接=结果的 download_url）
@@ -154,6 +239,12 @@ gtrk matrix material "<情绪+地理文化检索词>" --scope audio --top-k 5 --
 # ④ 配音（音色 code 用 catalog 的 voice_id；稿子存 txt 传 --text-file）
 gtrk tool audio_tts_clone --text-file <稿.txt> --speaker <voice_id> --json
 
+# ④′ 语速回校（★ 2026-09-02 新增，零成本自我标定；快速成片照跑不停顿，只汇报）
+#   实测挂钟语速 = 稿件字数 ÷ 音频实际时长（时长取 ffprobe duration；字数口径同服务端：Unicode 码点、含标点与英文数字）
+#   与写稿时所用的估值比对：**偏差 >15% MUST 在交付汇报里点名**（报「估 X / 实测 Y / 偏 Z%」），
+#   并按 references/speech-rate.md 的五项格式追加一条标定档案 —— 每跑一条片攒一条样本，「孤证」从结构上消失。
+#   MUST NOT 自动改稿、MUST NOT 自动重跑 TTS：改稿得从 ④ 重跑（TTS 变=全链时码变，⑤起全部重建）、要重付 TTS 费用，返工与否是用户的决定。
+
 # ⑤ 建工程（画幅按检查点①拍板；产物目录含 gtrk/transcript/audio）
 gtrk project init --tts-task <TTS任务id> --canvas 1920x1080 --no-open --json
 #   ↑ 产的 transcript 文稿缺省去逗号句号（成片字幕口径）；要**带标点的文稿版本**
@@ -165,20 +256,42 @@ gtrk split --project "<工程目录>" --json          # 投影：拿 utterance i
 #   lane 全 FILM_BROLL、base_track="旁白主导"、narrative 用八枚举、
 #   字卡挂 aux_layers type:"overlay"（handoff.category:"overlay"+duration_hint，进 dispatch.mg）、
 #   看点关键词圈 handoff.anchors（[{keyword,utterance,query}] ≤2 个/beat——地名/奇观/数字头衔类实词，
-#   铺轨把锚 query 最高分命中钉在关键词说出时刻：听到「野牛高速」的瞬间看到野牛；圈定指引见 gtrk-splitter）
+#   铺轨把锚 query **原始 sim 最高的合格命中**（原始检索相似度，不是 mark/highlight 融合分）
+#   钉在关键词说出时刻：听到「野牛高速」的瞬间看到野牛；锚预留优先于普通序贯槽消费，
+#   取不到第一名时锚 outcome 如实报名次与去向；圈定指引见 gtrk-splitter）
+#   ⚠️ 上面这串是**非穷举**摘录（另含 irreplaceability / rhythm / visual_task / container_stage 四个必填项）：
+#   beat 必填字段全表以 gtrk-splitter 的 references/field-schema.md 为准，MUST 照该表写全
 gtrk split "<拆分稿>" --project "<工程目录>" --json
+#   ↑ 落地后走一遍 §六 末的**字卡自检清单**：数 type:"overlay" 的 aux 条数、核对 --json 回执里
+#     queues.mg 的条数是否落在「每片 2-4 颗」（这个数以前全链无一处比对，真机两条片各只落 1 颗无人喊）
 
 # ⑦ B-roll 三连（describe 给字卡抽帧检查与 mark 加权供料；internal 用户 describe 免费）
-gtrk matrix --project "<工程目录>" --local --dirs "<素材夹>" --lay 0 --json
+# ★ 铁则（口径同 gtrk-narration 与 gtrk-matrix，不许长出第二种说法）：解说链**一稿对一片**——
+#   二创场景 --dirs MUST 钉到**这一部片的绝对路径**，**不许传素材夹**。--dirs 既吃文件夹也吃单个素材文件，
+#   传文件就是把检索域收窄到该素材。同夹邻片会抢占候选：260828 三片同夹实测 187 个候选里 86 条来自邻片（46.0%），
+#   那不是「排序靠后的次优解」，是**范畴错误**——A 稿的解说配 B 片的画面永远不可能对。
+gtrk matrix index --dirs "<这一部片的绝对路径>" --json
+#   ↑ 二创也要先建索引（原来 index 只挂在原创分支下，于是只能顺手对整夹建、正好把三条片灌进同一个 index.db）；
+#     若此前已对整夹建过索引则**不必重建**，检索侧传单片即可收窄（判据是路径前缀，传的就是那一条素材本身）
+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 --highlight-weight 0.2 --gap-fill fast --json
+#   ↑ 同时读 describe 输出的**剔除风险**清单：候选数 ≤1 的 beat 一删就掏空
+#     （音频驱动 ⇒ 整段黑屏或跨 beat 借片；口播 ⇒ 露 A-roll）。先补素材再剔，MUST NOT 见 flag 就删。
+#     ——260902 真机 P3 八个 beat 里七个只有 1 条候选，按 flag 删就是把整段掏空
+gtrk matrix lay --project "<工程目录>" --mark-weight 0.3 --highlight-weight 0.2 --gap-fill fast --yes --json
+#   ↑ --yes 的前提是**编排量预估已在检查点①（§四.6）报过并拿到同意**；MUST NOT 未经同意就带。
+#     不带 --yes 且无 TTY 时本步**整轮铺轨中止**、工程零改动（plan 照常可用、可重跑）——
+#     260902 真机三条片全停在这一步，就是「图纸漏了这个 flag、也没地方报预估」的形态
 
 # ⑧⑨ 字卡（§六 规约产颗粒 → lint → 铺）
 gtrk mg lint "<工程目录>/mg/<composition_id>.html" --dispatch "<工程目录>/split/dispatch.json"
 gtrk mg --project "<工程目录>" --json
 
-# ⑩ BGM（音量口径见下）
+# ⑩ BGM（音量口径见下；<bgm> 是**本地文件**，检查点①拍板后先落地——URL 传给 --file 必炸）
+# BGM 是带人声歌曲（audio_type:"song"）→ MUST 下载 accompaniment_url 伴奏版上轨，
+# 不得用 download_url 原曲（人声与配音打架，260827 美食批踩坑）；"pure" 取 download_url。
+# 文件名 bgm-<曲名>[-伴奏].<扩展名>：跨片避让按**标题归一化键**记账（剥 bgm- 前缀与伴奏/instrumental/off-vocal 后缀），乱命名=下一轮 --exclude-recent 失准
 gtrk audio lay --project "<工程目录>" --file "<bgm>" --volume 0.1 --beat-align --json
 
 # ⑪ 字幕（样式/颜色 = 检查点①拍板值；用户没选用 default/雅黑；纯本地零计费、重跑幂等替换）
@@ -194,7 +307,7 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
   **MUST NOT 加到语义压不住**（那会变成「专挑好看的，不管说的是什么」）。
   ⚠️ 两个权重与 blurry 降权**都依赖 `matrix describe --plan` 跑过**（编排 ⑦ 那一步）；
   没跑就是全部候选中性、排序与不开权重逐字节一致——lay 会就此打告警，看到就说明漏了；
-- `--gap-fill fast`（★ 主理人 2026-08-21 拍板：快速成片不留空）：主轨空洞放宽地板随便填候选→延长相邻颗粒→黑片兜底——客户端主轨磁吸开启时 gap 会被吸除、画面与配音错位，快速成片以画面连续性优先；CLI 缺省是 solid（黑片垫齐，精修可见），本配方须**显式传 fast**；
+- `--gap-fill fast`（★ 主理人 2026-08-21 拍板：快速成片不留空）：主轨空洞按**五级**依次填——放宽地板取剩余候选 → 段界内延长相邻颗粒 → **跨 beat 借未消费候选** → **次地板补真画面** → 仍不够才落黑片。⚠️ 后两级容易被误当 bug：借来的画面**与本段稿子相关性弱**，次地板槽是**不到 1.2s 的快切**；两者都会在日志里指名报出（`kind` 为 `borrowed` / `subfloor`）——那是**如实告知，不是缺陷，别当 bug 上报**。宁可这样也不落黑，是因为客户端主轨磁吸开启时 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 对应的原片区间约束检索（可选增强，全库检索在几百场景规模下命中率已够）；
@@ -213,6 +326,21 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 - **产前抽帧**（overlay 必做）：对挂点用本地 ffmpeg 抽 1 帧看底轨明暗与主体位置（临时文件落系统 temp 用完即删）；
 - 产物存 `<工程目录>/mg/<composition_id>.html`，逐颗 lint 过了再铺。
 
+**字卡自检清单**（★ 2026-09-02 补，形制同 §三「写后自校验清单」）：
+
+- [ ] 拆分稿写完，**数一遍** `aux_layers` 里 `type:"overlay"` 的条数，是否落在**每片 2-4 颗**；
+- [ ] 落地后核对 `gtrk split --json` 的 `queues.mg` 条数，与上一条对得上、且仍在 2-4；
+- [ ] 不足按地标出场句补挂；超出按「稀缺才有力」裁掉。
+
+> **为什么补在图纸而不上机器闸**（拍板留痕）：「2-4 颗」以前**全链无一处拿它比对**——`split` 只如实报数、
+> `mg` 的 `empty_queue` 只防误清空整轨、`mg lint` 是单颗 HTML 内的静态校验、`splitdoc` 对 `aux_layers`
+> 条数零校验；于是真机两条片各只落 **1 颗**，下游每一环都 100% 报「全部铺成」，观感上完全正常，**无人喊**。
+> 但它与仓内唯一那道数量硬闸（`MAX_ANCHORS_PER_BEAT`）**判据类型不同**：那条的理由是**工程后果**
+> （锚过密会把序贯填充区间切碎），字卡颗数是**审美编排量**——上通用闸等于让通用契约背垂类配方
+> （撞 `gtrk-mg`「不硬编任何栏目的视觉风格」）。缺口的真正位置是**图纸缺自检项**（§三 有、§六 没有），
+> 补在缺口上最省，**零代码变更**。⚠️ 反方也如实记：颗数是 `dispatch.mg.length` 一行就能算的机器可判量，
+> 若这类漂移反复发生，改上「通用可选入参 + 由图纸传值 + 非致命告警」是正当的。
+
 ## 七、增量调整与个性化出路（垂类示例定位）
 
 **本图纸是解说链的垂类示例，承诺面只有快速成片**（检查点①一次拍板后一杆到底；决策前置三条腿照公约执行，单模式不豁免）。交付后对**个别环节**不满意，用下表增量重跑悔棋——改哪步跑哪步，不整链重来：
@@ -221,7 +349,7 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 |---|---|---|---|
 | 写稿 | 解说稿 vN | 用户改意见 → 你改稿 | 改稿后从 ④ 重跑（TTS 变=全链时码变，⑤起全部重建） |
 | 拆分 | split/view.json + 拆分稿 | 改 beat 划分/queries | `gtrk split <拆分稿> --project` 重落 |
-| B-roll | broll-plan.json | 编辑 plan（删候选/换段/pinned 钉选） | `gtrk matrix lay`（消费 plan 零检索零计费） |
+| B-roll | broll-plan.json | 编辑 plan（删候选/换段/pinned 钉选） | `gtrk matrix lay`（消费 plan **零检索**；⚠️ 本地素材路的**编排仍按编排量计费**，不是零计费——重跑前照 §四.6 再报一次预估） |
 | 字卡 | mg/*.html | 改颗粒 HTML | `gtrk mg --project --only <beatId>` 单颗重铺 |
 | BGM | audio_track | 换歌/换音量 | `gtrk audio lay` 同文件幂等替换 |
 | 字幕 | cve 字幕 lane | 换样式/颜色 | `gtrk subtitle lay --style/--color` 重跑幂等替换（手加 text 不受影响）；逐条微调在客户端 |
@@ -236,6 +364,7 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 - **`gtrk render` 仅是主轨快照预览**（★ 打样误用教训）：只渲一条视频轨、不合成字卡 overlay——可以当粗查混音与 B-roll 落位的预览片，**MUST NOT 当成片交付**；
 - **云渲必拒**：含本地 B-roll 的工程提交云渲会被直接拒绝（`local_broll_cloud_render_rejected`）——出片走客户端本地导出或 `gtrk render` 预览，如实告知用户；
 - 交付话术：报产物目录+客户端打开指引+各环节计费实耗；候选轨小眼睛切换、字卡可删可改、BGM 音量客户端可终调、字幕客户端可整轨换样式——把悔棋通道讲清楚。
+  - 报计费实耗 SHALL 转述 `--json` 的 `credits_estimated`（**实耗口径**，豁免时为 0），MUST NOT 转述 `credits_would_be`（原价）；`exempt_probe:"failed"` 时须注明『身份没探到，此数按非豁免保守估』。
 
 ## 九、计费速查
 
@@ -244,12 +373,18 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 | transcript 转写 | ASR 按分钟 | 二创场景一次 |
 | matrix index（embed） | 会话计量按实际用量 | 同合云内部成员豁免 |
 | matrix describe | 1 积分/张 | 内部成员豁免；同帧缓存永不重复计费 |
-| TTS 配音 | 按成本档 1-12 积分/计费分钟（240 字/分钟折算） | 音色 catalog 可查档位；同参重合成走缓存不重复扣费 |
-| project init / split / audio lay / subtitle lay | 0 积分 | producer 同步口 0 元留痕；beat 分析（--beat-align）走 audio_music_analyze 计费 |
+| **B-roll 云端编排（`matrix lay`，本地素材路）** | 按「**编排量**」计费（服务端复算为准） | 缺省即走云端（`--arrange local` 已不受理）；素材矩阵路的编排在本机跑、不计费。预估用 `--arrange-estimate-only`（§四.6），跑前须已拿到同意 |
+| TTS 配音 | 按成本档 1-12 积分/计费分钟（240 字/分钟折算） | **计费分钟按标准语速折算，不等于音频实际时长**；音色 catalog 可查档位；同参重合成走缓存不重复扣费 |
+| project init / split / audio lay / subtitle lay | 0 积分 | **`matrix lay` 不在此列**（见上一行的云端编排）；producer 同步口 0 元留痕；beat 分析（--beat-align）走 audio_music_analyze 计费 |
 | BGM 矩阵搜索（`gtrk matrix material`） | 公开口 1 积分/次；矩阵成员口 0 积分 | 档位由零件自动路由，命令输出如实报口径与计费 |
 | image_move 图片运镜 | 2 积分/张 | 素材夹含图片且被选中上轨时 |
 
+> ★ **脚注（划界，2026-09-02）**：表里那个 **240 字/分钟是计费折算常量**，
+> **MUST NOT 用于写稿篇幅估算** —— 写稿口径在 §三（挂钟语速，按音色取、缺省 ≈330），两者保守方向相反。
+> 本脚注**只划界，不动**该行的积分档位与计量单位（单位口径归 infra `refactor-billing-measure-kchar` 的 CLI 联动件）。
+
 起跑前把预估总消耗报给用户（检查点①一并确认），结束报实耗。
+**§一′ 适配闸命中而中止时，已经发生的计费（transcript / index / describe）SHALL 如实报出**——MUST NOT 只报一句「已中止」把账藏起来。
 
 ## 十、已知边界与排障
 
@@ -258,7 +393,7 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 - **字幕**：⑪ `gtrk subtitle lay` 已直接上好（7 样式 × 11 色，客户端可整轨换样式、逐条可编辑）；改稿重跑 TTS 后须重跑 subtitle lay（时码变了）；
 - describe 的 `text_overlay` 信号命中多为撞上原片烧录字幕区（片头片尾高发）——裁定换段或保留交客户端；
 - `matrix lay` 拒铺（`tracks_edited`）不是失败：用户在客户端动过候选轨，plan 照产（`planReusable:true`），提示用户后按其意愿 `--replace-all` 或保留；
-- BGM 曲长 < 成片：audio lay 不循环，垫不满如实告知（客户端可复制 clip 补尾）。
+- BGM 曲长 < 成片：**已不再是边界**（⟲ 2026-09-02 订正——旧条目按早期行为写，落后于实现整整一版）。现行缺省是**循环叠满至工程末尾、尾段裁齐**（多 clip 首尾相接，命令打 INFO 报段数），不必再去客户端补尾；要单次铺才传 `--no-loop`。
 
 ---