@sokeai/cli 1.0.77 → 1.0.78

package/skills/multi/soke-course/references/dependencies/soke-assign.md

@@ -0,0 +1,103 @@
+---
+name: soke-assign
+version: 1.0.0
+description: 指派管理 — 查询部门/用户并指派课程给学员，支持必修/选修
+tags: [soke, assign, department, user, enrollment]
+---
+
+# 指派管理
+
+## 触发描述
+
+课程创建并发布后，需要将课程指派给部门或具体学员时触发本技能。支持查询组织架构、查询用户列表、创建指派记录及查看指派列表。
+
+## 前置条件
+
+- 目标课程 `status = 1`（已发布），未发布的课程不可指派
+- 具有指派权限（管理员或课程负责人）
+
+## 执行流程
+
+### 1. 查询部门 `assign +list-departments`
+
+```bash
+soke assign +list-departments
+```
+
+返回当前租户下所有部门结构。输出格式预期为部门 ID 与名称的层级列表。
+
+> 该项为辅助查询，不直接参与指派创建，但可用于确认用户所属部门。
+
+### 2. 查询用户 `assign +list-users`
+
+```bash
+soke assign +list-users --department-id <departmentId>
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--department-id` | 否 | 按部门过滤，不传则返回全部用户 |
+
+返回用户列表，包含用户 ID、姓名、所属部门等基本信息。
+
+### 3. 创建指派 `assign +create`
+
+```bash
+soke assign +create \
+  --module course \
+  --module-id <courseId> \
+  --compulsory <1|0> \
+  --user-ids "<userId1>,<userId2>,<userId3>"
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--module` | 是 | 固定值 `course` |
+| `--module-id` | 是 | 课程 ID |
+| `--compulsory` | 是 | `1` = 必修，`0` = 选修 |
+| `--user-ids` | 是 | 逗号分隔的用户 ID 列表 |
+
+> ⚠️ 课程必须 `status = 1`（已发布），否则指派会失败。
+
+### 4. 查询指派 `assign +list`
+
+```bash
+soke assign +list --module-id <courseId>
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--module-id` | 是 | 课程 ID |
+
+返回该课程所有已指派的学员列表，包含用户信息、必修/选修标记、学习进度。
+
+## 输出标准
+
+创建指派成功后输出：
+
+```
+✅ 指派创建成功
+- 课程: {courseTitle} (ID: {courseId})
+- 类型: {必修/选修}
+- 指派人数: {N} 人
+- 用户: {userName1}, {userName2}...
+```
+
+查询操作以表格或列表形式输出结果。
+
+## 注意事项
+
+1. **课程必须先发布**（status=1）才能指派，未发布课程无法创建指派记录
+2. `--module` 当前仅支持 `course`，扩展模块后可能支持其他值
+3. 必修课（compulsory=1）学员不可跳过，选修课（compulsory=0）学员可自主选择
+4. 指派后可重复指派同一用户，以最新一次为准（覆盖更新）
+5. 批量指派建议单次 user-ids 不超过 500 人，超出分批处理
+6. 取消指派（删除指派记录）需通过后台操作，CLI 不直接支持
+
+## 检查清单
+
+- [ ] 课程 status = 1（已发布确认）
+- [ ] 已通过 list-departments / list-users 确认目标用户 ID
+- [ ] compulsory 正确设定（1=必修, 0=选修）
+- [ ] user-ids 为逗号分隔的有效用户 ID 列表
+- [ ] 指派完成后通过 assign +list 验证结果

package/skills/multi/soke-course/references/dependencies/soke-lesson.md

@@ -0,0 +1,119 @@
+---
+name: soke-lesson
+version: 1.0.0
+description: 课件管理 — 创建/查询/排序课程章节课件，所有参数来自素材上传返回结果
+tags: [soke, lesson, courseware, chapter, video, audio, document]
+---
+
+# 课件管理
+
+## 触发描述
+
+用户已有课程（course）且完成素材上传后，需要将素材添加为课程的章节课件时触发本技能。支持创建课件、列表查询、详情查询和排序，仅支持 `video | audio | document` 三种类型的课件。
+
+## 输入要求
+
+所有课件创建参数**必须来自 `soke-material` 上传返回的结果对象**，不允许手动构造。传入参数：
+
+```json
+{
+  "uuid": "素材上传返回的 uuid",
+  "filename": "素材上传返回的 filename",
+  "type": "素材上传返回的 type（仅 video/audio/document）",
+  "ext": "素材上传返回的 ext",
+  "filesize": "素材上传返回的 filesize",
+  "object": "素材上传返回的 object",
+  "duration": "默认时长或自定义时长（秒）",
+  "courseId": "目标课程 ID",
+  "title": "课件标题（用户提供或从 filename 推断）"
+}
+```
+
+> ⚠️ `uuid` `filename` `type` `ext` `filesize` `object` 六个字段必须严格从素材上传返回结果中取值，不可自行构造或编造。
+
+## 执行流程
+
+### 1. 创建课件 `course +lesson-create`
+
+```bash
+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`
+
+```bash
+soke course +lesson-list --course-id <courseId>
+```
+
+返回指定课程下所有课件的列表，包含课件 ID、标题、类型、排序序号。
+
+### 3. 课件详情 `course +lesson-get`
+
+```bash
+soke course +lesson-get --lesson-id <lessonId>
+```
+
+返回单个课件的完整信息（标题、类型、素材引用、时长、转码状态等）。
+
+### 4. 课件排序 `course +lesson-sort`
+
+```bash
+soke course +lesson-sort --course-id <courseId> --order "<lessonId1>,<lessonId2>,<lessonId3>"
+```
+
+调整课程内课件的展示顺序，`--order` 为逗号分隔的课件 ID 列表，按先后顺序排列。
+
+## 输出标准
+
+创建课件成功后输出摘要：
+
+```
+✅ 课件创建成功
+- 课程: {courseTitle} (ID: {courseId})
+- 课件: {title}
+- 类型: {type}
+- 时长: {duration}s
+- 课件 ID: {lessonId}
+```
+
+排序完成后输出更新后的课件列表。
+
+## 注意事项
+
+1. **仅支持三种类型**：`video` `audio` `document`，图片等其他类型不支持作为课件
+2. 所有素材引用参数必须来自 `soke-material` 上传返回，严禁手动编造 uuid / object 等字段
+3. 课件创建后自动关联到指定课程，无需额外绑定步骤
+4. 排序使用课件 ID 列表，未在列表中的课件保持在末尾，不丢失
+5. 课件删除、批量导入等操作不在 CLI 范围，如有需求引导至后台操作
+
+## 检查清单
+
+- [ ] 素材已完成上传，持有完整返回对象
+- [ ] courseId 已确认存在
+- [ ] type 仅限 video / audio / document
+- [ ] uuid / filename / type / ext / filesize / object 六个字段均来自上传返回
+- [ ] duration 已按类型默认规则或用户指定设定
+- [ ] 课件创建完成后能通过 lesson-list 验证

package/skills/multi/soke-course/references/dependencies/soke-material.md

@@ -0,0 +1,105 @@
+---
+name: soke-material
+version: 1.0.0
+description: 素材库管理 — 上传视频/音频/文档素材，返回资产元信息供课件创建直接使用
+tags: [soke, material, upload, video, audio, document]
+---
+
+# 素材库管理
+
+## 触发描述
+
+用户需要上传课程素材（视频、音频、文档）到素材库，或从已有素材库中选择素材时触发本技能。
+
+本技能支持两条路径：
+- **本地上传**：上传本地文件到素材库，返回标准资产信息
+- **素材库选择**：从已有素材库中搜索、浏览、选择已上传的素材
+
+## 输入要求
+
+**本地上传：**
+- **文件路径**：本地文件的绝对路径
+- **支持格式**：
+  | 类型 | 扩展名 |
+  |------|--------|
+  | 视频 | `.mp4` `.avi` `.mov` |
+  | 音频 | `.mp3` `.wav` |
+  | 文档 | `.pdf` `.ppt` `.pptx` `.doc` `.docx` |
+- **文件大小**：无硬性限制，由平台存储策略决定
+
+**素材库选择：**
+- 由调度方（soke-course）通过弹窗选定素材
+- 素材库中的文件已是上传态，直接返回复用即可
+
+## 执行流程
+
+### 第一步：确认文件有效性
+
+1. 校验文件存在且可读
+2. 校验扩展名在支持列表中
+3. 获取文件大小（bytes）
+
+### 第二步：调用上传接口
+
+使用 CLI 命令上传素材：
+
+```bash
+soke file +upload --path "/absolute/path/to/file"
+```
+
+### 第三步：解析返回结果
+
+上传成功后返回如下结构体，**全部字段原样保留**，供后续课件创建直接引用：
+
+```json
+{
+  "uuid": "素材唯一标识",
+  "filename": "原始文件名",
+  "type": "video | audio | document",
+  "ext": "mp4 | avi | mov | mp3 | wav | pdf | ppt | pptx | doc | docx",
+  "filesize": 文件字节数,
+  "object": "存储路径/对象键"
+}
+```
+
+### 第四步：设定默认时长
+
+素材默认学习时长按类型分别处理：
+
+| 素材类型 | 默认时长（秒） |
+|----------|----------------|
+| `video`  | 600s           |
+| `audio`  | 300s           |
+| `document` | 0s           |
+
+> 视频和音频实际时长以文件元数据为准；文档类不计时可设 0。
+
+## 输出标准
+
+完成上传后向用户输出摘要：
+
+```
+✅ 素材上传成功
+- 文件名: {filename}
+- 类型: {type}
+- 大小: {filesize} bytes
+- UUID: {uuid}
+```
+
+可将完整返回对象缓存在上下文中，供后续 `soke-lesson` 创建课件时直接引用。
+
+## 注意事项
+
+1. 上传前确认文件路径正确，扩展名匹配实际文件类型
+2. 不支持图片格式（`.jpg` `.png` 等），图片应使用其他上传通道
+3. 文档类素材默认时长 0s，如需强制学习时长可在课件创建时覆盖
+4. 返回的 `uuid` 是课件创建的唯一索引，务必保留
+5. 素材上传后默认进入当前租户的素材库，权限与租户一致
+
+## 检查清单
+
+- [ ] 文件路径存在且可访问
+- [ ] 扩展名在 `.mp4|.avi|.mov|.mp3|.wav|.pdf|.ppt|.pptx|.doc|.docx` 中
+- [ ] 上传完成，获取到完整返回对象（uuid / filename / type / ext / filesize / object）
+- [ ] 默认时长按类型正确设定
+- [ ] 返回数据完整传递给后续课件创建流程