@sokeai/cli 1.0.77 → 1.0.78

package/skills/multi/soke-task/references/shared.md

@@ -0,0 +1,185 @@
+---
+name: soke-shared
+summary: 授客CLI共享基础（配置/登录/权限/错误处理/安全规则）
+version: 1.0.0
+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-training-demand/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: soke-training-demand
+description: "授客学堂培训需求收集：通过 soke-cli training-demand 浏览需求列表、获取需求分类、分步引导提交培训需求（分类、标签、描述、紧急程度）以及为需求投票。当用户需要提交培训需求、浏览需求列表、给需求投票或查看需求分类时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  executionGuard:
+    - "提交培训需求时，MUST 严格按 4 步依次执行（1->2->3->4），每完成一步 MUST 等待用户回复后才能进入下一步。NEVER 跳步、NEVER 合并多步为一步、NEVER 在用户未回复时自行推进。"
+    - "步骤 2（选择标签）是独立步骤，NEVER 被跳过（除非分类 tag 为空/null）。即使用户在步骤 1 选择了分类，也 MUST 先展示标签列表让用户选择或跳过，然后才能进入步骤 3。"
+    - "每一步输出后 MUST STOP 等待用户输入。NEVER 在同一个回复中同时展示两个步骤的提示。"
+    - "NEVER 自行发挥、NEVER 添加 skill 未定义的步骤或提示文字。所有输出格式和提示语必须严格按本 skill 中常见工作流的定义，一字不差。"
+    - "步骤 2 展示标签时，MUST 严格使用步骤 1 中用户选定的那个分类对象（通过用户选择的序号从 +list-categories 返回的 data.list 数组中精确取出）的 tag 字段。NEVER 使用其他分类的 tag、NEVER 凭记忆猜测标签、NEVER 用列表中其他位置分类的 tag。"
+  cliHelp: "soke-cli training-demand --help"
+---
+
+# 培训需求收集
+
+**CRITICAL — 开始前 MUST 先读取 ./references/shared.md，其中包含认证、配置和权限处理。**
+
+## 🛑 执行守卫（EXECUTION GUARD）
+
+> **以下规则是硬性约束，违反任何一条即为执行错误：**
+>
+> 1. **逐步执行**：提交需求 MUST 严格按 4 步顺序（1->2->3->4）逐步引导，每步 MUST 等待用户回复后再进入下一步。NEVER 跳步、NEVER 合步。
+> 2. **步骤独立**：每个步骤 MUST 单独输出为一个回复。NEVER 在同一个回复中同时展示两个步骤的提示。步骤 1 输出后 STOP 等用户选分类；步骤 2 输出后 STOP 等用户选标签；步骤 3 输出后 STOP 等用户输入描述；步骤 4 输出后 STOP 等用户选紧急程度。
+> 3. **步骤 2 不可省略**：步骤 2（选择标签）是独立步骤，NEVER 被省略（除非分类 tag 为空/null）。NEVER 在步骤 1 的回复中同时展示标签选项。
+> 4. **严禁自行发挥**：所有提示语、输出格式 MUST 严格照搬本 skill 常见工作流中的定义，NEVER 自行发挥、NEVER 添加额外文字或解释、NEVER 改变提示格式。
+>
+> 5. **标签-分类严格绑定**：步骤 2 展示标签时，MUST 严格使用步骤 1 中用户选定的分类对象（通过序号从 +list-categories 的 data.list 中精确取出）的 tag 字段。NEVER 用其他分类的 tag、NEVER 凭记忆猜测、NEVER 用列表中其他位置分类的 tag。不确定时 MUST 重新调用 +list-categories 按序号精确匹配。
+
+## 核心规则
+
+- 分类、标签必须与管理后台设置完全一致，**禁止自行拓展或创造分类/标签**。标签来源仅限用户所选分类的 tag 字段。
+- 提交培训需求必须严格按以下 **4 步顺序** 引导用户，不可跳步或合并：
+  1. **选择分类**（单选） → 2. **选择标签**（选填，可多选≤5，可跳过，无标签时自动跳过） → 3. **填写培训需求**（≤200字，必填） → 4. **紧急程度**（1-5，选填）
+- 分类：从 +list-categories 返回的 data.list[].title 中选择，**仅限单选**，不可同时选多个分类。
+- 标签：从所选分类的 data.list[].tag 字段中按逗号拆分，编号列出供用户选择。**标签为选填，用户可以选择标签也可以不选直接跳过**。可多选最多5个。若该分类 tag 为空或不存在，提示"📌 该分类暂无标签"，自动跳过标签步骤进入步骤3。
+- 培训需求描述：即 --title，**必填，最多 200 字符**，纯文本输入。
+- 紧急程度：即 --level，1=普通、2=较普通、3=一般、4=较紧急、5=最紧急，**选填**，不选时默认 0（不设置等级）。
+- 投票前，先执行 +list，使用返回的培训需求 uuid。不要把分类 uuid 传给投票接口。
+- 创建和投票是写操作。用户意图不明确时，先确认要提交或投票的对象。
+- 默认用 --format json 获取结构化输出。
+
+### 提交成功后的展示规则
+- **不显示需求 UUID**：提交成功后向用户展示的详情表格中，不要包含 uuid 字段。UUID 仅用于内部投票等操作，不向用户暴露。
+- **时间加8小时**：API 返回的 create_time 是 UTC 时间，向用户展示时必须加 8 小时转换为 UTC+8（北京时间）。例如返回 "2026-07-23 01:56:31" 应展示为 "2026-07-23 09:56:31"。
+
+### 标签处理规则
+
+- **隐藏接口字段**：所选分类的 tag 字段原始值是接口内部数据，**严禁在对话中向用户展示**（如不得出现"所选分类的 tag 字段为：公司介绍,规章制度"之类的话）。步骤 2 只展示编号后的标签选项列表，不暴露原始 tag 字段值或任何接口字段名。
+
++list-categories 返回的每个分类对象中 tag 字段是一个逗号分隔的字符串，例如 "企业文化培训,企业发展历程培训,营销战略发展规则培训"。提交需求时：
+- **标签来源仅限当前分类**：从用户所选的那个分类的 tag 字段按逗号拆分出所有可选标签，编号列出供用户选择。**严禁跨分类混合标签或自行创造标签**。
+- **🛑 标签-分类严格绑定（防错硬约束）**：步骤 2 展示标签时，MUST 从步骤 1 中用户选定的分类对象（即 +list-categories 返回的 data.list 中，按用户选择的序号精确匹配的那一条）的 tag 字段按逗号拆分。NEVER 使用其他分类的 tag 字段、NEVER 凭记忆猜测标签内容、NEVER 用列表中其他位置分类的 tag。如果记忆可能出错或不确定，MUST 重新执行 +list-categories 并严格按序号匹配对应分类对象后再拆分其 tag。
+- 用户选中后，将选中的标签用逗号拼接传给 --tag。
+- **标签选填**：标签为选填项，用户可以选择标签也可以**不选任何标签直接跳过**。跳过时不传 --tag（CLI 会从 --category-tag 自动合并）。用户输入"0"、"不选"、"跳过"等表示不选择标签，直接进入步骤 3。
+- **最多选 5 个标签**：选择超过5个时提醒"❌ 最多只能选择5个标签，请减少选择"。
+- **无标签时自动跳过**：若所选分类的 tag 为空字符串（""）或不存在/为 null，提示"📌 该分类暂无标签，无需选择"，自动跳过步骤 2 进入步骤 3。
+- --category-tag 必须传所选分类的原始完整 tag 字段值（未拆分、未修改）。
+
+## 命令
+
+### 查询培训需求列表
+
+```bash
+soke-cli training-demand +list \
+  --page 1 \
+  --limit 10 \
+  --status 1 \
+  --keyword "" \
+  --is-owner 0 \
+  --create-time-order desc \
+  --owner-vote 0 \
+  --format json
+```
+
+列表返回的 data.list[].uuid 是投票使用的培训需求 UUID。
+
+### 查询培训需求分类
+
+```bash
+soke-cli training-demand +list-categories --format json
+```
+
+分类返回的 data.list[].uuid、data.list[].title 和 data.list[].tag 只用于创建需求。
+
+### 提交培训需求
+
+单分类提交时使用 --category-uuid：
+
+```bash
+soke-cli training-demand +create \
+  --title "门店销售沟通训练" \
+  --tag "职场心态,需求测试" \
+  --level 0 \
+  --category-uuid "FA0C937C-EE52-463B-BE3A-C13F96C426AE" \
+  --format json
+```
+
+- --title：培训需求描述，**必填，最多 200 字符**。
+- --tag：从所选分类 tag 中用户选中的标签，逗号拼接；不传时 CLI 从 --category-tag 自动合并。
+- --level：紧急程度，1=普通、5=最紧急，**选填**，默认 0。
+- --category-uuid：所选分类的 uuid。
+- 分类为单选，不使用 --category-list。
+
+### 给培训需求投票
+
+```bash
+soke-cli training-demand +vote \
+  --uuid "41EA8B23-5E5E-48FD-99A3-FF8F420752A6" \
+  --format json
+```
+
+--uuid 必须来自 +list 返回的需求 UUID。
+
+## 常见工作流
+
+### 提交培训需求（严格 4 步流程）
+
+用户说"我想提一个培训需求"或类似意图时，**必须**按以下 4 步依次引导，不可跳步：
+
+**步骤 1 — 选择分类（单选）**
+**🛑 本步骤 MUST 单独输出，NEVER 与步骤 2 合并在同一回复中。**
+
+1. 执行 soke-cli training-demand +list-categories --format json。
+2. 将返回的 data.list[].title 编号列出，格式严格如下（NEVER 自行发挥格式）：
+   ```
+   请选择培训需求分类（单选）：
+   1. 企业文化
+   2. 职业素养
+   3. 企业培训
+   ...
+   ```
+   让用户**单选一个分类**。
+3. 记录用户所选分类的 uuid、title 和 tag（原始完整值）。
+4. **🛑 STOP HERE** — 等待用户选择分类后，再进入步骤 2。NEVER 在同一回复中展示步骤 2 的标签列表。
+
+**步骤 2 — 选择标签（选填，可多选≤5，可跳过；无标签时自动跳过）**
+**🛑 本步骤 MUST 单独输出，NEVER 与步骤 1 合并在同一回复中。**
+
+1. **展示分类标签**：从步骤 1 记录的所选分类 tag 字段中按逗号拆分，编号列出所有可选标签。**严禁在对话中暴露 tag 字段原始值或接口字段名**，只展示编号列表供用户选择。格式示例：
+   **🛑 关键防错**：MUST 确保标签来自步骤 1 中用户选定分类对象的 tag 字段。用户选择分类序号 N 后，MUST 从 +list-categories 返回的 data.list[N-1]（序号从1开始，数组索引从0开始）取出分类对象，然后用其 tag 字段拆分展示。NEVER 凭记忆选其他分类的 tag、NEVER 用序号偏移后的分类。如不确定，必须重新调用 +list-categories 并严格按序号匹配。
+   ```
+   请选择标签（选填，可多选，最多5个，也可不选直接跳过）：
+   1. 企业文化培训
+   2. 企业发展历程培训
+   3. 营销战略发展规则培训
+   ...
+
+   请输入序号（多选用逗号分隔，如 1,3,5；不选可输入"0"或"跳过"）
+   ```
+2. **无标签判断**：若所选分类的 tag 为空字符串（""）或不存在/为 null，直接显示：
+   ```
+   📌 该分类暂无标签，无需选择
+   ```
+   然后自动跳过步骤 2，进入步骤 3。
+3. **选填，可跳过**：标签为选填项，用户可以选择标签也可以**不选任何标签直接跳过**。用户输入"0"、"不选"、"跳过"等表示不选择标签，直接进入步骤 3。
+4. **多选交互**：让用户输入序号多选标签（如"1,3,5"），最多选 5 个；选择超过 5 个时提醒"❌ 最多只能选择5个标签，请减少选择"。
+5. **确认选择**：若用户选择了标签，简要展示确认（如"✅ 已选择标签：企业文化培训, 营销战略发展规则培训"），提交时用逗号拼接为 --tag 参数值。若用户跳过，显示"⏭ 未选择标签，继续下一步"。
+6. **⚠️ 重要**：标签来源仅限当前所选分类的 tag 字段，严禁跨分类混合标签或自行创造标签。
+7. **🛑 STOP HERE** — 等待用户选择/跳过标签后，再进入步骤 3。NEVER 在同一回复中同时展示步骤 3 的提示。
+
+**步骤 3 — 填写培训需求描述（必填，≤200字符）**
+**🛑 本步骤 MUST 单独输出，NEVER 与步骤 2 合并在同一回复中。**
+
+1. 提示用户输入培训需求描述（纯文本），提示语严格如下（NEVER 自行发挥）：
+   ```
+   请输入培训需求描述（必填，最多200字符）：
+   ```
+2. 记录输入内容，即 --title 参数值。
+3. 若用户输入超过 200 字符，提醒"❌ 需求描述最多200字符，请缩短或重新填写"。
+4. **🛑 STOP HERE** — 等待用户输入需求描述后，再进入步骤 4。NEVER 在同一回复中同时展示步骤 4 的提示。
+
+**步骤 4 — 紃急程度（选填）**
+**🛑 本步骤 MUST 单独输出，NEVER 与步骤 3 合并在同一回复中。**
+
+1. 提示用户选择紧急程度，提示语严格如下（NEVER 自行发挥）：
+   ```
+   请选择紧急程度（选填，不选默认为0）：
+   1 = 普通
+   2 = 较普通
+   3 = 一般
+   4 = 较紧急
+   5 = 最紧急
+
+   输入数字或输入"0"/"跳过"表示不设置
+   ```
+2. 不选则默认 0（不设置等级）。用户输入"0"或"跳过"表示不设置。
+3. 记录选择值，即 --level 参数值。
+
+**最终提交**
+用步骤 1-4 收集的数据执行 +create。提交前可向用户展示汇总确认。
+
+### 投票需求
+
+用户说"帮我给某个需求投票"：
+- 执行 +list --keyword "<关键词>" --format json。
+- 用需求标题和创建人等信息确认目标。
+- 执行 +vote --uuid "<需求uuid>"。
+
+### 浏览需求
+
+用户只想浏览需求：
+- 执行 +list --page 1 --limit 10 --create-time-order desc。
+- 返回标题、分类、标签、票数、是否已投票和需求 UUID。
+
+## 字段依赖
+
+| 场景 | 依赖字段 | 来源 |
+|------|----------|------|
+| 创建需求 | --category-uuid / --tag / --title / --level | +list-categories 的 data.list[] + 用户输入 |
+| 投票 | uuid | +list 的 data.list[].uuid |
+
+## 排错
+
+- 创建失败提示分类无效：重新执行 +list-categories，不要自行手写分类 UUID。
+- 创建失败提示标签无效：重新执行 +list-categories，从所选分类返回的 tag 中选择，不要自行编写标签。**确保 --category-tag 传的是原始完整 tag 字段值**。
+- 投票失败提示需求无效：确认传入的是培训需求 UUID，不是分类 UUID。
+- 鉴权失败：按 soke-shared 执行 soke-cli auth login 后重试。