WiseGrade（智评）交接说明

更新日期：2026-09-26。先阅读技术规格、对话页面与业务 Agent 和部署与使用指南；本文件记录当前实现、验证边界和接手后的优先事项。

当前状态

已实现《自动化专业综合实践》的教师端闭环：课程与规则版本、挂载目录扫描和导入、文档解析、课程及项目知识库、独立评分批次、逐项复核、Excel 成绩表和逐生 PDF 反馈。
当前源码新增默认“对话”页面、持久多轮会话、固定类型工具白名单、DeepSeek 原生工具调用、教师确认卡片、导入后自动索引任务和批次固定项目清单。旧页面继续可用。模型不能确认操作；会话、运行和待确认操作由迁移 0003 持久化。
前端为 React/TypeScript/Vite/Ant Design；后端为 FastAPI/SQLAlchemy；PostgreSQL + pgvector 存储数据，Redis + RQ 执行评分任务，Nginx 提供前端并代理 /api。
本机 Compose 预览使用 127.0.0.1:18080，因为 8080 已被占用；仓库默认端口仍为 8080。本机 .env 已生成随机加密密钥并填入 DeepSeek API Key，但不在 Git 中。
已执行数据库迁移 0002，初始课程及其版本已写入 PostgreSQL。本机已从 docs/ 示例报告导入 1 个验收项目；汇报 PPTX 由示例报告内容生成，并非学生原始 PPT。
docs/阶段报告3.pdf 已纳入示例材料和端到端测试。
本机已下载 BGE-M3 到 models/bge-m3/，固定 Hugging Face 修订版 5617a9f61b028005a4858fdac845db406aefb181；模型目录不提交到 Git。
本机已下载 PP-OCRv5 mobile 检测与中文识别模型到 models/ocr/；下载与解压命令见部署指南。

代码入口与数据流

位置	作用
`compose.yaml`、`.env.example`	五个容器及环境变量；原件目录以只读方式挂载到 `/data/inbox`
`backend/wisegrade/main.py`、`api.py`	FastAPI 启动、初始化课程、教师端 API
`backend/wisegrade/models.py`、`migrations/`、`seed.py`	数据模型、Alembic 迁移、初始课程和规则
`backend/wisegrade/storage.py`、`parsing.py`	相对路径安全检查、目录识别、文件哈希、PDF/DOCX/PPTX 解析与页面资产
`backend/wisegrade/rag.py`、`llm.py`、`scoring.py`	本地嵌入与混合检索、DeepSeek 适配、批次评分
`backend/wisegrade/settings_store.py`、`exports.py`	API Key 加密保存、Excel/PDF 导出
`backend/wisegrade/services.py`、`indexing.py`	REST 与 Agent 共用导入、入库、建批、复核服务；持久后台索引任务
`backend/wisegrade/agent_tools.py`、`actions.py`、`chat_api.py`	类型化工具注册、确认边界、会话与 SSE 编排
`frontend/src/App.tsx`、`frontend/src/api.ts`	教师端页面及 API 调用
`frontend/src/Chat.tsx`	会话恢复、引用、进度和确认卡片
`backend/tests/`	路径、规则、版本、解析、模型输出、复核、导出及示例材料流程测试

教师选择 /data/inbox 下的相对目录后，后端扫描 学号_姓名_选题题目 子目录；教师确认材料类型后保存路径、大小、时间和 SHA-256。解析结果与页面图像进入 data/processed/，知识片段进入 PostgreSQL。评分时复制课程、规则和模型配置快照到独立批次，由 RQ worker 处理。模型原始评分、证据和教师修改记录分别保留；导出文件写入 data/exports/。原件不经过浏览器上传。

启动与检查

首次部署复制 .env.example 为 .env，设置学生目录 WISEGRADE_DATA_DIR、随机 WISEGRADE_SECRET_KEY、DeepSeek 地址及密钥，并把离线 BGE-M3 模型放在 models/bge-m3/。扫描版 PDF 另需 models/ocr/detection/ 和 models/ocr/recognition/。模型目录和 .env 均不提交到 Git。详情及 Windows 路径写法见部署指南。

docker compose up --build -d
docker compose ps -a
curl http://127.0.0.1:18080/api/health

上面的 curl 使用本机当前端口；其他环境应改为 .env 中的 WISEGRADE_WEB_PORT（默认 8080）。本机预览地址为 http://127.0.0.1:18080。api 启动时自动运行 Alembic 迁移。排障先看 docker compose logs api worker web。

Python 开发统一使用 uv：

cd backend
uv sync --extra ocr --group dev
uv run pytest -q

前端构建：cd frontend && npm ci && npm run build。宿主机缺少 LibreOffice 时，DOCX/PPTX 渲染测试会跳过；生产容器镜像已包含 LibreOffice。

已验证与尚未验证

部署镜像内完整后端测试：19 通过、0 跳过，包括 DOCX/PPTX 转换与页面图像测试。宿主机运行结果为 18 通过、1 跳过，因为宿主机未安装 LibreOffice；部署容器内为 25.2.3.2。另已用课程 DOCX 和验收 PPTX 实际验证页数、文字及页面图片。
2026-09-25：后端测试已改用独立 PostgreSQL + pgvector，并通过真实 DeepSeek 和本地 BGE-M3 模型测试。19 个其他测试通过；使用课程示例材料的完整流程单独重跑通过，22 个评分项全部完成，教师复核和导出检查通过。测试命令见 docs/DEPLOYMENT.md。
前端生产构建通过；Compose 的 PostgreSQL、Redis、API、worker、Web 当前均已启动，首页、深链接、/api/health、课程及仪表盘 API 返回正常。数据库版本为 0002；全新 SQLite 数据库迁移至 0002 也已验证。
2026-09-26 当前源码：宿主机独立 PostgreSQL 测试执行 uv run pytest -q -m 'not integration'，24 通过、1 跳过、2 个真实集成测试未运行；使用既有测试镜像加只读源码挂载执行 Compose 同组测试，25 通过、2 个真实集成测试未运行。单独构造旧版 0002 表结构，在临时 PostgreSQL 数据库升级 0003 通过；新数据库迁移也由测试覆盖。前端 npm run build 和新 Nginx 配置 nginx -t 通过。
2026-09-26 最小真实 DeepSeek tool_calls 兼容性探针通过，完整工具白名单也返回 list_courses 原生调用；该端点拒绝 tool_choice="required"，适配层已使用 auto 并校验返回的工具调用。未在该探针发送学生原件。
完整 Compose 测试首次运行 25 通过、1 失败：真实模型证据匹配导致示例流程首轮批次 partial。测试改为按既有重试规则继续未完成项后，单独重跑示例流程 1 通过（11 分 48 秒）；成功项和教师复核结果由生产评分代码保留。此次未重新运行一次完整的所有测试组合，不应把第一次完整命令写成全部通过。
测试 Compose 现增设独立 test-redis，与业务队列隔离。隔离前完整测试曾把 5 个测试索引作业送入业务 Redis；旧业务 worker 因缺少新模块执行失败，未写入业务数据库，测试作业已从业务 Redis 失败队列和作业键清理。
当前运行中的 Compose 业务镜像仍是上一版代码，数据库仍为 0002；本次源码尚未重建并部署到业务容器。上述 Compose 测试使用独立 test-db、独立 test-redis 和只读源码挂载。
docker compose --profile test run --build --rm test pytest -q -m 'not integration' 曾启动镜像重建，但 Debian 软件源下载 LibreOffice 依赖在约 24 分钟后仍未完成，故中止；随后用已有测试镜像加最新源码只读挂载执行相同测试。尚未在浏览器中实际点击新对话主页、刷新恢复、确认卡片及深链接；目前这些路径由代码检查、后端 API 测试和前端 TypeScript／生产构建覆盖。重新部署业务容器及浏览器实机验收仍需完成。
RQ worker 曾在空闲期间因 Redis 连接超时退出，日志显示正常退出码 0；已在 compose.yaml 设置 restart: unless-stopped 并重新启动。接手后应观察是否反复超时。
使用 docs/ 的四份示例报告及生成的汇报 PPTX，经目录扫描、确认、课程资料入库、真实 BGE-M3/pgvector 检索和真实 DeepSeek API 完成批次 3：22/22 项成功。首轮有 1 项引文不匹配，重试后成功；保留了成功项。项目索引重建后有 316 段、平均 506 字，向量均为 1024 维；77 条评分证据均能匹配对应文档页的原文和页面图片。
对批次 3 完成教师复核和修改历史验证；Excel 成绩表及 11 页 PDF 反馈均可下载且可解析，文件位于 data/exports/。批次 2 保留为首次真实运行的对照记录（16 项成功、6 项证据不匹配）。
将 docs/阶段报告1.pdf 的一页栅格化为无文本层 PDF 后，离线 PaddleOCR 提取 496 字，识别到目录和章节标题。真实扫描仪产生的不同质量扫描件尚未实测。Windows Docker Desktop 尚未在 Windows 机器上实测。

接手后优先完成

使用独立提供、已脱敏的学生目录再次验收五类原始材料，尤其是学生原始 PPTX 和真实扫描仪 PDF；当前验收使用仓库示例报告与生成材料。
在目标 Windows Docker Desktop 环境验证目录挂载、模型路径和完整启动。
持续查看 worker 日志；若 Redis 空闲超时重复出现，再定位 Docker 后端休眠或网络原因。不要仅凭容器显示“已启动”判断评分任务可用。

当前代码位于 main 分支，阶段提交使用 Conventional Commits。交接前工作区应保持干净；.env、models/、data/、缓存和构建产物由 .gitignore 排除。

9.4 KiB Raw Blame History Unescape Escape