@sokeai/cli 1.0.76 → 1.0.78

package/skills/multi/soke-shared/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: soke-shared
+description: "授客CLI共享基础：应用配置初始化、认证登录（auth login）、权限管理、错误处理、安全规则。当用户需要第一次配置（soke-cli auth login）、使用登录授权（soke-cli auth login）、遇到权限不足、或首次使用soke-cli时触发。"
+---
+
+# soke-cli 共享规则
+
+本技能指导你如何通过soke-cli操作授客AI资源，以及有哪些注意事项。
+
+## 配置初始化
+
+首次使用需运行 `soke-cli auth login` 完成应用配置。
+
+当你帮用户初始化配置时，引导用户按照交互式提示完成配置：
+
+```bash
+# 初始化配置
+soke-cli auth login
+```
+
+配置项包括：
+- `app_id`: 开放平台应用ID
+- `app_key`: 开放平台应用Key
+- `app_secret`: 开放平台应用Secret
+- `api_base_url`: API地址（默认: https://opendev.soke.cn）
+- `corpid`: 企业ID
+
+配置文件保存在 `~/.soke-cli/config.json`
+
+## 认证
+
+### 用户登录
+
+用户需要通过OAuth授权获取访问令牌：
+
+```bash
+# 用户登录授权
+soke-cli auth login
+```
+
+登录成功后，`access_token` 和 `refresh_token` 会自动保存到配置文件中。
+
+### Token管理
+
+- **access_token**: 用户访问令牌，用于调用API
+- **refresh_token**: 刷新令牌，用于获取新的access_token
+- Token过期后需要重新执行 `soke-cli auth login`
+
+### 查看当前配置
+
+```bash
+# 查看当前配置（不显示敏感信息）
+soke-cli config show
+```
+
+## 权限不足处理
+
+遇到权限相关错误时，通常有以下几种情况：
+
+### 1. 未登录或Token过期
+
+**错误特征**: 返回401 Unauthorized或Token无效
+
+**解决方案**:
+```bash
+soke-cli auth login
+```
+
+### 2. 缺少必要权限
+
+**错误特征**: 返回403 Forbidden或权限不足提示
+
+**解决方案**:
+- 联系管理员在开放平台后台为应用开通相应权限
+- 确认企业ID（corpid）和应用配置正确
+
+### 3. 参数错误
+
+**错误特征**: 返回400 Bad Request或参数验证失败
+
+**解决方案**:
+- 检查必需参数是否提供
+- 使用 `--help` 查看命令参数说明
+- 参考API文档确认参数格式
+
+## 命令结构
+
+### Shortcuts（推荐）
+
+Shortcuts是对常用操作的高级封装，参数友好，最适合AI Agent调用：
+
+```bash
+soke-cli <service> +<verb> [flags]
+```
+
+示例：
+```bash
+soke-cli exam +get-exam-user --exam-id exam123 --dept-user-id user456
+soke-cli course +list-courses --page 1 --page-size 10
+```
+
+### 通用API调用
+
+支持直接调用任意API：
+
+```bash
+soke-cli api <METHOD> <path> [--data <json>] [--params <json>]
+```
+
+示例：
+```bash
+soke-cli api GET /users/me
+soke-cli api POST /some/endpoint --data '{"key": "value"}'
+```
+
+## 输出格式
+
+### JSON格式（默认）
+
+所有命令默认输出JSON格式，便于程序解析：
+
+```bash
+soke-cli exam +list-exams --format json
+```
+
+### 表格格式
+
+部分命令支持表格格式输出，更易读：
+
+```bash
+soke-cli exam +list-exams --format table
+```
+
+## 安全规则
+
+- **禁止输出密钥**（app_secret、access_token）到终端明文
+- **写入/删除操作前必须确认用户意图**
+- 敏感操作建议先使用 `--dry-run`（如果支持）预览
+
+## 错误处理
+
+当命令执行失败时：
+
+1. **检查配置**: 运行 `soke-cli config show` 确认配置正确
+2. **检查登录状态**: 如果是认证错误，运行 `soke-cli auth login`
+3. **检查参数**: 使用 `soke-cli <service> <command> --help` 查看参数说明
+4. **查看错误信息**: 错误响应中通常包含详细的错误原因
+
+## 常见问题
+
+### Q: 如何获取app_key和app_secret？
+
+A: 登录授客AI开放平台（https://opendev.soke.cn），创建应用后即可获取。
+
+### Q: Token过期了怎么办？
+
+A: 重新执行 `soke-cli auth login` 进行授权。
+
+### Q: 如何切换企业？
+
+A: 运行 `soke-cli auth login` 重新配置，或直接编辑 `~/.soke-cli/config.json` 文件。
+
+### Q: 支持哪些业务模块？
+
+A: 目前支持以下模块：
+- `contact`: 组织架构（部门、用户、岗位、讲师）
+- `course`: 课程管理
+- `exam`: 考试管理
+- `training`: 培训管理
+- `learning_map`: 学习地图
+- `credit`: 学分管理
+- `point`: 积分管理
+- `news`: 资讯管理
+- `certificate`: 证书管理
+- 等等...
+
+每个模块都有对应的Skill，AI Agent会根据用户意图自动选择。
+
+## 相关链接
+
+- 授客AI开放平台: https://opendev.soke.cn
+- NPM包: @sokeai/cli
+- 代码仓库: https://codeup.aliyun.com/5edbc121d1d1abe63b55f1c7/soke/soke-cli.git

package/skills/multi/soke-supervisor/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: soke-supervisor
+description: "授客 AI 督导模块：通过 soke-cli supervisor 对接督导场景接口，覆盖场景列表、创建草稿、选择评分标准、更新配置、部门/成员查询、创建指派、发布、详情、关闭前检查和关闭。当用户需要创建或维护 AI 督导场景、配置督导评分标准、给用户或部门指派督导任务、发布或关闭督导场景时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli supervisor --help"
+---
+
+# AI 督导模块 (supervisor)
+
+**CRITICAL — 开始前 MUST 先读取 [`./references/shared.md`](./references/shared.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`。