@sokeai/cli 1.0.77 → 1.0.78

package/skills/multi/soke-course/references/subs/settings/SOP.md

@@ -0,0 +1,136 @@
+---
+name: soke-course-settings
+version: 1.0.0
+description: 课程设置 — 基础信息编辑及高级设置项说明，支持通过 CLI 更新课程高级设置
+tags: [soke, course, settings, configuration, advanced]
+---
+
+# 课程设置
+
+## 触发描述
+
+课程创建后需要对课程标题、描述等基础信息进行修改，或需要更新高级设置项（学习模式、人脸识别、提醒、倍速等）时触发本技能。
+
+## CLI 支持的操作
+
+### 基础信息更新 `course +update`
+
+```bash
+soke course +update \
+  --course-id <courseId> \
+  --title "<新标题>" \
+  --credit 10 \
+  --description "<新描述>" \
+  --image "<图片库 photoUri>"
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--course-id` | 是 | 课程 ID |
+| `--action` | 否 | 操作类型，默认 `update`；传 `close` 可关闭课程 |
+| `--title` | 否 | 课程标题 |
+| `--credit` | 否 | 学分 |
+| `--description` | 否 | 课程描述/简介 |
+| `--image` | 否 | 课程封面图片地址，使用图片库列表接口返回的 `photoUri` |
+| `--image-x` | 否 | 封面裁剪 x 坐标，默认 0 |
+| `--image-y` | 否 | 封面裁剪 y 坐标，默认 0 |
+| `--image-w` | 否 | 封面裁剪宽度，默认 0 |
+| `--image-h` | 否 | 封面裁剪高度，默认 0 |
+
+> 至少传一个可更新字段，可同时更新。`--description ""` 会清空课程描述。
+
+### 高级设置更新 `course +advanced`
+
+```bash
+soke course +advanced \
+  --course-id <courseId> \
+  --study-type 2 \
+  --is-accelerate 1 \
+  --is-drag 0 \
+  --evaluate-required 1
+```
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `--course-id` | 必填 | 课程 ID |
+| `--open-workrecord` | 0 | 待办推送，1 开启，0 不开启 |
+| `--allow-after-expiration` | 1 | 截止后继续学习，1 允许，0 不允许 |
+| `--open-face-recognition` | 0 | 课程前人脸识别，1 开启，0 不开启 |
+| `--is-first-face` | 0 | 0 不识别，1 首次使用，2 每次进入 |
+| `--learning-face-recognition` | 0 | 视频学习中人脸识别，1 开启，0 不开启 |
+| `--face-recognition-times` | 1 | 视频学习中人脸识别次数 |
+| `--study-type` | 1 | 学习模式，1 自由式，2 解锁式 |
+| `--is-remind` | 0 | 未学提醒，1 开启，0 不开启 |
+| `--remind-days` | 1 | 未学提醒推送周期，单位天 |
+| `--remind-time` | 空 | 推送时间，格式 HH:MM:SS |
+| `--remind-content` | 管理员提醒文案 | 未学提醒推送内容 |
+| `--is-accelerate` | 1 | 视频或音频倍速，1 开启，0 不开启 |
+| `--is-drag` | 0 | 视频是否可拖动，1 允许，0 不允许 |
+| `--drag-type` | 1 | 1 仅首次播放不允许拖动，2 每次播放均不允许拖动 |
+| `--evaluate-required` | 0 | 完成学习后打星评价，1 开启，0 不开启 |
+| `--image-file` | 空 | 本地交流群二维码图片路径，命令内部上传到 OSS 并写入 `imageOssUrl`，不进入图片库；支持 jpg/jpeg/png |
+| `--image-oss-url` | 空 | 已上传到 OSS/CDN 的交流群二维码完整访问 URL；与 `--image-file` 二选一 |
+| `--is-hang` | 0 | 文档防挂机，1 开启，0 不开启 |
+| `--hang-time` | 0 | 文档防挂机时间，单位分钟，最多 60 |
+| `--comment-switch` | 1 | 课程评论，1 开启，0 不开启 |
+
+该命令请求 `PUT /skills/course/advanceSetting/{id}`，请求体固定带 `action=advanced`。
+
+**交流群二维码 `imageOssUrl` 取值规则：**
+
+1. 如果用户提供的是本地二维码图片，直接使用 `--image-file`。命令会在内部调用 OSS 上传能力，使用 `Module: "image"` 上传，并把签名里的 `editorHost`（优先）或 `cdnhost` 与 OSS object 拼成完整 URL 写入 `imageOssUrl`。该图片不会进入图片库。
+
+```bash
+soke-cli course +advanced \
+  --course-id <courseId> \
+  --image-file "./qrcode.png"
+```
+
+2. 如果用户已经有 OSS/CDN 完整访问 URL，直接传 `--image-oss-url`：
+
+```bash
+soke-cli course +advanced \
+  --course-id <courseId> \
+  --image-oss-url "$IMAGE_URL"
+```
+
+3. `--image-file` 和 `--image-oss-url` 只能传一个。不要把图片 UUID、素材 UUID 或纯 `data.object` 当作 `imageOssUrl`；该字段需要可访问的完整图片 URL。
+
+## ⚠️ CLI 暂不支持的设置
+
+| 设置项 | 说明 | 后台操作路径 |
+|--------|------|-------------|
+| **证书设置** `certificate` | 配置结业证书模板（背景图、字段、盖章）和通过条件 | 后台 → 课程管理 → 课程列表 → 编辑 → 证书设置 |
+| **证书签名** `signature` | 配置证书上的签名图片（讲师/负责人手写签名） | 后台 → 课程管理 → 课程列表 → 编辑 → 证书设置 → 签名管理 |
+
+## 输出标准
+
+基础信息更新成功后：
+
+```
+✅ 课程信息更新成功
+- 课程: {newTitle} (ID: {courseId})
+- 描述: {newDescription 摘要}
+```
+
+高级设置更新成功后：
+
+```
+✅ 课程高级设置更新成功
+- 课程: {courseId}
+- 结果: 1
+```
+
+## 注意事项
+
+1. `course +update` 支持标题、学分、描述、封面图、分类 ID 修改，以及通过 `--action close` 关闭课程
+2. 封面图地址来自图片库列表接口返回的 `photoUri`
+3. 分类修改可通过 `--category-id` 更新
+4. 高级设置项之间可能存在依赖关系（如开启视频学习中人脸识别后再设置识别次数），建议按表格顺序逐项配置
+5. 钉钉二维码设置与课程复制时的行为有关联（复制时不携带，见 `soke-course-copy`）
+
+## 检查清单
+
+- [ ] CLI 操作：title/description 或高级设置参数已准备完毕，courseId 确认存在
+- [ ] 高级设置需求已识别，优先使用 `course +advanced`
+- [ ] 证书/签名等未支持设置已提供对应后台路径

package/skills/multi/soke-course/references/subs/template/SOP.md

@@ -0,0 +1,223 @@
+---
+name: course-template
+version: 1.1.0
+description: 课程模板选择 — 7套预置配置，按业务场景快速初始化课程设置
+tags: [soke, course, template, preset]
+---
+
+# 课程模板
+
+## 触发描述
+
+创建课程（Step 1.3 完成）后立即触发。根据用户业务场景推荐对应模板，输出预置配置清单。Phase 3 时展示当前所有设置项，用户可用自然语言逐项覆盖。
+
+## 模板速查
+
+| # | 模板名称 | 一句话场景 | 特征标签 |
+|---|---------|-----------|---------|
+| 1 | 合规必修（最严） | 安全/合规/法务培训 | 🔒最严管控 |
+| 2 | 考核认证 | 上岗/资格/技能鉴定 | 📝考试+证书 |
+| 3 | 新人入职 | 新员工/转岗培训 | 🚀快速上手 |
+| 4 | 知识分享 | 内部分享/兴趣课程 | 📖自由学习 |
+| 5 | 领导力/软技能 | 管理/沟通/职业素养 | 🎓进阶提升 |
+| 6 | 产品/业务培训 | 新产品上线/业务更新 | 📦快速推送 |
+| 7 | 不选择模板 | 手动逐项配置 | ✋自行设置 |
+
+---
+
+## 配置映射表
+
+### 1. 合规必修（最严）
+
+| 设置项 | 值 | CLI | 说明 |
+|--------|-----|:---:|------|
+| 学习模式 | 必修 + 解锁式(LongDragon) | ⚠️ | 后台：学习设置 |
+| 人脸识别 | 开启 | ⚠️ | 后台：学习设置 → 人脸识别 |
+| 倍速播放 | 禁用 | ⚠️ | 后台：学习设置 → 播放控制 |
+| 拖动进度条 | 禁用 | ⚠️ | 后台：学习设置 → 播放控制 |
+| 电子签名 | 开启 | ⚠️ | 后台：证书设置 → 签名管理 |
+| 收费 | 可选 | ⚠️ | 后台：收费设置 |
+| 截止时间 | 需设置 | ⚠️ | 后台：学习设置 |
+| 课程评价 | 打星评价 | ⚠️ | 后台：评价设置 |
+| 关联证书 | 是 | ⚠️ | 后台：证书设置 |
+| 发布方式 | 审批发布 | ⚠️ | 后台：发布设置 |
+
+**适用场景**：安全培训、合规培训、法务必修课。需要强制学习+防作弊+可追溯。
+
+---
+
+### 2. 考核认证
+
+| 设置项 | 值 | CLI | 说明 |
+|--------|-----|:---:|------|
+| 学习模式 | 必修 + 解锁式(LongDragon) | ⚠️ | 后台：学习设置 |
+| 小测验 | 限制次数 | ⚠️ | 后台：课件设置 |
+| 作业 | 多级审批 | ⚠️ | 后台：课件设置 |
+| 人脸识别 | 选开 | ⚠️ | 后台：学习设置 → 人脸识别 |
+| 关联证书 | 是 | ⚠️ | 后台：证书设置 |
+| 发布方式 | 审批发布 | ⚠️ | 后台：发布设置 |
+
+**适用场景**：上岗考试、资格认证、技能鉴定。需考核+认证背书。
+
+---
+
+### 3. 新人入职
+
+| 设置项 | 值 | CLI | 说明 |
+|--------|-----|:---:|------|
+| 学习模式 | 必修 + 自由模式(Free) | ⚠️ | 后台：学习设置 |
+| 倍速播放 | 开启 | ⚠️ | 后台：学习设置 → 播放控制 |
+| 未学提醒 | 开启 | ⚠️ | 后台：学习设置 → 提醒设置 |
+| 截止时间 | 需设置 | ⚠️ | 后台：学习设置 |
+| 自动配课 | 开启 | ⚠️ | 后台：指派设置 |
+| 课程评价 | 打星评价 | ⚠️ | 后台：评价设置 |
+
+**适用场景**：新员工培训、转岗培训。需快速覆盖+自动推送+追踪完成。
+
+---
+
+### 4. 知识分享
+
+| 设置项 | 值 | CLI | 说明 |
+|--------|-----|:---:|------|
+| 学习模式 | 选修 + 自由模式(Free) | ⚠️ | 后台：学习设置 |
+| 倍速播放 | 开启 | ⚠️ | 后台：学习设置 → 播放控制 |
+| 拖动进度条 | 允许 | ⚠️ | 后台：学习设置 → 播放控制 |
+| 收费 | 免费 | ⚠️ | 后台：收费设置 |
+| 小测验 | 不限次数 | ⚠️ | 后台：课件设置 |
+
+**适用场景**：内部分享、兴趣课程、文化宣传。低门槛+自由学习+无考核压力。
+
+---
+
+### 5. 领导力/软技能
+
+| 设置项 | 值 | CLI | 说明 |
+|--------|-----|:---:|------|
+| 学习模式 | 选修或必修 + 自由模式(Free) | ⚠️ | 后台：学习设置 |
+| 作业 | 无需批改 | ⚠️ | 后台：课件设置 |
+| 课程评价 | 打星评价 | ⚠️ | 后台：评价设置 |
+| 关联证书 | 可选 | ⚠️ | 后台：证书设置 |
+| 钉钉群 | 可配置 | ⚠️ | 后台：学习设置 → 钉钉二维码 |
+
+**适用场景**：管理培训、沟通课程、职业素养。互动+讨论+可选认证。
+
+---
+
+### 6. 产品/业务培训
+
+| 设置项 | 值 | CLI | 说明 |
+|--------|-----|:---:|------|
+| 学习模式 | 必修 + 自由模式(Free) | ⚠️ | 后台：学习设置 |
+| 倍速播放 | 开启 | ⚠️ | 后台：学习设置 → 播放控制 |
+| 拖动进度条 | 允许 | ⚠️ | 后台：学习设置 → 播放控制 |
+| 小测验 | 开启 | ⚠️ | 后台：课件设置 |
+| 定时发布 | 需设置 | ⚠️ | 后台：发布设置 |
+| 未学提醒 | 开启 | ⚠️ | 后台：学习设置 → 提醒设置 |
+
+**适用场景**：新产品上线、业务知识更新。需快速推送+检验理解+追踪覆盖。
+
+---
+
+### 7. 不选择模板
+
+不预置任何配置项，所有设置在 Phase 3 逐项手动确认。适合模板不匹配的场景或需要精细控制的课程。
+
+---
+
+## 执行流程
+
+### Step 1: 模板选择弹窗（Phase 1 创建课程后立即触发）
+
+**先输出速查表：**
+
+```
+📋 可选模板（7种）：
+
+| # | 名称 | 适用场景 | 核心配置 |
+|---|------|---------|---------|
+| 1 | 合规必修 | 安全/合规/法务培训 | 人脸+签名+证书+审批 |
+| 2 | 考核认证 | 上岗考试/资格认证 | 考试+证书+多级审批 |
+| 3 | 新人入职 | 新员工/转岗培训 | 提醒+自动配课+评价 |
+| 4 | 知识分享 | 内部分享/兴趣课程 | 自由学习+免费+不限测验 |
+| 5 | 领导力/软技能 | 管理/沟通/职业素养 | 作业+评价+证书+钉钉群 |
+| 6 | 产品/业务培训 | 新产品上线/业务更新 | 定时发布+小测验+提醒 |
+| 7 | 不选择模板 | 模板不匹配/精细控制 | 无预设，后续逐项手动配置 |
+```
+
+**再弹窗让用户选：**
+
+```
+ask_user_question
+  question: "选择课程模板（7选1，详情见上方表格）"
+  header: "模板"
+  options:
+    - label: "1. 合规必修"     description: "安全/合规/法务 · 人脸+签名+证书+审批"
+    - label: "2. 考核认证"     description: "上岗考试/资格认证 · 考试+证书"
+    - label: "3. 新人入职"     description: "新员工/转岗 · 提醒+配课+评价"
+    - label: "4. 知识分享"     description: "内部分享/兴趣 · 自由学习+免费"
+    - label: "5. 领导力/软技能" description: "管理/沟通/素养 · 作业+证书+钉钉群"
+    - label: "6. 产品/业务培训" description: "产品上线/业务更新 · 定时+测验+提醒"
+    - label: "7. 不选择模板"   description: "无预设，逐项手动配置"
+```
+
+### Step 2: 输出模板配置
+
+用户选 1-6 → 输出该模板完整配置表：
+
+```
+✅ 已选择「{模板名称}」模板
+
+📋 该模板预置以下设置（CLI 不支持，需后台操作）：
+
+| 设置项 | 预置值 | 后台路径 |
+|--------|--------|---------|
+| xxx    | xxx    | 后台 → xxx |
+| ...    | ...    | ...       |
+
+⏭️ 后续进入 Phase 3 时，可以逐项修改以上设置。回复"继续"进入下一步。
+```
+
+用户选 7.「不选择模板」→ 不输出配置清单，直接进入 Phase 1 的路由弹窗。
+
+### Step 3: Phase 3 展示当前设置（可逐项修改）
+
+进入 Phase 3 时，将当前课程所有设置项以表格形式展示：
+
+```
+📋 当前设置（模板: {模板名称}）：
+
+| 设置项 | 当前值 |
+|--------|--------|
+| 标题   | "xxx"  |
+| 描述   | "xxx"  |
+| 学习模式 | 必修+解锁式 |
+| 人脸识别 | 开启 |
+| ... | ... |
+
+💬 想修改哪项？直接告诉我就行，比如：
+  - "标题改成 xxx"
+  - "学习模式改成自由式"
+  - "关掉人脸识别"
+  - "加一个证书"
+```
+
+用户输入修改指令后的处理：
+
+| 修改项 | CLI 支持 | 处理方式 |
+|--------|:---:|------|
+| 标题/描述 | ✅ | 执行 `course +update` 更新，表中同步刷新 |
+| 其他所有设置 | ⚠️ | "该设置需在后台修改（路径: xxx）。我会在清单中标注为待修改。" |
+| 修改模板预设值 | ⚠️ | "已记录：{设置项} → {新值}（需在后台操作）" |
+
+每次修改后刷新配置表，直到用户说"可以了"/"继续"进入下一步。
+
+---
+
+## 注意事项
+
+1. 模板选择后不自动通过 CLI 修改课程 — 大部分设置 CLI 不支持
+2. 模板选择不影响已创建的 title/description/category-id
+3. Phase 3 必须展示完整设置清单，让用户逐项确认/修改
+4. 用户选「不选择模板」(7)时，Phase 3 也需展示所有可配置项，方便用户了解能做什么
+5. 若用户选了模板但没去后台配置，发布阶段 Gate Check 可能阻塞

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

@@ -0,0 +1,68 @@
+# 常见问题排错指南
+
+## 认证类
+
+| 错误信息 | 原因 | 修复 |
+|---------|------|------|
+| `access_key_id not configured` | 未配置登录凭证 | `soke-cli config set --key access_key_id --value <your-key>` |
+| `Token 过期 / 401 Unauthorized` | 登录 Token 已过期 | `soke-cli auth login` |
+| `Permission denied / 403` | 当前账号无操作权限 | 联系管理员在开放平台开通权限 |
+
+## 课程操作类
+
+| 错误信息 | 原因 | 修复 |
+|---------|------|------|
+| `课程标题为空` | 未设置标题 | `course +update --course-id <id> --title "标题"` |
+| `分类不存在 / category not found` | category-id 无效 | `course +list-categories` 重新查询有效分类 |
+| `课程不存在 / Course not found` | course-id 无效或已删除 | `course +list-courses` 确认课程列表 |
+| `课程状态不是未发布，不能发布` | status=1(已发布)或2(已关闭) | 已发布无需操作；已关闭不能重新发布 |
+| `课件数量不足` | 课程无课件 | 进入 Phase 2 添加课件 |
+
+## 上传类
+
+| 错误信息 | 原因 | 修复 |
+|---------|------|------|
+| `file not found` | 文件路径错误或不存在 | 检查路径是否正确，使用绝对路径 |
+| `文件类型不支持` | 格式不在支持列表中 | 转换为 .mp4/.mp3/.pdf 等支持格式 |
+| `文件大小超过限制` | 文件超过上限 | 压缩文件后重试 |
+| `OSS upload failed` | 网络问题或 Token 失效 | 重新登录后重试 |
+| `转码失败` | 文件损坏或格式异常 | 删除失败课件，确认源文件可用后重新上传 |
+
+## 课件操作类
+
+| 错误信息 | 原因 | 修复 |
+|---------|------|------|
+| `素材不存在 / media not found` | media-id 无效 | 确认素材已上传成功 `file +list-files` |
+| `课件类型不匹配` | type 与素材不符 | type 必须与素材上传响应的 type 一致 |
+| `课件已存在` | 重复创建 | 检查 `course +lesson-list` |
+| `课件数量达到上限` | 课程课件数超标 | 删除不需要的课件 |
+
+## 指派类
+
+| 错误信息 | 原因 | 修复 |
+|---------|------|------|
+| `课程未发布，不能指派` | status ≠ 1 | 先发布课程再指派 |
+| `用户不存在` | user-id 无效 | `assign +list-users` 确认有效用户 |
+| `部门不存在` | dept-id 无效 | `assign +list-departments` 确认有效部门 |
+
+## 查询类
+
+| 错误信息 | 原因 | 修复 |
+|---------|------|------|
+| `时间范围超过365天` | +list-courses 限制 | 分批查询，每年一次 |
+| `数据为空` | 筛选条件无匹配 | 放宽筛选条件或检查权限范围 |
+
+## 通用调试步骤
+
+```bash
+# 1. 检查认证状态
+soke-cli config show
+
+# 2. 检查课程是否存在
+soke-cli course +get-course --course-id "xxx" --format json
+
+# 3. 检查课件状态
+soke-cli course +lesson-list --course-id "xxx" --format json
+
+# 4. 始终使用 --format json 获取结构化输出
+```

package/skills/multi/soke-course/scripts/check_readiness.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Check that the soke-course Skill and CLI prerequisites are available."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def check_command() -> bool:
+    executable = shutil.which("soke-cli")
+    if not executable:
+        print("  ❌ soke-cli 未安装")
+        print("     请读取 references/installation.md 按步骤安装")
+        return False
+
+    try:
+        version = subprocess.run(
+            [executable, "--version"],
+            check=False,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+    except OSError as exc:
+        print(f"  ❌ soke-cli 无法执行: {exc}")
+        return False
+
+    print(f"  ✅ soke-cli: {version or '已找到'}")
+    return True
+
+
+def check_login() -> None:
+    executable = shutil.which("soke-cli")
+    if not executable:
+        return
+    result = subprocess.run(
+        [executable, "config", "show"],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    output = f"{result.stdout}\n{result.stderr}"
+    if "user_token" in output:
+        print("  ✅ 已登录")
+    else:
+        print("  ⚠️  未登录或 Token 过期")
+        print("     请运行: soke-cli auth login")
+
+
+def main() -> int:
+    base_dir = Path(__file__).resolve().parent.parent
+    print("🔍 课程发布主管 — 环境检查")
+    print("============================\n")
+
+    guide = base_dir / "references" / "installation.md"
+    print("📖 前置依赖:")
+    print(f"  {'✅' if guide.is_file() else '❌'} references/installation.md {'存在' if guide.is_file() else '缺失'}")
+
+    print("\n🔧 命令行工具:")
+    available = check_command()
+    if available:
+        check_login()
+
+    print("\n📋 包内依赖:")
+    for name in ("soke-material", "soke-lesson", "soke-assign"):
+        dependency = base_dir / "references" / "dependencies" / f"{name}.md"
+        print(f"  {'✅' if dependency.is_file() else '⚠️'} {name}")
+
+    print("\n📁 子能力 SOP:")
+    for name in ("category", "settings", "charge", "publish", "copy", "query", "ai"):
+        sop = base_dir / "references" / "subs" / name / "SOP.md"
+        print(f"  {'✅' if sop.is_file() else '⚠️'} {name}")
+
+    print("\n📚 参考文档:")
+    for name in ("intent-cases.md", "sop-full-workflow.md", "sop-lesson-types.md", "sop-publish-check.md", "troubleshoot.md"):
+        reference = base_dir / "references" / name
+        print(f"  {'✅' if reference.is_file() else '⚠️'} {name}")
+
+    print("\n✅ 环境检查完成")
+    return 0 if available else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+