@ninkch/dsh-artcraft 0.2.10 → 0.3.0

package/skills/artcraft-color-light/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: artcraft-color-light
+description: 影调与调色决策——一级（曝光/对比/白平衡/饱和）与二级（HSL 限定/肤色/局部）的作业顺序与判据、跨镜头一致性（FilmCraft lumetri.applyMatch、LightCraft develop 分区）、示波器客观判读、Log/HDR 到交付空间的转换、风格 look 与题材表达、常见偏色与过饱和的排查。映射到 LightCraft 122 个 develop 控制、FilmCraft lumetri/lut/scopes、PhotoCraft image.adjustments 与 filter。
+---
+
+# 影调与调色
+
+目标顺序永远是：**先统一（一致性）→ 再修正（技术）→ 后风格（创作）**。跳过前两步直接套 LUT，是全片跳色的根源。
+
+## 一、一级校色：固定顺序与判据
+
+| 顺序 | 调整 | 判据（客观） | 常见错 |
+|---|---|---|---|
+| 1 | 曝光 / 黑位 / 白位 | 波形图：黑位不贴底、白位不削顶 | 黑位抬高→发灰；白位削顶→死白 |
+| 2 | 对比 / 曲线 | 直方图分布，主体落在中段 | 对比过猛→暗部糊 |
+| 3 | 白平衡（色温/色调） | 矢量示波器：肤色线附近 | 偏黄/偏青不察 |
+| 4 | 饱和 / 自然饱和度 | 矢量示波器不越界 | 过饱和→溢出结块 |
+
+**LightCraft 落点（122 控制 / 14 分区）**——标准冲洗顺序：
+
+```
+profile.amount → wb.temp / wb.tint → light.exposure / light.contrast /
+light.highlights / light.shadows / light.whites / light.blacks →
+curve.*（highlights/lights/darks/shadows + splitShadows/splitMid/splitHighlights）→
+color.vibrance / color.saturation → grading.*（阴影/中间调/高光/全局 的 hue·sat·lum）→
+mixer.*（8 色相 × hue/sat/lum，用于定点修色）→
+detail.*（锐化 4 + 降噪 7）→ optics.*（畸变/暗角/去边/色差）→
+geometry.*（透视/旋转/裁切）→ effects.texture/clarity/dehaze → grain.* → vignette.*
+```
+
+**FilmCraft 落点**：`lumetri.setSection {section:"basic|creative|curves|wheels"}`、`lumetri.setInputLut`（技术 LUT：Log→709）、`lumetri.setLook`（创意 Look）、`lumetri.applyPreset`、`presets.save/apply`（自制预设跨镜复用）。
+
+**PhotoCraft 落点**：`image.adjustments.exposure/levels/curves/vibrance/desaturate`；RAW 走 `filter.cameraRaw`；批量一致性用 `actions.record → actions.save → file.automate.batch`。
+
+## 二、二级校色与局部
+
+| 手法 | 何时用 | 落点 |
+|---|---|---|
+| HSL 限定（定点修色） | 只改某色相（如把草地压黄） | LightCraft `mixer.<color>.hue/sat/lum`；PhotoCraft `filter.*` 选择性 |
+| 肤色优先 | 任何风格化前先护住肤色 | LightCraft `mixer.orange.*` + `grading.midtones.*`；矢量示波器核对 |
+| 分区调色 | 阴影/中间调/高光分别偏移 | LightCraft `grading.shadows/midtones/highlights.*`；FilmCraft `wheels`（三路色轮） |
+| 局部遮罩 | 只调人脸/天空/背景 | LightCraft `mask.*`（12 条）+ `develop` 局部；FilmCraft `masks.*`（含 `masks.track` 跟踪） |
+| 分离色调 | 阴影冷/高光暖的"电影感" | LightCraft `grading.blending` + `balance`；`curve.splitShadows/splitMid/splitHighlights` |
+
+## 三、跨镜头一致性（**先做这一步**）
+
+1. **参考镜头**：选一个曝光与白平衡最准的镜头做基准。
+2. **匹配**：FilmCraft `lumetri.applyMatch {clip, referenceTime|referenceFrame|referenceTimecode, faceDetection}`——按参考帧匹配，人脸优先。
+3. **锁定配方**：把成品参数存成预设（`presets.save` / LightCraft `preset.create`），后续镜头 `applyPreset` 复用；LightCraft 可 `history.*` 回溯与 `version.*` 留版。
+4. **核对**：`scopes.read {scopes:["waveform","parade","histogram","vectorscopeYuv",…]}` 横向比对，逐镜读数一致。
+
+**一致性三件套**：参考帧匹配 + 参数预设 + 示波器读数。
+
+## 四、Log / HDR / 色彩空间
+
+- 先查：`color.spaces`（FilmCraft）列出可用色彩空间；交付前明确目标空间（Rec.709 交付，Log 只作中间）。
+- 技术转换：`lumetri.setInputLut`（输入 LUT，如 S-Log3→709）；不用外部工具。
+- HDR→SDR：LightCraft 用 `hdr.maxEv / hdr.sdrBrightness / hdr.sdrContrast / hdr.sdrHighlights / hdr.sdrShadows / hdr.sdrWhites / hdr.sdrClarity`（7 个映射控制）；FilmCraft 走 `lumetri` + `lut` 并核 `scopes.read`。
+- LUT 资产：`lut.import/list/export`（.cube 等格式）可复用；`lut.export` 便于交接。
+
+## 五、风格 look 与题材（用参数表达，不靠玄学）
+
+| 题材 | 影调倾向 | 参数落点（LightCraft 为例） |
+|---|---|---|
+| 都市短剧 | 干净、肤色透亮 | 曝光微提、`grading.midtones` 微暖、`vibrance` +、`clarity` 微增 |
+| 悬疑/权谋 | 低饱和、青冷阴影 | `grading.shadows.hue` 偏青、`saturation` −、`light.contrast` +、`vignette.amount` + |
+| 回忆/怀旧 | 暖黄、柔焦、颗粒 | `wb.temp` +、`grain.amount` +、`effects.texture`、高光柔化 |
+| 纪录片 | 中性、低干预 | 只做曝光/白平衡/轻微对比，`grain` 0 |
+| 广告/产品 | 高对比高清晰 | `detail.sharpenAmount` +、`clarity` +、色彩干净（避免溢色） |
+| 夜戏 | 保留暗部层次 | 黑位不贴底、`light.shadows` +、`denoise` 加强、`grain` 压噪点 |
+
+**风格化铁律**：**先统一、后风格**；同一部片最多 1–2 种影调倾向，跨集沿用同一预设（保证"60 集像同一部剧"）。
+
+## 六、常见问题速查
+
+| 症状 | 可能原因 | 处理 |
+|---|---|---|
+| 全片发灰 | 黑位抬高 | 压低 `light.blacks` / 曲线暗部 |
+| 肤色发黄/发青 | 白平衡或 `mixer.orange` 偏移 | 回正 `wb.tint`，核对矢量示波器肤色线 |
+| 颜色结块/溢出 | 过饱和 | 降 `color.saturation`，改提 `vibrance` |
+| 跨镜跳色 | 未做匹配 | `lumetri.applyMatch` + 预设复用 |
+| 暗部噪点爆发 | 提亮过度/未降噪 | `detail.nrLuminance` + `denoise.*`（LightCraft 16 条） |
+| 锐化出现白边 | 锐化过量 | `detail.sharpenMasking` + 降 `sharpenAmount` |
+| HDR 片子在 SDR 上发闷 | 未做色调映射 | `hdr.sdr*` 七控制 / `lumetri` 映射 |
+
+## 七、作业模板
+
+```
+1) 探      artcraft_cli { bin:"lightcraft", args:["run","--demo","develop.controls"] }  # 看可用控制
+           artcraft_cli { bin:"filmcraft", args:["commands","lumetri"] }               # 看调色族
+2) 统一    lumetri.applyMatch（参考帧）→ presets.save
+3) 修正    一级四项 → 二级限定 → 局部遮罩
+4) 核对    scopes.read（波形/矢量/直方）逐镜读数
+5) 风格    Look/LUT/预设，跨镜复用
+6) 交付    按 artcraft-delivery-qc 核响度与色彩空间
+```

package/skills/artcraft-color-light/references/develop-controls.md

@@ -0,0 +1,43 @@
+# LightCraft develop 控制参考（122 项 / 14 分区）
+
+> 由 `lightcraft-cli run --demo develop.controls` 精确导出。
+> 用法：`artcraft_cli { bin:"lightcraft", args:["run","--library","<库>","develop.set","control=<id>","value=<v>"] }`
+> 顺序建议（冲洗链）：profile → color → light → curve → grading → mixer → detail → optics → geometry → effects → grain → vignette → bwMix → calibration。
+
+| 分区 | 项数 | 控制 id（label · 范围 · 默认） |
+|---|---:|---|
+| **mixer** | 24 | `mixer.red.hue` (Red Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.red.sat` (Red Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.red.lum` (Red Luminance · -100–100 · 默认 0 · 步进 1)<br>`mixer.orange.hue` (Orange Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.orange.sat` (Orange Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.orange.lum` (Orange Luminance · -100–100 · 默认 0 · 步进 1)<br>`mixer.yellow.hue` (Yellow Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.yellow.sat` (Yellow Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.yellow.lum` (Yellow Luminance · -100–100 · 默认 0 · 步进 1)<br>`mixer.green.hue` (Green Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.green.sat` (Green Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.green.lum` (Green Luminance · -100–100 · 默认 0 · 步进 1)<br>`mixer.aqua.hue` (Aqua Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.aqua.sat` (Aqua Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.aqua.lum` (Aqua Luminance · -100–100 · 默认 0 · 步进 1)<br>`mixer.blue.hue` (Blue Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.blue.sat` (Blue Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.blue.lum` (Blue Luminance · -100–100 · 默认 0 · 步进 1)<br>`mixer.purple.hue` (Purple Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.purple.sat` (Purple Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.purple.lum` (Purple Luminance · -100–100 · 默认 0 · 步进 1)<br>`mixer.magenta.hue` (Magenta Hue · -100–100 · 默认 0 · 步进 1)<br>`mixer.magenta.sat` (Magenta Saturation · -100–100 · 默认 0 · 步进 1)<br>`mixer.magenta.lum` (Magenta Luminance · -100–100 · 默认 0 · 步进 1) |
+| **grading** | 14 | `grading.shadows.hue` (Shadows Hue · 0–360 · 默认 0 · 步进 1)<br>`grading.shadows.sat` (Shadows Saturation · 0–100 · 默认 0 · 步进 1)<br>`grading.shadows.lum` (Shadows Luminance · -100–100 · 默认 0 · 步进 1)<br>`grading.midtones.hue` (Midtones Hue · 0–360 · 默认 0 · 步进 1)<br>`grading.midtones.sat` (Midtones Saturation · 0–100 · 默认 0 · 步进 1)<br>`grading.midtones.lum` (Midtones Luminance · -100–100 · 默认 0 · 步进 1)<br>`grading.highlights.hue` (Highlights Hue · 0–360 · 默认 0 · 步进 1)<br>`grading.highlights.sat` (Highlights Saturation · 0–100 · 默认 0 · 步进 1)<br>`grading.highlights.lum` (Highlights Luminance · -100–100 · 默认 0 · 步进 1)<br>`grading.global.hue` (Global Hue · 0–360 · 默认 0 · 步进 1)<br>`grading.global.sat` (Global Saturation · 0–100 · 默认 0 · 步进 1)<br>`grading.global.lum` (Global Luminance · -100–100 · 默认 0 · 步进 1)<br>`grading.blending` (Blending · 0–100 · 默认 50 · 步进 1)<br>`grading.balance` (Balance · -100–100 · 默认 0 · 步进 1) |
+| **light** | 13 | `light.exposure` (Exposure · -5–5 · 默认 0 · 步进 0.01)<br>`light.contrast` (Contrast · -100–100 · 默认 0 · 步进 1)<br>`light.highlights` (Highlights · -100–100 · 默认 0 · 步进 1)<br>`light.shadows` (Shadows · -100–100 · 默认 0 · 步进 1)<br>`light.whites` (Whites · -100–100 · 默认 0 · 步进 1)<br>`light.blacks` (Blacks · -100–100 · 默认 0 · 步进 1)<br>`hdr.maxEv` (HDR Headroom · 0–5 · 默认 3 · 步进 0.1)<br>`hdr.sdrBrightness` (SDR Brightness · -100–100 · 默认 0 · 步进 1)<br>`hdr.sdrContrast` (SDR Contrast · -100–100 · 默认 0 · 步进 1)<br>`hdr.sdrHighlights` (SDR Highlights · -100–100 · 默认 0 · 步进 1)<br>`hdr.sdrShadows` (SDR Shadows · -100–100 · 默认 0 · 步进 1)<br>`hdr.sdrWhites` (SDR Whites · -100–100 · 默认 0 · 步进 1)<br>`hdr.sdrClarity` (SDR Clarity · -100–100 · 默认 0 · 步进 1) |
+| **optics** | 13 | `optics.distortion` (Distortion · -100–100 · 默认 0 · 步进 1)<br>`optics.vignetting` (Vignetting · -100–100 · 默认 0 · 步进 1)<br>`optics.vignettingMidpoint` (Midpoint · 0–100 · 默认 50 · 步进 1)<br>`optics.profileDistortion` (Profile Distortion · 0–200 · 默认 100 · 步进 1)<br>`optics.profileVignetting` (Profile Vignetting · 0–200 · 默认 100 · 步进 1)<br>`optics.defringePurple` (Purple Amount · 0–20 · 默认 0 · 步进 1)<br>`optics.defringePurpleHueLo` (Purple Hue Low · 0–90 · 默认 30 · 步进 1)<br>`optics.defringePurpleHueHi` (Purple Hue High · 10–100 · 默认 70 · 步进 1)<br>`optics.defringeGreen` (Green Amount · 0–20 · 默认 0 · 步进 1)<br>`optics.defringeGreenHueLo` (Green Hue Low · 0–90 · 默认 40 · 步进 1)<br>`optics.defringeGreenHueHi` (Green Hue High · 10–100 · 默认 60 · 步进 1)<br>`optics.caRed` (Red/Cyan Fringe · -100–100 · 默认 0 · 步进 1)<br>`optics.caBlue` (Blue/Yellow Fringe · -100–100 · 默认 0 · 步进 1) |
+| **detail** | 11 | `enhance.denoise` (Amount · 0–100 · 默认 0 · 步进 1)<br>`detail.sharpenAmount` (Sharpening · 0–150 · 默认 0 · 步进 1)<br>`detail.sharpenRadius` (Radius · 0.5–3 · 默认 1 · 步进 0.1)<br>`detail.sharpenDetail` (Detail · 0–100 · 默认 25 · 步进 1)<br>`detail.sharpenMasking` (Masking · 0–100 · 默认 0 · 步进 1)<br>`detail.nrLuminance` (Noise Reduction · 0–100 · 默认 0 · 步进 1)<br>`detail.nrDetail` (Detail · 0–100 · 默认 50 · 步进 1)<br>`detail.nrContrast` (Contrast · 0–100 · 默认 0 · 步进 1)<br>`detail.nrColor` (Color Noise Reduction · 0–100 · 默认 0 · 步进 1)<br>`detail.nrColorDetail` (Detail · 0–100 · 默认 50 · 步进 1)<br>`detail.nrColorSmoothness` (Smoothness · 0–100 · 默认 50 · 步进 1) |
+| **curve** | 8 | `curve.highlights` (Highlights · -100–100 · 默认 0 · 步进 1)<br>`curve.lights` (Lights · -100–100 · 默认 0 · 步进 1)<br>`curve.darks` (Darks · -100–100 · 默认 0 · 步进 1)<br>`curve.shadows` (Shadows · -100–100 · 默认 0 · 步进 1)<br>`curve.splitShadows` (Shadows split · 10–70 · 默认 25 · 步进 1)<br>`curve.splitMid` (Midtones split · 20–80 · 默认 50 · 步进 1)<br>`curve.splitHighlights` (Highlights split · 30–90 · 默认 75 · 步进 1)<br>`curve.refineSaturation` (Refine Saturation · 0–100 · 默认 100 · 步进 1) |
+| **bwMix** | 8 | `bw.red` (Red · -100–100 · 默认 0 · 步进 1)<br>`bw.orange` (Orange · -100–100 · 默认 0 · 步进 1)<br>`bw.yellow` (Yellow · -100–100 · 默认 0 · 步进 1)<br>`bw.green` (Green · -100–100 · 默认 0 · 步进 1)<br>`bw.aqua` (Aqua · -100–100 · 默认 0 · 步进 1)<br>`bw.blue` (Blue · -100–100 · 默认 0 · 步进 1)<br>`bw.purple` (Purple · -100–100 · 默认 0 · 步进 1)<br>`bw.magenta` (Magenta · -100–100 · 默认 0 · 步进 1) |
+| **geometry** | 8 | `geometry.vertical` (Vertical · -100–100 · 默认 0 · 步进 1)<br>`geometry.horizontal` (Horizontal · -100–100 · 默认 0 · 步进 1)<br>`geometry.rotate` (Rotate · -10–10 · 默认 0 · 步进 0.1)<br>`geometry.aspect` (Aspect · -100–100 · 默认 0 · 步进 1)<br>`geometry.scale` (Scale · 50–150 · 默认 100 · 步进 1)<br>`geometry.offsetX` (Offset X · -100–100 · 默认 0 · 步进 0.1)<br>`geometry.offsetY` (Offset Y · -100–100 · 默认 0 · 步进 0.1)<br>`crop.angle` (Straighten · -45–45 · 默认 0 · 步进 0.01) |
+| **calibration** | 7 | `calibration.shadowsTint` (Shadows Tint · -100–100 · 默认 0 · 步进 1)<br>`calibration.redHue` (Red Hue · -100–100 · 默认 0 · 步进 1)<br>`calibration.redSat` (Red Saturation · -100–100 · 默认 0 · 步进 1)<br>`calibration.greenHue` (Green Hue · -100–100 · 默认 0 · 步进 1)<br>`calibration.greenSat` (Green Saturation · -100–100 · 默认 0 · 步进 1)<br>`calibration.blueHue` (Blue Hue · -100–100 · 默认 0 · 步进 1)<br>`calibration.blueSat` (Blue Saturation · -100–100 · 默认 0 · 步进 1) |
+| **vignette** | 5 | `vignette.amount` (Vignette · -100–100 · 默认 0 · 步进 1)<br>`vignette.midpoint` (Midpoint · 0–100 · 默认 50 · 步进 1)<br>`vignette.roundness` (Roundness · -100–100 · 默认 0 · 步进 1)<br>`vignette.feather` (Feather · 0–100 · 默认 50 · 步进 1)<br>`vignette.highlights` (Highlights · 0–100 · 默认 0 · 步进 1) |
+| **color** | 4 | `wb.temp` (Temp · 2000–50000 · 默认 6500 · 步进 50)<br>`wb.tint` (Tint · -150–150 · 默认 0 · 步进 1)<br>`color.vibrance` (Vibrance · -100–100 · 默认 0 · 步进 1)<br>`color.saturation` (Saturation · -100–100 · 默认 0 · 步进 1) |
+| **effects** | 3 | `effects.texture` (Texture · -100–100 · 默认 0 · 步进 1)<br>`effects.clarity` (Clarity · -100–100 · 默认 0 · 步进 1)<br>`effects.dehaze` (Dehaze · -100–100 · 默认 0 · 步进 1) |
+| **grain** | 3 | `grain.amount` (Grain · 0–100 · 默认 0 · 步进 1)<br>`grain.size` (Size · 0–100 · 默认 25 · 步进 1)<br>`grain.roughness` (Roughness · 0–100 · 默认 50 · 步进 1) |
+| **profile** | 1 | `profile.amount` (Amount · 0–200 · 默认 100 · 步进 1) |
+
+## 常见目标对应的控制
+
+| 目标 | 控制 |
+|---|---|
+| 曝光/对比 | `light.exposure` · `light.contrast` |
+| 高光/阴影恢复 | `light.highlights` · `light.shadows` · `hdr.sdrHighlights` · `hdr.sdrShadows` |
+| 白平衡 | `wb.temp` · `wb.tint` |
+| 饱和度/自然饱和度 | `color.saturation` · `color.vibrance` |
+| 分区调色 | `grading.shadows.*` · `grading.midtones.*` · `grading.highlights.*` · `grading.global.*` |
+| 定点修色（8 色相） | `mixer.<red|orange|yellow|green|aqua|blue|purple|magenta>.<hue|sat|lum>` |
+| 曲线 | `curve.highlights` · `curve.lights` · `curve.darks` · `curve.shadows` · `curve.splitShadows/Mid/Highlights` |
+| 锐化 | `detail.sharpenAmount` · `sharpenRadius` · `sharpenDetail` · `sharpenMasking` |
+| 降噪 | `detail.nrLuminance` · `nrDetail` · `nrContrast` · `nrColor` · `nrColorDetail` · `nrColorSmoothness` · `enhance.denoise` |
+| 镜头校正 | `optics.distortion` · `optics.vignetting` · `optics.defringePurple/Green` · `optics.caRed/caBlue` |
+| 几何/裁切 | `geometry.vertical/horizontal/rotate/aspect/scale/offsetX/offsetY` · `crop.angle` |
+| 氛围 | `effects.texture` · `effects.clarity` · `effects.dehaze` |
+| 胶片感 | `grain.amount` · `grain.size` · `grain.roughness` · `vignette.amount` |
+| 黑白 | `bw.<red|orange|yellow|green|aqua|blue|purple|magenta>` |
+| 相机校准 | `calibration.shadowsTint` · `calibration.<red|green|blue><Hue|Sat>` |
+| HDR→SDR | `hdr.maxEv` · `hdr.sdrBrightness` · `hdr.sdrContrast` · `hdr.sdrHighlights` · `hdr.sdrShadows` · `hdr.sdrWhites` · `hdr.sdrClarity` |

package/skills/artcraft-color-light/references/lumetri-and-scopes.md

@@ -0,0 +1,65 @@
+# Lumetri / LUT / 示波器接口（FilmCraft）
+
+> 来源：官方 `docs/control-protocol.md`（已验证）+ 本机命令表实测。
+> 调色的方法顺序与判据见 `../SKILL.md`；本文件只讲**精确接口**，避免写错参数。
+
+## 一、Lumetri 与 LUT
+
+| 命令 | 参数 | 说明 |
+|---|---|---|
+| `lumetri.setInputLut` | `{clip?, lut:"lib:<id>"\|"builtin:<id>"\|"", path?}` | **技术 LUT**（Log→709）；输入转换只应在这里做 |
+| `lumetri.setLook` | `{clip?, lut:"lib:<id>"\|"builtin:<id>"\|"", path?}` | **创意 Look**（风格化）；与技术转换分离 |
+| `lumetri.setSection` | `{clip?, section, on?}` | 展开/开关 Lumetri 分区（`basic` / `creative` / `curves` / `wheels` …） |
+| `lumetri.applyMatch` | `{clip?, referenceTime\|referenceFrame\|referenceTimecode, faceDetection?}` | **跨镜匹配**：以参考镜头的某一时刻为基准（`faceDetection` 默认开） |
+| `lumetri.presets` | `{folder?}` | 列出可用调色预设 |
+| `lumetri.applyPreset` | `{name, clips?}` | 套用预设（一致性锁的关键动作） |
+| `lumetri.presetThumbnails` | `{folder?, names?, width?, columns?, …}` | 生成预设缩略图（供视觉挑选） |
+| `lut.import` / `lut.list` / `lut.remove` / `lut.export` | `{path, name?}` / `{}` / `{id}` / `{lut, path, format?}` | LUT 资产管理（`.cube` 等） |
+
+**UI 面板 id**（`ui.set` 用）：`lumetri.input_lut` · `lumetri.look_lut` · `lumetri.switch.<section>` · `lumetri.section.<section>` · `lumetri.match.*`；
+颜色对话框：`colorDialog.wideGamut` · `colorDialog.autoToneMap` · `colorDialog.ok` / `cancel`。
+
+## 二、示波器（客观判据）
+
+```
+artcraft_control { app:"filmcraft", method:"scopes.read",
+                   params:{ scopes:["waveform","parade","histogram","vectorscopeYuv"] } }
+```
+
+- `scopes.read` 返回所选示波器的读数；HDR 素材另有 **`scopes.hdrWaveform`**。
+- 判读要点：
+  - **Waveform（波形/亮度）**：黑位不贴底（否则暗部死）、白位不削顶（否则高光丢细节）。
+  - **Parade（RGB 分量）**：三通道是否对齐——偏色会在分量上先暴露。
+  - **Vectorscope（矢量）**：**肤色线**附近为正常肤色；越界即过饱和。
+  - **Histogram（直方）**：分布是否堆积在两端（对比过猛/过平）。
+- 示波器只是在运行中 App 里才能实时读；无头流程可用 `artcraft_qc`（读产物）+ 抽帧目检替代。
+
+## 三、色域与 HDR
+
+| 需求 | 接口 |
+|---|---|
+| 列出可用色彩空间 | `color.spaces` |
+| HDR 交付 | `file.exportMedia {sdr:true}` 导出 SDR 版本；HDR 原样导出则不带该参数 |
+| HDR→SDR 映射（照片/RAW 链路） | LightCraft `hdr.maxEv` / `hdr.sdrBrightness` / `hdr.sdrContrast` / `hdr.sdrHighlights` / `hdr.sdrShadows` / `hdr.sdrWhites` / `hdr.sdrClarity`（见 artcraft-color-light 的控制表） |
+| LUT 交接给其他软件 | `lut.export {lut:"lib:<id>", path:"<out>.cube", format:"cube"}` |
+
+## 四、跨镜一致性操作序列（可直接照抄）
+
+```
+1) 选参考：timeline.selectClipAtPlayhead / scopes.read 找曝光与白平衡最准的镜头
+2) 匹配：  lumetri.applyMatch { clip:"<目标>", referenceTime:<参考时刻>, faceDetection:true }
+3) 预设：  presets.save { name:"ep01-main" }（把定稿参数存成预设）
+4) 复用：  lumetri.applyPreset { name:"ep01-main", clips:[…] }（其余镜头统一）
+5) 核对：  scopes.read 逐镜比对（波形/矢量读数一致）
+6) 固件：  lut.export（把 Look 导出为 .cube 交付/归档，供跨集与跨软件复用）
+```
+
+## 五、常见错误
+
+| 错误 | 后果 | 纠正 |
+|---|---|---|
+| 把风格 LUT 塞进 `setInputLut` | 技术转换与风格混淆，后期无法回退 | 技术转换用 `setInputLut`，风格用 `setLook` |
+| 逐镜手调而不 `applyMatch` | 跳色 | 先匹配再套预设 |
+| 只看监视器不看示波器 | 不同显示器上片子颜色不一致 | 一律以 `scopes.read` 读数为准 |
+| 忘了 `faceDetection` | 匹配把肤色带偏 | 保持默认开启；人像镜头尤其重要 |
+| LUT 未归档 | 跨集/交接后无法复现 | `lut.export` 存档并写入 `craft/` |

package/skills/artcraft-delivery-qc/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: artcraft-delivery-qc
+description: 交付与质检——平台规格（横竖屏分辨率/帧率/码率/时长/响度/字幕安全区）、导出预设与格式选择、交换格式交付（EDL/XML/FCPXML/OTIO/AAF/OMF）、客观质检（探产物/示波器/音频体检/无障碍/数据校验/尺寸测量）、主观复核（抽帧联络表 + 视觉确认）、命名与目录规范、常见翻车排查。用于成片导出、平台适配与交付前把关。
+---
+
+# 交付与质检
+
+交付不是"导出完事"，而是**证明它符合规格**。所有质检结论要基于事实（参数读数、抽帧图、体检报告），不基于"我觉得没问题"。
+
+## 一、平台规格速查
+
+| 平台/场景 | 画幅 | 建议分辨率 | 帧率 | 视频码率 | 音频 | 响度 |
+|---|---|---|---|---|---|---|
+| B 站 / YouTube 横屏 | 16:9 | 1920×1080（可 4K） | 24/25/30/60 | 1080p 8–12 Mbps；4K 35–45 Mbps | AAC 192–320 kbps | −14 LUFS |
+| 抖音 / Reels / Shorts 竖屏 | 9:16 | 1080×1920 | 30/60 | 6–10 Mbps | AAC 128–192 kbps | −14 LUFS |
+| 微信视频号 | 9:16 或 1:1 | 1080×1920 / 1080×1080 | 30 | 6–8 Mbps | AAC 128 kbps | −14 LUFS |
+| 广播/电视 | 16:9 | 1920×1080 | 25/50（PAL）· 29.97/59.94（NTSC） | 50 Mbps+ 或 ProRes | PCM | **−23 LUFS** |
+| 影院/DCP | 1.85 / 2.39 | 2K/4K | 24 | JPEG2000 | PCM 5.1 | −27 LUFS 参考 |
+| 播客（纯音频） | — | — | — | — | WAV/AAC 44.1k+ | −16 LUFS |
+
+**字幕安全区**：竖屏下字幕避开底部 12–15%（平台 UI 遮挡区）、左右各留 5%；横屏底部 10%。FilmCraft `graphics.*` 与 `captions.setStyle` 支持安全区参数。
+
+## 二、导出：预设优先，参数兜底
+
+```
+1) 查预设   filmcraft-cli export --list-presets          # 名称/类别/格式
+2) 用预设   export <out> --preset <name> [--range entire|inOut|workArea] [--scale] [--quality]
+3) 无预设   显式指定：--format h264|hevc|prores|dnxhr|… --bitrateKbps --audioCodec aac|pcm|flac
+```
+
+- **FilmCraft**：`export.presets.list` / `export.formats` / `file.exportMedia {path, preset|format, width, height, fps, bitrateKbps, bitrateMode, audioCodec, …}`；`--gpu-rendering auto|off` 控制硬件编码；`--queue` 走导出队列。
+- **EffectCraft**：`render --format h264|hevc|av1|prores|webm|png|jpeg|tiff|exr|gif|wav|aiff`（`exec app.capabilities` 可列全部导出格式）+ `--resolution full|half|third|quarter`、`--quality best|draft`、`--channels rgb|rgba`、`--prores PROFILE`、`--webm-codec vp9|av1`。
+- **PhotoCraft**：`convert <in> <out> [--format] [--quality] [--tiff-layers]`。
+- **VectorCraft**：`convert IN OUT [--scale] [--artboard|--range] [--outline-text]`。
+- **DeckCraft/DesignCraft/WordCraft/GridCraft/CADCraft/PdfCraft**：各有 `convert`/`render`/`export` 子命令；PDF 类注意 `--scale`、出血、CMYK（FigCraft `export --bleed --crop-marks --cmyk`）。
+- **音频**：SoundCraft `file.bounce_mix` / `file.bounce_stems {dir, format: wav|aiff|flac, bit_depth: 16|24|32f}`。
+
+## 三、交换格式（跨软件交付）
+
+| 目标 | 命令 | 说明 |
+|---|---|---|
+| 剪辑时间线 | FilmCraft `file.exportInterchange {format:"edl\|xml\|fcpxml\|otio\|aaf\|omf", path, sequence}` | **OTIO/FCPXML 优先**；EDL 仅作剪辑清单（单轨、无特效） |
+| 给混音师 | `file.exportAaf` / `file.exportOmf` | 支持 `handles`、`breakoutToMono`、`audio:"embedded\|separate"` |
+| 字幕交付 | `captions.export {path, format:"srt\|vtt\|scc\|mcc\|stl\|ttml\|dfxp"}` | 平台不同格式不同 |
+| 静态图/序列 | PhotoCraft `convert`、EffectCraft `render --format png|exr|tiff` | 序列命名用 `%04d` 约定 |
+
+## 四、客观质检（读数 + 体检）
+
+| 检查项 | 用什么 | 通过判据 |
+|---|---|---|
+| 容器/流参数 | `filmcraft probe <media>`、各成员 `info` | 分辨率/帧率/时长/音轨布局与规格一致 |
+| 画面电平 | `scopes.read {scopes:["waveform","parade","histogram","vectorscopeYuv"]}` | 黑不贴底、白不削顶、矢量不越界 |
+| 黑帧/冻结/静音 | 抽样探 + 抽帧目视 | 无意外黑场/定格/无声段 |
+| 音频体检 | SoundCraft `session.audio_health`；FilmCraft `essentialSound.inspect` | 无丢失/无异常片段 |
+| 真峰值/响度 | `essentialSound.autoMatch` 后核对 | 达标（见 artcraft-sound-design） |
+| 文档无障碍 | PdfCraft `a11y.check`、`a11y.alt_text`、`a11y.reading_options`；WordCraft `file.accessibility` | 无致命项 |
+| 尺寸/边距 | PdfCraft `measure.distances/area`；FigCraft `measure.distances/padding` | 符合版式与出血要求 |
+| 数据正确性 | GridCraft `data.validate` / `data.validation` | 无校验失败项 |
+| 字体齐全 | FilmCraft `graphics.fonts.used`；FigCraft `--no-system-fonts` 渲染一致性 | 无缺字/回退字体 |
+| 快捷键冲突（工程健康） | FilmCraft `shortcuts.audit` / `shortcuts.conflicts` | 无冲突残留 |
+
+## 五、主观复核（机器读数之外）
+
+1. **抽帧联络表**：整片按固定间隔抽帧（FilmCraft `render` 单帧 / PhotoCraft `convert` / `ui.screenshot`），拼成联络表。
+2. **自己看**：由你（多模态）逐格确认——构图、曝光、肤色、字幕位置、转场是否自然。
+3. **听**：对白清晰度、音乐是否抢戏、切点有无爆音（无法听时，至少核对响度与波形读数）。
+4. **看首尾**：开头 3 秒与结尾 3 秒是观众最挑剔的地方，必须单独复核。
+
+## 六、命名与目录规范
+
+```
+<project>/
+  media/     素材（只读，不改）
+  craft/     工程文件与中间产物（.fcproj/.ecproj/.pcraft/.figcraft…）
+  out/       交付物
+     <name>_<平台>_<画幅>_<版本>.<ext>
+     例：ep01_douyin_9x16_v3.mp4
+  reports/   质检记录（读数、抽帧图、体检输出）
+```
+
+**版本纪律**：改一版进一位（v1→v2→v3），**绝不覆盖上一版交付物**；最终版单独标记 `_final`。
+
+## 七、常见翻车与排查
+
+| 症状 | 原因 | 处理 |
+|---|---|---|
+| 平台压片后变糊 | 码率不足 / 二次压缩 | 提码率、给平台更大源文件 |
+| 竖屏被 UI 挡字幕 | 未留安全区 | 字幕上移；`captions.setStyle` 调位置 |
+| 颜色在平台上变了 | 色彩空间/标签错误 | 明确交付 Rec.709 并核对 `color.spaces` |
+| 音画不同步 | 源 VFR / 帧率不匹配 | 先统一恒定帧率再导出 |
+| 响度忽大忽小 | 未统一归一化 | `autoMatch` 全片统一（见 sound-design） |
+| 时长超平台限制 | 未按规格裁剪 | 导出前核对平台时长上限 |
+| 字幕时间轴偏移 | 帧率/时基换算错误 | 用 `captions.setTimes` 按秒/帧/时间码校正 |
+| 字体在不同机器不一致 | 系统字体依赖 | 用内置字体（FigCraft `--no-system-fonts`）或转曲 |
+
+## 八、交付前最终清单
+
+- [ ] 规格：分辨率/帧率/码率/时长/画幅 全部达标
+- [ ] 画面：无黑帧冻结、示波器不越界、主观复核通过
+- [ ] 声音：响度达标、真峰值不削、无爆音、对白清晰
+- [ ] 字幕：时间轴正确、不断句错、在安全区内、格式正确
+- [ ] 元数据：标题/作者/描述（`metadata.set`）填写完整
+- [ ] 交换件：需要交接时 OTIO/FCPXML/AAF 已生成并验证可打开
+- [ ] 命名与版本：规范、未覆盖旧版
+- [ ] 报告：读数与抽帧证据已留档（reports/）

package/skills/artcraft-delivery-qc/references/platform-specs.md

@@ -0,0 +1,74 @@
+# 平台规格与交付参数表
+
+> 配合插件工具使用：`artcraft_qc { path:"<产物>", platform:"douyin" }` 会按本表核对画幅/帧率并给出修复命令。
+> 响应值：`pass` / `pass-with-manual-checks` / `warn` / `fail`；`manual` 级项目需在应用内复核（响度、无障碍、印刷尺寸）。
+
+## 一、视频平台
+
+| platform id | 场景 | 画幅 | 目标分辨率 | 推荐帧率 | 建议码率 | 音频 | 响度目标 |
+|---|---|---|---|---|---|---|---|
+| `bilibili` | B 站 / 横屏 | 16:9 | 1920×1080（可 4K） | 24 / 25 / 30 / 50 / 60 | 1080p 8–12 Mbps · 4K 35–45 Mbps | AAC 192–320 kbps | −14 LUFS / TP −1 |
+| `youtube` | YouTube / 横屏 | 16:9 | 1920×1080（可 4K） | 24 / 25 / 30 / 50 / 60 | 同上 | AAC 192–320 kbps | −14 LUFS / TP −1 |
+| `douyin` | 抖音 / 竖屏 | 9:16 | 1080×1920 | 30 / 60 | 6–10 Mbps | AAC 128–192 kbps | −14 LUFS / TP −1 |
+| `reels` | Instagram Reels | 9:16 | 1080×1920 | 30 / 60 | 6–10 Mbps | AAC 128–192 kbps | −14 LUFS / TP −1 |
+| `shorts` | YouTube Shorts | 9:16 | 1080×1920 | 30 / 60 | 6–10 Mbps | AAC 128–192 kbps | −14 LUFS / TP −1 |
+| `wechat` | 视频号 | 9:16 或 1:1 | 1080×1920 / 1080×1080 | 30 | 6–8 Mbps | AAC 128 kbps | −14 LUFS / TP −1 |
+| `broadcast` | 广播 / 电视（EBU R128） | 16:9 | 1920×1080 | 25 / 50（PAL）· 29.97 / 59.94（NTSC） | 50 Mbps+ 或 ProRes | PCM | **−23 LUFS / TP −2** |
+| `podcast` | 播客（纯音频） | — | — | — | — | WAV/AAC ≥ 44.1 kHz | **−16 LUFS / TP −1.5** |
+
+## 二、编码与容器选择
+
+| 场景 | 视频编码 | 备注 |
+|---|---|---|
+| 平台上传（通用） | H.264 (AVC) | 兼容性最好；码率按上表 |
+| 画质优先 / 4K | H.265 (HEVC) | 同画质省 30–50% 体积；部分平台转码后反而降质 |
+| 网页/开源编码 | AV1 | 体积最优，编码慢；EffectCraft 支持 `--webm-codec av1` |
+| 中间/交付母版 | ProRes（422/4444） | 剪辑与合成交接；带 alpha 用 4444 |
+| 广播/影院中间 | DNxHR / ProRes | 稳定、可多次编辑 |
+| 静帧序列 | PNG / EXR / TIFF | EXR 保 HDR 与多通道；序列命名 `%04d` |
+| 音频母版 | WAV 24-bit / 48 kHz | 分轨交付用 stems（`file.bounce_stems`） |
+
+## 三、字幕与安全区
+
+| 项 | 竖屏（9:16） | 横屏（16:9） |
+|---|---|---|
+| 底部避让（平台 UI） | 12–15% | 8–10% |
+| 左右安全边距 | 5% | 5% |
+| 单行字数（中文） | ≤ 15 | ≤ 20 |
+| 最短停留 | 1 s | 1 s |
+| 描边/底条 | 2–3 px 描边或半透明底条 | 同 |
+| 全片一致性 | 一种字体、一套样式（`captions.setStyle`） | 同 |
+
+## 四、文档与印刷
+
+| 交付物 | 检查项 | 命令 |
+|---|---|---|
+| PDF（阅读） | 无障碍（标签/阅读顺序/替代文本） | `pdfcraft run a11y.check` · `a11y.report` · `a11y.alt_text` |
+| PDF（印刷） | 出血、裁切标记、CMYK、尺寸 | FigCraft `export --bleed 3mm --crop-marks --cmyk`；DesignCraft `layout/type` |
+| PDF（长期存档） | PDF/A 合规 | `pdfcraft run standards.pdfa` |
+| PDF（传输） | 体积 | `pdfcraft run optimize.reduce`（或 `optimize.advanced`） |
+| PDF（安全） | 口令/权限 | `pdfcraft protect.password` / `protect.remove` |
+| Word 文档 | 无障碍、批注、修订、文献 | `wordcraft run --cmd file.accessibility` · `review.changes` · `references.bibliography` |
+| 表格 | 数据校验、公式、图表 | `gridcraft data.validate` / `data.validation` · `formulas.evaluate` |
+| 演示 | 转场/动画时长、备注 | `deckcraft transition.set` · `animation.timing` |
+
+## 五、命名与目录约定
+
+```
+<project>/
+  media/     素材（只读；帧表放 media/frames/）
+  craft/     工程与中间产物（.fcproj/.ecproj/.pcraft/.scraft/.figcraft/表）
+  out/       交付物：<name>_<平台>_<画幅>_<版本>.<ext>   例：ep01_douyin_9x16_v3.mp4
+  reports/   质检证据（读数、抽帧图、QC 输出、报告）
+```
+
+**版本纪律**：改一版进一位（v1→v2→v3），不覆盖旧交付物；最终版标记 `_final`。
+
+## 六、质检顺序建议
+
+1. `artcraft_qc`（自动：规格/画幅/帧率/时长/结构）
+2. 示波器（`scopes.read`：波形/矢量/直方）——画面电平
+3. 音频（`essentialSound.inspect` / `session.audio_health` / bounce 返回的 LUFS 与真峰值）
+4. 抽帧目检（agent 视觉复核构图/字幕/转场）
+5. 文档类附加检查（a11y / measure / validate / review）
+6. 记录到 `reports/`，结论可回溯到命令输出

package/skills/artcraft-edit-rhythm/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: artcraft-edit-rhythm
+description: 剪辑节奏与转场决策——镜头时长与情绪曲线、剪切点选择、动作/图形/视线匹配、J-cut 与 L-cut、跳切与蒙太奇的取舍、转场词典与"默认永远是切"、节拍剪辑与声音先行，并映射到 FilmCraft timeline/trim/captions/transcript/multicam 与 SoundCraft 节拍分析命令。用于剪辑、粗剪、节奏调整与转场设计。
+---
+
+# 剪辑节奏与转场
+
+剪辑的本质是**控制信息与情绪的释放速度**。节奏不是"快"，而是"该快的地方快、该停的地方停"。
+
+## 一、镜头时长与情绪曲线
+
+| 段落功能 | 时长倾向 | 手法 |
+|---|---|---|
+| 建立（开场/新场景） | 长（3–6s+） | 少切、让观众读空间 |
+| 递进（信息累积） | 递减 | 景别递进 + 切换加快 |
+| 峰值（冲突/高潮） | 最短 | 短切、近景、声音同步冲击 |
+| 余韵（收束） | 拉长 | 一个长镜或静帧，留呼吸 |
+
+**情绪曲线**：把每场标出"紧张值"，剪辑时让切点密度与之同向变化。平直的密度=观众走神。
+
+## 二、剪切点怎么选（五种可靠切点）
+
+| 切点 | 说明 | 优点 |
+|---|---|---|
+| **动作中切** | 在动作进行中切走 | 最隐蔽、最顺 |
+| **情绪峰值前切** | 在情绪刚要爆时切走 | 保留张力 |
+| **视线转移切** | 角色看向某处时切到所看之物 | 天然动机 |
+| **声音先行（J-cut）** | 下一场声音先入 | 段落缝合顺滑 |
+| **静默前切** | 台词/音乐落点后 2–3 帧切 | 有"落定感" |
+
+**避免**：在动作完成后停顿再切（显拖沓）、在完全静止时硬切（显跳）。
+
+## 三、剪辑类型与何时用
+
+| 类型 | 何时用 | 何时别用 |
+|---|---|---|
+| 动作匹配 cut on action | 动作段落、打斗、开门 | 动作方向不一致时 |
+| 图形匹配 graphic match | 相似形状/构图转场 | 过度刻意时 |
+| 视线匹配 eyeline match | 对话、观察 | 视线方向错乱 |
+| **J-cut / L-cut** | 对话戏、场景过渡（声音先行/滞后） | 纪录片采访硬切时 |
+| 跳切 jump cut | 时间压缩、焦躁、Vlog | 叙事连续场景（会"穿帮"） |
+| 蒙太奇 montage | 时间流逝、训练/准备段 | 关键冲突（会泄压） |
+| 插入镜头 insert | 强调道具/细节 | 无信息量时 |
+| 交叉剪辑 cross-cut | 平行时空、追逐 | 线索过多（>3 线） |
+| 平行剪辑 parallel | 对比主题 | 无明显对比时 |
+
+## 四、转场词典（**默认永远是切**）
+
+| 转场 | 语义 | 何时用 | 何时别用 |
+|---|---|---|---|
+| **切 cut** | 中性、默认 | 90% 场合 | —— |
+| 叠化 dissolve | 时间流逝、柔和过渡 | 段落之间、回忆 | 同场对话内 |
+| 闪白/闪黑 flash | 冲击、断裂 | 高能转场、惊吓 | 文艺段落 |
+| 划像 wipe | 空间/时间并列 | 类型片、幽默 | 严肃题材 |
+| 匹配转场 match cut | 巧思、主题呼应 | 记忆点 | 滥用即花哨 |
+| 隐藏剪辑 invisible cut | 无缝长镜错觉 | 沉浸式段落 | 需要明显断点时 |
+| 声音转场 sound bridge | 用声音缝合画面 | 几乎所有好剪辑 | —— |
+
+**铁律**：转场承载语义；**没有动机就不加转场**——"加个酷炫转场"是新手病。相邻转场不要连续用同一种。
+
+## 五、音乐、节拍与声音先行
+
+- **节拍切**：把切点落在音乐重拍上（情绪段），但**不要每拍都切**——重拍切 + 弱拍留白更有力。
+- **声音先行**：下一场的声音提前 0.5–1.5s 进入（J-cut）；或上一场声音延后（L-cut）。
+- **留白**：情绪峰值后给 0.5–1s 无声或环境声，比继续堆音乐更有效。
+- **响度**：跨段落响度要一致（见 artcraft-sound-design 与 artcraft-delivery-qc）。
+
+## 六、ArtCraft 落点（真实命令族）
+
+**FilmCraft（剪辑主场）**
+
+| 动作 | 命令 |
+|---|---|
+| 放置/移动/剃刀 | `timeline.place` · `timeline.move` · `timeline.razor` |
+| 修剪（常规/波纹） | `timeline.trim {mode:"regular\|ripple"}` · `trim.ripplePrevious/rippleNext` |
+| 滚动/滑移/滑动 | `timeline.roll` · `timeline.slip` · `timeline.slide` |
+| 变速（速率拉伸） | `timeline.rateStretch` |
+| 微调（按帧） | `timeline.nudgeLeft/Right`(+5) · `timeline.slipLeft/Right` · `timeline.slideUp/Down` |
+| 加转场 | `sequence.applyVideoTransition {effect:"cross_dissolve\|…", frames, edge, params}` · `sequence.applyAudioTransition` |
+| 默认转场批量 | `trim.applyDefaultTransition` |
+| 试看剪点 | `trim.playAround {clock, loop}` · `trim.selectNearest` · `trim.extendToPlayhead` |
+| 标记（镜头点/音乐点/待办） | `markers.*`（32 条） |
+| 多机位切换 | `multicam.*`（35 条，含按音频对齐与切换） |
+| 播放头/走带 | `playhead.*`（14 条） |
+
+**自动粗剪（家族自带，不需要外部工具）**
+
+| 目标 | 命令 |
+|---|---|
+| 转写 | `transcript.generate {model:"whisper-base", language}`（`transcript.models` 查可用模型） |
+| **去停顿** | `transcript.removePauses {minSeconds, keepSeconds}` |
+| **去口头禅** | `transcript.removeFillers {fillers}` |
+| 由转写生成字幕 | `transcript.createCaptions {maxChars, lines, minSeconds, maxSeconds}` |
+| 字幕精修 | `captions.*`（拆/并/改文/调时/样式/导入导出 srt·vtt·scc·mcc·stl·ttml·dfxp） |
+| 字幕升级为图形 | `graphics.upgradeCaption`（可做花字/动效字幕） |
+
+**节拍与音乐（SoundCraft）**：`event.beat_detective {sensitivity}`（检测节拍）· `event.identify_beat` · `event.extract_chords`（和弦）· `event.input_quantize`（量化到节拍）。把检测出的拍点写进 FilmCraft `markers.*`，再按标记切。
+
+## 七、剪辑质检清单（交付前自查）
+
+- [ ] 每场有明确的**情绪走向**，不是匀速
+- [ ] 相邻镜头**景别不重复**（除非刻意）
+- [ ] 无"动作完成后停顿"的拖沓切点
+- [ ] 转场**有语义动机**，且不连续重复
+- [ ] 对话戏有 J-cut/L-cut，不是全程硬切
+- [ ] 声音跨切点连续（无爆音/断点），响度一致
+- [ ] 音乐重拍与关键切点**对齐或刻意错开**
+- [ ] 字幕不断句错误、不超安全区（见 artcraft-delivery-qc）
+
+> 一句话原则：**切点是观众注意力的呼吸口**——该给信息时切，该给情绪时停。

package/skills/artcraft-edit-rhythm/references/transitions.md

@@ -0,0 +1,53 @@
+# 转场接口与选用决策（FilmCraft / DeckCraft）
+
+> 接口来自本机命令表与官方控制协议（已验证）；选用决策是创作判断（见 `../SKILL.md` 第四节）。
+> 铁律：**默认永远是切**；转场必须承载语义。
+
+## 一、命令接口（已验证）
+
+| 命令 | 参数 | 说明 |
+|---|---|---|
+| `sequence.applyVideoTransition` | `{clip?, effect:"<id>\|<显示名>"?, frames?, edge:"in"\|"out"?, params?:{…}, reverse?}` | 在剪辑点加视频转场 |
+| `sequence.applyAudioTransition` | `{clip?, effect?, frames?, edge?, params?, reverse?}` | 音频转场；**已验证**的音频转场名：`constant_power` / `constant_gain` / `exponential_fade` |
+| `sequence.setTransition` | `{transition, params?, reverse?, reset?, duration?, align:"center"\|"start"\|"end", start?, merge?, begin?}` | 修改已有转场的参数与时长/对齐 |
+| `sequence.removeTransition` | `{transitions?:[id]}` | 清除转场 |
+| `trim.applyDefaultTransition` | `{clips?}` | 给选区套默认转场（批量） |
+| `effects.setDefaultTransition` | `{effect:"constant_power\|constant_gain\|exponential_fade\|<video transition>"}` | 设定默认转场类型 |
+
+**视频转场的取值**：CLI 提示里以 `cross_dissolve|Cross Dissolve|…` 形式给出（应用内会截断长枚举），
+即**既接受 id 也接受显示名**；完整清单以应用「效果 → 视频转场」目录为准。
+DeckCraft（演示）另有 `transition.list` / `transition.set {kind, option?, duration?, index?}`，其 kind 枚举为
+`none|morph|fade|push|wipe|split|reveal|cut|randomBar|shape|uncover|cover|flash|…`（以 `transition.list` 为准）。
+
+## 二、选用决策表
+
+| 转场 | 语义 | 何时用 | 何时别用 | 时长经验 |
+|---|---|---|---|---|
+| **切 cut** | 中性、默认 | 90% 场合；对话、动作、信息递进 | —— | 0 |
+| 叠化 dissolve | 时间流逝 / 柔和过渡 | 段落之间、回忆、时间跳跃 | 同场对话内（会显得"软"） | 12–24 帧 |
+| 划像 wipe | 并列、类型化 | 类型片、幽默、对比 | 严肃写实题材 | 8–16 帧 |
+| 闪白/闪黑 | 冲击、断裂 | 高能转场、惊吓、章节切换 | 文艺/写实段落 | 4–8 帧 |
+| 匹配转场 match cut | 主题呼应、巧思 | 记忆点、呼应结构 | 滥用即花哨 | 0（靠构图） |
+| 隐藏剪辑 | 无缝长镜错觉 | 沉浸式、伪一镜到底 | 需要明确断点时 | 0 |
+| 声音桥 sound bridge | 缝合段落 | **几乎所有好剪辑** | —— | 0.5–1.5 s 提前/延后 |
+| 音频转场 `constant_power` | 等功率交叉淡化 | 音乐/环境声衔接（默认） | —— | 12–24 帧 |
+| 音频转场 `constant_gain` | 等增益（线性） | 需要保持电平感时 | 长叠化（中段会塌） | 8–16 帧 |
+| 音频转场 `exponential_fade` | 指数淡化 | 情绪渐弱/渐强 | 需要等功率时 | 12–36 帧 |
+
+## 三、操作要点
+
+1. **先切点、后转场**：转场加在已确认的剪辑点上；`sequence.setTransition {align:"center"}` 可让转场居中（默认），需要特定对齐时用 `align:"start"|"end"`。
+2. **时长按语义给**：情绪越强、转场越短（或干脆用切）；叙事性过渡（回忆）可给 24 帧以上。
+3. **声音优先于画面**：跨段落时先做 J-cut/L-cut（声音先行/延后），再考虑画面转场；多数情况下声音桥已足够，画面不必加转场。
+4. **一致性**：同一部片最多 1–2 种转场类型；同类转场时长统一（写入美学圣经，见 artcraft-style-bible）。
+5. **批量**：给一组剪辑点统一套默认转场 → 先 `effects.setDefaultTransition`，再 `trim.applyDefaultTransition`。
+
+## 四、常见错误
+
+| 错误 | 症状 | 纠正 |
+|---|---|---|
+| 每个剪辑点都加转场 | 花哨、廉价、节奏被拖慢 | 只保留有语义的少数转场 |
+| 同场对话内用叠化 | 节奏发软、像幻灯片 | 用切；需要柔和时用声音桥 |
+| 转场时长超镜头长度 | 报错或画面异常 | 先看镜头时长（`trim.playAround` 试看） |
+| 音频转场类型混用 | 段落间电平跳变 | 全片统一一种音频转场 |
+| 转场代替叙事 | 观众被形式干扰 | 问"这个转场说了什么"——答不出就删 |