exam-paper-plugin

Readme

# 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 消耗评估

## 项目结构

```text
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

```bash
git clone <your-repo-url> exam-paper-plugin
cd exam-paper-plugin
./install.sh
```

可选参数：

```bash
./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
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 安装

```bash
dsh plugin --profile <name> add "github:<owner>/exam-paper-plugin"
# 或本地路径
dsh plugin --profile <name> add "/path/to/exam-paper-plugin"
```

## 使用

### 基础出卷

上传题目文件后对 Agent 说：

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

然后：

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

### 智能抽题

插件提供两个新增工具：

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

对 Agent 说：

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

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

### 智能引擎 CLI

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

```bash
# 使用 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 并下载模型后：

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

输出示例：

```json
{
  "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 参数、索引路径均通过统一配置管理。
- 标签映射支持导入导出，便于人工维护知识点体系。

## 测试与评估

```bash
python -m pytest -q tests/
```

评估维度：

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

## 数据说明

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

## License

[MIT](LICENSE)