@sokeai/cli 1.0.64 → 1.0.66

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sokeai/cli",
-    "version": "1.0.64",
+    "version": "1.0.66",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"

package/skills/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git push *)"
+    ]
+  }
+}

package/skills/soke-ai-training/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: soke-ai-training
-summary: AI教练知识包同步、source管理、场景绑定和知识计划查询
+summary: AI教练知识包同步、source管理、场景绑定、知识计划查询和场景CLI更新
 version: 1.0.0
-description: "用于本地Agent通过soke-cli调用开放平台AI教练知识包接口，完成Markdown source上传、结构化entries同步、source管理、场景知识包版本绑定和知识计划编译查询。"
+description: "用于本地Agent通过soke-cli调用开放平台AI教练接口，完成Markdown source上传、结构化entries同步、source管理、场景知识包版本绑定、知识计划编译查询、场景详情读取、系统角色资源查询和场景CLI安全更新。"
 metadata:
   requires:
     bins: ["soke-cli"]
   cliHelp: "soke-cli ai-training --help"
 ---
 
-# AI教练知识包
+# AI教练知识包与场景管理
 
 **CRITICAL — 开始前 MUST 先读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置和权限处理。**
 
@@ -85,9 +85,165 @@ soke-cli ai-training +compile-plan \
 soke-cli ai-training +get-plan --scenario-id scenario_micro_loan_sales --format json
 ```
 
+## 场景读取与更新
+
+场景配置更新必须先读取当前场景，再基于 `updated_at` 构造 `base_updated_at`。只修改描述、角色、评分或流程时，使用 `+preview-scenario-update` 和 `+apply-scenario-update`；发布场景时才使用 `+publish-scenario`。
+
+### 创建场景
+
+如果封面图由本地智能体生成，先上传封面并拿到可写入 `scenario_cover` 的 CDN URL：
+
+```bash
+soke-cli ai-training +upload-scenario-cover \
+  --file ./cover.png
+```
+
+默认只输出 CDN URL。需要排障时可加 `--raw` 查看完整上传凭证响应；不要把 `upload_url`、OSS 签名字段、access key 或 security token 写入仓库、状态文件或对话记录。SaaS 与 MentorAI 共用 OSS/CDN，封面上传复用开放平台的 SaaS OSS 签名能力，不需要 MentorAI 端单独上传接口。
+
+最小参数创建：
+
+```bash
+soke-cli ai-training +upload-scenario-cover --file ./cover.png > cover-url.txt
+
+soke-cli ai-training +create-scenario \
+  --name "创建测试" \
+  --description "描述" \
+  --tags "" \
+  --key-points "关键点" \
+  --scene-lang zh \
+  --scenario-cover "$(cat cover-url.txt)" \
+  --pretty
+```
+
+复杂角色、评分规则、流程步骤和时间设置使用完整 JSON：
+
+```bash
+soke-cli ai-training +create-scenario \
+  --request-file scenario-create.json \
+  --pretty
+```
+
+创建命令默认输出 MentorAI `BaseResponse.data`，通常可从返回对象中读取新场景 ID。创建请求中的 `corp_id`、`company_id`、`user_id`、`implementation_corp_id` 不作为授权依据，企业和用户上下文由开放平台认证注入。
+
+### 读取和资源选择
+
+```bash
+soke-cli ai-training +list-scenarios \
+  --page 1 \
+  --page-size 20 \
+  --keyword "销售" \
+  --pretty
+
+soke-cli ai-training +get-scenario \
+  --scenario-id scenario_micro_loan_sales \
+  --pretty \
+  --output scenario.json
+
+soke-cli ai-training +list-role-avatars \
+  --lang zh \
+  --show-detail \
+  --pretty
+
+soke-cli ai-training +list-role-voices \
+  --lang zh \
+  --gender female \
+  --pretty
+```
+
+`+list-scenarios` 默认输出 MentorAI `BaseResponse.data`，用于发现可操作场景 ID。列表 query 不要伪造 `corp_id`、`company_id`、`user_id` 或 `implementation_corp_id`；可见范围由开放平台 token、用户登录态和 MentorAI 权限决定。拿到场景 ID 后，优先执行 `+get-scenario` 保存完整基准 JSON。
+
+头像更新写入 `ai_roles[].role_data.avatar` 时使用头像资源的 `url`，不是资源 `id`。声音更新写入 `ai_roles[].role_data.voice_id` 时使用声音资源的 `id`，不是 `sample_url`。
+
+### 预览和应用
+
+完整请求文件示例：
+
+```json
+{
+  "base_updated_at": "2026-07-08T10:20:00+08:00",
+  "idempotency_key": "cli-scenario-update-001",
+  "reason": "优化客户角色开场和声音",
+  "source": "cli",
+  "operations": [
+    {
+      "type": "patch_ai_role",
+      "data": {
+        "scenario_role_id": "role_customer_owner",
+        "patch": {
+          "role_data": {
+            "voice_id": "zh_female_warm_01"
+          },
+          "customized_fields": ["voice_id"]
+        }
+      }
+    }
+  ]
+}
+```
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id scenario_micro_loan_sales \
+  --request-file update.json \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id scenario_micro_loan_sales \
+  --request-file update.json \
+  --pretty
+```
+
+也可以只提供 operations 数组，并用 flag 组装请求：
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id scenario_micro_loan_sales \
+  --operations-file operations.json \
+  --base-updated-at "2026-07-08T10:20:00+08:00" \
+  --reason "优化场景说明" \
+  --pretty
+```
+
+`+apply-scenario-update` 必须有 `idempotency_key`，可放在 `--request-file` 中，或用 `--idempotency-key` 覆盖补充。遇到 409 乐观锁冲突时，重新执行 `+get-scenario` 获取最新 `updated_at` 后再生成更新请求。
+
+### 发布场景
+
+发布场景使用独立命令：
+
+```bash
+soke-cli ai-training +publish-scenario \
+  --scenario-id scenario_micro_loan_sales \
+  --pretty
+```
+
+MentorAI `POST /api/v1/scenarios/{scenario_id}/publish` 使用路径中的 `scenario_id`，并在 body 中发送 `version` 和 `version_description`。CLI 默认 `--version 1`、`--version-description "CLI发布"`，不再提供 `--request-file`。不要用 `+publish-scenario` 做任意局部更新；如果只是修改描述、角色字段、评分项或对话步骤，继续走 preview/apply。发布接口返回 409/422 时，加 `--raw` 保留 `errorCode/errorMessage/details/traceId`。
+
+### 快照
+
+```bash
+soke-cli ai-training +list-scenario-snapshots \
+  --scenario-id scenario_micro_loan_sales \
+  --page 1 \
+  --page-size 20 \
+  --pretty
+
+soke-cli ai-training +restore-scenario-snapshot \
+  --scenario-id scenario_micro_loan_sales \
+  --snapshot-id snapshot_001 \
+  --reason "回滚错误CLI更新" \
+  --pretty
+```
+
+新增场景命令默认输出 MentorAI `BaseResponse.data`；排查错误时加 `--raw` 保留 `success/errorCode/errorMessage/details/traceId`。
+
 ## 注意
 
 - 不要在 manifest 或 entries 中伪造 `corp_id`、`user_id` 或 `object_key`。
 - `object_key` 必须使用 upload-token 返回值。
 - 不要把客户原始资料、token、app_secret 或 OSS 签名写入仓库。
+- `+upload-scenario-cover` 默认只输出 `cdn_url`；只有排障时才使用 `--raw`，且不要持久化完整签名响应。
 - `advisor_golden_script` 不应进入 AI 客户角色可见知识。
+- 场景更新请求体或 query 中不要伪造 `corp_id`、`company_id`、`user_id`。
+- 场景创建请求体中的 `corp_id`、`company_id`、`user_id`、`implementation_corp_id` 会由代理剥离，不要依赖它们选择租户。
+- 场景更新前必须以 `+get-scenario` 的 `updated_at` 作为 `base_updated_at`。
+- 场景发布需要 `+publish-scenario --scenario-id <id>`，默认带 `version=1` 和 `version_description=CLI发布`；不要把它当作局部更新命令。

package/skills/soke-assign/SKILL.md

@@ -1,383 +1,103 @@
 ---
 name: soke-assign
-summary: 授客学堂指派管理（创建指派/查询指派/查询部门/查询用户），支持课程、考试、学习地图等多种模块的指派操作
 version: 1.0.0
-description: "授客学堂指派管理：通用的学习资源指派系统，支持将课程、考试、学习地图等学习资源指派给部门、用户、群组、职位或角色。提供完整的指派生命周期管理，包括创建指派、查询指派列表、查询可用部门和用户。支持必修和选修两种学习类型，支持批量指派和消息通知。当用户需要为部门或用户分配学习任务时使用。"
-metadata:
-  requires:
-    bins: ["soke-cli"]
-  cliHelp: "soke-cli assign --help"
+description: 指派管理 — 查询部门/用户并指派课程给学员，支持必修/选修
+tags: [soke, assign, department, user, enrollment]
 ---
 
-# 指派管理 (assign)
+# 指派管理
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+## 触发描述
 
-## ⚠️ 使用前提
+课程创建并发布后，需要将课程指派给部门或具体学员时触发本技能。支持查询组织架构、查询用户列表、创建指派记录及查看指派列表。
 
-本 skill 基于 **soke-cli** 命令行工具，使用前必须完成以下步骤：
+## 前置条件
 
-1. **安装 soke-cli**：确保已安装 `@sokeai/cli` NPM 包或 soke-cli 二进制文件
-2. **用户登录授权**：运行 `soke-cli auth login` 完成 OAuth 设备码授权流程，获取用户访问令牌
+- 目标课程 `status = 1`（已发布），未发布的课程不可指派
+- 具有指派权限（管理员或课程负责人）
 
-**快速开始**：
-```bash
-# 1. 用户登录授权（必须）
-soke-cli auth login
-
-# 2. 验证登录状态
-soke-cli config show
-```
-
-未完成登录授权将无法调用任何指派管理相关的 API。详细的认证配置说明请参考 [soke-shared/SKILL.md](../soke-shared/SKILL.md)。
-
-## 核心概念
-
-- **Assign（指派）**: 将学习资源分配给特定对象的操作，通过 `uuid` 标识
-- **Module（模块）**: 学习资源类型，如 course（课程）、exam（考试）、learning_map（学习地图）
-- **Target（目标）**: 被指派的学习资源，通过 `target_id` 标识
-- **AssignType（指派类型）**: 指派对象类型，包括 dept（部门）、user（用户）、group（群组）、position（职位）、role（角色）
-- **LearnType（学习类型）**: required（必修）或 optional（选修）
-
-## 支持的模块
-
-- **course** - 课程指派
-- **exam** - 考试指派
-- **learning_map** - 学习地图指派
-- 其他模块（根据系统配置）
-
-## 支持的指派类型
-
-- **dept（部门）**: 部门下所有成员都可以学习
-- **user（用户）**: 只有指定的用户可以学习
-
-## 可用命令
+## 执行流程
 
-### 1. 查询部门列表
-
-查询可用的部门列表，用于指派前选择目标部门。
+### 1. 查询部门 `assign +list-departments`
 
 ```bash
-soke-cli assign +list-departments [flags]
+soke assign +list-departments
 ```
 
-**参数**:
-- `--page` - 页码（默认：1）
-- `--limit` - 每页数量（默认：10）
-- `--parent-id` - 父部门ID（默认：1，查询顶级部门）
-- `--keyword` - 搜索关键词（部门名称）
-
-**示例**:
-```bash
-# 查询顶级部门
-soke-cli assign +list-departments
-
-# 搜索部门
-soke-cli assign +list-departments --keyword "研发"
+返回当前租户下所有部门结构。输出格式预期为部门 ID 与名称的层级列表。
 
-# 查询子部门
-soke-cli assign +list-departments --parent-id "130110584"
-```
+> 该项为辅助查询，不直接参与指派创建，但可用于确认用户所属部门。
 
-**输出信息**:
-- 部门ID（用于创建指派）
-- 部门名称
-- 父部门ID
-- 成员数量
-- 子部门数量
-
----
-
-### 2. 查询用户列表
-
-查询可用的用户列表，用于指派前选择目标用户。
+### 2. 查询用户 `assign +list-users`
 
 ```bash
-soke-cli assign +list-users [flags]
+soke assign +list-users --department-id <departmentId>
 ```
 
-**参数**:
-- `--dept-id` - 部门ID
-- `--keyword` - 搜索关键词
-- `--search-target` - 搜索目标：name（姓名）/phone（手机号）/job_number（工号），默认：name
-- `--is-in` - 是否在权限范围内：0否/1是
-- `--is-new` - 是否新用户：0否/1是（默认：0）
-- `--page` - 页码（默认：1）
-- `--limit` - 每页数量（默认：20）
-
-**示例**:
-```bash
-# 查询所有用户
-soke-cli assign +list-users
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--department-id` | 否 | 按部门过滤，不传则返回全部用户 |
 
-# 查询指定部门的用户
-soke-cli assign +list-users --dept-id "130110584"
+返回用户列表，包含用户 ID、姓名、所属部门等基本信息。
 
-# 按姓名搜索
-soke-cli assign +list-users --keyword "张三" --search-target "name"
-
-```
-
-**输出信息**:
-- 用户ID（用于创建指派）
-- 姓名
-- 部门ID
-- 职位
-- 工号
-- 在职状态
-
----
-
-### 3. 创建指派
-
-将学习资源指派给部门、用户、群组、职位或角色。
+### 3. 创建指派 `assign +create`
 
 ```bash
-soke-cli assign +create [flags]
+soke assign +create \
+  --module course \
+  --module-id <courseId> \
+  --compulsory <1|0> \
+  --user-ids "<userId1>,<userId2>,<userId3>"
 ```
 
-**必填参数**:
-- `--module` - 模块类型：course（课程）、exam（考试）、learning_map（学习地图）
-- `--target-id` - 目标ID（如课程ID、考试ID等）
-
-**可选参数**:
-- `--learn-type` - 学习类型：required（必修）、optional（选修），默认：required
-- `--dept-ids` - 部门ID列表，逗号分隔
-- `--dept-names` - 部门名称列表，逗号分隔，与dept-ids对应
-- `--user-ids` - 用户ID列表，逗号分隔
-- `--user-names` - 用户名称列表，逗号分隔，与user-ids对应
-- `--message-content` - 通知消息内容
-- `--message-switch` - 消息开关：0关闭/1开启，默认：1
-
-**示例**:
-```bash
-# 指派课程给部门（必修）
-soke-cli assign +create \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
-  --dept-ids "130110584" \
-  --dept-names "研发部" \
-  --learn-type "required" \
-  --message-content "新课程已为您安排，请及时学习！"
-
-# 指派课程给用户
-soke-cli assign +create \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
-  --user-ids "1241453468881932" \
-  --user-names "张三" \
-  --learn-type "required"
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--module` | 是 | 固定值 `course` |
+| `--module-id` | 是 | 课程 ID |
+| `--compulsory` | 是 | `1` = 必修，`0` = 选修 |
+| `--user-ids` | 是 | 逗号分隔的用户 ID 列表 |
 
-# 同时指派给部门和用户
-soke-cli assign +create \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
-  --dept-ids "130110584,130110585" \
-  --dept-names "研发部,测试部" \
-  --user-ids "1241453468881932" \
-  --user-names "张三" \
-  --learn-type "required"
+> ⚠️ 课程必须 `status = 1`（已发布），否则指派会失败。
 
-# 指派考试给部门
-soke-cli assign +create \
-  --module "exam" \
-  --target-id "EXAM-UUID-12345" \
-  --dept-ids "130110584" \
-  --dept-names "研发部" \
-  --learn-type "required"
-
-# 创建选修课指派
-soke-cli assign +create \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
-  --dept-ids "130110584" \
-  --dept-names "研发部" \
-  --learn-type "optional"
-```
-
-**重要提示**:
-- 至少需要指定一种指派类型（部门或用户）
-- 支持批量指派，使用逗号分隔多个ID和名称
-- ID和名称的顺序要一一对应
-- 默认开启消息通知，可通过 `--message-switch 0` 关闭
-
----
-
-### 4. 查询指派列表
-
-查询已创建的指派记录。
+### 4. 查询指派 `assign +list`
 
 ```bash
-soke-cli assign +list [flags]
+soke assign +list --module-id <courseId>
 ```
 
-**参数**:
-- `--target-id` - 目标ID（筛选特定资源的指派）
-- `--module` - 模块类型：course/exam/learning_map等
-- `--learn-type` - 学习类型：required/optional
-- `--assign-type` - 指派类型：dept/user/group/position/role
-- `--keyword` - 搜索关键词（部门名、用户名等）
-- `--page` - 页码（默认：1）
-- `--limit` - 每页数量（默认：10）
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--module-id` | 是 | 课程 ID |
 
-**示例**:
-```bash
-# 查询特定课程的所有指派
-soke-cli assign +list \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271"
+返回该课程所有已指派的学员列表，包含用户信息、必修/选修标记、学习进度。
 
-# 查询特定课程的部门指派
-soke-cli assign +list \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
-  --assign-type "dept"
+## 输出标准
 
-# 按关键词搜索
-soke-cli assign +list \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
-  --keyword "研发"
+创建指派成功后输出：
 
-# 查询必修课指派
-soke-cli assign +list \
-  --module "course" \
-  --learn-type "required"
 ```
-
-**输出信息**:
-- 指派UUID
-- 指派对象名称
-- 指派类型
-- 目标ID
-- 学习类型
-- 创建时间
-- 创建人
-- 状态信息
-
----
-
-## 完整工作流
-
-### 场景1：为新员工培训课程创建指派
-
-```bash
-# 步骤1: 查询部门列表，找到目标部门
-soke-cli assign +list-departments --keyword "研发"
-# 输出：部门ID: 130110584, 部门名称: 研发部
-
-# 步骤2: 查询该部门的用户（可选）
-soke-cli assign +list-users --dept-id "130110584"
-# 输出：用户列表
-
-# 步骤3: 创建课程指派
-soke-cli assign +create \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
-  --dept-ids "130110584" \
-  --dept-names "研发部" \
-  --learn-type "required" \
-  --message-content "新员工培训课程已为您安排，请在一周内完成学习！"
-
-# 步骤4: 验证指派是否成功
-soke-cli assign +list \
-  --module "course" \
-  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271"
+✅ 指派创建成功
+- 课程: {courseTitle} (ID: {courseId})
+- 类型: {必修/选修}
+- 指派人数: {N} 人
+- 用户: {userName1}, {userName2}...
 ```
 
-### 场景2：为考试创建多维度指派
-
-```bash
-# 同时指派给部门和用户
-soke-cli assign +create \
-  --module "exam" \
-  --target-id "EXAM-UUID-12345" \
-  --dept-ids "130110584,130110585" \
-  --dept-names "研发部,测试部" \
-  --user-ids "1241453468881932" \
-  --user-names "张三" \
-  --learn-type "required" \
-  --message-content "年度考核考试已开放，请按时参加！"
-```
-
----
+查询操作以表格或列表形式输出结果。
 
 ## 注意事项
 
-1. **指派前准备**
-   - 确保目标资源已创建（如课程已发布）
-   - 使用 `+list-departments` 和 `+list-users` 查询可用的部门和用户
-   - 记录部门ID和用户ID用于创建指派
-
-2. **批量指派**
-   - 支持同时指派给多个对象
-   - 使用逗号分隔多个ID和名称
-   - ID和名称的顺序要一一对应
-
-3. **必修 vs 选修**
-   - 必修（required）：用户必须完成学习
-   - 选修（optional）：用户可选择性学习
-
-4. **消息通知**
-   - 默认开启消息通知
-   - 可自定义消息内容
-   - 可通过 `--message-switch 0` 关闭通知
-
-5. **权限要求**
-   - 需要具有指派的读写权限
-   - 只能查询和操作权限范围内的部门和用户
-
----
-
-## 常见问题
-
-### Q1: 如何获取课程ID？
-```bash
-soke-cli course +list-courses --page 1 --limit 10
-```
-
-### Q2: 如何获取部门ID？
-```bash
-soke-cli assign +list-departments --keyword "研发"
-```
+1. **课程必须先发布**（status=1）才能指派，未发布课程无法创建指派记录
+2. `--module` 当前仅支持 `course`，扩展模块后可能支持其他值
+3. 必修课（compulsory=1）学员不可跳过，选修课（compulsory=0）学员可自主选择
+4. 指派后可重复指派同一用户，以最新一次为准（覆盖更新）
+5. 批量指派建议单次 user-ids 不超过 500 人，超出分批处理
+6. 取消指派（删除指派记录）需通过后台操作，CLI 不直接支持
 
-### Q3: 如何获取用户ID？
-```bash
-soke-cli assign +list-users --dept-id "1" --keyword "张三"
-```
-
-### Q4: 指派失败怎么办？
-检查以下几点：
-1. 目标资源是否已发布
-2. 部门ID和用户ID是否正确
-3. 是否有足够的权限
-4. module 参数是否正确
-
-### Q5: 可以同时指派给多种类型吗？
-可以！在一次指派中可以同时指定部门、用户、群组、职位和角色。
-
----
-
-## API 接口
-
-本 skill 使用以下 API 接口：
-
-- `GET /skills/department/list` - 查询部门列表
-- `GET /skills/user/list` - 查询用户列表
-- `POST /skills/assignLog/create` - 创建指派
-- `GET /skills/assignLog/list` - 查询指派列表
-
-详细的 API 文档请参考 [API_PROXY_INTERFACES_2.0.md](../../docs/API_PROXY_INTERFACES_2.0.md)。
-
----
-
-## 相关 Skills
-
-- **soke-course** - 课程管理，创建和管理课程
-- **soke-exam** - 考试管理，创建和管理考试
-- **soke-learning-profile** - 学习地图管理
-
----
+## 检查清单
 
-**版本**: 1.0.0  
-**最后更新**: 2026-05-28
+- [ ] 课程 status = 1（已发布确认）
+- [ ] 已通过 list-departments / list-users 确认目标用户 ID
+- [ ] compulsory 正确设定（1=必修, 0=选修）
+- [ ] user-ids 为逗号分隔的有效用户 ID 列表
+- [ ] 指派完成后通过 assign +list 验证结果