@gitruck/cli 1.3.7 → 1.3.9

package/CHANGELOG.md

@@ -11,6 +11,29 @@
 
 ## 未发布
 
+## 1.3.8（2026-10-18）
+
+- 新增参考片精读：`gtrk media` 看片命令族（`probe` / `lines` / `frames` / `tile` / `tiles` / `boundaries` / `cut`，纯本地、不计费）。取帧网格下方标出源片秒、时码与正在念的字；`--around` 按台词定位；`boundaries` 给视觉变化候选（机械证据，不是镜头判定）。配套随包 skill `/gtrk-ref-reading`：按「改不改变讲者的位置、大小或可见区域」把参考片的每个视觉系统归到 MG 或合成风格；`/gtrk-style-maker` 的作品逆向可接视频参考。
+- 竖屏 / 方形工程也能做合成：合成舞台随工程画布。`gtrk composite scaffold` 按工程 `.gtrk` 的 `video_size` 写场景 `stage`（缺席按 1920×1080）；`build` 遇场景舞台与工程画布不一致逐颗报错，不缩放了事；机检、静帧与烘焙都按舞台尺寸出，烘焙产物尺寸与缓存身份随舞台；`--abi` 增 `stage:"canvas"`。客户端对竖屏合成的导出支持随下一版客户端发出。
+- 成片图纸缺省带精剪包装（合成层）：口播、解说、美食、配音、旅拍、Vlog 图纸的快速成片在字幕之后、出片之前做一轮合成（auto 选窗口不超过全片 25%，逐窗口复核、构建机检至多三轮，再铺轨烘焙），开工时告知一句；直播切片开工多问一句（缺省不做），长剪短跑前问一次。
+- 修：竖屏 / 方形工程的 MG 颗粒经 `gtrk render` / `gtrk project export` 预渲后被压扁（横胖竖扁、旋转被拉平）。颗粒预渲原先一律按 1280×720 开舞台，云端按「舞台 / 颗粒声明尺寸」非等比挂载；现在舞台按颗粒声明的 `data-width` / `data-height` 等比缩到短边 720（竖屏 1080×1920 → 720×1280，方形 → 720×720），`project export` 登记的颗粒 MOV 尺寸随之对齐。横屏 16:9 颗粒的舞台与缓存键不变，存量缓存照常命中；竖屏 / 方形颗粒升级后首次渲染会重烤一次（旧缓存是压扁的，不复用）。客户端导出剪映 / PR 的颗粒预渲需客户端同步跟进（fix-particle-capture-follows-declared-aspect）。
+- 修：`gtrk tool image_matting` 处理带 EXIF 方向标记的手机照片（如 Orientation=6），产物转了 90°。上传前先按显示方向摆正（原图不动，摆正件按原图指纹缓存在 `~/.gitruck/audio-cache/`）；无方向标记或非 JPEG 照旧原文件直传；缺 ffmpeg 等摆正失败时提示后按原像素上传（fix-image-matting-exif-orientation）。
+- `gtrk-mg` skill / 参考文档改准画幅口径：颗粒画幅须等于工程画布，竖屏可用；registry 中性块仍只有 1920×1080。
+- 修：竖屏 / 方形工程取文字模板（`gtrk mg fetch --source text`）恒得 1920×1080 颗粒，铺进去被拉伸。`--canvas` 原先在这条路上只被收下、不生效；现在按目标画幅编：派单模式缺省取工程 `.gtrk` 的 `video_size`（显式 `--canvas` 与工程不符当场拒，找不到工程文件时按 1920×1080 编并提示），独立模式按 `--canvas`。`gtrk mg compile` 新增 `--canvas`，重置颗粒时缺省沿用颗粒自己的画幅，`--remote` 同样把画幅交给服务端。横屏工程与不给 `--canvas` 时产物不变（fix-text-template-canvas-not-compiled）。
+- 修：画幅比例不对的 MG 颗粒（如竖屏工程里声明 1920×1080 的手写颗粒或旧颗粒）照样能铺进工程，渲染时被拉伸，全程不报错。`gtrk mg --project`（铺轨，含 `--lint-only`）与 `gtrk mg lint --dispatch / --project` 现在按工程 `.gtrk` 的 `video_size` 比对颗粒声明的比例：跨比例判 `1-canvas-match` 致命、不铺；同比例不同尺寸（如 4K 横屏工程里的 1920×1080 颗粒）照常放行，比例差 7% 以内视为同比例（DCI 4K 4096×2160 这类 17:9 工程里的 16:9 颗粒放行，接受 6.7% 横向拉伸）。工程缺 `.gtrk` 或 `video_size` 不合法时不比对并提示一句。裸 `gtrk mg lint <file>` 不变（fix-mg-lay-lint-reads-project-canvas）。
+- 修：竖屏 / 方形工程派单取 registry 中性块（`gtrk mg fetch --pick <块> --slot <beat> --project <dir>`）照样下载并落一颗 1920×1080 颗粒，要到 lint / 铺轨才被拦。现在按工程 `.gtrk` 的 `video_size` 比例判（同上，容差 7%）：比例不是 16:9 在下载前就拒、不落盘，报错指路 `--source text`（文字模板按工程画幅编）或栏目 skill。横屏 16:9 工程（含 4K）与 DCI 17:9 工程照取、产物不变；独立模式（`--as`）不读工程；找不到 `.gtrk` 或 `video_size` 不合法时不比对、照取并提示一句（fix-mg-fetch-registry-reads-project-canvas）。
+- 修：`gtrk composite bake --progress jsonl` 的取消恰好落在工作页打开出片台时，要约 24 秒才报 `cancelled` 并退出（浏览器已被结束，打开页面却仍按每轮 8 秒等到期限）；现在浏览器一退出即放弃，取消照常几秒内收尾。开烤前建工作目录那一段也有进度行了（原先这段可能超过 1 秒没有输出）；装渲染组件期间关闭 stdin，装完即按取消收尾（原先会漏掉、照常烤完）（add-composite-bake）。
+- 修：`gtrk matrix` 铺轨三处坑：
+  - `clip_id` 带来源层（`<beat>-<layer>-broll/bedfill/gapfill-…`），通用层与本地层同 beat 同序号不再撞名，`gtrk patch --clip` 可直接寻址；老工程重铺不受影响。
+  - 口播（fill 形态）工程里片段间 1–2 帧的缝、锚点前短于 1.2 秒的空档，在素材余量内并入相邻片段，不再闪黑；余量不够仍补黑，并逐段告警。
+  - `gtrk matrix --online` 收尾零候选时不再覆盖盘上已有的 plan（结果带 `plan_kept`）。
+- 合成层在英文口播片上更好用：
+  - 场景锚点的关键词照句子原文写即可：匹配时关键词与句子都忽略空格、标点与大小写，英文按整词（`"cold brew"` 直接写，`tea` 不再先命中 `teas`）；找不到时报错打印句子原文。
+  - `gtrk composite plan` 的「建议画面」识别英文的对照（unlike / but / instead of …）、列举（逗号列举，或转写不带标点时的一长串并列）、数字与分点；其他语种不做文字信号，审稿稿里写明。中文判定不变。
+  - `gtrk composite lay` 的回执改为当前出片口径：客户端（1.2.13 起）原生导出与剪映 / Pr 导出、`gtrk render`、`gtrk project export` 都先在本机烤合成，失败段按粗剪出画。
+  - `/gtrk-composite` 场景速查写明：工具箱只给舞台直接子元素定位，容器里的元素自己写 `position:absolute` 或加 `.abs`。
+- `gtrk composite lint` 新增 `unpositioned-offset`：容器里的元素写了 `left` / `top` 偏移、却没写 `position:absolute` 也没加 `.abs`（偏移不生效、挤成一列）时报出来，点名元素与容器。只在 lint 时检查，颗粒与烘焙缓存不变、已烤的颗粒不用重烤。
+
 ## 1.3.7（2026-10-18）
 
 - 新增匿名使用统计：每条命令结束时记下命令名（注册名，不含任何参数）、成败、失败时的错误码或分类、耗时区间与调用方（终端或 agent 名称），用于了解命令热度、失败率与版本铺开情况。

package/README.en.md

@@ -10,9 +10,9 @@
 <p>
 <a href="#demo">Demo</a> ·
 <a href="#quick-start">Quick start</a> ·
-<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">Tutorials</a> ·
-<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
-<a href="docs/development.en.md">Develop</a> ·
+<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">Tutorials</a> ·
+<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
+<a href="docs/development.en.md">Develop</a> ·
 <a href="README.md">简体中文</a>
 </p>
 
@@ -157,47 +157,48 @@ flowchart LR
 
 **Conversations currently happen in your own agent; the desktop client has no built-in AI chat.** Review and refine the project in the client after your agent changes it, or render with `gtrk render`. Motion graphics that require cloud rendering are billed separately; cached renders can be reused.
 
-The three-format rough-cut output and the export of a fully packaged project have different support boundaries. The [workflow guide](docs/workflow.en.md) explains where each deliverable opens and which effects need rendering.
-
-After refining a `.gtrk` project in the client, use `gtrk project export --project <dir>` to produce Jianying, Premiere XML, FCPXML or OTIO while preserving the refined timeline; do not rerun `oralcut`, which rebuilds the rough cut. Export renders MG particles into the NLE package: structural export is billed per task, and particles missing from the shared cache are billed by the minute. `project init` remains zero-credit. When only `gtrk` is requested, the native `beat_track` is kept and particle rendering is skipped.
-
-## gtrk + AI Drama Desk: from storyboard to editable clips
-
-For AI-generated story scenes, connect [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) to the same project workflow. The responsibilities stay separate:
-
-| Component | What it does | Output |
-| --- | --- | --- |
-| `gtrk CLI` | Understands the request in your agent, orchestrates workflows and manages `.gtrk` projects | An editable video project |
-| `AI Drama Desk` | Imports storyboards, manages characters and styles, generates keyframes / I2V clips and exports a handoff package | A `return-v1` clip package + `manifest` |
-| `gtrk ai-drama lay` | Places exported clips back into the project by beat windows | A dedicated AI video track |
-
-The typical path looks like this:
-
-```text
-storyboard.md → AI Drama Desk → references / keyframes / I2V → return-v1 package
-                                                                  ↓
-                                      gtrk ai-drama lay → .gtrk project → client refinement
-```
-
-The desk supports mock, cloud and optional local ComfyUI engines. Start with a zero-GPU, zero-key rehearsal, then enable a real engine when needed. For an existing desk project, the CLI only needs the **API base and project ID**; it does not scan the repository:
-
-```bash
-gtrk ai-drama lay --project ./my-video --desk-project <project-id>
-```
-
-→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI drama tutorial](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [command reference](docs/reference.en.md#command-reference)
-
-## Use just one tool, too
+The three-format rough-cut output and the export of a fully packaged project have different support boundaries. The [workflow guide](docs/workflow.en.md) explains where each deliverable opens and which effects need rendering.
+
+After refining a `.gtrk` project in the client, use `gtrk project export --project <dir>` to produce Jianying, Premiere XML, FCPXML or OTIO while preserving the refined timeline; do not rerun `oralcut`, which rebuilds the rough cut. Export renders MG particles into the NLE package: structural export is billed per task, and particles missing from the shared cache are billed by the minute. `project init` remains zero-credit. When only `gtrk` is requested, the native `beat_track` is kept and particle rendering is skipped.
+
+## gtrk + AI Drama Desk: from storyboard to editable clips
+
+For AI-generated story scenes, connect [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) to the same project workflow. The responsibilities stay separate:
+
+| Component | What it does | Output |
+| --- | --- | --- |
+| `gtrk CLI` | Understands the request in your agent, orchestrates workflows and manages `.gtrk` projects | An editable video project |
+| `AI Drama Desk` | Imports storyboards, manages characters and styles, generates keyframes / I2V clips and exports a handoff package | A `return-v1` clip package + `manifest` |
+| `gtrk ai-drama lay` | Places exported clips back into the project by beat windows | A dedicated AI video track |
+
+The typical path looks like this:
+
+```text
+storyboard.md → AI Drama Desk → references / keyframes / I2V → return-v1 package
+                                                                  ↓
+                                      gtrk ai-drama lay → .gtrk project → client refinement
+```
+
+The desk supports mock, cloud and optional local ComfyUI engines. Start with a zero-GPU, zero-key rehearsal, then enable a real engine when needed. For an existing desk project, the CLI only needs the **API base and project ID**; it does not scan the repository:
+
+```bash
+gtrk ai-drama lay --project ./my-video --desk-project <project-id>
+```
+
+→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI drama tutorial](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [command reference](docs/reference.en.md#command-reference)
+
+## Use just one tool, too
 
 | What you need | Start here |
 | --- | --- |
 | Matting, denoising, vocal separation, upscaling, interpolation, image motion or video dubbing | [Toolbox](https://hocassian.feishu.cn/wiki/Uh19wAphailtSqkt6jsclW0Rnie) · `gtrk tool list` |
 | Covers in multiple aspect ratios | [Cover workflow](https://hocassian.feishu.cn/wiki/AD5bwUAHris75vkWl4DcsvPJntb) |
 | A spectrum video for a song | [Music visualizer Skill](skills/gtrk-music-visualizer/SKILL.md) |
+| Break down a reference video's packaging and pacing | [Reference-reading Skill](skills/gtrk-ref-reading/SKILL.md) · `gtrk media` |
 | A visual style for your show | [Style-maker Skill](skills/gtrk-style-maker/SKILL.md) |
 | Third-party animation, typography or creative Skills | [Skill map](https://hocassian.feishu.cn/wiki/SxRtwJ0G7inTbQkwckFcZmClnrd) |
 
-## FAQ
+## FAQ
 
 **Do I need to code?**
 
@@ -215,21 +216,21 @@ Talking-head and long-to-short project workflows keep the original locally and u
 
 The CLI runs across platforms. The Windows client provides visual preview and refinement; the CLI can render existing projects. Jianying and Premiere support depends on the installed software and the project format.
 
-**Skills are missing, or a task failed. What now?**
-
-Open a new agent session and run `gtrk doctor`. Use `gtrk skills install` to refresh Skills. If a task already has an ID, recover its results before submitting it again. See [workflow and troubleshooting](docs/workflow.en.md).
-
-## Star History
-
-<a href="https://star-history.com/#Gitruck/cli&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-  </picture>
-</a>
-
-## Documentation and contributions
+**Skills are missing, or a task failed. What now?**
+
+Open a new agent session and run `gtrk doctor`. Use `gtrk skills install` to refresh Skills. If a task already has an ID, recover its results before submitting it again. See [workflow and troubleshooting](docs/workflow.en.md).
+
+## Star History
+
+<a href="https://star-history.com/#Gitruck/cli&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+  </picture>
+</a>
+
+## Documentation and contributions
 
 [Full tutorials](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [Workflow](docs/workflow.en.md) · [Command reference](docs/reference.en.md) · [Development](docs/development.en.md) · [Changelog](CHANGELOG.md)
 

package/README.md

@@ -10,9 +10,9 @@
 <p>
 <a href="#demo">观看演示</a> ·
 <a href="#quick-start">快速开始</a> ·
-<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">使用教程</a> ·
-<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
-<a href="docs/development.md">开发文档</a> ·
+<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">使用教程</a> ·
+<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
+<a href="docs/development.md">开发文档</a> ·
 <a href="README.en.md">English</a>
 </p>
 
@@ -157,47 +157,48 @@ flowchart LR
 
 **当前对话入口在你自己的 Agent 中，客户端没有内置 AI 对话框。** Agent 修改工程后，在客户端查看效果、继续精修；也可以用 `gtrk render` 渲染成片。需要云端渲染的动态图会单独计费，缓存可复用。
 
-粗剪阶段的三端工程，与完整包装后的导出支持范围不同；[工作流指南](docs/workflow.md)说明每种交付物在哪打开、哪些效果需要渲染。
-
-客户端精修 `.gtrk` 后，用 `gtrk project export --project <目录>` 导出剪映、Premiere XML、FCPXML 或 OTIO，保留精修时间线；不要重跑 `oralcut`，否则会重新生成粗剪。导出会把 MG 颗粒预渲进 NLE 工程，结构导出按次计费，未命中共享缓存的颗粒按分钟计费；`project init` 仍是 0 积分。只选 `gtrk` 时会保留原生 `beat_track` 并自动跳过颗粒预渲。
-
-## gtrk + AI Drama Desk：从分镜到可回轨片段
-
-如果你的素材不是实拍，而是希望把一份分镜稿变成 AI 情景片段，可以把 [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) 接到同一条工程链里。两者分工很清楚：
-
-| 组件 | 负责什么 | 产物 |
-| --- | --- | --- |
-| `gtrk CLI` | 在 Agent 中理解需求、组织工作流、管理 `.gtrk` 工程 | 可继续精修的视频工程 |
-| `AI Drama Desk` | 导入分镜稿、管理角色与画风、生成 keyframe / I2V 片段、导出回轨包 | `return-v1` 片段包 + `manifest` |
-| `gtrk ai-drama lay` | 把工作台导出的片段按 beat 区间铺回工程 | 独立 AI 视频轨 |
-
-典型路径是：
-
-```text
-分镜稿 md → AI Drama Desk → 角色参考图 / keyframe / I2V → return-v1 导出包
-                                                          ↓
-                                      gtrk ai-drama lay → .gtrk 工程 → 客户端精修
-```
-
-工作台支持 mock、云端出口和可选的本地 ComfyUI；你可以先零 GPU、零 Key 跑通流程，再按需要启用真实引擎。已有工作台项目时，CLI 只需要 **API 地址 + 项目 ID**，不需要扫描仓库目录：
-
-```bash
-gtrk ai-drama lay --project ./my-video --desk-project <project-id>
-```
-
-→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI 漫剧教程](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [命令参考](docs/reference.md#命令参考)
-
-## 成片之外，也能只做一件事
+粗剪阶段的三端工程，与完整包装后的导出支持范围不同；[工作流指南](docs/workflow.md)说明每种交付物在哪打开、哪些效果需要渲染。
+
+客户端精修 `.gtrk` 后，用 `gtrk project export --project <目录>` 导出剪映、Premiere XML、FCPXML 或 OTIO，保留精修时间线；不要重跑 `oralcut`，否则会重新生成粗剪。导出会把 MG 颗粒预渲进 NLE 工程，结构导出按次计费，未命中共享缓存的颗粒按分钟计费；`project init` 仍是 0 积分。只选 `gtrk` 时会保留原生 `beat_track` 并自动跳过颗粒预渲。
+
+## gtrk + AI Drama Desk：从分镜到可回轨片段
+
+如果你的素材不是实拍，而是希望把一份分镜稿变成 AI 情景片段，可以把 [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) 接到同一条工程链里。两者分工很清楚：
+
+| 组件 | 负责什么 | 产物 |
+| --- | --- | --- |
+| `gtrk CLI` | 在 Agent 中理解需求、组织工作流、管理 `.gtrk` 工程 | 可继续精修的视频工程 |
+| `AI Drama Desk` | 导入分镜稿、管理角色与画风、生成 keyframe / I2V 片段、导出回轨包 | `return-v1` 片段包 + `manifest` |
+| `gtrk ai-drama lay` | 把工作台导出的片段按 beat 区间铺回工程 | 独立 AI 视频轨 |
+
+典型路径是：
+
+```text
+分镜稿 md → AI Drama Desk → 角色参考图 / keyframe / I2V → return-v1 导出包
+                                                          ↓
+                                      gtrk ai-drama lay → .gtrk 工程 → 客户端精修
+```
+
+工作台支持 mock、云端出口和可选的本地 ComfyUI；你可以先零 GPU、零 Key 跑通流程，再按需要启用真实引擎。已有工作台项目时，CLI 只需要 **API 地址 + 项目 ID**，不需要扫描仓库目录：
+
+```bash
+gtrk ai-drama lay --project ./my-video --desk-project <project-id>
+```
+
+→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI 漫剧教程](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [命令参考](docs/reference.md#命令参考)
+
+## 成片之外，也能只做一件事
 
 | 想做什么 | 从这里开始 |
 | --- | --- |
 | 抠像、降噪、人声分离、超分、补帧、图片运镜、视频译制 | [单点工具箱](https://hocassian.feishu.cn/wiki/Uh19wAphailtSqkt6jsclW0Rnie) · `gtrk tool list` |
 | 做一套多尺寸封面 | [封面工作流](https://hocassian.feishu.cn/wiki/AD5bwUAHris75vkWl4DcsvPJntb) |
 | 把一首歌做成频谱视频 | [音乐可视化 Skill](skills/gtrk-music-visualizer/SKILL.md) |
+| 拆解一条参考视频的包装与节奏 | [参考片精读 Skill](skills/gtrk-ref-reading/SKILL.md) · `gtrk media` |
 | 给自己的栏目建立视觉风格 | [风格体系 Skill](skills/gtrk-style-maker/SKILL.md) |
 | 接入第三方动画、排版或创作 Skills | [Skill 地图](https://hocassian.feishu.cn/wiki/SxRtwJ0G7inTbQkwckFcZmClnrd) |
 
-## 常见问题
+## 常见问题
 
 **需要会写代码吗？**
 
@@ -215,21 +216,21 @@ CLI 代码采用 MIT 许可证；同合云能力按对应规则计费，你使
 
 CLI 可以跨平台执行。Windows 客户端用于可视化预览与精修；已有工程也可通过 CLI 渲染。剪映、Premiere 的使用取决于对应软件和工程格式的支持情况。
 
-**安装后找不到 Skills，或任务出错怎么办？**
-
-重新打开 Agent 会话，运行 `gtrk doctor` 检查环境；补装用 `gtrk skills install`。任务已有 ID 时优先恢复结果，避免重新提交云端任务。详见[工作流与排障](docs/workflow.md)。
-
-## Star History
-
-<a href="https://star-history.com/#Gitruck/cli&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-  </picture>
-</a>
-
-## 文档与参与
+**安装后找不到 Skills，或任务出错怎么办？**
+
+重新打开 Agent 会话，运行 `gtrk doctor` 检查环境；补装用 `gtrk skills install`。任务已有 ID 时优先恢复结果，避免重新提交云端任务。详见[工作流与排障](docs/workflow.md)。
+
+## Star History
+
+<a href="https://star-history.com/#Gitruck/cli&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+  </picture>
+</a>
+
+## 文档与参与
 
 [完整教程](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [工作流](docs/workflow.md) · [命令参考](docs/reference.md) · [开发文档](docs/development.md) · [更新日志](CHANGELOG.md)
 

package/assets/composite-kit/kit.css

@@ -1,57 +1,57 @@
-/* 合成颗粒工具箱 composite-kit@1 的公共样式（构建时内联）。
- * 中性：配色、字体、纹理一律走变量，由栏目 / 工程风格（composite/theme.css，构建时接在本文件之后）覆盖。
- * 变量：--bg 底色 / --bg2 次底色 / --ink 正文 / --muted 次要文字 / --line 分隔线 /
- *       --accent 强调 / --accent2 / --accent3 辅助色 / --alert 警示 / --font 正文字体 / --font-serif 标题字体。 */
-html, body { margin: 0; height: 100%; overflow: hidden; background: transparent; }
-#stage {
-  position: absolute; left: 0; top: 0; width: 1920px; height: 1080px; transform-origin: 0 0; overflow: hidden;
-  --bg: #F4F4F2; --bg2: #E6E6E2; --ink: #1D1D1F; --muted: #6B6B70; --line: #CFCFCB;
-  --accent: #2F6FDE; --accent2: #2E8B57; --accent3: #4A5568; --alert: #D14343;
-  --font: "Noto Sans SC", "Source Han Sans CN", "Microsoft YaHei", "PingFang SC", sans-serif;
-  --font-serif: "Noto Serif SC", "Source Han Serif SC", "Source Han Serif", "SimSun", serif;
-  font-family: var(--font); color: var(--ink);
-}
-#stage > *, #stage .abs { position: absolute; box-sizing: border-box; }
-[data-slot] { visibility: hidden !important; }
-.serif { font-family: var(--font-serif); }
-.bed { left: 0; top: 0; width: 1920px; height: 1080px; background: var(--bg); }
-.bed.dark { background: radial-gradient(ellipse at 30% 35%, #2A2A2E 0%, #141416 70%); }
-/* 槽位装饰：阴影在下（back），描边在上（front）。描边只给最上层的画面——下层画面的 front 描边会压到上层画面上 */
-.shadow { border-radius: 18px; box-shadow: 0 18px 50px rgba(0, 0, 0, .22), 0 3px 10px rgba(0, 0, 0, .12); background: #000; }
-.shadow.round { border-radius: 50%; }
-.frame { border: 3px solid var(--ink); border-radius: 18px; }
-.frame.round { border-radius: 50%; }
-.frame.thin { border-width: 2px; }
-.frame.light { border-color: rgba(255, 255, 255, .85); }
-.ring { border: 4px solid var(--ink); border-radius: 50%; }
-.ring.light { border-color: rgba(255, 255, 255, .9); }
-/* 字幕：颗粒接管字幕后自己排 */
-.cap {
-  left: 160px; width: 1600px; top: 958px; height: 70px; text-align: center; white-space: nowrap;
-  font-size: 44px; font-weight: 600; letter-spacing: .02em; color: var(--ink); line-height: 70px;
-}
-.cap b { color: var(--accent); font-weight: 800; }
-.cap.dark { color: #fff; text-shadow: 0 2px 12px rgba(0, 0, 0, .55); }
-.cap.dark b { color: var(--accent); }
-/* 文字 */
-.tag { font-size: 26px; letter-spacing: .2em; color: var(--muted); white-space: nowrap; }
-.kicker { font-size: 28px; font-weight: 700; letter-spacing: .28em; color: var(--accent); white-space: nowrap; }
-.h1 { font-size: 96px; font-weight: 900; line-height: 1.12; white-space: nowrap; }
-.h2 { font-size: 64px; font-weight: 900; line-height: 1.2; white-space: nowrap; }
-.h3 { font-size: 44px; font-weight: 700; line-height: 1.3; white-space: nowrap; }
-.body { font-size: 34px; line-height: 1.5; color: var(--ink); }
-.num { font-size: 30px; font-weight: 800; color: var(--accent); letter-spacing: .1em; }
-.pill { height: 54px; padding: 0 26px; border-radius: 27px; font-size: 28px; font-weight: 700; line-height: 54px; white-space: nowrap; }
-.rule { height: 3px; background: var(--ink); }
-.card { background: #FFFFFF; border-radius: 22px; box-shadow: 0 10px 30px rgba(0, 0, 0, .08); }
-.stamp { font-size: 72px; font-weight: 900; color: var(--alert); border: 6px solid var(--alert); border-radius: 14px; padding: 6px 26px; white-space: nowrap; }
-/* 对话气泡（字幕变成一串对话时用） */
-.bubble {
-  height: 76px; padding: 0 30px; border-radius: 38px 38px 10px 38px; background: #FFFFFF; font-size: 32px; line-height: 76px;
-  white-space: nowrap; color: var(--ink); box-shadow: 0 6px 18px rgba(0, 0, 0, .08); border: 2px solid transparent;
-}
-.bubble b { color: var(--accent); font-weight: 700; }
-.bubble.now { border-color: var(--accent); }
-/* 画面标签：贴在画面左上角，说明这张画面对应台词里的哪个词 */
-.ptag { height: 46px; padding: 0 20px; border-radius: 23px; background: rgba(20, 20, 22, .74); color: #fff; font-size: 26px; font-weight: 700; line-height: 46px; letter-spacing: .06em; white-space: nowrap; }
-.ptag.warm { background: var(--accent); }
+/* 合成颗粒工具箱 composite-kit@1 的公共样式（构建时内联）。
+ * 中性：配色、字体、纹理一律走变量，由栏目 / 工程风格（composite/theme.css，构建时接在本文件之后）覆盖。
+ * 变量：--bg 底色 / --bg2 次底色 / --ink 正文 / --muted 次要文字 / --line 分隔线 /
+ *       --accent 强调 / --accent2 / --accent3 辅助色 / --alert 警示 / --font 正文字体 / --font-serif 标题字体。 */
+html, body { margin: 0; height: 100%; overflow: hidden; background: transparent; }
+#stage {
+  position: absolute; left: 0; top: 0; width: 1920px; height: 1080px; transform-origin: 0 0; overflow: hidden; /* 实际尺寸由 kit.js 按舞台写回 */
+  --bg: #F4F4F2; --bg2: #E6E6E2; --ink: #1D1D1F; --muted: #6B6B70; --line: #CFCFCB;
+  --accent: #2F6FDE; --accent2: #2E8B57; --accent3: #4A5568; --alert: #D14343;
+  --font: "Noto Sans SC", "Source Han Sans CN", "Microsoft YaHei", "PingFang SC", sans-serif;
+  --font-serif: "Noto Serif SC", "Source Han Serif SC", "Source Han Serif", "SimSun", serif;
+  font-family: var(--font); color: var(--ink);
+}
+#stage > *, #stage .abs { position: absolute; box-sizing: border-box; }
+[data-slot] { visibility: hidden !important; }
+.serif { font-family: var(--font-serif); }
+.bed { left: 0; top: 0; width: 100%; height: 100%; background: var(--bg); }
+.bed.dark { background: radial-gradient(ellipse at 30% 35%, #2A2A2E 0%, #141416 70%); }
+/* 槽位装饰：阴影在下（back），描边在上（front）。描边只给最上层的画面——下层画面的 front 描边会压到上层画面上 */
+.shadow { border-radius: 18px; box-shadow: 0 18px 50px rgba(0, 0, 0, .22), 0 3px 10px rgba(0, 0, 0, .12); background: #000; }
+.shadow.round { border-radius: 50%; }
+.frame { border: 3px solid var(--ink); border-radius: 18px; }
+.frame.round { border-radius: 50%; }
+.frame.thin { border-width: 2px; }
+.frame.light { border-color: rgba(255, 255, 255, .85); }
+.ring { border: 4px solid var(--ink); border-radius: 50%; }
+.ring.light { border-color: rgba(255, 255, 255, .9); }
+/* 字幕：颗粒接管字幕后自己排 */
+.cap {
+  left: 160px; width: 1600px; top: 958px; height: 70px; text-align: center; white-space: nowrap;
+  font-size: 44px; font-weight: 600; letter-spacing: .02em; color: var(--ink); line-height: 70px;
+}
+.cap b { color: var(--accent); font-weight: 800; }
+.cap.dark { color: #fff; text-shadow: 0 2px 12px rgba(0, 0, 0, .55); }
+.cap.dark b { color: var(--accent); }
+/* 文字 */
+.tag { font-size: 26px; letter-spacing: .2em; color: var(--muted); white-space: nowrap; }
+.kicker { font-size: 28px; font-weight: 700; letter-spacing: .28em; color: var(--accent); white-space: nowrap; }
+.h1 { font-size: 96px; font-weight: 900; line-height: 1.12; white-space: nowrap; }
+.h2 { font-size: 64px; font-weight: 900; line-height: 1.2; white-space: nowrap; }
+.h3 { font-size: 44px; font-weight: 700; line-height: 1.3; white-space: nowrap; }
+.body { font-size: 34px; line-height: 1.5; color: var(--ink); }
+.num { font-size: 30px; font-weight: 800; color: var(--accent); letter-spacing: .1em; }
+.pill { height: 54px; padding: 0 26px; border-radius: 27px; font-size: 28px; font-weight: 700; line-height: 54px; white-space: nowrap; }
+.rule { height: 3px; background: var(--ink); }
+.card { background: #FFFFFF; border-radius: 22px; box-shadow: 0 10px 30px rgba(0, 0, 0, .08); }
+.stamp { font-size: 72px; font-weight: 900; color: var(--alert); border: 6px solid var(--alert); border-radius: 14px; padding: 6px 26px; white-space: nowrap; }
+/* 对话气泡（字幕变成一串对话时用） */
+.bubble {
+  height: 76px; padding: 0 30px; border-radius: 38px 38px 10px 38px; background: #FFFFFF; font-size: 32px; line-height: 76px;
+  white-space: nowrap; color: var(--ink); box-shadow: 0 6px 18px rgba(0, 0, 0, .08); border: 2px solid transparent;
+}
+.bubble b { color: var(--accent); font-weight: 700; }
+.bubble.now { border-color: var(--accent); }
+/* 画面标签：贴在画面左上角，说明这张画面对应台词里的哪个词 */
+.ptag { height: 46px; padding: 0 20px; border-radius: 23px; background: rgba(20, 20, 22, .74); color: #fff; font-size: 26px; font-weight: 700; line-height: 46px; letter-spacing: .06em; white-space: nowrap; }
+.ptag.warm { background: var(--accent); }