@sokeai/cli 1.0.41 → 1.0.53

package/skills/soke-course/README.md

@@ -1,131 +1,188 @@
-# soke-course Skill
+# 授客课程管理 Skill
 
-授客课程管理 Skill，用于查询课程列表、课程分类、课程详情、学习记录等。
+完整的课程生命周期管理，集成素材库和课件管理子 skills，提供模块化的课程内容管理。
 
 ## 功能概述
 
-这个 skill 提供了完整的课程管理查询功能，包括：
+这个 skill 提供了完整的课程管理功能，包括：
 
-- 📚 **课程查询**: 查询课程列表、课程详情
-- 🏷️ **分类管理**: 查询课程分类
-- 📝 **课件管理**: 查询课程下的课件列表
+- 📚 **课程管理**: 创建、更新、发布、查询课程
+- 🏷️ **分类管理**: 查询和管理课程分类
+- 📦 **素材管理**: 集成 soke-material skill，管理素材库
+- 📝 **课件管理**: 集成 soke-lesson skill，管理课程课件
 - 👥 **学习记录**: 查询用户的课程学习记录
 - 📊 **学习统计**: 查询课件学习记录和人脸识别记录
 
-## 快速开始
+## 集成的子 Skills
 
-### 前置条件
+### 📦 soke-material - 素材库管理
+负责文件上传和素材管理
+- [详细文档](../soke-material/SKILL.md)
 
-1. 安装 soke-cli
-```bash
-npm install -g @sokeai/cli
-```
-
-2. 配置认证
-```bash
-soke-cli config init
-soke-cli auth login
-```
+### 📚 soke-lesson - 课件管理
+负责课件的创建和管理
+- [详细文档](../soke-lesson/SKILL.md)
 
-### 基本使用
+## 快速开始
 
-#### 查询课程列表
+### 创建课程
 
 ```bash
-# 查询2024年的所有课程
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000
-
-# 查询已发布的课程
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000 \
-  --status 1
-
-# 查询自建课
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000 \
-  --is-in 1
-```
-
-#### 查询课程详情
+# 1. 查询课程分类，获取 category-id
+soke-cli course +list-categories
 
-```bash
-soke-cli course +get-course --uuid "course-uuid-here"
+# 2. 创建课程（使用上一步获取的 category-id）
+soke-cli course +create --title "Go语言入门" --category-id "CATEGORY-UUID"
+
+# 3. 上传素材
+soke-cli file +upload --file ./lesson1.mp4
+
+# 4. 创建课件
+soke-cli course +lesson-create \
+  --course-id "COURSE-UUID" \
+  --title "第一课" \
+  --media-id "MATERIAL-UUID" \
+  --type "video" \
+  --length 600 \
+  --object "path/to/file.mp4" \
+  --filename "lesson1.mp4" \
+  --ext "mp4" \
+  --filesize 10485760
+
+# 5. 发布课程
+soke-cli course +publish --course-id "COURSE-UUID"
 ```
 
-#### 查询课程分类
+### 查询课程
 
 ```bash
-soke-cli course +list-categories
-```
+# 查询课程列表
+soke-cli course +list-courses
 
-#### 查询课程学习记录
+# 查询课程详情
+soke-cli course +get-course --course-id "COURSE-UUID"
 
-```bash
-# 查询某个课程的所有学习记录
-soke-cli course +list-course-users --course-id "course-uuid-here"
+# 查询课程分类
+soke-cli course +list-categories
 
-# 查询特定用户的学习记录
-soke-cli course +get-course-user \
-  --course-id "course-uuid-here" \
-  --dept-user-id "user-uuid-here"
+# 查询课程学习记录
+soke-cli course +list-course-users --course-id "COURSE-UUID"
 ```
 
 ## 主要命令
 
+### 课程管理
 | 命令 | 说明 |
 |------|------|
-| `+list-courses` | 查询课程列表 |
+| `+list-categories` | 查询课程分类（获取 category-id） |
+| `+create` | 创建课程基本信息 |
+| `+update` | 更新课程信息 |
+| `+publish` | 发布课程 |
 | `+get-course` | 查询课程详情 |
-| `+list-categories` | 查询课程分类 |
-| `+list-lessons` | 查询课程课件列表 |
+| `+list-courses` | 查询课程列表 |
+
+### 课件管理（soke-lesson）
+| 命令 | 说明 |
+|------|------|
+| `+lesson-create` | 创建课件 |
+| `+lesson-get` | 查询课件详情 |
+| `+lesson-list` | 查询课件列表 |
+
+### 素材管理（soke-material）
+| 命令 | 说明 |
+|------|------|
+| `file +upload` | 上传文件到素材库 |
+| `file +list-files` | 查询素材列表 |
+| `file +get-info` | 查询素材详情 |
+
+### 学习记录
+| 命令 | 说明 |
+|------|------|
 | `+list-course-users` | 查询课程学习记录 |
-| `+get-course-user` | 查询用户课程学习详情 |
+| `+get-course-user` | 查询用户学习详情 |
 | `+list-lesson-learns` | 查询课件学习记录 |
-| `+list-lesson-faces` | 查询课件人脸识别记录 |
+| `+list-lesson-faces` | 查询人脸识别记录 |
 
 ## 使用场景
 
-### 场景1: 统计课程完成情况
+### 场景1: 创建课程
 
-```bash
-# 1. 获取课程列表
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000
+适用于需要精细控制每个步骤的场景：
 
-# 2. 查询某个课程的学习记录
-soke-cli course +list-course-users --course-id "course-uuid"
+```bash
+# 1. 查询课程分类，获取 category-id
+soke-cli course +list-categories
 
-# 3. 分析返回数据中的 finish_status 和 study_progress 字段
+# 2. 创建课程（使用上一步获取的 category-id）
+course_id=$(soke-cli course +create \
+  --title "Python数据分析实战" \
+  --category-id "CATEGORY-UUID" \
+  --format json | jq -r '.data.uuid')
+
+# 3. 批量上传素材
+for file in ./lessons/*.mp4; do
+  media_id=$(soke-cli file +upload --file "$file" --format json | jq -r '.data.uuid')
+  
+  # 4. 创建课件
+  soke-cli course +lesson-create \
+    --course-id "$course_id" \
+    --title "$(basename "$file" .mp4)" \
+    --media-id "$media_id" \
+    --type "video" \
+    --length 600 \
+    --object "path/to/$(basename "$file")" \
+    --filename "$(basename "$file")" \
+    --ext "mp4" \
+    --filesize $(stat -f%z "$file")
+done
+
+# 5. 发布课程
+soke-cli course +publish --course-id "$course_id"
 ```
 
-### 场景2: 查询用户学习情况
+### 场景2: 管理现有课程
 
 ```bash
-# 1. 查询用户ID（如果只知道用户名）
-soke-cli contact +search-user --name "张三"
-
-# 2. 查询该用户的课程学习记录
-soke-cli course +get-course-user \
-  --course-id "course-uuid" \
-  --dept-user-id "user-uuid"
+# 查询课程列表
+soke-cli course +list-courses --status 1
+
+# 获取课程详情
+soke-cli course +get-course --course-id "COURSE-UUID"
+
+# 查询课程的课件
+soke-cli course +lesson-list --course-id "COURSE-UUID"
+
+# 更新课程信息
+soke-cli course +update \
+  --course-id "COURSE-UUID" \
+  --title "新标题" \
+  --description "新描述"
+
+# 添加新课件
+media_id=$(soke-cli file +upload --file ./new-lesson.mp4 --format json | jq -r '.data.uuid')
+soke-cli course +lesson-create \
+  --course-id "COURSE-UUID" \
+  --title "新增课件" \
+  --media-id "$media_id" \
+  --type "video" \
+  --length 600 \
+  --object "path/to/new-lesson.mp4" \
+  --filename "new-lesson.mp4" \
+  --ext "mp4" \
+  --filesize 10485760
 ```
 
-### 场景3: 课程内容分析
+### 场景3: 统计课程完成情况
 
 ```bash
-# 1. 获取课程详情
-soke-cli course +get-course --uuid "course-uuid"
+# 1. 获取课程列表
+soke-cli course +list-courses
 
-# 2. 获取课程的课件列表
-soke-cli course +list-lessons --course-id "course-uuid"
+# 2. 查询某个课程的学习记录
+soke-cli course +list-course-users --course-id "COURSE-UUID"
 
-# 3. 查询每个课件的学习记录
-soke-cli course +list-lesson-learns --lesson-id "lesson-uuid"
+# 3. 查询课件学习记录
+soke-cli course +list-lesson-learns --lesson-id "LESSON-UUID"
 ```
 
 ## 参数说明
@@ -157,10 +214,12 @@ const endTime = new Date('2024-12-31').getTime();   // 1735660799000
 
 ## 注意事项
 
-1. **时间范围限制**: `+list-courses` 的时间范围不能超过365天
-2. **分页查询**: 默认每页100条，最大100条
-3. **权限要求**: 需要相应的只读权限（`course:*:readonly`）
-4. **认证要求**: 所有命令都需要先完成 `soke-cli auth login`
+1. **课程发布要求**: 课程至少需要一个课件才能发布
+2. **分类必填**: 创建课程时必须指定分类ID
+3. **素材先行**: 创建课件前必须先上传素材到素材库
+4. **类型匹配**: 课件类型必须与素材类型匹配
+5. **权限要求**: 需要相应的读写权限（`course:*:write` 或 `course:*:readonly`）
+6. **认证要求**: 所有命令都需要先完成 `soke-cli auth login`
 
 ## 错误处理
 
@@ -188,16 +247,33 @@ soke-cli auth login
 
 ## 相关文档
 
-- [SKILL.md](./SKILL.md) - 完整的 Skill 文档
-- [course-list-courses.md](./references/course-list-courses.md) - 课程列表查询详细参考
-- [授客开放平台API文档](../../cli-doc/授客开放平台API接口文档.md) - API 接口文档
+- [SKILL.md](./SKILL.md) - 完整的 Skill 文档和 API 参考
+- [素材库管理 Skill](../soke-material/SKILL.md) - 文件上传和素材管理
+- [课件管理 Skill](../soke-lesson/SKILL.md) - 课件创建和管理
+- [共享配置 Skill](../soke-shared/SKILL.md) - 认证和配置管理
+- [API 接口文档](../../docs/API_PROXY_INTERFACES.md) - 完整的 API 接口说明
 
-## 技术支持
+## Skill 架构
 
-如有问题，请参考：
-- 授客开放平台: https://opendev.soke.cn
-- soke-cli 文档: [../../cli-doc/soke-cli.md](../../cli-doc/soke-cli.md)
+```
+soke-course (主 skill)
+├── 课程管理 (本 skill)
+│   ├── +create (创建课程)
+│   ├── +update (更新课程)
+│   ├── +publish (发布课程)
+│   └── 查询命令...
+├── soke-lesson (子 skill - 课件管理)
+│   ├── +lesson-create
+│   ├── +lesson-get
+│   └── +lesson-list
+└── soke-material (子 skill - 素材管理)
+    ├── file +upload
+    ├── file +create
+    └── 查询命令...
+```
 
 ## 版本历史
 
+- v3.0.0 (2024-05-26): 重构为模块化架构，集成 soke-material 和 soke-lesson 子 skills
+- v2.0.0 (2024-05-25): 添加课程创建和更新功能
 - v1.0.0 (2024-05-14): 初始版本，支持课程查询、分类、学习记录等功能