@sokeai/cli 1.0.39 → 1.0.53

package/skills/soke-learning-map/SKILL.md

@@ -0,0 +1,544 @@
+---
+name: soke-learning-map
+summary: 授客学堂学习地图管理（创建/阶段/发布/查询/指派），完整管理学习地图生命周期
+version: 1.0.0
+description: "授客学堂学习地图管理：完整的学习地图生命周期管理，包括创建学习地图、查询课程分类与课程、检查课程可用性、创建阶段、发布地图、指派部门/学员、查询学员进度的全链路流程。集成 soke-assign（指派管理）子 skill。当用户需要创建学习地图、添加阶段和课程内容、发布地图、指派学员、查询学习进度时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+    skills: ["soke-assign"]
+  cliHelp: "soke-cli learning-map --help"
+---
+
+# 学习地图管理 (soke-learning-map)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+
+## 使用前提
+
+1. 已安装 `soke-cli`
+2. 已登录授权：`soke-cli auth login`
+
+```bash
+soke-cli auth login
+soke-cli config show  # 验证登录状态
+```
+
+---
+
+## 端到端创建工作流
+
+完整创建一个可学习的学习地图需要以下步骤：
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ 1. 查询地图分类      →  获取 category-uuid (path[0])                │
+│ 2. 创建学习地图      →  获取 map-uuid                               │
+│ 3. 查询课程分类子树  →  获取课程分类 uuid                            │
+│ 4. 搜索课程列表      →  获取课程 uuid + 课程元数据                   │
+│ 5. 检查课程可用性    →  确认课程可加入该地图                          │
+│ 6. 创建学习地图阶段  →  添加课程内容，获取 stage-uuid                │
+│ 7. 发布学习地图      →  学员可见                                      │
+│ 8. (可选) 指派       →  分配给部门/学员 → 学员开始学习               │
+│ 9. 查询学员进度      →  查看学习状态                                  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 数据流转图
+
+```
+地图分类查询                   课程分类子树查询
+     │                               │
+     ▼                               ▼
+ category-uuid                 course-category-uuid
+     │                               │
+     ▼                               ▼
+创建学习地图 ──→ map-uuid ──→ 搜索课程列表 ──→ course-uuid
+                    │                                │
+                    └──────────────┬─────────────────┘
+                                   ▼
+                           检查课程可用性 ──→ availabelIds
+                                   │
+                                   ▼
+                           创建学习地图阶段 ──→ stage-uuid
+                                   │
+                                   ▼
+                           发布学习地图 ◄── 至少 1 个阶段
+                                   │
+                                   ▼
+                           指派给学员 ◄── assign +create (可选)
+                                   │
+                                   ▼
+                           学员可开始学习
+```
+
+### 各步骤参数依赖
+
+| 步骤 | 命令 | 关键输出 | 传入下一步 |
+|------|------|----------|------------|
+| 1 | `+list-categories` | `data.list[].uuid` | 步骤2 `--path` |
+| 2 | `+create-map` | `data.info.uuid` | 步骤5/6/7 `--map-id` / `--uuid` |
+| 3 | `+course-category-tree` | `data[].uuid` | 步骤4 `--category-id` |
+| 4 | `+search-courses` | `data[].uuid` | 步骤5 `--course-ids`；步骤6 `--item-uuids` |
+| 5 | `+check-item-status` | `data.availabelIds[]` | 步骤6 `--item-uuids`（只传可用 UUID） |
+| 6 | `+create-stage` | `data.info.uuid` | 可创建多个阶段 |
+| 7 | `+publish` | `data.info.status=1` | 发布成功 |
+
+---
+
+## 步骤1：查询学习地图分类
+
+创建学习地图前必须先获取分类 ID。
+
+```bash
+soke-cli learning-map +list-categories --page 1 --page-size 10
+
+# JSON 输出供解析：
+soke-cli learning-map +list-categories --format json
+```
+
+**响应关键字段**：
+- `data.list[].uuid` → 分类 UUID（传入步骤2 `--path`）
+- `data.list[].title` → 分类名称
+
+---
+
+## 步骤2：创建学习地图
+
+```bash
+soke-cli learning-map +create-map \
+  --path "CATEGORY-UUID" \
+  --title "学习地图标题" \
+  --type "cycle" \
+  --template "14" \
+  --picture "https://newsokecdn.soke.cn/dingfc5d942826fce9d9/public/image/learning_map/other.png"
+
+# 带可选参数：
+soke-cli learning-map +create-map \
+  --path "CATEGORY-UUID" \
+  --title "新员工入职培训" \
+  --type "cycle" \
+  --template "14" \
+  --picture "https://newsokecdn.soke.cn/.../other.png" \
+  --description "<p>新员工培训学习地图</p>" \
+  --is-new "1" \
+  --unlock-type "0" \
+  --format json
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--path` | 是 | 所属分类 UUID（步骤1 获取） |
+| `--title` | 是 | 学习地图名称 |
+| `--type` | 是 | `cycle`（周期学习）/ `free`（自由学习） |
+| `--template` | 是 | 模板 ID，如 `14` |
+| `--picture` | 是 | 封面图片 URL |
+| `--description` | 否 | 简介（支持 HTML） |
+| `--is-new` | 否 | 是否新员工专属：`0` 否 / `1` 是（默认 `0`） |
+| `--is-ojt` | 否 | 是否 OJT：`0` 否 / `1` 是（默认 `0`） |
+| `--is-public` | 否 | 是否公开：`0` 否 / `1` 是（默认 `0`） |
+| `--open-time` | 否 | 开放时间（`YYYY-MM-DD HH:mm:ss`），`0000-00-00 00:00:00` 不限 |
+| `--end-time` | 否 | 结束时间，`0000-00-00 00:00:00` 不限 |
+| `--unlock-type` | 否 | `0` 顺序解锁 / `1` 自由解锁（默认 `0`） |
+
+**响应提取**：`data.info.uuid` → 地图 UUID（`map-uuid`），后续所有步骤均使用此值。
+
+---
+
+## 步骤3：查询课程分类子树
+
+查询可加入学习地图的课程所在分类。
+
+```bash
+soke-cli course +category-tree \
+  --parent-id "PARENT-CATEGORY-UUID"
+
+# JSON 输出：
+soke-cli course +category-tree --parent-id "UUID" --format json
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--parent-id` | 是 | 父分类 UUID（根分类一般已知，可从平台获取） |
+| `--lang` | 否 | 语言，默认 `zh` |
+
+**响应关键字段**：
+- `data[].uuid` → 子分类 UUID（传入步骤4 `--category-id`）
+- `data[].title` → 分类名称
+- `data[].has_children` → 是否还有子分类（`1` 表示有，可继续递归查询）
+
+---
+
+## 步骤4：搜索课程列表
+
+根据分类 UUID 搜索该分类下的课程。
+
+```bash
+soke-cli course +search \
+  --category-id "COURSE-CATEGORY-UUID"
+
+# JSON 输出：
+soke-cli course +search \
+  --category-id "COURSE-CATEGORY-UUID" \
+  --format json
+```
+
+**响应关键字段**：
+
+| 字段 | 用途 |
+|------|------|
+| `data[].uuid` | 课程 UUID（步骤5 `--course-ids`；步骤6 `--item-uuids`） |
+| `data[].title` | 课程标题（供展示确认） |
+
+---
+
+## 步骤5：检查课程可用性
+
+验证所选课程能否加入该学习地图（避免无效操作）。
+
+```bash
+soke-cli learning-map +check-item-status \
+  --map-id "MAP-UUID" \
+  --course-ids "COURSE-UUID-1,COURSE-UUID-2"
+
+# JSON 输出：
+soke-cli learning-map +check-item-status \
+  --map-id "MAP-UUID" \
+  --course-ids "COURSE-UUID-1" \
+  --format json
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--map-id` | 是 | 学习地图 UUID（步骤2 获取） |
+| `--course-ids` | 是 | 课程 UUID 列表，多个以英文逗号分隔 |
+
+**响应关键字段**：
+- `data.canUse` → `true` 表示全部可用
+- `data.availabelIds[]` → 可用课程 UUID 列表（只将此列表中的 UUID 传入步骤6 `--item-uuids`）
+
+---
+
+## 步骤6：创建学习地图阶段
+
+提供阶段内容类型和课程 UUID 列表，CLI 会自动调用课程详情接口获取完整信息并构建 `selectItems`，无需手动传入 JSON。
+
+```bash
+soke-cli learning-map +create-stage \
+  --map-id "MAP-UUID" \
+  --title "阶段1：基础学习" \
+  --item-type "course" \
+  --item-uuids "COURSE-UUID-1,COURSE-UUID-2" \
+  --cycle "7" \
+  --unlock-type "0" \
+  --finish-all "1"
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--map-id` | 是 | 学习地图 UUID（步骤2 获取） |
+| `--title` | 是 | 阶段名称 |
+| `--item-type` | 是 | 阶段内容类型，目前支持 `course`（课程） |
+| `--item-uuids` | 是 | 资源 UUID 列表，多个以英文逗号分隔（步骤5 `availabelIds` 中的 UUID） |
+| `--cycle` | 否 | 学习周期（天），`0` 不限（默认 `0`） |
+| `--description` | 否 | 阶段描述 |
+| `--display` | 否 | 是否显示：`1` 显示 / `0` 隐藏（默认 `1`） |
+| `--start-time` | 否 | 开始时间，`0000-00-00 00:00:00` 不限 |
+| `--end-time` | 否 | 结束时间，`0000-00-00 00:00:00` 不限 |
+| `--unlock-type` | 否 | `0` 顺序解锁 / `1` 自由解锁（默认 `0`） |
+| `--finish-all` | 否 | 是否需完成全部：`1` 是 / `0` 否（默认 `1`） |
+| `--need-count` | 否 | 需完成数量（`--finish-all 0` 时有效，默认 `1`） |
+| `--certificate-id` | 否 | 证书 ID |
+
+> **说明**：`--item-type course` 时，CLI 自动调用 `/course/course/info` 获取每个课程的标题、封面、时长、积分、学分等信息，自动组装 `selectItems` 字段后再提交创建请求，无需手动构造 JSON。
+
+**响应提取**：`data.info.uuid` → 阶段 UUID；可重复步骤6创建多个阶段。
+
+---
+
+## 步骤7：发布学习地图
+
+**前提**：学习地图至少包含 1 个阶段。
+
+```bash
+soke-cli learning-map +publish --uuid "MAP-UUID"
+
+# 下架：
+soke-cli learning-map +publish --uuid "MAP-UUID" --status "0"
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--uuid` | 是 | 学习地图 UUID（步骤2 获取） |
+| `--status` | 否 | `1` 发布 / `0` 下架（默认 `1`） |
+
+**响应验证**：`data.info.status` = `1` 表示发布成功。
+
+---
+
+## 步骤8：指派学习地图（可选）
+
+> 详见 [`../soke-assign/SKILL.md`](../soke-assign/SKILL.md)
+
+发布后指派给部门或学员，学员才能看到并开始学习。
+
+### 8.1 查询可用部门/用户
+
+```bash
+soke-cli assign +list-departments --keyword "关键词"
+soke-cli assign +list-users --dept-id "DEPT-ID" --keyword "关键词"
+```
+
+### 8.2 创建指派
+
+```bash
+# 指派给部门
+soke-cli assign +create \
+  --module "learning_map" \
+  --target-id "MAP-UUID" \
+  --dept-ids "DEPT-ID" \
+  --dept-names "部门名称" \
+  --learn-type "required"
+
+# 指派给用户
+soke-cli assign +create \
+  --module "learning_map" \
+  --target-id "MAP-UUID" \
+  --user-ids "USER-ID" \
+  --user-names "学员姓名" \
+  --learn-type "required"
+```
+
+---
+
+## 步骤9：查询学员进度
+
+```bash
+# 查询学习地图学员列表
+soke-cli learning-map +list-map-users --map-id "MAP-UUID"
+
+# 查询单个学员详情
+soke-cli learning-map +get-map-user \
+  --map-id "MAP-UUID" \
+  --dept-user-id "DEPT-USER-ID"
+
+# 查询阶段学员进度
+soke-cli learning-map +list-stage-users \
+  --map-id "MAP-UUID" \
+  --stage-id "STAGE-UUID"
+```
+
+---
+
+## 可用命令全览
+
+### 学习地图创建（本 skill 新增）
+
+| 命令 | 说明 | 风险 |
+|------|------|------|
+| `learning-map +create-map` | 创建学习地图 | write |
+| `course +category-tree` | 获取课程分类子树 | read |
+| `course +search` | 按分类搜索课程 | read |
+| `learning-map +check-item-status` | 检查课程是否可加入地图 | read |
+| `learning-map +create-stage` | 创建学习地图阶段 | write |
+| `learning-map +publish` | 发布/下架学习地图 | write |
+
+### 学习地图查询
+
+| 命令 | 说明 | 风险 |
+|------|------|------|
+| `+list-categories` | 查询学习地图分类 | read |
+| `+list-maps` | 查询学习地图列表 | read |
+| `+list-stages` | 查询阶段列表 | read |
+| `+list-items` | 查询阶段内容列表 | read |
+
+### 学员进度查询
+
+| 命令 | 说明 | 风险 |
+|------|------|------|
+| `+list-map-users` | 查询地图学员列表 | read |
+| `+list-stage-users` | 查询阶段学员列表 | read |
+| `+list-item-users` | 查询内容学员列表 | read |
+| `+get-map-user` | 查询单个学员详情 | read |
+
+### 指派管理（soke-assign）
+
+| 命令 | 说明 |
+|------|------|
+| `assign +list-departments` | 查询可用部门 |
+| `assign +list-users` | 查询可用用户 |
+| `assign +create` | 创建指派 |
+| `assign +list` | 查询指派记录 |
+
+---
+
+## 调试与故障排除
+
+### 常见错误速查
+
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| `未登录授权` | Token 过期 | `soke-cli auth login` |
+| `分类不存在` | category UUID 无效 | 重新查询 `+list-categories` |
+| `学习地图不存在` | map-id 无效 | 确认创建成功 |
+| `课程不可用` | 课程已在其他地图或未发布 | 检查 `+check-item-status` 返回的 `availabelIds` |
+| `发布失败` | 无阶段或阶段无内容 | 先创建至少 1 个有课程的阶段 |
+| `参数错误` | 必填参数缺失或格式不对 | `soke-cli learning-map <cmd> --help` |
+
+### 调试检查清单
+
+```bash
+# 1. 认证状态
+soke-cli config show
+
+# 2. 确认地图存在
+soke-cli learning-map +list-maps \
+  --start-time 1700000000000 --end-time 1800000000000 --format json | \
+  jq '.data.list[] | select(.uuid=="MAP-UUID")'
+
+# 3. 查询阶段
+soke-cli learning-map +list-stages --map-id "MAP-UUID" --format json | \
+  jq '.data.list | length'
+
+# 4. 确认发布状态（status=1 已发布）
+soke-cli learning-map +list-maps \
+  --start-time 1700000000000 --end-time 1800000000000 --format json | \
+  jq '.data.list[] | select(.uuid=="MAP-UUID") | .status'
+
+# 始终用 --format json 获取结构化输出
+```
+
+---
+
+## 完整示例
+
+```bash
+# === 1. 查询地图分类 ===
+MAP_CATEGORY_ID=$(soke-cli learning-map +list-categories --format json | \
+  jq -r '.data.list[0].uuid')
+
+# === 2. 创建学习地图 ===
+MAP_UUID=$(soke-cli learning-map +create-map \
+  --path "$MAP_CATEGORY_ID" \
+  --title "新员工入职培训" \
+  --type "cycle" \
+  --template "14" \
+  --picture "https://newsokecdn.soke.cn/dingfc5d942826fce9d9/public/image/learning_map/other.png" \
+  --description "<p>新员工入职培训学习地图</p>" \
+  --is-new "1" \
+  --format json | jq -r '.data.info.uuid')
+
+echo "地图 UUID: $MAP_UUID"
+
+# === 3. 查询课程分类子树 ===
+COURSE_CATEGORY_ID=$(soke-cli course +category-tree \
+  --parent-id "COURSE-ROOT-CATEGORY-UUID" \
+  --format json | jq -r '.data[0].uuid')
+
+# === 4. 搜索课程 ===
+COURSES=$(soke-cli course +search \
+  --category-id "$COURSE_CATEGORY_ID" \
+  --format json | jq '.data')
+
+COURSE_UUID=$(echo "$COURSES" | jq -r '.[0].uuid')
+
+# === 5. 检查课程可用性 ===
+AVAILABLE=$(soke-cli learning-map +check-item-status \
+  --map-id "$MAP_UUID" \
+  --course-ids "$COURSE_UUID" \
+  --format json | jq -r '.data.canUse')
+
+if [ "$AVAILABLE" != "true" ]; then
+  echo "课程不可用，请检查"
+  exit 1
+fi
+
+# === 6. 创建阶段（CLI 自动获取课程详情并构建 selectItems）===
+STAGE_UUID=$(soke-cli learning-map +create-stage \
+  --map-id "$MAP_UUID" \
+  --title "阶段1：基础学习" \
+  --item-type "course" \
+  --item-uuids "$COURSE_UUID" \
+  --cycle "7" \
+  --unlock-type "0" \
+  --finish-all "1" \
+  --format json | jq -r '.data.info.uuid')
+
+echo "阶段 UUID: $STAGE_UUID"
+
+# === 7. 发布学习地图 ===
+soke-cli learning-map +publish --uuid "$MAP_UUID"
+
+# === 8. 指派给部门（可选）===
+DEPT_ID=$(soke-cli assign +list-departments --keyword "研发" --format json | \
+  jq -r '.data.list[0].uuid')
+
+soke-cli assign +create \
+  --module "learning_map" \
+  --target-id "$MAP_UUID" \
+  --dept-ids "$DEPT_ID" \
+  --dept-names "研发部" \
+  --learn-type "required"
+
+# === 9. 验证 ===
+soke-cli learning-map +list-maps \
+  --start-time 1700000000000 --end-time 1800000000000 \
+  --format json | jq '.data.list[] | select(.uuid=="'"$MAP_UUID"'")'
+```
+
+---
+
+## API 接口映射
+
+| CLI 命令 | API 路径 | 方法 |
+|----------|----------|------|
+| `learning-map +list-categories` | `/learningMap/category/list` | GET |
+| `learning-map +list-maps` | `/learningMap/learningMap/list` | GET |
+| `learning-map +create-map` | `/skills/learningMap/create` | POST (form) |
+| `course +category-tree` | `/skills/course/category/tree` | GET |
+| `course +search` | `/skills/course/search` | GET |
+| `learning-map +check-item-status` | `/skills/learningMap/item/checkUseStatus` | POST (form) |
+| `learning-map +create-stage` | `/skills/learningMap/stage/create` | POST (form) |
+| `learning-map +publish` | `/skills/learningMap/update/{uuid}` | PUT (form) |
+| `learning-map +list-stages` | `/learningMap/stage/list` | GET |
+| `learning-map +list-items` | `/learningMap/item/list` | GET |
+| `learning-map +list-map-users` | `/learningMap/user/list` | GET |
+| `learning-map +list-stage-users` | `/learningMap/stageUser/list` | GET |
+| `learning-map +list-item-users` | `/learningMap/itemUser/list` | GET |
+| `learning-map +get-map-user` | `/learningMap/user/info` | GET |
+| `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 |
+
+## 权限要求
+
+| 操作 | 权限范围 |
+|------|----------|
+| 学习地图读写 | `learningMap:learningMap:write` / `learningMap:learningMap:readonly` |
+| 指派读写 | `assign:write` / `assign:read` |
+
+## 注意事项
+
+1. **学习地图至少需要 1 个阶段才能发布**
+2. **创建阶段前必须先检查课程可用性**（`+check-item-status`），只将 `data.availabelIds` 中的 UUID 传入 `--item-uuids`
+3. **`--item-type` 和 `--item-uuids` 替代了旧的 `--select-items`**，CLI 自动获取资源详情并构建完整的 `selectItems` 字段，无需手动构造 JSON
+4. **发布后学员才可见**
+5. **指派是可选的**，未指派时学员看不到学习地图
+6. **可以创建多个阶段**，重复步骤6即可
+
+## 相关文档
+
+- [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md) — 认证、配置、权限
+- [`../soke-assign/SKILL.md`](../soke-assign/SKILL.md) — 指派管理
+- [`../../docs/LEARNING_MAP_CREATE.md`](../../docs/LEARNING_MAP_CREATE.md) — 学习地图创建接口文档

package/skills/soke-learning-profile/SKILL.md

@@ -3,7 +3,6 @@ name: soke-learning-profile
 summary: 学员学习档案查询
 version: 1.0.0
 description: "学员学习档案查询：查询学员的完整学习记录，包括课程学习、考试成绩、证书获取、学分积分等。当用户需要查询学员学习档案、查看学员学习情况、统计学员学习数据、查询学员综合学习信息时使用。"
-requiredAuthorizations: [{"platformId":"soke-ai"}]
 metadata:
   requires:
     bins: ["soke-cli"]

package/skills/soke-lesson/README.md

@@ -0,0 +1,53 @@
+# 授客课件管理 Skill
+
+课件生命周期管理，包括基于素材创建课件、查询课件列表和详情、管理课件排序。
+
+## 快速开始
+
+### 创建课件
+
+```bash
+# 步骤1: 上传素材
+soke-cli file +upload --file ./lesson1.mp4
+# 返回: media_id
+
+# 步骤2: 创建课件
+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
+```
+
+### 管理课件
+
+```bash
+# 查询课件列表
+soke-cli course +lesson-list --course-id "COURSE-UUID"
+
+# 获取课件详情
+soke-cli course +lesson-get --lesson-id "LESSON-UUID"
+```
+
+## 主要功能
+
+- ✅ 基于素材创建课件
+- ✅ 查询课件列表
+- ✅ 获取课件详情
+- ✅ 管理课件排序
+- ✅ 支持视频、音频、文档等多种类型
+
+## 课件类型
+
+- **视频课件** (video): 支持 mp4, avi, mov 等格式
+- **音频课件** (audio): 支持 mp3, wav, m4a 等格式
+- **文档课件** (document): 支持 pdf, ppt, doc 等格式
+
+## 详细文档
+
+查看 [SKILL.md](./SKILL.md) 获取完整的使用说明和 API 文档。