@sokeai/cli 1.0.73 → 1.0.74

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/skills/soke-exam-question-pool/SKILL.md +76 -45
  3. package/skills/soke-task/SKILL.md +29 -9
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sokeai/cli",
3
- "version": "1.0.73",
3
+ "version": "1.0.74",
4
4
  "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
5
5
  "bin": {
6
6
  "soke-cli": "scripts/run.js"
package/skills/soke-exam-question-pool/SKILL.md CHANGED
@@ -1,35 +1,37 @@
1
1
  ---
2
2
  name: soke-exam-question-pool
3
- summary: 授客可练习题库查询（题库列表、题库详情、题目列表），通过 soke-cli exam-question-pool 命令操作
4
- version: 1.0.0
5
- description: "授客可练习题库查询：按 examQuestionPool 接口链路先查询题库列表，再用题库 uuid 查询详情和题目列表。当用户需要查看可练习题库、题库详情、题目内容、答案和解析时使用。 | Soke question pool lookup: use the examQuestionPool API flow to list pools, get pool detail, and list questions."
3
+ summary: 授客可练习题库（题库列表、题库详情、题目列表、题库练习交卷），通过 soke-cli exam-question-pool 命令操作
4
+ version: 1.1.0
5
+ description: "授客可练习题库：按 examQuestionPool 接口链路先查询题库列表，再用题库 uuid 查询详情、题目列表，可进行题库练习交卷。当用户需要查看可练习题库、题库详情、题目内容、答案和解析，或提交题库练习交卷时使用。 | Soke question pool: use the examQuestionPool API flow to list pools, get pool detail, list questions, and finish a practice session."
6
6
  metadata:
7
7
  requires:
8
8
  bins: ["soke-cli"]
9
9
  cliHelp: "soke-cli exam-question-pool --help"
10
10
  ---
11
11
 
12
- # 可练习题库查询 (examQuestionPool)
12
+ # 可练习题库 (examQuestionPool)
13
13
 
14
14
  **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
15
15
 
16
16
  ## 核心链路
17
17
 
18
- 这组命令对接 `/skills/examQuestionPool/...` 接口。调用顺序必须固定：
18
+ 这组命令对接 `/skills/examQuestionPool/...` 接口。推荐调用顺序：
19
19
 
20
- 1. `+list` 获取题库列表，从 `data.list[].uuid` 取题库 UUID。
21
- 2. `+get --pool-id <uuid>` 查询详情，确认 `data.info.uuid` 与传入 `pool-id` 一致。
20
+ 1. `+list` 获取题库列表，从默认输出的 `uuid` 取题库 UUID。
21
+ 2. `+get --pool-id <uuid>` 查询详情，确认题库列表的 `uuid` 与传入 `pool-id` 一致。
22
22
  3. `+questions --pool-id <uuid>` 使用同一个 `pool-id` 查询题目。
23
+ 4. `+finish --pool-id <uuid> --answers '<答案JSON>'` 进行题库练习交卷。
23
24
 
24
- `--page`、`--page-size`、`--status` 只用于第一步列表分页和筛选，不要传给详情或题目查询。
25
+ `--page`、`--page-size` 用于第一步题库列表分页查询。
25
26
 
26
27
  ## Shortcuts 总览
27
28
 
28
29
  | Shortcut | 说明 |
29
30
  |----------|------|
30
- | `+list` | 获取可练习题库列表，返回后续 `pool-id` 所需的 `uuid` |
31
+ | `+list` | 获取可练习题库列表，返回后续 `pool-id` 所需的题库 `uuid` |
31
32
  | `+get` | 根据题库 `pool-id` 获取可练习题库详情 |
32
- | `+questions` | 根据同一个 `pool-id` 获取题库题目 |
33
+ | `+questions` | 根据 `pool-id`(题库id)，即题库列表的 `uuid`，获取题库题目 |
34
+ | `+finish` | 根据 `pool-id` 进行题库练习交卷 |
33
35
 
34
36
  ## +list
35
37
 
@@ -38,25 +40,23 @@ metadata:
38
40
  ```bash
39
41
  soke-cli exam-question-pool +list \
40
42
  --page 1 \
41
- --page-size 10 \
42
- --status 1 \
43
- --format json
43
+ --page-size 10
44
44
  ```
45
45
 
46
46
  | 参数 | 必需 | 说明 |
47
47
  |------|------|------|
48
48
  | `--page` | 否 | 页码，从 1 开始，默认 1 |
49
49
  | `--page-size` | 否 | 每页条数，默认 10 |
50
- | `--status` | 否 | 状态筛选，`1` 表示启用 |
51
50
 
52
- 关键返回字段：
51
+ 默认输出为横向单行文本，每条题库数据显示：
53
52
 
54
53
  | 字段 | 说明 |
55
54
  |------|------|
56
- | `data.list[].uuid` | 题库 UUID，后续作为 `--pool-id` |
57
- | `data.list[].title` | 题库标题 |
58
- | `data.list[].question_count` | 题目数量 |
59
- | `data.list[].category_title` | 分类名称 |
55
+ | `uuid` | 题库 UUID，后续作为 `--pool-id` |
56
+ | `title` | 题库标题 |
57
+ | `description` | 题库描述，默认会清理简单 HTML 标签和换行 |
58
+ | `题目数量` | 来自 `question_count` |
59
+ | `创建时间` | 来自 `create_exercise_time` |
60
60
 
61
61
  ## +get
62
62
 
@@ -64,25 +64,24 @@ soke-cli exam-question-pool +list \
64
64
 
65
65
  ```bash
66
66
  soke-cli exam-question-pool +get \
67
- --pool-id "<上一步 data.list[].uuid>" \
68
- --format json
67
+ --pool-id "<上一步题库列表的 uuid，即题库id>"
69
68
  ```
70
69
 
71
70
  | 参数 | 必需 | 说明 |
72
71
  |------|------|------|
73
- | `--pool-id` | 是 | 题库 ID，必须来自 `+list` 的 `data.list[].uuid` |
72
+ | `--pool-id` | 是 | 题库 ID，必须来自 `+list` 默认输出中的 `uuid` |
74
73
 
75
- 关键返回字段：
74
+ 默认输出为横向单行文本，题库详情数据：
76
75
 
77
76
  | 字段 | 说明 |
78
77
  |------|------|
79
- | `data.info.uuid` | 题库 UUID，应与请求 `--pool-id` 一致 |
80
- | `data.info.title` | 题库标题 |
81
- | `data.all_count` | 题库总题数 |
82
- | `data.point` | 积分配置 |
83
- | `data.examPoolUser` | 当前用户在题库中的状态 |
84
- | `data.question_url` | 题库题目 JSON 地址 |
85
- | `data.answer_url` | 题库答案 JSON 地址 |
78
+ | `uuid` | 题库 UUID，应与请求 `--pool-id` 一致 |
79
+ | `title` | 题库标题 |
80
+ | `description` | 题库描述，默认会清理简单 HTML 标签和换行 |
81
+ | `题目数量` | 来自 `question_count` |
82
+ | `创建时间` | 来自 `create_exercise_time` |
83
+ | `总题数` | 来自 `data.all_count` |
84
+
86
85
 
87
86
  ## +questions
88
87
 
@@ -90,35 +89,67 @@ soke-cli exam-question-pool +get \
90
89
 
91
90
  ```bash
92
91
  soke-cli exam-question-pool +questions \
93
- --pool-id "<同一个题库 uuid>" \
94
- --format json
92
+ --pool-id "<题库列表的 uuid，即题库id>"
95
93
  ```
96
94
 
97
95
  | 参数 | 必需 | 说明 |
98
96
  |------|------|------|
99
97
  | `--pool-id` | 是 | 题库 ID，复用列表或详情中的同一个 UUID |
100
98
 
101
- 关键返回字段：
99
+ 默认输出为 JSON，是题目数据本身。
100
+
101
+ 关键字段：
102
102
 
103
103
  | 字段 | 说明 |
104
104
  |------|------|
105
- | `data.pool_id` | 题库 ID，应与请求 `--pool-id` 一致 |
106
- | `data.content[].uuid` | 题目 UUID |
107
- | `data.content[].title` | 题目标题 |
108
- | `data.content[].type` | 题目类型 |
109
- | `data.content[].choices` | 选项列表 |
110
- | `data.content[].show_answer` | 展示答案 |
111
- | `data.content[].analysis` | 题目解析 |
105
+ | `uuid` | 题目 UUID |
106
+ | `title` | 题目标题 |
107
+ | `type` | 题目类型 |
108
+ | `choices` | 选项列表 |
109
+ | `show_answer` | 展示答案 |
110
+ | `analysis` | 题目解析 |
112
111
 
113
112
  ## 推荐操作顺序
114
113
 
115
114
  ```bash
116
- # 1. 查询题库列表，取 data.list[0].uuid
117
- soke-cli exam-question-pool +list --page 1 --page-size 10 --status 1 --format json
115
+ # 1. 查询题库列表，取输出中的 uuid
116
+ soke-cli exam-question-pool +list --page 1 --page-size 10
118
117
 
119
118
  # 2. 查询题库详情
120
- soke-cli exam-question-pool +get --pool-id "<pool_uuid>" --format json
119
+ soke-cli exam-question-pool +get --pool-id "<pool_uuid>"
120
+
121
+ # 3. 查询同一题库的题目列表
122
+ soke-cli exam-question-pool +questions --pool-id "<pool_uuid>"
121
123
 
122
- # 3. 查询同一题库的题目
123
- soke-cli exam-question-pool +questions --pool-id "<pool_uuid>" --format json
124
+ # 4. 题库练习交卷
125
+ soke-cli exam-question-pool +finish \
126
+ --pool-id "<pool_uuid>" \
127
+ --answers '{"<question_uuid>":[0,1]}'
124
128
  ```
129
+
130
+ ## +finish
131
+
132
+ 提交可练习题库练习交卷。
133
+
134
+ ```bash
135
+ soke-cli exam-question-pool +finish \
136
+ --pool-id "70DE9AFB-1C18-4F5C-B158-E25182ECBE1A" \
137
+ --answers '{"A93647C7-7ECF-44D6-931D-DE84344DA580":["1","1","1"],"0E7E8283-EB5F-489C-9778-34A9B2F13BA7":[0]}'
138
+ ```
139
+
140
+ | 参数 | 必需 | 说明 |
141
+ |------|------|------|
142
+ | `--pool-id` | 是 | 题库 ID，复用列表或详情中的同一个 UUID |
143
+ | `--answers` | 是 | 答案 JSON 原文，key 为题目 ID，数组为答题选项 |
144
+
145
+ `--answers` 会加密之后进行传输。
146
+
147
+ 返回结果默认展示：
148
+
149
+ | 字段 | 说明 |
150
+ |------|------|
151
+ | `rightCount` | 答对题目数 |
152
+ | `allCount` | 全部题目数量 |
153
+ | `rate` | 题库练习进度 |
154
+
155
+ 默认输出示例：`题库id:70DE9AFB-1C18-4F5C-B158-E25182ECBE1A，答对题目数：2，全部题目数量：0，题库练习进度：0%`。使用 `--format json` 时输出接口原始字段。
package/skills/soke-task/SKILL.md CHANGED
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: soke-task
3
- summary: 授客学堂异步任务管理（创建任务/查询任务），支持学习地图学员统计导出
3
+ summary: 授客学堂异步任务管理（创建任务/查询任务），支持学习地图学员统计报表和统计生成
4
4
  version: 1.0.0
5
- description: "授客学堂异步任务管理：通过独立 task 命令创建和查询异步导出任务。目前支持学习地图学员统计导出任务，按“创建任务 -> 获取 data.id -> 查询任务详情和 filePath”的流程使用。当用户需要导出学习地图学员统计、查询导出任务状态、获取导出文件下载地址时使用。 | Soke Academy async task management: create and query export jobs through the standalone task command. Currently supports learning map learner statistics export tasks. Use when users need to export learner statistics, check export task status, or obtain exported file URLs."
5
+ description: "授客学堂异步任务管理：通过独立 task 命令创建和查询异步任务。目前支持学习地图学员统计报表和统计生成，按“创建任务 -> 获取 data.id -> 查询任务详情和 filePath”的流程使用。当用户需要生成学习地图学员统计报表、生成统计、查询任务状态或获取文件下载地址时使用。 | Soke Academy async task management: create and query jobs through the standalone task command. Currently supports learning map learner statistics report/statistics generation. Use when users need to generate learner statistics reports, generate statistics, check task status, or obtain file URLs."
6
6
  metadata:
7
7
  requires:
8
8
  bins: ["soke-cli"]
@@ -18,11 +18,12 @@ metadata:
18
18
  - 任务接口是独立模块，命令统一使用 `soke-cli task ...`，不要使用 `soke-cli learning-map ...` 创建或查询任务。
19
19
  - 创建任务后必须保存返回的 `data.id`，再调用 `+get` 查询任务详情。
20
20
  - 默认用 `--format json` 获取结构化输出；需要人工快速查看时可省略 format 输出表格。
21
- - 当前已知任务类型是学习地图学员统计导出，`--module` 默认 `learningMapUser`，`--action` 默认 `export`，`--type` 默认 `aloneDept`。
21
+ - 当前已知任务类型是学习地图学员统计相关任务，`--module` 默认 `learningMapUser`，`--action` 默认 `export`，`--type` 默认 `aloneDept`。
22
+ - 查询 `soke-cli task +get --id "TASK-ID"` 后，必须根据创建任务时传入的 `--action` 判断状态字段：`action=export` 看 `data.export_status`，`action=report` 看 `data.status`。
22
23
 
23
24
  ## 命令
24
25
 
25
- ### 创建学习地图学员统计导出任务
26
+ ### 创建学习地图学员统计任务
26
27
 
27
28
  ```bash
28
29
  soke-cli task +create \
@@ -44,8 +45,10 @@ soke-cli task +create \
44
45
  | `--learn-status` | 否 | 空 | 学习状态筛选：空值表示不限，`learning` 未完成，`finished` 已完成 |
45
46
  | `--eligible-status` | 否 | 空 | 达标状态筛选，空值表示不限 |
46
47
  | `--limit` | 否 | `4500` | 任务处理上限 |
47
- | `--action` | 否 | `export` | 操作类型，导出任务固定为 `export` |
48
+ | `--action` | 否 | `export` | 操作类型：`export` 生成报表，`report` 生成统计 |
48
49
  | `--type` | 否 | `aloneDept` | 部门导出类型：`aloneDept` 单列导出，`manyDept` 部门多列导出 |
50
+ | `--is-leave` | 否 | `0` | 是否离职：`0` 否，`1` 是 |
51
+ | `--taskId` | 否 | 空字符串 | 任务 ID，默认空字符串 |
49
52
  | `--custom-tags` | 否 | 空 | 导出的自定义字段列表，多个字段用英文逗号分隔；也可传 JSON 字符串数组 |
50
53
 
51
54
  响应关键字段：
@@ -58,18 +61,25 @@ soke-cli task +create \
58
61
 
59
62
  默认输出会打印单行任务 ID，例如 `id:13288419`。需要完整字段时使用 `--format json`。
60
63
 
61
- ### 查询异步导出任务
64
+ ### 查询异步任务
62
65
 
63
66
  ```bash
64
67
  soke-cli task +get --id "TASK-ID" --format json
65
68
  ```
66
69
 
70
+ 状态判断规则：
71
+
72
+ | 创建任务时的 `--action` | 查询完成状态字段 | 说明 |
73
+ |-------------------------|------------------|------|
74
+ | `export` | `data.export_status` | 生成报表时用导出状态判断是否生成文件 |
75
+ | `report` | `data.status` | 生成统计时用任务执行状态判断是否完成 |
76
+
67
77
  响应关键字段：
68
78
 
69
79
  | 字段 | 说明 |
70
80
  |------|------|
71
- | `data.status` | 任务执行状态；接口示例中 `2` 表示执行完成 |
72
- | `data.export_status` | 导出状态；接口示例中 `2` 表示已生成导出文件 |
81
+ | `data.status` | 任务执行状态；`action=report` 生成统计时用此字段判断任务状态，接口示例中 `2` 表示执行完成 |
82
+ | `data.export_status` | 导出状态；`action=export` 生成报表时用此字段判断导出状态，接口示例中 `2` 表示已生成导出文件 |
73
83
  | `data.filePath` | 导出文件访问地址，未生成时为空 |
74
84
  | `data.filename` | 导出文件名 |
75
85
  | `data.filesize` | 导出文件大小 |
@@ -89,6 +99,16 @@ TASK_ID=$(soke-cli task +create \
89
99
  soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.filePath'
90
100
  ```
91
101
 
102
+ 按创建任务的 action 查询状态：
103
+
104
+ ```bash
105
+ # action=export
106
+ soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.export_status'
107
+
108
+ # action=report
109
+ soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.status'
110
+ ```
111
+
92
112
  ## API 接口映射
93
113
 
94
114
  | CLI 命令 | API 路径 | 方法 |
@@ -101,4 +121,4 @@ soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.filePath'
101
121
  - `data.filePath` 为空：任务可能还未完成，等待后重新执行 `task +get --id "TASK-ID" --format json`。
102
122
  - `未登录授权`：按 `soke-shared` 执行 `soke-cli auth login` 后重试。
103
123
  - 自定义字段没有导出：确认已通过 `--custom-tags "字段1,字段2"` 指定，字段名需与学习地图学员统计支持的自定义字段一致。
104
- - 任务创建失败：确认 `--map-id` 是有效学习地图 UUID，`--module learningMapUser`，`--action export`，`--type aloneDept` 或 `--type manyDept`。
124
+ - 任务创建失败：确认 `--map-id` 是有效学习地图 UUID，`--module learningMapUser`，`--action export` 或 `--action report`，`--type aloneDept` 或 `--type manyDept`。