MediaKit 共享规则

本技能说明如何通过 mediakit-cli 操作媒体资源，以及适用于每次调用的共享规则与注意事项。

前提条件

安装 CLI

首次使用前，请确认 CLI 已正确安装：

# 安装
npm install -g @volcengine/mediakit-cli

# 验证
mediakit-cli --version

认证检查

优先级：环境变量 > 配置文件（路径：~/.mediakit/config.json）。

字段参考

• 环境变量 / 配置文件字段：MEDIAKIT_API_KEY、MEDIAKIT_ENDPOINT、MEDIAKIT_SURFACE、MEDIAKIT_RUNTIME

当任一必需字段缺失时，应中止执行，并一次性输出所有缺失项及其修复建议。

云调用会自动携带 x-surface / x-runtime。Header 优先级：环境变量 > ~/.mediakit/config.json > 默认值 / 环境探测。当本技能或插件通过 mediakit-cli 调用云能力时，运行时必须显式注入 MEDIAKIT_SURFACE=skill|plugin 和 MEDIAKIT_RUNTIME=。CLI 保留原始产品前缀，并上报 x-surface=cli/skill 或 x-surface=cli/plugin。若未显式配置，CLI 默认使用 x-surface=cli；x-runtime 则按顺序回退至 IDENTITY_NAME / OPENCLAW_SERVICE_MARKER 环境变量探测，最终为 unknown。

来源上报约束

• 当技能调用 mediakit-cli 时，必须显式设置 MEDIAKIT_SURFACE=skill，且不得依赖用户已预设的环境变量。
• 当插件调用 mediakit-cli 时，必须显式设置 MEDIAKIT_SURFACE=plugin，且不得复用技能所设的值。
• 主机运行时标识也须通过 MEDIAKIT_RUNTIME= 显式设置；若未设置，CLI 将回退至环境变量探测或默认值 unknown。

MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME= mediakit-cli editing add-image-to-video

MEDIAKIT_SURFACE=plugin MEDIAKIT_RUNTIME= mediakit-cli editing add-image-to-video

CLI 使用方式

初始化

首次使用前，请运行初始化向导：

mediakit-cli init

对于非交互式初始化（如 Agent 场景），需显式传入请求来源与运行时配置：

mediakit-cli init --mode cloud-first --api-key  --runtime  --surface cli --yes
mediakit-cli init --mode local-first --api-key  --endpoint  --output-path ~/mediakit-output --runtime  --surface cli --credential-store config --yes

初始化后常用命令：

# 查看当前配置
mediakit-cli config show

# 将默认模式切换为本地优先
mediakit-cli config set mode local-first

# 将默认模式切换为云优先
mediakit-cli config set mode cloud-first

# 刷新环境检查并查看依赖状态
mediakit-cli doctor

命令结构

MediaKit CLI 统一采用 domain + tool 的调用形式：

mediakit-cli {domain} {tool} [flags]

常用帮助命令：

# 列出全部 domain
mediakit-cli --domains

# 列出指定 domain 下的所有工具
mediakit-cli {domain} --help

# 查看指定工具的参数说明
mediakit-cli {domain} {tool} --help

# 动态发现工具能力及返回结构
mediakit-cli {domain} {tool} --schema
mediakit-cli --local {domain} {tool} --schema

当前产品覆盖的 domain： editing、video。

Schema 发现机制

每个能力命令均支持 --schema 参数，供 Agent 动态读取工具能力。启用 --schema 时，不强制校验业务必需参数。

返回结构包含以下字段：

• name：工具名称（snake_case 格式），例如 add_image_to_video
• description：工具描述，自动包含 Mode 与 Async 信息
• input_schema：输入参数的 JSON Schema
• output_schema：当前执行模式下的返回结构

返回结构消歧规则：

• 默认情况下，返回结构依据全局 mode 配置解析
• --local ... --schema 输出本地模式下的返回结构；本地模式直接返回最终结果字段
• 云异步工具返回 task_id / request_id，并在 final_result 字段中描述 query-task 查询到的完成态结果
• query-task 仅限云模式；其 schema 描述任务状态及完成态结果

示例：

mediakit-cli editing trim-video --schema
mediakit-cli --local editing trim-video --schema

单次调用模式覆盖

除通过 config set mode 设置默认模式外，还可为单条命令临时覆盖执行模式：

mediakit-cli --local editing add-image-to-video

mediakit-cli --cloud editing add-image-to-video

补充规则：

• --local / --cloud 仅影响当前命令，不会修改全局 config.mode
• --local 与 --cloud 互斥，不可同时使用

异步任务

当异步媒体处理任务成功提交后，响应中将包含 task_id 字段。请使用 shared query-task 命令轮询结果。

mediakit-cli shared query-task --task-id 

本地模式 / 云模式约束

• query-task 是仅云模式支持的工具
• 本地模式不支持 query-task
• 当前能力集主要运行于云模式；当需显式声明时，优先使用 --cloud

云模式媒体输入说明

• 当命令以 --cloud 方式运行，或处于 cloud-first 策略下时，媒体输入参数（video_url、audio_url、image_url、subtitle_url、sub_image_url 及其对应数组/对象子字段）支持 http:// / https:// URL、mediakit://... file_id，以及本地文件路径
• http:// / https:// URL 与 mediakit://... file_id 将原样提交；本地文件路径则由 CLI 首先上传为 mediakit://... file_id，再提交至云服务工具
• 各工具文档中参数说明均源自 APIHub/OpenAPI 原始字段描述；即使显示为公网 URL 或 HTTP/HTTPS URL，也仅代表云 API 最终接收到的资源形式——这并不限制 CLI 在云模式下对本地路径进行预处理的能力

本地模式说明

• 本地输出目录优先级：--output-path > MEDIAKIT_OUTPUT_PATH > 配置项 output_path > ~/.mediakit/temp
• 当 --output-path 指向具体媒体文件名时，该路径即作为最终输出文件；否则文件名按 {source_name}_{tool_name}.{ext} 构建，并在发生命名冲突时追加 6 位随机后缀
• 当无法从输入 URL 或路径中提取文件名时，回退至 {tool_name}-{UnixNano}.{ext}
• 本地模式依赖 ffmpeg / ffprobe；若缺失，错误响应中将包含 install_guide
• 本地模式媒体处理输出必须严格符合对应接口响应 Schema；禁止暴露内部执行元数据

错误响应

• CLI 云模式将 API 返回的原始错误对象原样透传，不提取 message 字段
• CLI 本地模式返回结构化错误：{"error":{"type":"...","code":"...","message":"..."}}
• MCP error_response 原样透传原始错误内容；字典类型将直接作为 error 字段值使用

幂等性参数维护

补充规则：

• client_token 长度不得超过 64 字符
• callback_args 适用于回调透传与对账追踪场景

轮询策略