Media Toolkit 概述
Media Toolkit 是一个面向智能体的媒体处理技能。当目标是从本地文件或远程媒体 URL 运行媒体处理时，可以使用该技能。工具包内部处理所需的输入准备，包括必要时上传本地文件，并默认返回稳定的结构化结果，同时可选将同一 JSON 结果信封写入磁盘以供后续步骤使用。
适用场景
- 用户希望从本地文件或 URL 获取转录、分割结果、前景遮罩或变换后的视频。
- 用户需要从本地文件获得已上传的媒体 URL。
- 其他技能或仓库本地工作流需要机器优先的媒体客户端，而不是直接进行 Python 导入。
- 需要最终任务结果，而不是手动检查队列或工作进程。
- 需要用 job_id 检查既有媒体任务。
工作流程
使用客户端脚本：
./scripts/media_toolkit.sh ...
优先使用规范子命令：
- transcribe
- segment
- transform
- matte
- upload
- status
upload 是一等子命令。它在底层使用共享的本地 upload-media 工具，并返回结构化上传元数据，其中包括已上传的 URL。
直接调用 WIN API 需要 bearer 认证。工具包默认从 ~/.secrets/aipodcasting/env 读取后端令牌，或在覆盖该文件路径时从 AIPODCASTING_WIN_API_KEY_FILE 读取。部署场景支持运行时环境回退（WIN_API_KEY、AIP_API_KEY，或 WIN_API_KEYS/AIP_API_KEYS 中的第一个值）。不要在命令行上传入密钥。
优先使用一个输入定位符：
- --file $HOME/media/video.mp4
- --url https://...
默认输出 JSON。仅在快速 shell 检查时使用 --plain。 对于长时间等待，优先使用默认的 --progress auto 行为，使进度显示在 stderr，而最终结果保留在 stdout。
除非调用方明确需要异步处理，否则让工具包等待：
- 默认：等待任务到达终态并返回最终结果
- --no-wait：返回已提交的 job_id
- status --job-id ... [--wait]：检查或轮询既有任务
- --output /path/result.json：将最终 JSON 信封写入文件
- --progress off|plain|jsonl：控制 stderr 上的等待进度
常用命令
上传本地文件并返回已上传的媒体 URL：
./scripts/media_toolkit.sh
upload --file $HOME/media/video.mp4
--output /tmp/upload.json
转录本地文件：
./scripts/media_toolkit.sh
transcribe --file $HOME/media/audio.mp3
--output /tmp/transcribe.json
transcribe 始终使用 WIN 的 artifact-backed 转录路径。它请求 Mac-backed 的 local_transcription 提供方，保持缓存启用，将本地文件上传到 R2 的 cache/ 下，并返回 data.transcript 以及 data.artifacts.transcript_url、data.artifacts.words_url 和 data.artifacts.sentences_url。当转录应在返回 artifact 前运行 WIN 说话人识别时，传入 --identify-speakers；WIN 在可用时会加上 YouTube 标题/描述上下文。可选标志：--speaker-identification-context 和 --force-speaker-identification。
分割图像：
./scripts/media_toolkit.sh
segment image --file $HOME/media/image.png
--prompt "black ball"
--output /tmp/segment-image.json
仅当明确需要预合成的透明资产时才添加 --with-alpha。对于 Remotion 风格工作流，掩码通常就足够。
分割视频：
./scripts/media_toolkit.sh
segment video --file $HOME/media/video.mp4
--prompt "black ball"
--anchor-seconds 14
--window-start-seconds 12
--window-end-seconds 64
--output /tmp/segment-video.json
segment image 和 segment video 默认生成掩码。仅当明确需要额外的 alpha 产物时才使用 --with-alpha。
变换远程视频：
./scripts/media_toolkit.sh
transform --url https://example.com/video.mp4
--scale-width 1280
--scale-height 720
创建前景遮罩并导出清单：
./scripts/media_toolkit.sh
matte --file $HOME/media/video.mp4
--output /tmp/matte-result.json
检查任务：
./scripts/media_toolkit.sh
status --job-id VIDEO_TRANSFORM_123 --wait
规则
- 保持该技能轻量。工具包脚本是行为的确定性来源。
- 当任务 API 是合适的契约时，不要直接调用媒体处理 Python 内部实现。
- 默认使用 JSON 输出作为契约。
- 保持文件输出简单：--output 写入与 stdout 返回相同的 JSON 信封。
- 使密钥远离标志和 stdout。凭据必须保留在仓库/运行时配置中。
- 需要命令映射或输出契约细节时，阅读 references/cli-contract.md。