@sokeai/cli 1.0.39 → 1.0.53

package/skills/soke-course/SKILL.md

@@ -1,595 +1,507 @@
 ---
 name: soke-course
-summary: 授客课程管理（课程列表/分类/课程详情/学习记录），通过 soke-cli 查询
-version: 1.0.0
-description: "授客课程管理：查询课程、课程分类、课程详情、学习记录。查询课程列表、课程分类、课程用户学习记录、课件列表、人脸识别记录。当用户需要查询课程信息、查看课程列表、查询学习记录、查看课程分类时使用。"
-requiredAuthorizations: [{"platformId":"soke-ai"}]
+summary: 授客学堂课程管理（课程创建/更新/发布/查询），集成素材库和课件管理子 skills，完整管理课程生命周期
+version: 4.0.0
+description: "授客学堂课程管理：完整的课程生命周期管理，包括创建课程分类、上传文件（素材）、创建课件、创建课程、指派部门/学员、查询学员学习状态的全链路流程。集成 soke-material（素材库管理）、soke-lesson（课件管理）、soke-assign（指派管理）子 skills。当用户需要创建课程、上传课件、指派学员、查询学习进度时使用。"
 metadata:
   requires:
     bins: ["soke-cli"]
+    skills: ["soke-material", "soke-lesson", "soke-assign"]
   cliHelp: "soke-cli course --help"
 ---
 
-# 课程管理 (course)
+# 课程管理 (soke-course)
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
 
-## 核心概念
+## 使用前提
 
-- **Course（课程）**: 课程实体，包含标题、分类、讲师、学时等信息，通过 `uuid` 标识
-- **CourseUser（课程用户）**: 用户的课程学习记录，包含学习进度、完成状态、学习时长等，通过 `target_id` 标识
-- **Category（课程分类）**: 课程分类，支持层级结构，通过 `uuid` 标识
-- **Lesson（课件）**: 课程下的课件，包含视频、音频、文章、文档等类型
-- **LessonLearn（课件学习记录）**: 用户的课件学习记录
-- **LessonFace（人脸识别记录）**: 课件学习过程中的人脸识别记录
+1. 已安装 `soke-cli`
+2. 已登录授权: `soke-cli auth login`
 
-## 资源关系
-
-```
-Course (课程)
-├── Category (课程分类)
-├── Lesson (课件)
-│   ├── LessonLearn (课件学习记录)
-│   └── LessonFace (人脸识别记录)
-└── CourseUser (课程用户学习记录)
-    ├── dept_user_id (用户ID)
-    ├── study_progress (学习进度)
-    ├── finish_status (完成状态)
-    └── study_duration (学习时长)
+```bash
+soke-cli auth login
+soke-cli config show  # 验证登录状态
 ```
 
-## Shortcuts（推荐优先使用）
+## 端到端工作流
 
-Shortcut 是对常用操作的高级封装（`soke-cli course +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+完整创建一门可学习的课程需要以下步骤：
 
-| Shortcut | 说明 |
-|----------|------|
-| [`+list-courses`](#list-courses) | 列出课程列表，支持时间范围、分类和状态筛选 |
-| [`+get-course`](#get-course) | 获取单个课程的详细信息 |
-| [`+list-categories`](#list-categories) | 列出课程分类 |
-| [`+list-lessons`](#list-lessons) | 列出课程下的课件列表 |
-| [`+list-course-users`](#list-course-users) | 列出课程用户学习记录列表 |
-| [`+get-course-user`](#get-course-user) | 获取单个用户的课程学习详情 |
-| [`+list-lesson-learns`](#list-lesson-learns) | 列出课件学习记录 |
-| [`+list-lesson-faces`](#list-lesson-faces) | 列出课件人脸识别记录 |
-| [`+batch-create-from-excel`](#batch-create-from-excel) | 通过 Excel 批量创建课程并上传课件(原 createcourse 工具能力,已合入) |
-
-## 命令详解
-
-### +list-courses
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ 1. 查询课程分类  →  获取 category-id                             │
+│ 2. 创建课程      →  获取 course-id                               │
+│ 3. 上传素材      →  获取 media-id + 所有文件信息                  │
+│ 4. 创建课件      →  关联素材到课程 (至少 1 个)                    │
+│ 5. (可选)更新课程 → 补充描述等                                    │
+│ 6. 发布课程      →  学员可见                                       │
+│ 7. (可选)指派    →  分配给部门/学员 → 学员开始学习                  │
+│ 8. 查询学习状态  →  查看学员进度/完成率                            │
+└──────────────────────────────────────────────────────────────────┘
+```
 
-列出课程列表，支持按时间范围、分类和状态筛选。
+### 数据流转图
 
-**命令格式**:
-```bash
-soke-cli course +list-courses \
-  --start-time <timestamp> \
-  --end-time <timestamp> \
-  [--category-id <category_id>] \
-  [--is-in <0|1>] \
-  [--status <0|1|2>] \
-  [--page <page>] \
-  [--page-size <size>]
 ```
-
-**参数说明**:
-- `--start-time`: 课程创建开始时间（Unix时间戳，毫秒）**必需**
-- `--end-time`: 课程创建结束时间（Unix时间戳，毫秒）**必需**（起始与结束时间差不超365天）
-- `--category-id`: 课程分类ID（可选）
-- `--is-in`: 课程来源（可选）
-  - `0`: 采购课
-  - `1`: 自建课
-- `--status`: 课程状态（可选）
-  - `0`: 未发布
-  - `1`: 已发布
-  - `2`: 已关闭
-- `--page`: 页码，从1开始（默认: 1）
-- `--page-size`: 每页数量，最大100（默认: 100）
-
-**返回字段**:
-- `uuid`: 课程ID
-- `title`: 课程标题
-- `category_id`: 课程分类ID
-- `certificate_id`: 关联证书ID
-- `lector_id`: 关联讲师ID
-- `study_type`: 学习模式（1=自由式, 2=解锁式）
-- `credit`: 学分数量
-- `point`: 积分数量
-- `status`: 课程发布状态（-1=删除, 0=未发布, 1=已发布, 2=关闭）
-- `lesson_num`: 课件数量
-- `total_length`: 学时长度（单位：秒）
-- `description`: 课程描述
-- `pc_url`: PC端跳转链接
-- `mobile_url`: 移动端跳转链接
-- `create_time`: 创建时间
-- `update_time`: 更新时间
-- `create_dept_user_id`: 创建人ID
-- `create_dept_user_name`: 创建人姓名
-
-**示例**:
-```bash
-# 查询2024年的所有课程
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000
-
-# 查询已发布的自建课
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000 \
-  --is-in 1 \
-  --status 1
-
-# 查询特定分类的课程
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000 \
-  --category-id "category123"
+分类查询                    素材上传 (file +upload)
+  │                           │
+  ▼                           ▼
+category-id              media-id, filename, filesize, object, ext, type
+  │                           │
+  ▼                           ▼
+创建课程 ──→ course-id ──→ 创建课件 (course +lesson-create) ──→ lesson-id
+                                │
+                                ▼
+                          发布课程 ◄── 课件数量 ≥ 1
+                                │
+                                ▼
+                          指派给学员 ◄── assign +create (可选)
+                                │
+                                ▼
+                          学员可开始学习
+                                │
+                                ▼
+                          查询学习记录/进度
 ```
 
-**权限要求**: `course:course:readonly`
-
 ---
 
-### +get-course
+## 步骤1: 查询课程分类
 
-获取单个课程的详细信息。
+创建课程前必须先获取分类 ID。
 
-**命令格式**:
 ```bash
-soke-cli course +get-course --uuid <course_id>
-```
-
-**参数说明**:
-- `--uuid`: 课程ID **必需**
-
-**返回字段**:
-与 `+list-courses` 返回字段相同，但返回单个课程的完整详情。
+soke-cli course +list-categories --page 1 --page-size 100
 
-**示例**:
-```bash
-# 查询指定课程详情
-soke-cli course +get-course --uuid "course123"
+# JSON 输出供解析:
+soke-cli course +list-categories --format json
 ```
 
-**权限要求**: `course:course:readonly`
+**响应关键字段**:
+- `data.list[].uuid` → 分类 ID（创建课程时传入 `--category-id`）
+- `data.list[].title` → 分类名称
+- `data.list[].parent_id` → 父分类 ID
 
 ---
 
-### +list-categories
-
-列出课程分类，支持分页。
-
-**命令格式**:
-```bash
-soke-cli course +list-categories \
-  [--page <page>] \
-  [--page-size <size>]
-```
-
-**参数说明**:
-- `--page`: 页码，从1开始（默认: 1）
-- `--page-size`: 每页数量，最大100（默认: 100）
-
-**返回字段**:
-- `uuid`: 分类ID
-- `title`: 分类标题
-- `parent_id`: 分类父ID
-- `create_time`: 创建时间
+## 步骤2: 创建课程
 
-**示例**:
 ```bash
-# 查询所有课程分类
-soke-cli course +list-categories
+soke-cli course +create \
+  --title "课程标题" \
+  --category-id "CATEGORY-UUID" \
+  --description "课程描述（可选）"
 
-# 分页查询
-soke-cli course +list-categories --page 1 --page-size 50
+# JSON 输出:
+soke-cli course +create --title "标题" --category-id "CATEGORY-UUID" --format json
 ```
 
-**权限要求**: `course:category:readonly`
+**参数**:
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--title` | 是 | 课程标题 |
+| `--category-id` | 是 | 分类 ID（从步骤1获取） |
+| `--description` | 否 | 课程描述 |
+
+**响应提取**: `data.uuid` → 课程 ID (`course-id`)
 
 ---
 
-### +list-lessons
+## 步骤3: 上传素材文件
 
-列出课程下的课件列表。
+> 详见 [`../soke-material/SKILL.md`](../soke-material/SKILL.md)
 
-**命令格式**:
 ```bash
-soke-cli course +list-lessons \
-  --course-id <course_id> \
-  [--page <page>] \
-  [--page-size <size>]
-```
+# 自动检测文件类型和时长
+soke-cli file +upload --file "./video.mp4"
 
-**参数说明**:
-- `--course-id`: 课程ID **必需**
-- `--page`: 页码，从1开始（默认: 1）
-- `--page-size`: 每页数量，最大100（默认: 100）
-
-**返回字段**:
-- `uuid`: 课件ID
-- `title`: 课件标题
-- `type`: 课件类型（video=视频, audio=音频, article=文章, document=文档）
-- `media_id`: 关联素材库ID
-- `duration`: 课件时长（单位：秒）
-- `sort`: 排序号
-- `status`: 状态（-1=删除, 0=未发布, 1=发布）
-- `create_time`: 创建时间
-
-**示例**:
-```bash
-# 查询课程的所有课件
-soke-cli course +list-lessons --course-id "course123"
+# 指定类型和时长
+soke-cli file +upload --file "./audio.mp3" --type audio --length 236
+
+# JSON 输出
+soke-cli file +upload --file "./video.mp4" --format json
 ```
 
-**权限要求**: `course:lesson:readonly`
+**响应关键字段（全部用于步骤4创建课件）**:
+| 字段 | 用途 | 说明 |
+|------|------|------|
+| `data.uuid` | `--media-id` | 素材 UUID |
+| `data.filename` | `--filename` | 文件名 |
+| `data.filesize` | `--filesize` | 文件大小（字节） |
+| `data.object` | `--object` | OSS 对象路径 |
+| `data.ext` | `--ext` | 文件扩展名 |
+| `data.type` | `--type` | 文件类型 |
+
+**时长默认值**: video→600s, audio→300s, 其他→0s
 
 ---
 
-### +list-course-users
+## 步骤4: 创建课件
 
-列出课程用户学习记录列表，支持按用户ID和完成时间筛选。
+> 详见 [`../soke-lesson/SKILL.md`](../soke-lesson/SKILL.md)
 
-**命令格式**:
 ```bash
-soke-cli course +list-course-users \
-  --course-id <course_id> \
-  [--userid-list <user_ids>] \
-  [--finish-start-time <timestamp>] \
-  [--finish-end-time <timestamp>] \
-  [--page <page>] \
-  [--page-size <size>]
+soke-cli course +lesson-create \
+  --course-id "COURSE-UUID" \
+  --title "第一课" \
+  --media-id "MATERIAL-UUID" \
+  --type "video" \
+  --length 600 \
+  --object "uploads/20260601/video.mp4" \
+  --filename "video.mp4" \
+  --ext "mp4" \
+  --filesize 10485760 \
+  --sort 0
 ```
 
-**参数说明**:
-- `--course-id`: 课程ID **必需**
-- `--userid-list`: 用户ID列表，逗号分隔，最多100个（可选）
-- `--finish-start-time`: 完成开始时间（Unix时间戳，毫秒）（可选）
-- `--finish-end-time`: 完成结束时间（Unix时间戳，毫秒）（可选）
-- `--page`: 页码，从1开始（默认: 1）
-- `--page-size`: 每页数量，最大100（默认: 100）
-
-**返回字段**:
-- `target_id`: 课程用户记录ID
-- `dept_user_id`: 部门用户ID
-- `dept_user_name`: 用户姓名
-- `study_progress`: 学习进度（百分比）
-- `finish_status`: 完成状态（0=未完成, 1=已完成）
-- `study_duration`: 学习时长（单位：秒）
-- `create_time`: 创建时间
-- `update_time`: 更新时间
-
-**示例**:
-```bash
-# 查询某个课程的所有用户学习记录
-soke-cli course +list-course-users --course-id "course123"
-
-# 查询特定用户的学习记录
-soke-cli course +list-course-users \
-  --course-id "course123" \
-  --userid-list "user1,user2,user3"
+**参数来源映射**:
+| 参数 | 必填 | 来源 |
+|------|------|------|
+| `--course-id` | 是 | 步骤2 `data.uuid` |
+| `--title` | 是 | 自定义标题 |
+| `--media-id` | 是 | 步骤3 `data.uuid` |
+| `--type` | 是 | 步骤3 `data.type` |
+| `--length` | 否 | 媒体时长（秒） |
+| `--object` | 否 | 步骤3 `data.object` |
+| `--filename` | 否 | 步骤3 `data.filename` |
+| `--ext` | 否 | 步骤3 `data.ext` |
+| `--filesize` | 否 | 步骤3 `data.filesize` |
+| `--sort` | 否 | 排序值（默认 0） |
 
-# 查询某个时间段内完成的学习记录
-soke-cli course +list-course-users \
-  --course-id "course123" \
-  --finish-start-time 1704038400000 \
-  --finish-end-time 1735660799000
-```
+**关键原则**: 课件参数全部从 `file +upload` 响应提取，无需手动填写。
 
-**权限要求**: `course:courseUser:readonly`
+### 批量上传文件
 
----
-
-### +get-course-user
-
-获取单个用户的课程学习详情。
-
-**命令格式**:
 ```bash
-soke-cli course +get-course-user \
-  --course-id <course_id> \
-  --dept-user-id <dept_user_id>
+FILES=("lesson1.mp4" "lesson2.mp4" "handout.pdf")
+
+for file in "${FILES[@]}"; do
+  RESULT=$(soke-cli file +upload --file "$file" --format json)
+  MEDIA_ID=$(echo "$RESULT" | jq -r '.data.uuid')
+  FILE_TYPE=$(echo "$RESULT" | jq -r '.data.type')
+  FILE_NAME=$(echo "$RESULT" | jq -r '.data.filename')
+  FILE_SIZE=$(echo "$RESULT" | jq -r '.data.filesize')
+  OBJECT=$(echo "$RESULT" | jq -r '.data.object')
+  EXT=$(echo "$RESULT" | jq -r '.data.ext')
+
+  LENGTH=0
+  [[ "$FILE_TYPE" == "video" ]] && LENGTH=600
+  [[ "$FILE_TYPE" == "audio" ]] && LENGTH=300
+
+  TITLE=$(basename "$file" | sed 's/\.[^.]*$//')
+
+  soke-cli course +lesson-create \
+    --course-id "$COURSE_ID" --title "$TITLE" \
+    --media-id "$MEDIA_ID" --type "$FILE_TYPE" --length "$LENGTH" \
+    --object "$OBJECT" --filename "$FILE_NAME" --ext "$EXT" --filesize "$FILE_SIZE"
+done
 ```
 
-**参数说明**:
-- `--course-id`: 课程ID **必需**
-- `--dept-user-id`: 部门用户ID **必需**
+---
 
-**返回字段**:
-与 `+list-course-users` 返回字段相同，但返回单个用户的完整学习详情。
+## 步骤5: 更新课程（可选）
 
-**示例**:
 ```bash
-# 查询张三的课程学习记录
-soke-cli course +get-course-user \
-  --course-id "course123" \
-  --dept-user-id "user456"
+soke-cli course +update \
+  --course-id "COURSE-UUID" \
+  --title "新标题" \
+  --description "课程描述"
 ```
 
-**权限要求**: `course:courseUser:readonly`
-
-**使用场景**:
-- 当用户询问"查询某人的课程学习情况"时使用
-- 需要同时提供课程ID和用户ID
-- 如果只知道用户名，需要先通过 `soke-cli contact +search-user` 查询用户ID
-
 ---
 
-### +list-lesson-learns
+## 步骤6: 发布课程
 
-列出课件学习记录，支持按用户ID和时间范围筛选。
+**前提**: 课程至少包含 1 个课件。
 
-**命令格式**:
 ```bash
-soke-cli course +list-lesson-learns \
-  --lesson-id <lesson_id> \
-  [--userid-list <user_ids>] \
-  [--start-time <timestamp>] \
-  [--end-time <timestamp>] \
-  [--page <page>] \
-  [--page-size <size>]
+soke-cli course +publish --course-id "COURSE-UUID"
 ```
 
-**参数说明**:
-- `--lesson-id`: 课件ID **必需**
-- `--userid-list`: 用户ID列表，逗号分隔，最多100个（可选）
-- `--start-time`: 学习开始时间（Unix时间戳，毫秒）（可选）
-- `--end-time`: 学习结束时间（Unix时间戳，毫秒）（可选）
-- `--page`: 页码，从1开始（默认: 1）
-- `--page-size`: 每页数量，最大100（默认: 100）
-
-**返回字段**:
-- `uuid`: 学习记录ID
-- `dept_user_id`: 部门用户ID
-- `dept_user_name`: 用户姓名
-- `study_duration`: 学习时长（单位：秒）
-- `finish_status`: 完成状态（0=未完成, 1=已完成）
-- `create_time`: 创建时间
-- `update_time`: 更新时间
-
-**示例**:
-```bash
-# 查询某个课件的所有学习记录
-soke-cli course +list-lesson-learns --lesson-id "lesson123"
-
-# 查询特定用户的课件学习记录
-soke-cli course +list-lesson-learns \
-  --lesson-id "lesson123" \
-  --userid-list "user1,user2"
-```
+---
 
-**权限要求**: `course:lessonLearn:readonly`
+## 步骤7: 指派课程（可选）
 
----
+> 详见 [`../soke-assign/SKILL.md`](../soke-assign/SKILL.md)
 
-### +list-lesson-faces
+发布后指派给部门或学员，学员才能看到并学习。
 
-列出课件人脸识别记录，支持按用户ID和时间范围筛选。
+### 7.1 查询可用部门/用户
 
-**命令格式**:
 ```bash
-soke-cli course +list-lesson-faces \
-  --lesson-id <lesson_id> \
-  [--userid-list <user_ids>] \
-  [--start-time <timestamp>] \
-  [--end-time <timestamp>] \
-  [--page <page>] \
-  [--page-size <size>]
+soke-cli assign +list-departments --keyword "关键词"
+soke-cli assign +list-users --dept-id "DEPT-ID" --keyword "关键词"
 ```
 
-**参数说明**:
-- `--lesson-id`: 课件ID **必需**
-- `--userid-list`: 用户ID列表，逗号分隔，最多100个（可选）
-- `--start-time`: 识别开始时间（Unix时间戳，毫秒）（可选）
-- `--end-time`: 识别结束时间（Unix时间戳，毫秒）（可选）
-- `--page`: 页码，从1开始（默认: 1）
-- `--page-size`: 每页数量，最大100（默认: 100）
-
-**返回字段**:
-- `uuid`: 识别记录ID
-- `dept_user_id`: 部门用户ID
-- `dept_user_name`: 用户姓名
-- `face_status`: 识别状态（0=未识别, 1=识别成功, 2=识别失败）
-- `face_time`: 识别时间
-- `create_time`: 创建时间
-
-**示例**:
-```bash
-# 查询某个课件的所有人脸识别记录
-soke-cli course +list-lesson-faces --lesson-id "lesson123"
+### 7.2 创建指派
 
-# 查询特定用户的人脸识别记录
-soke-cli course +list-lesson-faces \
-  --lesson-id "lesson123" \
-  --userid-list "user1,user2"
+```bash
+# 指派给部门
+soke-cli assign +create \
+  --module "course" \
+  --target-id "COURSE-UUID" \
+  --dept-ids "DEPT-ID" \
+  --dept-names "部门名称" \
+  --learn-type "required"
+
+# 指派给用户
+soke-cli assign +create \
+  --module "course" \
+  --target-id "COURSE-UUID" \
+  --user-ids "USER-ID" \
+  --user-names "学员姓名" \
+  --learn-type "required"
+
+# 同时指派给多个部门和用户
+soke-cli assign +create \
+  --module "course" --target-id "COURSE-UUID" \
+  --dept-ids "DEPT1,DEPT2" --dept-names "部门1,部门2" \
+  --user-ids "USER1,USER2" --user-names "学员1,学员2" \
+  --learn-type "required"
 ```
 
-**权限要求**: `course:lessonFace:readonly`
+**指派参数**:
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--module` | 是 | 固定 `course` |
+| `--target-id` | 是 | 课程 ID |
+| `--learn-type` | 是 | `required`(必修) / `optional`(选修) |
+| `--dept-ids` | 否 | 部门 ID，逗号分隔 |
+| `--dept-names` | 否 | 部门名（与 ids 一一对应） |
+| `--user-ids` | 否 | 用户 ID，逗号分隔 |
+| `--user-names` | 否 | 用户名（与 ids 一一对应） |
 
 ---
 
-## 常见工作流
-
-### 工作流1: 查询用户的课程学习情况
+## 步骤8: 查询学习状态
 
-当用户询问"查询张三的课程学习情况"时：
+### 课程学习记录
 
-**步骤1**: 如果只知道用户名，先查询用户ID
 ```bash
-soke-cli contact +search-user --name "张三"
-```
+soke-cli course +list-course-users --course-id "COURSE-UUID"
 
-**步骤2**: 获取课程列表，找到目标课程ID
-```bash
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000
+# 按用户筛选
+soke-cli course +list-course-users \
+  --course-id "COURSE-UUID" --userid-list "USER1,USER2"
+
+# 按完成时间筛选
+soke-cli course +list-course-users \
+  --course-id "COURSE-UUID" \
+  --finish-start-time 1700000000000 --finish-end-time 1700100000000
 ```
 
-**步骤3**: 查询该用户的课程学习记录
+### 学员学习详情
+
 ```bash
 soke-cli course +get-course-user \
-  --course-id <course_id> \
-  --dept-user-id <dept_user_id>
+  --course-id "COURSE-UUID" --dept-user-id "DEPT-USER-ID"
 ```
 
-### 工作流2: 统计课程学习完成情况
+返回: `lesson_finish_num`(已完成)、`lesson_num`(总数)、`progress`(进度%)、`learn_status`
 
-当用户询问"统计某个课程的学习完成情况"时：
+### 课件学习记录
 
-**步骤1**: 获取课程用户学习记录列表
 ```bash
-soke-cli course +list-course-users --course-id <course_id>
+soke-cli course +list-lesson-learns \
+  --course-id "COURSE-UUID" --lesson-id "LESSON-UUID"
 ```
 
-**步骤2**: 分析返回的数据
-- 统计 `finish_status` 字段的分布
-- 计算平均学习进度（`study_progress` 字段）
-- 统计完成人数和未完成人数
-- 计算平均学习时长（`study_duration` 字段）
+### 课件列表
 
-### 工作流3: 查询某个时间段的课程
-
-当用户询问"查询本月的课程"时：
-
-**步骤1**: 计算时间范围（Unix时间戳，毫秒）
 ```bash
-# 例如：2024年1月1日 00:00:00 = 1704038400000
-# 2024年1月31日 23:59:59 = 1706716799000
-```
+# +list-lessons: 支持时间范围
+soke-cli course +list-lessons --course-id "ID" --start-time 1700000000000 --end-time 1700100000000
 
-**步骤2**: 查询课程列表
-```bash
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1706716799000
+# +lesson-list: 支持类型/关键词筛选
+soke-cli course +lesson-list --course-id "ID" --type "video" --keyword "关键词"
 ```
 
-### 工作流4: 查询课程的课件学习详情
+---
 
-当用户询问"查询某个课程的课件学习情况"时：
+## 可用命令全览
+
+### 课程管理
+
+| 命令 | 说明 | 风险 |
+|------|------|------|
+| `+list-categories` | 查询课程分类列表 | read |
+| `+list-courses` | 查询课程列表 | read |
+| `+get-course` | 查询课程详情 | read |
+| `+create` | 创建课程 | write |
+| `+update` | 更新课程 | write |
+| `+publish` | 发布课程 | write |
+
+### 课件管理
+
+| 命令 | 说明 | 风险 |
+|------|------|------|
+| `+lesson-create` | 创建课件 | write |
+| `+lesson-get` | 查询课件详情 | read |
+| `+lesson-list` | 查询课件列表（type/keyword） | read |
+| `+list-lessons` | 查询课件列表（时间范围） | read |
+
+### 素材管理 (soke-material)
+
+| 命令 | 说明 |
+|------|------|
+| `file +upload` | 上传文件到素材库 |
+| `file +create` | 手动创建素材记录 |
+| `file +list-files` | 查询素材列表 |
+| `file +get-info` | 查询素材详情 |
+| `file +download` | 获取下载链接 |
+| `file +list-categories` | 查询素材分类 |
+
+### 学习记录查询
+
+| 命令 | 说明 |
+|------|------|
+| `+list-course-users` | 课程学员学习记录 |
+| `+get-course-user` | 学员个人详情 |
+| `+list-lesson-learns` | 课件学习记录 |
+| `+list-lesson-faces` | 人脸识别记录 |
+
+### 指派管理 (soke-assign)
+
+| 命令 | 说明 |
+|------|------|
+| `assign +list-departments` | 查询可用部门 |
+| `assign +list-users` | 查询可用用户 |
+| `assign +create` | 创建指派 |
+| `assign +list` | 查询指派记录 |
 
-**步骤1**: 获取课程的课件列表
-```bash
-soke-cli course +list-lessons --course-id <course_id>
-```
+---
 
-**步骤2**: 查询每个课件的学习记录
-```bash
-soke-cli course +list-lesson-learns --lesson-id <lesson_id>
-```
+## 调试与故障排除
 
-**步骤3**: （可选）查询课件的人脸识别记录
-```bash
-soke-cli course +list-lesson-faces --lesson-id <lesson_id>
-```
+### 常见错误速查
 
-### +batch-create-from-excel
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| `未登录授权` | Token 过期 | `soke-cli auth login` |
+| `参数错误` | 必填参数缺失 | `soke-cli course <cmd> --help` |
+| `文件不存在` | 上传路径错误 | 使用绝对路径 |
+| `课程发布失败` | 无课件 | 先创建至少 1 个课件 |
+| `分类不存在` | category-id 无效 | 查询 `+list-categories` |
+| `素材不存在` | media-id 无效 | 确认上传成功 |
+| `指派失败` | 资源未发布 | 先发布课程 |
 
-通过 Excel 文件批量创建课程并上传课件素材。能力来自原独立工具 createcourse,已物理合入本 CLI(`internal/courseimport`)。
+### 调试检查清单
 
-**命令格式**:
 ```bash
-soke-cli course +batch-create-from-excel \
-  --file <课程信息.xlsx> \
-  [--material-dir <素材目录>] \
-  [--separator <分隔符>] \
-  [--mode default|hg] \
-  [--picture-time 6] \
-  [--material-category-id <分类ID>] \
-  [--json-events]
-```
-
-**Flags**:
+# 1. 认证状态
+soke-cli config show  # 确认用户凭证不为空
 
-| 名称 | 必填 | 默认 | 说明 |
-| --- | --- | --- | --- |
-| `--file` | 是 | - | Excel 文件路径,必须 `.xlsx` |
-| `--material-dir` | 否 | Excel 同目录 | 素材文件相对路径解析的根目录 |
-| `--separator` | 否 | `-` | Excel `分类` / `标签` 列的分隔符,同时影响两列 |
-| `--mode` | 否 | `default` | `default` 普通课程 / `hg` 海关学时模式 |
-| `--picture-time` | 否 | `6` | 视频抽帧秒数;仅当系统已装 ffmpeg 时生效 |
-| `--material-category-id` | 否 | 空 | 素材库默认分类 ID,空则交由后端兜底 |
-| `--json-events` | 否 | false | stdout 输出 JSON-lines 进度事件,供 sokeclaw 等 IPC 调用方解析 |
+# 2. 课程存在
+soke-cli course +get-course --course-id "ID" --format json | jq '.data.uuid'
 
-**Excel 模板**: 详见 [`templates/batch-create-from-excel.md`](./templates/batch-create-from-excel.md)。
+# 3. 课件数量
+soke-cli course +lesson-list --course-id "ID" --format json | jq '.data.list | length'
 
-**进度事件协议**(`--json-events` 模式):
+# 4. 发布状态
+soke-cli course +get-course --course-id "ID" --format json | jq '.data.status'
+# status=1 表示已发布
 
-| `type` | 含义 |
-| --- | --- |
-| `env` | 启动时报告 ffmpeg 是否可用 |
-| `course_start` | 开始处理某门课程 |
-| `course_done` | 某门课程全流程成功 |
-| `course_failed` | 某门课程失败(单门失败不中断整批) |
-| `episode_uploaded` | 单节课件上传完成 |
-| `cover_fallback` | 封面降级为默认封面 |
-| `run_done` | 整批结束,带 `ok` / `failed` 计数 |
+# 5. 指派状态
+soke-cli assign +list --module course --target-id "ID" --format json | jq '.data.list | length'
 
-**示例**:
-
-```bash
-# 默认模式,Excel 与素材同目录
-soke-cli course +batch-create-from-excel --file ./courses.xlsx
-
-# HG 学时模式,显式指定素材目录,机器可读输出
-soke-cli course +batch-create-from-excel \
-  --file ./hg-courses.xlsx \
-  --material-dir ./materials \
-  --mode hg \
-  --json-events
+# 始终用 --format json 获取结构化输出
 ```
 
-**注意**:
-
-- ffmpeg 是可选依赖:已装则启用视频抽帧封面;未装则封面策略自动降级到默认封面,不影响主流程。如需启用抽帧,把 ffmpeg 装到 `PATH`,或设置环境变量 `SOKE_CLI_FFMPEG_PATH` 指向可执行文件。
-- HG 模式下"所属单位标签"的 tag id 通过环境变量 `SOKE_CLI_HG_ORG_TAG_ID` 注入(原 createcourse 写死在 token 配置表里,合入 soke-cli 后改为外部注入)。
-- 单门课程失败不会中断整批运行,失败统计会在 `run_done` 事件汇总。
+---
 
-## 注意事项
+## 完整示例
 
-1. **时间格式**: 所有时间参数使用Unix时间戳（毫秒），不是秒
-2. **时间范围限制**: `+list-courses` 的起始与结束时间差不能超过365天
-3. **分页**: 默认每页100条，最大100条，超过需要分页查询
-4. **用户ID**: `dept_user_id` 是企业内的用户ID，不是用户名
-5. **课程ID**: `course-id` 和 `uuid` 是同一个字段，都表示课程ID
-6. **权限**: 所有操作都需要先完成认证（`soke-cli auth login`）
-7. **课程状态**: 
-   - `-1`: 删除
-   - `0`: 未发布
-   - `1`: 已发布
-   - `2`: 关闭
-8. **学习模式**:
-   - `1`: 自由式（可以任意顺序学习）
-   - `2`: 解锁式（必须按顺序学习）
-
-## 错误处理
-
-### 权限不足
-如果遇到权限错误，参考 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md) 中的权限处理章节。
-
-### 参数错误
-使用 `--help` 查看命令参数说明：
 ```bash
-soke-cli course +list-courses --help
+# === 1. 查询分类 ===
+CATEGORY_ID=$(soke-cli course +list-categories --format json | jq -r '.data.list[0].uuid')
+
+# === 2. 创建课程 ===
+COURSE_ID=$(soke-cli course +create \
+  --title "Python 数据分析实战" \
+  --category-id "$CATEGORY_ID" \
+  --format json | jq -r '.data.uuid')
+
+# === 3. 上传素材 ===
+UPLOAD=$(soke-cli file +upload --file "./lesson1.mp4" --format json)
+MEDIA_ID=$(echo "$UPLOAD" | jq -r '.data.uuid')
+FILE_TYPE=$(echo "$UPLOAD" | jq -r '.data.type')
+FILENAME=$(echo "$UPLOAD" | jq -r '.data.filename')
+FILESIZE=$(echo "$UPLOAD" | jq -r '.data.filesize')
+OBJECT=$(echo "$UPLOAD" | jq -r '.data.object')
+EXT=$(echo "$UPLOAD" | jq -r '.data.ext')
+
+# === 4. 创建课件 ===
+soke-cli course +lesson-create \
+  --course-id "$COURSE_ID" --title "第一课：环境搭建" \
+  --media-id "$MEDIA_ID" --type "$FILE_TYPE" --length 600 \
+  --object "$OBJECT" --filename "$FILENAME" --ext "$EXT" --filesize "$FILESIZE"
+
+# === 5. 发布课程 ===
+soke-cli course +publish --course-id "$COURSE_ID"
+
+# === 6. 指派学员 ===
+DEPT_ID=$(soke-cli assign +list-departments --keyword "研发" --format json | jq -r '.data.list[0].uuid')
+soke-cli assign +create \
+  --module "course" --target-id "$COURSE_ID" \
+  --dept-ids "$DEPT_ID" --dept-names "研发部" \
+  --learn-type "required"
+
+# === 7. 验证 ===
+soke-cli course +get-course --course-id "$COURSE_ID" --format json | jq .
+soke-cli course +lesson-list --course-id "$COURSE_ID" --format json | jq '.data.list'
 ```
 
-### 数据不存在
-如果查询的课程或用户不存在，API会返回空数据或错误提示。
-
-### 时间范围超限
-如果 `+list-courses` 的时间范围超过365天，API会返回错误，需要缩小时间范围。
+---
 
 ## API 接口映射
 
-| Shortcut | API 路径 | HTTP 方法 |
-|----------|----------|-----------|
+| CLI 命令 | API 路径 | 方法 |
+|----------|----------|------|
+| `+list-categories` | `/course/category/list` | GET |
 | `+list-courses` | `/course/course/list` | GET |
 | `+get-course` | `/course/course/info` | GET |
-| `+list-categories` | `/course/category/list` | GET |
+| `+create` | `/skills/course/create` | POST |
+| `+update` | `/skills/course/update/{id}` | PUT |
+| `+publish` | `/skills/course/update/{id}` | PUT |
+| `+lesson-create` | `/skills/course/lesson/create` | POST |
+| `+lesson-get` | `/skills/courseware/get/{id}` | GET |
+| `+lesson-list` | `/skills/course/lesson/list` | GET |
 | `+list-lessons` | `/course/lesson/list` | GET |
-| `+list-course-users` | `/course/courseUser/list` | GET |
-| `+get-course-user` | `/course/courseUser/info` | GET |
+| `+list-course-users` | `/course/user/list` | GET |
+| `+get-course-user` | `/course/user/info` | GET |
 | `+list-lesson-learns` | `/course/lessonLearn/list` | GET |
 | `+list-lesson-faces` | `/course/lessonFace/list` | GET |
+| `file +upload` | `/skills/uploadFile/signature` + `/skills/uploadFile/create` | POST |
+| `assign +list-departments` | `/skills/department/list` | GET |
+| `assign +list-users` | `/skills/user/list` | GET |
+| `assign +create` | `/skills/assignLog/create` | POST |
+| `assign +list` | `/skills/assignLog/list` | GET |
+
+## 权限要求
+
+| 操作 | 权限范围 |
+|------|----------|
+| 课程读写 | `course:course:write` / `course:course:readonly` |
+| 课件读写 | `course:courseware:write` / `course:courseware:readonly` |
+| 素材读写 | `file:file:write` / `file:file:readonly` |
+| 指派读写 | `assign:write` / `assign:read` |
+| 学习记录 | `course:courseUser:readonly` / `course:lessonLearn:readonly` |
+
+## 注意事项
+
+1. **课程至少需要 1 个课件才能发布**
+2. **课件参数全部从素材上传响应提取**，不手动构造
+3. **时长根据文件类型自动设置**: video=600s, audio=300s, 其他=0
+4. **课程发布后学员才可见**
+5. **指派是可选的**，未指派时学员看不到课程
+6. **所有时间参数使用毫秒级 Unix 时间戳**
+
+## 相关文档
+
+- [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md) — 认证、配置、权限
+- [`../soke-material/SKILL.md`](../soke-material/SKILL.md) — 文件上传和素材管理
+- [`../soke-lesson/SKILL.md`](../soke-lesson/SKILL.md) — 课件创建和管理
+- [`../soke-assign/SKILL.md`](../soke-assign/SKILL.md) — 指派管理
+- [`references/examples.md`](./references/examples.md) — 更多使用示例
+- [`references/course-list-courses.md`](./references/course-list-courses.md) — 课程查询参考