前言¶
在 DSH 的插件工作方式里，很多重复文档任务可以拆成独立插件。出题流程里比较常见的痛点，是题目散在 .doc、.docx、.pdf、.txt、.md 文件里，需要人工识别题型、挑选题目、排版成可打印试卷；如果直接让模型读完整题库，上下文和 Token 消耗也会比较高。exam-paper-plugin 针对这个流程提供基础解析出卷，以及本地智能索引、聚类、检索和抽题。下面介绍它的能力、安装方式和常用命令。
这是什么¶
exam-paper-plugin 是 elegymythos 维护的 DeepSeek Harness 插件，许可证为 MIT。它把题目文件解析成可处理结构，按需抽题，并生成 .docx 与 .html 试卷；智能引擎部分在本地做特征提取、聚类、向量检索和多样性重排。
核心功能¶
基础出卷¶
- 自动解析
.doc/.docx/.pdf/.txt/.md题目文件。 - 识别选择题、填空题、判断题、解答题、作文等题型。
- 提取题干、选项和配图；图片不处理内容，仅保留位置关联与
has_image标记。 - 支持
WMF/EMF公式图：DOCX 输出补齐内容类型，HTML 输出自动转换为 PNG 预览。 - 按需抽题并生成
.docx+.html试卷。 - 支持卷头、书写空隙、选择题双列等出卷配置。
智能引擎¶
- 多视图特征提取：文本、分类、结构、统计。
- HDBSCAN 自动聚类，支持离群点识别与聚类解释报告。
- FAISS 向量索引与余弦相似度检索。
- 分类硬过滤 + 向量召回 + MMR 多样性重排。
- 提供
index_question_bank和smart_select_questions工具。 - 提供 CLI 与 Python API，用于本地智能索引、聚类、检索与抽题。
- 支持版本化评估工具和本地 Ollama Token 消耗评估。
安装与启用¶
插件依赖 @deepseek-ai/dsh-tools >=0.1.0-rc.0。按 DSH 插件方式安装时，可以使用仓库给出的 bundle 命令：
dsh plugin --profile <name> add "github:<owner>/exam-paper-plugin"
<name> 是 profile 名，<owner> 是仓库 owner，按实际环境替换。
智能引擎依赖集中在 requirements.txt。安装脚本默认创建 .venv 隔离 Python 依赖。如果未安装智能引擎依赖，原有 parse_question_file / generate_exam_paper 仍可使用。
典型用法¶
基础出卷¶
上传或指定题目文件后，可以对 Harness 会话说：
解析 /path/to/数学试卷.docx 里的题目
继续指定抽题和出卷参数：
要第 1、3、5 题，标题「数学单元测验（一）」，解答题留 8 行横线
这一步会按指定题目生成可打印试卷，输出包含 .docx 与 .html。
智能抽题¶
智能抽题使用 index_question_bank 与 smart_select_questions 工具。对会话说：
用智能抽题从这些文件里选 5 道数学函数题
流程会先建立本地索引，再执行分类硬过滤、向量召回和 MMR 多样性重排，返回少量候选题。
CLI¶
独立运行智能引擎时，先初始化工作区：
python -m smart_engine.cli --workdir ./data/engine init
导入示例题目、建立索引和聚类：
python -m smart_engine.cli --workdir ./data/engine import data/sample/questions.json
python -m smart_engine.cli --workdir ./data/engine build-index
python -m smart_engine.cli --workdir ./data/engine cluster
检索和抽题：
python -m smart_engine.cli --workdir ./data/engine search --query "二次函数" --top-k 5
python -m smart_engine.cli --workdir ./data/engine select --query "二次函数" --count 3
版本化评估与本地 Ollama Token 评估：
python -m smart_engine.cli --workdir ./data/engine eval quick
python -m smart_engine.cli --workdir ./data/engine eval token --model deepseek-r1:1.5b --sample-questions 20 --num-ctx 16384
适用场景与注意¶
适合在本地维护题库、需要把 Word/PDF 题目转成可打印试卷、并希望减少完整题库进入大模型上下文的 DSH 用户。
使用前注意几点：
- 插件以当前
dsh进程权限运行。安装前应检查源码与许可证。 - 图片只保留位置关联与
has_image标记，不处理图片内容。 - 智能引擎不引入难度维度。
- 基础解析引擎继续零第三方依赖；智能引擎依赖集中在
requirements.txt，默认通过.venv隔离。 - 真实试卷等大文件建议放在
data/下，但已被.gitignore排除；智能引擎运行数据位于data/engine*/或会话工作区.exam-paper/，同样不会提交。
结尾¶
exam-paper-plugin 把“解析题目、抽题、生成可打印试卷”放到本地插件里处理，再用智能引擎做索引、聚类、检索和多样性重排，适合作为 DSH 出题流程的基础能力。可以在 DeepSeek Harness 社区目录按 exam-paper-plugin 查找，也可以访问 GitHub 仓库：
