# 批量任务与报告交付

## 直接提交用例

用户要求执行明确的测试集合时，将每个独立目标转成一个 case。`parameters` 是简单值字典，`tags` 是字符串，不能填列表；目标中的 `{{参数名}}` 会替换成参数值。前置条件用自然语言描述真实起点。

先生成唯一 `request_id`（例如 UUID），保存在当前任务记录中，然后调用：

```json
{
  "action": "create",
  "request_id": "52c3e95d-7e31-4e41-b42d-27aa3774fb2d",
  "batch": {
    "name": "系统设置冒烟测试",
    "device_serial": "用户已选择的设备编号",
    "profile": "pro",
    "formats": ["docx", "xlsx"],
    "stop_on_failure": false,
    "timeout_seconds": 1800,
    "cases": [
      {
        "name": "设置首页可达",
        "goal": "打开系统设置，确认设置首页可见，不修改任何设置。",
        "expected": "能看到设置首页及至少一个设置分类，记录实际文字与截图证据。",
        "app": "com.android.settings",
        "preconditions": "设备已解锁。",
        "parameters": {},
        "tags": "冒烟,只读"
      }
    ]
  }
}
```

`create` 只保存已校验的草稿。检查返回批次编号和范围，用户已经授权执行时接着 `mobile_batch(action="start", batch_id=...)`；用户只要求准备方案时留在草稿，不启动。保存 `batch_id`，用 `get` 跟踪各项状态。

创建请求超时可能已经落库。先 `lookup(request_id=...)`；需要重发时保留**相同 request_id 和相同内容**。服务会返回原批次，内容不同会拒绝。不要通过换编号“修复超时”，否则会形成重复批次。

## Excel 导入

`mobile_task_file(action="template")` 返回空白模板的本地路径。标准列为任务名称、任务目标、预期结果、目标应用、前置条件、输入参数(JSON)、标签。每行独立，不支持公式、宏、外部链接。

`preview` 返回 `valid/tasks/errors`，不会执行。所有错误处理完后，将 `tasks` 中每项的预览字段 `row` 去掉，作为 `batch.cases` 提交。不要跳过错误行却声称全部导入成功。

## 状态与异常

- 批次 `draft` 等待开始；`running` 调度中；`paused` 等待处理；`completed` 表示所有项进入终态，不代表全部通过。
- 单项 `pending/queued/running/finalizing` 尚未结束，`completed/failed/cancelled/interrupted/skipped` 是终态。`finalizing` 在生成报告，不能提前宣称报告已完成。
- `pause` 保留当前执行。设备断开、模型持续失败或任务达到批次时限会暂停后续派发；用诊断确认恢复后再响应用户的继续指令。
- `resume` 只继续未开始项；`retry_failed` 复制失败、取消和中断项为新草稿，不修改原结果。必须来自用户的明确重跑请求。该动作不提供创建去重，响应不确定时先 `list` 查找新批次，不自动重复调用。

## 报告

`mobile_export_report(batch_id=...)` 下载批次 ZIP，包含汇总和各项报告，格式由创建批次时的设置决定。单任务传 `session_id`（单任务 MCP 的 `trace_id`）以及可选 `formats=["docx"]`。默认格式通过 `mobile_config(section="reports")` 查看。

结果文件在 MCP 主机的 `artifacts/mcp_exports/`。不要把 Office 文件内容当作文本塞入上下文；先检查工具返回的结构化结论，需要进一步审阅时再用宿主具备的文档工具打开文件。失败和未验证项也必须交付，保持原始证据。