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 <your-repo-url> 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 <name> add "github:<owner>/exam-paper-plugin"
# 或本地路径
dsh plugin --profile <name> 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 <old> <new>

本地大模型 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