前言¶
在 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 倉庫：
