@sokeai/cli 1.0.61 → 1.0.62

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

@@ -40,7 +40,7 @@ soke-cli config show  # 验证登录状态
 │ 6. 创建学习地图阶段  →  添加课程内容，获取 stage-uuid                │
 │ 7. 发布学习地图      →  学员可见                                      │
 │ 8. (可选) 指派       →  分配给部门/学员 → 学员开始学习               │
-│ 9. 查询学员进度      →  查看学习状态                                  │
+│ 9. 查询学习地图详情  →  查看地图完整信息                              │
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -83,6 +83,7 @@ soke-cli config show  # 验证登录状态
 | 5 | `+check-item-status` | `data.availabelIds[]` | 步骤6 `--item-uuids`（只传可用 UUID） |
 | 6 | `+create-stage` | `data.info.uuid` | 可创建多个阶段 |
 | 7 | `+publish` | `data.info.status=1` | 发布成功 |
+| 9 | `+detail` | `data.info.*` | 查看完整地图信息 |
 
 ---
 
@@ -132,7 +133,7 @@ soke-cli learning-map +create-map \
 |------|------|------|
 | `--path` | 是 | 所属分类 UUID（步骤1 获取） |
 | `--title` | 是 | 学习地图名称 |
-| `--type` | 是 | `cycle`（周期学习）/ `free`（自由学习） |
+| `--type` | 是 | `fixed`（固定时间）/ `cycle`（周期型） |
 | `--template` | 是 | 模板 ID，如 `14` |
 | `--picture` | 是 | 封面图片 URL |
 | `--description` | 否 | 简介（支持 HTML） |
@@ -321,23 +322,30 @@ soke-cli assign +create \
 
 ---
 
-## 步骤9：查询学员进度
+## 步骤9：查询学习地图详情
 
 ```bash
-# 查询学习地图学员列表
-soke-cli learning-map +list-map-users --map-id "MAP-UUID"
+soke-cli learning-map +detail --uuid "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"
+# JSON 输出：
+soke-cli learning-map +detail --uuid "MAP-UUID" --format json
 ```
 
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--uuid` | 是 | 学习地图 UUID |
+
+**响应关键字段**：
+- `data.info.uuid` → 地图 UUID
+- `data.info.title` → 地图名称
+- `data.info.status` → 状态（`0` 未发布 / `1` 已发布）
+- `data.info.stage_number` → 阶段数量
+- `data.info.learning_num` → 学习人数
+- `data.info.finish_num` → 完成人数
+- `data.info.point` / `data.info.credit` → 积分 / 学分
+
 ---
 
 ## 可用命令全览
@@ -359,6 +367,7 @@ soke-cli learning-map +list-stage-users \
 |------|------|------|
 | `+list-categories` | 查询学习地图分类 | read |
 | `+list-maps` | 查询学习地图列表 | read |
+| `+detail` | 查询学习地图详情 | read |
 | `+list-stages` | 查询阶段列表 | read |
 | `+list-items` | 查询阶段内容列表 | read |
 
@@ -510,6 +519,7 @@ soke-cli learning-map +list-maps \
 | `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 +detail` | `/skills/learningMap/detail/{uuid}` | GET |
 | `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 |

package/skills/soke-learning-map/soke-cli/345/256/211/350/243/205/346/214/207/345/215/227.md

@@ -30,79 +30,102 @@
 
 ## 安装步骤
 
-### 通过 NPM 安装
+> ⚠️ **先看这里**：以下步骤会将 `soke-cli` 安装到用户专属目录（`~/.npm-global`），无需 sudo、不依赖任何 AI 工具，任何终端打开即用。
+> 
+> **三步走：① 改 npm prefix → ② 加 PATH → ③ 安装**
 
-这是推荐的安装方式，简单快捷，适合所有用户。
+### 第一步：配置 npm prefix（所有平台通用）
 
-#### macOS / Linux 安装
-
-打开终端，执行以下命令：
+设置 npm 全局安装路径为用户专属目录，这样：
+- **不需要 sudo/管理员权限**
+- **不会装到奇怪的系统目录**
+- **任何终端都能找到**
 
 ```bash
-npm install -g @sokeai/cli@latest
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
 ```
 
-#### Windows 安装
+> 💡 这一步只需执行一次，之后所有通过 `npm install -g` 安装的工具都会放到统一位置。
 
-**方式一：使用 PowerShell（推荐）**
+---
 
-1. 以管理员身份打开 PowerShell：
-   - 按 `Win + X`，选择"Windows PowerShell (管理员)"
-   - 或在开始菜单搜索"PowerShell"，右键选择"以管理员身份运行"
+### 第二步：把 npm 全局 bin 目录加入 PATH
 
-2. 执行安装命令：
-   ```powershell
-   npm install -g @sokeai/cli@latest
-   ```
+把 `~/.npm-global/bin` 加入 shell 搜索路径，这样终端才能找到 `soke-cli`。
 
-**方式二：使用 CMD 命令提示符**
+#### macOS / Linux
 
-1. 以管理员身份打开命令提示符：
-   - 按 `Win + R`，输入 `cmd`，按 `Ctrl + Shift + Enter`
-   - 或在开始菜单搜索"cmd"，右键选择"以管理员身份运行"
+在 `~/.zshrc`（Zsh）或 `~/.bashrc`（Bash）末尾追加一行：
 
-2. 执行安装命令：
-   ```cmd
-   npm install -g @sokeai/cli@latest
-   ```
+```bash
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
 
-> 💡 **Windows 提示**: 
-> - 如果提示"npm 不是内部或外部命令"，请先安装 [Node.js](https://nodejs.org/)
-> - 安装过程中可能需要管理员权限
-> - 如果遇到权限问题，确保以管理员身份运行终端
+> 💡 **Apple Silicon (M1/M2/M3) 用户**如果用 Homebrew 安装 Node.js，npm prefix 可能已指向 `/opt/homebrew`（arm64）或 `/usr/local`（x64）。上述 `npm config set prefix` 会覆盖默认值，所有全局工具统一走 `~/.npm-global`，不影响 Homebrew 自有工具。
 
----
+#### Windows
+
+**PowerShell**：
+```powershell
+# 查看当前用户 PATH
+[Environment]::GetEnvironmentVariable('Path', 'User')
 
-### 安装过程说明
+# 追加 npm-global 路径
+$npmGlobal = "$env:USERPROFILE\.npm-global\bin"
+[Environment]::SetEnvironmentVariable('Path', "$(([Environment]::GetEnvironmentVariable('Path', 'User') -split ';' -notlike '' -join ';'));$npmGlobal", 'User')
+
+# 验证（需要重新打开 PowerShell 使改动生效，或手动刷新）
+$env:Path = [Environment]::GetEnvironmentVariable('Path', 'User')
+```
 
-无论使用哪个平台，安装过程都是自动化的：
+**CMD**：
+```cmd
+setx PATH "%PATH%;%USERPROFILE%\.npm-global\bin"
+```
 
-1. NPM 会自动下载 `@sokeai/cli` 包
-2. 安装脚本会根据你的操作系统（macOS/Linux/Windows）和架构（x64/arm64）自动下载对应的二进制文件
-3. 二进制文件会被放置在对应的目录：
-   - **macOS/Linux**: `$(npm root -g)/@sokeai/cli/bin/soke-cli`
-   - **Windows**: `%APPDATA%\npm\node_modules\@sokeai\cli\bin\soke-cli.exe`
-4. 如果你安装了 AI Agent（如 Claude Code），相关的 Skills 会自动同步到对应目录
+> ⚠️ **Windows**: `setx` 修改的是**系统环境变量**，需要新的 CMD/PowerShell 窗口才能生效（当前窗口不会变）。
 
 ---
 
-### 验证安装
+### 第三步：安装 soke-cli
 
-安装完成后，验证是否安装成功：
+PATH 配置完成后，新开一个终端窗口（或 `source` 刚改的文件），然后安装：
 
-**macOS / Linux**:
+**macOS / Linux**：
 ```bash
-soke-cli --version
+npm install -g @sokeai/cli@latest
 ```
 
-**Windows (PowerShell / CMD)**:
-```cmd
+**Windows (PowerShell / CMD)**：
+```powershell
+npm install -g @sokeai/cli@latest
+```
+
+> 💡 安装脚本会自动根据操作系统（macOS / Linux / Windows）和芯片架构（x64 / arm64）下载对应二进制文件，无需手动选择。
+
+---
+
+### 安装后验证
+
+新开一个终端（让 PATH 生效），依次执行：
+
+```bash
+# 确认路径
+which soke-cli
+# 预期输出类似: /Users/你的用户名/.npm-global/bin/soke-cli
+
+# 确认版本
 soke-cli --version
+# 预期输出: soke-cli version x.x.x
 ```
 
-如果显示版本号（如 `1.0.15`），说明安装成功。
+如果显示版本号，说明安装成功 ✅。
 
-**如果提示"命令未找到"**，请参考[常见问题](#常见问题)章节。
+**如果 `which soke-cli` 无输出**，说明 PATH 未生效：
+- macOS/Linux: 确认 `echo $PATH | tr ':' '\n' | grep npm-global` 有输出，若没有请重新执行第二步
+- Windows: 确认环境变量中已添加 `C:\Users\你的用户名\.npm-global\bin`
 
 ---
 
@@ -246,51 +269,47 @@ soke-cli exam +list-exams --page 1 --page-size 10
 
 **原因**: 二进制文件不在系统 PATH 中。
 
-**解决方案**:
+**解决方案（重新做安装步骤第二步）**:
 
-**macOS/Linux**:
+**macOS / Linux**：
 ```bash
-# 检查安装位置
+# 确认 npm-global/bin 是否已在 PATH
 which soke-cli
 
-# 如果没有输出，手动创建软链接
-sudo ln -s $(npm root -g)/@sokeai/cli/bin/soke-cli /usr/local/bin/soke-cli
+# 若无输出，检查路径是否存在
+ls ~/.npm-global/bin/soke-cli 2>/dev/null && echo "存在，但 PATH 未生效"
+
+# 重新追加 PATH 并生效
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# 再次验证
+which soke-cli
+soke-cli --version
 ```
 
-**Windows**:
+**Windows**：
+```powershell
+# 检查 .npm-global/bin 是否存在
+Test-Path "$env:USERPROFILE\.npm-global\bin\soke-cli.exe"
 
-1. **检查 NPM 全局路径是否在 PATH 中**
-   
-   打开 PowerShell，执行：
-   ```powershell
-   npm config get prefix
-   ```
-   
-   记下输出的路径（例如：`C:\Users\YourName\AppData\Roaming\npm`）
+# 若存在但命令找不到，手动刷新 PATH
+$env:Path = [Environment]::GetEnvironmentVariable('Path', 'User')
 
-2. **添加到系统 PATH**
-   
-   - 按 `Win + X`，选择"系统"
-   - 点击"高级系统设置"
-   - 点击"环境变量"
-   - 在"用户变量"或"系统变量"中找到 `Path`
-   - 点击"编辑"，添加上面的 NPM 路径
-   - 点击"确定"保存
-
-3. **重启终端**
-   
-   关闭并重新打开 PowerShell 或 CMD，再次尝试：
-   ```cmd
-   soke-cli --version
-   ```
+# 确认
+where.exe soke-cli
+```
 
-**或者使用完整路径运行**:
-```cmd
-# Windows 示例
-%APPDATA%\npm\soke-cli --version
+**直接运行（临时方案，不推荐长期使用）**：
 
-# 或者
-C:\Users\YourName\AppData\Roaming\npm\soke-cli.exe --version
+**macOS / Linux**：
+```bash
+~/.npm-global/bin/soke-cli --version
+```
+
+**Windows**：
+```cmd
+%USERPROFILE%\.npm-global\bin\soke-cli.exe --version
 ```
 
 ### Q3: 登录时浏览器没有自动打开
@@ -394,4 +413,4 @@ npx skills add liuchenlong1111/soke-cli -y -g
 
 ---
 
-**祝你使用愉快！** 🎉
+**祝你使用愉快！** 🎉

package/skills/soke-lesson/SKILL.md

@@ -141,6 +141,31 @@ soke-cli course +lesson-get --lesson-id "LESSON-UUID"
 **返回：**
 - 课件详细信息（包含素材信息、转换状态等）
 
+### 课件排序
+
+#### `course +lesson-sort` - 调整课程课件顺序
+
+按指定顺序重新排列课程下的课件。
+
+**参数：**
+- `--course-id` (必填): 课程 UUID
+- `--sort-list` (必填): 课件 ID 有序列表，多个 ID 用逗号分隔，顺序即为最终显示顺序
+
+**示例：**
+```bash
+# 将两个课件按指定顺序排列
+soke-cli course +lesson-sort \
+  --course-id "F23F32C5-8586-45E5-B98D-5D005FD596B1" \
+  --sort-list "29F629AB-3FF6-4EC0-A7C5-CC6D7124518E,058B89B2-95CA-45EF-9F52-231E58AF2E91"
+```
+
+**返回：**
+- 调整成功提示及课件数量
+
+**说明：**
+- `--sort-list` 中课件 ID 的顺序即为调整后的最终排列顺序
+- 先使用 `course +lesson-list` 查出所有课件 UUID，再按需排列后传入
+
 
 ## 使用场景
 
@@ -248,44 +273,20 @@ soke-cli course +lesson-create \
 soke-cli course +lesson-list --course-id "{course_id}" --format json
 ```
 
-**响应示例**：
-```json
-{
-  "success": true,
-  "data": {
-    "list": [
-      {
-        "uuid": "lesson-123",
-        "title": "第一课",
-        "type": "video",
-        "length": 600,
-        "sort_order": 1
-      }
-    ]
-  }
-}
-```
-
 **获取课件详情**：
 ```
 soke-cli course +lesson-get --lesson-id "{lesson_id}" --format json
 ```
 
-**响应示例**：
-```json
-{
-  "success": true,
-  "data": {
-    "uuid": "lesson-123",
-    "title": "第一课",
-    "type": "video",
-    "length": 600,
-    "media_id": "media-456",
-    "filename": "lesson1.mp4",
-    "filesize": 10485760,
-    "object": "uploads/2024/01/abc123.mp4"
-  }
-}
+**调整课件顺序**：
+```
+# 先查询出所有课件 UUID
+soke-cli course +lesson-list --course-id "{course_id}" --format json
+
+# 按期望顺序传入 UUID 列表（逗号分隔，第一个排在最前）
+soke-cli course +lesson-sort \
+  --course-id "{course_id}" \
+  --sort-list "{lesson_id_1},{lesson_id_2},{lesson_id_3}"
 ```
 
 ## API 接口映射
@@ -295,6 +296,7 @@ soke-cli course +lesson-get --lesson-id "{lesson_id}" --format json
 | `course +lesson-create` | `/skills/course/lesson/create` | POST | 创建课件 |
 | `course +lesson-list` | `/skills/course/lesson/list` | GET | 列出课件列表 |
 | `course +lesson-get` | `/skills/course/lesson/{id}` | GET | 获取课件详情 |
+| `course +lesson-sort` | `/skills/course/lesson/sort/{course_id}` | PUT | 调整课件顺序 |
 | `course +lesson-update` | `/skills/course/lesson/{id}` | PUT | 更新课件信息 |
 ## 课件与素材的关系
 
@@ -481,7 +483,8 @@ soke-cli file +upload --file "lesson.mp4" --format json
 1. **素材必须先上传**: 创建课件前必须先上传素材到素材库
 2. **类型匹配**: 课件类型必须与素材类型匹配
 3. **时长设置**: 视频和音频必须设置正确的时长，文档类型填 0
-4. **排序规则**: 课件按创建时间自动排序，也可以手动调整 `sort_order`
+4. **排序规则**: 课件按创建时间自动排序，可通过 `course +lesson-sort` 手动调整顺序
+5. **排序需覆盖全部课件**: 调用 `+lesson-sort` 时建议传入课程下所有课件的 UUID，避免遗漏
 6. **发布要求**: 课程至少需要一个课件才能发布
 
 ## 权限要求