learning-exercise-markdown

Files (1)

• SKILL.md

SKILL.md (first lines)

# 练习 Markdown 与题目数据

学习站把练习保存为本地 Markdown 文件，但不是把任意 Markdown 解析成可评分练习。区分以下两份相关记录：

- 练习文档：带元数据，正文由程序生成，供阅读和导出。旧布局或尚未归入课程时可位于 `exercises/<documentId>.md`；归入课程、完成迁移后位于 `courses/<courseId>/materials/documents/<documentId>.md`。以实际文档路径为准，不根据旧布局猜测。
- `sessions/<sessionId>/entries/<entryId>.md`：原会话的记录也使用 Markdown 文件，元数据中的 `data` 保存结构化题目 ID、题干、答案、解析、来源及评分量表。做题与评分读取这份数据；练习文档元数据指向当前题集记录。

直接修改 `.md` 正文中的“参考答案”不会改变评分依据。不要把写入普通文本、修改页面标题或生成一段 Markdown 说成“已更新练习题”。只有工具的持久化回执能够证明修改完成。

## 本地 Markdown 格式

元数据由程序维护，包含 `kind: exercise`、稳定文档 ID、标题，以及 `originSessionId`、`exerciseEntryId`、`sourceDocumentId` 等关联。不要手写或复制这些标识注册另一份练习；不要修改历史会话中的原题或旧评分记录。

正文依次包含：

1. `# 练习` 和阅读视图说明。
2. 可选的 `## 练习说明`。
3. 每题的 `## 第 N 题`、题目编号、`### 题干`、`### 参考答案`、`### 解析`、`### 来源`。
4. 来源以 `[[稳定来源ID]]` 链接表示；没有来源时写“未声明材料来源。”。

题干、答案、解析和说明在导出正文中使用 `text` 围栏保持字面内容。内容包含反引号时，程序使用更长的围栏。多项可接受答案逐行写入同一答案块，不代表必须同时作答。下面只展示正文片段，示意 ID 不能用于真实请求：

````markdown
## 第 1 题

题目编号：`q_example`

### 题干

```text
3.5 千米等于多少米？只填写数值。
```

### 参考答案

```text
3500
3,500
```

### 解析

```text
1 千米 = 1000 米，所以 3.5 × 1000 = 3500 米。
```

### 来源

- [[source_example]]
````

正文没有独立的 `options` 或 `choices` 字段。选择题选项属于 `question` 题干，可以用 A、B、C 等分行表示。`format` 不是“单选/多选”的枚举：短且有限答案使用 `exact`，开放作答使用 `self`；标签、评分量表等结构化字段不应靠解析上述 Markdown 猜回。

## 新建练习

使用 `generate_exercises` 工具或练习生成入口。需要出题指导和完整生成参数时，通过 `load_learning_skill` 加载 `learning-exercises`。新建参数和修改已有练习的参数不同，不要混用。

`sourceIds` 只能取本轮授权来源清单里的稳定编号；文件路径不是来源编号。未交卷且用户没有明确要求查看答案时，不把参考答案混入题干或普通提示。

## 修改已有练习

只在用户明确要求修改该练习、并已有相应读取/写入授权时操作：

1. 请用户先在当前练习切到“编辑 Markdown”视图，再发送修改要求。做题视图的聚焦本身不授予完整题集和参考答案读取权限；不要代替用户扩大授权。通过当前授权的练习文档地址读取，例如 `documents/<exerciseDocumentId>.md`。这是相对当前课程材料的工具地址，旧布局由应用处理；不得自行移动练习文件或拼接其他课程的 ID。
2. 练习专用读取返回 `version` 和 `content`；`content` 是结构化题集的 JSON 字符串，不是上述导出 Markdown。先解析实际读回结果，保留不打算修改的题目及字段。
3. `write.content` 必须是题集对象序列化后的 JSON 字符串（例如 `JSON.stringify` 的结果），不是对象；解析后顶层只有 `exercises`。`write.expectedVersion` 使用本次读取的版本，不猜测、不沿用旧回合版本。
4. 保留已有题目的 `id` 表示原题不变或提出修改；新增题目省略 `id`；删除题目从题集数组中省略。不能伪造其他题目 ID。变更题与新增题的最终 ID 由程序生成，未变题保留原 ID。
5. 等待逐题审阅。每题的题干、选项、答案、解析和量表作为一个整体接受或拒绝。待审阅不等于已保存；只报告回执已确认的结果。

结构示意（所有 ID 和版本必须替换为实际读取值；这里展示 `content` 解析后的对象，不是完整 `write` 入参）：

```json
{
  "exercises": [
    {
      "id": "q_from_read",
      "question": "3.5 千米等于多少米？只填写数值。",
      "format": "exact",
      "answers": ["3500", "3,500"],
      "explanation": "1 千米 = 1000 米，所以结果是 3500 米。",
      "tags": ["单位换算"],
      "sourceIds": ["source_from_read"],
      "answerMatch": "trim"
    }
  ]
}
```

现有题集约束为 1 至 5 题。逐题接受触及数量限制时，按错误提示先处理另一项新增或删除，不通过普通文件写入绕过校验。版本冲突时重新读取并核对尚未决定的修改；结果未知先核对原操作，不盲目重发。

接受修改会更新当前练习与对应题目数据，保留旧题、旧作答和旧评分。不要让修改后的答案重新解释用户过去的作答，也不要将旧答案自动当作新题作答。

From YuShenLiu06/learning-station, MIT.

More from YuShenLiu06/learning-station