试卷生成器 elegymythos/exam-paper-plugin

exam-paper-plugin

DeepSeek Harness 插件：解析 Word / PDF 题目，生成带书写空隙的可打印试卷，并内置一套纯 Python 智能试题引擎，用于本地多视图特征提取、聚类、语义检索与多样性抽题，从而减少大模型 Token 消耗。

功能

基础能力

- 自动解析 .doc / .docx / .pdf / .txt / .md 题目文件
- 识别选择题、填空题、判断题、解答题、作文等题型
- 提取题干、选项和配图（图片仅保留位置关联与 has_image 标记）
- 支持 WMF/EMF 公式图：DOCX 输出补齐内容类型，HTML 输出自动转换为 PNG 预览
- 按需抽题并生成 .docx + .html 试卷
- 支持卷头、书写空隙、选择题双列等出卷配置

智能引擎能力

- 多视图特征提取：文本、分类、结构、统计四个视图
- 不处理图片内容，不引入难度维度
- HDBSCAN 自动聚类，支持离群点识别
- 聚类解释报告，支持人工给“簇”打标签，而非逐题标注
- FAISS 向量索引，余弦相似度检索
- 分类硬过滤 + 向量召回 + MMR 多样性重排
- 版本化评估工具：聚类质量、检索效果、多样性效果、系统性能、版本对比
- 本地 Ollama Token 消耗评估

项目结构

exam-paper-plugin/
├── src/
│ ├── plugin.mjs # Cordis 插件入口，注册工具 │ └── exam_paper.py # 文档解析与试卷生成引擎 ├── smart_engine/ # 纯 Python 智能试题引擎 │ ├── cli.py # CLI 命令入口 │ ├── pipeline.py # 编程调用门面（供插件/二次开发） │ ├── features.py # 多视图特征提取 │ ├── clustering.py # HDBSCAN 聚类与报告 │ ├── labels.py # 簇标签映射 │ ├── index.py # FAISS 向量索引 │ ├── mmr.py # 多样性重排 │ └── eval/ # 评估工具 ├── install.sh # Linux/macOS 安装脚本 ├── install.ps1 # Windows 安装脚本 ├── install.bat # Windows 双击入口 ├── requirements.txt # 智能引擎 Python 依赖 ├── environment.yml # Conda 环境模板（国内镜像） └── data/sample/questions.json # 示例题目数据

安装

Linux / macOS

git clone exam-paper-plugin
cd exam-paper-plugin
./install.sh

可选参数：

./install.sh --with-doc # 额外询问安装 .doc 转换后端 ./install.sh --install-deps # 自动安装缺失依赖（含智能引擎） ./install.sh --skip-deps # 跳过所有依赖安装 ./install.sh --skip-smart # 只装插件，不装智能引擎依赖 ./install.sh --uninstall # 卸载

安装脚本会：

1. 复制 plugin.mjs、exam_paper.py、smart_engine/ 到 Harness 插件目录；
2. 建立 @deepseek-ai 依赖作用域链接；
3. 注册“试卷生成”代理预设；
4. 交互式选择智能引擎 Python 环境：
- [1] 在插件目录创建 .venv 虚拟环境（推荐）；
- [2] 指定你已有的 Python 解释器；
- [3] 跳过智能引擎依赖。
5. 如果选择指定 Python，会把解释器路径写入 smart_python.txt，插件运行时优先使用该 Python。

Windows

powershell -ExecutionPolicy Bypass -File install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1 -InstallDeps
powershell -ExecutionPolicy Bypass -File install.ps1 -SkipSmart
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall

安装智能引擎依赖时同样支持选择“创建 .venv”或“指定现有 Python”。

作为 bundle 安装

dsh plugin --profile add "github:/exam-paper-plugin"
或本地路径
dsh plugin --profile add "/path/to/exam-paper-plugin"

使用

基础出卷

上传题目文件后对 Agent 说：

解析 /path/to/数学试卷.docx 里的题目

然后：

要第 1、3、5 题，标题「数学单元测验（一）」，解答题留 8 行横线

智能抽题

插件提供两个新增工具：

| 工具 | 作用 |
| index_question_bank | 解析题目并建立本地智能索引 |
| smart_select_questions | 按查询词与分类条件智能抽题，返回多样性候选 |

对 Agent 说：

用智能抽题从这些文件里选 5 道数学函数题

引擎会执行：解析 → 导入题库 → 建索引 → 向量召回 → MMR 多样性重排 → 返回少量候选。

智能引擎 CLI

独立开发/测试时可直接使用：

使用 conda 或 venv 创建 Python 3.10 环境
pip install -r requirements.txt

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 report --markdown
python -m smart_engine.cli --workdir ./data/engine label set 1 一次函数
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
python -m smart_engine.cli --workdir ./data/engine eval quick
python -m smart_engine.cli --workdir ./data/engine eval full
python -m smart_engine.cli --workdir ./data/engine eval compare

本地大模型 Token 评估

安装好 Ollama 并下载模型后：

python -m smart_engine.cli --workdir ./data/engine eval token \
--model deepseek-r1:1.5b \
--sample-questions 20 \
--num-ctx 16384

输出示例：

{
"full_context_tokens": 9438,
"smart_context_tokens": 1035,
"token_savings_ratio": 0.8903
}

与现有插件架构的适配分析

交互方式

- 现有插件通过 Cordis shell 服务调用 Python 脚本，输入输出为 JSON。
- 智能引擎同时提供 CLI 与 Python API，后续可直接被 plugin.mjs 调用，也可以被其他脚本导入。
- 插件中新增的 smart_select_questions 在会话工作区 .exam-paper/smart-engine/ 下保存索引和标签，不污染全局环境。

依赖与部署

- 基础解析引擎继续零第三方依赖，保证核心出卷功能稳定。
- 智能引擎依赖集中在 requirements.txt，安装脚本默认创建 .venv 隔离，避免影响系统 Python。
- 如果没有安装智能引擎依赖，原有 parse_question_file / generate_exam_paper 不受影响。

生命周期与资源管理

- SmartExamEngine 支持 init → import → build-index → search/select → close 的明确生命周期。
- 插件每次调用通过 CLI 子进程方式工作，避免常驻进程带来的复杂状态管理。
- 后续如果需要更高性能，可以在不改核心逻辑的情况下增加常驻服务模式。

输入输出兼容

- 智能引擎的题目字段与 exam_paper.py 解析结果保持一致。
- 抽题结果可直接交给 generate_exam_paper 生成试卷，无需额外转换。

可扩展点

- 文本特征目前默认使用 TF-IDF，可切换为本地 Ollama Embedding。
- 聚类参数、特征权重、MMR 参数、索引路径均通过统一配置管理。
- 标签映射支持导入导出，便于人工维护知识点体系。

测试与评估

python -m pytest -q tests/

评估维度：

- 聚类质量：轮廓系数、噪声比例、簇大小分布、簇数量稳定性
- 检索效果：分类过滤命中率、Top-K 召回、检索耗时、内存占用
- 多样性效果：MMR 前后重复知识点/题型比例、λ 敏感性
- 系统性能：不同数据量级下的建索引耗时、检索耗时、资源占用
- 版本对比：保存历史评估结果，自动标记关键指标回归

数据说明

- data/sample/questions.json 是随仓库保留的示例数据。
- 真实试卷等大文件建议放在 data/ 下，但已被 .gitignore 排除，不会进入 Git 历史。
- 智能引擎运行数据位于 data/engine*/ 或会话工作区的 .exam-paper/，同样不会提交。

License

MIT