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

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

• 标准答案识别：从“答案页/题目页”图片识别出结构化标准答案（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）。

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

在 CardGraderAI 目录下执行：

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

• 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/模型之间切换。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

• 采用语义化版本号 (Semantic Versioning)：Major.Minor.Patch (主版本.次版本.修订号)。
  • Major：包含不兼容的 API 更改或重大架构调整。
  • Minor：增加向下兼容的新功能。
  • Patch：向下兼容的问题修复 (Bug Fixes)。
• 更新位置：每次更新需在 手写答题卡识别.csproj 中的 <Version> 标签同步修改，程序会自动读取并显示在“关于”页面。

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

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

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