AI-Grading-Assistant/teckdoc.md

````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 辅助阅卷体验。
````