@ninkch/dsh-artcraft 0.2.10 → 0.3.1

package/skills/artcraft-motion-vfx/references/scene-to-effect.md

@@ -0,0 +1,103 @@
+# 场景意图 → 效果 id 速查（EffectCraft）
+
+> 效果 id 来自官方注册表（`ec.<类别>.<名称>`），共 307 个；完整清单见同目录 `effect-catalogue.md`。
+> 用法：`artcraft_cli { bin:"effectcraft", args:["exec","effect.apply","--params","{\"layer\":N,\"effect\":\"<id>\"}"] }`
+> 参数走 `effect.setParam {clip|layer, effect, param, value}`；参数 id 形如 `effects/#1/<param>`。
+> 表中 id 均为**已验证存在**；没有把握的不要写死，先 `describe` 或查目录。
+
+## 一、光效与氛围
+
+| 意图 | 效果 id | 备注 |
+|---|---|---|
+| 辉光 / 柔光扩散 | `ec.stylize.glow` | 高光发光最常用；过度会糊 |
+| 体积光 / 光束 | `ec.generate.beam` | 配合遮罩做体积光 |
+| 光扫 / 光带 | `ec.generate.cclightsweep` | 品牌片头扫光 |
+| 光线放射 | `ec.generate.cclightrays` | 与 `glow` 叠加用 |
+| 镜头光晕 | `ec.generate.lensflare` | 慎用：过时感强 |
+| 闪电 | `ec.generate.advancedlightning` | 大场景；CPU 较慢 |
+| 斑斓反射（水下/玻璃） | `ec.sim.caustics` | 水面焦散 |
+| 渐变色块 | `ec.generate.fourcolor` / `ec.generate.gradientramp` | 背景与渐变过渡 |
+
+## 二、质感与风格化
+
+| 意图 | 效果 id | 备注 |
+|---|---|---|
+| 胶片颗粒 | `ec.noise.addgrain` / `ec.noise.matchgrain` | `matchGrain` 用于与实拍匹配（CPU） |
+| 去颗粒 | `ec.noise.removegrain` | 与上者配对 |
+| 噪点（数字） | `ec.noise.noise` / `ec.noise.fractal` | `fractal` 做云雾/纹理 |
+| 卡通 / 描边 | `ec.stylize.cartoon` / `ec.stylize.findedges` | 风格化整段慎用 |
+| 马赛克 | `ec.stylize.mosaic` | 打码/风格化 |
+| 海报化 | `ec.stylize.posterize` | 与 `posterizeTime` 配合做定格感 |
+| 边缘粗糙化 | `ec.stylize.roughenedges` | 手绘/做旧 |
+| 画笔涂抹 | `ec.stylize.brushstrokes` | 油画感 |
+| 玻璃折射 | `ec.stylize.ccglass` | 需要贴图配合 |
+| 灼烧转场 | `ec.stylize.ccburnfilm` | 复古转场 |
+
+## 三、变形与镜头语言
+
+| 意图 | 效果 id | 备注 |
+|---|---|---|
+| 位移/缩放/旋转 | `ec.distort.transform` | 基础变换（等效 layer transform 的滤镜版） |
+| 透视贴合（屏幕替换） | `ec.distort.cornerpin` | 与跟踪配合 |
+| 网格变形 | `ec.distort.meshwarp` | 精修形状 |
+| 液化 | `ec.distort.liquify` | 人脸/身体微调（慎用） |
+| 波纹 / 水波 | `ec.distort.ripple` / `ec.distort.wavewarp` | 水下、热浪 |
+| 湍流位移 | `ec.distort.turbulentdisplace` | 火焰/烟雾形态 |
+| 球面化 | `ec.distort.spherize` / `ec.perspective.ccsphere` | 星球/镜头畸变 |
+| 镜像 | `ec.distort.mirror` | 对称构图 |
+| 置换贴图 | `ec.distort.displacementmap` | 用手绘贴图驱动变形 |
+| 补偿镜头畸变 | `ec.distort.opticscompensation` | 广角素材修正 |
+| 卷帘快门修复 | `ec.distort.rollingshutterrepair` | 手机/运动相机素材 |
+
+## 四、合成与抠像
+
+| 意图 | 效果 id | 备注 |
+|---|---|---|
+| 绿幕抠像 | `ec.keying.keylight`（"Key Light"） | 行业标准；56 参数 |
+| 溢色抑制 | `ec.key.advancedspill` / `ec.key.spill` | **抠像最后一步** |
+| 键控清理 | `ec.key.keycleaner` | 修补边缘 |
+| 颜色范围抠像 | `ec.key.colorrange` / `ec.key.linearcolor` | 纯色背景 |
+| 蒙版收边 | `ec.matte.simplechoker` / `ec.matte.mattechoker` | 收/放边缘 |
+| 柔边精修 | `ec.matte.refinesoft` / `ec.matte.refinehard` | 发丝/硬边 |
+| Roto Brush | `ec.matte.rotobrush` | 与 `roto.*` 命令族配合 |
+| 通道运算合成 | `ec.channel.blend` / `ec.channel.compoundarithmetic` | 高级合成 |
+| 去黑/去白底 | `ec.key.unmult` / `ec.channel.removecolormatting` | 预乘处理 |
+| 投影 | `ec.perspective.dropshadow` / `ec.perspective.radialshadow` | 元素落地感 |
+
+## 五、时间、动效与图形
+
+| 意图 | 效果 id | 备注 |
+|---|---|---|
+| 时间重映射 | `ec.time.timedisplacement` | 与 `time.*` 命令配合 |
+| 卡帧 / 定格感 | `ec.time.posterizetime` | 抽帧风格 |
+| 音频驱动图形 | `ec.generate.audiospectrum` / `ec.generate.audiowaveform` | 音乐可视化 |
+| 数字滚动 | `ec.text.numbers` | 计数器/数据动效 |
+| 自动书写 | `ec.generate.writeon` | 手写标题 |
+| 描边动画 | `ec.generate.stroke` | 描边生长 |
+| 涂鸦线 | `ec.generate.scribble` | 手绘解释风 |
+| 万花筒/织带 | `ec.generate.vegas` | 风格化线条 |
+| 抖动 / 错位 | `ec.stylize.scatter` / `ec.stylize.motiontile` | 故障风（配合 `ec.vr.digitalglitch`） |
+| 玻璃/扭曲转场 | `ec.stylize.ccglass` + `ec.distort.turbulentdisplace` | 组合做有机转场 |
+
+## 六、模拟（重）与代价提示
+
+| 意图 | 效果 id | 代价 |
+|---|---|---|
+| 粒子系统 | `ec.sim.ccparticlesystems2` / `ec.sim.ccparticleworld` | 中；先半分辨率预演 |
+| 泡沫/气泡 | `ec.sim.foam` / `ec.sim.ccbubbles` | 中 |
+| 破碎 | `ec.sim.shatter` | **重**（60 参数），务必先 `render-frame` |
+| 雨雪 | `ec.sim.ccrainfall` / `ec.sim.ccsnowfall` | 中 |
+| 粒子游乐场 | `ec.sim.particleplayground` | **最重**（92 参数） |
+| 卡片舞动 | `ec.sim.carddance` | 重（53 参数） |
+
+> 通用纪律：**先 `render-frame` 看单帧 → 半分辨率草稿 → 全质量**；3D/粒子类避免直接全片渲染（见 `../SKILL.md` 第九节）。
+
+## 七、不要用效果做的事
+
+| 想做的事 | 别用效果 | 应该用 |
+|---|---|---|
+| 变速 | 时间类效果 | 剪辑层 `timeline.rateStretch`（保音高、可预期） |
+| 画面整体调色 | 逐个 `ec.color.*` | 优先 FilmCraft `lumetri.*` 或 LightCraft `develop.*`（见 artcraft-color-light） |
+| 稳定 | `ec.distort.warpstabilizer` 单打 | 优先 `track.stabilize`（两遍、可补偿缩放） |
+| 转场 | 叠加两个效果模拟 | 剪辑层 `sequence.applyVideoTransition`（见 artcraft-edit-rhythm） |
+| 抠像遮罩初形 | 直接用键控 | 先 `mask.*`/`roto.*` 出遮罩，再键控收边 |

package/skills/artcraft-multicam/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: artcraft-multicam
+description: 多机位剪辑——用 FilmCraft 的 multicam 命令族（35 条）把 2–9 台机位的素材对齐、切换、成片：建多机位源、音频对齐、网格巡视（gridLayout/grid/page/nextPage/prevPage）、角度选择与切换（selectCamera1-9 巡视 vs cutToCamera1-9 切出）、实时切换录制（recordStart/recordStop）、audioFollowsVideo、声音与画面一致性（allSound 处理、lumetri.applyMatch 跨机位对齐）、以及切换节奏的镜头语言规则与质检要点。用于访谈、演出、直播切片、多机位短剧。
+---
+
+# 多机位剪辑
+
+多机位的难点不是技术，而是**切换节奏**：切点错了，再多机位也只是"画面在跳"。
+
+## 一、命令族（FilmCraft multicam，35 条，已验证）
+
+| 命令 | 用途 |
+|---|---|
+| `multicam.inspect` | 查看当前多机位源与角度状态（**先 inspect**） |
+| `multicam.editCameras` | 编辑机位（增删/排序机位源） |
+| `multicam.grid` / `multicam.gridLayout` | 网格视图（同时看多路） |
+| `multicam.page` / `multicam.nextPage` / `multicam.prevPage` | 网格分页（>4 路时分页巡视） |
+| `multicam.selectCamera1…9` | **巡视**（只切预览，不落剪辑点） |
+| `multicam.cutToCamera1…9` | **切出**（把当前机位切到时间线） |
+| `multicam.switchAngle` / `multicam.cut` / `multicam.cutToCamera` | 通用角度切换 |
+| `multicam.recordStart` / `multicam.recordStop` | **实时切换录制**（边看边切，自动落点） |
+| `multicam.audioFollowsVideo` | 音频跟随视频机位（切换时同步换音源） |
+| `multicam.selectionTopDown` | 选择顺序（从上到下） |
+| `multicam.autoAdjustQuality` | 自动降低预览质量（多路预览卡顿时用） |
+| `multicam.showPreviewMonitor` / `multicam.transmitView` | 预览监视器 / 输出监看 |
+
+> `select*` = 看；`cutTo*` = 切。**混淆这两个是新手最常见的错误**（以为在看，其实已经切了）。
+
+## 二、标准流程
+
+```
+1) 导入素材        file.import / mediaBrowser.import（各机位分别入箱）
+2) 建多机位源      multicam.editCameras（把机位加入同一个源）
+3) 对齐            multicam.inspect 核对角度与同步；必要时用音频对齐（见 artcraft-sound-design 的 sync 思路）
+4) 巡视            multicam.grid / gridLayout → page/nextPage/prevPage 分页查看
+5) 切换            selectCameraN 巡视 → cutToCameraN 落点；或 recordStart 实时切 → recordStop
+6) 音频            multicam.audioFollowsVideo（切画面同时切音源）或统一用外部录音轨
+7) 影调统一        各机位分别 lumetri.applyMatch 到同一参考（跨机位跳色是多机位最扎眼的问题）
+8) 响度统一        essentialSound.setType("dialogue") → autoMatch（不同机位的电平差异必须先拉平）
+9) 导出            见 artcraft-delivery-qc
+```
+
+## 三、切换节奏（把 multicam 当成剪辑来做）
+
+| 原则 | 说明 |
+|---|---|
+| **切点落在动作中** | 与单机剪辑同理：动作进行中切最隐蔽 |
+| **切点落在说话人变化** | 谁说话给谁（除非刻意给反应镜头） |
+| **视线匹配** | 切到对方视角前，先给一个"看向"的镜头 |
+| **不要机械交替** | A/B/A/B 交替=监控录像感；按叙事需要停留 |
+| **反应镜头有价值** | 听话者的表情常比说话者更有信息 |
+| **一次切换一个理由** | 说不出理由的切换就删掉 |
+| **节奏与内容同向** | 争论加快、抒情放慢（见 artcraft-edit-rhythm） |
+
+## 四、多机位一致性问题（多机位专属）
+
+| 问题 | 原因 | 处理 |
+|---|---|---|
+| 画面跳色 | 各机位白平衡/曝光不同 | 逐机位 `lumetri.applyMatch {referenceTime}` 到同一参考 |
+| 声音跳电平 | 各机位话放/距离不同 | 统一 `essentialSound.setType("dialogue")` + `autoMatch {target:-14}` |
+| 相位/回声 | 多路同源音频叠加 | 只用一路主音（通常外录），其余静音或 `audioFollowsVideo` 但只留一路 |
+| 音频不同步 | 各机位时钟漂移 | 先按音频对齐（长素材必须做漂移校正）；短片用拍手点对齐 |
+| 预览卡顿 | 多路同时解码 | `multicam.autoAdjustQuality`、降低预览分辨率、用代理（`media.createProxies`） |
+
+## 五、多机位素材的准备与代理
+
+- 大素材（4K/多机位）**先建代理**：`media.createProxies` → `media.attachProxies` → 剪辑用代理 → 导出前 `media.reconnectFullRes`（否则交付代理画质）。
+- 素材健康：`media.status` / `media.findMissing` / `media.autoRelink`（换机器后必备）。
+- 素材变更：`media.refreshChanged`（源文件被重新转码后）或 `media.replaceFootage`（保留剪辑替换素材）。
+
+## 六、质检清单
+
+- [ ] 各机位影调统一（示波器/矢量读数接近）
+- [ ] 对白响度统一，且只用一路主音（无回声/相位问题）
+- [ ] 音画同步（长素材已做漂移校正）
+- [ ] 切换有理由（无机械交替）
+- [ ] 反应镜头与视线匹配到位
+- [ ] 导出前已切回全分辨率（代理已断开）
+- [ ] `artcraft_qc` 通过（规格/画幅/响度）

package/skills/artcraft-ops/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: artcraft-ops
+description: ArtCraft 家族 13 个应用的调用基本功——用哪个成员、走哪条通道（无头 CLI / 控制通道 / HTTP 任务）、怎么自发现命令与前置条件、怎么探-改-验、长任务与批量怎么编排。任何要驱动 ArtCraft 家族完成视频/图像/音频/文档后期的任务，先读本技能再动手。
+---
+
+# ArtCraft 家族调用基本功
+
+ArtCraft 是 13 个同源桌面应用的家族，**每个菜单项、滑块、对话框都是一条命令**；同一套命令既能从无头 CLI 调用，也能走运行中应用的 JSON 控制通道。本技能教你"怎么调得顺"，不涉及创作判断（创作判断见 artcraft-shot-language / edit-rhythm / color-light / sound-design / motion-vfx / delivery-qc）。
+
+## 一、成员职责矩阵（先选对人）
+
+| 需求 | 成员 | 关键命令族 |
+|---|---|---|
+| 图像编辑、批处理、动作 | **PhotoCraft** | `filter.*`(62 滤镜) `image.adjustments.*` `actions.*` `file.automate.*` |
+| 矢量插画、透视作图、数据驱动图形 | **VectorCraft** | `object.*` `perspective.*` `dataset.*` `symbol.*` |
+| 剪辑、字幕、转写、多机位、调色、混音 | **FilmCraft** | `timeline.*` `trim.*` `captions.*` `transcript.*` `graphics.*` `lumetri.*` `essentialSound.*` `multicam.*` `tts.*` |
+| 照片库、RAW 冲洗、批量影调 | **LightCraft** | `develop.*`(122 控制) `preset.*` `mask.*` `crop.*` `denoise.*` |
+| PDF 阅读/整理/保护/OCR/无障碍 | **PdfCraft** | `page.*` `edit.*` `ocr.*` `measure.*` `a11y.*` `protect.*` |
+| 合成、动效、跟踪、抠像、3D 机位 | **EffectCraft** | `effect.*`(307 效果) `keys.*` `essential.*` `track.*` `roto.*` `camera.*` `puppet.*` |
+| 页面排版、出版、表格排版 | **DesignCraft** | `object.*` `style.*` `type.*` `layout.*` `book.*` `article.*` |
+| 写作、修订、文献引用 | **WordCraft** | `para.*` `format.*` `styles.*` `review.*` `references.*` |
+| 演示、幻灯片、动效转场 | **DeckCraft** | `slide.*` `shape.*` `animation.*` `transition.*` `design.*` |
+| 表格、数据、透视表、图表 | **GridCraft** | `formulas.*` `data.*` `pivot.*` `chart.*` `slicer.*` |
+| 制图、标注、图纸布局 | **CADCraft** | `arc.*` `circle.*` `dimstyle.*` `layout.*` `vports.*` `blocks.*` |
+| 音频录制/编辑/混音/母带 | **SoundCraft** | `mix.*` `automation.*` `track.*` `event.*` `file.bounce_*` |
+| UI/设计系统、原型、Dev 交付 | **FigCraft** | `component.*` `instance.*` `variable.*` `style.*` `proto.*` `inspect.*` |
+
+跨界组合是常态：**剪辑在 FilmCraft，合成元素在 EffectCraft，影调可走 LightCraft，声音在 SoundCraft，分镜图文用 DeckCraft/DesignCraft/FigCraft，数据用 GridCraft**。
+
+## 二、三条通道怎么选（最关键的一步）
+
+| 通道 | 何时用 | 入口 |
+|---|---|---|
+| **无头 CLI** | 一次性、可批处理、可脚本、要确定性产物 | `artcraft_cli { bin, args }` |
+| **控制通道**（运行中的 App） | 要"边看边调"、要读界面状态、要截图验证 | `artcraft_control { app\|port, method, params }` |
+| **HTTP 任务** | 长渲染（分钟~小时），不能占住请求 | `POST /artcraft/api/job` → 轮询 → `GET /artcraft/api/file` |
+
+控制通道默认端口：`filmcraft 9876`、`effectcraft 9877`、`vectorcraft 7979`、`lightcraft 7980`。其余成员端口动态：以 `app --port PORT` 启动后，向 `artcraft_control` 传 `port` 直连。PhotoCraft 控制通道是令牌鉴权变体、PdfCraft 是文件式（`--control FILE`），两者走无头 CLI。
+
+**判断口诀**：能一次跑完 → CLI；需要中途看/改 → 控制通道；超过 1 分钟 → HTTP 任务。
+
+## 三、自发现三件套（不要背命令，要会查）
+
+| 机制 | 用法 | 得到什么 |
+|---|---|---|
+| `commands [--json]` | `artcraft_cli { bin:"filmcraft", args:["commands","--json"] }` | 全量命令：id / label / 菜单路径 / params / 快捷键 |
+| **`describe <id>`** | `artcraft_cli { bin:"soundcraft", args:["describe","file.bounce_stems"] }` | params + `enabled` + **`disabled_reason`** + `where:`（界面位置） |
+| `exec app.capabilities` | EffectCraft 专用 | 命令数 / 效果数 / 导出格式 / 表达式支持 |
+
+`describe` 是"顺畅"的关键：**先问能不能跑，再跑**。典型 `disabled_reason`：「make an edit selection first」「the session has no tracks」——看到就先满足前置条件，别硬跑。
+
+枚举服务（要用哪个清单就调哪个）：
+
+| 要什么 | 调什么 |
+|---|---|
+| 转场清单 | DeckCraft `transition.list`；FilmCraft `sequence.applyVideoTransition`（params 内枚举） |
+| 动画预设 | FilmCraft `animation.list`(DeckCraft 同名) |
+| 调色预设 | FilmCraft `lumetri.presets` / `presets.list`；LightCraft `preset.*` |
+| LUT | FilmCraft `lut.list`；LightCraft `develop.controls` |
+| 图形模板 | FilmCraft `graphics.template.list`（.fcgt，支持 `values` 传参渲染） |
+| 语音模型 / 音色 | FilmCraft `transcript.models` / `tts.voices` |
+| 抠像模型 | EffectCraft `roto.models`（可 `roto.model.download`） |
+| 色彩空间 | FilmCraft `color.spaces` |
+| 示波器 | FilmCraft `scopes.read`（waveform/parade/histogram/vectorscope…） |
+| 表格函数 | GridCraft `formulas.functions` |
+| 素材目录检索 | LightCraft `catalog.query` / `catalog.stats` |
+
+## 四、纪律：探 → 改 → 验
+
+1. **探**：任何媒体在动手前先探——`photocraft info`、`filmcraft probe`、`pdfcraft info`、`soundcraft info`、`lightcraft run app.info`、`vectorcraft info`、`wordcraft info`、`deckcraft info`、`gridcraft info`、`cadcraft info`、`figcraft info`。用**实测事实**（时长/帧率/分辨率/色彩/音轨布局）决定策略，不要凭文件名猜。
+2. **改**：
+   - **无损优先**：能流拷贝就流拷贝（`-c copy` 类操作），只在必须时重编码（精确到帧的剪切、滤镜、格式变换）。
+   - **关键帧对齐**：流拷贝剪切会落到最近的关键帧；要求精确到帧就显式要求重编码。
+   - **一次一步**：改一步、验一步；不要连续叠三步无法定位的重编码。
+3. **验**：产物必须复核——`probe`/`info` 看客观参数；画面类改动用 `ui.screenshot`（EffectCraft/FilmCraft 控制通道）或 `photocraft render`/`deckcraft render` 出图，**由你（多模态）亲眼确认**，而不是相信退出码 0。
+
+## 五、长任务与批量
+
+- **长渲染**：`POST /artcraft/api/job { bin, args, outputs }` 拿到 `id` → `GET /artcraft/api/job?id=…&tail=30` 轮询 `status`（running/done/failed/timeout）与 `outputs[].exists` → `GET /artcraft/api/file` 取回。不要用 CLI 同步阻塞几十分钟。
+- **批处理**：
+  - PhotoCraft：`batch --actions <actions.json> --in <dir> --out <dir>`；或 `droplet <file.pcdroplet>`
+  - FilmCraft：`run <script.jsonl>`（每行一条 `{"id","params"}`，`#` 可注释）
+  - DeckCraft/DesignCraft/SoundCraft：`run [--cmd 'id={json}']…` 或 `script <file>`
+  - FigCraft：`run <script.json|jsonl>`
+  - GridCraft：`--script FILE.jsonl`
+- **批量共通**：先在一份样本上跑通，再全量；输入/输出目录分开，**绝不覆盖原片**（家族多数工具默认新文件名，如需覆盖要显式授权）。
+
+## 六、路径与产物约定（本插件只是桥）
+
+- 路径由调用方决定，**必须绝对路径**；对话调用落在当前工作空间，画布调用落在项目目录。
+- 推荐三件套布局：`media/`（素材）· `craft/`（工程文件与中间产物）· `out/`（成片与交付物）。
+- 工程文件随成员而异：`.pcraft`（PhotoCraft）· `.fcproj`（FilmCraft）· `.ecproj`（EffectCraft）· `.scraft`（SoundCraft）· `.figcraft`（FigCraft）· `.mlt` 类交换走 FilmCraft `file.exportInterchange`。
+- 跨成员交付用交换格式：**FilmCraft `file.exportInterchange` 支持 edl / xml / fcpxml / otio / aaf / omf**；音频交接用 `file.exportAaf`/`file.exportOmf`（含 handles、breakoutToMono）。
+
+## 七、常见失败与对策
+
+| 症状 | 原因 | 对策 |
+|---|---|---|
+| 命令报 unknown command | 版本差异或写错 id | 先 `commands [--json]` 或 `commands <filter>` 核对 |
+| `enabled:false` | 前置条件未满足 | 读 `disabled_reason`，先做选择/建轨/开工程 |
+| 剪切点偏移 | 流拷贝对齐关键帧 | 要求帧精确（重编码）或接受关键帧吸附 |
+| 手机/录屏素材时间轴错乱 | 可变帧率(VFR) | 先探 VFR，必要时先统一恒定帧率 |
+| 路径错误 | 传了相对路径 | 一律绝对路径（或 base + rel 组合） |
+| 控制通道连不上 | App 未以 `--control` 启动 | 先启动带控制通道的实例，或改用无头 CLI |
+| 产物"看起来没生效" | 只信退出码 | 探产物 + 出图复核 |
+
+## 八、最小工作流模板
+
+```
+1) 探    artcraft_cli { bin:"<app>", args:["info"|"probe", "<file>"] }
+2) 查    artcraft_cli { bin:"<app>", args:["commands","--json"] }        # 找到族
+         artcraft_cli { bin:"<app>", args:["describe","<id>"] }          # 看 params/前置
+3) 干    短任务 → artcraft_cli；要看/要改 → artcraft_control；长任务 → HTTP job
+4) 验    probe/info + 出图复核（ui.screenshot / render）
+5) 交    out/ 下命名规范产物；需要跨软件 → file.exportInterchange
+```

package/skills/artcraft-ops/references/command-families.md

@@ -0,0 +1,57 @@
+# ArtCraft 13 成员命令族总表（实测）
+
+> 来源：2026-10 在本机对 13 个成员 CLI 的 `commands` 注册表实测。
+> 精确条目数来自 JSON 注册表（`commands --json`：filmcraft / effectcraft / photocraft / gridcraft / wordcraft / figcraft），其余为 id 扫描值（近似）。
+> 随时复核：`artcraft_cli { bin:"<app>", args:["commands","--json"] }`（不支持 `--json` 的成员直接 `commands`）。
+
+## 规模总览
+
+| 成员 | 命令数 | 版本实测 | 定位 |
+|---|---:|---|---|
+| EffectCraft | 731（含 **307 效果**） | 0.10.0 | 合成 / 动效 / VFX |
+| FilmCraft | 701 | 0.8.0 | 剪辑 / 字幕 / 调色 / 混音 |
+| FigCraft | 552 | — | 界面设计与原型 |
+| SoundCraft | 478 | 0.7.0 | 音频后期 / 混音 |
+| VectorCraft | 385 | 0.11.0 | 矢量插画 |
+| PhotoCraft | 364（**62 滤镜**） | 0.9.0 | 图像 / 影调 |
+| WordCraft | 299 | 0.7.0 | 写作 / 文档 |
+| DesignCraft | 279 | 0.8.0 | 页面排版 / 出版 |
+| LightCraft | 192（**122 develop 控制**） | 0.8.0 | 照片 / RAW 冲洗 |
+| DeckCraft | 165 | 0.7.0 | 演示 / 幻灯片 |
+| CADCraft | 139 | 0.7.0 | 制图 |
+| GridCraft | 115 | 0.7.0 | 表格 / 数据 |
+| PdfCraft | 71（**86 个可运行工具**） | 0.8.0 | PDF / 文档质检 |
+
+## 各成员主要命令族
+
+| 成员 | 主要族（数量） |
+|---|---|
+| FilmCraft | `graphics` 82 · `clip` 57 · `file` 57 · **`timeline` 56** · `sequence` 45 · `project` 40 · `edit` 39 · **`multicam` 35** · `markers` 32 · **`trim` 24** · **`captions` 22** · `mixer` 20 · `export` 19 · `effects` 16 · **`transcript` 14** · `masks` 12 · `essentialSound` 9 · **`lumetri` 7** · **`tts` 7** · `lut` 4 · `scopes` 1 · `color` 1 |
+| EffectCraft | `layer` 121 · `view` 78 · `file` 61 · **`keys` 36** · `comp` 31 · `edit` 27 · **`track` 22** · **`essential` 22** · `renderQueue` 20 · `effect` 19 · **`camera` 19** · `prop` 18 · `mask` 17 · `time` 17 · **`roto` 14** · `text` 13 · `footage` 12 · **`puppet` 10** |
+| FigCraft | `text` 52 · `view` 48 · `vector` 40 · `object` 27 · `tool` 21 · `select` 21 · **`component` 21** · `collab` 20 · `file` 20 · **`proto` 20** · `library` 18 · **`variable` 18** · `edit` 15 · `comment` 14 · `plugin` 11 · **`style` 10** · `version` 8 · `instance` 8 · `annotation` 8 · `branch` 7 |
+| SoundCraft | `view` 96 · `edit` 93 · **`track` 65** · `event` 35（含 **`beat_detective`/`identify_beat`/`extract_chords`**） · `options` 35 · `clip` 31 · **`mix` 29** · `setup` 20 · `file` 17（**`bounce_mix`/`bounce_stems`**） · `transport` 13 · **`session` 11（含 `audio_health`）** · **`automation` 10** |
+| VectorCraft | **`object` 71** · **`perspective` 24** · `select` 18 · `file` 17 · `swatch` 15 · `document` 12 · `layer` 11 · `path` 11 · **`symbol` 10** · **`dataset` 10** |
+| PhotoCraft | **`filter` 62**（gallery 47 / blur 11 / stylize 9 / distort 9 / render 9 / pixelate 7 / blurGallery 5 / noise 5 / sharpen 5 …） · `edit` 31 · `layer` 26 · `select` 19 · `file.automate` 18 · `channel` 18 · **`actions` 14** · `brush` 13 · `paint` 12 · `gradient` 12 · **`image.adjustments` 9** |
+| WordCraft | `para` 28 · `format` 25 · `file` 18（含 `accessibility`） · **`review` 16** · `equation` 15 · `insert` 15 · `table` 14 · `view` 13 · `select` 12 · `picture` 11 · `styles` 11 · **`references` 10** · `mailings` 9 |
+| DesignCraft | `object` 22 · **`style` 17** · `file` 15 · `transform` 10 · `data` 10 · `type` 10 · `library` 8 · `layout` 7 · `book` 7 · `article` 6 · `table` 7 |
+| LightCraft | `library` 20 · **`faces` 17** · **`denoise` 16** · **`develop` 16（122 控制 / 14 分区）** · `photo` 14 · `mask` 12 · `keyword` 12 · `preset` 9 · `crop` 6 · `stack` 6 · `version` 5 · `history` 5 |
+| DeckCraft | `format` 32 · `shape` 19 · `slide` 15 · `file` 13 · **`animation` 10** · `text` 10 · `edit` 9 · `media` 7 · `insert` 7 · `arrange` 7 · **`design` 5** · **`transition` 4** |
+| CADCraft | `table` 11 · `arc` 10 · `zoom` 9 · **`dimstyle` 7** · `blocks` 6 · `grip` 6 · `layout` 6 · `layerstate` 5 · `vports` 5 · `circle` 5 |
+| GridCraft | `home` 12 · **`pivot` 11** · `insert` 10 · **`data` 10** · `view` 9 · `sheet` 8 · `edit` 7 · `file` 7 · `selection` 6 · **`formulas` 5** · `chart` 3 · `slicer` 3 |
+| PdfCraft | `edit` 13 · `page` 10 · **`measure` 7** · **`a11y` 5** · `export` 4 · `ocr` 3 · `form` 3 · `comment` 3 · `protect` 2 · `sign` 2（另有 86 个可 `run` 的工具，含 `a11y.check`/`a11y.report`/`measure.info`/`optimize.reduce`/`standards.pdfa`/`doc.compare`） |
+
+## 自发现三件套
+
+| 需求 | 命令 |
+|---|---|
+| 全部命令 | `commands [--json]`（部分成员支持 `--filter TEXT`） |
+| 单命令参数与前置 | `describe <id>` → params / enabled / **disabled_reason** / where |
+| 能力总览 | EffectCraft：`exec app.capabilities` → 命令数 / 效果数 / 导出格式 / 表达式 |
+| 枚举型清单 | `transition.list`（DeckCraft）· `animation.list` · `lumetri.presets` · `presets.list` · `graphics.template.list` · `lut.list` · `roto.models`（EffectCraft）· `transcript.models` · `tts.voices` · `color.spaces` · `formulas.functions`（GridCraft）· `catalog.query`（LightCraft） |
+| 探针 | `probe`（FilmCraft）· `info`（PhotoCraft/VectorCraft/PdfCraft/WordCraft/DeckCraft/GridCraft/CADCraft/FigCraft/SoundCraft）· `develop.controls`（LightCraft） |
+
+## 使用的注意点
+
+- **参数名随成员而异**：FilmCraft/EffectCraft 用 `params` JSON；SoundCraft 用 `key=value`；LightCraft 用 `control=<id> value=<v>`；GridCraft 用 `--cmd 'id={json}'`。
+- **前置条件是硬门槛**：先 `describe`，看到 `enabled:false` 就按 `disabled_reason` 先满足条件（建轨、开工程、做选择）。
+- **端口**：控制通道默认 filmcraft 9876 / effectcraft 9877 / vectorcraft 7979 / lightcraft 7980，其余动态（`app --port` 后用 `port` 直连）。

package/skills/artcraft-shot-language/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: artcraft-shot-language
+description: 镜头语言设计——景别、机位、角度、运动、构图、光线、轴线、覆盖拍摄与分镜的"何时用/何时别用"决策表，并把每种语法映射到 ArtCraft 家族可执行命令（EffectCraft camera/view/layer、FilmCraft graphics/timeline、LightCraft develop、VectorCraft perspective、FigCraft layout）。用于分镜设计、镜头选择、画面构图与机位调度。
+---
+
+# 镜头语言：判断 → 语法 → 命令
+
+先问三个问题，再选语法：**这场戏要让观众感到什么？信息给谁、瞒谁？权力关系如何用站位与机位表达？** 想清楚再落到下面的表。
+
+## 一、景别（决定"观众离角色多远、知道多少"）
+
+| 景别 | 叙事功能 | 何时用 | 何时别用 | ArtCraft 落点 |
+|---|---|---|---|---|
+| 大远景 ELS | 交代环境、人的渺小 | 开场、转场、孤立感 | 对话戏 | EffectCraft 3D 视图/大场景；LightCraft 宽裁切 |
+| 远景 LS | 空间关系、人物全身+环境 | 建立镜头、群戏 | 情绪特写 | FilmCraft 时间线选镜；LightCraft `crop.aspect` |
+| 全景 FS | 全身、动作完整 | 动作段落、调度展示 | 内心戏 | FilmCraft `graphics.*` 构图参考 |
+| 中景 MS | 对话主力景别 | 常规对话 | 强调细节时 | 剪辑节奏见 artcraft-edit-rhythm |
+| 中近景 MCU | 情绪开始进入 | 对话升级、微表情 | 大动作 | EffectCraft 合成裁切/放大 |
+| 近景 CU | 情绪、心理 | 情绪峰值、关键台词 | 交代空间 | EffectCraft `layer.*` 缩放关键帧 |
+| 大特写 ECU | 压迫、细节符号 | 反转、道具暗示 | 长段落 | PhotoCraft `filter.*` 强化质感 |
+
+**交替规则**：相邻镜头避免同景别硬接（除非刻意"跳轴式"冲击）；情绪上升时景别递进（MS→MCU→CU），段落收束回到 LS 交代。
+
+## 二、机位与角度（决定"谁强谁弱"）
+
+| 角度 | 心理效果 | 何时用 | 落点 |
+|---|---|---|---|
+| 平视 | 平等、客观 | 常态对话 | 基准 |
+| 仰拍 | 压迫感、权威 | 强者、威胁、英雄化 | EffectCraft 3D `camera.orbit/pan` 抬高机位 |
+| 俯拍 | 弱势、被审视 | 失败、屈服、全景调度 | 同上，机位下压 |
+| 斜角 Dutch | 失衡、不安 | 危机、精神异常 | EffectCraft `layer.*` 旋转 |
+| 过肩 OTS | 对话关系、代入 | 正反打 | 双人机位对切 |
+| 主观 POV | 强代入 | 惊悚、代入角色视线 | 与视线匹配剪辑配合 |
+| 鸟瞰/虫视 | 极致权力差 | 强调、类型化 | 特例，慎用 |
+
+**轴线铁律**：保持 180° 轴线，越轴会让空间"翻转"让人失忆。需要越轴时用**中性镜头**或**运动越轴**过渡。到 ArtCraft 落点：在分镜/调度阶段就用 FigCraft/DeckCraft 画**俯视调度图**（站位+走位线+机位+灯位+轴线），**在图纸期消灭跳轴**。
+
+## 三、运动（决定"情绪是推上去还是压下来"）
+
+| 运动 | 语义 | 何时用 | 何时别用 |
+|---|---|---|---|
+| 推 / 前移 | 进入、聚焦、压迫 | 强调、揭示 | 每镜都推=廉价 |
+| 拉 / 后移 | 抽离、揭示环境、失落 | 段落收尾、反转 | 情绪正高时 |
+| 摇 pan | 展示空间、跟随 | 环境交代 | 快速摇易糊 |
+| 移 track | 伴随、沉浸 | 走廊、跟随 | 无动机时 |
+| 升降 crane | 宏大、命运感 | 开场/结尾 | 小场景 |
+| 跟 follow | 参与感 | 动作、行走 | 稳定器缺失时 |
+| 手持 | 真实、紧张 | 纪实、冲突 | 精致产品镜头 |
+| **变焦 vs 位移** | 变焦=机械抽离；位移=观众移动 | 变焦做"惊觉"，位移做"进入" | 二者混用会晕 |
+| 环绕 orbit | 仪式感、审视 | 英雄时刻 | 对话 |
+
+ArtCraft 落点：EffectCraft **`camera.orbit` / `camera.pan` / `camera.dolly`**（3D 机位）、`camera.fromView`、`camera.orbitNull`；2D 素材用 `layer.*` 的位移/缩放关键帧 + `keys.easyEase*` 缓动；FilmCraft 用 `effects.setParam` + `effects.addKeyframe` 做运动/缩放。
+
+**运动铁律**：**单镜单向**（一个镜头一个运动方向），起幅与落幅都要有"到达感"；缓动用 `keys.easyEase` / `keys.easyEaseIn/Out`，避免线性生硬。
+
+## 四、构图（画面内"眼睛往哪走"）
+
+| 法则 | 用途 | 落点 |
+|---|---|---|
+| 三分法 | 通用平衡 | 参考线：FigCraft `grid.*` / `layout.*`；VectorCraft `view.guides.*` |
+| 中心构图 | 仪式感、对峙 | FilmCraft `graphics.alignFrame.hcenter/vcenter` |
+| 对称 | 秩序/压迫 | 同上 + 精确对齐 |
+| 框式构图 | 窥视、层次 | 前景元素放置（`graphics.arrangeLayer`） |
+| 引导线 | 视线导向主体 | 透视作图 VectorCraft `perspective.grid/snap` |
+| 负空间 | 孤独、留白 | 主体偏移，`graphics.nudge*` 微调 |
+| 视线空间 | 人物"看向"要留空 | 主体偏左则留右 |
+| 头顶空间 | 太挤显压抑、太空显漂浮 | 微调 `graphics.nudgeUp/Down` |
+| 前景/中景/远景层次 | 纵深感 | 分层合成（EffectCraft `layer.*`） |
+
+安全区：字幕/图形用 FilmCraft `graphics.*` 的**安全区与响应式设计**（`graphics.setResponsiveTime`、`graphics.pin`），竖屏另有平台安全区。
+
+## 五、光线（决定"质感与情绪底色"）
+
+| 光型 | 效果 | 何时用 | 落点 |
+|---|---|---|---|
+| 主光 + 辅光 | 常规立体 | 多数场景 | LightCraft `light.*`（曝光/对比/高光/阴影/白/黑） |
+| 轮廓光 rim | 分离主体与背景 | 暗背景、人物 | LightCraft `grading.highlights.*`；EffectCraft 光效层 |
+| 伦勃朗光 | 戏剧肖像 | 人物特写 | `grading.*` 分区色调 |
+| 明暗对照 chiaroscuro | 强对比、压迫 | 悬疑/权谋 | `light.contrast` + `curve.*` |
+| 实用光 practical | 真实感光源入画 | 夜戏、室内 | 合成光效（EffectCraft `effect.*`） |
+| 黄金时刻 | 温暖、怀旧 | 情感段落 | LightCraft `wb.temp/tint` + `grading` |
+| 无源光 | **大忌**：光没有来源 | —— | 调度图阶段标注灯位即可避免 |
+
+**光比**：情绪越紧、光比越大；写实场景 4:1~6:1，惊悚可 8:1 以上。
+
+## 六、焦点与景深
+
+- 浅景深引导注意；深景深展示调度。
+- EffectCraft：`camera.setFocusToLayer` / `camera.linkFocusToLayer`（焦点跟随）、`camera.linkFocusToPoi`（对焦兴趣点）；镜头虚化用 `effect.*` 中的模糊族（Blur & Sharpen 共 16 个）。
+- PhotoCraft：`filter.blurGallery.*`（tiltShift/irisBlur/fieldBlur/spinBlur/pathBlur）做选择性虚化；`filter.blur.*` 做整体虚化。
+
+## 七、覆盖拍摄与分镜（把语法变成可执行清单）
+
+标准覆盖：**主镜头（Master）→ 中景对话 → 反应镜头 → 插入镜头（手/道具/细节）→ 特写情绪点**。
+
+分镜最小字段（写进分镜表，供后续执行）：
+`镜号 · 景别 · 角度 · 运动(方向/幅度/起落幅) · 时长 · 画面内容 · 光线 · 声音 · 转场`
+
+ArtCraft 承载：**FigCraft**（画板/组件/原型，做可交互分镜与界面资产）· **DeckCraft**（幻灯片式分镜）· **DesignCraft**（图文版面/画册）· **GridCraft**（镜头数据表：排序/筛选/透视）· **FilmCraft**（时间线落地；`markers.*` 标注镜头点）。
+
+## 八、速查：从意图到命令
+
+| 意图 | 首选命令族 |
+|---|---|
+| 设计机位/运镜 | EffectCraft `camera.*`、`view.3d.*`、`layer.*`+`keys.*` |
+| 画面内文字/图形构图 | FilmCraft `graphics.*`（新文本/形状/对齐/分布在帧·组·选区三个层级） |
+| 透视/等距作图 | VectorCraft `perspective.grid.define/preset/snap` |
+| 界面与布局资产 | FigCraft `layout.*`、`grid.*`、`component.*` |
+| 影调与光线 | LightCraft `develop.*`（见 artcraft-color-light） |
+| 分镜表与调度图 | DeckCraft `slide.*`、DesignCraft `object.*`、GridCraft `data.*` |
+
+> 判断优先于语法：**先定情绪与信息，再选景别与运动**；语法服务于叙事，不为炫技而动镜头。

package/skills/artcraft-shot-language/references/shot-vocabulary.md

@@ -0,0 +1,98 @@
+# 镜头语言速查词表（景别 · 机位 · 运动 · 构图 · 光线）
+
+> 本表是 `../SKILL.md` 的紧凑查表版：每行 = 术语 → 叙事功能 → 何时用 → 何时别用 → 家族落点。
+> 家族落点命令见 `artcraft-ops/references/command-families.md`；运镜实现在 EffectCraft `camera.*` / `view.3d.*`。
+
+## 一、景别（8 级）
+
+| 术语 | 英文 | 叙事功能 | 何时用 | 何时别用 |
+|---|---|---|---|---|
+| 大远景 | ELS | 环境即主题、人的渺小 | 开场、段落转场、孤独 | 对话戏、细节 |
+| 远景 | LS | 空间关系、群像 | 建立镜头、调度展示 | 情绪刻画 |
+| 全景 | FS | 全身动作完整 | 动作段落、舞蹈 | 内心戏 |
+| 中景 | MS | 对话主力 | 常规对话、信息交换 | 强调细节 |
+| 中近景 | MCU | 情绪进入 | 对话升级、微表情 | 大动作 |
+| 近景 | CU | 情绪、心理 | 情绪峰值、关键台词 | 交代空间 |
+| 大特写 | ECU | 压迫、符号 | 反转、道具暗示 | 长段落 |
+| 插入特写 | INSERT | 强调物件/手部 | 细节交代 | 无信息量时 |
+
+**节奏规则**：相邻镜头避免同景别硬接；情绪上升递进（MS→MCU→CU）；段落收束回 LS。
+
+## 二、机位与角度（9 种）
+
+| 角度 | 心理效果 | 何时用 |
+|---|---|---|
+| 平视 | 平等、客观 | 常态对话（基准） |
+| 仰拍 | 权威、压迫、英雄化 | 强者、威胁、宣言 |
+| 俯拍 | 弱势、被审视 | 失败、屈服、俯瞰调度 |
+| 鸟瞰/上帝视角 | 命运感、宿命 | 开场/结尾、宏观 |
+| 虫视 | 极端压迫 | 强对比、类型化 |
+| 斜角 Dutch | 失衡、不安 | 危机、精神异常 |
+| 过肩 OTS | 关系、代入 | 正反打对话 |
+| 主观 POV | 强代入 | 惊悚、视角绑定 |
+| 反打 reverse | 对话闭环 | 正反打配对 |
+
+**轴线**：保持 180°；越轴用中性镜头或运动越轴过渡。**在调度图阶段标出轴线**（FigCraft/DeckCraft 画俯视图）。
+
+## 三、运动（12 种）
+
+| 运动 | 语义 | 何时用 | 何时别用 |
+|---|---|---|---|
+| 推 in | 进入、聚焦、压迫 | 强调、揭示 | 每镜都推=廉价 |
+| 拉 out | 抽离、揭示环境 | 段落收尾、反转 | 情绪正高时 |
+| 摇 pan | 展示空间、跟随 | 环境交代、横向转移 | 快速摇易糊 |
+| 移 track | 伴随、沉浸 | 走廊、跟随人物 | 无动机时 |
+| 升降 crane | 宏大、命运 | 开场/结尾 | 小场景 |
+| 跟 follow | 参与感 | 动作、行走 | 无稳定器时 |
+| 手持 | 真实、紧张 | 纪实、冲突 | 精致产品镜头 |
+| 环绕 orbit | 仪式感、审视 | 英雄时刻、产品 | 对话戏 |
+| 甩 whip pan | 突发、连接 | 转场、惊喜 | 频繁使用 |
+| 变焦 zoom | 机械抽离/惊觉 | 强调突变 | 与位移混用（晕） |
+| 位移 dolly | 观众移动/进入 | 沉浸、揭示 | 无动机时 |
+| 静态固定 | 稳定、观察 | 对话、构图展示 | 长段落无变化（闷） |
+
+**单镜单向**：一个镜头一个运动方向；起幅与落幅要有"到达感"；缓动（`keys.easyEase*`）是默认。
+
+## 四、构图（12 条）
+
+| 法则 | 用途 | 落点 |
+|---|---|---|
+| 三分法 | 通用平衡 | FigCraft `grid.*` / VectorCraft `view.guides.*` |
+| 中心构图 | 仪式、对峙 | FilmCraft `graphics.alignFrame.hcenter/vcenter` |
+| 对称 | 秩序/压迫 | 精确对齐（同上） |
+| 框式 | 窥视、层次 | 前景元素（`graphics.arrangeLayer`） |
+| 引导线 | 视线导向 | VectorCraft `perspective.grid/snap` |
+| 负空间 | 孤独、留白 | 主体偏移（`graphics.nudge*`） |
+| 视线空间 | 看向方向留空 | 主体偏左留右 |
+| 头顶空间 | 挤压/漂浮感 | `graphics.nudgeUp/Down` |
+| 前景/中景/远景 | 纵深 | EffectCraft 分层合成 |
+| 重复与韵律 | 秩序美感 | 符号/组件复用（VectorCraft `symbol.*`） |
+| 打破对称 | 张力 | 斜角、偏心 |
+| 明暗对比引导 | 视觉落点 | LightCraft `grading.*` / 光效层 |
+
+## 五、光线（10 种）
+
+| 光型 | 效果 | 何时用 | 落点 |
+|---|---|---|---|
+| 主光+辅光 | 常规立体 | 多数场景 | LightCraft `light.*` |
+| 轮廓光 rim | 分离背景 | 暗背景人像 | `grading.highlights.*` |
+| 伦勃朗光 | 戏剧肖像 | 人物特写 | `grading.*` 分区 |
+| 明暗对照 | 强对比压迫 | 悬疑/权谋 | `light.contrast` + `curve.*` |
+| 顺光/平光 | 干净、无阴影 | 商业、美妆 | 减对比 |
+| 侧光 | 质感、立体 | 人物、产品 | `detail.sharpenAmount` 配合 |
+| 逆光 | 氛围、剪影 | 情绪段落 | 高光处理 |
+| 实用光 | 真实光源入画 | 夜戏、室内 | EffectCraft 光效层 |
+| 黄金时刻 | 温暖、怀旧 | 情感段落 | `wb.temp/tint` + `grading` |
+| 无源光 | **大忌**：光无来源 | —— | 调度图标注灯位即可避免 |
+
+**光比**：写实 4:1–6:1；悬疑/惊悚 8:1 以上；喜剧/商业 2:1–3:1。
+
+## 六、检查清单（分镜/拍摄前）
+
+- [ ] 每镜有明确景别与角度，且相邻不重复
+- [ ] 运动单镜单向，有起落幅
+- [ ] 轴线一致（调度图画过）
+- [ ] 主体有视线空间/头顶空间
+- [ ] 光有来源（灯位已标）
+- [ ] 情绪目标一句话能说清（见 artcraft-style-bible 命门句）
+- [ ] 关键镜头有覆盖（主镜+插入+反应）