# 智能阅卷系统

**Repository Path**: interim/CardGraderAI

## Basic Information

- **Project Name**: 智能阅卷系统
- **Description**: 手写答题卡识别，是处理手写的 图片的答题卡的，识别题目答案，得到对错结果，并给出评价和建议，并返回结果。
- **Primary Language**: C#
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能阅卷系统（AI Powered）

![系统展示](展示图片/image1.png)

用于将纸质试卷/手写答题卡图片进行结构化识别，并在提供“标准答案/评分参考”的前提下，自动完成题目级别的对错判定、得分统计、错题汇总与结果导出。

作者：磁县教师发展中心 郑重  
工作室：邯郸市信息技术马建辉名师工作室

## 主要功能

- 标准答案识别：从“答案页/题目页”图片识别出结构化标准答案（JSON），可作为后续批改参考
- 批量批改：对多张学生答题卡图片并发处理，输出每题结果、总分、总体分析
- 扫描采集：支持 TWAIN 扫描仪采集并保存到本地目录，可加入批量列表
- 结果展示与导出：
  - 界面内表格展示（DevExpress Spreadsheet）
  - 导出 CSV（便于 Excel 透视分析）
  - 生成批次报告（txt / 原始 json）
- 学生档案沉淀：按学生姓名/科目追加保存分析与错题，便于长期跟踪
- 数据库留存：使用 SQLite 保存考试记录与题目明细，便于后续查询统计

## 运行环境

- Windows 10/11
- .NET SDK 9（项目目标框架：`net9.0-windows`）
- Visual Studio 2022（建议 17.14+，或使用 `dotnet` 命令行）
- AI 接口：支持 OpenAI 兼容的 Chat Completions 服务（`Endpoint` + `API Key` + `ModelId`）

依赖包见 `手写答题卡识别.csproj`（例如：`Microsoft.SemanticKernel`、`Microsoft.Data.Sqlite`、`NTwain`、`DevExpress.Win.Spreadsheet`）。

## 快速开始

### 方式一：Visual Studio 运行

1. 打开 `手写答题卡识别.sln`
2. 还原 NuGet 包（VS 会自动还原）
3. 直接运行（F5）

### 方式二：命令行运行（PowerShell）

在 `CardGraderAI` 目录下执行：

```powershell
dotnet restore .\手写答题卡识别.csproj
dotnet run --project .\手写答题卡识别.csproj
```

## 使用说明（按界面标签页）

### 1）模型设置

- `API Key`：你的模型服务密钥（界面中会以 `*` 显示）
- `Model ID`：例如 `gpt-4o`（或你服务端支持的模型名）
- `Endpoint`：OpenAI 兼容服务的基地址，例如：
  - OpenAI：`https://api.openai.com/v1`
  - 本地/内网兼容服务：`http://127.0.0.1:11434/v1`（示例）
- 并发数：用于批量处理时的最大并发任务数
- `MaxTokens`：每次请求允许的最大输出 token
- 推理开关/强度：用于支持具备 “reasoning” 参数的兼容服务（不支持的服务可关闭）
- 自动预处理：启用后会对输入图片做压缩/缩放等处理以降低成本与失败率（以程序实现为准）

模型配置支持“保存为配置模板”，便于在多个 Key/模型之间切换。

### 2）系统提示词

系统提示词用于约束 AI 的输出结构与评分规则。程序内置了一份默认提示词，也支持维护多份“提示词库”。

### 3）标准答案

1. 点击“识别图片为答案...”，选择包含题目/标准答案/评分标准的图片（支持多选）
2. 识别结果会以 JSON 文本形式存入“标准答案”文本框
3. 后续批量批改时，会把该标准答案作为评分参考拼接进最终 Prompt

### 4）测试功能

用于单图快速验证识别与批改效果：

1. 选择图片（支持旋转预览）
2. 点击测试按钮，观察日志与输出

### 5）扫描

点击扫描后，会通过 TWAIN 设备采集图片，并保存到：

- `ScannedImages\yyyy-MM-dd\TwainScan_yyyyMMddHHmmss.jpg`

扫描得到的图片可加入“批量列表”。

### 6）批量处理

![批量处理过程](展示图片/image2.png)

1. 选择一批学生答题卡图片（或从扫描页加入）
2. 点击开始处理
3. 处理过程中会：
   - 生成批次目录：`ExamResults\yyyy-MM-dd_HHmmss\`
   - 按学生输出报告：`{学生姓名}.txt` 与 `{学生姓名}-json.json`（无姓名时用序号）
   - 追加学生档案：`StudentKnowledgeBase\{学生姓名}\{科目}.txt`
   - 保存 SQLite：`StudentData.db`（在程序运行目录）

### 7）结果/导出

![结果展示与导出](展示图片/image3.png)

- 界面内可查看结果表格
- 可导出 CSV（UTF-8 编码，便于 Excel 打开不乱码）

## 配置文件说明

程序会在运行目录自动读写 `appSettings.json`，用于保存：

- 当前模型信息（`ApiKey`/`ModelId`/`Endpoint`）
- 系统提示词、识别提示词、标准答案文本
- 提示词库、模型配置库
- 部分界面参数（并发、表格样式等）

说明：`appSettings.json` 中包含密钥信息，建议不要上传到公开仓库。

## 输出文件一览

- `appSettings.json`：运行配置（包含密钥）
- `StudentData.db`：SQLite 数据库（考试记录与题目明细）
- `ExamResults\...`：每次批量处理的批次输出（txt/json）
- `StudentKnowledgeBase\...`：按学生沉淀的长期档案
- `ScannedImages\...`：扫描仪采集图片

## 版本更新

### v1.0.0 (2025-12-30)
- **初始版本发布**：支持标准答案识别、批量批改、扫描采集、结果导出、学生档案沉淀等核心功能。
- **UI 优化**：集成了 DevExpress Spreadsheet 用于结果展示。
- **数据库支持**：引入 SQLite 持久化存储考试数据。
- **关于页面**：新增“关于我们”页面，支持动态显示程序版本号。

---

## 版本更新与维护预案

为了确保系统的长期稳定运行与功能迭代，制定以下版本维护方案：

### 1. 版本号管理规范
- **采用语义化版本号** (Semantic Versioning)：`Major.Minor.Patch` (主版本.次版本.修订号)。
  - **Major**：包含不兼容的 API 更改或重大架构调整。
  - **Minor**：增加向下兼容的新功能。
  - **Patch**：向下兼容的问题修复 (Bug Fixes)。
- **更新位置**：每次更新需在 [手写答题卡识别.csproj](file:///d:/MyCSharpCode/%E6%89%8B%E5%86%99%E7%AD%94%E9%A2%98%E5%8D%A1%E8%AF%86%E5%88%AB/CardGraderAI/%E6%89%8B%E5%86%99%E7%AD%94%E9%A2%98%E5%8D%A1%E8%AF%86%E5%88%AB.csproj) 中的 `<Version>` 标签同步修改，程序会自动读取并显示在“关于”页面。

### 2. 更新流程预案
- **文档同步**：每次发布新版本，必须同步更新 `README.md` 的“版本更新”章节。
- **配置文件迁移**：若更新涉及 `appSettings.json` 结构变更，需在程序启动时增加旧配置的自动兼容与迁移逻辑。
- **数据库升级**：若更新涉及 `StudentData.db` 表结构变更，需使用 SQLite 迁移脚本或在 `DatabaseService` 中实现自动升表逻辑。

### 3. 未来扩展规划（待实施）
- **自动检查更新**：计划在程序启动时请求指定的 JSON 接口（如 GitHub Release），比对本地版本号并提醒用户下载新版。
- **在线热更新**：探索基于 `.zip` 包解压覆盖的轻量化更新方案。

## 免责声明

本项目属于教学与教研用途的工具实践。AI 结果可能存在误判，请在正式使用中保留人工复核环节，尤其是主观题与复杂题型。