byted-mediakit-shared

# The MIT License (MIT)

Copyright © 2025 Beijing Volcano Engine Technology Ltd.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE

# 异步任务查询

## 能力用途

查询异步任务状态与结果

## 参数填写规则

- task_id 必须来自真实异步任务受理结果；可选轮询参数仅在用户明确指定，或可从用户意图准确确定时填写，不得伪造。
- `max_poll_timeout_seconds` 默认 `0` 表示不限制；仅在用户明确需要限制单次轮询总时长时填写。`poll_interval_seconds × max_poll_attempts` 不得超过该上限。

## Cloud

### 命令与生命周期

- 命令：`mediakit-cli shared query-task`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。

### 使用指南

- 布尔参数（`--poll-complete`）只能写成 `--poll-complete=true` 或 `--poll-complete=false`，也可用裸 `--poll-complete`（等价 true）；禁止空格传值 `--poll-complete true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。

### 调用示例

```bash
mediakit-cli shared query-task \
  --task-id <task_id>
```

仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。

### 参数

| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `max_poll_attempts` | `--max-poll-attempts` | integer | 否 | 0 | 最小值: 0 | 最多轮询次数；0 表示只查询一次。与 `poll_interval_seconds` 的乘积不得超过 `max_poll_timeout_seconds`。 |
| `poll_complete` | `--poll-complete` | boolean | 否 | false | - | 是否持续轮询直到任务进入终态。 |
| `poll_interval_seconds` | `--poll-interval-seconds` | number | 否 | 10 | 大于: 0 | 轮询间隔，单位为秒；必须大于 0，仅在持续轮询时使用。 |
| `max_poll_timeout_seconds` | `--max-poll-timeout-seconds` | number | 否 | 0 | 最小值: 0 | 轮询总时长上限，单位为秒；0 表示不限制。 |
| `task_id` | `--task-id` | string | 是 | - | - | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |

### 返回结果

| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `error` | any | 否 | Cloud | 失败终态的原始错误内容；仅在实际失败且后端返回时出现。 |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端实际返回非空值时出现。 |
| `status` | string | 否 | Cloud | 任务状态；completed 为成功终态，failed、canceled 或 cancelled 为失败终态。 |
| `success` | boolean | 否 | Cloud | 失败终态返回 false；其他状态仅在后端实际返回时出现。 |
| `task_id` | string | 否 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `usage` | object | 否 | Cloud | 可选顶层返回字段。仅对已开放该字段的账号，在 Cloud 同步调用成功，或 query_task 查询到 completed 终态，且服务实际产生并返回正向计费用量时透传；其他状态、异步提交及 Local 调用不返回。 |
| `usage.normalized_usage` | number | 是 | Cloud | 归一化后的计费用量。由服务端按 BillingCount / 固定单位换算值 × list_price 计算，结果保留 6 位小数；客户端只校验并原样透传，不计算、推断或补齐。 |

### 机器合同

以下命令只读取本模式的实时 help/schema，不发起业务调用：

```bash
mediakit-cli shared query-task --help
mediakit-cli shared query-task --schema
```

---
name: byted-mediakit-shared
version: '0.2.1'
license: 'MIT'
description: 'MediaKit 是面向音视频与图像处理的专业工具集，覆盖视频剪辑与合成、音频处理、视频理解与增强、图像处理与内容理解等工作流。用户明确提出剪辑、拼接、裁剪、转场、滤镜、运镜、混音、提取字幕、语音转字幕、音视频处理、图片处理、视频分析或画质增强目标时，先加载本 Skill，再按对象和目标选择 audio、editing、image 或 video。不承担具体能力参数说明。'
permissions:
  - shell
metadata:
  requires:
    bins: ['mediakit-cli']
  cliHelp: 'mediakit-cli --help'
  product: mediakit-cli/skills
  domain: shared
  capability_count: 0
---

# 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`，必须注入。

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

```bash
MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video --video-url <url> --sub-image-url <url>
MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli shared query-task --task-id <task_id>
```

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

## 能力范围

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

## 能力选择与优先加载

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

| 用户目标                                                 | 优先加载                 |
| -------------------------------------------------------- | ------------------------ |
| 对现有素材进行裁剪、拼接、转场、滤镜、运镜、叠加、混音或成片编排 | `byted-mediakit-editing` |
| 处理音频转码、音轨、语音边界或人声与背景声                   | `byted-mediakit-audio`   |
| 处理单张或批量图片、尺寸体积治理、文字识别、图片质量或图像编辑 | `byted-mediakit-image`   |
| 视频理解、高光拆条、抽帧、画质增强或检测、提取字幕、语音转字幕、字幕擦除、水印、隐私、转码或视频智能处理 | `byted-mediakit-video`   |

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

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

## 安装与可用性检查

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

```bash
npx @volcengine/mediakit-cli install -y
```

安装后验证公开入口：

```bash
mediakit-cli --version
mediakit-cli --help
```

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

```bash
npx @volcengine/mediakit-cli install --skills-only -y
```

## 初始化与检查

```bash
mediakit-cli init
mediakit-cli config show
mediakit-cli doctor
```

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

## 命令发现与机器合同

```bash
mediakit-cli --domains
mediakit-cli <domain> --help
mediakit-cli <domain> <tool> --help
mediakit-cli <domain> <tool> --schema
```

`--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` 只显示所选模式的
参数与结果。

规范命令顺序为：

```bash
mediakit-cli --cloud <domain> <tool> [flags]
mediakit-cli --local <domain> <tool> [flags]
```

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

```bash
mediakit-cli config set output-path <输出目录>
```

## 异步结果

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

```bash
mediakit-cli shared query-task --task-id <task_id>
```

需要持续等待终态时，按 [query_task.md](reference/query_task.md) 中的查询协议执行。

## 更新

```bash
mediakit-cli update
mediakit-cli update --check
mediakit-cli version --check
```

## 共享查询协议

| 协议       | 说明                                    | 命令                             | 参考                                               |
| ---------- | --------------------------------------- | -------------------------------- | -------------------------------------------------- |
| query-task | 查询 Cloud 异步任务状态与终态业务结果。 | `mediakit-cli shared query-task` | [reference/query_task.md](reference/query_task.md) |