@sokeai/cli 1.0.41 → 1.0.53

package/skills/soke-lesson/SKILL.md

@@ -0,0 +1,510 @@
+---
+name: soke-lesson
+summary: 授客课件管理（创建课件、查询课件），支持视频/音频/文档等多种类型
+version: 1.0.0
+description: "授客课件管理：课件生命周期管理，包括基于素材创建课件、查询课件列表和详情、管理课件排序。支持视频、音频、文档等多种课件类型。当用户需要添加课件、管理课件、查询课件信息时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli course --help"
+---
+
+# 课件管理 (lesson)
+
+**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
+
+# 2. 验证登录状态
+soke-cli config show
+```
+
+未完成登录授权将无法调用任何课件管理相关的 API。详细的认证配置说明请参考 [soke-shared/SKILL.md](../soke-shared/SKILL.md)。
+
+## 核心概念
+
+- **Lesson（课件）**: 课程下的学习单元，包含视频、音频、文档等类型的学习内容
+- **Material（素材）**: 课件关联的素材文件，必须先上传到素材库才能创建课件
+- **Course（课程）**: 课件所属的课程，通过 `course_id` 关联
+- **Sort Order（排序）**: 课件在课程中的显示顺序，按创建时间自动排序
+
+## 课件类型
+
+| 类型 | 说明 | 对应素材类型 |
+|------|------|-------------|
+| video | 视频课件 | video |
+| audio | 音频课件 | audio |
+| document | 文档课件 | document |
+
+## 课件创建流程
+
+完整的课件创建流程：
+
+1. **上传素材** - 使用 `file +upload` 上传文件到素材库，获取 `media_id`
+2. **创建课件** - 使用 `course +lesson-create` 基于素材创建课件
+3. **发布课程** - 课件添加完成后，使用 `course +publish` 发布课程
+
+## 可用命令
+
+### 课件创建
+
+#### `course +lesson-create` - 创建课件
+
+基于素材库文件创建课件并关联到课程。
+
+**参数：**
+- `--course-id` (必填): 课程 UUID
+- `--title` (必填): 课件标题
+- `--media-id` (必填): 素材库文件 UUID（通过 `file +upload` 获取）
+- `--type` (必填): 课件类型 (video/audio/document)
+- `--length` (必填): 媒体时长（秒，文档类型可填 0）
+- `--object` (必填): OSS 对象路径
+- `--filename` (必填): 文件名
+- `--ext` (必填): 文件扩展名
+- `--filesize` (必填): 文件大小（字节）
+- `--storage` (可选): 存储类型，默认 "aliyun"
+- `--description` (可选): 课件描述
+
+**示例：**
+```bash
+# 创建视频课件
+soke-cli course +lesson-create \
+  --course-id "COURSE-UUID" \
+  --title "第一课：入门介绍" \
+  --media-id "MATERIAL-UUID" \
+  --type "video" \
+  --length 600 \
+  --object "ding123/course/video/lesson1.mp4" \
+  --filename "lesson1.mp4" \
+  --ext "mp4" \
+  --filesize 10485760
+
+# 创建音频课件
+soke-cli course +lesson-create \
+  --course-id "COURSE-UUID" \
+  --title "第二课：音频讲解" \
+  --media-id "MATERIAL-UUID" \
+  --type "audio" \
+  --length 236 \
+  --object "ding123/course/audio/lesson2.mp3" \
+  --filename "lesson2.mp3" \
+  --ext "mp3" \
+  --filesize 9453464
+```
+
+**返回：**
+- 课件 UUID
+- 课件标题
+- 课件类型
+- 关联的素材信息
+
+### 课件查询
+
+#### `course +lesson-list` - 列出课程的课件列表
+
+查询指定课程下的所有课件。
+
+**参数：**
+- `--course-id` (必填): 课程 UUID
+
+**示例：**
+```bash
+soke-cli course +lesson-list --course-id "COURSE-UUID"
+```
+
+**返回：**
+- 课件列表（包含 UUID、标题、类型、时长、排序等信息）
+
+#### `course +lesson-get` - 获取课件详情
+
+获取单个课件的详细信息。
+
+**参数：**
+- `--lesson-id` (必填): 课件 UUID
+
+**示例：**
+```bash
+soke-cli course +lesson-get --lesson-id "LESSON-UUID"
+```
+
+**返回：**
+- 课件详细信息（包含素材信息、转换状态等）
+
+
+## 使用场景
+
+### 场景1：为课程添加单个课件
+
+**步骤说明**：
+1. 上传素材到素材库
+2. 从上传响应中提取完整文件信息
+3. 使用提取的信息创建课件
+
+**步骤1：上传素材**
+```
+soke-cli file +upload --file ./lesson1.mp4 --format json
+```
+
+**响应示例**：
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "media-123456",
+    "filename": "lesson1.mp4",
+    "filesize": 10485760,
+    "object": "uploads/2024/01/abc123.mp4",
+    "ext": "mp4",
+    "type": "video"
+  }
+}
+```
+
+**提取字段**：
+- `data.uuid` → `media_id`
+- `data.filename` → `filename`
+- `data.filesize` → `filesize`
+- `data.object` → `object`
+- `data.ext` → `ext`
+- `data.type` → `type`
+
+**步骤2：创建课件**（使用步骤1提取的信息）
+```
+soke-cli course +lesson-create \
+  --course-id "{course_id}" \
+  --title "第一课" \
+  --media-id "media-123456" \
+  --type "video" \
+  --length 600 \
+  --object "uploads/2024/01/abc123.mp4" \
+  --filename "lesson1.mp4" \
+  --ext "mp4" \
+  --filesize 10485760
+```
+
+### 场景2：批量添加课件
+
+**流程说明**：
+1. 对每个文件重复"上传素材 → 创建课件"流程
+2. 保持 `course_id` 不变
+3. 每个课件使用不同的 `title`
+
+**命令序列**：
+```
+# 对每个文件重复以下步骤：
+
+# 文件1：
+# 1. 上传素材
+soke-cli file +upload --file "lesson1.mp4" --format json
+# 提取: media_id, filename, filesize, object, ext, type
+
+# 2. 创建课件
+soke-cli course +lesson-create \
+  --course-id "{course_id}" \
+  --title "第1课" \
+  --media-id "{media_id}" \
+  --type "{type}" \
+  --length 600 \
+  --object "{object}" \
+  --filename "{filename}" \
+  --ext "{ext}" \
+  --filesize {filesize}
+
+# 文件2：
+# 1. 上传素材
+soke-cli file +upload --file "lesson2.mp4" --format json
+# 提取: media_id, filename, filesize, object, ext, type
+
+# 2. 创建课件
+soke-cli course +lesson-create \
+  --course-id "{course_id}" \
+  --title "第2课" \
+  --media-id "{media_id}" \
+  --type "{type}" \
+  --length 600 \
+  --object "{object}" \
+  --filename "{filename}" \
+  --ext "{ext}" \
+  --filesize {filesize}
+
+# ... 重复上述步骤
+```
+
+### 场景3：管理课件
+
+**查询课程的所有课件**：
+```
+soke-cli course +lesson-list --course-id "{course_id}" --format json
+```
+
+**响应示例**：
+```json
+{
+  "success": true,
+  "data": {
+    "list": [
+      {
+        "uuid": "lesson-123",
+        "title": "第一课",
+        "type": "video",
+        "length": 600,
+        "sort_order": 1
+      }
+    ]
+  }
+}
+```
+
+**获取课件详情**：
+```
+soke-cli course +lesson-get --lesson-id "{lesson_id}" --format json
+```
+
+**响应示例**：
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "lesson-123",
+    "title": "第一课",
+    "type": "video",
+    "length": 600,
+    "media_id": "media-456",
+    "filename": "lesson1.mp4",
+    "filesize": 10485760,
+    "object": "uploads/2024/01/abc123.mp4"
+  }
+}
+```
+
+## API 接口映射
+
+| CLI 命令 | API 路径 | HTTP 方法 | 说明 |
+|----------|----------|-----------|------|
+| `course +lesson-create` | `/skills/course/lesson/create` | POST | 创建课件 |
+| `course +lesson-list` | `/skills/course/lesson/list` | GET | 列出课件列表 |
+| `course +lesson-get` | `/skills/course/lesson/{id}` | GET | 获取课件详情 |
+| `course +lesson-update` | `/skills/course/lesson/{id}` | PUT | 更新课件信息 |
+## 课件与素材的关系
+
+```
+素材库 (Material)
+    ↓ (通过 media_id 关联)
+课件 (Lesson)
+    ↓ (通过 course_id 关联)
+课程 (Course)
+```
+
+**重要说明：**
+1. 课件必须关联素材库中的文件（通过 `media_id`）
+2. 一个素材可以被多个课件使用
+4. 删除素材会影响关联的课件
+
+## 课件参数说明
+
+### 必填参数详解
+
+| 参数 | 说明 | 如何获取 |
+|------|------|----------|
+| course_id | 课程UUID | 通过 `course +create` 创建课程时返回 |
+| media_id | 素材UUID | 通过 `file +upload` 上传素材时返回 |
+| title | 课件标题 | 用户自定义 |
+| type | 课件类型 | 根据素材类型设置 (video/audio/document) |
+| length | 媒体时长 | 视频/音频的实际时长（秒），文档填 0 |
+| object | OSS路径 | 从素材信息中获取 |
+| filename | 文件名 | 从素材信息中获取 |
+| ext | 文件扩展名 | 从素材信息中获取 |
+| filesize | 文件大小 | 从素材信息中获取（字节） |
+
+### 从素材信息获取参数
+
+**推荐方式**：直接从 `file +upload` 响应中提取所有参数
+
+**上传素材命令**：
+```
+soke-cli file +upload --file "lesson.mp4" --format json
+```
+
+**响应包含所有必需字段**：
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "media-123456",
+    "filename": "lesson.mp4",
+    "filesize": 10485760,
+    "object": "uploads/2024/01/abc123.mp4",
+    "ext": "mp4",
+    "type": "video",
+    "length": 600
+  }
+}
+```
+
+**字段映射**：
+
+| 课件参数 | 来源字段 | 说明 |
+|---------|---------|------|
+| media-id | data.uuid | 素材 UUID |
+| type | data.type | 文件类型（video/audio/document） |
+| length | data.length 或默认值 | 媒体时长（秒） |
+| object | data.object | OSS 对象路径 |
+| filename | data.filename | 文件名 |
+| ext | data.ext | 文件扩展名 |
+| filesize | data.filesize | 文件大小（字节） |
+
+**时长设置**：
+- 如果响应中有 `length` 字段，直接使用
+- 如果没有，根据类型设置默认值：
+  - video → 600秒
+  - audio → 300秒
+  - document → 0秒
+
+**不推荐的方式**：
+- ❌ 手动填写 `--object` 路径
+- ❌ 本地计算 `--filesize`
+- ❌ 额外调用 `file +get-info` 查询素材信息
+
+## 最佳实践
+
+### 1. 素材上传与信息提取
+
+**关键原则**：素材上传响应包含创建课件所需的所有信息，直接提取使用。
+
+**正确流程**：
+1. 调用 `file +upload` 上传文件
+2. 从响应的 `data` 字段提取所有必需信息
+3. 使用提取的信息调用 `course +lesson-create`
+
+**错误做法**：
+- ❌ 手动构造 OSS 路径
+- ❌ 猜测文件大小或扩展名
+- ❌ 上传后再查询素材详情
+
+### 2. 课件类型匹配
+
+课件类型必须与素材类型一致：
+
+| 素材类型 | 课件类型 | 说明 |
+|---------|---------|------|
+| video | video | 视频课件 |
+| audio | audio | 音频课件 |
+| document | document | 文档课件 |
+
+**建议**：直接使用素材上传响应中的 `type` 字段
+
+### 3. 时长设置规则
+
+| 课件类型 | 时长要求 | 默认值 |
+|---------|---------|--------|
+| video | 必填，单位秒 | 600秒（10分钟） |
+| audio | 必填，单位秒 | 300秒（5分钟） |
+| document | 填 0 | 0秒 |
+
+### 4. 批量创建建议
+
+**批量创建课件**：
+- 对每个文件重复"上传 → 创建"流程
+- 保持 `course_id` 不变
+- 使用不同的 `title` 区分课件
+- 可以并行上传素材以提高效率
+
+**命名建议**：
+- 使用序号：第1课、第2课、第3课
+- 使用主题：入门介绍、基础语法、高级特性
+- 使用文件名：从文件名中提取标题
+
+### 5. 错误处理
+
+**检查点**：
+- 素材上传成功（`success: true`）
+- 提取的 `media_id` 不为空
+- 课件创建成功（`success: true`）
+- 课件类型与素材类型匹配
+
+**常见错误**：
+- `course_id` 无效 → 确认课程已创建
+- `media_id` 无效 → 确认素材上传成功
+- 类型不匹配 → 检查 `type` 参数
+- 参数缺失 → 检查所有必填参数
+
+### 6. 数据流转
+
+**完整的数据流转链路**：
+
+```
+1. 上传素材
+   输入: 文件路径
+   输出: media_id, filename, filesize, object, ext, type, length
+   
+2. 创建课件
+   输入: course_id + 步骤1的所有输出 + title
+   输出: lesson_id
+   
+3. 查询验证
+   输入: lesson_id 或 course_id
+   输出: 课件详情或课件列表
+```
+
+### 7. 跨平台兼容性
+
+**文件路径**：
+- 支持相对路径和绝对路径
+- Windows 支持 `/` 和 `\` 两种分隔符
+- 建议使用 `/` 保持跨平台兼容
+
+**JSON 解析**：
+- 使用 `--format json` 获取 JSON 输出
+- 使用各平台的 JSON 解析工具：
+  - 命令行: `jq`
+  - PowerShell: `ConvertFrom-Json`
+  - Python: `json.loads()`
+  - Node.js: `JSON.parse()`
+
+**命令执行**：
+- 所有命令在 Windows、macOS、Linux 上通用
+- 只需根据平台选择合适的 JSON 解析方法
+
+## 注意事项
+
+1. **素材必须先上传**: 创建课件前必须先上传素材到素材库
+2. **类型匹配**: 课件类型必须与素材类型匹配
+3. **时长设置**: 视频和音频必须设置正确的时长，文档类型填 0
+4. **排序规则**: 课件按创建时间自动排序，也可以手动调整 `sort_order`
+6. **发布要求**: 课程至少需要一个课件才能发布
+
+## 权限要求
+
+- **写操作 (创建)): `course:courseware:write`
+- **读操作** (查询): `course:courseware:readonly`
+
+## 错误处理
+
+常见错误及解决方案：
+
+| 错误码 | 错误信息 | 解决方案 |
+|--------|----------|----------|
+| 1001 | 参数错误 | 检查必填参数是否完整 |
+| 2001 | 课程不存在 | 确认 course_id 正确 |
+| 2002 | 素材不存在 | 确认 media_id 正确，素材已上传 |
+| 2003 | 课件类型不匹配 | 确保课件类型与素材类型一致 |
+| 3001 | 课件不存在 | 确认 lesson_id 正确 |
+| 3002 | 课件数量超限 | 课程课件数量达到上限 |
+
+## 相关文档
+
+- [课程管理 Skill](../soke-course/SKILL.md) - 课程创建和发布
+- [素材库管理 Skill](../soke-material/SKILL.md) - 素材上传和管理
+- [共享配置 Skill](../soke-shared/SKILL.md) - 认证和配置管理
+- [API 接口文档](../../docs/API_PROXY_INTERFACES.md) - 完整的 API 接口说明

package/skills/soke-material/README.md

@@ -0,0 +1,49 @@
+# 授客素材库管理 Skill
+
+素材库文件管理，包括文件上传到OSS、创建素材记录、查询素材列表和详情、管理素材分类。
+
+## 快速开始
+
+### 上传文件到素材库
+
+```bash
+# 自动检测类型和时长
+soke-cli file +upload --file ./video.mp4
+
+# 指定类型和时长
+soke-cli file +upload --file ./audio.mp3 --type audio --length 236
+```
+
+### 查询素材
+
+```bash
+# 列出所有素材
+soke-cli file +list-files
+
+# 列出视频素材
+soke-cli file +list-files --type video
+
+# 获取素材详情
+soke-cli file +get-info --file-id "FILE-UUID"
+```
+
+## 主要功能
+
+- ✅ 文件上传到 OSS（自动获取签名）
+- ✅ 创建素材库记录
+- ✅ 查询素材列表（支持类型和分类筛选）
+- ✅ 获取素材详情
+- ✅ 管理素材分类
+- ✅ 自动检测文件类型
+- ✅ 自动设置默认时长
+
+## 支持的文件类型
+
+- **视频**: mp4, avi, mov, wmv, flv, mkv, webm 等
+- **音频**: mp3, wav, flac, aac, ogg, wma, m4a 等
+- **图片**: jpg, jpeg, png, gif, bmp, svg, webp 等
+- **文档**: pdf, ppt, pptx, doc, docx, xls, xlsx 等
+
+## 详细文档
+
+查看 [SKILL.md](./SKILL.md) 获取完整的使用说明和 API 文档。