# med-exam-kit

**Repository Path**: stackzhao/med-exam-kit

## Basic Information

- **Project Name**: med-exam-kit
- **Description**: 自动从医学考试 App（如阿虎医考、医考帮）中提取题目数据的AutoX.js脚本
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-14
- **Last Updated**: 2026-03-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 医学考试题库爬取与处理工具

本项目是一个完整的医学考试题库自动化解决方案，包含两大部分：

1.  **爬虫部分**：使用 AutoX.js 脚本自动从医学考试 App（如阿虎医考、医考帮）中提取题目数据。
2.  **后处理部分**：使用 Python 程序对爬取的 JSON 数据进行去重、格式转换和导出。

通过本工具，您可以将手机上的医学考试题目高效地整理成 Excel、Word、PDF 等多种格式，也可以进行自动组卷，方便学习和复习。

## 功能特点

- **自动化爬取**：无需手动复制粘贴，节省大量时间。
- **多平台支持**：支持阿虎医考、医考帮等多个医学考试 App。
- **智能去重**：自动识别并去除重复题目，保证题库质量。
- **多格式导出**：支持导出为 XLSX、CSV、DOCX、PDF 等常用格式。
- **数据统计**：提供题目数量、正确率等统计信息。
- **AI 解析补全**：调用 AI 大模型自动为缺少解析或答案的题目补全内容，支持 OpenAI、DeepSeek、Qwen3 等主流模型及深度思考模式。
- **可视化编辑**：内置本地 Web 编辑器，在浏览器中直接修改题目、解析、批量替换文本。
- **智能刷题**：内置本地 Web 刷题应用，支持练习模式、考试模式、背题模式三种学习方式，具备错题本功能，以 SM-2 算法进行记忆。

## 目录结构

```
med-exam-kit/
├── js/                 # AutoX.js 爬虫脚本
│   ├── ah.js           # 阿虎医考爬虫脚本
│   └── ykb.js          # 医考帮爬虫脚本
├── src/                # Python 后处理源码
├── data/
│   ├── raw/            # 存放爬取的原始 JSON 文件
│   └── output/         # 存放处理后的输出文件
├── config.yaml         # 项目配置文件
├── pyproject.toml      # Python 项目依赖配置
└── Makefile            # 常用命令快捷方式
```

## 快速开始

对于初次使用的用户，建议按照以下顺序阅读本文档：

1.  **给没有编程经验用户的详细操作指南**：这是最详细的步骤说明，适合完全不了解编程的用户。
2.  **第一部分：使用爬虫脚本（AutoX.js）**：了解爬虫的基本原理和操作。
3.  **第二部分：使用Python进行后处理**：了解数据处理的方法和命令。
4.  **命令行高级用法：** [COMMAND.md](COMMAND.md)
 
## 使用流程概述

整个使用流程分为两个主要步骤：

1.  **数据爬取**：使用 AutoX.js 脚本在 Android 设备上运行，自动提取题目并保存为 JSON 文件。
2.  **数据处理**：使用 Python 程序读取 JSON 文件，进行去重和格式转换，最终导出所需格式的文件。

接下来将详细介绍每个步骤的具体操作方法。

## 第一部分：使用爬虫脚本（AutoX.js）

此部分用于从医学考试 App 中自动提取题目数据。您需要在 Android 设备上安装 AutoX.js 应用并配置相关脚本。

### 准备工作

1.  **安装 AutoX.js**：
    - 在您的 Android 设备上下载并安装 AutoX.js 应用（可在酷安、GitHub 等平台搜索下载）。
    - 确保 Android 设备已开启无障碍服务和悬浮窗权限给 AutoX.js。

2.  **准备目标 App**：
    - 在 Android 设备上安装您要爬取的医学考试 App（如阿虎医考、医考帮）。
    - 确保 App 内已有您需要爬取的题目内容。

3.  **传输脚本文件**：
    - 将本项目 `js/` 目录下的对应脚本文件（`ah.js` 或 `ykb.js`）传输到 Android 设备。
    - 在 AutoX.js 应用中导入该脚本文件。

### 操作步骤

1.  **配置脚本**：
    - 打开 AutoX.js 应用，编辑导入的脚本。
    - 确认脚本中的 `OUTPUT_DIR` 变量指向您希望保存 JSON 文件的路径（默认为 `/sdcard/tests/`）。
    - 根据需要调整其他配置项（如 `SKIP_MODES` 等）。

2.  **运行脚本**：
    - 在 AutoX.js 中启用脚本的无障碍服务。
    - 启动目标医学考试 App，并导航到您想要爬取的题目列表。
    - 返回 AutoX.js 应用，运行脚本。
    - 脚本会自动遍历题目，提取内容并保存为 JSON 文件到指定目录。

3.  **获取数据**：
    - 脚本运行完成后，前往 `OUTPUT_DIR` 指定的路径查看生成的 JSON 文件。
    - 将这些 JSON 文件传输到电脑，存放到本项目的 `data/raw/` 目录中，供后续处理。

### 使用 VSCode 进行远程开发（推荐）

为了更方便地编辑和调试脚本，您可以使用 VSCode 配合 AutoX.js 插件进行远程开发。

#### 准备工作

1.  **安装 VSCode**：在您的电脑上安装 Visual Studio Code。
2.  **安装 AutoX.js 插件**：在 VSCode 扩展商店中搜索并安装 "Auto.js-Autox.js-VSCodeExt" 插件。
3.  **连接设备**：确保您的 Android 设备通过 USB 数据线连接到电脑，并开启了 USB 调试模式。

#### 操作步骤

1.  **连接设备**：
   - 打开 VSCode，在侧边栏找到 Auto.js 插件图标。
   - 点击插件图标，详细阅读插件使用流程
   - 确保 AutoX.js 应用已在手机上运行。

2.  **编辑脚本**：
   - 在 VSCode 中打开项目文件夹。
   - 直接编辑 `js/` 目录下的脚本文件（`ah.js` 或 `ykb.js`）。

3.  **同步和运行**：
   - 编辑完成后，使用插件提供的同步功能将脚本推送到手机上的 AutoX.js 应用。
   - 在 VSCode 中可以直接运行或停止脚本，无需在手机上操作。

4.  **调试**：
   - 可以利用 VSCode 的断点调试功能来调试脚本。
   - 查看实时日志输出，便于排查问题。

### 爬虫风险提示

在使用本工具进行数据爬取时，请务必了解并承担以下风险：

#### 法律合规风险
- **版权侵犯**：爬取的题目内容可能受版权保护，未经授权的复制、传播可能构成侵权。
- **法律法规**：请确保您的爬取行为符合当地法律法规，避免违反《著作权法》、《网络安全法》等相关法律条款。
- **使用目的**：本工具仅供个人学习和研究使用，请勿用于商业用途或非法活动。

#### 账号安全风险
- **账号封禁**：目标 App 可能检测到异常访问行为，导致您的账号被限制或封禁。
- **账号追踪**：频繁或大规模的爬取行为可能被记录，增加账号被识别和追踪的风险。

#### 技术风险
- **数据错误**：爬取过程中可能出现数据丢失、错误或不完整的情况。
- **设备故障**：长时间运行脚本可能导致设备发热、卡顿或异常重启。
- **兼容性问题**：目标 App 更新后可能导致脚本失效，需要及时调整。

### 注意事项

- 爬取过程中请勿手动操作手机，以免干扰脚本运行。
- 确保网络连接稳定，避免因加载问题导致数据缺失。
- 部分 App 可能存在反爬机制，如遇到问题可尝试降低爬取速度或暂停后重新开始。
- 请合理控制爬取频率，避免对服务器造成过大压力。
- 建议定期备份已爬取的数据，以防意外丢失。

## 第二部分：使用Python进行后处理

此部分用于对爬取得到的 JSON 文件进行去重、格式转换等处理，并导出为便于使用的文件格式。

### 准备工作

1.  **安装 Python**：
    - 确保您的电脑已安装 Python 3.10 或更高版本。
    - 可以通过命令行输入 `python --version` 或 `python3 --version` 来检查。

2.  **安装项目依赖**：
    - 打开命令行工具（Windows 用户可用 CMD 或 PowerShell，Mac/Linux 用户可用终端）。
    - 进入项目根目录（即包含 `pyproject.toml` 的目录）。
    - 运行以下命令安装所需的 Python 库：
      ```bash
      pip install -e .
      ```
      如果您使用的是 Python 3，可能需要使用 `pip3`：
      ```bash
      pip3 install -e .
      ```

### 操作步骤

1.  **准备原始数据**：
    - 确保您已将爬取得到的 JSON 文件放入 `data/raw/` 目录。

2.  **运行处理程序**：
    - 在命令行中，进入项目根目录。
    - 使用 `med-exam` 命令来执行不同的处理任务。

    **查看数据信息**：
    ```bash
    med-exam info
    ```
    此命令会显示 `data/raw/` 目录中 JSON 文件的数量、题目类型分布等信息。

    **导出为不同格式**：
    - 导出为 Excel 文件：
      ```bash
      med-exam export -f xlsx
      ```
    - 导出为 CSV 文件：
      ```bash
      med-exam export -f csv
      ```
    - 导出为 Word 文档：
      ```bash
      med-exam export -f docx
      ```
    - 导出为 PDF 文件：
      ```bash
      med-exam export -f pdf
      ```
    - 导出为数据库文件：
      ```bash
      med-exam export -f db
      ```

    **同时导出多种格式**：
    ```bash
    med-exam export -f xlsx -f csv -f docx
    ```

    **导出特定条件的题目**：
    - 只导出正确率低于 50% 的难题：
      ```bash
      med-exam export -f xlsx --max-rate 50
      ```
    - 只导出 A1 型题目：
      ```bash
      med-exam export -f xlsx --mode A1
      ```

3.  **查看结果**：
    - 处理完成后，导出的文件将保存在 `data/output/` 目录中。
    - 您可以打开这些文件进行查看和使用。

### 配置说明

- 项目的处理行为可以通过 `config.yaml` 文件进行配置，例如修改输入输出目录、调整去重策略等。
- 如果您不了解 YAML 格式，请谨慎修改此文件，以免影响程序正常运行。

## 第三部分：刷题练习

本项目内置了本地 Web 刷题应用，支持三种学习模式，帮助您高效复习医学考试题目。

### 启动刷题应用

首先需要构建或准备好 `.mqb` 格式的题库文件：

```bash
# 构建题库（从 JSON 文件）
med-exam build -i data/raw -o data/output/questions

# 启动刷题应用
med-exam quiz --bank data/output/questions.mqb
```

启动后会自动在浏览器中打开 `http://127.0.0.1:5174`。

### 命令参数

```bash
med-exam quiz --bank <题库路径> [选项]

选项：
  --password    题库密码（如果题库已加密）
  --port        本地端口（默认 5174）
  --host        监听地址（默认 127.0.0.1）
  --no-browser  不自动打开浏览器
```

### 三种学习模式

#### 1. 练习模式

- **特点**：即时反馈，边做边学
- **交互**：选择答案后立即显示正确/错误状态和详细解析
- **适用场景**：日常学习和知识点巩固
- **快捷键**：数字键 1-5 选择答案，方向键 ← → 切换题目

#### 2. 考试模式

- **特点**：计时限时，模拟正式考试环境
- **功能**：
  - 支持自定义考试时长（60/90/120/150 分钟）
  - 题目小地图导航，可快速跳转任意题目
  - 支持标记功能，方便回顾疑难题目
  - 提交后统一显示结果和解析
- **适用场景**：模拟真实考试环境，检验学习成果

#### 3. 背题模式

- **特点**：卡片翻转式学习，强化记忆
- **交互**：先看题目思考，点击揭示答案，然后自我评估掌握程度
- **功能**：
  - 支持"已掌握"和"再练一次"的自评机制
  - 智能重复未掌握题目
  - 左右滑动进行自评（移动端）
- **适用场景**：考前冲刺和重点题目强化记忆

### 功能特性

- **多设备适配**：响应式设计，支持桌面和移动设备
- **主题切换**：支持深色/浅色主题，保护视力
- **题目筛选**：可按章节、题型进行筛选练习
- **进度统计**：实时显示答题进度和正确率
- **触控优化**：移动端支持滑动切题等手势操作
- **键盘快捷键**：桌面端支持键盘快捷操作

### 键盘快捷键

| 按键 | 功能 |
|------|------|
| 1-5 | 选择对应选项 |
| ← / → | 上一题 / 下一题 |
| Enter | 提交答案 / 下一题 |
| Escape | 返回首页 |

## 给没有编程经验用户的详细操作指南

如果您对编程不太熟悉，不用担心！以下是更详细的步骤指导，帮助您顺利完成整个过程。

### 第一步：准备工作

1.  **下载项目文件**：
    - 访问本项目的代码仓库（如果是在 GitHub 等平台），下载整个项目压缩包到您的电脑上。
    - 解压压缩包到一个容易找到的文件夹，例如桌面。

2.  **安装必要软件**：
    - **Python**：访问 [Python官网](https://www.python.org/downloads/) 下载并安装最新版本的 Python。安装时请勾选 "Add Python to PATH" 选项。
    - **AutoX.js**：在您的 Android 手机上访问 [AutoX.js的GitHub页面](https://github.com/aiselp/AutoX) 下载并安装 AutoX.js 应用。

3.  **准备医学考试 App**：
    - 在您的 Android 手机上安装您想爬取题目的 App（如阿虎医考、医考帮）。
    - 确保 App 内有您需要的题目内容（可能需要购买或解锁相应课程）。

### 第二步：使用手机爬取题目

1.  **传输脚本**：
    - 将解压后的项目文件夹中的 `js` 目录里的 `ah.js`（如果是阿虎医考）或 `ykb.js`（如果是医考帮）文件发送到您的手机（可通过微信、QQ、邮件等方式）。
    - 打开手机上的 AutoX.js 应用，点击 "脚本" 或类似标签，然后点击 "+" 或 "导入" 按钮，选择您刚刚发送到手机的 `.js` 文件。

2.  **设置权限**：
    - 在手机的系统设置中，找到 "应用管理" 或 "权限管理"，为 AutoX.js 开启 "无障碍服务" 和 "悬浮窗" 权限。

3.  **运行爬虫**：
    - 打开目标医学考试 App，导航到您想要爬取的题目列表。
    - 切换到 AutoX.js 应用，点击您刚才导入的脚本，然后点击 "运行"。
    - 此时手机会自动开始翻题并提取内容，请勿手动操作手机，直到脚本运行完毕。

4.  **获取 JSON 文件**：
    - 脚本运行结束后，会在手机的 `/sdcard/tests/` 目录下生成多个 `.json` 文件。
    - 使用手机自带的文件管理器或其他文件管理 App 找到这些文件，将它们发送到电脑上（同样可通过微信、QQ、邮件或数据线传输）。
    - 将这些 JSON 文件全部复制到电脑上之前解压的项目文件夹中的 `data/raw/` 目录里。

### 第三步：在电脑上处理数据

1.  **打开命令行**：
    - **Windows 用户**：在项目文件夹空白处按住 Shift 键，同时鼠标右键，选择 "在此处打开 PowerShell 窗口" 或 "在此处打开命令窗口"。
    - **Mac/Linux 用户**：打开终端应用，使用 `cd` 命令切换到项目文件夹路径。

2.  **安装依赖**：
    - 在打开的命令行窗口中，输入以下命令并按回车键执行：
      ```bash
      pip install -e .
      ```
      如果提示找不到 `pip`，尝试使用 `pip3`：
      ```bash
      pip3 install -e .
      ```

3.  **执行导出命令**：
    - 在命令行中输入您需要的导出命令，例如导出 Excel 文件：
      ```bash
      med-exam export -f xlsx
      ```
      按回车键执行，等待处理完成。

4.  **查看结果**：
    - 处理完成后，前往项目文件夹中的 `data/output/` 目录，即可看到生成的 Excel 或其他格式的文件。
    - 双击打开文件即可查看您爬取并处理好的医学考试题目。

### 常见问题

- **命令行找不到 `med-exam` 命令怎么办？**
  - 确保您已在项目根目录下执行了 `pip install -e .` 命令。
  - 确保您是在同一个命令行窗口中执行导出命令，且没有切换目录。

- **Python 版本过低怎么办？**
  - 请升级到 Python 3.10 或更高版本。

- **JSON 文件无法识别怎么办？**
  - 检查 `data/raw/` 目录下是否有 `.json` 文件。
  - 确认 JSON 文件内容是否完整，没有损坏。

- **导出的文件为空怎么办？**
  - 检查 `data/raw/` 目录中的 JSON 文件是否包含有效数据。

### 致谢

 * 本脚本灵感来自 [https://github.com/wjixiang/ykb_copyer](https://github.com/wjixiang/ykb_copyer)