@tikagent/skill-tik-video-editor 1.0.0-preview.1 → 1.0.1-preview.1

package/SKILL.md

@@ -2,7 +2,7 @@
 name: tik-video-editor
 description: 剪辑师通过 tik-video-editor-cli 编辑 project.json 剪辑视频，支持素材导入、时间线编辑、字幕、转场、画面缩放（含平滑推镜）、镜像、翻转、画中画、微裁切、调色、视频去重、按音频波形清理低幅度气口、工程读取与回写、预览和导出。适用于创建或继续修改视频剪辑项目。
 metadata:
-  version: "1.0.0-preview.1"
+  version: "1.0.1-preview.1"
   publish: true
   cliMinVersion: "1.5.0"
   registry: "https://registry.npmjs.org/"
@@ -35,9 +35,12 @@ node "<本技能目录>/scripts/check-update.js" --skill tik-video-editor --skil
 
 ### CLI
 
-- 命令不存在：`npm install -g tik-video-editor-cli@latest`。
-- 已安装：运行 `tik-video-editor-cli version`。`managed` 为 true 时由宿主维护，不要检查也不要升级。否则只比较 `x.y.z`，同号的 `-test` 或 `-rc` 视为达到该正式版。低于 `cliMinVersion` 时运行 `tik-video-editor-cli update --min <cliMinVersion>`。
-- `version` 或 `update` 报 `Unknown command` 时，改为 `npm install -g tik-video-editor-cli@latest`。非托管安装才这样做。
+CLI 的 npm 包是 `@tikagent/video-editor-cli`，安装后的命令仍是 `tik-video-editor-cli`。旧包 `tik-video-editor-cli` 已停止维护。
+
+- 命令不存在：`npm install -g @tikagent/video-editor-cli@latest`。
+- 已安装：运行 `tik-video-editor-cli version`。`managed` 为 true 时由宿主维护，不要检查也不要升级。
+- 非托管且 `name` 不是 `@tikagent/video-editor-cli`，或 `version` 报 `Unknown command`：这是旧包。先运行 `npm uninstall -g tik-video-editor-cli`，再运行 `npm install -g @tikagent/video-editor-cli@latest`，不论版本号高低。
+- 非托管且 `name` 是 `@tikagent/video-editor-cli`：只比较 `x.y.z`，忽略 `-alpha.N`、`-insider.N`、`-preview.N` 后缀。低于 `cliMinVersion` 时运行 `tik-video-editor-cli update --min <cliMinVersion>`。`update` 报 `Unknown command` 时，改为 `npm install -g @tikagent/video-editor-cli@latest`。
 
 ## 环境检查
 
@@ -104,7 +107,7 @@ tik-video-editor-cli <命令> <参数>
 - 传给 `patch-project` / `set-project` 的 JSON 可以用 `--ops` / `--document` 内联，或写入文件后用 `--ops-file` / `--document-file`。文件方式避免命令行参数长度和 shell 引号问题；每一对只能传其中一个。
 
 - `version`：输出 `name`、`version`、`managed`。`managed` 为 true 时由桌面端升级，不要执行 `update`。
-- `update [--min x.y.z]`：升级独立安装。当前版本是 `x.y.z-test.N` 时跟随 `test`，否则跟随 `latest`。桌面托管安装会拒绝。
+- `update [--min x.y.z]`：升级独立安装的 `@tikagent/video-editor-cli`。当前版本带 `-alpha.N`、`-insider.N`、`-preview.N` 时跟随同名 tag，否则跟随 `latest`。桌面托管安装会拒绝。
 - `doctor`：检查 Node、ffmpeg、ffprobe，返回 `ok` 与逐项 `checks`。
 - `download --url <URL> --output <路径>`：通用下载，返回绝对 `path`。
 - `auth status`：校验当前 API Key。返回 `logged_in`；已登录时还返回用户信息。

package/package.json

@@ -1,4 +1,4 @@
 {
   "name": "@tikagent/skill-tik-video-editor",
-  "version": "1.0.0-preview.1"
+  "version": "1.0.1-preview.1"
 }

package/references/editing-guide.md

@@ -30,6 +30,7 @@
   "inPoint": 0,
   "outPoint": 12,
   "disabledTracks": ["A2"],
+  "tracks": [{"id": "V2", "kind": "video", "name": "字幕"}, {"id": "V1", "kind": "video", "name": "主画面"}, {"id": "A2", "kind": "audio"}],
   "media": [
     {
       "id": "m_intro",
@@ -74,11 +75,11 @@
 - `start`：片段在时间线中的起点，单位秒。
 - `in`：源素材入点，单位秒；图片、SVG、文本和调整层通常为 0。
 - `duration`：时间线长度，单位秒。
-- `track`：V1 先绘制，V2、V3 依次覆盖；A1–A4 放独立音频或视频的关联声道。
+- `tracks`：数组按工作台从上到下排列，视频轨在音频轨之前；画面按 `tracks` 从底层向上绘制（默认 `V1` 在底，`V2`、`V3` 依次在上方覆盖），重排轨道后以 `tracks` 顺序为准，不单靠轨道编号判断层级。`track` 引用其中的轨道 ID，A1–A4 放独立音频或视频的关联声道。
 - `linkGroup`：画面与关联音频共享的可选联动 ID。
 - 静态变速必须满足 `in + duration × speed ≤ media.duration`。
 - 切分片段时，前段长度为 `t`；后段的 `start` 增加 `t`，`in` 增加 `t × speed`。
-- 同轨重叠加后一个片段的淡入转场即为交叉淡化。
+- 同轨片段重叠时，CLI 会自动分配新轨。交叉淡化使用上下两轨的重叠片段，并给上层片段加淡入；提交后读回确认实际轨道，不用同轨叠放实现效果。
 - 缺省属性使用默认值；不要为了完整而写入所有默认属性。
 - 修改完整文档时必须基于最新 revision；优先使用 merge-safe patch。
 
@@ -89,7 +90,7 @@
 | 属性 | 默认值 | 说明 |
 | --- | --- | --- |
 | `x`、`y` | 0 | 相对画布中心的像素偏移 |
-| `scale` | 1 | 缩放 |
+| `scale` | 1 | 相对 `fit` 适配结果缩放；编辑器滑块范围 0.1–4 |
 | `rotation` | 0 | 角度 |
 | `opacity` | 1 | 0–1 |
 | `blend` | `normal` | `multiply`、`screen`、`overlay`、`lighter`、`soft-light`、`hard-light`、`color-dodge`、`darken`、`lighten`、`difference` |
@@ -99,7 +100,7 @@
 | 属性 | 默认值 | 说明 |
 | --- | --- | --- |
 | `fit` | `contain` | `contain`、`cover`、`stretch`、`none` |
-| `cropL/R/T/B` | 0 | 各边裁切百分比 |
+| `cropL/R/T/B` | 0 | 源画面各边裁切百分比，先裁切再按 `fit` 适配画布；渲染时限制在 0–95 |
 | `cornerRadius` | 0 | 圆角像素 |
 | `flipH`、`flipV` | false | 水平或垂直翻转 |
 
@@ -108,7 +109,7 @@
 | 属性 | 默认值 | 说明 |
 | --- | --- | --- |
 | `filterPreset` | `none` | `cinematic`、`teal-orange`、`noir`、`vintage`、`faded`、`warm`、`cold`、`pop`、`dreamy`、`retro`、`bw-soft`、`cyberpunk`、`sunset`、`midnight` |
-| `brightness`、`contrast`、`saturation` | 100 | 百分比，100 为中性 |
+| `brightness`、`contrast`、`saturation` | 100 | Canvas/CSS 百分比滤镜，100 为中性；编辑器滑块范围 0–200 |
 | `hue` | 0 | 色相角度 |
 | `temperature`、`tint` | 0 | -100 到 100 |
 | `blur` | 0 | 模糊像素 |
@@ -116,7 +117,7 @@
 | `shake` | 0 | 镜头抖动像素 |
 | `shakeSpeed` | 8 | 抖动频率 |
 | `rgbSplit` | 0 | RGB 分离像素 |
-| `grain` | 0 | 动态颗粒百分比 |
+| `grain` | 0 | 动态颗粒百分比，编辑器滑块范围 0–100；噪声纹理按页面随机生成，预览与独立导出不保证逐像素一致 |
 
 ### 抠像与音频
 
@@ -173,7 +174,7 @@
 
 转场类型：`fade`、`slide-left/right/up/down`、`zoom`、`wipe-left/right/up/down`、`iris`、`spin`、`blur`、`whip`、`glitch`、`pop`。转场叠加在关键帧结果上；fade 同时作用于音频。
 
-调整层使用 `kind: "adjust"`、`mediaId: null`，放在 V2/V3，对下方画面统一应用调色、颗粒、RGB 分离、抖动和透明度。
+调整层使用 `kind: "adjust"`、`mediaId: null`，放在 V2/V3 等更高视频轨，按 `tracks` 顺序对下方合成画面统一应用调色、颗粒、RGB 分离、抖动和透明度。
 
 ## 动画 SVG
 
@@ -194,7 +195,7 @@
 - 绿幕：主体放更高视频轨，设置 `chromaKey`、容差与柔化；背景放 V1，轨道名 `主画面`。
 - 画中画：更高视频轨使用 `scale: 0.35`、位置偏移、圆角和 slide 转场，轨道名和片段名都是 `画中画`。
 - Ken Burns：图片的 scale 从 1 线性到 1.2，并缓慢移动 x 或 y。
-- 交叉淡化：同轨重叠约 1 秒，后片段设置 fade 入场。
+- 交叉淡化：上下两轨重叠约 1 秒，上层片段设置 fade 入场，按 `tracks` 顺序确认层级。
 - 鞭甩切换：前后片段使用约 0.25 秒 whip 转场。
 - 节拍剪辑：把节拍时间写入 markers，并让片段起点对齐 markers。
 - 变速落点：先快后慢的 speed 关键帧在节拍处落到慢速；确认源素材足够。
@@ -235,7 +236,7 @@ tik-video-editor-cli preset --project-id <project_id> --pip auto --pip-scale 0.3
 
 ### 镜像、翻转与裁切
 
-水平镜像是 `flipH`，垂直翻转是 `flipV`。全片镜像时每个 `V1` 视频片段都写；分段镜像按时间顺序交替，切换落在已有片段边界，不把一个片段拆开。`cropL`、`cropR`、`cropT`、`cropB` 是各边裁掉的百分比，四边一起裁，避免把主体推偏。
+水平镜像是 `flipH`，垂直翻转是 `flipV`。全片镜像时每个 `V1` 视频片段都写；分段镜像按时间顺序交替，切换落在已有片段边界，不把一个片段拆开。`cropL`、`cropR`、`cropT`、`cropB` 是各边裁掉的源画面百分比，先裁切再按 `fit` 适配画布，不改变工程分辨率；四边一起裁，避免把主体推偏。
 
 ```json
 {"op":"updateClip","id":"c_1","set":{"props":{"flipH":true,"cropL":1,"cropR":1,"cropT":1,"cropB":1}}}
@@ -261,17 +262,16 @@ tik-video-editor-cli preset --project-id <project_id> --pip auto --pip-scale 0.3
 
 ## 视频去重
 
-去重是把上一节的手法组合起来用，不是另一组参数，也不是另一个命令。用户只点名一种手法时只做该手法。用户只说「去重」时，用轻微放大加热微的调色，不要默认镜像：
+去重是把上一节的手法组合起来用，不是另一组参数，也不是另一个命令。仅在用户明确要求去重时执行，不因完成粗剪而自动应用。
 
-```bash
-tik-video-editor-cli preset --project-id <project_id> --zoom 1.04 --grade subtle --grade-track-name "调色（去重）" --grade-name "轻微调色（去重）"
-```
-
-用户明确要求平滑推镜时，用 `--smooth-zoom 1.05` 代替 `--zoom`，仍然带上 `调色（去重）`。只有用户确认画面没有文字、标识和左右不对称问题时，才额外加 `--mirror alternate`。四边微裁切用 `--crop 1` 或 `2`。要加画中画时再加 `--pip auto --pip-track-name "画中画（去重）" --pip-name "画中画（去重）"`。
-
-这些名字里的「去重」只在这次操作确实是为了去重时才写。用户只是要调色或画中画时，轨道名仍是 `调色`、`画中画`。
-
-去重不改片段顺序、入点、时长、倍速和字幕文本。不声称平台不会判重。商品颜色是卖点时不要用明显滤镜；画面里的文字、标识或不对称款式不要镜像。
+- **手法选择**：用户点名一种或多种手法时只做指定手法，指定参数优先，不补默认组合，也不做随机抽签。用户只说「去重」时，用轻微放大加轻微调色，不要默认镜像：
+  ```bash
+  tik-video-editor-cli preset --project-id <project_id> --zoom 1.04 --grade subtle --grade-track-name "调色（去重）" --grade-name "轻微调色（去重）"
+  ```
+- **组合与进阶参数**：用户明确要求平滑推镜时，用 `--smooth-zoom 1.05` 代替 `--zoom`，仍然带上 `调色（去重）`。四边微裁切用 `--crop 1` 或 `2`。要加画中画时再加 `--pip auto --pip-track-name "画中画（去重）" --pip-name "画中画（去重）"`。这些名字里的「去重」只在这次操作确实是为了去重时才写；常规调色或画中画的轨道名仍是 `调色`、`画中画`。
+- **水平镜像约束**：只有用户指定镜像，或确认画面没有文字、标识和左右不对称问题时，才用 `--mirror all` 或 `--mirror alternate`。分段交替镜像切换落在已有片段边界，不把长片段拆碎；若时间线上只有一个长片段，未获整段镜像确认时跳过镜像并说明原因。
+- **工程与内容保护**：去重不改片段顺序、入点、时长、倍速和字幕文本。指定手法会破坏商品文字、标识、款式、肤色或构图，或商品原色是核心卖点不宜调色时，说明冲突并询问用户，不擅自换成其他手法。片段上已有调好的推镜、裁切或局部调色需要保留时，改用 `patch-project --ops-file` 按需更新对应属性，避免重置已有效果。
+- **能力边界**：当前剪辑工具没有片段级抽帧补帧、随机 `seed` 复现、清元数据、重写标题或无损重封装开关；用户要求这些旧版能力时如实说明不支持，不用变速、降低 FPS 或堆轨道替代。不承诺提高平台原创度、权重或保证不被判重。
 
 ## 音频波形与气口精剪