init: AI Grading Assistant MVP

2026-07-15 21:54:21 +08:00
commit 3b1dc16489
34 changed files with 10266 additions and 0 deletions
@@ -0,0 +1,807 @@
+````markdown
+# AI 阅卷助手（AI Grading Assistant）
+
+> **技术开发文档 V1.0**
+>
+> 技术栈：**Electron + Vue3 + TypeScript + Node.js**
+>
+> 更新时间：2026-07-15
+
+---
+
+# 1. 项目简介
+
+## 1.1 项目背景
+
+目前高校、中小学普遍已使用网上阅卷系统，但教师仍需要逐题阅读学生答案并手动评分，存在以下痛点：
+
+- 重复性劳动强
+- 主观评分容易受疲劳影响
+- 阅卷效率低
+- 长时间阅卷容易漏判、误判
+
+AI 阅卷助手定位为**桌面端 AI Copilot**，通过悬浮工具栏辅助教师完成阅卷，而不是替换现有阅卷系统。
+
+整体工作流程如下：
+
+```text
+学校阅卷系统
+        │
+        ▼
+教师查看学生答案
+        │
+        ▼
+快捷键截图
+        │
+        ▼
+AI 自动评分
+        │
+        ▼
+展示建议分数及扣分原因
+        │
+        ▼
+教师确认或修改
+```
+
+整个过程无需修改学校现有系统，实现"零侵入式"接入。
+
+---
+
+# 2. 项目目标
+
+构建一款跨平台桌面应用，实现以下能力：
+
+- 全局悬浮工具栏
+- 全局快捷键截图
+- AI 图片识别
+- AI 智能阅卷
+- 评分标准管理
+- 历史记录管理
+- 多模型切换
+- 本地模型支持（后续）
+
+---
+
+# 3. 技术架构
+
+## 3.1 技术栈
+
+| 模块 | 技术 |
+|------|------|
+| 桌面框架 | Electron |
+| 前端框架 | Vue3 |
+| 开发语言 | TypeScript |
+| UI组件 | Element Plus |
+| 状态管理 | Pinia |
+| 路由 | Vue Router |
+| 网络请求 | Axios |
+| AI接口 | OpenAI Compatible API |
+| 数据库 | SQLite |
+| ORM | Prisma（可选） |
+| 配置管理 | electron-store |
+| 日志 | electron-log |
+| 图片处理 | Sharp |
+| OCR（可选） | PaddleOCR |
+
+---
+
+## 3.2 系统架构
+
+```text
+                    Electron
+
+           ┌──────────────────────┐
+           │     Main Process      │
+           └──────────┬────────────┘
+                      │ IPC
+ ┌────────────────────┼────────────────────┐
+ │                    │                    │
+ ▼                    ▼                    ▼
+Renderer         Screenshot          AI Service
+(Vue3)             Module             (Node)
+ │                    │                    │
+ │                    ▼                    │
+ │             Image Processing           │
+ │                                         │
+ └───────────────► SQLite ◄────────────────┘
+```
+
+---
+
+# 4. 项目目录结构
+
+```text
+ai-grading-assistant
+
+├── electron
+│   ├── main
+│   │   ├── main.ts
+│   │   ├── window.ts
+│   │   ├── shortcut.ts
+│   │   ├── screenshot.ts
+│   │   ├── ipc.ts
+│   │   └── tray.ts
+│   │
+│   └── preload
+│       └── preload.ts
+│
+├── src
+│   ├── api
+│   ├── assets
+│   ├── components
+│   ├── composables
+│   ├── layouts
+│   ├── pages
+│   ├── router
+│   ├── stores
+│   ├── services
+│   ├── styles
+│   ├── types
+│   ├── utils
+│   ├── App.vue
+│   └── main.ts
+│
+├── database
+│   ├── sqlite.ts
+│   ├── schema.sql
+│   └── migration
+│
+├── prompts
+│
+├── config
+│
+├── logs
+│
+└── package.json
+```
+
+---
+
+# 5. 功能模块设计
+
+## 5.1 悬浮工具栏
+
+### 功能
+
+始终悬浮于所有窗口顶部。
+
+功能按钮：
+
+```text
+┌────────────────────────────────────┐
+│ 📷截图 │ ⚡阅卷 │ 📚模板 │ 📜历史 │ ⚙设置 │
+└────────────────────────────────────┘
+```
+
+特点：
+
+- 无边框
+- 半透明
+- 可拖拽
+- 自动吸附屏幕边缘
+- 支持隐藏
+
+Electron 配置：
+
+```typescript
+new BrowserWindow({
+    width: 420,
+    height: 60,
+    frame: false,
+    transparent: true,
+    alwaysOnTop: true,
+    skipTaskbar: true,
+    resizable: false
+})
+```
+
+---
+
+## 5.2 全局快捷键
+
+默认：
+
+```text
+Alt + Q
+```
+
+支持：
+
+- 修改快捷键
+- 多快捷键配置
+
+例如：
+
+```text
+Alt+Q
+
+开始截图
+```
+
+---
+
+## 5.3 截图模块
+
+流程：
+
+```text
+快捷键
+
+↓
+
+显示遮罩层
+
+↓
+
+鼠标拖动
+
+↓
+
+生成截图
+
+↓
+
+发送AI
+```
+
+功能：
+
+- 全屏截图
+- 区域截图
+- Esc取消
+- Enter确认
+
+输出：
+
+```text
+PNG
+```
+
+---
+
+## 5.4 AI阅卷模块
+
+支持模型：
+
+- GPT
+- Claude
+- Gemini
+- Qwen-VL
+- GLM
+- DeepSeek
+
+支持：
+
+图片直接发送。
+
+无需OCR。
+
+输入：
+
+```
+图片
+
+评分标准
+
+Prompt
+```
+
+输出：
+
+```json
+{
+    "score":9,
+    "confidence":0.96,
+    "deductions":[
+        "未说明ACK作用"
+    ],
+    "comment":"回答完整"
+}
+```
+
+---
+
+## 5.5 评分标准模块
+
+每场考试：
+
+```
+课程
+
+↓
+
+试卷
+
+↓
+
+题目
+
+↓
+
+评分标准
+```
+
+例如：
+
+```text
+Java
+
+期末考试
+
+第5题
+```
+
+评分标准：
+
+```text
+满分
+
+10
+
+评分点
+
+① 多态
+
+② 继承
+
+③ 封装
+```
+
+数据库保存。
+
+---
+
+## 5.6 AI评分展示
+
+右侧弹窗：
+
+```text
+────────────────────
+
+AI建议：
+
+9分
+
+可信度：
+
+96%
+
+扣分：
+
+① 未说明第三次握手意义
+
+评价：
+
+回答基本完整。
+
+────────────────────
+```
+
+按钮：
+
+```
+确认
+
+修改
+
+重新评分
+```
+
+---
+
+## 5.7 历史记录
+
+保存：
+
+- 截图
+- AI评分
+- 教师评分
+- 时间
+- AI耗时
+
+支持：
+
+- 查询
+- 删除
+- 导出Excel
+
+---
+
+# 6. 系统流程
+
+## AI阅卷流程
+
+```text
+开始阅卷
+
+↓
+
+快捷键
+
+↓
+
+截图
+
+↓
+
+AI识别图片
+
+↓
+
+评分标准匹配
+
+↓
+
+AI评分
+
+↓
+
+返回JSON
+
+↓
+
+前端展示
+
+↓
+
+教师确认
+```
+
+---
+
+# 7. Vue 前端架构
+
+```text
+App
+
+│
+
+├── FloatingToolbar
+
+├── ScreenshotOverlay
+
+├── ResultDrawer
+
+├── SettingDialog
+
+├── HistoryPage
+
+├── TemplatePage
+
+└── AboutPage
+```
+
+---
+
+# 8. Electron IPC 通信
+
+```text
+Vue
+
+↓
+
+ipcRenderer.invoke()
+
+↓
+
+Main Process
+
+↓
+
+执行任务
+
+↓
+
+返回数据
+```
+
+事件：
+
+| 名称 | 描述 |
+|------|------|
+| screenshot:start | 开始截图 |
+| screenshot:end | 截图完成 |
+| ai:grade | AI阅卷 |
+| ai:result | AI返回 |
+| history:list | 获取历史 |
+| settings:get | 获取配置 |
+
+---
+
+# 9. 数据库设计
+
+## exam
+
+```sql
+id INTEGER PRIMARY KEY
+
+name TEXT
+
+course TEXT
+
+created_at DATETIME
+```
+
+---
+
+## question
+
+```sql
+id INTEGER PRIMARY KEY
+
+exam_id INTEGER
+
+title TEXT
+
+max_score INTEGER
+
+rubric TEXT
+```
+
+---
+
+## history
+
+```sql
+id INTEGER PRIMARY KEY
+
+question_id INTEGER
+
+image_path TEXT
+
+student_answer TEXT
+
+ai_score REAL
+
+teacher_score REAL
+
+confidence REAL
+
+created_at DATETIME
+```
+
+---
+
+# 10. AI接口封装
+
+统一接口：
+
+```typescript
+interface AIProvider {
+
+    grade(
+        image:string,
+        rubric:string
+    ):Promise<GradeResult>
+
+}
+```
+
+实现：
+
+```text
+OpenAIProvider
+
+GeminiProvider
+
+ClaudeProvider
+
+QwenProvider
+```
+
+方便切换。
+
+---
+
+# 11. Prompt设计
+
+系统Prompt：
+
+```text
+你是一名经验丰富的高校教师。
+
+请依据评分标准严格评分。
+
+要求：
+
+1、识别学生答案
+
+2、分析答案
+
+3、依据评分标准逐项评分
+
+4、输出JSON
+
+禁止输出Markdown。
+```
+
+输出：
+
+```json
+{
+    "score":0,
+    "confidence":0,
+    "deductions":[],
+    "comment":""
+}
+```
+
+---
+
+# 12. 配置管理
+
+支持：
+
+```text
+API Key
+
+Base URL
+
+模型
+
+快捷键
+
+主题
+
+字体
+
+代理
+
+超时时间
+```
+
+保存：
+
+```
+electron-store
+```
+
+---
+
+# 13. 日志系统
+
+记录：
+
+```text
+程序启动
+
+截图
+
+AI请求
+
+AI耗时
+
+异常
+
+退出
+```
+
+使用：
+
+```
+electron-log
+```
+
+---
+
+# 14. 异常处理
+
+截图失败：
+
+```
+重新截图
+```
+
+AI失败：
+
+```
+重新评分
+```
+
+JSON解析失败：
+
+```
+重新生成
+```
+
+网络异常：
+
+```
+请检查网络连接
+```
+
+---
+
+# 15. 开发计划
+
+## 第一阶段（MVP）
+
+预计：2 周
+
+完成：
+
+- Electron 初始化
+- Vue3 页面
+- 悬浮工具栏
+- 快捷键截图
+- AI 调用
+- AI 评分展示
+
+---
+
+## 第二阶段
+
+预计：2 周
+
+完成：
+
+- 评分模板
+- 历史记录
+- 设置页面
+- 多模型支持
+
+---
+
+## 第三阶段
+
+预计：3 周
+
+完成：
+
+- OCR 支持
+- 本地模型
+- 自动识别题号
+- 自动填分
+- 自动切换下一题
+
+---
+
+# 16. 后续优化方向
+
+## AI能力
+
+- 本地部署 Qwen-VL
+- DeepSeek-R1 推理
+- 自定义 Prompt
+- AI 连续阅卷
+
+## 产品能力
+
+- 自动识别当前题号
+- 自动关联评分模板
+- 一键批量阅卷
+- 自动填写分数（RPA）
+- 教师评分统计
+- AI 与教师评分一致率分析
+- 导出阅卷报告
+
+## 企业级能力
+
+- 用户登录
+- 云端同步评分模板
+- 多教师共享评分标准
+- AI 模型统一配置
+- 学校私有化部署
+
+---
+
+# 17. MVP 核心功能
+
+✅ Electron 桌面应用
+
+✅ Vue3 + TypeScript 前端
+
+✅ 悬浮工具栏
+
+✅ 全局快捷键截图
+
+✅ AI 图片阅卷
+
+✅ 建议分数展示
+
+✅ 扣分原因分析
+
+✅ 教师人工确认
+
+该版本可作为最小可行产品（MVP），能够在不改造现有阅卷系统的前提下，为教师提供高效、可靠的 AI 辅助阅卷体验。
+````