byted-mediakit-shared

MediaKit 专业媒体处理入口

MediaKit 是面向音视频与图像处理的专业工具集。它将常见的媒体加工、内容理解和 智能增强能力统一到 mediakit-cli，适合从素材处理到成片制作的完整工作流。

使用规则

1. 通过本 Skill 或领域 Skill 实际执行 mediakit-cli 业务命令时，必须在同一次 调用中注入来源与宿主，避免 CLI 无法识别调用来源：
   • MEDIAKIT_SURFACE=skill（本 Skill / 领域 Skill 调用固定为 skill）
   • MEDIAKIT_RUNTIME=<当前 Agent 宿主>（无法判断时用 unknown）
2. 注入方式：在命令前设置环境变量（推荐），不要把这两个值当成 CLI flag 或业务参数。
3. --help / --schema / --domains / --version 等只读发现命令可不注入；一旦发起 真实处理或 shared query-task，必须注入。

示例（每次真实调用都带上）：

MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video --video-url <url>

<runtime> 填当前宿主标识（如 cursor、claude-code、codex）；不确定时填 unknown。不要省略 MEDIAKIT_SURFACE=skill。

能力范围

• 视频剪辑与合成：裁剪、拼接、转场、调速、音量调整、视频滤镜、运镜、画面叠加、字幕压制、 混音、淡入淡出、音视频提取与合流、文字滚屏、图转视频和多画面编排。
• 音频与音轨处理：音频转码与媒资探测、语音边界定位、人声与背景声分离， 以及面向视频音轨的处理。
• 视频理解与增强：视频内容分析、剧情/剧本与精彩高光拆条、画质增强与画质检测、抽帧、 语音转字幕与字幕提取、字幕擦除、水印处理、隐私保护、场景与语义分段、画面文字识别、 转码转封装、抠像与换脸等。
• 图像处理与内容理解：尺寸缩放与体积治理、元信息探测、裁剪旋转翻转与圆角、颜色与锐化、 负片、模糊与打码、水印、背景移除、文字识别、画质评估与智能裁剪等。

能力选择与优先加载

按用户的处理对象和明确目标选择领域 Skill：

如果一个请求同时包含多个阶段，先加载与主要产出最匹配的领域 Skill，再按工作流 需要加载其他领域 Skill。只说明“处理一个视频”或“处理一张图片”而没有说明目标 时，先向用户澄清，不要根据媒体类型猜测具体能力。

选定领域后，必须先读取该领域 Skill，再读取最终选定工具的完整 reference，最后 依据当前 CLI 的机器合同构造参数。共享入口只负责能力导航和通用 CLI 使用方式， 不重复具体工具的参数、枚举或结果字段。

安装与可用性检查

首次使用时安装 CLI 与随附 Skills：

安装后验证公开入口：

需要重装当前版本携带的 Skills 时执行：

初始化与检查

doctor 用于检查当前 CLI 与本地处理依赖；具体工具是否支持本地处理，以对应 领域 Skill 和工具 reference 为准。

命令发现与机器合同

--schema 只读取当前有效模式的机器合同，不发起业务调用；顶层包含 name、 description、input_schema 和 output_schema。构造参数前先读取目标工具的 --help 与 --schema，并以完整 reference 中的字段说明为 Agent 使用指引。

媒体输入

直接把用户提供的媒体输入传给工具参数。本机文件请传本地文件路径（如 /path/to/file.jpg 或 ./file.jpg），不要自行添加 mediakit:// 前缀；CLI 的媒体输入适配器会处理上传。不需要额外创建上传命令或上传参数。

Cloud / Local 模式

未指定模式时，由 CLI 当前配置选择 Cloud-first 或 Local-first。--local 与 --cloud 只用于单次命令覆盖；CLI 的 --help 与 --schema 只显示所选模式的 参数与结果。

规范命令顺序为：

Local 不支持的参数不能被静默忽略；应改用 Cloud 或移除对应参数。Local 工具同步 返回处理结果，不产生 Cloud 异步任务。Local 输出目录通过 CLI 配置管理：

异步结果

Cloud 异步能力返回 task_id。先使用共享查询命令获取任务状态与最终业务结果：

需要持续等待终态时，按 query_task.md 中的查询协议执行。

更新

共享查询协议