KyaniteLabs/kinocut

kinocut 是做什么的？

当代理需要结构化的视频编辑界面而不是手写 FFmpeg 命令时，请使用 Kinocut。它提供 MCP 工具、Python 客户端和 CLI，用于编辑、分析、字幕、音频、Hyperframes、分层合成以及本地复用工作流。

默认路径（先执行此步骤）

1. 运行 kino doctor，然后执行 kino --format json info <file>。
2. 对于不熟悉的任务，请使用用户的任务调用 search_tools（例如“删除填充词”或“保持面部在画面内”），然后检查返回的工具所需的输入。使用 video_intent 规划支持的意图（可选的 goal= 编译剪切列表；360/桌面/桌子/x4 目标也会提出 360_assembly_plan）。在渲染之前，检查提案是否确实满足请求。
3. 渲染（video_cutfile_render、video_edit、工作流或单个引擎工具）。对于 360：在计划上使用 video_review_decide 批准/拒绝，然后渲染——切勿渲染 proposed 计划。拒绝 .insv 文件；需要已经拼接好的 360 MP4。指南：docs/360_ASSEMBLY.md。
4. video-quality-check / assert_quality。同步 repurpose 和 shorts-package 在低于 80 分时失败关闭，除非跳过或使用 allow_fail。
5. 人工视觉/音频检查。切勿将为收据视为已发布。

深度内容（修复、抢救、合成、Hyperframes、薄声 S12）：docs/TOOLS.md、docs/RESCUE.md、docs/WORKFLOWS.md。工作流允许列表：probe、trim、resize、convert、crop、add_text、merge、composite_layers、burn_in。

需要时加载相关指南。使用源证据进行编辑选择；保留名称、数字、否定和限定条件。报告缺失的证据或不受支持的操作，而不是凭空捏造源声明、时间戳或功能。规划工具提出编辑建议；其存在并不意味着所需的检测器或模型已运行。代码负责时序、变换、验证和执行；人工审核仍与模型判断分开。

Revideo 本地代码-视频流程（开发技巧）

当调用者需要可检查的阶段性项目时，请使用 revideo_materialize、revideo_install 和 revideo_render。使用 revideo_render_job 在单个调用中完成相同的受保护步骤。提供的场景是可执行的 TypeScript 代码：在使用前检查它，切勿运行不受信任的场景代码。依赖项安装可能访问 npm；渲染在本地针对 Kinocut 的固定模板运行。渲染收据将观察到的媒体和输出字节绑定到磁盘上确切的有界作业文件摘要。.mp4、.webm 和 .mov 选择固定的 MP4、WebM 和 ProRes 4444 导出器模式，并在发布前进行验证。对照输出字节验证收据，运行 video_quality_check 和 video_release_checkpoint，然后要求人工视觉检查。

从这里开始

• 阅读 ../../README.md 了解安装和安全合约。
• 在 FFmpeg / Hyperframes / AI 扩展之前运行 kino doctor。

选择一种界面

• MCP：最适合 Claude Code、Cursor、Codex 风格的客户端和其他代理主机。配置 uvx --from kinocut kino。
• CLI：最适合直接的本地编辑、快速诊断、composite-layers --dry-run、批处理任务和 CI 友好的 JSON 输出。
• Python 客户端：最适合需要结构化结果、输出路径和保存的层计划收据的可重复流水线。

360 度双摄像头组装（已发布 1.14.0）

当源文件是来自任何相机（Insta360、Ricoh Theta、GoPro MAX、DJI Osmo 360 等）的已拼接的等距 360 MP4，并且要求是作为分割/切换/画中画/单摄像头的两个虚拟摄像头时使用。

1. video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH) 或 Client.propose_360_assembly(...)。
2. 显示摄像头、布局和故事板静态图。切勿发明 yaw/pitch。
3. video_review_decide / Client.decide_360_assembly 使用 approve 或 reject。
4. 仅渲染已批准的计划（Client.render_360_assembly 或 video_review_decide + output_path）。

没有 video_360_* MCP 工具，也没有 kino 360 命令。CLI intent 和 review-decide 不运行此编译器。Director 钩子接受注入的 JSON 提议者；配置的模型名称本身不执行模型。云提议需要 allow_cloud；director 从不写入像素。

产品/对象抠图（在 1.15.1 中发布；当前在 1.15.3 中）

可选的 object-matte 扩展在已发布的 1.15.3 中可用。使用现有的 hyperframes-remove-background / hyperframes_remove_background 命令。默认模型是人物。对于目录 SKU、珠宝、瓶子、鞋、包装或任何非人物物品：

1. hyperframes_remove_background(info=true) — 列出模型，无下载。
2. pip install "kinocut[object-matte]" 然后 model="birefnet-general"。
3. 可选 --mask-interval 3 用于产品视频。可选设备覆盖用于剩余的转台/支架/三脚架/扫掠。
4. 使用 composite-layers 合成到商店底板上。将所有 src 保留在规格目录内。

不要发明 video_product_matte；这不是一个新的 MCP 工具。不要在缺少对象扩展时回退到人物模型。指南：docs/PRODUCT_MATTE.md。示例：examples/product-matte/。

专用视频修复

当请求是修复一个本地片段，同时保留其源、故事和时间线时，请使用 video_rescue_*、rescue-* 或 Client.rescue_*。

必需的顺序：

1. 调用计划并保存计划工件。
2. 向用户呈现 safe_repairs、recommendations、unavailable_repairs、blocked_repairs、预览、包意图、功能和估计。
3. 在渲染前检查计划。仅对 safe_repairs 中的 ID 获取或推断明确批准；省略 ID 列表意味着所检查计划中的所有安全 ID。
4. 使用恰好那些批准的安全 ID 调用渲染。
5. 检查渲染收据，然后报告包路径、不可用的侧车文件、完整性、门控验证、隐私、恢复和清理状态。

切勿从未经审查的计划直接渲染。切勿将推荐 ID、不可用 ID 或阻止的 ID 添加到批准中。切勿使用云工具、烧录修复字幕、重写源文件或将 unavailable 视为自动失败。取消或验证失败必须保持未提升或隔离状态。

确定性 AI 视频检查

当生成的素材在做出编辑决定前需要证据时，请使用 video_ingest、video_preflight 和 video_inspect_temporal（或它们的平面 CLI 和 Python 等价物）。首先导入，然后通过返回的哈希地址访问资产。切勿用主机路径替换该资产 ID 或在公共边界构造 AssetRecord。时序检查返回完整的采样帧和运动条带包、确定性发现以及显式的不可用提供者功能。提供者的缺失是预期的，不得触发下载或网络回退。

受治理的 AI 视频审查和抢救

使用 video_verdict、video_acceptance_eval、video_body_swap 和 video_salvage（或它们的平面 CLI 和 Python 等价物）进行精确资产编辑决策和衍生恢复。未批准的判决可能捕获代理分析，但批准的处置必须绑定一个活跃的、精确的人工决策，并带有明确的要求、角色和工件证据。接受评估是衍生性的，而不是批准操作，并且每个抢救输出都从一个新的未批准的审查槽开始。

切勿发明决策 ID、传递未存储的批准，或寻找强制/覆盖路径。除非调用者选择明确的策略，否则 Body swap 拒绝持续时间不匹配。抢救需要一个现有的私人项目、一个存储的源资产、一个有界的配方策略和一个精确的验收规格 ID。

接受评估采用活跃的已存储 acceptance_spec_id 和 verdict_ids，而不是由调用者构建的证据对象。公共 body swap 始终首先使用 project_dir，并且两个源路径必须解析为该确切项目中的活跃资产。

在操作此工作流之前阅读 docs/AI_VIDEO_REVIEW_AND_SALVAGE.md。将每个衍生作品视为新的未批准的工作，并在发布前保持明确的人工视觉/音频门控。

抢救后规划

当请求需要语义检索、普通清理编辑、主题感知变换、恢复、合成、创意协调或远程出口时，请使用匹配的 video_* MCP 工具、平面 CLI 命令或 Client 方法。传递 JSON 兼容的证据和意图；在任何单独的渲染步骤之前呈现返回的计划和差异。

切勿发明源描述、隐藏不确定性、从计划中推断批准，或将缺少本地执行器视为使用云提供商的许可。远程工作需要单独的出口清单和批准。缺乏证据或功能的规划者必须弃权。

分层合成

当编辑是图像、视频或纯色图层的有序堆栈时，尤其是下部三分之一、画中画变体、模糊背景板、遮罩/蒙版或特定平台的布局变体时，请使用 composite-layers / video_composite_layers。

当代理需要变换、不透明度、开始/持续时间窗口、遮罩/蒙版 Alpha 源或可在发布前审查的收据时，优先选择此路径而非原始的 FFmpeg filtergraph。

计划优先流程：

1. 编写一个带有 canvas、有序 layers 和显式输出的 JSON 规格。
2. 运行 kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json。
3. 检查层计划中的源哈希、filtergraph 哈希、变换、旋转/枢轴、混合模式、时序窗口和遮罩。
4. 仅在计划看起来正确后渲染。
5. 运行 video-quality-check、storyboard 或 thumbnail，以及 video_release_checkpoint。

合成器支持白名单的全画布和定位混合模式（multiply、screen、overlay、darken、lighten），具有不透明度和时序窗口；收据保持为 layer_plan v2。非 normal 混合支持两种几何体中的不透明度和 start/duration 窗口：在 {0,0} 处没有明确尺寸的全画布，或具有正整数 width 和 height 以及画布内积分非负位置的定位矩形。RGB 混合避免将颜色算术应用于子采样色度平面。缩放、旋转/枢轴、遮罩/蒙版、分数位置和画布外矩形保持延迟，并以 unsupported_blend_geometry 失败关闭。视频图层和视频遮罩在其声明的开始时间开始播放。将所有源和遮罩保留在规格目录内。输出仅为视频；anchor 是位置别名，与 pivot 不同。旋转 + 遮罩、音频合成和完整的 NLE 适配器保持延迟。在人工审查前检查收据；不要将其视为完整的 NLE 替代品。

代理工作流引擎

当编辑是一个多步骤任务（而不是单个工具调用）时，使用工作流引擎从一个 JSON 作业规格进行规划、验证、渲染、恢复和证明——通过 video_workflow_*（MCP）、workflow-*（CLI）或 Client.workflow_*（Python）。操作是一个小的允许列表（probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in），绑定到经过审核的引擎；媒体引用是符号性的（@sources.*、@work/*、@outputs.*），并且限制在工作区内；所有操作在失败时关闭。参见 ../../docs/WORKFLOWS.md。

计划 → 验证 → 渲染 → 检查 → 恢复：

1. workflow-validate --spec job.json — 廉价的结构门控；什么都不渲染。
2. workflow-plan --spec job.json --save-plan plan.json — 干运行操作图 + 源探测/哈希；不渲染任何媒体。
3. workflow-render --spec job.json --save-receipt receipt.json — 顺序执行；生成来源收据（每步哈希、清理清单、确定性说明）。添加 --all-variants 用于批量变体。
4. workflow-inspect --receipt receipt.json — 只读完整性重新检查 + 人工审查指针，在信任收据之前。
5. workflow-render --spec job.json --resume receipt.json — 恢复一个失败但保留了中间结果的作业（如果规格已更改则失败关闭）。

收据仅存储相对于工作区的路径——保持规格和示例收据中不包含主目录路径、用户名和令牌。

工作流

1. 首先检查输入：kino info <file> 或 MCP/Python 等价物。
2. 制定低风险计划：裁剪、调整大小、标准化音频、字幕、叠加、效果或 Hyperframes 渲染。
3. 在昂贵或破坏性导出之前，优先使用预览或干运行清单：
   • 使用 preview 进行快速视觉审查。
   • 在 repurpose 之前使用 repurpose-plan。
   • Hyperframes 在完整渲染之前使用 inspect、snapshot 或 still。
   • 对于保存的 shorts 计划：shorts-plan-show → shorts-review → shorts-render → shorts-package。
   • 对于薄声：sound-capabilities 然后 sound-plan-validate / sound-voice-batch / sound-mix-render / sound-qa-loudness / sound-qa-asr（或 kino sound <action>）。
   • 为声音持续时间、增益、响度和配置文件版本提供数值；布尔值在被强制转换前被拒绝。明确无效的计划不能选择示例计划。类型化计划被重新验证；参见 docs/SOUND_INPUT_VALIDATION.md 了解字段特定的兼容性规则。
   • 真正的 ASR 使用哈希化的音频/参考请求和明确的根目录；保留其转录 ZIP 并诚实地报告不匹配。仅缓存本地 Whisper；无自动下载。仅哈希调用的旧式调用是模拟。参见 docs/SOUND_ASR_REQUESTS.md。
   • 对于真正的单声道/立体声 PCM16 响度 QA，提供 SoundLoudnessRequest 加上项目根目录并检查 within_tolerance；成功的测量可能不符合要求。需要 FFmpeg，并且无输入夹具标记为演示。参见 docs/SOUND_LOUDNESS_REQUESTS.md。
   • 对于保留的单声道/立体声母带制作，向 sound-master-render 提供 SoundMasterRequest 和明确的根目录；参见 docs/SOUND_MASTER_REQUESTS.md。在发布前检查验证后的 ZIP、实际的标准化模式和测量的最终政策合规性，然后收听。输入通道被保留；现有输出永远不会被替换。
   • 对于实际的本地 EN/ES ca

…

[为翻译进行了截断]