Examark Markdown 试卷格式¶

Examark Markdown 是 Examark 的试卷源码格式。它用于批量编辑整张试卷、编译单题，以及让生成式工具按稳定结构产出可检查、可预览、可打印的试卷草稿。

当前规范版本为 v2，文件扩展名为 .examark.md，编码必须为 UTF-8。v2 支持结构化评分标准和题目标签；已有 v1 源码仍可完整编译。

结构数据仍是权威数据

源码只有在 编译成功 后才会更新浏览器中的当前草稿，之后仍需选择 保存试题 才会写入系统。编译错误不会覆盖当前草稿。

下载规范文件¶

JSON Schema 描述编译后的语义结构；EBNF 描述源码的结构指令。生成工具应同时遵守本页约束。

基本结构¶

整卷源码由 YAML 文件头和一个或多个题组组成：

---
format: examark-paper
version: 2
paper:
  title: 期中测试
print:
  show_page_numbers: true
---

@group
key: objective
title: 一、选择题
allowed_types: [single_choice]
default_scores:
  single_choice: 4

@question
key: q1
type: single_choice
score: 4
knowledge_points: [示例知识点]
answer: [A]
@stem
下列选项正确的是（ ）。
@endstem
@option A
选项 A
@endoption
@option B
选项 B
@endoption
@explanation
答案为 A。
@endexplanation
@endquestion
@endgroup

结构指令必须使用英文并独占一行；题目、说明、答案和解析可以使用中文。

YAML 文件头¶

字段	必填	说明
`format`	是	固定为 `examark-paper`
`version`	是	当前版本固定为整数 `2`；整数 `1` 按旧规范编译
`paper.title`	是	试卷标题，最长 200 个字符
`print`	是	试卷显示配置；未知字段会在规范化时移除

print 支持以下字段：

字段	类型	说明
`paper_main_title`	string	试卷大标题
`show_student_info`	boolean	显示学生信息栏
`show_instructions`	boolean	显示考试须知
`show_exam_time` / `exam_time`	boolean / string	显示考试时间及文本
`show_exam_location` / `exam_location`	boolean / string	显示考试地点及文本
`show_exam_duration` / `exam_duration`	boolean / string	显示考试时长及文本
`show_manual_grading_table`	boolean	显示人工登分表
`show_page_numbers`	boolean	显示页码
`show_question_count`	boolean	显示题目数
`show_total_score`	boolean	显示总分
`body_font_size_pt`	number	正文字号，范围为 9 至 14 pt
`instructions`	string	考试须知，多行文本使用 YAML `\|`
`student_no_config`	object	`prefix`、`digit_count`、`digits`
`answer_sheet_config`	object	增强扫描、题干嵌入和题目标签显示配置

A3/A4、单双面和空白页策略属于预印版本配置，不写入试卷作者源码。

answer_sheet_config 用于控制答题卡展示：

字段	说明
`enhanced_scanning`	建议在答题卡嵌入题干、说明或选择题选项时开启；当前不是强制项
`embed_question_content`	“在答题卡中加入题干”总开关，默认 `false`；只有开启后两个题干子项才生效
`embed_written_stems`	在答题卡中加入填空、主观题和作文题的题干、相关题组标题与说明；填空题题干中的空位会显示为 `（1）`、`（2）`，学生仍在下方对应作答线填写
`embed_objective_stems`	在答题卡中加入选择题题干和选项，并在后方显示填涂区域
`show_question_tags`	在答题卡中显示题目标签，默认 `false`，不依赖题干总开关

embed_written_stems 和 embed_objective_stems 会保留用户最后一次选择。总开关显式为 false 时，两个子项即使仍为 true 也不生效，但不会被清空；再次开启总开关时会恢复原选择。为兼容旧源码和旧配置，如果缺少 embed_question_content，系统会用两个子项的逻辑 OR 推断总开关。新建配置的三个开关均默认为 false。

show_question_tags 是独立开关。新版答题卡模板会为单选、多选、判断、填空、主观题和作文题各自的最终答题区域固定预留一行标签位，位于答题区域下方并靠右显示 标签一、标签二。关闭显示或题目没有标签时，该行仍留空，因此切换显示开关不会改变页数或扫描坐标。填空题的标签跟随最后一空；跨页的主观题和作文题只在最后一个续答区域显示和预留。标签过长时会从 8 pt 缩小到最低 6 pt，仍放不下则在答题卡中省略末尾内容，编辑器和源码继续保留完整值。题目标签不加入学生试卷或教师答案卷。已经生成并锁定的正式答题卡继续使用其绑定的旧版模板，不会回填标签区域。

这些字段只影响答题卡打印展示。扫描仍以模板中的条码、定位点、学号区、客观题填涂区、填空题下方作答区和主观题裁图区为准，不识别题干文字中的空位本身。

题组和说明¶

题组使用 @group 和 @endgroup。每个题组必须有稳定且唯一的 key：

@group
key: written
title: 二、主观题
allowed_types: [fill_blank, subjective]
default_scores:
  fill_blank: 6
  subjective: 12

@instruction
key: written_note
@content
请写出必要步骤。
@endinstruction
@endgroup

key 只能包含字母、数字、点、下划线、冒号和连字符，最长 128 个字符。已有试卷生成源码时，系统会由现有 ID 派生稳定 key。删除或修改已有 key 会被视为结构性变更。

共享材料应写在题组说明中，后续题目按顺序引用；v2 不建立独立复合小题模型。

题目¶

题目使用 @question、@stem 和 @endquestion。通用元数据如下：

字段	说明
`key`	稳定且唯一的题目 key
`type`	题型代码
`score`	本题分值；填空题总分由各空分值相加
`group_key`	可选；整卷编译时通常由所在题组确定
`knowledge_points`	字符串数组，对应可视化编辑器中的“题目标签”；最多 30 项，每项最长 120 个字符

可视化编辑器允许用中文逗号、英文逗号或换行分隔多个题目标签。保存和编译时会对每项去除首尾空白、移除空项，并按首次出现顺序去重。整卷代码和本题完整代码都会输出 knowledge_points；没有标签时输出空数组。题组说明不是可作答题目，不接受题目标签。

单选题和多选题¶

题型代码分别为 single_choice 和 multiple_choice。答案写在元数据的 answer 数组中，每个选项使用独立的 @option：

@question
key: q_choice
type: multiple_choice
score: 6
answer: [A, C]
@stem
选择所有正确项。
@endstem
@option A
第一项
@endoption
@option B
第二项
@endoption
@option C
第三项
@endoption
@explanation
A、C 正确。
@endexplanation
@endquestion

每题最多 6 个选项。答案标签必须与选项标签一致；单选题只能有一个答案，多选题至少有一个答案。

判断题¶

判断题代码为 true_false，使用 T 表示正确、F 表示错误。规范化源码会包含 T/F 两个选项。

填空题¶

填空题代码为 fill_blank。题干中的每个填空使用 {{blank:key}}，元数据中的 blanks 必须逐一提供答案和分值：

@question
key: q_blank
type: fill_blank
score: 6
blanks:
  - key: b1
    score: 3
    answers: [H2O, H₂O]
  - key: b2
    score: 3
    answers: [氧气]
@stem
水的化学式是 {{blank:b1}}，支持燃烧的气体是 {{blank:b2}}。
@endstem
@rubric
version: 1
criteria:
  - key: formula
    title: 化学式
    points: 3
    observable: 正确写出水的化学式
    evidence: 第一空为 H2O 或 H₂O
    levels:
      - score: 0
        description: 错误或未作答
      - score: 3
        description: 答案正确
  - key: gas
    title: 气体名称
    points: 3
    observable: 正确写出支持燃烧的气体
    evidence: 第二空为氧气
    levels:
      - score: 0
        description: 错误或未作答
      - score: 3
        description: 答案正确
@endrubric
@explanation
逐空核对标准答案。
@endexplanation
@endquestion

同一空的 answers 表示可接受的多个答案。源码中的空位 key、答案 key 和数量必须一致。

当答题卡开启“在答题卡中加入题干”并选择主观/填空题干时，答题卡上的填空槽会自动显示空号，例如 （1）、（2）。答题卡下方会生成对应作答线，例如 5.（1）、5.（2）；学生应在这些作答线填写答案，扫描和后续阅卷仍读取下方作答区。

主观题¶

主观题代码为 subjective。answer_style 可为 lined 或 blank，answer_lines 是正整数：

key: q_subjective
type: subjective
score: 12
answer_style: lined
answer_lines: 6

作文¶

作文代码为 composition，使用 composition_rows 设置作文格行数。答案区域由打印模板生成，不在源码中写 HTML 或 CSS。

内容格式¶

题干、选项、说明和解析支持 Markdown 段落、1 至 6 级标题、无序和有序列表、引用、分隔线、表格、粗体、斜体、删除线、上标、下标、行内代码与代码块。扩展语法如下：

语法	用途
`++重点++`	下划线
`~~删除~~`	删除线
`H~2~O`	下标
`x^2^`	上标
`\(x^2+y^2\)`	行内 LaTeX 公式
`\[\frac{a}{b}\]`	块级 LaTeX 公式
`{{blank:b1}}`	填空槽
`{{pinyin "hua4 xue2"}}`	数字声调拼音，编译为 `huà xué`
`{align=left}` / `{align=center}` / `{align=right}`	对齐紧邻的段落，写在该段末行
`{{image asset="..." width=100 x=0 y=0 border=false}}`	系统图片资源
`%% 注释`	源码注释；代码块外独占一行，规范化后移除

段落、换行和对齐¶

题干区域采用“段落即行”的编辑语义：

普通 Enter 建立新的紧凑段落，可单独设置左、中、右对齐；
Shift+Enter 是同一段内硬换行，同段共享一个对齐方式；
多行纯文本粘贴时，系统会尽量拆成独立段落；
{align=...} 作用于紧邻的上一段，不要求额外空一行；
列表、表格和代码块不会因为普通换行被拆坏。

例如：

第一行居左 {align=left}
第二行居中 {align=center}
第三行居右 {align=right}

实时预览、学生试卷 PDF 和答题卡 PDF 使用同一套安全富文本渲染规则。保存后仍应重新打开题目，确认对齐、表格、图片和公式都按预期回显。

图片参数：

参数	规则
`asset`	必须是当前组织、当前考试下已验证的 JPG/PNG 题目资源 ID
`width`	10 至 120，表示相对宽度百分比
`x` / `y`	-20 至 20，表示毫米偏移
`border`	`true` 或 `false`
`caption`	可选说明文字，最长 200 个字符

应先在代码编辑器中选择 插入图片，由系统上传并插入正确的资源 ID。Markdown 外部图片 URL、Base64 图片和 HTML <img> 均不允许。

表格使用标准 Markdown 表格语法，适合展示少量横向对照信息。表格过宽时，答题卡嵌题干版式可能无法安全容纳；预印失败时请减少列数、缩短文字或关闭答题卡嵌入。

评分标准和解析¶

非客观题使用 @rubric ... @endrubric 保存评分标准。v2 的内容是安全加载的 YAML，不是 Markdown 或 HTML。
所有题型都可以使用 @explanation ... @endexplanation 保存解析。
预印锁定后，整卷源码只读；选择 仅编辑答案 后，本题代码只包含当前题目的答案、评分标准和解析。

结构化评分标准固定使用 version: 1，包含一个或多个评分点：

字段	规则
`criteria[].key`	稳定且唯一，最长 64 个字符
`criteria[].title`	评分点名称
`criteria[].points`	该评分点满分，必须大于 0
`criteria[].observable`	阅卷时可以直接观察和判断的标准
`criteria[].evidence`	学生答案中能够支持得分的具体证据
`criteria[].levels`	可选分档；填写时必须同时包含 `0` 分和该评分点满分，可增加部分得分条件

所有 criteria[].points 必须精确合计为题目 score。评分点最多 30 个，每个评分点最多 10 个分档；分档分值不能重复，也不能超过该评分点满分。系统会由结构化内容生成兼容的评分标准文本。

旧试卷的自由文本评分标准仍然有效。v2 规范化源码会将其表示为：

@rubric
legacy_text: 按关键步骤分点给分。
@endrubric

生成教师答案卷时，标准答案区域按以下顺序显示：有显式标准答案时直接显示答案；没有唯一答案但有结构化评分点时显示“本题采用逐点评分，无唯一标准答案；请按下方评分点和得分条件判分。”；只有旧版文本评分标准时提示参照下方评分标准；答案和评分标准都未配置时才显示“未配置标准答案”。

答案模式源码使用 format: examark-question 和 mode: answer_metadata。不得修改其 key 或题型，也不能加入题干、选项、分值、题目标签或版面字段。

安全限制¶

以下内容会导致编译失败：

原始 HTML、<script>、事件属性、CSS 或其他可执行标记；
Markdown 外部图片、Base64 图片和非本考试资源；
YAML 锚点、别名、自定义标签或过深、过大的 YAML 数据；
未知结构指令、重复 key、不闭合的结构区块或公式定界符；
超过 1,000,000 个字符的源码；
超过 50 个题组、500 个题目或说明、每题 6 个选项；
单题超过 30 个题目标签，或任一标签超过 120 个字符；
题型不匹配的答案、分值、填空槽或答题区域设置。

Markdown 解析关闭原始 HTML，编译结果还会经过 Examark 的富文本白名单净化。代码块中的 HTML 示例会作为普通文本转义，不会执行。

编译、规范化与并发¶

选择 整卷代码 或 本题代码。
修改源码后选择编译。
编译成功后核对实时预览、题目栏、总分和差异摘要。
选择 保存试题 才会保存并生成一条历史版本。

编译会返回规范化源码。注释、字段顺序和不影响语义的空行可能被调整，因此不应把源码排版当作长期数据。删题、换题型、修改稳定 key 或丢失图片会要求再次确认。

保存使用草稿 ETag 检查并发修改。发生冲突时系统不会覆盖其他协作者的版本；应先下载本地源码，再重新加载或打开版本管理进行比较。

AI 生成要求¶

生成式工具应遵循以下顺序：

固定输出 format: examark-paper 和 version: 2。
为所有题组、说明和题目分配稳定、唯一、可读的 key，后续修订不随意改 key。
只使用本规范列出的题型、字段和结构指令；需要标签时使用 knowledge_points 字符串数组。
保证客观题答案对应真实选项，填空答案对应全部填空槽，各题分值非负且合理。
为填空、主观题和作文生成结构化评分标准；每一分都应对应可观察标准和答案证据，评分点精确合计题目满分。
不虚构图片资源 ID；需要图片时使用调用方明确提供的当前考试 asset ID。
不把资料引用、内部说明或模型推理写入学生可见的题干、选项、答案、评分标准或解析。
不输出 HTML、CSS、外链图片、Base64、脚本、页面命令或强制分页。
输出后先调用编译校验，根据行列诊断修正，再交给用户预览和保存。

完整结构请从本页顶部下载范例、Schema 和 EBNF。JSON Schema 无法表达“评分点分值精确合计题目满分”等全部跨字段规则，因此生成工具必须同时通过 Examark 编译器。未来能力会通过新版本扩展，v1 源码仍保持可编译。