@sokeai/cli 1.0.77 → 1.0.79

package/skills/{soke-exam/SKILL.md → mono/references/modules/soke-exam/MODULE.md}

@@ -11,7 +11,7 @@ metadata:
 
 # 考试管理 (exam)
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理**
 
 ## 核心概念
 

package/skills/{soke-learning-map/SKILL.md → mono/references/modules/soke-learning-map/MODULE.md}

@@ -12,7 +12,7 @@ metadata:
 
 # 学习地图管理 (soke-learning-map)
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`./soke-cli安装指南.md`](./soke-cli安装指南.md)，其中包含认证、配置、权限处理**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../../../references/installation.md`](../../../references/installation.md)，其中包含认证、配置、权限处理**
 
 ## 使用前提
 
@@ -289,7 +289,7 @@ soke-cli learning-map +publish --uuid "MAP-UUID" --status "0"
 
 ## 步骤8：指派学习地图（可选）
 
-> 详见 [`../soke-assign/SKILL.md`](../soke-assign/SKILL.md)
+> 详见 [`../soke-assign/MODULE.md`](../soke-assign/MODULE.md)
 
 发布后指派给部门或学员，学员才能看到并开始学习。
 
@@ -380,7 +380,7 @@ soke-cli learning-map +detail --uuid "MAP-UUID" --format json
 | `+list-item-users` | 查询内容学员列表 | read |
 | `+get-map-user` | 查询单个学员详情 | read |
 
-学员统计导出任务使用独立模块：`soke-cli task +create` / `soke-cli task +get`，详见 [`../soke-task/SKILL.md`](../soke-task/SKILL.md)。
+学员统计导出任务使用独立模块：`soke-cli task +create` / `soke-cli task +get`，详见 [`../soke-task/MODULE.md`](../soke-task/MODULE.md)。
 
 ### 指派管理（soke-assign）
 
@@ -551,6 +551,5 @@ soke-cli learning-map +list-maps \
 
 ## 相关文档
 
-- [`../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) — 学习地图创建接口文档
+- [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md) — 认证、配置、权限
+- [`../soke-assign/MODULE.md`](../soke-assign/MODULE.md) — 指派管理

package/skills/{soke-learning-profile/SKILL.md → mono/references/modules/soke-learning-profile/MODULE.md}

@@ -9,7 +9,7 @@ metadata:
   cliHelp: "soke-cli learning-profile --help"
 ---
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理**
 
 ## 核心概念
 
@@ -207,7 +207,7 @@ soke-cli learning-profile +list --page-size 100 --format json > learning_profile
 ## 错误处理
 
 ### 权限不足
-如果遇到权限错误，参考 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)
+如果遇到权限错误，参考 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)
 
 ### 参数错误
 使用 `--help` 查看命令参数说明：

package/skills/mono/references/modules/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](./MODULE.md) 获取完整的使用说明和 API 文档。

package/skills/mono/references/modules/soke-material/README.md

@@ -0,0 +1,49 @@
+# 授客素材库管理 Skill
+
+素材库文件管理，包括文件上传到OSS、创建素材记录、查询素材列表和详情、管理素材分类。
+
+## 快速开始
+
+### 上传文件到素材库
+
+```bash
+# 自动检测类型和时长
+soke-cli file +upload --file ./video.mp4
+
+# 指定类型和时长
+soke-cli file +upload --file ./audio.mp3 --type audio --length 236
+```
+
+### 查询素材
+
+```bash
+# 列出所有素材
+soke-cli file +list-files
+
+# 列出视频素材
+soke-cli file +list-files --type video
+
+# 获取素材详情
+soke-cli file +get-info --file-id "FILE-UUID"
+```
+
+## 主要功能
+
+- ✅ 文件上传到 OSS（自动获取签名）
+- ✅ 创建素材库记录
+- ✅ 查询素材列表（支持类型和分类筛选）
+- ✅ 获取素材详情
+- ✅ 管理素材分类
+- ✅ 自动检测文件类型
+- ✅ 自动设置默认时长
+
+## 支持的文件类型
+
+- **视频**: mp4, avi, mov, wmv, flv, mkv, webm 等
+- **音频**: mp3, wav, flac, aac, ogg, wma, m4a 等
+- **图片**: jpg, jpeg, png, gif, bmp, svg, webp 等
+- **文档**: pdf, ppt, pptx, doc, docx, xls, xlsx 等
+
+## 详细文档
+
+查看 [SKILL.md](./MODULE.md) 获取完整的使用说明和 API 文档。

package/skills/{soke-photo-gallery/SKILL.md → mono/references/modules/soke-photo-gallery/MODULE.md}

@@ -11,7 +11,7 @@ metadata:
 
 # 图片库管理 (soke-photo-gallery)
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理**
 
 ## 使用前提
 
@@ -283,5 +283,4 @@ soke-cli photo-gallery +list --format json
 
 ## 相关文档
 
-- [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md) — 认证、配置、权限
-- [`../../docs/photo-gallery-api.md`](../../docs/photo-gallery-api.md) — 图片库接口文档
+- [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md) — 认证、配置、权限

package/skills/mono/references/modules/soke-supervisor/MODULE.md

@@ -0,0 +1,186 @@
+---
+name: soke-supervisor
+summary: 授客 AI 督导模块：督导场景创建、评分标准配置、指派、发布、详情查询和关闭
+version: 1.0.0
+description: "授客 AI 督导模块：通过 soke-cli supervisor 对接督导场景接口，覆盖场景列表、创建草稿、选择评分标准、更新配置、部门/成员查询、创建指派、发布、详情、关闭前检查和关闭。当用户需要创建或维护 AI 督导场景、配置督导评分标准、给用户或部门指派督导任务、发布或关闭督导场景时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli supervisor --help"
+---
+
+# AI 督导模块 (supervisor)
+
+**CRITICAL — 开始前 MUST 先读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理。**
+
+## 核心概念
+
+- **Supervisor Scenario（督导场景）**：AI 督导配置主体，通过 `scenario_id` 标识。
+- **Scoring Criteria（评分标准）**：督导评分模板或自定义评分维度。选择模板后，取 `data.list[].id` 作为 `template_id`，并复用其 `dimensions[]` 组装更新请求。
+- **Assignment（指派）**：将督导场景分配给用户或部门，`type=user` 时目标是 `user_id`，`type=department` 时目标是部门 `id`。
+- **Resource Check（关闭前检查）**：关闭前必须先检查 `resource_type=ai_supervisor`、`resource_id=scenario_id`，仅当 `data.can_operate=true` 才允许关闭。
+
+## 命令总览
+
+| 命令 | 说明 |
+|---|---|
+| `soke-cli supervisor +list-scenarios` | 查询督导场景列表 |
+| `soke-cli supervisor +create-scenario` | 创建督导场景草稿 |
+| `soke-cli supervisor +list-scoring-criteria` | 查询评分标准模板 |
+| `soke-cli supervisor +update-scenario` | 更新场景信息并设置评分标准 |
+| `soke-cli supervisor +list-assigns` | 查询场景已有指派 |
+| `soke-cli supervisor +list-department-children` | 查询可指派部门 |
+| `soke-cli supervisor +list-department-members` | 查询部门成员 |
+| `soke-cli supervisor +assign-scenario` | 创建用户/部门指派 |
+| `soke-cli supervisor +publish-scenario` | 发布督导场景 |
+| `soke-cli supervisor +get-scenario` | 查询督导场景详情 |
+| `soke-cli supervisor +check-resource` | 关闭前检查 |
+| `soke-cli supervisor +close-scenario` | 关闭督导场景 |
+
+默认输出格式化后的 `data` JSON；需要关闭缩进时使用 `--pretty=false`，排障时加 `--raw` 查看完整 `{code,status,message,data,request_id}`。
+
+## 推荐创建流程
+
+1. 创建草稿：
+
+```bash
+soke-cli supervisor +create-scenario \
+  --name "电话服务质检督导" \
+  --description "用于检查客服录音中的关键服务动作" \
+  --key-points "开场确认身份；倾听客户诉求；给出清晰处理方案；合规结束" \
+  --pretty
+```
+
+记录返回的 `data.id` 作为 `scenario_id`。
+
+2. 查询评分标准：
+
+```bash
+soke-cli supervisor +list-scoring-criteria --page 1 --page-size 10 --pretty
+```
+
+选择模板时，保存 `data.list[].id` 和该模板的 `dimensions[]`。
+
+3. 更新场景和评分配置：
+
+```bash
+soke-cli supervisor +update-scenario \
+  --scenario-id "<scenario_id>" \
+  --name "电话服务质检督导" \
+  --description "用于检查客服录音中的关键服务动作" \
+  --key-points "开场确认身份；倾听客户诉求；给出清晰处理方案；合规结束" \
+  --status 0 \
+  --template-id "<template_id>" \
+  --template-name "金融贷款评分标准" \
+  --template-version "1.0" \
+  --criteria-name "电话服务质检评分标准" \
+  --criteria-description "电话服务质检评分标准" \
+  --criteria-dimension-name "合规表达" \
+  --criteria-dimension-description "表达是否合规" \
+  --criteria-dimension-weight 100 \
+  --criteria-dimension-rule "符合则得分" \
+  --criteria-dimension-sort-order 1 \
+  --pretty
+```
+
+4. 指派前查重：
+
+```bash
+soke-cli supervisor +list-assigns \
+  --scenario-id "<scenario_id>" \
+  --page 1 \
+  --page-size 50 \
+  --pretty
+```
+
+检查 `target_id`、`assign_type`、`status`，避免重复指派。
+
+5. 查询部门和成员：
+
+```bash
+soke-cli supervisor +list-department-children --corp-id "<corp_id>" --pretty
+
+soke-cli supervisor +list-department-members \
+  --department-id "<department_id>" \
+  --corp-id "<corp_id>" \
+  --page 1 \
+  --page-size 50 \
+  --pretty
+```
+
+6. 创建指派：
+
+```bash
+# 指派用户
+soke-cli supervisor +assign-scenario \
+  --scenario-id "<scenario_id>" \
+  --type user \
+  --target-ids "user_id_1,user_id_2" \
+  --pretty
+
+# 指派部门
+soke-cli supervisor +assign-scenario \
+  --scenario-id "<scenario_id>" \
+  --type department \
+  --target-ids "department_id_1" \
+  --pretty
+```
+
+7. 发布并验收：
+
+```bash
+soke-cli supervisor +publish-scenario --scenario-id "<scenario_id>" --pretty
+
+soke-cli supervisor +get-scenario --scenario-id "<scenario_id>" --pretty
+```
+
+发布后检查 `status`、`status_text`、`scoring_criteria_config`。
+
+## 关闭流程
+
+关闭前必须先检查：
+
+```bash
+soke-cli supervisor +check-resource --scenario-id "<scenario_id>" --pretty
+```
+
+只有当 `data.can_operate=true` 时才执行：
+
+```bash
+soke-cli supervisor +close-scenario --scenario-id "<scenario_id>" --pretty
+```
+
+如果 `can_operate=false`，根据 `block_message` 和 `bind_maps` 处理阻塞关系，不要强行关闭。
+
+## JSON 请求文件
+
+### 创建草稿
+
+```json
+{
+  "name": "电话服务质检督导",
+  "description": "用于检查客服录音中的关键服务动作",
+  "key_points": "开场确认身份；倾听客户诉求；给出清晰处理方案；合规结束",
+  "status": 0
+}
+```
+
+### 创建指派
+
+```json
+{
+  "scenario_id": "<scenario_id>",
+  "assignments": [
+    {
+      "type": "user",
+      "target_ids": ["<user_id>"]
+    }
+  ]
+}
+```
+
+## 排错
+
+- 查部门成员时无数据：确认 `--corp-id` 与部门所属企业一致，并使用 `+list-department-children` 返回的部门 `id`。
+- 发布后详情无评分配置：重新检查 `+update-scenario` 的 `scoring_criteria_config.criteria_data.dimensions` 是否为空。
+- 关闭被阻塞：先查看 `+check-resource --raw --pretty` 中的 `block_message` 和 `bind_maps`。

package/skills/mono/references/modules/soke-task/MODULE.md

@@ -0,0 +1,146 @@
+---
+name: soke-task
+summary: 授客学堂异步任务管理（创建统计任务/查询任务状态/获取报表文件），支持学习地图和课程学员统计的报表导出与统计生成，通过 soke-cli 操作
+version: 1.1.0
+description: "授客学堂异步任务管理：通过 soke-cli task 创建统计任务、查询任务状态、获取导出文件。支持学习地图学员统计和课程学员统计的报表导出与统计生成。当用户需要生成学习地图或课程学员统计报表、生成统计、查询任务状态或获取文件下载地址时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli task --help"
+---
+
+# 异步任务管理 (soke-task)
+
+**CRITICAL — 开始前 MUST 先读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置和权限处理。**
+
+## 核心规则
+
+- 任务接口是独立模块，命令统一使用 `soke-cli task ...`，不要使用 `soke-cli learning-map ...` 创建或查询任务。
+- 创建任务后必须保存返回的 `data.id`，再调用 `+get` 查询任务详情。
+- 默认用 `--format json` 获取结构化输出；需要人工快速查看时可省略 format 输出表格。
+- 当前已知任务类型是学习地图学员统计和课程学员统计；`--module` 默认 `learningMapUser`，课程学员统计使用 `--module courseUser`。
+- `--target-id` 是统一目标 ID：`--module learningMapUser` 时会提交为 `学习地图id`，`--module courseUser` 时会提交为 `课程id`。
+- `--departments` 和 `--users` 可传英文逗号分隔 ID 或 JSON 数组；CLI 会转换为接口需要的对象数组。
+- `--action` 默认 `export`，`--type` 默认 `aloneDept`。
+- 查询 `soke-cli task +get --id "TASK-ID"` 后，必须根据创建任务时传入的 `--action` 判断状态字段：`action=export` 看 `data.export_status`，`action=report` 看 `data.status`。
+
+## 命令
+
+### 创建学习地图学员统计任务
+
+```bash
+soke-cli task +create \
+  --target-id "MAP-UUID" \
+  --learn-type "required" \
+  --type "aloneDept" \
+  --departments "130110584" \
+  --users "1302105847786" \
+  --custom-tags "job_number,position" \
+  --limit 4500 \
+  --format json
+```
+
+### 创建课程学员统计任务
+
+```bash
+soke-cli task +create \
+  --target-id "COURSE-UUID" \
+  --module courseUser \
+  --learn-type "required" \
+  --type "aloneDept" \
+  --departments '[130110584]' \
+  --users '[1302105847786]' \
+  --limit 4500 \
+  --format json
+```
+
+完整参数：
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--target-id` | 是 | - | 目标 UUID；`learningMapUser` 时作为 `map_id`，`courseUser` 时作为 `course_id` |
+| `--module` | 否 | `learningMapUser` | 任务模块：`learningMapUser` 学习地图学员统计，`courseUser` 课程学员统计 |
+| `--learn-type` | 否 | `required` | 学习类型，如 `required` |
+| `--learn-status` | 否 | 空 | 学习状态筛选：空值表示不限，`learning` 未完成，`finished` 已完成 |
+| `--eligible-status` | 否 | 空 | 达标状态筛选，空值表示不限 |
+| `--limit` | 否 | `4500` | 任务处理上限 |
+| `--action` | 否 | `export` | 操作类型：`export` 生成报表，`report` 生成统计 |
+| `--type` | 否 | `aloneDept` | 部门导出类型：`aloneDept` 单列导出，`manyDept` 部门多列导出 |
+| `--is-leave` | 否 | `0` | 是否离职：`0` 否，`1` 是 |
+| `--taskId` | 否 | 空字符串 | 任务 ID，默认空字符串 |
+| `--departments` | 否 | 空 | 部门 ID 列表，多个 ID 用英文逗号分隔；也可传 JSON 数组 |
+| `--users` | 否 | 空 | 用户 ID 列表，多个 ID 用英文逗号分隔；也可传 JSON 数组 |
+| `--custom-tags` | 否 | 空 | 导出的自定义字段列表，多个字段用英文逗号分隔；也可传 JSON 字符串数组 |
+
+响应关键字段：
+
+| 字段 | 说明 |
+|------|------|
+| `data.id` | 任务 ID，查询任务详情时传给 `+get --id` |
+| `data.key` | 任务去重或配置缓存 Key |
+| `data.config_result` | 上游配置模块检查结果 |
+
+默认输出会打印单行任务 ID，例如 `id:13288419`。需要完整字段时使用 `--format json`。
+
+### 查询异步任务
+
+```bash
+soke-cli task +get --id "TASK-ID" --format json
+```
+
+状态判断规则：
+
+| 创建任务时的 `--action` | 查询完成状态字段 | 说明 |
+|-------------------------|------------------|------|
+| `export` | `data.export_status` | 生成报表时用导出状态判断是否生成文件 |
+| `report` | `data.status` | 生成统计时用任务执行状态判断是否完成 |
+
+响应关键字段：
+
+| 字段 | 说明 |
+|------|------|
+| `data.status` | 任务执行状态；`action=report` 生成统计时用此字段判断任务状态，接口示例中 `2` 表示执行完成 |
+| `data.export_status` | 导出状态；`action=export` 生成报表时用此字段判断导出状态，接口示例中 `2` 表示已生成导出文件 |
+| `data.filePath` | 导出文件访问地址，未生成时为空 |
+| `data.filename` | 导出文件名 |
+| `data.filesize` | 导出文件大小 |
+| `data.params` | 创建任务参数的 JSON 字符串 |
+
+## 推荐工作流
+
+```bash
+TASK_ID=$(soke-cli task +create \
+  --target-id "$MAP_UUID" \
+  --learn-type "required" \
+  --type "aloneDept" \
+  --custom-tags "工号,岗位,入职日期" \
+  --limit 4500 \
+  --format json | jq -r '.data.id')
+
+soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.filePath'
+```
+
+按创建任务的 action 查询状态：
+
+```bash
+# action=export
+soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.export_status'
+
+# action=report
+soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.status'
+```
+
+## API 接口映射
+
+| CLI 命令 | API 路径 | 方法 |
+|----------|----------|------|
+| `task +create` | `/skills/job/task` | POST (form) |
+| `task +get` | `/skills/job/task/{id}` | GET |
+
+## 排错
+
+- `data.filePath` 为空：任务可能还未完成，等待后重新执行 `task +get --id "TASK-ID" --format json`。
+- `未登录授权`：按 `soke-shared` 执行 `soke-cli auth login` 后重试。
+- 自定义字段没有导出：确认已通过 `--custom-tags "字段1,字段2"` 指定，字段名需与当前任务类型支持的自定义字段一致。
+- 任务创建失败：确认 `--target-id` 与 `--module` 匹配；学习地图用 `--module learningMapUser`，课程用 `--module courseUser`。
+- 部门或用户筛选无效：先用 `soke-cli assign +list-departments` / `soke-cli assign +list-users` 确认可用 ID，再传给 `--departments` / `--users`。

package/skills/{soke-training-demand/SKILL.md → mono/references/modules/soke-training-demand/MODULE.md}

@@ -17,7 +17,7 @@ metadata:
 
 # 培训需求收集
 
-**CRITICAL — 开始前 MUST 先读取 ../soke-shared/SKILL.md，其中包含认证、配置和权限处理。**
+**CRITICAL — 开始前 MUST 先读取 ../soke-shared/MODULE.md，其中包含认证、配置和权限处理。**
 
 ## 🛑 执行守卫（EXECUTION GUARD）