@sokeai/cli 1.0.78 → 1.0.80

package/skills/multi/soke-course/references/cli-facts.md

@@ -0,0 +1,105 @@
+# CLI 事实表（唯一事实源）
+
+> 实测于 soke-cli v1.0.77（2026-08-29）。本表为所有命令参数的唯一事实源；子 SOP 只写用法示例，参数以本表为准。
+> 兜底规则：本表未覆盖的命令 → 跑 `soke-cli <cmd> --help` 实测后补录本表。
+> 通用：所有命令支持 `--format json`（结构化输出推荐）；时间戳均为毫秒。
+> 返回契约：以下“必取字段”是进入下一步的最低要求；实际响应可能包裹在 `data/list/items` 中，先定位字段再继续。未知字段或未知状态不得按成功推断，需保留原始 JSON 并执行 `--help`/实测确认。
+
+## course 组
+
+### +create 创建课程
+`--title`(必填) `--category-id`(必填) `--description`
+返回最低字段：`course-id`、`title`、`status`。
+
+### +update 更新/关闭课程
+`--course-id`(必填) `--title` `--credit` `--description` `--category-id`
+`--image`(封面，**只收图片库 photoUri**) `--image-x/y/w/h`(裁剪)
+`--action` = update(默认) | **close（关闭课程，CLI 支持！删除才需后台）**
+
+### +advanced 高级设置
+`--course-id`(必填)；`--study-type` 1自由/2解锁；`--is-accelerate` 倍速；`--is-drag`/`--drag-type` 拖动；
+`--open-face-recognition` 课前人脸；`--is-first-face` 0不/1首次/2每次；`--learning-face-recognition`/`--face-recognition-times` 学习中人脸；
+`--open-workrecord` 待办；`--allow-after-expiration` 截止后学习；`--is-remind`/`--remind-days`/`--remind-time`/`--remind-content` 未学提醒；
+`--evaluate-required` 打星评价；`--is-hang`/`--hang-time`(≤60分) 文档防挂机；`--comment-switch` 评论；
+`--image-file`(本地二维码图，内部传 OSS 不进图片库，jpg/jpeg/png) 与 `--image-oss-url` 二选一
+
+### +publish 发布
+`--course-id`(必填) `--publish-time`("YYYY-MM-DD HH:MM:SS" 北京时间；默认 0000-00-00 00:00:00=立即)
+返回最低字段：`course-id`、`status`；定时发布另需回查 `publish-time`。
+
+### +get-course / +list-courses
+get: `--course-id`
+list: `--keyword` `--category-path`(分类筛选，**不是 --category-id**) `--status`(0/1/2，**默认1**) `--is-in`(0外部/1内部，默认1) `--is-my` `--is-joint` `--joint-out` `--page` `--page-size`(默认10)
+**⚠️ 无 --start-time/--end-time（旧文档的时间范围/365天限制对本命令不成立）**
+
+### +list-categories
+`--page` `--page-size`(max 100)。当前事实表未确认 `--parent-id`/`--level`，不得直接使用；如需末级分类，先按返回的 parent_id/level 递归查询或执行 --help 实测后补录。
+
+### +lesson-create 创建课件
+`--course-id`(必填) `--title` `--type` video/audio/photo_gallery/document/exam
+非 exam：`--media-id`(素材UUID，**不是 --uuid**) `--filename` `--ext` `--filesize` `--object` `--length`(秒，**不是 --duration**)
+exam：`--paper-id` 或 `--paper-title`(列表匹配) `--pool-id`(可选) `--minute`(默认30)/`--second`
+通用：`--point` `--sort`
+返回最低字段：`lesson-id`、`course-id`、`type`、`status`；非 exam 还需保留上传对象字段。
+
+### +lesson-list / +lesson-get / +lesson-sort
+list: `--course-id` `--keyword` `--type`(video/audio/image/document/link/live/exam/questionnaire/sign_in) `--page` `--limit`(默认10，**不是 --page-size**)
+get: `--id`(课件ID，**不是 --lesson-id**)
+sort: `--course-id` `--sort-list`("id1,id2,..."，**不是 --order**)
+
+### 学习数据查询
++list-course-users: `--course-id` `--finish-start-time`/`--finish-end-time`(**必传，跨度≤7天**，回归实测) `--userid-list`(逗号,≤100) `--page` `--page-size`
++get-course-user: `--course-id` `--dept-user-id`
++list-lesson-learns: `--lesson-id` `--course-id` `--userid-list` `--finish-start-time`/`--finish-end-time` `--page` `--page-size`
++list-lesson-faces: `--target-id`(=课件uuid，**不是 --lesson-id**) `--userid-list` `--page` `--page-size`（**无时间参数**）
+
+## file 组（素材库）
+
++upload: `--file`(本地路径，**不是 --path**；不支持图片) `--type`(默认自动检测) `--length`(默认视频600/音频300/**文档120**) `--category-id` `--module`(默认material) `--object-name` `--storage`
+返回最低字段：`uuid`、`filename`、`type`、`ext`、`filesize`、`object`、`length`；图片不得使用此命令。
+list-files: **无 + 前缀** → `soke-cli file list-files --page --page-size`
+get-info: **无 + 前缀** → `soke-cli file get-info --file-id`
++create: 创建素材库文件（已有 OSS 对象时）
+
+## assign 组（指派）
+
++list-departments: `--keyword` `--parent-id`(默认"1"=仅顶级，**全树需递归**) `--page` `--limit`
++list-users: `--dept-id` `--keyword` `--search-target`(name/phone/job_number) `--list-all` `--is-in` `--page` `--limit`
++create: `--module`(course/exam/learning_map) `--target-id`(**不是 --module-id**) `--learn-type` **required/optional（不是 --compulsory 1|0）** `--user-ids` `--user-names`(对应) `--dept-ids` `--dept-names` `--date` `--set-message`/`--message-switch`/`--message-content`
+返回最低字段：`target-id`、目标类型、实际指派数量和已存在/新增/失败明细。
++list: `--module` `--target-id` `--keyword` `--learn-type` `--page` `--limit`
+
+## photo-gallery 组（图片库）
+
++create: `--file`(本地图片) `--title` `--category-id`(默认empty) → 返回 uuid/photoUri
++list: `--file-keyword` `--category-id` `--from` `--page` `--limit`
++get: `--uuid`（含完整访问 URL）
+
+## exam 最小建题链（subs/exam 专用）
+
++create-pool: `--title` `--path`('["分类uuid"]') `--description` `--status`
++create-question: `--pool-id` `--type`(single_choice/choice/uncertain_choice/determine/fill/essay/material) `--title`(fill 用 `[[答案N]]`，**不传 --answer**) `--score`(>0) `--difficulty`(simple/medium/hard) `--choices`('[{"key":"A1","value":"A"}]') `--answer`(选择/判断为索引数组) `--answer-type`(fill) `--analysis`
++create-paper: `--title`(≤50) `--pool-id`('["pool_uuid"]') `--pattern`(questionType/random/selection/import) `--type-metas`(JSON: {"single_choice":{"count":N,"score":N},...})
++update-paper: `--paper-id` `--title`(**publish 必重传**) `--action publish`
+
+## clock 组（作业查询，只读；**--page/--page-size 强制必传**）
+
+list-learnings: `--target-id`(课程ID) `--start-time`/`--end-time`(毫秒) `--page` `--page-size`
+list-logs: `--clock-id`(来自 list-learnings) `--start-time`/`--end-time` `--page` `--page-size`
+list-log-lessons: `--target-id`(提交ID，来自 list-logs) `--page` `--page-size`
+
+## 漂移修正表（旧文档 → 实际）
+
+| 旧 | 实际 |
+|----|------|
+| file +upload --path | --file |
+| file +list-files / +get-info | 无 + 前缀 |
+| lesson-create --uuid / --duration | --media-id / --length |
+| lesson-get --lesson-id | --id |
+| lesson-sort --order | --sort-list |
+| lesson-list --page-size | --limit |
+| list-courses --start-time/--end-time/--category-id | 不存在；用 --keyword/--category-path |
+| list-lesson-faces --lesson-id + 时间范围 | --target-id，无时间参数 |
+| assign --module-id / --compulsory 1\|0 | --target-id / --learn-type required\|optional |
+| 关闭课程仅后台 | +update --action close |
+| 文档默认时长 0s | 120s |

package/skills/multi/soke-course/references/examples.md

@@ -1,480 +1,56 @@
-# 课程查询使用示例
+# 使用示例（v6.39.0，命令已实测）
 
-本文档提供了使用 `soke-course` skill 的实际示例。
+## 示例 1：一条消息收集 + 创建 + 发布
 
-## 示例1: 查询本月的课程
-
-### 需求
-查询2024年5月创建的所有已发布课程。
-
-### 步骤
-
-**1. 计算时间戳**
-
-```javascript
-// 2024年5月1日 00:00:00
-const startTime = new Date('2024-05-01 00:00:00').getTime();
-console.log(startTime); // 1714492800000
-
-// 2024年5月31日 23:59:59
-const endTime = new Date('2024-05-31 23:59:59').getTime();
-console.log(endTime); // 1717171199000
 ```
+主管: **请输入你要上传的课程标题**
+      | A | 来源 |   A1 本地上传 / A2 素材库选择
+      | B | 分类 |   B1 外部课程 … B8 产品迭代
+      | C | 模板 |   C1 合规必修 … C7 不选择模板
+      > 请直接提供课程标题、课件来源、分类和模板；本地上传时同时提供文件路径。
 
-**2. 执行查询**
+用户: Python入门 A1B3C3 + demo.mp4
 
-```bash
-soke-cli course +list-courses \
-  --start-time 1714492800000 \
-  --end-time 1717171199000 \
-  --status 1
-```
+主管: ✅ 课程已创建 (id: course_xxx) ｜ 模板: 新人入职
+      ✅ 上传 demo.mp4 → 课件已创建（视频 · 转码中）
+      加小测验吗？回复 D1 加 / D2 不加
 
-**3. 预期输出**
+用户: D2
 
-```
-uuid                                  title              category_id  status  lesson_num  create_time
-------------------------------------  -----------------  -----------  ------  ----------  -------------
-abc123-def456-ghi789                  Go语言入门         cat001       1       20          1714492800000
-xyz789-uvw456-rst123                  Python基础教程     cat002       1       15          1714579200000
-```
+主管:       ✅ Gate Check 6 项通过
+      指派课程并发布吗？回复 G1 指派 / G2 不指派；E1 发布 / E2 不发布
 
----
+用户: G1，E1
 
-## 示例2: 统计课程完成率
-
-### 需求
-统计某个课程的学习完成情况，包括完成人数、平均进度等。
-
-### 步骤
-
-**1. 获取课程学习记录**
-
-```bash
-soke-cli course +list-course-users \
-  --course-id "abc123-def456-ghi789" \
-  --page-size 100
+主管: ✅ 已指派 → ✅ 已发布（status=1）
 ```
 
-**2. 分析返回数据**
+## 示例 2：素材库 + 小测验（引用试卷）
 
-假设返回数据如下：
-
-```json
-{
-  "data": {
-    "list": [
-      {
-        "dept_user_id": "user001",
-        "dept_user_name": "张三",
-        "study_progress": 100,
-        "finish_status": 1,
-        "study_duration": 7200
-      },
-      {
-        "dept_user_id": "user002",
-        "dept_user_name": "李四",
-        "study_progress": 50,
-        "finish_status": 0,
-        "study_duration": 3600
-      },
-      {
-        "dept_user_id": "user003",
-        "dept_user_name": "王五",
-        "study_progress": 100,
-        "finish_status": 1,
-        "study_duration": 6800
-      }
-    ]
-  }
-}
 ```
+用户: A2B4C5，搜索 销售
 
-**3. 计算统计数据**
-
-```javascript
-const data = response.data.list;
-
-// 总人数
-const totalUsers = data.length; // 3
+主管: 📚 匹配: 11 3231销售连带提升课件.pdf ｜ 16 授客学堂价格表.xlsx …回复编号
 
-// 完成人数
-const completedUsers = data.filter(u => u.finish_status === 1).length; // 2
+用户: 11，D1，H1，试卷叫"安全卷一"
 
-// 完成率
-const completionRate = (completedUsers / totalUsers * 100).toFixed(2); // 66.67%
-
-// 平均进度
-const avgProgress = (data.reduce((sum, u) => sum + u.study_progress, 0) / totalUsers).toFixed(2); // 83.33%
-
-// 平均学习时长（小时）
-const avgDuration = (data.reduce((sum, u) => sum + u.study_duration, 0) / totalUsers / 3600).toFixed(2); // 1.62小时
-
-console.log(`总人数: ${totalUsers}`);
-console.log(`完成人数: ${completedUsers}`);
-console.log(`完成率: ${completionRate}%`);
-console.log(`平均进度: ${avgProgress}%`);
-console.log(`平均学习时长: ${avgDuration}小时`);
+主管: ✅ 课件已创建（文档）
+      ✅ 小测验已挂载（--paper-title 安全卷一 · 30 分）
+      指派课程并发布吗？回复 G1 指派 / G2 不指派；E1 发布 / E2 不发布
 ```
 
----
-
-## 示例3: 查询用户的学习情况
+## 示例 3：查进度 + 关闭
 
-### 需求
-查询"张三"在某个课程的学习情况。
-
-### 步骤
-
-**1. 查询用户ID**
-
-```bash
-soke-cli contact +search-user --name "张三"
 ```
+用户: 看看谁学完了
 
-假设返回：
-```json
-{
-  "data": {
-    "dept_user_id": "user001",
-    "dept_user_name": "张三"
-  }
-}
-```
+主管: 📊 Python入门 — 完成 2/3（张三 100% / 王五 100% / 李四 50%）
 
-**2. 查询课程学习记录**
+用户: 这门课下线吧
 
-```bash
-soke-cli course +get-course-user \
-  --course-id "abc123-def456-ghi789" \
-  --dept-user-id "user001"
-```
+主管: ⚠️ 关闭后学员不可见，可重新发布。回复「确认关闭」执行
 
-**3. 预期输出**
+用户: 确认关闭
 
-```json
-{
-  "data": {
-    "target_id": "record001",
-    "dept_user_id": "user001",
-    "dept_user_name": "张三",
-    "study_progress": 100,
-    "finish_status": 1,
-    "study_duration": 7200,
-    "create_time": 1714492800000,
-    "update_time": 1714579200000
-  }
-}
+主管: ✅ 已关闭（status=2）
 ```
-
-**4. 解读结果**
-
-- 学习进度: 100%（已完成）
-- 完成状态: 1（已完成）
-- 学习时长: 7200秒（2小时）
-- 开始时间: 2024-05-01
-- 最后更新: 2024-05-02
-
----
-
-## 示例4: 查询课程的课件学习详情
-
-### 需求
-查询某个课程的所有课件，并统计每个课件的学习情况。
-
-### 步骤
-
-**1. 获取课程课件列表**
-
-```bash
-soke-cli course +list-lessons \
-  --course-id "abc123-def456-ghi789"
-```
-
-**2. 预期输出**
-
-```json
-{
-  "data": {
-    "list": [
-      {
-        "uuid": "lesson001",
-        "title": "第1课：Go语言简介",
-        "type": "video",
-        "duration": 1800,
-        "sort": 1
-      },
-      {
-        "uuid": "lesson002",
-        "title": "第2课：环境搭建",
-        "type": "video",
-        "duration": 2400,
-        "sort": 2
-      }
-    ]
-  }
-}
-```
-
-**3. 查询每个课件的学习记录**
-
-```bash
-# 查询第1课的学习记录
-soke-cli course +list-lesson-learns --lesson-id "lesson001"
-
-# 查询第2课的学习记录
-soke-cli course +list-lesson-learns --lesson-id "lesson002"
-```
-
-**4. 统计分析**
-
-```javascript
-// 假设lesson001有50人学习，40人完成
-// 假设lesson002有50人学习，30人完成
-
-const lessonStats = [
-  { title: "第1课：Go语言简介", total: 50, completed: 40, rate: "80%" },
-  { title: "第2课：环境搭建", total: 50, completed: 30, rate: "60%" }
-];
-
-console.table(lessonStats);
-```
-
----
-
-## 示例5: 按分类查询课程
-
-### 需求
-查询"技术培训"分类下的所有已发布课程。
-
-### 步骤
-
-**1. 获取课程分类列表**
-
-```bash
-soke-cli course +list-categories
-```
-
-**2. 找到目标分类**
-
-假设返回：
-```json
-{
-  "data": {
-    "list": [
-      {
-        "uuid": "cat001",
-        "title": "技术培训",
-        "parent_id": "0"
-      },
-      {
-        "uuid": "cat002",
-        "title": "管理培训",
-        "parent_id": "0"
-      }
-    ]
-  }
-}
-```
-
-**3. 查询该分类下的课程**
-
-```bash
-soke-cli course +list-courses \
-  --start-time 1704038400000 \
-  --end-time 1735660799000 \
-  --category-id "cat001" \
-  --status 1
-```
-
----
-
-## 示例6: 查询人脸识别记录
-
-### 需求
-查询某个课件的人脸识别记录，确保学员本人学习。
-
-### 步骤
-
-**1. 查询课件的人脸识别记录**
-
-```bash
-soke-cli course +list-lesson-faces \
-  --lesson-id "lesson001" \
-  --start-time 1714492800000 \
-  --end-time 1717171199000
-```
-
-**2. 预期输出**
-
-```json
-{
-  "data": {
-    "list": [
-      {
-        "uuid": "face001",
-        "dept_user_id": "user001",
-        "dept_user_name": "张三",
-        "face_status": 1,
-        "face_time": 1714492800000
-      },
-      {
-        "uuid": "face002",
-        "dept_user_id": "user002",
-        "dept_user_name": "李四",
-        "face_status": 2,
-        "face_time": 1714493400000
-      }
-    ]
-  }
-}
-```
-
-**3. 分析识别结果**
-
-- `face_status = 1`: 识别成功（张三）
-- `face_status = 2`: 识别失败（李四）
-
----
-
-## 示例7: 批量查询多个用户的学习记录
-
-### 需求
-查询多个用户在某个课程的学习情况。
-
-### 步骤
-
-**1. 准备用户ID列表**
-
-```bash
-# 用户ID列表（逗号分隔，最多100个）
-USER_IDS="user001,user002,user003,user004,user005"
-```
-
-**2. 批量查询**
-
-```bash
-soke-cli course +list-course-users \
-  --course-id "abc123-def456-ghi789" \
-  --userid-list "$USER_IDS"
-```
-
-**3. 预期输出**
-
-```json
-{
-  "data": {
-    "list": [
-      {
-        "dept_user_id": "user001",
-        "dept_user_name": "张三",
-        "study_progress": 100,
-        "finish_status": 1
-      },
-      {
-        "dept_user_id": "user002",
-        "dept_user_name": "李四",
-        "study_progress": 50,
-        "finish_status": 0
-      }
-      // ... 其他用户
-    ]
-  }
-}
-```
-
----
-
-## 示例8: 查询某个时间段完成的学习记录
-
-### 需求
-查询2024年5月完成课程学习的所有用户。
-
-### 步骤
-
-**1. 计算时间范围**
-
-```javascript
-const finishStartTime = new Date('2024-05-01 00:00:00').getTime(); // 1714492800000
-const finishEndTime = new Date('2024-05-31 23:59:59').getTime();   // 1717171199000
-```
-
-**2. 查询完成记录**
-
-```bash
-soke-cli course +list-course-users \
-  --course-id "abc123-def456-ghi789" \
-  --finish-start-time 1714492800000 \
-  --finish-end-time 1717171199000
-```
-
-**3. 筛选已完成的记录**
-
-```javascript
-const data = response.data.list;
-const completedUsers = data.filter(u => u.finish_status === 1);
-
-console.log(`5月完成学习的用户数: ${completedUsers.length}`);
-completedUsers.forEach(u => {
-  console.log(`- ${u.dept_user_name}: ${u.study_progress}%`);
-});
-```
-
----
-
-## 常用脚本
-
-### 脚本1: 课程完成率统计脚本
-
-```bash
-#!/bin/bash
-
-COURSE_ID="abc123-def456-ghi789"
-
-# 获取学习记录
-RESULT=$(soke-cli course +list-course-users --course-id "$COURSE_ID" --page-size 100)
-
-# 使用jq解析JSON（需要安装jq）
-TOTAL=$(echo "$RESULT" | jq '.data.list | length')
-COMPLETED=$(echo "$RESULT" | jq '[.data.list[] | select(.finish_status == 1)] | length')
-RATE=$(echo "scale=2; $COMPLETED * 100 / $TOTAL" | bc)
-
-echo "课程ID: $COURSE_ID"
-echo "总人数: $TOTAL"
-echo "完成人数: $COMPLETED"
-echo "完成率: $RATE%"
-```
-
-### 脚本2: 批量导出课程数据
-
-```bash
-#!/bin/bash
-
-START_TIME=1704038400000
-END_TIME=1735660799000
-OUTPUT_FILE="courses.json"
-
-# 导出所有课程
-soke-cli course +list-courses \
-  --start-time "$START_TIME" \
-  --end-time "$END_TIME" \
-  --page-size 100 > "$OUTPUT_FILE"
-
-echo "课程数据已导出到: $OUTPUT_FILE"
-```
-
----
-
-## 注意事项
-
-1. **时间戳格式**: 所有时间参数必须使用毫秒级Unix时间戳
-2. **分页处理**: 如果数据量大，需要循环分页查询
-3. **权限检查**: 确保已完成认证并有相应权限
-4. **错误处理**: 建议在脚本中添加错误处理逻辑
-5. **API限流**: 注意API调用频率限制
-
-## 相关资源
-
-- [SKILL.md](../SKILL.md) - 完整文档
-- [README.md](../README.md) - 快速开始
-- [course-list-courses.md](./course-list-courses.md) - 详细参考