AI 作文批改助手 ✨

上传手写英文作文 → 自动识别文本 → 按高考标准打分 → 输出详尽反馈报告，全流程在本地浏览器完成。

全面重构亮点

• 现代化 Web UI：基于 Flask 构建的单页应用，所有功能集中在浏览器端完成，配置与状态实时同步。
• 任务可追溯：每次批改都会创建独立 run id，原图、Markdown、HTML 报告集中存放，便于回看和分享。
• 并发调度升级：多线程线程池 + 独立任务状态机，批量图片互不阻塞，失败文件单独记录。
• Prompt / 评分可插拔：默认内置高考英语评分模板，可在 UI 动态替换；书写敏感度、模型温度均可调整。
• 安全与透明：API Key 以设备指纹派生的密钥加密存储，支持一键清除；Token 用量实时累积并在 UI 展示。
• 自动更新提示：后台检查 GitHub Releases 获取最新版本信息，可一键触发或关闭。

工作原理概览

1. 图片接入：兼容摄像头拍照、扫描件或批量上传，自动清洗文件名防止覆盖。
2. VLM 解析：将图片转为 base64，通过兼容 OpenAI 的视觉模型 OCR + 计算书写分。
3. LLM 批改：根据作文题目、识别文本、书写分构建 Prompt，生成结构化中文反馈。
4. 报告生成：按配置保存 Markdown，并可渲染为带主题的 HTML 文件输出。
5. 状态同步：Web UI 实时播报进度、日志、Token 消耗。

快速开始

环境准备

• Python 3.9 及以上
• macOS / Windows / Linux 均可
• 任意兼容 OpenAI API 协议的 VLM/LLM 服务（OpenAI、Azure OpenAI、通义、DeepSeek 等）

安装依赖

git clone https://github.com/Eric-Terminal/Pro_llm_correct.git
cd Pro_llm_correct
python3 -m venv venv
source venv/bin/activate        # Windows 使用 venv\Scripts\activate
pip install -r requirements.txt

启动 Web 版

python3 main.py

• 应用将尝试从 4567–4667 中选择空闲端口，并自动打开默认浏览器。
• 首次运行会生成 config.json、output_reports/ 等目录。

使用流程

1. 在「批改作文」页填入题目或场景说明。
2. 上传一张或多张作文图片并提交。
3. 查看实时处理状态：成功会显示 Markdown / HTML 下载链接，失败会给出详细错误。
4. 结果保存在 output_reports/<run_id>/ 中，run id 由时间戳生成，保证唯一。

output_reports/
└── <run_id>/               # 例如 20240101-120000
    ├── essay-1.png         # 原始上传文件
    ├── essay-1_report.md   # Markdown 报告（若启用 SaveMarkdown）
    └── essay-1_report.html # HTML 报告（若启用 RenderMarkdown）

• OutputDirectory 可改为绝对路径以迁移到 NAS / 外部硬盘。
• 若只启用 HTML，程序会在渲染完成后自动删除对应 Markdown 文件。

关键配置参考

分类	键名	说明
服务连接	VlmUrl / VlmModel / VlmApiKey LlmUrl / LlmModel / LlmApiKey	与 OpenAI SDK 参数保持一致；密钥输入后即被本地加密，输入框留空表示沿用已有值。
性能与容错	MaxWorkers / MaxRetries / RetryDelay / RequestTimeout	控制并发线程数、失败重试次数与间隔、单次请求超时（秒）。
评分策略	SensitivityFactor	对 VLM 输出的书写分进行幂次强化/弱化（默认 1.0）。
	VlmTemperature / LlmTemperature	约束模型随机性，范围 0–2。
Prompt 定制	LlmPromptTemplate	使用 Python str.format 语法，支持 {topic}、{wscore}、{essay_text} 占位符，留空回退到内置模板。
输出控制	OutputDirectory / SaveMarkdown / RenderMarkdown	自定义输出目录及报告格式，布尔选项可在 UI 勾选。
版本与统计	AutoUpdateCheck / UsageVlmInput 等	自动更新开关及历史 Token 统计，展示于 UI「关于」面板。

配置文件位于仓库根目录 config.json，敏感字段均以设备指纹派生密钥加密存储，迁移到新设备后需重新输入 API Key。

Web API（用于自动化集成）

• GET /api/config：读取当前配置、版本信息、Token 统计。
• POST /api/config：提交 JSON 更新配置；支持 ClearVlmApiKey / ClearLlmApiKey 清除敏感字段。
• POST /api/process：multipart/form-data，包含 topic 与 files[]，返回 run id。
• GET /api/run-status/<run_id>：轮询任务状态、日志、Token 用量以及生成的文件路径。
• GET /outputs/<path>：访问生成的原图或批改报告。

日志与故障排查

• 控制台会输出端口探测、API 请求摘要和异常信息。
• Web UI：结果卡片实时显示每个文件的日志及错误信息。
• 常见问题排查：
  • 配置缺失：缺少必填项时，后端会在任务开始前返回具体提示。
  • 网络或权限错误：请确认模型名称、Key 是否正确，服务是否支持图像输入，并适当调整 RequestTimeout / RetryDelay。

开发者指南

• 核心依赖：Flask（Web 服务）、cryptography（配置加密）、openai SDK（兼容多家服务）、markdown（报告渲染）。
• 调试技巧：

  python3 web_app.py   # 直接运行 Flask 应用
  python3 main.py      # 启动正式入口，包含日志与端口选择

• 如需打包为单文件可执行程序：

  pyinstaller --noconsole --onefile main.py

  生成的可执行文件位于 dist/。

贡献与许可

• 欢迎通过 Issue / Pull Request 分享想法与改进。
• 如果这个项目对你有帮助，别忘了点个 ⭐️。
• 本项目遵循 MIT License。