@sokeai/cli 1.0.64 → 1.0.66

package/skills/soke-course/SKILL.md

@@ -1,507 +1,400 @@
 ---
 name: soke-course
-summary: 授客学堂课程管理（课程创建/更新/发布/查询），集成素材库和课件管理子 skills，完整管理课程生命周期
-version: 4.0.0
-description: "授客学堂课程管理：完整的课程生命周期管理，包括创建课程分类、上传文件（素材）、创建课件、创建课程、指派部门/学员、查询学员学习状态的全链路流程。集成 soke-material（素材库管理）、soke-lesson（课件管理）、soke-assign（指派管理）子 skills。当用户需要创建课程、上传课件、指派学员、查询学习进度时使用。"
-metadata:
-  requires:
-    bins: ["soke-cli"]
-    skills: ["soke-material", "soke-lesson", "soke-assign"]
-  cliHelp: "soke-cli course --help"
+version: 5.0.0
+description: >
+  线上课创建与发布的端到端编排技能，课程发布主管。
+  负责识别用户意图、选择执行流程、校验前置条件、调度 3 个并列技能完成全链路操作。
+  当用户想创建课程、上传课件、配置设置、发布课程、指派学员时触发。
+author: Soke Team
+tags: [课程管理, 流程编排, 发布管理]
 ---
 
-# 课程管理 (soke-course)
+# 课程发布主管
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`./soke-cli安装指南.md`](./soke-cli安装指南.md)，其中包含认证、配置、权限处理**
+> **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`./soke-cli安装指南.md`](./soke-cli安装指南.md)，其中包含认证、配置、权限处理。**
 
-## 使用前提
-
-1. 已安装 `soke-cli`
-2. 已登录授权: `soke-cli auth login`
-
-```bash
-soke-cli auth login
-soke-cli config show  # 验证登录状态
-```
+## 交互规范（必须遵守）
 
-## 端到端工作流
+**任何需要用户从固定选项中做选择的场景，必须调用 `ask_user_question` 工具弹窗，禁止纯文本罗列让用户打字。**
 
-完整创建一门可学习的课程需要以下步骤：
+适用场景：
+- 选择课程分类（列出所有分类，最后一项为"🆕 新建分类"）
+- 歧义消解（不确定用户想做什么时）
+- 确认是否继续（"还要加课件吗？"/"调顺序吗？"/"确认发布？"）
+- 选择发布对象（部门/用户列表）
+- 中断恢复（从已有课程列表中选择继续哪个）
+- 任何其他有 2-4 个固定选项的决策点
 
+弹窗标准格式：
 ```
-┌──────────────────────────────────────────────────────────────────┐
-│ 1. 查询课程分类  →  获取 category-id                             │
-│ 2. 创建课程      →  获取 course-id                               │
-│ 3. 上传素材      →  获取 media-id + 所有文件信息                  │
-│ 4. 创建课件      →  关联素材到课程 (至少 1 个)                    │
-│ 5. (可选)更新课程 → 补充描述等                                    │
-│ 6. 发布课程      →  学员可见                                       │
-│ 7. (可选)指派    →  分配给部门/学员 → 学员开始学习                  │
-│ 8. 查询学习状态  →  查看学员进度/完成率                            │
-└──────────────────────────────────────────────────────────────────┘
+ask_user_question
+  question: "选择课程分类"
+  header: "分类"
+  options:
+    - label: "📁 技术研发"  description: "一级分类"
+    - label: "📁 企业管理"  description: "一级分类"
+    - label: "🆕 新建分类"  description: "前往管理后台新建分类"
 ```
 
-### 数据流转图
-
-```
-分类查询                    素材上传 (file +upload)
-  │                           │
-  ▼                           ▼
-category-id              media-id, filename, filesize, object, ext, type
-  │                           │
-  ▼                           ▼
-创建课程 ──→ course-id ──→ 创建课件 (course +lesson-create) ──→ lesson-id
-                                │
-                                ▼
-                          发布课程 ◄── 课件数量 ≥ 1
-                                │
-                                ▼
-                          指派给学员 ◄── assign +create (可选)
-                                │
-                                ▼
-                          学员可开始学习
-                                │
-                                ▼
-                          查询学习记录/进度
-```
-
----
+## 使用前提
 
-## 步骤1: 查询课程分类
+1. 已安装 `soke-cli`
+2. 已登录授权 — 首次执行时自动检查并引导登录
 
-创建课程前必须先获取分类 ID。
+**登录状态检查与自动登录（必须执行）：**
 
 ```bash
-soke-cli course +list-categories --page 1 --page-size 100
-
-# JSON 输出供解析:
-soke-cli course +list-categories --format json
+# 第一步：检查登录状态
+soke-cli config show
 ```
 
-**响应关键字段**:
-- `data.list[].uuid` → 分类 ID（创建课程时传入 `--category-id`）
-- `data.list[].title` → 分类名称
-- `data.list[].parent_id` → 父分类 ID
+若返回包含 `user_token` → ✅ 已登录，继续。
 
----
-
-## 步骤2: 创建课程
+若返回无 `user_token` 或报错 → ⚠️ 未登录，立即执行：
 
 ```bash
-soke-cli course +create \
-  --title "课程标题" \
-  --category-id "CATEGORY-UUID" \
-  --description "课程描述（可选）"
-
-# JSON 输出:
-soke-cli course +create --title "标题" --category-id "CATEGORY-UUID" --format json
+# 第二步：自动打开浏览器完成 OAuth 授权
+# soke-cli auth login 会自动调用系统默认浏览器打开授权页面
+soke-cli auth login
 ```
 
-**参数**:
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--title` | 是 | 课程标题 |
-| `--category-id` | 是 | 分类 ID（从步骤1获取） |
-| `--description` | 否 | 课程描述 |
+`soke-cli auth login` 执行后会自动打开浏览器到授客AI开放平台授权页，用户在浏览器中完成登录授权即可。授权成功后 CLI 终端会显示 `✅ 已登录`，Token 自动保存至 `~/.soke-cli/config.json`。
 
-**响应提取**: `data.uuid` → 课程 ID (`course-id`)
+> 如果浏览器没有自动打开，终端会输出授权链接，手动复制到浏览器打开即可完成授权。
 
----
+**任何课程操作之前，必须先通过上述两步确认登录状态。未登录时禁止跳过，必须完成登录后再继续。**
 
-## 步骤3: 上传素材文件
+## 一、触发描述
 
-> 详见 [`../soke-material/SKILL.md`](../soke-material/SKILL.md)
+### 触发词
 
-```bash
-# 自动检测文件类型和时长
-soke-cli file +upload --file "./video.mp4"
+| 意图 | 触发词 |
+|------|--------|
+| 创建课程 | 创建/新建/做课/开课/生成课程 |
+| 课件管理 | 添加课件/加视频/加音频/加文档/课件排序/调顺序 |
+| 课程设置 | 设置学分/积分/讲师/封面/标签/修改分类/简介 |
+| 高级设置 | 倍速/人脸/提醒/学习模式/解锁/评价/证书/签名/钉钉群 |
+| 收费设置 | 收费/价格/试看/免费/付费 |
+| 发布 | 发布/上线/定时发布/审批 |
+| 指派 | 指派/安排学习/分配学员/必修/选修 |
+| 查询 | 学习进度/完成率/谁学了/谁完成 |
+| 维护 | 关闭/删除/下架/复制/克隆 |
+| 分类管理 | 分类/课程分类/添加分类/新建分类 |
 
-# 指定类型和时长
-soke-cli file +upload --file "./audio.mp3" --type audio --length 236
+### 上下文触发
+- 对话已有 course-id → 在当前课程上操作，不创建新课程
+- 用户上传文件 + 提"课件"/"课程" → 课件子流程
 
-# JSON 输出
-soke-cli file +upload --file "./video.mp4" --format json
-```
+### 不触发（交给独立 skill）
+- 纯考试/题库/试卷
+- 学习地图
+- 纯素材浏览（不提课程）
+- 单查学员档案（无课程上下文）
 
-**响应关键字段（全部用于步骤4创建课件）**:
-| 字段 | 用途 | 说明 |
-|------|------|------|
-| `data.uuid` | `--media-id` | 素材 UUID |
-| `data.filename` | `--filename` | 文件名 |
-| `data.filesize` | `--filesize` | 文件大小（字节） |
-| `data.object` | `--object` | OSS 对象路径 |
-| `data.ext` | `--ext` | 文件扩展名 |
-| `data.type` | `--type` | 文件类型 |
+## 二、输入要求
 
-**时长默认值**: video→600s, audio→300s, 其他→0s
+### 创建课程
+  必填: 课程标题 + 课程分类
+  可选: 描述/学分/讲师/标签/封面
 
----
+### 添加课件
+  必填: 课件内容（文件路径或文本）
+  从上下文获取: course-id
 
-## 步骤4: 创建课件
+### 发布
+  从上下文获取: course-id
+  前置: Gate Check 全部通过
 
-> 详见 [`../soke-lesson/SKILL.md`](../soke-lesson/SKILL.md)
+### 指派
+  必填: 部门名或用户名 + course-id
 
-```bash
-soke-cli course +lesson-create \
-  --course-id "COURSE-UUID" \
-  --title "第一课" \
-  --media-id "MATERIAL-UUID" \
-  --type "video" \
-  --length 600 \
-  --object "uploads/20260601/video.mp4" \
-  --filename "video.mp4" \
-  --ext "mp4" \
-  --filesize 10485760 \
-  --sort 0
-```
-
-**参数来源映射**:
-| 参数 | 必填 | 来源 |
-|------|------|------|
-| `--course-id` | 是 | 步骤2 `data.uuid` |
-| `--title` | 是 | 自定义标题 |
-| `--media-id` | 是 | 步骤3 `data.uuid` |
-| `--type` | 是 | 步骤3 `data.type` |
-| `--length` | 否 | 媒体时长（秒） |
-| `--object` | 否 | 步骤3 `data.object` |
-| `--filename` | 否 | 步骤3 `data.filename` |
-| `--ext` | 否 | 步骤3 `data.ext` |
-| `--filesize` | 否 | 步骤3 `data.filesize` |
-| `--sort` | 否 | 排序值（默认 0） |
+## 三、执行流程
 
-**关键原则**: 课件参数全部从 `file +upload` 响应提取，无需手动填写。
+### 3.1 意图路由
 
-### 批量上传文件
-
-```bash
-FILES=("lesson1.mp4" "lesson2.mp4" "handout.pdf")
-
-for file in "${FILES[@]}"; do
-  RESULT=$(soke-cli file +upload --file "$file" --format json)
-  MEDIA_ID=$(echo "$RESULT" | jq -r '.data.uuid')
-  FILE_TYPE=$(echo "$RESULT" | jq -r '.data.type')
-  FILE_NAME=$(echo "$RESULT" | jq -r '.data.filename')
-  FILE_SIZE=$(echo "$RESULT" | jq -r '.data.filesize')
-  OBJECT=$(echo "$RESULT" | jq -r '.data.object')
-  EXT=$(echo "$RESULT" | jq -r '.data.ext')
-
-  LENGTH=0
-  [[ "$FILE_TYPE" == "video" ]] && LENGTH=600
-  [[ "$FILE_TYPE" == "audio" ]] && LENGTH=300
-
-  TITLE=$(basename "$file" | sed 's/\.[^.]*$//')
-
-  soke-cli course +lesson-create \
-    --course-id "$COURSE_ID" --title "$TITLE" \
-    --media-id "$MEDIA_ID" --type "$FILE_TYPE" --length "$LENGTH" \
-    --object "$OBJECT" --filename "$FILE_NAME" --ext "$EXT" --filesize "$FILE_SIZE"
-done
 ```
-
----
-
-## 步骤5: 更新课程（可选）
-
-```bash
-soke-cli course +update \
-  --course-id "COURSE-UUID" \
-  --title "新标题" \
-  --description "课程描述"
+用户消息 → 关键词 → 意图 → 路由
+
+create       → 3.2 全流程创建
+add_lesson   → 3.3 课件子流程
+settings     → 3.4 设置子流程（→ read references/subs/settings/SOP.md）
+publish      → 3.5 发布子流程（→ read references/subs/publish/SOP.md）
+assign       → 3.6 指派子流程
+query        → 3.7 查询子流程（→ read references/subs/query/SOP.md）
+maintain     → 3.8 维护子流程
+category     → read references/subs/category/SOP.md
 ```
 
----
+歧义消解: 上下文有 course-id → 当前课程操作 | 有文件附件 → 倾向课件 | 不确定 → `ask_user_question` 弹窗列出可能的操作让用户点选（如"创建课程"/"添加课件"/"修改设置"）
+
+### 3.2 全流程创建（主链路）
+
+> 完整 SOP 见 references/sop-full-workflow.md
+
+#### Phase 1: 创建课程骨架
+
+Step 1.1 权限检查（自动登录）
+  exec: soke-cli config show
+  → 有 user_token → ✅ 跳过登录
+  → 无 user_token → exec: soke-cli auth login（自动打开浏览器）
+    等待用户在浏览器中完成授权
+    再次 exec: soke-cli config show 确认 user_token 已写入
+  登录完成 → 继续下一步
+
+Step 1.2 获取分类
+  → read references/subs/category/SOP.md 执行
+  执行: soke course +list-categories 获取分类树
+  策略:
+    1. 用户已指定分类名 → 精确/模糊匹配到唯一结果 → 直接使用
+    2. 匹配到多个结果 → `ask_user_question` 弹窗让用户选一个，最后加一项"🆕 新建分类"
+    3. 用户未指定 → `ask_user_question` 弹窗列出所有一级分类，最后加一项"🆕 新建分类"
+    4. 用户说"随便" → 取第一个一级分类
+  → 用户选"🆕 新建分类" → 告知："CLI 暂不支持新建分类，请前往管理后台 → 课程管理 → 分类设置 → 新增分类" → 新建完成后说"分类建好了"再继续
+  提取: category-id → 存上下文
+
+Step 1.3 创建课程
+  自身: course +create --title "xxx" --category-id "xxx"
+  提取: course-id → 存上下文
+
+Step 1.4 选择模板（创建课程后立即触发）
+  → read references/subs/template/SOP.md 执行
+  弹窗: `ask_user_question` 列出 7 个模板（含"7. 不选择模板"）
+  用户选 1-6 → 输出该模板的配置清单（标注后台路径） → 确认后继续
+  用户选 7 → 不输出配置，直接进入路由弹窗
+  详见: references/subs/template/SOP.md
+
+Gate 1→2: ✅ 有 course-id
+
+Phase 1 完成后 → `ask_user_question` 弹窗: "下一步？" → ["添加课件"/"先做设置"/"直接发布"]
+  选"添加课件" → 进入 Phase 2
+  选"先做设置" → 跳到 Phase 3
+  选"直接发布" → 跳到 Phase 4（需通过 Gate Check）
+
+#### Phase 2: 构建课件
+
+Step 2.1 选择素材来源
+  → `ask_user_question` 弹窗: "从哪儿添加课件素材？" → ["📁 本地上传"/"📚 素材库选择"]
+  选"本地上传" → 进入 Step 2.2
+  选"素材库选择" → 进入 Step 2.2b
 
-## 步骤6: 发布课程
+Step 2.2 本地上传
+  可上传: 视频(.mp4/.avi/.mov/.mkv/.webm)、音频(.mp3/.wav/.ogg/.flac/.aac)、文档(.pdf/.ppt/.pptx/.doc/.docx/.xls/.xlsx)
+  ⚠️ 不支持 CLI: 图片/文章/外链/小测验/作业 → 告知后台路径
+  → 用户提供本地文件路径
+  → 调度 soke-material: file +upload（自动根据扩展名判断类型）
+  提取: media-id + 全字段信息 → 存 media_ids[]
+  → 进入 Step 2.3
 
-**前提**: 课程至少包含 1 个课件。
+Step 2.2b 素材库选择
+  → 调度 soke-material
+  exec: soke file list-files（分页拉取全量素材列表）
+  展示: 文件名 / 类型 / 大小 / 日期（分页或截取前 20 条）
+  告知用户: "输入关键词搜索素材（文件名模糊匹配），或输入序号选择"
+  用户输入关键词 → 在素材列表中模糊匹配 → 弹窗列匹配项
+  用户选序号 → 确认该素材 → 提取全字段信息 → 存 media_ids[]
+  无目标素材 → 弹窗: "素材库中没找到，要不要切换到本地上传？" → ["切本地上传"/"重新搜索"]
+  选"切本地上传" → 回到 Step 2.2
+  → 进入 Step 2.3
 
-```bash
-soke-cli course +publish --course-id "COURSE-UUID"
-```
+Step 2.3 创建课件
+  → 调度 soke-lesson
+  参数全部来自 Step 2.2 或 Step 2.2b 的返回
+  提取: lesson-id
+  存: lesson_ids[]
 
----
+Step 2.4 循环
+  → `ask_user_question` 弹窗: "还要加课件吗？" → ["继续加课件"/"不了，进入下一步"]
 
-## 步骤7: 指派课程（可选）
+Step 2.5 排序（可选）
+  → `ask_user_question` 弹窗: "需要调整课件顺序吗？" → ["调整顺序"/"保持现状"]
+  选"调整" → 调度 soke-lesson 排序
 
-> 详见 [`../soke-assign/SKILL.md`](../soke-assign/SKILL.md)
+Gate 2→3: ✅ 课件 ≥ 1
 
-发布后指派给部门或学员，学员才能看到并学习。
+#### Phase 3: 课程设置
 
-### 7.1 查询可用部门/用户
+  → read references/subs/settings/SOP.md 执行
+    基础: title/description（course +update）
 
-```bash
-soke-cli assign +list-departments --keyword "关键词"
-soke-cli assign +list-users --dept-id "DEPT-ID" --keyword "关键词"
-```
-
-### 7.2 创建指派
-
-```bash
-# 指派给部门
-soke-cli assign +create \
-  --module "course" \
-  --target-id "COURSE-UUID" \
-  --dept-ids "DEPT-ID" \
-  --dept-names "部门名称" \
-  --learn-type "required"
-
-# 指派给用户
-soke-cli assign +create \
-  --module "course" \
-  --target-id "COURSE-UUID" \
-  --user-ids "USER-ID" \
-  --user-names "学员姓名" \
-  --learn-type "required"
-
-# 同时指派给多个部门和用户
-soke-cli assign +create \
-  --module "course" --target-id "COURSE-UUID" \
-  --dept-ids "DEPT1,DEPT2" --dept-names "部门1,部门2" \
-  --user-ids "USER1,USER2" --user-names "学员1,学员2" \
-  --learn-type "required"
-```
-
-**指派参数**:
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--module` | 是 | 固定 `course` |
-| `--target-id` | 是 | 课程 ID |
-| `--learn-type` | 是 | `required`(必修) / `optional`(选修) |
-| `--dept-ids` | 否 | 部门 ID，逗号分隔 |
-| `--dept-names` | 否 | 部门名（与 ids 一一对应） |
-| `--user-ids` | 否 | 用户 ID，逗号分隔 |
-| `--user-names` | 否 | 用户名（与 ids 一一对应） |
-
----
+  → read references/subs/template/SOP.md Step 3 执行
+    将当前所有设置项以表格形式展示（仅「设置项」+「当前值」两列）
+    告知用户: "想修改哪项？直接告诉我就行。"
+  用户指令处理:
+    - 标题/描述 → exec: course +update（✅ CLI 支持） → 刷新表格
+    - 其他设置 → "已记录: {项} → {新值}（需在后台操作: {路径}）" → 刷新表格
+    - "可以了"/"继续" → 退出 Phase 3
+  循环直到用户确认
 
-## 步骤8: 查询学习状态
+Gate 3→4: 无硬阻塞
 
-### 课程学习记录
+#### Phase 4: 发布
 
-```bash
-soke-cli course +list-course-users --course-id "COURSE-UUID"
+  → read references/subs/publish/SOP.md 执行
+    Gate Check: 标题/分类/课件数量/转码状态
+    通过 → course +publish
+    定时/审批/批量 → ⚠️ CLI 不支持
 
-# 按用户筛选
-soke-cli course +list-course-users \
-  --course-id "COURSE-UUID" --userid-list "USER1,USER2"
+Gate 4→5: ✅ status=1
 
-# 按完成时间筛选
-soke-cli course +list-course-users \
-  --course-id "COURSE-UUID" \
-  --finish-start-time 1700000000000 --finish-end-time 1700100000000
-```
+#### Phase 5: 指派学员
 
-### 学员学习详情
+  → 调度 soke-assign
+    
+  Step 5.1 拉取部门列表
+    exec: soke assign +list-departments
+    提取: 全量部门名称+ID → 存内存
 
-```bash
-soke-cli course +get-course-user \
-  --course-id "COURSE-UUID" --dept-user-id "DEPT-USER-ID"
-```
+  Step 5.2 用户输入关键词搜索
+    告知用户: "请输入要指派的部门名称（支持模糊搜索）"
+    用户输入关键词 → 在部门列表中模糊匹配（不区分大小写，支持部分匹配）
+    匹配结果:
+      - 唯一匹配 → 直接确认使用
+      - 多个匹配 → `ask_user_question` 弹窗列出匹配的部门让用户选
+      - 无匹配 → 建议换个关键词，或 `ask_user_question` 弹窗列所有部门
 
-返回: `lesson_finish_num`(已完成)、`lesson_num`(总数)、`progress`(进度%)、`learn_status`
+  Step 5.3 确认指派方式
+    → `ask_user_question` 弹窗: "必修还是选修？" → ["必修"/"选修"]
 
-### 课件学习记录
+  Step 5.4 执行指派
+    exec: soke assign +create --module course --module-id <courseId> --compulsory 1|0 --user-ids "<用部门 ID 查到的人员>"
 
-```bash
-soke-cli course +list-lesson-learns \
-  --course-id "COURSE-UUID" --lesson-id "LESSON-UUID"
-```
-
-### 课件列表
+#### Phase 6: 运营维护
 
-```bash
-# +list-lessons: 支持时间范围
-soke-cli course +list-lessons --course-id "ID" --start-time 1700000000000 --end-time 1700100000000
+  → read references/subs/query/SOP.md 执行（进度/记录/人脸）
+  → read references/subs/publish/SOP.md 执行（关闭/删除，⚠️）
+  → read references/subs/copy/SOP.md 执行（复制，⚠️）
 
-# +lesson-list: 支持类型/关键词筛选
-soke-cli course +lesson-list --course-id "ID" --type "video" --keyword "关键词"
-```
+### 3.3 课件子流程
 
----
+前提: 上下文有 course-id
+流程: = Phase 2（判断类型→上传→创建→循环→排序）
 
-## 可用命令全览
+### 3.4 设置子流程
 
-### 课程管理
+前提: 上下文有 course-id
+流程: read references/subs/settings/SOP.md + references/subs/charge/SOP.md 执行
 
-| 命令 | 说明 | 风险 |
-|------|------|------|
-| `+list-categories` | 查询课程分类列表 | read |
-| `+list-courses` | 查询课程列表 | read |
-| `+get-course` | 查询课程详情 | read |
-| `+create` | 创建课程 | write |
-| `+update` | 更新课程 | write |
-| `+publish` | 发布课程 | write |
+### 3.5 发布子流程
 
-### 课件管理
+前提: course-id + status=0
+流程: read references/subs/publish/SOP.md 执行 → Gate Check → 发布 → 询问指派
 
-| 命令 | 说明 | 风险 |
-|------|------|------|
-| `+lesson-create` | 创建课件 | write |
-| `+lesson-get` | 查询课件详情 | read |
-| `+lesson-list` | 查询课件列表（type/keyword） | read |
-| `+list-lessons` | 查询课件列表（时间范围） | read |
+### 3.6 指派子流程
 
-### 素材管理 (soke-material)
+前提: course-id + status=1
+流程: 调度 soke-assign → 拉全量部门 → 用户输入关键词搜索 → 确认 → 指派
 
-| 命令 | 说明 |
-|------|------|
-| `file +upload` | 上传文件到素材库 |
-| `file +create` | 手动创建素材记录 |
-| `file +list-files` | 查询素材列表 |
-| `file +get-info` | 查询素材详情 |
-| `file +download` | 获取下载链接 |
-| `file +list-categories` | 查询素材分类 |
+### 3.7 查询子流程
 
-### 学习记录查询
+前提: course-id
+流程: read references/subs/query/SOP.md 执行 → 进度/记录/人脸
 
-| 命令 | 说明 |
-|------|------|
-| `+list-course-users` | 课程学员学习记录 |
-| `+get-course-user` | 学员个人详情 |
-| `+list-lesson-learns` | 课件学习记录 |
-| `+list-lesson-faces` | 人脸识别记录 |
+### 3.8 维护子流程
 
-### 指派管理 (soke-assign)
+流程: read references/subs/publish/SOP.md（关闭/删除）/ references/subs/copy/SOP.md（复制）/ references/subs/category/SOP.md（分类）
 
-| 命令 | 说明 |
-|------|------|
-| `assign +list-departments` | 查询可用部门 |
-| `assign +list-users` | 查询可用用户 |
-| `assign +create` | 创建指派 |
-| `assign +list` | 查询指派记录 |
+### SOP 执行 5 步法
 
----
+1. READ `references/subs/<name>/SOP.md` → 理解输入输出
+2. BUILD 从上下文提取参数
+3. EXEC 按 SOP 流程调用 CLI
+4. PARSE 按 SOP 输出标准解析
+5. STORE 关键值写入上下文
 
-## 调试与故障排除
+上下文变量: course_id / category_id / lesson_ids[] / media_ids[] / course_status / current_phase
 
-### 常见错误速查
+## 四、输出标准
 
-| 错误 | 原因 | 解决 |
-|------|------|------|
-| `未登录授权` | Token 过期 | `soke-cli auth login` |
-| `参数错误` | 必填参数缺失 | `soke-cli course <cmd> --help` |
-| `文件不存在` | 上传路径错误 | 使用绝对路径 |
-| `课程发布失败` | 无课件 | 先创建至少 1 个课件 |
-| `分类不存在` | category-id 无效 | 查询 `+list-categories` |
-| `素材不存在` | media-id 无效 | 确认上传成功 |
-| `指派失败` | 资源未发布 | 先发布课程 |
+### 每步即时输出
+```
+✅ <做了什么>
+📋 <关键数据>
+⏭️ <下一步建议>
+```
 
-### 调试检查清单
+### 阶段状态报告
+```
+📋 课程: <标题> (id: <uuid>)
+   Phase 1 ✅ 已创建
+   Phase 2 🔄 课件 3 个
+     ├─ ✅ 第1课: 环境搭建 (video, 转码完成)
+     ├─ ✅ 第2课: Pandas (video, 转码中)
+     └─ ✅ 第3课: 数据清洗.pdf (document)
+   Phase 3 ⏸️  设置
+   Phase 4 ⏸️  发布（阻塞: 第2课转码中）
+   Phase 5 ⏸️  指派
+   下一步: 等转码完成后发布
+```
 
-```bash
-# 1. 认证状态
-soke-cli config show  # 确认用户凭证不为空
+### Gate Check 矩阵
 
-# 2. 课程存在
-soke-cli course +get-course --course-id "ID" --format json | jq '.data.uuid'
+| # | 检查项 | 获取方式 | 严重度 | 不通过时 |
+|---|--------|---------|--------|---------|
+| 1 | 标题非空 | +get-course.title | 🔴阻塞 | 请设置标题 |
+| 2 | 分类已选 | +get-course.category_id | 🔴阻塞 | 请选择分类 |
+| 3 | 课件≥1 | +lesson-list count | 🔴阻塞 | 至少1个课件 |
+| 4 | 无转码失败 | +lesson-list.transcode_status | 🔴阻塞 | 课件[X]转码失败 |
+| 5 | 无转码中 | +lesson-list.transcode_status | 🟡警告 | 课件[X]转码中，确认发布？ |
+| 6 | 付费方式 | 需确认 | 🟡警告 | — |
 
-# 3. 课件数量
-soke-cli course +lesson-list --course-id "ID" --format json | jq '.data.list | length'
+### 最终交付
+```
+📦 课程已发布: <标题>
+🔗 ID: <uuid> | 📊 课件: 5 个 | 👥 已指派: 研发部(32人)
+⏭️ 查看进度: 说"看看学习进度"
+```
 
-# 4. 发布状态
-soke-cli course +get-course --course-id "ID" --format json | jq '.data.status'
-# status=1 表示已发布
+## 五、注意事项
 
-# 5. 指派状态
-soke-cli assign +list --module course --target-id "ID" --format json | jq '.data.list | length'
+### 硬规则
+1. 不编造参数 — UUID 来自真实返回
+2. 不跳过 Gate — 发布前逐项校验
+3. 不静默失败 — 失败: 查排错文档 → 中文告知 → 修复建议 → 保存进度 → 提供选项
+4. 类型必须匹配 — 课件与素材类型一致
+5. 一个 course-id 贯穿全部
 
-# 始终用 --format json 获取结构化输出
-```
+### 架构分工
 
----
+**外部并列技能**（独立 skill，通过 skill 调度）:
+- 上传文件到素材库 → soke-material
+- 基于素材创建课件 → soke-lesson
+- 将课程指派给学员 → soke-assign
 
-## 完整示例
+**内嵌 SOP**（references/subs/ 下，按需 read 执行）:
+- 管理课程分类 → references/subs/category/SOP.md
+- 配置课程设置 → references/subs/settings/SOP.md
+- 设置收费 → references/subs/charge/SOP.md
+- 发布校验和发布 → references/subs/publish/SOP.md
+- 复制课程 → references/subs/copy/SOP.md
+- 查询学习数据 → references/subs/query/SOP.md
+- AI生成课程 → references/subs/ai/SOP.md
+- 课程模板（7套预置配置） → references/subs/template/SOP.md
 
-```bash
-# === 1. 查询分类 ===
-CATEGORY_ID=$(soke-cli course +list-categories --format json | jq -r '.data.list[0].uuid')
-
-# === 2. 创建课程 ===
-COURSE_ID=$(soke-cli course +create \
-  --title "Python 数据分析实战" \
-  --category-id "$CATEGORY_ID" \
-  --format json | jq -r '.data.uuid')
-
-# === 3. 上传素材 ===
-UPLOAD=$(soke-cli file +upload --file "./lesson1.mp4" --format json)
-MEDIA_ID=$(echo "$UPLOAD" | jq -r '.data.uuid')
-FILE_TYPE=$(echo "$UPLOAD" | jq -r '.data.type')
-FILENAME=$(echo "$UPLOAD" | jq -r '.data.filename')
-FILESIZE=$(echo "$UPLOAD" | jq -r '.data.filesize')
-OBJECT=$(echo "$UPLOAD" | jq -r '.data.object')
-EXT=$(echo "$UPLOAD" | jq -r '.data.ext')
-
-# === 4. 创建课件 ===
-soke-cli course +lesson-create \
-  --course-id "$COURSE_ID" --title "第一课：环境搭建" \
-  --media-id "$MEDIA_ID" --type "$FILE_TYPE" --length 600 \
-  --object "$OBJECT" --filename "$FILENAME" --ext "$EXT" --filesize "$FILESIZE"
-
-# === 5. 发布课程 ===
-soke-cli course +publish --course-id "$COURSE_ID"
-
-# === 6. 指派学员 ===
-DEPT_ID=$(soke-cli assign +list-departments --keyword "研发" --format json | jq -r '.data.list[0].uuid')
-soke-cli assign +create \
-  --module "course" --target-id "$COURSE_ID" \
-  --dept-ids "$DEPT_ID" --dept-names "研发部" \
-  --learn-type "required"
-
-# === 7. 验证 ===
-soke-cli course +get-course --course-id "$COURSE_ID" --format json | jq .
-soke-cli course +lesson-list --course-id "$COURSE_ID" --format json | jq '.data.list'
-```
+### 已知 CLI 缺失
 
----
+统一话术: "XXX 功能暂不支持 CLI 操作，请在后台手动设置。"
 
-## API 接口映射
-
-| CLI 命令 | API 路径 | 方法 |
-|----------|----------|------|
-| `+list-categories` | `/course/category/list` | GET |
-| `+list-courses` | `/course/course/list` | GET |
-| `+get-course` | `/course/course/info` | GET |
-| `+create` | `/skills/course/create` | POST |
-| `+update` | `/skills/course/update/{id}` | PUT |
-| `+publish` | `/skills/course/update/{id}` | PUT |
-| `+lesson-create` | `/skills/course/lesson/create` | POST |
-| `+lesson-get` | `/skills/courseware/get/{id}` | GET |
-| `+lesson-list` | `/skills/course/lesson/list` | GET |
-| `+list-lessons` | `/course/lesson/list` | GET |
-| `+list-course-users` | `/course/user/list` | GET |
-| `+get-course-user` | `/course/user/info` | GET |
-| `+list-lesson-learns` | `/course/lessonLearn/list` | GET |
-| `+list-lesson-faces` | `/course/lessonFace/list` | GET |
-| `file +upload` | `/skills/uploadFile/signature` + `/skills/uploadFile/create` | POST |
-| `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 |
-
-## 权限要求
-
-| 操作 | 权限范围 |
-|------|----------|
-| 课程读写 | `course:course:write` / `course:course:readonly` |
-| 课件读写 | `course:courseware:write` / `course:courseware:readonly` |
-| 素材读写 | `file:file:write` / `file:file:readonly` |
-| 指派读写 | `assign:write` / `assign:read` |
-| 学习记录 | `course:courseUser:readonly` / `course:lessonLearn:readonly` |
-
-## 注意事项
-
-1. **课程至少需要 1 个课件才能发布**
-2. **课件参数全部从素材上传响应提取**，不手动构造
-3. **时长根据文件类型自动设置**: video=600s, audio=300s, 其他=0
-4. **课程发布后学员才可见**
-5. **指派是可选的**，未指派时学员看不到课程
-6. **所有时间参数使用毫秒级 Unix 时间戳**
-
-## 相关文档
-
-- [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md) — 认证、配置、权限
-- [`../soke-material/SKILL.md`](../soke-material/SKILL.md) — 文件上传和素材管理
-- [`../soke-lesson/SKILL.md`](../soke-lesson/SKILL.md) — 课件创建和管理
-- [`../soke-assign/SKILL.md`](../soke-assign/SKILL.md) — 指派管理
-- [`references/examples.md`](./references/examples.md) — 更多使用示例
-- [`references/course-list-courses.md`](./references/course-list-courses.md) — 课程查询参考
+| 类别 | 缺失 |
+|------|------|
+| 课件类型 | image/article/link/quiz/homework |
+| 分类 | 新增分类 |
+| 课程设置 | credit/point/lector_id/tags/cover上传/简介插图 |
+| 高级设置 | 学习模式/倍速/人脸/提醒/评价/证书/签名/钉钉群 |
+| 收费 | 价格/试看 |
+| 发布 | 定时/审批/批量 |
+| 维护 | 关闭/删除/复制 |
+
+### 中断恢复
+用户"继续"/"接着做": 检查 course-id → 有:查状态+课件→报告→继续 | 无:列课程→选→恢复
+
+## 六、交付前自查
+
+- [ ] 每步有明确调度目标
+- [ ] 关键返回值已存入上下文
+- [ ] 每步完成有下一步建议
+- [ ] 发布前过完整 Gate Check
+- [ ] CLI 不支持功能已告知替代路径
+- [ ] 失败有修复建议
+- [ ] 所有固定选项的决策点均使用 `ask_user_question` 弹窗（禁止纯文本罗列让用户打字）
+- [ ] 分类选择弹窗最后一项始终为"🆕 新建分类"
+- [ ] 状态报告完整