试卷结构自洽检查 PerryLink/dsh-paper-doc-adapter

dsh-paper-doc-adapter — 解析后的试卷结构自洽检查，覆盖题型、答案、分值与 yotta 标识符

dsh-paper-doc-adapter 读取一份解析后的试卷 —— 试卷头加上每道题一行 —— 检查这份解析结果自身的结构自洽性：每道题是否记录了题号和题干，是否有答案或解析，各题分值加起来是否等于试卷头声明的总分，题型是否来自你配置的词表，难度系数是否落在你设定的范围内，题目标识符是否存在且唯一，是否记录了知识点，题干里是否还残留模板占位符。

它能回答什么

| 你问 | 它答 |
| 某一行题号和题干都是空的 —— 检查会说什么吗？ | 会。PD-001 会报出这一行，因为它的 questionNo 和 stem 都为空，而规则要求两者至少填一个。它只检查有没有填，不判断题目写得好不好、题干严不严谨。 |
| 一道题有题号和题干，但既没有答案也没有解析。 | PD-002 会报出这一行：它要求 answer 和 explanation 至少有一个。它不检查答案对不对 —— 那是学科专家审校的事，规则包自己也这么说。 |
| 各题分值加起来是 98，试卷头写的是 100 —— 能查出来吗？ | 能。PD-003 把 score 列相加，与试卷头声明的 totalScore 比较，允许配置的容差 0.01；如果试卷头的总分不是可解析的数字，规则会把自己记进 skipped。它只做加法 —— 分值分布是否合理，它不评判。 |
| 我们从来没列过自己的题型。工具拿题型列怎么办？ | PD-004 会把自己记进 skipped，因为它的 values 列表出厂就是空的：题型怎么命名是你们机构的约定，引擎不硬编码任何词表。你配置好取值之后，questionType 落在取值之外就会被报出；此时规则只检查是否属于该集合，不做任何针对具体题型的结构检查。 |
| 难度列一行是 1.2，另一行是 中等 —— 会返回什么？ | PD-005 会报出无法解析为数字的值，以及超出配置的 min/max 范围 0–1 的值。这个范围是你们机构的约定，不是唯一标尺 —— 用 1–5 或百分比就得改 min/max，或者把规则关掉。它只检查范围，从不判断难度是否合适，而且级别上限是 info。 |
| 两道题带着同一个 yotta 标识符。为什么这比空标识符更糟？ | PD-006 会报告重复值，比较时忽略空白，因为导入该解析结果会静默覆盖已有题目；空标识符只会让这一道题被排除在外。如果任何地方都没填标识符，规则会在 skipped 中报告自身。它只检查存在性与唯一性，除此之外不做别的。 |

遵循的标准

| 文档 | 编号 | 引用它的规则 |
| 《试题元数据规范》 | JY/T 0606 系列（本次未取得条文） | PD-001, PD-002, PD-003, PD-006, PD-007, PD-008 |
| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的题型口径） | PD-004 |
| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的难度口径） | PD-005 |

边界： 本插件检查试卷解析结果的结构自洽性——每道题都记录了自己的题号和题干，答案或解析存在，各题分值合计等于试卷总分，题型来自你的词表，难度系数落在你的区间内，题目标识符存在且唯一，记录了知识点，且没有占位符残留。它不判断题目写得好不好、答案对不对、难度是否合适，也不判断试卷是否达成其测评目标。

⚠️ 本插件刻意不做的事

它把试卷当作一张通用表格，不做任何题型专属检查。 因此它不校验答案字母是否落在所给选项之内、填空题的空数是否正确，也不校验单选题是否恰好只有一个正确选项。这些都需要解析出各题型自身的结构，而本适配器不做这种尝试。该边界写在规则包的头部和故障排查一节中。

除了键的存在性与唯一性，它从不检查数据是否适合导入题库。 标识符重复才是危险情形——导入会静默覆盖已有题目——所以 PD-006 是 warn，所以当没有标识符列时它会在 skipped 中报告自身，而不是去检查错误的列。

难度区间 0–1 是本地约定，不是唯一的量纲。 它是常见约定，数值越大表示越容易；采用 1–5 或百分比的单位可以改 min/max，或直接禁用该规则。

规则包里的每一条 excerpt 都明明白白写着，条文原文未取得——本次核查既没取到 JY/T 0606 的条文，也没取到 yotta 平台的字段规范。等条文到手后，把每条 excerpt 换成真实条文，并把 kind 提升为 direct。

兼容性

| 接口面 | 状态 |
| Harness | Peer 范围 >=0.1.2-rc.1 <0.2.0 \|\| >=0.2.0-0 <0.3.0 —— 已验证可同时接受 0.2.0-rc.2 和 0.2.1-alpha.1。刻意不声明 engines.dsh：它没有读取方，也无法拒绝宿主 |
| Node | ^22.19.0 || >=24.0.0 |
| 平台 | 全部（纯 ESM；无原生代码、无网络、不调用模型） |
| 工具模式 | 在 native、ptc 和 both 下都能用；完整试卷请用 ptc |

它做什么

注册 paper_doc_adapter 工具。它读取一份解析后的试卷 —— 试卷头加每道题一行 —— 套用带版本号的规则包，返回报告。

| 规则 | 检查内容 | 严重级别 | 依据类型 |
| PD-001 | 题号和题干都已记录 | warn | principle |
| PD-002 | 答案或解析存在 | warn | principle |
| PD-003 | 各题分值合计等于试卷总分 | warn | principle |
| PD-004 | 题型来自你的词表（默认关闭） | info | local |
| PD-005 | 难度系数落在你的区间内 | info | local |
| PD-006 | 题目标识存在且唯一 | warn | principle |
| PD-007 | 知识点已记录 | warn | principle |
| PD-008 | 题干里没有未替换的占位符 | warn | principle |

安装

dsh plugin --profile <name> add dsh-paper-doc-adapter
dsh --profile <name> --dump-config | grep 'dsh-paper-doc-adapter'

配置

| 键 | 类型 | 默认值 | 说明 |
| rulesFile | string | rules/paper-doc-adapter.yaml | 规则包路径，相对于包根目录 |
| disabledRules | string[] | [] | 停止运行的规则 id；每个都会出现在 skipped 里 |
| onlyRules | string[] | [] | 只运行这些规则 id；留空则运行全部规则 |
| skipNotes | string | "" | 追加到每条 skipped 原因后面的备注 |
| timeoutMs | number | 120000 | 协作式工具超时预算 |

几个值得了解的规则级参数：

- PD-003 field / headerField / tolerance —— 分值列，以及它必须匹配的试卷头总分。
- PD-004 values —— 你的题型，例如 [单选题, 多选题, 判断题, 填空题, 简答题, 计算题, 作文题]。留空表示不检查。
- PD-005 min / max —— 难度区间，默认 0 到 1。这是本地约定，不是标准数值。
- PD-008 terms —— 要查找的占位符。

素材格式

工具接受 JSON 或 YAML：

paperTitle: 某某科目 2026 年模拟试卷 subject: 某某科目 grade: 高二 paperVersion: 2026 版 totalScore: '3' durationMin: '90' rows:
- { 序号: '1', 题号: '1', 题型: 单选题, 题干: 下列关于……的说法，正确的是（　　）,
选项: A. ……；B. ……；C. ……；D. ……, 答案: B, 解析: 本题考查……，依据……，故 B 正确。, 分值: '3', 难度: '0.72', 知识点: 某某章节 某某知识点, 题目ID: YOTTA-2026-0001, 标签: 基础题 }

列名匹配不区分大小写，并忽略空格、下划线和连字符；试卷自己的列名会保留，所以每条发现都会指出它读的是哪一列。注意 序号 读作该行的显示编号 —— 请给题号单独一列（题号）。

规则来源

规则数据放在 rules/paper-doc-adapter.yaml。文件头部说明了插件不检查哪些内容，每条规则的 note 又重复了该规则相关的关键部分。加载时的守卫仍然要求每条规则都带 document、clause、excerpt 和 source，也仍然禁止把本地配置的检查设为 error。

故障排查

- 答案字母超出选项范围，它没发现。 这是有意为之：插件把试卷当成通用表格处理，不做任何针对题型的校验。
- PD-006 报告自己被跳过。 没有标识列，唯一性检查找不到可以下手的键。它如实报告，而不是去检查错误的列。
- 难度为 1.8 时 PD-005 触发。 默认范围是 0–1；如果你的题库用别的量纲，改 min/max。
- 试卷总分对得上，PD-003 却触发。 表头总分和各行之和对不上——通常是漏了一道题，或者分数打错了。
- PD-004 从不运行。 它的词表是空的；用你题库的题型把它填上。
- 插件装上了，工具却一直不出现。 检查 main 是否指向 lib/index.mjs，以及 pnpm run build 是否生成了它；main 写错会让加载器静默跳过入口。
- dsh plugin add 以不兼容为由拒绝这个包。 peer 范围覆盖 0.1.x 和 0.2.x；如果你的运行时不在这个范围内，显式授予豁免： dsh plugin --profile <name> allow-version dsh-paper-doc-adapter@0.1.0 --dsh-version <runtime> --accept-risk
- check 报告 manifest-peers 失败。 静态检查器比对的是一个硬编码的 peer 范围，它早于 0.2 系列。运行时会在安装时强制校验 peer 兼容性，所以声明的范围才是正确的；这是 dsh-plugin-dev 里已知的上游问题。

开发

pnpm install
pnpm run typecheck # tsc --noEmit
pnpm test # vitest, the shared table-plugin suite plus paired fixtures
pnpm run build # tsdown -> lib/index.mjs + lib/index.d.mts
node ../scripts/sync-shared.mjs dsh-paper-doc-adapter # refresh src/shared from ../_shared

插件是纯数据的：src/model.ts 声明表格形状，共享套件提供读取器和检查引擎，规则包声明每一项检查。

许可证

Apache License 2.0 © 2026 dsh-paper-doc-adapter contributors.