@sokeai/cli 1.0.76 → 1.0.78

package/skills/multi/soke-assign/references/dependencies/soke-exam.md

@@ -0,0 +1,600 @@
+---
+name: soke-exam
+summary: 授客考试管理（考试/题库/试题/试卷的创建、查询与管理），通过 soke-cli 操作
+version: 1.1.0
+description: "授客考试管理：创建和查询考试、题库、试题、试卷，管理考试用户和成绩。当用户需要创建考试、创建试题、管理题库、查询考试成绩、查看考试列表时使用。 | Soke exam management: create and query exams, question banks, questions, and papers; manage exam users and scores. Use when users need to create exams, create questions, manage question banks, query exam scores, or view exam lists."
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli exam --help"
+---
+
+# 考试管理 (exam)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../shared.md`](../shared.md)，其中包含认证、配置、权限处理**
+
+## 核心概念
+
+- **Exam（考试）**: 考试实体，包含标题、时间范围、状态等信息，通过 `uuid` 标识
+- **Pool（题库）**: 存放试题的容器，通过 `uuid` 标识，包含一个或多个分类
+- **Paper（试卷）**: 从题库按题型抽取试题生成的试卷，通过 `uuid` 标识
+- **Question（试题）**: 单个题目，支持 7 种题型，通过 `uuid` 标识
+- **ExamUser（考试用户）**: 用户的考试记录，包含成绩、状态、答题时间等
+- **Category（分类）**: 题库分类 / 考试分类，支持层级结构
+
+## 资源关系
+
+```
+Pool (题库)
+├── Category (题库分类)
+└── Question (试题) × N
+    └── Paper (试卷) — 按题型从题库中抽取
+        └── Exam (考试) — 关联试卷，指派用户
+            └── ExamUser (考试用户记录)
+```
+
+## Shortcuts 总览
+
+### 查询类（读）
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+list-exams`](#list-exams) | 列出考试列表 |
+| [`+get-exam`](#get-exam) | 获取单个考试详情 |
+| [`+list-exam-users`](#list-exam-users) | 列出考试用户成绩列表 |
+| [`+get-exam-user`](#get-exam-user) | 获取单个考试用户的详细成绩 |
+| [`+list-exam-categories`](#list-exam-categories) | 列出考试分类（通过 API） |
+| [`+list-pool-categories`](#list-pool-categories) | 列出题库分类 |
+| [`+list-pools`](#list-pools) | 列出题库列表 |
+| [`+get-pool`](#get-pool) | 获取题库详情 |
+| [`+list-questions`](#list-questions) | 获取试题列表 |
+| [`+list-papers`](#list-papers) | 获取试卷列表 |
+| [`+get-paper`](#get-paper) | 获取试卷详情 |
+| [`+get-paper-questions`](#get-paper-questions) | 获取试卷试题列表 |
+| [`+get-statistic-data`](#get-statistic-data) | 获取考试统计数据 |
+| [`+list-user-list`](#list-user-list) | 获取考生用户列表 |
+
+### 创建/修改类（写）
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+create-pool-category`](#create-pool-category) | 创建题库分类 |
+| [`+create-pool`](#create-pool) | 创建题库 |
+| [`+update-pool`](#update-pool) | 更新题库 |
+| [`+create-question`](#create-question) | 创建试题 |
+| [`+create-paper`](#create-paper) | 创建试卷 |
+| [`+update-paper`](#update-paper) | 更新试卷（支持发布） |
+| [`+delete-paper`](#delete-paper) | 删除试卷 |
+| [`+set-paper-score`](#set-paper-score) | 设置试卷分值 |
+| [`+create-exam`](#create-exam) | 创建考试 |
+| [`+update-exam`](#update-exam) | 更新考试 |
+| [`+import-paper`](#import-paper) | 关联试卷到考试 |
+| [`+assign-exam`](#assign-exam) | 指派考试给用户 |
+| [`+get-assign`](#get-assign) | 查询考试指派情况 |
+
+---
+
+## 试题类型与格式
+
+### 7 种题型一览
+
+| type 值 | 中文名 | choices | answer | 特殊说明 |
+|---------|--------|---------|--------|---------|
+| `single_choice` | 单选题 | 必传 | `["0"]` 索引数组 | 只有一个正确答案 |
+| `determine` | 判断题 | 不需要 | `["0"]` 对 / `["1"]` 错 | 默认选项为对/错 |
+| `choice` | 多选题 | 必传 | `["0","1"]` 索引数组 | 多个正确答案 |
+| `uncertain_choice` | 不定项选择 | 必传 | `["0","2"]` 索引数组 | 答案数量不固定 |
+| `fill` | 填空题 | 不需要 | **不传** | 见下方专节 |
+| `essay` | 简答题 | 不需要 | 字符串 | 参考答案文本 |
+| `material` | 材料题 | 不需要 | 字符串 | 类似简答 |
+
+### 填空题（fill）专节
+
+**填空题答案嵌入在 title 中**，使用 `[[答案N]]` 标记（N 从 1 开始），**不传 `--answer` 参数**。
+
+```bash
+# 正确：答案标记嵌入 title
+soke-cli exam +create-question \
+  --type fill \
+  --title "鲁班是[[答案1]]国人，本名[[答案2]]。" \
+  --answer-type 1 \
+  --pool-id "<pool-uuid>" \
+  --score 5 --difficulty simple
+
+# 错误：用 ______ 或其他标记 — 后端无法识别，报"答案为空"
+soke-cli exam +create-question \
+  --type fill \
+  --title "鲁班是______国人" \    # ❌ 不是 [[答案N]]
+  ...
+```
+
+**`--answer-type` 判卷方式**（`fill` 专属，不传时默认 `"1"`）：
+
+| 值 | 含义 |
+|----|------|
+| `1` | 完全一致（默认） |
+| `2` | 仅顺序不一致 |
+| `3` | 仅供参考 |
+
+**常见错误**：
+- 用 `______` / `___` / `(答案1)` 代替 `[[答案1]]` → 后端解析失败
+- 传了 `--answer` 参数 → 对 fill 类型无效，会被忽略
+- 不传 `--answer-type` → CLI 自动默认 `"1"`，一般不会出问题
+
+---
+
+## ⚠️ 题库分类 vs 考试分类
+
+**这是两个独立的分类系统，UUID 不能混用：**
+
+| 类型 | 用途 | 查询方式 |
+|------|------|---------|
+| **题库分类** (Pool Category) | 用于 `+create-pool --path` | `soke-cli exam +list-pool-categories` |
+| **考试分类** (Exam Category) | 用于 `+create-exam --path` 和 `+update-exam --path` | `soke-cli api GET /skills/examCategory/list` |
+
+**常见错误**：在 `+create-exam` 或 `+update-exam --action publish` 的 `--path` 中传入题库分类 UUID → 报"设置失败"/"分类不能为空"。
+
+### +list-exam-categories
+
+列出考试分类（通过 API 查询）。
+
+```bash
+soke-cli api GET /skills/examCategory/list
+```
+
+返回 JSON，从 `data.list.list[].uuid` 获取考试分类 UUID。
+
+---
+
+## 命令详解
+
+### +create-exam
+
+创建考试。
+
+```bash
+soke-cli exam +create-exam \
+  --title <考试标题> \
+  [--is-papers 1] \
+  [--source self] \
+  [--path '["<exam_category_uuid>"]']
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--title` | 是 | 考试标题，最大 50 字符 |
+| `--is-papers` | 否 | 是否关联试卷：0=否 1=是（默认 0） |
+| `--is-in` | 否 | 是否内部考试：0=否 1=是（默认 0） |
+| `--is-offline` | 否 | 是否线下考试：0=否 1=是（默认 0） |
+| `--set-time` | 否 | 是否设置考试时间（默认 0） |
+| `--source` | 否 | 来源：self/mall/public（默认 self） |
+| `--path` | 条件 | **考试分类** ID 数组（不是题库分类），JSON 格式，发布考试时必传 |
+
+---
+
+### +create-question
+
+创建试题。7 种题型有不同的参数要求，详见 [试题类型与格式](#试题类型与格式)。
+
+```bash
+soke-cli exam +create-question \
+  --title <内容> \
+  --type <题型> \
+  --score <分值> \
+  --difficulty <难度> \
+  --pool-id <题库UUID> \
+  [--choices <JSON选项>] \
+  [--answer <JSON答案>] \
+  [--answer-type <判卷方式>] \
+  [--analysis <解析>]
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--title` | 是 | 试题内容，fill 类型必须含 `[[答案N]]` |
+| `--type` | 是 | 题型：single_choice/choice/uncertain_choice/determine/fill/essay/material |
+| `--score` | 是 | 分值，必须大于 0 |
+| `--difficulty` | 是 | 难度：simple/medium/hard |
+| `--pool-id` | 是 | 所属题库 UUID |
+| `--choices` | 条件 | 选择题必传，JSON 数组：`'[{"key":"A1","value":"A"}]'` |
+| `--answer` | 条件 | 选择/判断题必传，fill 不传，简答/材料题为字符串 |
+| `--answer-type` | 否 | fill 专属，默认 `1` |
+| `--analysis` | 否 | 题目解析 |
+| `--dept-id` | 否 | 部门 ID |
+| `--dept-name` | 否 | 部门名称 |
+
+---
+
+### +create-pool
+
+创建题库。
+
+```bash
+soke-cli exam +create-pool \
+  --title <题库名称> \
+  --path '["<category_uuid>"]' \
+  [--description <描述>] \
+  [--status 1]
+```
+
+---
+
+### +create-pool-category
+
+创建题库分类。
+
+```bash
+soke-cli exam +create-pool-category --title <分类名称>
+```
+
+---
+
+### +create-paper
+
+从题库按题型抽取试题生成试卷。
+
+```bash
+soke-cli exam +create-paper \
+  --title <试卷名称> \
+  --pool-id '["<pool_uuid>"]' \
+  --pattern questionType \
+  --type-metas '<JSON>'
+```
+
+`--type-metas` 格式：
+```json
+{
+  "single_choice": {"count": 1, "score": 5},
+  "determine":      {"count": 1, "score": 2},
+  "choice":         {"count": 1, "score": 5},
+  "essay":          {"count": 1, "score": 10},
+  "uncertain_choice": {"count": 1, "score": 5},
+  "fill":           {"count": 1, "score": 5}
+}
+```
+
+---
+
+### +update-paper
+
+更新试卷，支持发布操作。**发布时必须同时传 `--title`，否则后端会将标题置空。**
+
+```bash
+# 发布试卷（title 必传）
+soke-cli exam +update-paper \
+  --paper-id <paper_uuid> \
+  --title <试卷名称> \
+  --action publish
+
+# 仅更新标题
+soke-cli exam +update-paper \
+  --paper-id <paper_uuid> \
+  --title <新标题>
+```
+
+---
+
+### +update-exam
+
+更新考试，支持发布。**发布时 `--title` 和 `--path` 必传**，`action` 会映射为后端 `act` 字段。
+
+```bash
+# 发布考试（title + path 必传）
+soke-cli exam +update-exam \
+  --exam-id <exam_uuid> \
+  --title <考试标题> \
+  --action publish \
+  --path '["<exam_category_uuid>"]'
+
+# 仅更新标题
+soke-cli exam +update-exam \
+  --exam-id <exam_uuid> \
+  --title <新标题>
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--exam-id` | 是 | 考试 UUID |
+| `--title` | 条件 | 发布时必传，避免标题被清空 |
+| `--action` | 否 | `publish`=发布考试，留空仅更新信息 |
+| `--path` | 条件 | 发布时必传，**考试分类** UUID 数组 JSON（不是题库分类） |
+
+**发布前提**：
+1. 考试创建时已设置 `--path`（分类），否则发布时分类检查不通过
+2. 考试已通过 `+import-paper` 关联了试卷
+3. 试卷已通过 `+update-paper --action publish` 发布
+
+---
+
+### +assign-exam
+
+指派考试给指定用户。
+
+```bash
+soke-cli exam +assign-exam \
+  --exam-id <exam_uuid> \
+  --user-ids '["<dept_user_id>", ...]'
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--exam-id` | 是 | 考试 UUID |
+| `--user-ids` | 是 | 用户 dept_user_id 数组，JSON 格式 |
+
+**查找用户 ID**：`soke-cli assign +list-users --keyword "姓名"`
+
+---
+
+### +get-assign
+
+查询考试已指派的用户列表。
+
+```bash
+soke-cli exam +get-assign --exam-id <exam_uuid>
+```
+
+---
+
+### +import-paper
+
+将已发布的试卷关联到考试。
+
+```bash
+soke-cli exam +import-paper \
+  --exam-id <exam_uuid> \
+  --paper-id <paper_uuid> \
+  [--is-papers 1]
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--exam-id` | 是 | 考试 UUID |
+| `--paper-id` | 是 | 试卷 UUID |
+| `--is-papers` | 否 | 是否多试卷模式（默认 0）。**如果考试是用 `--is-papers 1` 创建的，此处也必须传 `--is-papers 1`**，否则 paperId 会以字符串而非数组格式发送，导致发布时 crash |
+
+---
+
+### +get-exam
+
+获取考试详情。
+
+```bash
+soke-cli exam +get-exam --exam-id <exam_uuid>
+```
+
+返回字段包括：`uuid`, `title`, `status`（0=未发布 1=已发布）, `paper_id`, `question_count`, `total_score`, `pass_score` 等。
+
+---
+
+### +list-exams
+
+列出考试列表。
+
+```bash
+soke-cli exam +list-exams \
+  [--page <页码>] \
+  [--page-size <每页条数>]
+```
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--page` | 1 | 页码 |
+| `--page-size` | 10 | 每页条数 |
+
+---
+
+### +list-exam-users
+
+列出考试用户成绩列表。
+
+```bash
+soke-cli exam +list-exam-users \
+  --exam-id <exam_uuid> \
+  [--page <页码>] \
+  [--page-size <每页条数>]
+```
+
+---
+
+### +get-exam-user
+
+获取单个考试用户的详细成绩。
+
+```bash
+soke-cli exam +get-exam-user \
+  --exam-id <exam_uuid> \
+  --dept-user-id <dept_user_id>
+```
+
+---
+
+### +list-pool-categories
+
+列出题库分类。
+
+```bash
+soke-cli exam +list-pool-categories [--parent-id 1]
+```
+
+---
+
+### 其他查询命令
+
+```bash
+soke-cli exam +list-pools [--page 1] [--page-size 10]
+soke-cli exam +get-pool --pool-id <uuid>
+soke-cli exam +list-questions [--pool-id <uuid>] [--page 1] [--page-size 10]
+soke-cli exam +list-papers [--page 1] [--page-size 10]
+soke-cli exam +get-paper --paper-id <uuid>
+soke-cli exam +get-paper-questions --paper-id <uuid>
+soke-cli exam +get-statistic-data --exam-id <uuid>
+soke-cli exam +list-user-list --exam-id <uuid>
+soke-cli exam +list-categories [--page 1] [--page-size 10]
+soke-cli exam +update-pool --pool-id <uuid> --title <新标题>
+soke-cli exam +delete-paper --paper-id <uuid>
+soke-cli exam +set-paper-score --paper-id <uuid> --score <分值>
+```
+
+---
+
+## 完整工作流
+
+### 工作流 1：从零创建一场考试
+
+```bash
+# 1. 创建题库分类
+soke-cli exam +create-pool-category --title "考试分类名"
+# → 记下 uuid
+
+# 2. 创建题库
+soke-cli exam +create-pool \
+  --title "题库名" \
+  --path '["<category_uuid>"]'
+# → 记下 uuid
+
+# 3. 创建试题（6 种题型各一例）
+# 单选题
+soke-cli exam +create-question \
+  --pool-id "<pool_uuid>" --type single_choice \
+  --title "题目内容？" --score 5 --difficulty simple \
+  --choices '[{"key":"A1","value":"A"},{"key":"B1","value":"B"},{"key":"C1","value":"C"},{"key":"D1","value":"D"}]' \
+  --answer '["0"]'
+
+# 判断题
+soke-cli exam +create-question \
+  --pool-id "<pool_uuid>" --type determine \
+  --title "判断内容" --score 2 --difficulty simple \
+  --answer '["1"]'   # 0=对 1=错
+
+# 多选题
+soke-cli exam +create-question \
+  --pool-id "<pool_uuid>" --type choice \
+  --title "题目内容？" --score 5 --difficulty medium \
+  --choices '[{"key":"A1","value":"A"},...]' \
+  --answer '["0","1","2"]'
+
+# 简答题
+soke-cli exam +create-question \
+  --pool-id "<pool_uuid>" --type essay \
+  --title "题目内容？" --score 10 --difficulty medium \
+  --answer "参考答案文本"
+
+# 不定项选择题
+soke-cli exam +create-question \
+  --pool-id "<pool_uuid>" --type uncertain_choice \
+  --title "题目内容？" --score 5 --difficulty hard \
+  --choices '[{"key":"A1","value":"A"},...]' \
+  --answer '["0","2"]'
+
+# 填空题 — 答案嵌入 title 中，不传 --answer
+soke-cli exam +create-question \
+  --pool-id "<pool_uuid>" --type fill \
+  --title "...[[答案1]]...[[答案2]]..." \
+  --score 5 --difficulty medium
+
+# 4. 创建试卷（从题库按题型抽取）
+soke-cli exam +create-paper \
+  --title "试卷名" \
+  --pool-id '["<pool_uuid>"]' \
+  --pattern questionType \
+  --type-metas '{"single_choice":{"count":1,"score":5},"determine":{"count":1,"score":2},"choice":{"count":1,"score":5},"essay":{"count":1,"score":10},"uncertain_choice":{"count":1,"score":5},"fill":{"count":1,"score":5}}'
+
+# 5. 发布试卷（title 必传）
+soke-cli exam +update-paper \
+  --paper-id "<paper_uuid>" \
+  --title "试卷名" \
+  --action publish
+
+# 5.5 ⚠️ 查找考试分类（注意：考试分类 ≠ 题库分类！）
+# 题库分类 UUID 用于 pool，考试分类 UUID 用于 exam。两者不同！
+# 查询已有考试分类：
+soke-cli api GET /skills/examCategory/list
+# → 从中选择一个分类 UUID（如无合适的，请联系管理员创建）
+
+# 6. 创建考试（--path 必须使用考试分类 UUID，不是题库分类 UUID）
+soke-cli exam +create-exam \
+  --title "考试名" \
+  --path '["<exam_category_uuid>"]'
+
+# 7. 关联试卷到考试
+soke-cli exam +import-paper \
+  --exam-id "<exam_uuid>" \
+  --paper-id "<paper_uuid>"
+
+# 8. 发布考试（title + path 必传，path 必须用考试分类 UUID）
+soke-cli exam +update-exam \
+  --exam-id "<exam_uuid>" \
+  --title "考试名" \
+  --action publish \
+  --path '["<exam_category_uuid>"]'
+
+# 9. 指派考试给用户（先通过 soke-cli assign +list-users --keyword "姓名" 查 user ID）
+soke-cli exam +assign-exam \
+  --exam-id "<exam_uuid>" \
+  --user-ids '["<dept_user_id>"]'
+```
+
+### 工作流 2：查询用户考试成绩
+
+```bash
+# 1. 已知用户名，先查 dept_user_id
+soke-cli contact +search-user --dept-user-name "张三"
+
+# 2. 查询成绩
+soke-cli exam +get-exam-user \
+  --exam-id <exam_uuid> \
+  --dept-user-id <dept_user_id>
+```
+
+### 工作流 3：统计考试完成情况
+
+```bash
+soke-cli exam +get-statistic-data --exam-id <exam_uuid>
+soke-cli exam +list-exam-users --exam-id <exam_uuid>
+```
+
+---
+
+## 常见问题与排错
+
+### 填空题报"答案为空"
+
+title 中没有使用 `[[答案N]]` 标记。检查：
+- `______` → 改成 `[[答案1]]`
+- `___` → 改成 `[[答案1]]`
+- `(答案1)` → 改成 `[[答案1]]`
+
+### 填空题报 500 错误
+
+`--answer-type` 未传且 title 含 `[[答案N]]` 时可能触发（CLI 已默认 `"1"`，一般不再出现）。
+
+### 创建成功但没有输出
+
+API 返回了业务错误（如 `status: "error"`）但没显示。用 `--format json` 查看原始响应。CLI v1.0.52+ 已修复静默失败问题，现在会自动显示 `Error: [code] message`。
+
+### 列表接口报 500
+
+部分 `/skills/examUser/*` 端点可能因数据问题崩溃，先用 `+get-exam-user` 逐个查询。
+
+---
+
+## 权限表
+
+| 操作 | 所需权限 |
+|------|---------|
+| 查询类（list/get） | `exam:exam:readonly` / `exam:examUser:readonly` / `exam:category:readonly` |
+| 创建类（create） | `exam:exam:write` / `exam:examQuestion:write` / `exam:examPaper:write` / `exam:examPool:write` |
+| 更新/删除 | 对应模块的 `:write` 权限 |
+
+## 注意事项
+
+1. **填空答案格式**: 必须用 `[[答案N]]` 嵌入 title，不能用 `______` 或自定义标记
+2. **填空不传 --answer**: fill 类型的 `--answer` 参数会被忽略，答案在 title 标记中
+3. **--answer-type 默认值**: fill 类型不传时 CLI 自动设为 `"1"`（完全一致）
+4. **choices key 格式**: `{"key":"A1","value":"A"}` — key 是选项标识，value 是选项文本
+5. **answer 索引**: 选择题答案用 0-based 索引，`"0"` 表示第一个选项
+6. **判断题 answer**: `["0"]` 对，`["1"]` 错
+7. **试卷必须先发布且带标题**: `+update-paper --title "..." --action publish`
+8. **考试创建时需带分类**: `+create-exam --path '["<category_uuid>"]'`，否则无法发布
+9. **发布考试**: `+update-exam --title "..." --action publish --path '["<category_uuid>"]'`，`action` 映射为后端 `act` 字段
+8. **考试状态**: status=0 未发布，status=1 已发布