AI MediaKit
AI MediaKit
文档指南
请输入
- 文档首页
AI MediaKit智能体资源AI MediaKit Skill 用户指南
复制全文
下载 pdfAI MediaKit Skill 用户指南
文档反馈
问问助手AI MediaKit Skill 是一套基于 mediakit-cli 构建的 Agent 工具包。安装并配置后，您可以在支持的 Agent Runtime（如 Trae）中通过自然语言描述需求，Agent 便会自动调用对应的 mediakit-cli 命令来完成音视频处理任务，无需手动编写和拼接命令行参数。
本文档将介绍 Skill 的功能列表、安装与配置方法，并提供典型应用场景的示例。
Skill 列表
mediakit-cli npm 包内置 3 个按功能域划分的 skill：
说明
多数工具以异步任务方式在云端执行。任务提交后，系统将返回 task_id，您可以通过 shared query-task 命令查询任务结果。在本地模式下，除字幕擦除、画质增强、图片转视频这三个功能外，其余任务将同步返回结果。详细的执行规则请参考 AI MediaKit CLI 用户指南。
快速开始：通过自然语言完成“云端增强+本地剪辑”
本节将以一个“云端画质增强”和“本地视频剪辑”相结合的实例，引导您在几分钟内完成从安装、配置到成功处理视频的全过程，体验通过自然语言驱动 Agent 自动编排和执行端云协同任务。
准备工作
在开始之前，请确保您已具备以下条件：
- Agent 运行环境：已安装一个兼容的 Agent Runtime，例如 Claude Code 或 Trae。
- 获取 API Key：访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 AI MediaKit API Key。
- 待处理视频文件 URL：准备一个您希望增强画质的视频文件 URL。请确保该视频 URL 处于公网可访问状态（支持 HTTP/HTTPS 协议），文件大小不超过 10 GB。
- 若您没有可用视频，可参考火山方舟视频生成文档完成视频生成并获取视频地址。
- 为方便您快速测试，本文后续步骤的示例代码中提供了一个可直接使用的演示视频 URL。
步骤 1：安装 mediakit-cli
AI MediaKit Skill 是 mediakit-cli 的上层封装，因此首先需要安装 CLI 主程序。打开您的终端，执行以下命令：
说明
步骤 2：安装 AI MediaKit Skill
AI MediaKit Skill 遵循 skills 社区的统一标准，推荐使用 npx 命令进行安装。该命令会自动检测您本地已安装的所有兼容 Agent Runtime，并将 Skill 分发至相应目录，无需手动创建软链接。
打开终端，执行以下命令：
该命令会将 byted-mediakit-shared、byted-mediakit-editing、byted-mediakit-video 三个工具包安装到全局 Skill 目录 (`~/.agents/skills/`)，并自动为 Trae、Claude Code、Cursor、GitHub Copilot CLI 等十余种 Agent Runtime 创建软链接。
说明
- 安装过程中若出现 PromptScript: does not support global skill installation 等提示，属于正常现象。这表示某个被检测到的 Agent 不支持全局安装，安装程序会自动跳过，不影响其他 Agent 的配置。
- 安装完成后，建议重启 Trae 等部分 Agent 应用，以确保其能成功加载新安装的 Skill。
安装成功后，您可以直接在 Agent 的对话窗口提问 “你有哪些可用的 skill？”，如果回复中包含 byted-mediakit-*，则证明 Skill 已被成功识别。
步骤 3：配置环境变量（API Key）
为了使用需云端执行的功能，您要为 mediakit-cli 配置 API Key。推荐使用 init 命令进行一次性初始化配置。在终端执行以下命令，请将 <YOUR_AI_MEDIAKIT_API_KEY> 替换为您自己的真实 API Key：
完成后，使用 mediakit-cli config show 命令检查配置是否生效。
步骤 4：用自然语言提交云端画质增强任务
打开您的 Agent Runtime（如 Trae 或 Claude Code），在对话窗口输入以下指令，向 Agent 发起一个云端 AI 处理任务。
请使用 mediakit 的画质增强功能，将视频 https://vod-ai-test.tos-cn-beijing.volces.com/demo/demo_480p.mp4 的分辨率提升到 1080p。
Agent 将自动调用 byted-mediakit-video Skill，向云端提交一个异步的画质增强任务。由于视频处理需要一定时间，Agent 会在后台轮询任务状态，并在任务完成后返回最终结果。预期 Agent 回复：
任务已完成。增强后的视频已生成，您可以点击以下链接查看或下载：
https://example.vod.cn-north-1.volcvideo.com/8ed65d4f3d8****da65627d78781edb2?preview=1...
效果如下：
步骤 5：在本地对结果进行剪辑
接下来，引导 Agent 对上一步云端处理的产物，在本地执行一个轻量的剪辑任务。
继续在对话窗口输入以下指令：
很好。现在，请在**本地**对上一步增强后的视频进行裁剪，只保留第 3 秒到第 8 秒的片段。
Agent 会理解您的意图，并执行以下步骤：
- 自动下载上一步生成的增强后视频到本地临时目录。
- 调用 byted-mediakit-editing Skill，并强制使用本地模式 (--local) 对已下载的文件执行裁剪。
- 由于本地任务是同步执行的，Agent 会立即返回裁剪后文件的本地路径。
预期 Agent 回复：
已在本地完成裁剪。处理后的文件保存在您的本地路径： /Users/your-name/.mediakit/temp/enhanced_video_trimmed.mp4
通过以上步骤，您已经成功体验了通过自然语言驱动 Agent，完成“云端异步 AI 增强 + 本地同步轻量裁剪”的完整工作流。
实践示例
以下示例展示了如何通过自然语言指令，驱动 Agent 自动执行相应的 mediakit-cli 命令。
场景 1: 剪辑高光片段
适用场景：从长视频中截取指定时间段的片段。
用户指令：把视频 https://example.com/source.mp4 的第 5 秒到第 15 秒剪出来。
Agent 执行命令：
场景 2: 添加视频水印
适用场景：在视频指定位置添加 Logo、角标或水印。
用户指令：
给视频 https://example.com/video.mp4 的右下角加上 Logo https://example.com/logo.png，Logo 宽度占视频宽度的 10%。
Agent 执行命令：
说明：pos-x 和 pos-y 参数定义了图片左上角在视频画布中的相对位置，(0%, 0%) 代表视频左上角。Agent 会根据“右下角”等自然语言描述自动计算近似的百分比坐标。
场景 3: 添加中文字幕
适用场景：为视频添加内嵌字幕。
用户指令：
给视频 https://example.com/video.mp4 加上字幕，从第 2 秒到第 5 秒显示“开场介绍”，从第 6 秒到第 10 秒显示“核心要点”。
Agent 执行命令：
说明：在本地模式下执行此任务，需要您的 FFmpeg 构建版本包含 libass、libfribidi 和 libharfbuzz 库。为避免本地环境依赖问题，建议在配置了 MEDIAKIT_API_KEY 的情况下，优先使用云端模式执行。
场景 4: 画质增强
适用场景：提升模糊视频的清晰度、修复老旧视频或增强 AIGC 内容的画质。
用户指令：
这个短剧视频有些模糊，帮我用 AI 画质增强功能处理一下，分辨率提升到 1080p。视频地址是 https://example.com/short-drama.mp4。
Agent 执行命令：
说明：--scene 参数的常见取值包括 common、ugc、short_series、aigc、old_film。Agent 会根据用户描述（如“短剧”、“老片”）自动选择最合适的场景模式。此功能仅支持云端处理，需确保已正确配置 MEDIAKIT_API_KEY。
场景 5: 字幕擦除
适用场景：移除视频中的内嵌字幕或水印文字。
用户指令：
把这个视频 https://example.com/video.mp4 里的字幕擦掉。
Agent 执行命令 (自动检测模式)：
如果用户明确知道字幕区域，可以引导 Agent 使用更精确的手动框选模式。
用户指令：
把视频底部 20% 区域里的所有文字都擦掉。
Agent 执行命令 (手动框选模式)：
场景 6（进阶）: 多任务流编排
适用场景：通过 Agent 编排多个处理步骤，实现复杂的视频处理流程。
用户指令：
帮我把视频1和视频2拼接起来，然后在右下角加上 Logo，最后在视频的前 5 秒显示“我的频道”作为字幕。
Agent 执行流程 (分步)：
在每一步之间，Agent 都会使用 shared query-task 命令轮询任务状态，确保上一步任务成功完成后再执行下一步。
常见问题
Q1: Agent 未使用 mediakit-cli，而是尝试调用原生 ffmpeg 命令，应如何处理？
这通常由两个原因导致：
- Skill 未正确安装：请检查您的 Agent Runtime 对应的 skills 目录下是否已包含 byted-mediakit-* 的文件或软链接。如果不存在，请返回“安装 Skill”章节，重新执行安装步骤。
- Skill 未被正确加载或描述未命中：
- 首先，直接向 Agent 提问：“你当前可用的 skill 列表是什么？” 如果列表中没有 mediakit 相关 Skill，可能是 SKILL.md 文件格式有误，或 Runtime 需要重启才能加载新 Skill（尤其是 Trae）。
- 如果 Agent 能列出 Skill 但未使用，请尝试使用更明确的指令，例如：“用 mediakit-cli 帮我裁剪视频”。
Q2: 调用云端功能时，返回“凭据未配置”的错误，是什么原因？
这表示 MEDIAKIT_API_KEY 环境变量未被程序正确读取。请执行 mediakit-cli config show | grep api_key 命令进行验证。预期输出应包含您的 API Key 信息，而不是 <not configured>。如果未配置，请重新运行 mediakit-cli init 或通过 export MEDIAKIT_API_KEY=<key> 命令手动设置环境变量。
Q3: 在本地模式下执行任务时，出现缺少编解码器（如 openh264）或字体库（如 libfribidi）的错误，该如何解决？
本地执行部分视频转码或处理任务（如视频翻转、调速、加水印、加字幕）依赖 FFmpeg 的特定构建版本。最简单的解决方案是优先使用云端模式，在 init 时选择 --mode cloud-first（此为默认设置），这样就不再依赖本地环境。
Q4: Skill 的默认执行模式是云端还是本地？
默认模式是 cloud-first（优先使用云端）。但行为会根据配置发生变化：
- 如果 MEDIAKIT_API_KEY 未配置，CLI 会自动降级到 local（本地）模式，并在标准错误流中打印一条警告信息。
- 为确保行为可预测，建议在调用时显式指定 --cloud 或 --local 标志，避免因环境配置不确定而导致的模式自动切换。
Q5: Agent 是如何知道每个功能支持哪些参数的？
每个 Skill 的 SKILL.md 文件中包含了所有工具的基本描述。当需要获取详细参数信息时，Agent 会调用命令并附加 --schema 标志，例如 mediakit-cli editing add-image-to-video --schema。该命令会返回一个包含 input_schema 和 output_schema 的 JSON Schema，Agent 可据此了解所有可用参数、数据类型、是否必填、枚举值及默认值等详细信息。
Q6: Windows 平台的支持情况如何？
Windows 平台的支持现状如下：
- 二进制文件：mediakit-cli 的二进制文件支持 Windows（amd64）。
- 安装：npm 安装脚本已适配 Windows 环境。
- Skill 安装：在 Windows 上创建软链接（symlink）可能需要管理员权限或开启“开发人员模式”。作为替代，您可以使用直接复制的方式。相关的 shell 命令需要替换为 PowerShell 等价命令（如 New-Item 和 Copy-Item）。
- 路径：Windows 下的 Skill 目录通常位于 %USERPROFILE%\.claude\skills\ 或 %USERPROFILE%\.trae-cn\skills\。
- 验证状态：Windows 平台的支持已通过编译验证，但完整的端到端流程尚未经过全面测试。建议在生产使用前于 Windows 环境进行验证。
Q7: Trae 中安装 Skill 后无法识别，如何排查？
Trae 加载 Skill 的机制与 Claude Code 可能存在差异。如果您遇到此问题，请按以下步骤排查：
- 重启 Trae：完全退出并重新启动 Trae 应用程序。多数情况下，新安装的 Skill 需要重启后才能被加载。
- 检查路径解析：执行 ls -L ~/.trae-cn/skills/byted-mediakit-editing/SKILL.md 命令（-L 选项会解析软链接的最终路径），确保能够正常读取文件内容。
- 检查内置 Skill 冲突：检查 Trae 的 builtin_skills 目录，确认是否存在与您安装的 Skill 同名的工具包，避免因命名冲突导致自定义 Skill 被覆盖。
- 检查 Trae 设置：确认 Trae 的设置中是否包含“启用自定义 Skill”等相关选项，并确保其已开启。
最近更新时间：2026.09.08 20:29:51
这个页面对您有帮助吗？
有用
有用
无用
无用