fal Seedance 是一个用于 fal.ai Seedance 视频生成的技能，适合处理涉及 fal.ai Seedance、reference-to-video、image-to-video，或用于故事板/风格探索的 Seedance canaries 的任务。
默认通道
ref2v 端点：bytedance/seedance-2.0/reference-to-video（全质量，支持 1080p、多动作镜头、导演级镜头控制）。迭代 prompt 时若要更便宜更快，可传入 --endpoint bytedance/seedance-2.0/fast/reference-to-video 切换为变体。
i2v（image-to-video，确定性 start→end 变形）同时支持 Seedance 与 Kling 两个系列。
Seedance 相关端点：
- bytedance/seedance-2.0/image-to-video（默认）
- bytedance/seedance-2.0/fast/image-to-video
Kling O3 相关端点：
- fal-ai/kling-video/o3/standard/image-to-video（干净基线）
- fal-ai/kling-video/o3/pro/image-to-video（更高质量，当 standard 输出偏软或异常时推荐）
- fal-ai/kling-video/o3/4k/image-to-video（最高档位）
Kling V3 相关端点：
- fal-ai/kling-video/v3/standard/image-to-video
- fal-ai/kling-video/v3/pro/image-to-video
Kling 端点不接受 --resolution 与 --generate-audio，CLI 会自动剔除这两个参数。当 Seedance 在平滑或奶油色背景上出现色度噪点（chroma-noise）时，可切换到 Kling。
默认分辨率：1080p（仅 Seedance 支持）。如需在全质量端点上做更便宜的 canary，可降到 720p 或 480p；或使用 fast 端点（上限 720p）。
密钥通道
机器本地共享集成：fal。 密钥映射：/Users/dobby/GitHub/scripts/sync/machine-secrets/fal.env.map。 生成的密钥文件：~/.secrets/fal/env。 CLI 直接读取 ~/.secrets/fal/env。不要通过 flag、被跟踪的文件或聊天可见的 shell 命令传递 fal 密钥。 若未安装 fal-client：python3 -m pip install --user --break-system-packages fal-client。
工具入口与客户端契约
CLI：python3 .agents/skills/fal-seedance/scripts/fal_seedance_ref2v.py（Python，使用官方 fal-client PyPI SDK）。 客户端契约：.agents/skills/fal-seedance/references/client.md。
工作流
- 每个新 prompt 或参考集都先用 --dry-run 开始。
- 使用 --project <id> 使输出保留在 projects/<id>/seedance/ 下。
- 用重复的 --ref 传入本地参考图；真实运行时 CLI 会把它们上传到 fal CDN。
- 在 prompt 中用 @Image1、@Image2 等引用输入。
- 视觉 canary 默认使用 --no-generate-audio 并采用克制的 prompt。分辨率默认 1080p，便宜迭代时可降到 720p 或 480p（或使用 --endpoint .../fast/...）。
- 每次成功运行的 JSON receipt 应与 MP4 一同保留；用 receipt 重新生成或对比漂移（drift）。
命令
验证本地密钥引导： python3 .agents/skills/fal-seedance/scripts/fal_seedance_ref2v.py validate
在不做视频推理的情况下验证 fal 提供方连通性： python3 .agents/skills/fal-seedance/scripts/fal_seedance_ref2v.py doctor --remote
Dry-run 一个 canary：
python3 .agents/skills/fal-seedance/scripts/fal_seedance_ref2v.py run
--project <project-id>
--name portrait-motion-canary
--ref projects/<project-id>/storyboard/frame-01.png
--prompt "Animate @Image1 as a calm studio portrait. Gentle smile, subtle breathing, one natural blink, tiny head turn, soft key light, locked camera, no face reshaping."
--duration 4
--aspect-ratio 1:1
--dry-run
Dry-run 结果正确后，去掉 --dry-run 即可运行。
Kling O3 Pro 上的 image-to-video（确定性 start→end 变形）：
python3 .agents/skills/fal-seedance/scripts/fal_seedance_ref2v.py i2v
--project <project-id>
--name <beat-name>
--start-image projects/<project-id>/keyframes/start.png
--end-image projects/<project-id>/keyframes/end.png
--endpoint fal-ai/kling-video/o3/pro/image-to-video
--duration 5 --aspect-ratio 1:1
--prompt "<phased timing prompt>"
--dry-run
去掉 --dry-run 即可渲染。更便宜的迭代用 o3/standard，prompt 锁定后追求生产质量用 o3/pro。长 prompt 可用 --prompt-file 替代 --prompt。
多参考故事板 canary：
python3 .agents/skills/fal-seedance/scripts/fal_seedance_ref2v.py run
--project <project-id>
--name anchored-portrait-motion
--ref projects/<project-id>/storyboard/primary-frame.png
--ref projects/<project-id>/storyboard/identity-anchor-01.png
--ref projects/<project-id>/storyboard/style-anchor-01.png
--prompt "Animate @Image1 as the primary frame. Use @Image2 and @Image3 only as identity and style anchors. Subtle breathing, one natural blink, tiny head turn, soft studio light, locked camera, no face reshaping, no outfit change."
--duration 4
--aspect-ratio 1:1
--dry-run
Prompt 规则
- 使用 @ImageN 句柄，与 fal 的 Seedance schema 一致。
- @Image1 通常应是要动画化的主帧。其余图片引用应描述为身份、风格、物体或环境锚点，以免 Seedance 误将其当作变形目标。
- 在 prompt 中为每个引用明确指定角色：主帧、角色身份、风格、服装、环境、镜头运动、动作编排、节奏或声音。
- 描述确切的镜头动作与运动幅度。
- 身份 canary 要明确说明不变老、不变装、不重塑面部，且镜头锁定或接近锁定。
- 较长片段可写时间分段（[0-2s] ... [2-5s] ...）。完整的 Seedance 2.0 端点能在单次拍摄内处理连续多动作镜头（例如打开物体 → 镜头推拉 → 动作 → 状态变化）。仅在模型明显难以处理连续镜头时，才采用“原子 canary，再拼接”的方式，不要默认预先分片。
- 对两个特定状态之间的确定性变形（例如真实照片 → 插画肖像），把起始状态作为 @Image1（主帧），目标状态作为 @Image2（风格/结束状态锚点），并在 prompt 中明确描述这一变换。
- 不要直接照搬 Replicate 示例；fal 使用 image_urls / video_urls / audio_urls 与 @Image1 句柄。
输出契约
CLI 默认向 stdout 打印一个 JSON 对象：
- status：ok 或 error
- data.video.url：成功时的 fal 输出 URL
- data.local_video.path：启用下载时的已下载 MP4 路径
- data.receipt_path：JSON receipt 路径
- error.code：失败时的稳定错误码
进度与提供方日志只输出到 stderr。