@gitruck/cli 0.2.16 → 0.2.17

package/AGENT.md

@@ -1,8 +1,8 @@
 # gtrk-cli · Agent Playbook
 
 给 **agent** 看的操作手册：把用户「想剪一条口播」的自然语言需求，落成对 `gtrk` CLI 的一次调用，
-再把产物目录 + 三端（客户端 / 剪映 / PR）打开方式回给用户。任何 agent（Claude / Cursor / …）读完
-这一份就能驱动整条闭环；Claude 的 `/口播剪辑` skill 只是这份 playbook 的薄壳。
+再把产物目录 + 三端（客户端 / 剪映 / PR）打开方式回给用户。任何 agent 读完
+这一份就能驱动整条闭环；随包分发的各 `/gtrk-*` skill 只是这份 playbook 的薄壳。
 
 > 这条 CLI 做的事：**本地抽音频/720p（毛片永不上传）→ 只传抽出物 → 云端智能口播剪辑（video_oral_cut）
 > → 拉回 gtrk/剪映/PR 三方工程文件 →（可选）本地 ffmpeg 渲染成片 → 三端打开**。云端零改动、纯结构产物，
@@ -10,6 +10,17 @@
 
 ---
 
+## 产物落点纪律（全局 MUST · 本 playbook 与随包全部 skill 通用）
+
+- 一切产物（成片 / 预览 / 代理 / 素材 / 工程文件）只落**工程目录**（产物目录）或**用户显式指定的输出路径**。
+- **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录
+  （如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）。
+  需要引用媒体时**用原路径引用**，不做副本。
+- 临时文件（抽帧图 / 中间物等）一律放系统 temp 且**用完即删**（含中断 / 失败路径也要清干净）。
+- 违反本条的直观后果：用户系统盘被静默吃满——这是真机发生过的事故，不是假设。
+
+---
+
 ## 0. 一句话流程
 
 ```

package/README.md

@@ -27,7 +27,7 @@
 | ✂️ | `gtrk split [拆分稿]` | 视觉拆分派单器：成片 × transcript 投影 → beat 分镜校验落地（`struct_meta.split` + `dispatch.json`），驱动四车道派单；`--column <id>` 按栏目词表校验 |
 | ⚙️ | `gtrk init` | 引导式一次性配置（API Key + 剪映草稿目录），之后免管 |
 | 🩺 | `gtrk doctor` | 体检：配置 / 云端连通 / 剪映目录 / 运行时一键自检 |
-| 🤖 | `gtrk skills install` | 通过通用 `skills` 适配器和 gtrk 补充层，把 9 个 CLI 自带 skill 装进本机检测到的主流 Agent；`--all` 可覆盖全部已登记宿主 |
+| 🤖 | `gtrk skills install` | 通过通用 `skills` 适配器和 gtrk 补充层，把 10 个 CLI 自带 skill 装进本机检测到的主流 Agent；`--all` 可覆盖全部已登记宿主 |
 | ⬆️ | `gtrk upgrade` | 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装 |
 | 🎞️ | `gtrk render` | 本地渲染 gtrk 工程（EDL）→ 成片 mp4（需 ffmpeg） |
 | 🔎 | `gtrk matrix` | B-roll 检索+**候选铺轨**：消费 FILM_BROLL 派单 → 产候选清单 + 下载 preview 代理铺 N 条候选轨（`--lay N` 默认 1，opencut 打开即可用轨道小眼睛对比；`--lay 0` 只出清单）；`matrix search "<词>"` 单条 ad-hoc |
@@ -160,7 +160,7 @@ irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex
 | ![在 Agent 中调用 gtrk 示例 1](assets/agent-example-1.png) | ![在 Agent 中调用 gtrk 示例 2](assets/agent-example-2.png) |
 | ![在 Agent 中调用 gtrk 示例 3](assets/agent-example-3.png) | ![在 Agent 中调用 gtrk 示例 4](assets/agent-example-4.png) |
 
-`gtrk install` 会把 9 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-ai-drama`·`gtrk-style-maker`·`gtrk-transcript`·`gtrk-tools`·`gtrk-music-visualizer`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
+`gtrk install` 会把 10 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-ai-drama`·`gtrk-style-maker`·`gtrk-transcript`·`gtrk-tools`·`gtrk-music-visualizer`·`gtrk-cover`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
 
 默认使用 `~/.agents/skills` 作为统一正本，再链接到各 Agent 的兼容目录（Windows 使用 junction）；链接不可用时适配器会回退复制。这样更新只有一份正本，不会让多份副本逐渐漂移。常用命令：
 
@@ -202,9 +202,10 @@ gtrk skills install --copy
 | 📝 | `/gtrk-transcript` | `gtrk transcript` | 本地视频 → 一个含 Agent 总结、时码记录和纯文本的 Markdown，**不在成片 SOP 序列内** |
 | 🧰 | `/gtrk-tools` | `gtrk tool <name>` | 单点工具族（图转运镜 / 图片·视频抠像…）——单发单收，**不在成片 SOP 序列内**、随时可独立用 |
 | 🎵 | `/gtrk-music-visualizer` | `gtrk music-visualizer` | 一首歌 → 频谱可视化成片（模板 + 可选背景/封面 + 配色样式），**不在成片 SOP 序列内**、独立引流用 |
+| 🖼️ | `/gtrk-cover` | （无命令，纯创作） | 封面工作台两阶段：设计诊断 + 三尺寸中英双版文生图 Prompt → 用户外部平台抽图 → H5 排字工作台（拖拽/滚轮微调、一键导出多尺寸 PNG）。栏目封面审美经栏目配置 `style.skills`（`produces:"cover"`）注入；**不在成片 SOP 序列内**（投放配套的「第 0 阶段」） |
 
 > **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ④ 步（B-roll 定了才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
-> 上面 9 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装）——`/gtrk-transcript` 独立驱动视频转文字稿，`/gtrk-tools` 只负责单点工具族，二者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
+> 上面 10 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装）——`/gtrk-transcript` 独立驱动视频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，三者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
 
 **各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 再现什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
@@ -499,7 +500,7 @@ gtrk-cli/
 ├── src/index.ts              # commander 入口
 ├── src/commands/             # 子命令：install / init / oralcut / transcript / split / doctor / upgrade / skills
 ├── src/lib/                  # cloud / column-config / splitdoc / projection / user-config / jianying / …
-├── skills/                   # 打包的框架 skills：oralcut / splitter / matrix / mg / ai-drama / style-maker / transcript / tools
+├── skills/                   # 打包的框架 skills：oralcut / splitter / matrix / mg / ai-drama / style-maker / transcript / tools / music-visualizer / cover
 ├── contracts/                # 框架契约库正本（gsap-emit v1 + handoff→契约映射表）
 ├── assets/                   # README 配图（介绍图 / Agent 调用示例 / 剪映草稿目录指引图）
 └── AGENT.md                  # 可移植 agent playbook（skill 底座）

package/dist/index.js

@@ -10017,7 +10017,6 @@ function detectPrimitiveLoops(html) {
     for (const call of fnCalls) {
       if (create.loops.length === 0 && call.loops.length === 0)
         continue;
-      const inside = loopProduct(create.loops);
       const callerBody = innermostLoopBody(call.at, call.loops);
       const boundParent = parentBindingScope(create.fn, create.parent);
       const freshAt = freshParentDeclaration(create.parent, create.at, boundParent);

package/package.json

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

package/skills/gtrk-ai-drama/SKILL.md

@@ -27,6 +27,11 @@ description: AI 再现分镜稿生成器——把成片 SOP 第⑤步分到 AI_D
 2. **只产描述，不产成片、不产角色圣经、不产参考图。** 本 skill 的交付物是四段可移植描述文本。出片（渲染成视频片段）、角色三视图/角色圣经、参考图，全在下游平台或用户手里。不要假装能帮他渲染或建角色资产。
 3. **中英双版地位平等，不是主辅。** ①视觉基调、②故事背景、③角色、④分镜四段每一段都给完整的中文版 + 英文版（不是把中文翻一句了事）。中文喂可灵 / 即梦 / Vidu / 通义，英文喂 Veo / Runway / LTX / Luma，用户按目标平台选。**唯独 ⑤ 原文文稿是中文口播原文、不翻译**（它是源真相 + 手动拼接的对位锚，翻译反而失真）。
 
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> 分镜稿只落**工程目录**（`<project>/ai-drama/<beat_id>.md`）或**用户显式指定处**；
+> **MUST NOT** 把用户媒体（毛片 / 成片 / 预览 / 外部平台出的片段）或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
+> 临时文件一律放系统 temp 且**用完即删**（含中断 / 失败路径）。违者后果 = 用户系统盘被静默吃满（真机事故，非假设）。
+
 ## 业务分离：栏目 Style Lock 从哪来（关键）
 
 **视觉风格不是本 skill 预设的，是从栏目配置里解析出来的。** 解析链路（与 `gtrk-splitter` 的车道→生产 skill 解析同源）：

package/skills/gtrk-cover/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: gtrk-cover
+description: 封面工作台——把一期视频的封面从「设计诊断 + 文生图 Prompt」到「H5 排字工作台一键导出多尺寸 PNG」两阶段做完。阶段一产诊断与三尺寸中英双版 Prompt（用户拿去 Midjourney / Flux / SDXL / Nano Banana / 即梦 / 可灵 / 通义万相 等任意文生图平台抽图），阶段二收齐背景图后产可拖拽排字的单文件 H5 工作台、浏览器里导出原分辨率 PNG。这是**纯创作 skill、无 gtrk 命令**（抽图在外部平台、排字在用户浏览器，同 /gtrk-ai-drama）。当用户想「做封面 / 出封面 / 封面 prompt / 封面排版 / 封面工作台 / cover」时使用本 skill。通用封面工艺（两阶段交付 / T1 字数布局路由 / Prompt 槽位 / 工作台引擎）由本 skill 自持；栏目封面审美（色板 / 字体 / 意象体系 / T1 样本）从栏目配置 style.skills 里 produces=="cover" 的条目解析注入，绝不硬编某栏目风格。凡给成片配封面，优先用本 skill，别手搓 prompt、别让用户裸排版。
+---
+
+# 封面工作台（gtrk-cover）
+
+把一期视频的封面走完两阶段：**阶段一**产设计诊断 + 三尺寸中英双版文生图 Prompt，交棒用户去外部平台抽图；**阶段二**收齐背景图后产**定制化 H5 排字工作台**（单文件 HTML、可拖拽 / 方向键 / 数值 / 滚轮微调、逐尺寸与一键导出原分辨率 PNG），用户在浏览器里排字导出。
+
+> **这是纯创作 skill、没有 gtrk 命令**——主链路「审美诊断 → Prompt → 外部平台抽图 → 用户浏览器拖字导出」里，抽图与排字两个环节的「手」在外部平台和用户手里；唯一的机械段（背景图压缩 + base64 注入模板）是一次模板文本替换，量级不足一条业务命令，且 `.gtrk` 工程没有封面槽位可写回（性质同 `/gtrk-ai-drama`）。别去找 `gtrk cover` 这条命令，它不存在也不该存在。
+
+## 定位：管线外的「第 0 阶段」
+
+封面**不在成片 SOP 序列内**（oralcut→split→matrix→mg→ai-drama→render 是片内的事），但它是观众看到的第 0 帧——**封面与标题共同组成完整的钩子**。随时可做，建议在成片定稿、标题确定之后做（互文检验需要标题）。封面产物不进渲染管线、不进派单，闭环 = 用户从工作台导出 PNG、自行投放。
+
+## 三条铁律（先记死）
+
+1. **业务分离：通用工艺归本 skill，栏目审美从配置解析。** 本 skill 只持对任何栏目都通用的封面工艺（两阶段交付、T1 字数/结构→布局路由、Prompt 槽位骨架、工作台引擎与自检）。**栏目专属的封面审美（色板与情绪轴、字体选型、概念→意象对照、T1 语气样本、材质与回避清单）从有效栏目配置解析注入**（见下节），**绝不硬编某栏目风格**。未绑封面风格资产的栏目 → 用中性默认兜底。
+2. **两阶段不能合并。** 用户还没抽图就端出工作台 = 盲排（不看背景图排字，等于退回指令稿时代）；工作台的价值就在「因势象形地就着背景图排字」。阶段一交付后**停下等图**。
+3. **审美决策由本 skill 做，工作台只暴露微调面。** 工作台暴露给用户的只有：图层位置 / 字号 / 文案 / 显隐、显式声明的装饰件开关、T1 全局样式滑杆（描边 / 发光 / 既定字色选项）。色板体系、字体选型、布局拓扑、装饰件组合是审美决策——由你按注入的风格资产做出、交付时说明理由；用户想改审美层，**经对话增量改 HTML**（不推倒重来），别让他在工作台里找不存在的控件。
+
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> Prompt 文本与工作台 HTML 只落**用户显式指定目录**，或有工程上下文时落 `<project>/cover/`；
+> **MUST NOT** 把用户媒体（背景图 / 导出的封面 PNG / 任何大文件）复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——压缩背景图时**从原路径读取**，压缩产物直接以 base64 写进工作台 HTML，不留中间副本；
+> 压缩脚本等临时文件一律放系统 temp 且**用完即删**（含中断 / 失败路径）。违者后果 = 用户系统盘被静默吃满（真机事故，非假设）。
+
+## 业务分离：栏目封面风格从哪来（关键）
+
+**封面审美不是本 skill 预设的，是从栏目配置解析出来的。** 解析链路（与 `/gtrk-ai-drama` 的 Style Lock 解析同源）：
+
+1. **定位有效栏目**：用户 `--column <id>` 口头指定的栏目，或本地 config 的 `defaultColumn`；配置文件在 `~/.gitruck/columns/<id>.json`。本 skill 无 gtrk 命令，**直接读这个 JSON 文件**。
+2. **取封面风格条目**：读 `style.skills[]`，取 `produces` **大小写不敏感归一后 `== "cover"`** 的条目。
+   - 命中且未声明 `routing:"none"` → 拿它的 `ref`（指向一个 skill 目录/资源）→ **读该资产的封面风格维度**——色板与情绪轴、字体选型、概念→意象对照、T1 样本、材质与回避清单、平台安全区偏好……**读到什么维度用什么**；缺某维度就只对该维度回落中性默认，不整体放弃注入。
+   - 条目声明 `routing:"none"` → 跳过（退役 / 显式停用标记）。
+   - **无匹配活跃条目** → 用下面「中性默认」。
+3. **注入，不臆造**：读到什么用什么；没读到就中性默认，**绝不凭栏目名猜风格、绝不套用别的栏目的调性**。
+
+> 举例（仅示意解析机制，非硬编）：某栏目配置里有 `{produces:"cover", ref:"…/my-cover-style"}` → 读它的色板表 / 字体决策 / 意象对照注入诊断、Prompt 与工作台。换个栏目、换个 ref，注入的就是另一套审美。**本 skill 正文里不写死任何一套具体风格。**
+
+## 前置与输入
+
+**必要输入（没给齐就问，一次不超过 3 个）**：
+1. **选题 / 视频标题**（互文检验用）。
+2. **T1 封面大字**——用户亲拟的那句话（典型 4~10 字：短语 / 对偶 / 哲句 / 质问）。**T1 是用户的内容，skill 只建议拆分 / 重音处理，不擅自改写**；栏目风格资产带 T1 样本库时可据其语气提候选，仍由用户拍板。
+3. **尺寸集**：缺省 16:9 / 4:3 / 3:4 三种全出，用户按分发面增减。
+
+**可选输入（没给就推导或留空）**：
+- **核心意象 / 概念**（推封面视觉主体用）——没给时从 T1 与视频内容反推；栏目资产有概念→意象对照表就先查表，查不到就现场推一条（推完问用户要不要写进他的对照表）。
+- **情绪基调**——没给自己判；栏目资产有情绪轴按其轴归位。
+- **栏目名（品牌戳）/ 期号**——**用户没给就不放、不编造**，交付时老实标注「未提供，可省略」。
+
+## 两阶段工作流
+
+### 🎨 阶段一：设计诊断 + Prompt
+
+**Step 1 · 诊断展示**（是告知不是提问）：T1 结构诊断（字数 / 逗号对偶 / 关键词可抽性）→ 情绪 / 气质归位 → 视觉意象推导 → 布局配方选择（按 T1 字数路由，见 `references/layout-recipes.md`）→ 色板选择（从栏目色板表选一档并说理由）→ 装饰件决策（用什么 / 不用什么，**不许躲**——画面再好看也要显式决定）。
+
+**Step 2 · 出三尺寸 Prompt**（`references/prompt-templates.md`）：每尺寸一套**英文主版 + 中文辅版**，构图差异显式化（16:9 主体居中两侧留气 / 4:3 饱满可顶三边留对角气口 / 3:4 主体中段上下舒展）。铁律：**不让生图模型渲染中文字**——字全部由阶段二工作台贴，图里只留气息性软留白。
+
+**Step 3 · 阶段一自检**（`references/checklist.md` 阶段一 5 条）→ 结束语明确交棒：「每个尺寸抽到满意的图后传回来，我生成排字工作台」。**停，等图。**
+
+### 🛠️ 阶段二：H5 排字工作台
+
+**Step 4 · 收齐背景图后实例化工作台**（`references/workbench-guide.md` + `assets/workbench-template.html`）：
+1. 按各图宽高比归位到尺寸档（归不上就问，别硬塞）；
+2. 压缩 + base64 注入模板占位符（压缩参数与体积红线见 guide；临时脚本落系统 temp、用完即删）；
+3. 按 **T1 实际字数**实例化 T1 图层（模板 `T1_KEYS` 常量驱动，5 字就 5 个逐字图层，不写死 4 字）；
+4. 注入色板 CSS 变量、T1 字体与发光、装饰件、各图层默认坐标（按布局配方 + 实际画面气口微调）、T2/T5/品牌戳等附加图层初始文案；
+5. 命名 `<T1>_封面排版工作台.html`，落用户指定目录或 `<project>/cover/`。
+
+**Step 5 · 合规检查 + 交付**：占位符零残留 / 三尺寸 DEFAULTS 齐 / T1 初值两处一致 / 浏览器打开控制台零报错、三尺寸切换正常（能验就验）。交付时讲清：工作台能做什么（拖拽 / 方向键 / 滚轮微调 / 文案编辑 / 显隐 / 恢复默认 / 换背景 / 逐尺寸与一键导出）、默认布局按什么选的、审美决策为什么这么做；补一遍阶段二自检 4 条。
+
+**Step 6 · 迭代三分支**：用户自己微调位置字号文案 → 工作台已支持，不用回来；**审美层要改**（换色板 / 换字体 / 去装饰件）→ 对话告诉你，增量改 HTML 重新交付；**图要重抽** → 回阶段一只改相关槽位，其余不动。
+
+## 中性默认（未绑封面风格资产时）
+
+栏目配置里没有 produces=="cover" 的活跃条目时，别停、别硬套别的栏目，用这套克制通用的兜底：
+
+> **中性封面基调**：深色沉稳底 + 高对比单主体构图；T1 用无衬线特黑（系统可得的中文黑体族），纯白字 + 深色细描边、不加发光；无装饰件；Prompt 风格锚点用 cinematic illustration, clean composition, strong single subject，材质串用 subtle film grain；负面词用通用兜底（photorealistic face 之外按题材增删）。
+
+中性默认下**不设色板情绪轴、不设概念→意象对照体系**（那些是栏目资产）。用完顺带提醒：**想要这条栏目有自己的封面视觉 DNA，去 `/gtrk-style-maker` 沉淀一套封面风格资产，登记进栏目配置 `style.skills`（`produces:"cover"`，活跃条目不加 `routing:"none"`）**，之后每期封面自动注入。
+
+## 交付前自检
+
+两阶段各自过 `references/checklist.md`（阶段一：意象与视频核心概念一致 / 情绪与视觉对齐 / 封面-标题互文 / 材质层 / 生成图低级错误提示；阶段二补：字的主视觉重量 / 留字位落点 / 身份锚不编造 / 分发平台安全区按平台适配）。逐条输出结果，不合格直说，不静默跳过。
+
+## 这个 skill 不做什么 → 找谁
+
+- **视频内的 MG 动态图 / 颗粒** → 栏目 MG 生产 skill + `/gtrk-mg`
+- **AI 再现分镜稿** → `/gtrk-ai-drama`
+- **建栏目风格体系（含封面风格资产）** → `/gtrk-style-maker`
+- **成片剪辑 / 拆分 / 铺轨 / 渲染** → 成片 SOP 各步（`/gtrk-oralcut` 起）
+- **替用户抽图、替用户拖字导出** → 做不到也不该做：抽图在外部平台、排字在用户浏览器，这两步是用户检查点，交代清楚后**停下等用户**。