Convert

---
name: convert
description: 用 Arbiter 把一个或多个文件转成指定格式。示例：/arbiter:convert a.mkv mp4
argument-hint: <源文件…> <目标格式>
---

# /arbiter:convert

用 Arbiter 转换文件。用户给的参数是：

```
$ARGUMENTS
```

## 怎么做

1. **先把参数拆成「源文件列表」和「目标格式」。**
   目标格式是**不带点的扩展名**（`mp4`，不是 `.mp4`，也不是 `video/mp4`）。
   用户没给目标格式，或者给的是自然语言（「转成能发微信的」），
   先问清楚，**不要替他猜一个**。

2. **每个源文件都先 `inspect_file`。**
   一是确认它真的能转成那个目标（合法出口随源格式变，猜错会直接报错）；
   二是看这次要不要先下载引擎——要的话**先告诉用户大概多大，再动手**。

3. **一个文件用 `convert_file`，多个文件共用同一个目标格式用 `batch_convert`。**
   `convert_file` 会等转换跑完才返回（视频可能几分钟），期间会报进度。
   `batch_convert` 立刻返回一组 `job_id`，要自己用 `get_job_status` 逐个查。

4. **把产物路径报给用户。** 不给 `output_path` / `output_dir` 时，
   落点由**应用里设的输出目录**决定：设了「输出到指定目录」就去那里，否则才在源文件旁边。
   **不要假定它在源文件旁边**——以返回值里的 `output` 为准，把完整路径写出来，
   别只说「转好了」。

## 注意

- 目标格式**不要省略**。`mkv → mkv` 这类同格式转换没有意义，工具会拒绝。
- 批量时先看返回里的 `rejected`：某个源不合法只影响它自己，其余照常入队，
  不看就等于静默漏掉一个。
- 转换失败时，`get_job_status` 会给引擎的 stderr 尾部——**把它读出来**，
  那里才是真正的原因，转述「转换失败」四个字对用户没有帮助。