@sokeai/cli 1.0.63 → 1.0.65

package/skills/soke-lesson/SKILL.md

@@ -1,513 +1,119 @@
 ---
 name: soke-lesson
-summary: 授客课件管理（创建课件、查询课件），支持视频/音频/文档等多种类型
 version: 1.0.0
-description: "授客课件管理：课件生命周期管理，包括基于素材创建课件、查询课件列表和详情、管理课件排序。支持视频、音频、文档等多种课件类型。当用户需要添加课件、管理课件、查询课件信息时使用。"
-metadata:
-  requires:
-    bins: ["soke-cli"]
-  cliHelp: "soke-cli course --help"
+description: 课件管理 — 创建/查询/排序课程章节课件，所有参数来自素材上传返回结果
+tags: [soke, lesson, courseware, chapter, video, audio, document]
 ---
 
-# 课件管理 (lesson)
+# 课件管理
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+## 触发描述
 
-## ⚠️ 使用前提
+用户已有课程（course）且完成素材上传后，需要将素材添加为课程的章节课件时触发本技能。支持创建课件、列表查询、详情查询和排序，仅支持 `video | audio | document` 三种类型的课件。
 
-本 skill 基于 **soke-cli** 命令行工具，使用前必须完成以下步骤：
+## 输入要求
 
-1. **安装 soke-cli**：确保已安装 `@sokeai/cli` NPM 包或 soke-cli 二进制文件
-2. **用户登录授权**：运行 `soke-cli auth login` 完成 OAuth 设备码授权流程，获取用户访问令牌
+所有课件创建参数**必须来自 `soke-material` 上传返回的结果对象**，不允许手动构造。传入参数：
 
-**快速开始**：
-```bash
-
-# 1. 用户登录授权（必须）
-soke-cli auth login
-
-# 2. 验证登录状态
-soke-cli config show
+```json
+{
+  "uuid": "素材上传返回的 uuid",
+  "filename": "素材上传返回的 filename",
+  "type": "素材上传返回的 type（仅 video/audio/document）",
+  "ext": "素材上传返回的 ext",
+  "filesize": "素材上传返回的 filesize",
+  "object": "素材上传返回的 object",
+  "duration": "默认时长或自定义时长（秒）",
+  "courseId": "目标课程 ID",
+  "title": "课件标题（用户提供或从 filename 推断）"
+}
 ```
 
-未完成登录授权将无法调用任何课件管理相关的 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` 发布课程
-
-## 可用命令
-
-### 课件创建
+> ⚠️ `uuid` `filename` `type` `ext` `filesize` `object` 六个字段必须严格从素材上传返回结果中取值，不可自行构造或编造。
 
-#### `course +lesson-create` - 创建课件
+## 执行流程
 
-基于素材库文件创建课件并关联到课程。
+### 1. 创建课件 `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` - 列出课程的课件列表
-
-查询指定课程下的所有课件。
+soke course +lesson-create \
+  --course-id <courseId> \
+  --title "<课件标题>" \
+  --type <video|audio|document> \
+  --uuid <素材uuid> \
+  --filename "<文件名>" \
+  --ext <扩展名> \
+  --filesize <字节数> \
+  --object "<存储对象>" \
+  --duration <时长秒数>
+```
+
+**参数对照（全部来自素材上传返回）：**
+
+| 参数 | 来源 | 说明 |
+|------|------|------|
+| `--course-id` | 当前课程上下文 | 目标课程 ID |
+| `--title` | 用户指定或 filename 推断 | 课件展示名称 |
+| `--type` | 返回 `.type` | video / audio / document |
+| `--uuid` | 返回 `.uuid` | 素材唯一标识 |
+| `--filename` | 返回 `.filename` | 原始文件名 |
+| `--ext` | 返回 `.ext` | 文件扩展名 |
+| `--filesize` | 返回 `.filesize` | 文件字节数 |
+| `--object` | 返回 `.object` | 存储对象键 |
+| `--duration` | 默认规则或用户指定 | 学习时长（秒） |
+
+### 2. 课件列表 `course +lesson-list`
 
-**参数：**
-- `--course-id` (必填): 课程 UUID
-
-**示例：**
 ```bash
-soke-cli course +lesson-list --course-id "COURSE-UUID"
+soke course +lesson-list --course-id <courseId>
 ```
 
-**返回：**
-- 课件列表（包含 UUID、标题、类型、时长、排序等信息）
-
-#### `course +lesson-get` - 获取课件详情
+返回指定课程下所有课件的列表，包含课件 ID、标题、类型、排序序号。
 
-获取单个课件的详细信息。
+### 3. 课件详情 `course +lesson-get`
 
-**参数：**
-- `--lesson-id` (必填): 课件 UUID
-
-**示例：**
 ```bash
-soke-cli course +lesson-get --lesson-id "LESSON-UUID"
+soke course +lesson-get --lesson-id <lessonId>
 ```
 
-**返回：**
-- 课件详细信息（包含素材信息、转换状态等）
-
-### 课件排序
+返回单个课件的完整信息（标题、类型、素材引用、时长、转码状态等）。
 
-#### `course +lesson-sort` - 调整课程课件顺序
+### 4. 课件排序 `course +lesson-sort`
 
-按指定顺序重新排列课程下的课件。
-
-**参数：**
-- `--course-id` (必填): 课程 UUID
-- `--sort-list` (必填): 课件 ID 有序列表，多个 ID 用逗号分隔，顺序即为最终显示顺序
-
-**示例：**
 ```bash
-# 将两个课件按指定顺序排列
-soke-cli course +lesson-sort \
-  --course-id "F23F32C5-8586-45E5-B98D-5D005FD596B1" \
-  --sort-list "29F629AB-3FF6-4EC0-A7C5-CC6D7124518E,058B89B2-95CA-45EF-9F52-231E58AF2E91"
-```
-
-**返回：**
-- 调整成功提示及课件数量
-
-**说明：**
-- `--sort-list` 中课件 ID 的顺序即为调整后的最终排列顺序
-- 先使用 `course +lesson-list` 查出所有课件 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
-```
-
-**获取课件详情**：
-```
-soke-cli course +lesson-get --lesson-id "{lesson_id}" --format json
+soke course +lesson-sort --course-id <courseId> --order "<lessonId1>,<lessonId2>,<lessonId3>"
 ```
 
-**调整课件顺序**：
-```
-# 先查询出所有课件 UUID
-soke-cli course +lesson-list --course-id "{course_id}" --format json
+调整课程内课件的展示顺序，`--order` 为逗号分隔的课件 ID 列表，按先后顺序排列。
 
-# 按期望顺序传入 UUID 列表（逗号分隔，第一个排在最前）
-soke-cli course +lesson-sort \
-  --course-id "{course_id}" \
-  --sort-list "{lesson_id_1},{lesson_id_2},{lesson_id_3}"
-```
+## 输出标准
 
-## 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-sort` | `/skills/course/lesson/sort/{course_id}` | PUT | 调整课件顺序 |
-| `course +lesson-update` | `/skills/course/lesson/{id}` | PUT | 更新课件信息 |
-## 课件与素材的关系
+创建课件成功后输出摘要：
 
 ```
-素材库 (Material)
-    ↓ (通过 media_id 关联)
-课件 (Lesson)
-    ↓ (通过 course_id 关联)
-课程 (Course)
+✅ 课件创建成功
+- 课程: {courseTitle} (ID: {courseId})
+- 课件: {title}
+- 类型: {type}
+- 时长: {duration}s
+- 课件 ID: {lessonId}
 ```
 
-**重要说明：**
-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. **排序规则**: 课件按创建时间自动排序，可通过 `course +lesson-sort` 手动调整顺序
-5. **排序需覆盖全部课件**: 调用 `+lesson-sort` 时建议传入课程下所有课件的 UUID，避免遗漏
-6. **发布要求**: 课程至少需要一个课件才能发布
-
-## 权限要求
-
-- **写操作 (创建)): `course:courseware:write`
-- **读操作** (查询): `course:courseware:readonly`
-
-## 错误处理
-
-常见错误及解决方案：
-
-| 错误码 | 错误信息 | 解决方案 |
-|--------|----------|----------|
-| 1001 | 参数错误 | 检查必填参数是否完整 |
-| 2001 | 课程不存在 | 确认 course_id 正确 |
-| 2002 | 素材不存在 | 确认 media_id 正确，素材已上传 |
-| 2003 | 课件类型不匹配 | 确保课件类型与素材类型一致 |
-| 3001 | 课件不存在 | 确认 lesson_id 正确 |
-| 3002 | 课件数量超限 | 课程课件数量达到上限 |
+1. **仅支持三种类型**：`video` `audio` `document`，图片等其他类型不支持作为课件
+2. 所有素材引用参数必须来自 `soke-material` 上传返回，严禁手动编造 uuid / object 等字段
+3. 课件创建后自动关联到指定课程，无需额外绑定步骤
+4. 排序使用课件 ID 列表，未在列表中的课件保持在末尾，不丢失
+5. 课件删除、批量导入等操作不在 CLI 范围，如有需求引导至后台操作
 
-## 相关文档
+## 检查清单
 
-- [课程管理 Skill](../soke-course/SKILL.md) - 课程创建和发布
-- [素材库管理 Skill](../soke-material/SKILL.md) - 素材上传和管理
-- [共享配置 Skill](../soke-shared/SKILL.md) - 认证和配置管理
-- [API 接口文档](../../docs/API_PROXY_INTERFACES.md) - 完整的 API 接口说明
+- [ ] 素材已完成上传，持有完整返回对象
+- [ ] courseId 已确认存在
+- [ ] type 仅限 video / audio / document
+- [ ] uuid / filename / type / ext / filesize / object 六个字段均来自上传返回
+- [ ] duration 已按类型默认规则或用户指定设定
+- [ ] 课件创建完成后能通过 lesson-list 验证