@sokeai/cli 1.0.64 → 1.0.65

package/skills/soke-material/SKILL.md

@@ -1,390 +1,105 @@
 ---
 name: soke-material
-summary: 授客素材库管理（上传文件、创建素材、查询素材、管理分类），支持视频/音频/图片/文档等多种类型
 version: 1.0.0
-description: "授客素材库管理：素材库文件管理，包括文件上传到OSS、创建素材记录、查询素材列表和详情、管理素材分类。支持自动检测文件类型和设置默认时长。当用户需要上传文件、管理素材库、查询素材信息时使用。"
-metadata:
-  requires:
-    bins: ["soke-cli"]
-  cliHelp: "soke-cli file --help"
+description: 素材库管理 — 上传视频/音频/文档素材，返回资产元信息供课件创建直接使用
+tags: [soke, material, upload, video, audio, document]
 ---
 
-# 素材库管理 (material)
+# 素材库管理
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+## 触发描述
 
-## ⚠️ 使用前提
+用户需要上传课程素材（视频、音频、文档）到素材库，或从已有素材库中选择素材时触发本技能。
 
-本 skill 基于 **soke-cli** 命令行工具，使用前必须完成以下步骤：
+本技能支持两条路径：
+- **本地上传**：上传本地文件到素材库，返回标准资产信息
+- **素材库选择**：从已有素材库中搜索、浏览、选择已上传的素材
 
-1. **安装 soke-cli**：确保已安装 `@sokeai/cli` NPM 包或 soke-cli 二进制文件
-2. **用户登录授权**：运行 `soke-cli auth login` 完成 OAuth 设备码授权流程，获取用户访问令牌
+## 输入要求
 
-**快速开始**：
-```bash
-
-# 1. 用户登录授权（必须）
-soke-cli auth login
-
-# 3. 验证登录状态
-soke-cli config show
-```
-
-未完成登录授权将无法调用任何素材库管理相关的 API。详细的认证配置说明请参考 [soke-shared/SKILL.md](../soke-shared/SKILL.md)。
-
-## 核心概念
-
-- **Material（素材）**: 素材库中的文件资源，包含视频、音频、图片、文档等类型
-- **OSS（对象存储）**: 阿里云对象存储服务，用于存储素材文件
-- **Upload Signature（上传签名）**: OSS 上传所需的签名信息，包含 accessid、policy、signature 等
-- **Category（素材分类）**: 素材分类，用于组织和管理素材
-
-## 素材类型
-
-| 类型 | 说明 | 支持的文件格式 |
-|------|------|----------------|
-| video | 视频文件 | mp4, avi, mov, wmv, flv, mkv, webm, m4v, mpg, mpeg, 3gp, f4v, rmvb, rm |
-| audio | 音频文件 | mp3, wav, flac, aac, ogg, wma, m4a, ape, aiff |
-| image | 图片文件 | jpg, jpeg, png, gif, bmp, svg, webp, ico, tiff |
-| document | 文档文件 | pdf, ppt, pptx, doc, docx, xls, xlsx, txt 等 |
-
-## 素材上传流程
-
-完整的素材上传流程包括以下步骤：
-
-1. **获取上传签名** - 调用 `/skills/uploadFile/signature` 获取 OSS 上传凭证
-2. **上传文件到 OSS** - 使用签名信息将文件上传到阿里云 OSS
-3. **创建素材记录** - 调用 `/skills/uploadFile/create` 在素材库中创建记录
-
-**推荐使用**: `file +upload` 命令一键完成上述所有步骤
-
-## 可用命令
-
-### 素材上传与创建
-
-#### `file +upload` - 上传文件到素材库（推荐）
-
-一键完成文件上传到 OSS 并创建素材库记录，自动检测文件类型和设置默认时长。
-
-**参数：**
-- `--file` (必填): 本地文件路径
-- `--type` (可选): 文件类型 (video/audio/image/document)，默认自动检测
-- `--length` (可选): 媒体时长（秒），默认视频600秒/音频300秒
-- `--category-id` (可选): 分类ID
-- `--object-name` (可选): OSS对象名称，默认使用文件名
-
-**示例：**
-```bash
-# 自动检测类型和时长
-soke-cli file +upload --file ./video.mp4
-
-# 指定类型和时长
-soke-cli file +upload --file ./audio.mp3 --type audio --length 236
-
-# 指定分类
-soke-cli file +upload --file ./document.pdf --category-id "CATEGORY-UUID"
-```
-
-**返回：**
-- 素材 UUID
-- 文件名
-- 文件类型
-- 文件大小
-- 创建时间
-
-#### `file +create` - 创建素材库记录
-
-将已上传到 OSS 的文件信息保存到素材库（适用于已有 OSS 文件的场景）。
-
-**参数：**
-- `--filename` (必填): 文件名
-- `--object` (必填): OSS 对象路径
-- `--filesize` (必填): 文件大小（字节）
-- `--ext` (必填): 文件扩展名
-- `--type` (必填): 文件类型 (video/audio/image/document)
-- `--length` (可选): 媒体时长（秒）
-- `--category-id` (可选): 分类ID
-
-**示例：**
-```bash
-soke-cli file +create \
-  --filename "video.mp4" \
-  --object "ding123/course/video/abc.mp4" \
-  --filesize 10485760 \
-  --ext "mp4" \
-  --type "video" \
-  --length 600
-```
-
-### 素材查询
-
-#### `file +list-files` - 列出素材库文件
-
-查询素材库文件列表，支持分页和类型筛选。
-
-**参数：**
-- `--page` (可选): 页码，默认 1
-- `--limit` (可选): 每页数量，默认 10
-- `--type` (可选): 文件类型筛选 (video/audio/image/document)
-- `--category-id` (可选): 分类ID筛选
-
-**示例：**
-```bash
-# 列出所有素材
-soke-cli file +list-files
-
-# 列出视频素材
-soke-cli file +list-files --type video --page 1 --limit 20
-
-# 按分类筛选
-soke-cli file +list-files --category-id "CATEGORY-UUID"
-```
-
-#### `file +get-info` - 获取素材详情
-
-获取单个素材的详细信息。
-
-**参数：**
-- `--file-id` (必填): 素材 UUID
-
-**示例：**
-```bash
-soke-cli file +get-info --file-id "6D78C63A-0633-47FB-8F55-72F6F07256A0"
-```
-
-#### `file +download` - 获取素材下载链接
-
-获取素材文件的下载 URL。
+**本地上传：**
+- **文件路径**：本地文件的绝对路径
+- **支持格式**：
+  | 类型 | 扩展名 |
+  |------|--------|
+  | 视频 | `.mp4` `.avi` `.mov` |
+  | 音频 | `.mp3` `.wav` |
+  | 文档 | `.pdf` `.ppt` `.pptx` `.doc` `.docx` |
+- **文件大小**：无硬性限制，由平台存储策略决定
 
-**参数：**
-- `--file-id` (必填): 素材 UUID
-
-**示例：**
-```bash
-soke-cli file +download --file-id "6D78C63A-0633-47FB-8F55-72F6F07256A0"
-```
+**素材库选择：**
+- 由调度方（soke-course）通过弹窗选定素材
+- 素材库中的文件已是上传态，直接返回复用即可
 
+## 执行流程
 
-### 分类管理
+### 第一步：确认文件有效性
 
-#### `file +list-categories` - 列出素材分类
+1. 校验文件存在且可读
+2. 校验扩展名在支持列表中
+3. 获取文件大小（bytes）
 
-查询素材分类列表。
+### 第二步：调用上传接口
 
-**参数：**
-- `--page` (可选): 页码，默认 1
-- `--limit` (可选): 每页数量，默认 10
+使用 CLI 命令上传素材：
 
-**示例：**
 ```bash
-soke-cli file +list-categories
+soke file +upload --path "/absolute/path/to/file"
 ```
 
-## 使用场景
+### 第三步：解析返回结果
 
-### 场景1：上传单个文件
-
-**命令**：
-```
-soke-cli file +upload --file ./course-video.mp4 --format json
-```
+上传成功后返回如下结构体，**全部字段原样保留**，供后续课件创建直接引用：
 
-**响应示例**：
 ```json
 {
-  "success": true,
-  "data": {
-    "uuid": "media-123456",
-    "filename": "course-video.mp4",
-    "filesize": 10485760,
-    "object": "uploads/2024/01/abc123.mp4",
-    "ext": "mp4",
-    "type": "video"
-  }
+  "uuid": "素材唯一标识",
+  "filename": "原始文件名",
+  "type": "video | audio | document",
+  "ext": "mp4 | avi | mov | mp3 | wav | pdf | ppt | pptx | doc | docx",
+  "filesize": 文件字节数,
+  "object": "存储路径/对象键"
 }
 ```
 
-**说明**：返回的素材 UUID 可用于创建课件
+### 第四步：设定默认时长
 
-### 场景2：批量上传文件
+素材默认学习时长按类型分别处理：
 
-**流程说明**：
-1. 对每个文件执行 `file +upload` 命令
-2. 从响应中提取 `data.uuid` 作为 `media_id`
-3. 使用 `media_id` 创建课件
+| 素材类型 | 默认时长（秒） |
+|----------|----------------|
+| `video`  | 600s           |
+| `audio`  | 300s           |
+| `document` | 0s           |
 
-**命令序列**：
-```
-# 对每个文件重复以下步骤：
-
-# 1. 上传文件
-soke-cli file +upload --file "audio1.mp3" --type audio --format json
-# 提取: media_id = data.uuid
-
-# 2. 上传下一个文件
-soke-cli file +upload --file "audio2.mp3" --type audio --format json
-# 提取: media_id = data.uuid
+> 视频和音频实际时长以文件元数据为准；文档类不计时可设 0。
 
-# ... 重复上述步骤
-```
-
-### 场景3：查询和管理素材
+## 输出标准
 
-**查询所有视频素材**：
-```
-soke-cli file +list-files --type video --format json
-```
+完成上传后向用户输出摘要：
 
-**获取素材详情**：
-```
-soke-cli file +get-info --file-id "{file_id}" --format json
 ```
-
-**响应示例**：
-```json
-{
-  "success": true,
-  "data": {
-    "uuid": "media-123456",
-    "filename": "video.mp4",
-    "filesize": 10485760,
-    "object": "uploads/2024/01/abc123.mp4",
-    "ext": "mp4",
-    "type": "video",
-    "length": 600,
-    "category_id": "cat-789",
-    "created_at": "2024-01-01T12:00:00Z"
-  }
-}
+✅ 素材上传成功
+- 文件名: {filename}
+- 类型: {type}
+- 大小: {filesize} bytes
+- UUID: {uuid}
 ```
 
-## 最佳实践
-
-### 1. 文件上传建议
-
-**推荐使用 `file +upload`**：
-- 一键完成 OSS 上传和素材记录创建
-- 自动检测文件类型
-- 自动设置默认时长
-
-**手动流程（不推荐）**：
-- 需要手动获取上传签名
-- 需要手动上传到 OSS
-- 需要手动创建素材记录
-
-### 2. 文件类型检测
-
-系统根据文件扩展名自动检测类型：
-
-| 扩展名 | 检测为类型 |
-|--------|-----------|
-| mp4, avi, mov, wmv, flv, mkv, webm | video |
-| mp3, wav, flac, aac, ogg, wma | audio |
-| jpg, jpeg, png, gif, bmp, svg | image |
-| pdf, doc, docx, ppt, pptx, xls, xlsx | document |
-
-### 3. 默认时长设置
-
-| 文件类型 | 默认时长 |
-|---------|---------|
-| video | 600秒（10分钟） |
-| audio | 300秒（5分钟） |
-| image | 0秒 |
-| document | 0秒 |
-
-**建议**：如果知道准确时长，使用 `--length` 参数指定
-
-### 4. 素材信息提取
-
-上传素材后，响应包含创建课件所需的所有字段：
-
-**必需字段**：
-- `uuid` → 用作 `media_id`
-- `filename` → 文件名
-- `filesize` → 文件大小（字节）
-- `object` → OSS 对象路径
-- `ext` → 文件扩展名
-- `type` → 文件类型
-
-**可选字段**：
-- `length` → 媒体时长（视频/音频）
-- `category_id` → 分类ID
-
-### 5. 错误处理
-
-**检查上传结果**：
-- 验证 `success` 字段为 `true`
-- 验证 `data.uuid` 不为空
-- 如果失败，查看 `err_message` 字段
-
-**常见问题**：
-- 文件不存在 → 检查文件路径
-- 文件类型不支持 → 使用支持的格式
-- 文件大小超限 → 压缩文件（最大 1GB）
-
-### 6. 批量操作建议
-
-**批量上传**：
-- 对每个文件单独调用 `file +upload`
-- 记录每个文件的 `media_id`
-- 可以并行上传以提高效率
-
-**批量查询**：
-- 使用 `--type` 参数按类型筛选
-- 使用 `--category-id` 参数按分类筛选
-- 使用分页参数处理大量数据
-
-### 7. 跨平台兼容性
-
-**文件路径**：
-- 支持相对路径和绝对路径
-- Windows 支持 `/` 和 `\` 两种分隔符
-- 建议使用 `/` 保持跨平台兼容
-
-**JSON 解析**：
-- 使用 `--format json` 获取 JSON 输出
-- 使用各平台的 JSON 解析工具提取字段
-- 命令行: `jq`、PowerShell: `ConvertFrom-Json`、Python: `json.loads()`
-
-## API 接口映射
-
-| CLI 命令 | API 路径 | HTTP 方法 | 说明 |
-|----------|----------|-----------|------|
-| `file +upload` | `/skills/uploadFile/signature` + `/skills/uploadFile/create` | POST | 上传文件并创建素材 |
-| `file +create` | `/skills/uploadFile/create` | POST | 创建素材记录 |
-| `file +list-files` | `/skills/uploadFile/list` | GET | 列出素材列表 |
-| `file +get-info` | `/skills/uploadFile/info` | GET | 获取素材详情 |
-| `file +list-categories` | `/skills/uploadFile/category/list` | GET | 列出素材分类 |
+可将完整返回对象缓存在上下文中，供后续 `soke-lesson` 创建课件时直接引用。
 
 ## 注意事项
 
-1. **文件大小限制**: 单个文件最大 1GB
-2. **支持的存储类型**: aliyun（阿里云OSS）、ding（钉钉存储）
-3. **自动类型检测**: `file +upload` 会根据文件扩展名自动检测类型
-4. **默认时长**: 视频默认 600 秒，音频默认 300 秒，图片和文档为 0
-5. **OSS 路径格式**: `{corpid}/{module}/{type}/{filename}`
-
-## 权限要求
-
-- **写操作 (上传、创建)): `file:file:write`
-- **读操作** (查询、下载): `file:file:readonly`
-
-## 错误处理
-
-常见错误及解决方案：
-
-| 错误码 | 错误信息 | 解决方案 |
-|--------|----------|----------|
-| 1001 | 参数错误 | 检查必填参数是否完整 |
-| 1002 | 文件不存在 | 确认文件路径正确 |
-| 1003 | 文件类型不支持 | 使用支持的文件格式 |
-| 1004 | 文件大小超限 | 压缩文件或分片上传 |
-| 2001 | 上传签名获取失败 | 检查认证信息和网络连接 |
-| 2002 | OSS 上传失败 | 检查网络连接和 OSS 配置 |
-| 3001 | 素材不存在 | 确认素材 UUID 正确 |
+1. 上传前确认文件路径正确，扩展名匹配实际文件类型
+2. 不支持图片格式（`.jpg` `.png` 等），图片应使用其他上传通道
+3. 文档类素材默认时长 0s，如需强制学习时长可在课件创建时覆盖
+4. 返回的 `uuid` 是课件创建的唯一索引，务必保留
+5. 素材上传后默认进入当前租户的素材库，权限与租户一致
 
-## 相关文档
+## 检查清单
 
-- [课程管理 Skill](../soke-course/SKILL.md) - 使用素材创建课件
-- [共享配置 Skill](../soke-shared/SKILL.md) - 认证和配置管理
-- [API 接口文档](../../docs/API_PROXY_INTERFACES.md) - 完整的 API 接口说明
+- [ ] 文件路径存在且可访问
+- [ ] 扩展名在 `.mp4|.avi|.mov|.mp3|.wav|.pdf|.ppt|.pptx|.doc|.docx` 中
+- [ ] 上传完成，获取到完整返回对象（uuid / filename / type / ext / filesize / object）
+- [ ] 默认时长按类型正确设定
+- [ ] 返回数据完整传递给后续课件创建流程