@sokeai/cli 1.0.77 → 1.0.79

package/skills/multi/soke-exam/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-exam-question-pool/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: soke-exam-question-pool
+description: "授客学堂题库答题练习：通过 soke-cli exam-question-pool 分页拉取可练习题库列表，选择题库后随机逐题出题、实时判分并反馈进度。支持填空、判断、单选、多选、不定项五种题型，答题状态本地持久化。当用户需要刷题、题库练习、随机答题或查看答题进度时使用。"
+metadata:
+  requires:
+    bins: [soke-cli]
+  cliHelp: soke-cli exam-question-pool --help
+---
+
+# 可练习题库交互式练习系统
+
+核心链路全量分页选库随机逐题实时反馈
+
+## 交互流程总览
+
+用户触发练习Step1全量分页拉取全部题库展示供选择Step2用户选择一个题库Step3拉取该题库全部题目加载答题状态Step4从未答题目中随机抽一道呈现判分Step5询问下一题结束重开循环Step4
+
+## Step1全量分页拉取题库列表
+
+soke-cli exam-question-pool +list --page 1 --page-size 100 --status 1 --format json
+
+循环拉取检查data.hasMore若为1则继续翻页直到hasMore为0合并所有页data.list按uuid去重
+重要API分页存在跨页重叠bug相邻两页可能返回相同uuid的题库必须按uuid去重不能简单拼接
+优先使用page-size100一次拉全减少分页次数和重叠风险
+
+### 展示规则
+
+每个题库一行选项只显示序号和题库名称格式为title
+不要显示题目数question_count和状态pass_status
+题库总数小于等于20一次性展示全部
+题库总数大于20分页展示每页最多20个末尾追加下一页翻到底后追加上一页
+
+## Step2用户选择题库
+
+用户输入编号取pool_id为选中项的uuid
+若用户说随机选一个从未完成题库中随机选全部完成则全量随机
+
+## Step3拉取题目和初始化状态
+
+soke-cli exam-question-pool +questions --pool-id UUID --format json
+
+注意pool-id的值不要加引号否则会报参数格式错误
+
+提取data.content中所有题目uuid type title choices answer show_answer analysis
+
+### 答题状态文件
+
+路径C:\Users\soke\.qclaw\workspace\.exam-state\{pool-uuid}.json
+
+格式pool_id uuid pool_title 题库名 total 5 correct 0 answered 空数组
+
+文件不存在或pool_id不匹配新建answered为空数组
+答完一题追加uuid到answered正确则correct加1
+结束答题保留state
+重新开始清空answered为空数组correct为0
+answered长度大于等于total自动提示本轮全部答完
+已展示但未作答的题目不算已答用户在题目展示后说退出结束退出答题等该题不计入answered不计入correct不出现在本轮总结表格中只有用户实际选择了选项或输入了答案并提交才算作答
+
+## Step4随机出题和呈现
+
+### 随机逻辑
+
+从data.content排除answered中已有uuid
+剩余题目随机选一道
+每次进入题库出题顺序随机不固定
+
+### 用户输出红线
+
+严禁在面向用户的任何输出中暴露内部标识字段包括但不限于uuid pool_id source_id category_id target_id dept_user_id company_id answer_type display
+这些字段仅用于内部逻辑和状态文件不要出现在题目展示判分反馈进度统计小结表格或任何用户可见的文本中
+如果需要区分题目在内部用uuid但在用户界面只用序号或题目内容来标识
+用户看到的内容应该像正常的练习题一样干净简洁没有任何技术性ID字段
+
+### 按题型呈现
+
+A填空题type fill文本输入禁止变选择题
+纯文本呈现题目提示用户输入答案
+题目展示标题填空题第X题共N题题目将title中的span标签替换为括号加下划线提示多个空请用英文逗号分隔如答案1答案2答案3
+重要提示示例绝不能使用当前题目的正确答案只能用答案1答案2答案3等占位符
+填空判分show_answer为二维数组用户逗号分隔答案按序对应每个空匹配子数组中任一值即算对忽略首尾空格大小写不敏感全对正确部分对逐空标注全错错误
+
+B判断题type determine
+标题判断题第X题共N题选项A正确B错误判分show_answer A正确B错误
+
+C单选题type single_choice
+标题单选题第X题共N题选项A choices0 title B choices1 title等判分show_answer如A用户选了选项A即对
+
+D多选题type choice
+标题多选题第X题共N题选项同单选判分用户所选字母集合与show_answer字母集合完全一致顺序无关
+
+E不定项选择type uncertain_choice
+同多选题标题标注不定项选择
+
+## Step5判分反馈和循环
+
+答完后纯文本反馈正确或错误你的答案正确答案解析如有进度已答n题共total题正确m题pct百分比
+然后询问下一步下一题结束答题重新开始本轮
+下一题保存状态回到Step4
+结束答题保存状态显示本轮小结退出当前题目未作答则不计入总结
+重新开始本轮清空answered和correct回到Step4
+本轮答完时仅提供重新开始和结束
+
+### 本轮小结规则
+
+总结表格只包含实际作答的题目即uuid已写入answered的题目
+已展示但用户说退出未作答的题目不出现在总结中下次进入该题库时仍会出现
+进度统计以状态文件中的answered和correct为准不要自行脑补
+
+## Shortcuts参考
+
+list获取可练习题库列表
+get获取题库详情
+questions获取题库全部题目
+
+## 重要注意
+
+data.content数量可能与all_count不一致过滤题以实际返回为准
+填空show_answer是string二维数组每空可能有多个可接受值
+状态文件路径C:\Users\soke\.qclaw\workspace\.exam-state\uuid.json先确保目录存在
+每次出题前根据当前状态重新计算未答题池保证随机性
+填空题提示示例不能泄露正确答案统一用答案1答案2答案3占位