# platform +material-list

> **前置条件：** 先阅读 [`../cai-shared/SKILL.md`](../../cai-shared/SKILL.md) 了解认证、全局参数和安全规则。

查询素材库中的素材列表，支持按文件类型、关键词、父目录筛选，支持分页。

## 命令

```bash
# 默认查询（第 1 页，每页 15 条）
cai-cli platform +material-list

# 按文件类型筛选（2=图片，3=视频，4=PDF）
cai-cli platform +material-list --file-type 2

# 关键词搜索
cai-cli platform +material-list --q "产品图"

# 查询指定目录下的素材
cai-cli platform +material-list --parent-id 1862435987790101287

# 分页
cai-cli platform +material-list --page 2 --page-size 20
```

## 通用 API 调用（备用）

```bash
cai-cli api GET /gcli/cliapi/material/list --params '{"p":1,"s":15,"fileType":2}'
```

## 参数

| Flag | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--page` | int | `1` | 页码，从 1 开始 |
| `--page-size` | int | `15` | 每页数量 |
| `--file-type` | int | - | 文件类型：`2`=图片，`3`=视频，`4`=PDF（不填=全部） |
| `--q` | string | - | 搜索关键词，匹配文件名 |
| `--parent-id` | string | `0` | 父目录 ID，`0` 表示根目录 |

## 响应字段（`data` 对象）

| 字段 | 类型 | 说明 |
|------|------|------|
| `total` | int | 总记录数 |
| `p` | int | 当前页码 |
| `s` | int | 每页数量 |
| `list` | array | 素材列表，见下表 |

### list 数组 — 素材对象

| 字段 | 类型 | 必有 | 说明 |
|------|------|------|------|
| `id` | string | ✓ | 素材 ID |
| `parentId` | string | ✓ | 父目录 ID，`"0"` 表示根目录 |
| `fileName` | string | ✓ | 文件名（不含扩展名） |
| `fileType` | int | ✓ | `1`=目录，`2`=图片，`3`=视频，`4`=PDF |
| `uploadTime` | int | ✓ | 上传时间（毫秒时间戳） |
| `updateTime` | int | ✓ | 最后更新时间（毫秒时间戳） |
| `statusText` | string | ✓ | 状态文字：`"上传成功"` / `"审核中"` / `"审核通过"` / `""` |
| `fileSize` | string | 否 | 文件大小（字节，**字符串类型**；目录无此字段） |
| `fileExt` | string | 否 | 扩展名，如 `"mp4"`、`"PNG"`（目录无） |
| `width` | int | 否 | 宽度（像素） |
| `height` | int | 否 | 高度（像素） |
| `url` | string | 否 | CDN 访问地址 |
| `downloadUrl` | string | 否 | 下载地址 |
| `thumbUrl` | string | 否 | 缩略图地址（图片/视频封面） |
| `duration` | string | 否 | 视频时长（秒，**字符串类型**；仅视频有） |
| `fileMd5` | string | 否 | 文件 MD5（仅视频有） |
| `auditStatus` | int | 否 | `2`=审核中或审核通过（靠 `statusText` 区分），`3`=审核不通过（仅视频/PDF） |
| `auditReason` | string | 否 | 审核不通过原因（仅视频/PDF） |

> `fileSize` 和 `duration` 均为**字符串**，使用时需转换为数字。

## jq 使用示例

```bash
# 获取所有图片的 url 列表
cai-cli platform +material-list --file-type 2 --page-size 100 --jq '.list[] | .url'

# 查看总数
cai-cli platform +material-list --jq '.total'

# 只看文件名和状态
cai-cli platform +material-list --jq '[.list[] | {id, fileName, statusText}]'

# 搜索并只取 id 和 url
cai-cli platform +material-list --q "banner" --jq '[.list[] | {id, url}]'
```

## 风险等级

`read`（只读，不修改任何数据）

## 参考

- [cai-platform](../SKILL.md) — 平台管理全部命令
- [cai-shared](../../cai-shared/SKILL.md) — 认证和全局参数