| name | kinema-depth |
| description | 把一段实拍视频的人物运动复刻到本项目的角色身上。用户提到照着这段视频动、复刻动作、翻跳同一支舞、让我的角色跳这个、把实拍运动迁移到 AI 片段，或手上有参考视频想让角色照做时使用；引擎在本机把源片处理成人物深度与骨骼的控制视频，绑到分镜后作参考视频发出——运动来自源片，外观来自分镜图。 |
| metadata | {"kinema-managed-by":"agent/manifest.json","kinema-kind":"capability","kinema-status":"stable","kinema-version":"2.0.0","kinema-owner":"Kinema","kinema-source":"workspace","kinema-trust":"first-party","kinema-digest":"sha256:ae2c0326b304837d8366d353b1261fd606f63a69ae64eb9f13c1e22b410ff0c4"} |
kinema-depth · 深度捕捉（实拍运动 → 你自己的角色）
运动来自源片，外观来自你自己的设定。 拿一段实拍表演片当运动源，让你这个项目的
角色把同一套动作演一遍：引擎在本机把源片处理成只含人物深度浮雕与 OpenPose 骨骼的
控制视频（去场景、去人脸、去服装，多人各自成骨），按镜长裁段绑到分镜上，gen-video
时作 reference_video 发出。外观那一路发什么随画风档变——缺省是分镜图领衔，
写实人物档走设定图领衔（见铁律②），两种都不取自源片。
成本口径：处理全程本机 CPU，不花 API 的钱（每源秒约十几秒）。付费只在
gen-video 那一步，且输入视频秒数叠加在输出秒数之上——5 镜 × 12 秒就是
60 输出秒 + 60 输入秒。
本 skill 不进 project.skill。 它是能力工法包，与画风 skill 并肩调用：
项目照常 --profile <画风> --skill <该画风的 route skill>，深度捕捉在章节里按需用。
直接启动整套流程（/kinema-depth <源片或主题> 即可）
-
Read ../kinema/SKILL.md —— 立项、设定、分镜、生图、
合成的全部通用节点都在那里，本文只写与它不同的部分。
-
立项照常，画风由用户的题材决定，不由本 skill 决定：
python3 -m kinema project new --title "X" --id x --profile <画风> --skill <画风 route skill>
-
设定集先行，--skip-design 禁用——理由见「铁律②」。
-
每章对应一段源片，按下面这条顺序走。顺序本身是省钱与省时的：贵的、慢的、
一错就得全推倒的都排在前面，两条互不依赖的长任务并起来跑。
① character/scene add ─┐ 零成本，先把设定集立齐
② project refs（逐张人工审） │ 每张约 1.5 分钟；错了改 desc 重出，别往下走
③ control build（同时开跑） ─┘ 每源秒约十几秒 CPU，与 ② 互不依赖
④ control list 体检 people/tracks 幽灵轨迹与人数不符在这里拦掉，别等到出图
⑤ ChapterPlan 一次写齐 characters/scenes/face_visibility + 两档 PromptSpec
⑥ lint --strict 清零 零成本，把 camera/双语/代词这几条一次扫掉
⑦ gen-image 首镜 + 差异最大的一镜 ★人工审外观锁死，再出其余
⑧ control bind 框区间 dur 随之对齐，改区间会让已出的片段过期；有 beats 的镜再 sketch use --guide control
⑨ gen-video --dry-run ★审路线（写实档看是不是降级形态）与报价
⑩ 出片 → control compare 三列对照
三个「别走反」的点：② 与 ③ 并起来跑（一个是 API 等待、一个是本机 CPU，串行
白等一倍）；⑥ 在 ⑦ 之前（lint 零成本，出图之后再改提示词就是重出一轮）；
⑧ 在 ⑦ 之后（分镜图是对位的参照，先有图才知道景别与站位往哪对；绑定与改区间只让
已出的片段过期，不动分镜图）。
两条硬前置
第一次跑之前必须落实，缺一条就是在花钱那一步才失败：
- 参考视频要先上云。 Seedance 的
reference_video 只收公网 URL，gen-video 在发请求前
把控制段按需上传；上云能力（provider、桶、区域、密钥）没配齐时直接报错、一帧不发。判据是
能力齐备而不是 media.backend: oss——backend 留 local，storage.yaml 的 media 段只选
provider，桶、区域与密钥走 secrets（KINEMA_OSS_BUCKET / KINEMA_OSS_REGION /
KINEMA_OSS_ACCESS_KEY / KINEMA_OSS_SECRET_KEY），其余媒体照常留在本地。
- 感知栈与权重要显式装。
pip install -e "engine[control]" 之后再跑一行
pip install --no-deps rtmlib，然后 python3 -m kinema control fetch 拉约 115MB 权重。
权重不静默下载，就绪状态只在 doctor 的「可选依赖 control」一行——setup --check 的
ready=true 不包含它。
核心工法
① 处理源片（零 API 花费）
cd engine
python3 -m kinema control build --chapter x/ch01 --source dance.mp4
python3 -m kinema control list --chapter x/ch01
产物三条视频：control.mp4 是发给模型的纯控制视频，compare.mp4 是源片与深度的
二合一对照（竖片左右并排、横片上下叠放），审看只看它——单看深度判不出骨骼有没有
跟住动作；styled.mp4 是白色浮雕精细版，只给人看，--no-styled 可跳过、省约三成时间。
几条处理期的规矩：重传同一源片得新素材（id 是文件名加内容指纹，撞了缀 -2），
要就地重建须显式 --asset <既有 id>；同一章的 build 走 .build.lock 互斥，多条源片
串行处理；--bind-shot N 处理完直接绑到镜 N（区间从 0 起按镜秒数），Studio 走的就是它。
处理完先体检再绑，control list --json 逐条读三个数：
people 比画面里的真人多 ＝ 有幽灵轨迹（背景里的车、反光被当成了人），
成片里会多出一条乱挥的肢体。看 tracks[].frames：真人那条接近总帧数，
几十帧的短轨就是幽灵。实测一条 15 秒的多人街舞出了 14 条轨迹、其中 8 条不足
40 帧——这种素材直接换，救不回来；- 真人那条
frames 远小于总帧数 ＝ 大量帧检不出骨架（运动模糊/光线太暗），
做出来骨骼一闪一闪；
people 与你这一镜的出场角色数对不上 ＝ 先解决人数（见「对位纪律」）。
源片准入与切口判断见 references/source-and-cut.md。
上传与预览走 Studio 控制台时，按 ../kinema/references/studio-handoff.md
先启动或复用控制台再提示用户操作。
② 框区间：起点与终点都由你定
绑定收 --start 与 --end，框多长这一镜就多长——引擎按 round(终点-起点) 定段，
并把该镜 dur 对齐过去（控制段与成片 1:1 是运动不被拉伸的前提）。源片前后不要的
几秒直接框掉，不必先拿 ffmpeg 剪一遍。
control list 给出素材总长；strip.png 是每半秒一格的缩略条，切口在它上面定。
段长恒 4~15 秒（见铁律③），落在区间外直接拒绝、不静默钳。一段 60 秒的舞
= 5 镜 × 12 秒。
切口位置是唯一能软化观感的杠杆：落在动作停顿、重心交换、转身的那一刻，
不要落在时钟整数上。
Studio 的「◇ 绑定分镜」把这件事做成了可视的：缩略条上拖双把手，右边同步播
二合一（左源片、右深度），松手即可确认这一段的骨骼贴不贴得住动作。
③ 一份 ChapterPlan 建齐所有镜
{"op": "add", "id": 1, "fields": {"dur": 12, "narration": ""},
"prompt_spec": {"subject": "…", "action": "…", "composition": "…"}}
同一份计划里的章级字段：motion: "native"（强制显式，见铁律①）、
voiceover: "none"、control_video: true、control_bgm: true（成片配乐取源片
同区间音轨，见「声音设计」）。
narration: "" 合法——纯画面镜是本工法的常态。image 档 PromptSpec 写该段首帧上
角色的姿态，不写运动：运动由控制视频给。
④ 出图 → 绑定 → 审报价
python3 -m kinema lint --chapter x/ch01 --strict
python3 -m kinema gen-image --chapter x/ch01 --only 1
python3 -m kinema gen-image --chapter x/ch01
python3 -m kinema control bind --chapter x/ch01 --shot 1 --asset <素材id> --start 2 --end 14
python3 -m kinema gen-video --chapter x/ch01 -m b --control --dry-run
run 一条龙不吃 --control，只认章级 control_video: true。要用 Seedance 2.5 出片就
gen-video --video-provider seedance-2.5（或 chapter set --video-provider 持久点名）：
1080p 只在 2.5，单价按档计；点名 2.5 不改变段长上限，参考视频输入侧仍恒 4~15 秒。
控制视频替代的是运动编排，不是画面；分镜图的角色随画风档变（见铁律②）：
非写实档走路线 A，分镜图是请求里的外观锚，gen-image 不可跳过；写实档
closeup 镜的分镜图整个不进请求，引擎在降级路线上也不要求它在盘，出它只为
人工对位与首镜审看——可以只出首镜。
铁律
① motion: "native" 必须显式写
无对白章的 motion 缺省是 dubbed，而参考视频只在 native 生效。不写就是：
控制视频一帧都不发、还买了一整章静音占位配音与强制曲库 BGM。这是本功能最贵的
静默失败。零成本的 lint 会点名（control_inert），但要在花钱之前跑。
② 顺序倒置：设定集与设定图先于任何分镜图
V2V 分支不发首/末帧，图一律挂 role=reference_image。官方的互斥规则拦的是
首/末帧与参考媒体混发，不是「图与视频不能同发」——参考图 09 张、参考视频
03 段可以自由组合（火山方舟 Seedance 2.0 文档）。所以设定图在这条路上有通道，
而且是承重的通道：
| 画风档 | 请求里的外观锚 |
|---|
| 非写实档（缺省路线 A） | 分镜图领衔 + 设定图随发 |
写实档 · 标了 face_visibility: closeup | 场景基准图 + 身份图 + 俯视图，分镜图整个不进请求 |
第二行是写实人物复刻的唯一可行形态。写实档下分镜图是挂着设定图生成的（图生图），
人脸受信豁免天然不成立，路线 A 必被建任务时拒（HTTP 400、不计费）；能把受信身份图
（纯文生图、sheet_origin: t2i）送进请求的只有降级路线。判据与阶梯的实现真源在
docs/agents/photoreal-face.md。
所以：角色/道具/场景先立，project refs 出设定图并逐张人工审，首镜出图后再停一次，
确认外观锁死，再绑控制视频、再出其余镜。--skip-design 在本工法下禁用。
写实档的三件必做，缺一条整章发不出去：
- 身份图必须是
sheet_origin: t2i（project refs 直出即是；refine 局改会把它
变成图生图、当场失去受信）；
- 主场景基准图必须在盘——降级路线拿它顶
image 位；
- 有可辨识正脸的镜标
face_visibility: closeup，直接从降级形态起步，省一次
注定被拒的往返。
②b 场景基准图在这条路上是取景地权威，出图后必须审
路线 A 下分镜图压着它、错了也不显形；一进降级形态它就是 @图片1，整镜的陈设、
材质与光线都以它为准。而一句宽泛的场景描述很容易被模型加戏——实测「浅灰色无缝
背景纸的摄影棚、画面内不出现道具」出来的是一面米色墙加一个拱形壁龛。
写死结构名词与否定项（「cyclorama 无缝背景棚，背景纸从后墙弯折延伸到地面，
除这面纸外没有任何墙体结构、拱门、隔断、家具」），并在 desc 里钉死时段与主光
（lint scene_daypart_missing 只提醒没表态的，不判对错）。改了 desc 要重出：
project refs <项目> --only scene:<取景地> --force。
③ 段长 4~15 秒，seedance-2.5 也不例外
参考视频的服务端上限恒是 15 秒，与别名的 max_duration 无关（2.5 允许 30 秒
输出，参考视频仍只收 15）。control bind 对超出的镜直接拒绝并要求拆镜——静默截断
是拿 15 秒的运动去演 20 秒的镜。
④ 三路运动预演一镜只生效一条，绑了控制视频的镜不写 sketch.beats
3D 预演、控制视频、简笔板互斥，缺省仲裁按 previz > control > sketch，显式
shots[].guide 恒赢（sketch use --shot N --guide control 表态）。绑着控制视频的镜
不接受 previz 登记，有 previz 的镜要绑控制视频须 --replace-previz——两边都是
显式动作，不靠仲裁悄悄压掉另一路。写了 beats 不会顶掉控制视频，但通用 playbook 的
「秒级规划先行」在这一档不适用——运动已经逐帧给定，拍表是多余的第二套说法；而且
被压掉的拍表会触发 sketch_shadowed，lint --strict 下非零退出，要么 sketch use --guide control 表态，要么删掉 beats。
⑤ 出片后看三列对照
python3 -m kinema control compare --chapter x/ch01 --shot 1
源片段与控制段按素材画幅拼一条——竖片左右并排、横片上下叠放；成片段与素材同画幅时
接在后面，画幅取向相反（竖拍素材配 16:9 成片）时另起一行或一列；三路同一区间逐帧
对拍，control compare 顺带报成片相对控制段的偏移。Studio 里点分镜卡的
「◆ 深度」角标同样是它（第一次点会现拼几秒）。运动跟没跟住、外观有没有跑偏，
这一条比来回切三个窗口快得多。
提示词分工：控制视频带不动的那几样，正文必须补上
控制视频是黑底的深度浮雕 + 骨骼线。它带得动的只有三样：骨架的逐帧姿态、
人物的体积远近、以及人在画面里的位置与大小。除此之外它一无所有——
| 控制视频里没有 | 谁来给 |
|---|
| 头发、衣料的形态与惯性 | secondary_motion |
| 材质、皮肤、光的响应 | creative_notes |
| 机位怎么走 | camera（必写，见下） |
| 动作的力度与速度曲线 | action_delta，写质地不写序列 |
| 声音 | sound |
所以 V2V 的 video 档 PromptSpec 与普通镜反着写：引擎已经在提示词开头发了
「严格跟随@视频1的运镜、走位与动作节奏」，action_delta 再复述一遍动作序列
是第二套运动权威，与控制视频逐帧打架。正确写法是只定质地：
"action_delta": "动作序列本身跟随参考视频，这里只定动作的质地：重心转移干脆，
每一次落点都有明确的制动而不是滑过去；发力顺序自髋而肩再到指尖，
收势时速度自然衰减、不做突然的硬停"
"secondary_motion": "高马尾随头颈转向甩出半拍滞后的弧线、末端有回弹；长袖袖口与
裤脚在急停时出现顺惯性的抖动褶皱；衣料贴身，不产生夸张飘动"
camera 必写，且多半是「机位固定」。 空着等于把运镜交给模型随机发挥，而它
手上正拿着一段有自己机位的参考视频——两边一撞，人物运动跟住了、画面却在莫名其妙
地推拉。源片是三脚架固定的就写死固定（lint 的 motion=5 也会点名缺 camera）。
对位纪律
控制视频与分镜图的人物比例、站位、朝向、景别不一致时，模型会在两者之间折中，
出来的既不是你的构图也不是源片的运动。引擎不自动对位——对位需要视觉理解，
这是指挥层的活。
按该段控制视频的首帧对齐这四项，落点随画风档变：非写实档写进 image_prompt
（分镜图进请求）；写实档 closeup 镜的分镜图不进请求，对位改落在 video 档 PromptSpec
的 subject / composition——同一张表，换个落点：
| 项 | 怎么对 |
|---|
| 景别 | 源片全身入画就写全身，别写半身特写——模型会为了凑特写把动作裁掉 |
| 人物比例 | 人在画面里占多高，分镜图就画多高 |
| 站位 | 源片人偏左就写偏左；居中的写居中 |
| 朝向 | 正面/侧身/背身要一致，否则第一帧就要转体，动作从头错位 |
画幅取向要在立项时就对上。 裁段按章节画布贴合（那是承重的，不贴合成片会跟着
参考视频的几何走），于是一段竖拍装进 16:9 的章节后，cropdetect 量出来只有
608/1920 是画面、其余 68% 是补出来的黑边——发给模型的运动信息只占画面三分之一宽，
出来的人也就那么小一条。竖拍源片就把章节做成 9:16，或者绑定时用
--fit crop 填满（代价是切掉头顶脚底，全身舞蹈通常不划算）。混着来时以源片为准
改画布，比每镜去救构图便宜得多。
| 人数 | 出场角色必须与轨迹条数对上。三条骨架配一个已登记角色，模型得凭空造两张脸；
想要伴舞就在提示词里把他们写成逆光剪影（面部不可辨），或干脆各自登记角色 |
机体角色先登记 --subject-kind robot。 设定图模板缺省按人写（五官、瞳色、发际线、
肤质），一台机甲套上去会画成戴头盔的人；登记为 robot 后肖像区改成头部正面大特写、
头部正对镜头、无皮肤头发五官的机械口径。外貌描述里也把「纯机械构造、不是穿着装甲的人」
写在最前面。
平台版权审核是硬墙。 火山方舟对输出图与输出视频做版权识别，像已有 IP 就拒、不计费，
且设定图、分镜图、视频三级各判各的——上一级过了不代表下一级过。实测：接近某部作品配色与
天线组合的机甲，设定图连拒三次，换配色后设定图通过、同一机体进场景的分镜图仍被拒；一台
原创黑金机体图像两级都过、视频又被拒；仙侠人物三级一次通过。被拒的处置是改设计的辨识点，
不是同参数重跑。
声音设计
源片自己的音轨不进请求——盘上的控制段带源片同区间的音轨（审看用，@视频1 点开
即它），发给模型的是它的无声副本：模型的原生音是生成的、不会复现参考音频，把音乐塞进
参考只会给它加戏的机会。但那段音乐正是这支舞最对拍的配乐：控制段与
成片 1:1，章级 control_bgm: true 让合成用每个绑定镜的源片同一区间音轨作这一章的
主音乐：本地 ffmpeg 零成本，入轨响度与曲库同一口径，母线上不让路不闪避，模型原生音
退到环境床；未绑定的镜与源片无音轨的镜留静音。它与 native_bgm 同占母线且优先。复刻
舞蹈的章缺省就该写它；成片里的音乐来自 assemble，gen_clips/ 里的片段本身只有模型原生音。
配乐与成片动作的对拍由引擎量：music 阶段拿成片与控制段的运动能量做互相关，量出整体
偏移就平移那一镜的配乐起点（记在 gen.control.sync；control compare 与 Studio
对照片的信息栏都能看到）。它只救整体的早晚：模型在镜内忽快忽慢时相关会偏低、配乐不动，
那一镜只能重生成。
不要源片音乐时另两条路：章级 native_bgm: true + 曲库，或 audio_mode: "scored"
- 音频剧本（转 kinema-audio）。三者都与配音混烧互斥。这一步要主动带用户走——
assemble 前的曲库闸只在「曲库为空」或「native 从没表过态」时才发问。
重做意见词典
| 现象 | 根因 | 改法 |
|---|
| 动作跟不上源片 | 段落与镜长不是 1:1 | control compare 出三列对照逐帧比；control list 看有没有「时长已变」，重新 bind 重裁 |
| 音乐比动作早或晚几拍 | 模型整体滞后或超前 | music --force 重量对拍再 assemble；报「相关不足」则是镜内忽快忽慢，重生成这一镜 |
| 前几秒是废镜头 | 区间没框 | bind --start --end 直接框掉，不必先剪源片 |
| 人物比例不匹配 | 分镜图与控制视频没对位 | 改 image_prompt 的景别/站位，重出这一镜的图 |
| 段落接缝跳 | 切口落在动作中途 | 重定切口到动作停顿处，omit 旧镜 + 追加新镜 |
| 换手换脚 | 源片是自拍镜像 | 先 ffmpeg -i 源片 -vf hflip 翻转.mp4，拿翻转后的片子重新 build |
| 背景乱入 | 分镜图背景太强 | 控制视频只给运动，背景全靠分镜图——改图不改控制视频 |
| 成片没带控制视频 | motion 不是 native、章级开关没开、provider 不支持参考视频，或这一镜被 previz / 显式 guide 压掉 | lint --strict 会点名（control_inert / control_binding）；前两处都要显式，后者 sketch use --guide control |
| 设定图或成片被平台以版权拒绝 | 设计落到了某部作品的辨识组合上 | 改设计（配色、天线、面甲这类识别点），不同参数重跑；拒绝不计费 |
何时不用
- 有走位调度要排、但没有实拍源——用 3D 导演台（
previz）。
- 只要卡动作节奏、不需要复刻具体运动——用
kinema-sketchboard 的逐秒 beats。
- 纯氛围空镜或口播——两条都不需要，直接走
kinema 的缺省档。
- 源片是多机位剪辑过的片段——段内有剪辑点的源片处理出来是跳变的骨架，
先剪成单镜头的连续片段再来。
