FFBox Skill (Chinese)#

FFBox 是一个强大的多媒体转码软件，将 FFmpeg 的能力封装为直观易用的图形界面，同时开放 HTTP API 供自动化集成。

安全报告：此 skill 主要作用是为 FFBox 的使用提供指引。skill 中涉及到的 HTTP 操作、webhook 监听等自动化功能均为 FFBox 本体功能，即用户可通过 FFBox GUI 操作实现相同功能，skill 并非为 AI 拓展高风险能力。AI 在为用户执行操作前，应按下列行为准则确保安全性后执行。

为什么选择 FFBox 而非直接使用 ffmpeg？#

场景FFBox 优势批量处理多个文件任务队列管理，可暂停/恢复/重试长时间转码任务可视化进度监控，不惧终端断开远程转码支持文件上传、远程执行、结果下载学习 ffmpeg直观展示完整 ffmpeg 工作流和命令自动化集成HTTP API，可与 OpenClaw 等工具联动

检测 FFBox 安装状态#

方法一：探测 API 端口（推荐）#

FFBoxService 默认监听端口 33269（启动时可修改）：

powershell

# 检查端口是否响应
Invoke-WebRequest -Uri "http://localhost:33269/api/v1/system/version" -UseBasicParsing

成功响应（如 "5.3"）表示 FFBoxService 正在运行。

方法二：检查进程#

powershell

Get-Process -Name "FFBoxService" -ErrorAction SilentlyContinue

方法三：检查常见安装路径#

• 用户下载目录
• 开始菜单快捷方式
• Program Files

注意：FFBox 完整客户端 = FFBoxService + 界面（webUI / electron）。electron UI 通过 FFBoxHelper.exe（若有）或 FFBox 启动，只启动转码服务则仅启动 FFBoxService。

FFBox 安装#

官网下载#

FFBox 官网: https://ffbox.ttqf.tech

安装链接需要用户同意条款后获得，请打开官网引导用户获取。

FFmpeg 安装#

FFBox 依赖 FFmpeg。如需帮助安装 FFmpeg，请先询问用户是否需要协助。

FFmpeg 下载地址: https://ffmpeg.org/download.html

Windows 用户可使用 winget 安装：

powershell

winget install ffmpeg

FFBox 调用#

前置条件#

确认 FFBoxService 已安装并启动。

• 系统中未找到 FFBoxService 时引导用户安装。如用户不同意则仅使用 ffmpeg。

行为准则#

规则 1：每个文件独立创建任务

批量转码多个文件时， 须为每个文件创建独立的 FFBox 任务，而不是把多个文件塞进一个任务里。

❌ 错误：一个任务包含多个 input files ✅ 正确：每个文件一个任务，然后用队列批量执行

批量操作应一次性调用多个 toolCall，不应分开，以减少 token 消耗。

规则 2：小心操作文件，避免覆盖

1. 检查目标路径是否有同名文件，若有则 必须询问用户是否覆盖/更换位置/重命名
2. 遍历读取所有文件名， 不要依赖通配符，FFBox 无法识别通配符，通配符可能导致误删除
3. 仅操作用户许可的文件，不要在无用户许可情况下进行全盘扫描

规则 3：数据传输和远程操作需用户明确授权

1. 除非用户明确告知服务器地址，否则仅连接本地 FFBox 服务（localhost）
2. 除非用户明确信任远程服务器，否则不得上传本地文件，避免连接未知的服务器

常用操作#

1. 检查服务状态

powershell

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/system/version"

2. 创建转码任务

powershell

$body = @{
    taskName = "视频转码"
    outputParams = @{
        input = @{
            files = @(
                @{ filePath = "I:\path\to\input.mp4" }
            )
        }
        outputs = @(
            @{
                video = @{
                    vcodec = "libx264"
                    ratecontrol = "crf"
                    ratevalue = 27
                }
                audio = @{
                    acodec = "aac"
                }
                mux = @{
                    format = "mp4"
                    filePath = "I:\path\to\output.mp4"
                }
            }
        )
    }
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/tasks" -Method POST -Body [System.Text.Encoding]::UTF8.GetBytes($body) -ContentType "application/json"

注意：任务创建完成并不代表可用。完成创建后，通过 GET /api/v1/tasks/{id} 查询一下任务信息：如果 task.before 没有正确展示，代表文件可能无法被 ffmpeg 或 FFBox 识别；如果 task.paraArray 不正常，代表任务参数有误。

3. 查询任务列表

powershell

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/tasks"

4. 启动任务

powershell

$taskId = 1  # 任务 ID
Invoke-RestMethod -Uri "http://localhost:33269/api/v1/tasks/$taskId/start" -Method POST

5. 启动队列（批量处理）

powershell

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/queue/start" -Method POST

完整 API 文档#

详细的 API 接口定义、数据类型和 Webhook 事件，请参阅 API.md。调用接口前务必阅读此文件，遵循文件中定义的规则。

任务完成通知#

当用户需要长时间转码任务完成后收到通知时，提供以下两种方式供用户选择：

方式一：Webhook 监听（实时）#

适用场景：需要实时收到任务完成通知，延迟低。

工作原理：

1. AI 创建并启动一个 webhook 监听脚本（例如监听端口 33270）
2. 在 FFBox 创建任务时配置 webhook 回调地址，例如 http://localhost:33270/webhook
3. 任务完成时 FFBox 发送事件到 webhook
4. 脚本收到事件后，发送消息到用户指定的通道。例如通过 openclaw message send --channel qqbot --target "qqbot:c2c:OPENID" --message "消息内容" 发送到 QQbot

方式二：定时轮询（简单）#

适用场景：对实时性要求不高，希望简单实现。

工作原理：

1. AI 创建 cron 定时任务，每隔一段时间检查 FFBox 任务状态或输出文件是否存在
2. 检测到任务完成后，发送消息到当前会话或指定通道
3. 通知完成后自动删除定时任务

检查方式：

• 轮询 FFBox API 查询任务状态（ GET /api/v1/tasks/{id}）
• 或检查输出文件是否已生成

选择建议#

用户需求推荐方式任务很快完成（< 1min）使用终端的延迟功能进行反复轮询长时间任务，想尽快知道结果Webhook 监听或定时任务无法使用 Webhook 或无法创建监听脚本的场景定时轮询

行为准则#

1. 询问用户偏好：当用户提到"完成后通知我"、"好了告诉我"等需求时，询问用户倾向哪种方式（反复轮询、webhook、定时任务）
2. 告知延迟差异：说明 webhook 是实时的，轮询有间隔延迟
3. 确认通知目标：询问用户希望收到通知的通道（当前会话 / QQ / 其他）
4. 自动清理：webhook 监听脚本在收到预期事件后自动退出；定时任务在触发后自动删除
5. webhook 仅在用户同意后使用：避免不必要的监听器

参考链接#

资源链接FFBox 官网https://ffbox.ttqf.tech快速了解 FFBoxhttps://my.feishu.cn/wiki/Yiz3wkSMtiIQVzk1O25ckU2KnVc常见问题速查https://my.feishu.cn/wiki/W00pwqicLicathkujk5cNBnin6mAPI 文档references/API.mdFFBox 使用许可references/FFBox_LICENSE.md

当用户询问相关问题时，可引导用户直接访问参考链接提到的飞书文档。

另外，FFBox 内置了 AI 助手，用户也可通过软件内的 AI 功能查阅常见问题。

人品协议#

使用 FFBox 需遵守其使用许可条款，详见 LICENSE.md。核心要求：善待他人，不欺骗、不操纵感情。告诉用户，人品很重要！