docs: describe chat operations and validation boundaries
This commit is contained in:
+10
-1
@@ -1,10 +1,11 @@
|
||||
# WiseGrade（智评）交接说明
|
||||
|
||||
更新日期：2026-09-25。先阅读 [技术规格](docs/WISEGRADE_TECHNICAL_SPEC.md) 和 [部署与使用指南](docs/DEPLOYMENT.md)；本文件记录当前实现、验证边界和接手后的优先事项。
|
||||
更新日期：2026-09-26。先阅读 [技术规格](docs/WISEGRADE_TECHNICAL_SPEC.md)、[对话页面与业务 Agent](docs/CHAT_AGENT.md) 和 [部署与使用指南](docs/DEPLOYMENT.md)；本文件记录当前实现、验证边界和接手后的优先事项。
|
||||
|
||||
## 当前状态
|
||||
|
||||
- 已实现《自动化专业综合实践》的教师端闭环：课程与规则版本、挂载目录扫描和导入、文档解析、课程及项目知识库、独立评分批次、逐项复核、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。
|
||||
@@ -22,7 +23,10 @@
|
||||
| `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/`。原件不经过浏览器上传。
|
||||
@@ -54,6 +58,11 @@ uv run pytest -q
|
||||
- 部署镜像内完整后端测试：**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` 和只读源码挂载。
|
||||
- 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 项证据不匹配）。
|
||||
|
||||
@@ -2,9 +2,10 @@
|
||||
|
||||
WiseGrade 是面向《自动化专业综合实践》课程的教师端自动评分系统。
|
||||
|
||||
教师端系统包含课程版本、挂载目录导入、文档解析、知识库检索、独立评分批次、教师复核及导出。完整技术规格见：
|
||||
教师端系统包含持久对话与业务 Agent、课程版本、挂载目录导入、自动文档解析与索引、知识库检索、独立评分批次、教师复核及导出。完整技术规格见：
|
||||
|
||||
- [技术方案与开发规格](docs/WISEGRADE_TECHNICAL_SPEC.md)
|
||||
- [对话页面与业务 Agent](docs/CHAT_AGENT.md)
|
||||
- [Codex Goal 模式开发提示词](docs/CODEX_GOAL_PROMPT.md)
|
||||
|
||||
## 当前约束
|
||||
@@ -27,4 +28,4 @@ WiseGrade 是面向《自动化专业综合实践》课程的教师端自动评
|
||||
2. 将离线嵌入模型放在 `models/bge-m3/`（或修改 `EMBEDDING_MODEL_PATH`）。
|
||||
3. 运行 `docker compose up --build -d`，访问 <http://127.0.0.1:8080>。
|
||||
|
||||
学生材料只从只读挂载的 `/data/inbox` 读取。没有本地嵌入模型或 API 密钥时，系统仍可启动和完成导入；评分会显示明确错误。详细部署和使用步骤见 [部署与使用指南](docs/DEPLOYMENT.md)。
|
||||
打开系统默认进入“对话”；查询可直接执行，导入、入库、建批、启动、复核和导出先展示确认卡片，由教师点击后执行。学生材料只从只读挂载的 `/data/inbox` 读取。没有本地嵌入模型或 API 密钥时，系统仍可启动和完成导入；索引、对话或评分会显示明确错误。详细部署和使用步骤见 [部署与使用指南](docs/DEPLOYMENT.md)。
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# 对话页面与业务 Agent
|
||||
|
||||
更新日期：2026-09-26。本功能在原单机教师端内实现；原课程、导入、评分、复核和导出页面继续可用。
|
||||
|
||||
## 使用
|
||||
|
||||
打开系统默认进入“对话”。点击“新建”可限定课程版本、评分批次和学生项目；范围一旦建立，对话工具不能读取范围之外的对象。会话列表、消息、引用、待确认操作和运行状态保存在数据库，刷新后恢复。输入自然语言后，页面按 SSE 显示工具进度和回答。
|
||||
|
||||
可先问“列出课程版本”“扫描 batch 目录”“查看批次 3 的失败评分项”“查询项目 12 的报告实验数据”。课程目标与规则来自数据库；指定批次时使用批次创建时的快照。课程资料和报告通过 BGE-M3/pgvector 检索，回答附资料名、页码或幻灯片编号、原文片段和可打开的页面链接。没有证据时应明确说明。
|
||||
|
||||
扫描只读，可直接执行。导入、课程资料入库、创建批次、启动或重试、教师复核、导出和索引重试会生成确认卡片。卡片列出目标、范围、现值、新值及异常；教师点击“确认执行”才写入。模型工具白名单没有确认工具，聊天文字也不能代替按钮。导入候选有重复、识别异常或待确认文件时，卡片禁用确认；教师在卡片中修正身份、类别和文件选择，再“更新预览”。导入确认同时授权后台解析、必要 OCR 和项目索引。
|
||||
|
||||
教师复核必须在当前消息明确写出分数，例如“给 8 分”。Agent 可草拟评语，确认卡片展示批次、学生、评分项、模型原分、教师原分、证据、异常、新分和修改原因。失败或无法评分的项也可人工复核；原始模型分、证据和教师修改历史保留。
|
||||
|
||||
## 数据与任务
|
||||
|
||||
迁移 `0003` 添加会话、消息、运行、待确认操作、索引任务和批次固定项目清单。新批次在创建时保存项目 ID 列表；评分、结果查询和导出都使用该列表。旧批次该字段为 `NULL`，界面显示“历史项目清单未知”，只能按课程版本当前项目兼容读取，不能声称还原了创建时的范围。批次状态为 `created`、`queued`、`running`、`partial`、`failed`、`completed`；重复启动已入队或运行中的批次返回冲突。重试保留已评分项和教师复核。
|
||||
|
||||
导入后的每个待解析文件对应持久 `IndexTask`。worker 复用评分的解析和 RAG 入库代码；同一文件用共享处理目录中的文件锁串行化，避免自动索引与评分竞争写入。任务有 queued/running/completed/failed 状态、错误和重试入口。课程资料入库在对话中也作为索引任务执行。若 Redis 不可用，导入数据仍保存，索引任务标记失败并可重试。原始学生文件只从只读 `/data/inbox` 读取，文件 SHA-256 在预览和确认时复查。
|
||||
|
||||
待确认操作保存不可变参数、20 分钟有效期、幂等键和预期数据状态。确认时再次比对课程发布状态、规则与项目范围、批次状态、成绩与文件哈希。状态变化返回“重新预览”；重复确认已完成操作返回原结果。执行与会话 ID 写入审计日志。服务异常的操作标记失败，需重新准备；若进程在执行中崩溃，卡片保留 `executing` 状态，管理员应先核查实际业务记录再处理，不应直接重复写入。
|
||||
|
||||
批次汇总从数据库和现有权重规则计算完成数、未完成数、状态数量、分布、模型原始分均值和教师最终分均值。只有完整项目参与成绩均值及分布；失败、无法评分和待处理项不补零。详情仍可按学生、批次和评分项状态筛选。
|
||||
|
||||
## 模型与安全边界
|
||||
|
||||
对话使用模型设置页的 OpenAI 兼容 `/chat/completions` 地址、模型和后端 API Key。适配层按 [DeepSeek 原生工具调用文档](https://api-docs.deepseek.com/guides/tool_calls) 发送 `tools`，在每轮前用不含学生资料的 `wisegrade_ping` 最小探针验证端点会返回 `tool_calls`。当前 `deepseek-flash` 端点支持自动工具选择，但拒绝强制 `tool_choice="required"`，因此探针采用 `auto` 并检查返回结构。模型不支持时会显示明确配置错误，不会伪装工具已执行。既有评分 `json_call` 保持原有 JSON 行为。
|
||||
|
||||
工具输入由 Pydantic 校验，后端再校验课程、批次和项目关系。每轮最多 8 次工具调用、4 轮模型调用；工具输出和会话上下文限量。工具没有任意 SQL、任意文件路径、HTTP 请求、代码执行或确认能力。检索片段只作为数据，不作为工具指令。模型只收到当前问题所需的规则摘要、检索片段或紧凑统计；API Key 不写入日志或会话表。
|
||||
|
||||
## API 与故障恢复
|
||||
|
||||
`POST /api/conversations` 新建；`GET /api/conversations` 列表；`GET /api/conversations/{id}` 恢复消息、卡片和运行状态；`POST /api/conversations/{id}/messages` 返回 SSE 的 `run`、`tool`、`message`、`error`、`done` 事件。确认、取消和导入编辑分别为 `POST /api/conversations/{id}/actions/{action_id}/confirm|cancel|edit-import`。索引任务可通过 `GET /api/index-tasks`、`GET /api/index-tasks/{id}` 查询，失败任务可重试。Nginx 对消息流关闭代理缓冲并设置 900 秒读取超时。
|
||||
|
||||
连接中断后刷新会恢复已经写入的用户消息、已完成回答和卡片。运行中的生成器退出会标为 `interrupted`；服务进程异常留下的 `running` 记录超过 15 分钟，在读取会话时标为中断。失败或中断的消息可在同一会话继续提问。若嵌入模型或 OCR 缺失，任务保留具体失败原因；补齐离线模型后重试。若课程资料缺失、原件哈希变化、课程或批次状态变化，应重新预览。
|
||||
+9
-2
@@ -6,7 +6,7 @@ WiseGrade 是单机单管理员教师端。Web 服务仅绑定 `127.0.0.1`，默
|
||||
|
||||
- Docker Engine + Compose v2（Linux），或 Windows Docker Desktop（WSL2 后端，运行 Linux 容器）。
|
||||
- 一个存放学生材料的宿主机目录；其下每个批次目录包含 `学号_姓名_选题题目` 子目录。
|
||||
- `deepseek-flash` 可访问的 OpenAI 兼容 API 地址和密钥；该端点必须支持文本与图片输入。
|
||||
- `deepseek-flash` 可访问的 OpenAI 兼容 API 地址和密钥；该端点必须支持文本、图片输入及原生 `tool_calls`。若只做评分而不使用对话，仍可沿用已有 JSON 调用。
|
||||
- 离线嵌入模型包。默认使用 BAAI/bge-m3。内存不足时可改用 BAAI/bge-small-zh-v1.5。
|
||||
|
||||
仓库的 `docs/` 是课程资料，不是学生原件。旧版 `.doc` 只用于课程模板，经 LibreOffice 转换；学生输入只接受 PDF、DOCX、PPTX。
|
||||
@@ -79,9 +79,12 @@ tar -xf models/ocr/PP-OCRv5_mobile_rec_infer.tar --strip-components=1 -C models/
|
||||
|
||||
## 教师操作
|
||||
|
||||
打开系统默认进入“对话”。可新建并限定课程版本、批次和学生项目，使用自然语言查询规则、报告和进度。扫描目录可直接执行；导入、课程资料入库、建批、启动／重试、复核和导出须核对确认卡片并点击“确认执行”。有重复或识别异常的文件需先在卡片中修正选择。刷新后会话、引用和卡片保留。后台索引任务和评分进度可在对话页查看。详细规则见 [对话页面与业务 Agent](CHAT_AGENT.md)。
|
||||
|
||||
1. 在“课程与规则”中查看初始课程版本和评分规则。已发布版本不能直接覆盖；复制草稿、编辑、保存并发布新版本。课程目标、指标点、选题方向、模板和三个 Prompt 都属于课程版本。
|
||||
2. 在“知识库资料”中选课程版本并入库课程资料。入库使用本地嵌入模型和 PostgreSQL `pgvector`。
|
||||
3. 在“目录扫描与导入”中浏览 `/data/inbox` 下的相对目录，选择学生总目录并扫描。修正学号、姓名、选题和材料类型；PPT 导出的 PDF 必须确认成“汇报PPT/PDF”。每类材料只选择一个文件。
|
||||
确认导入后，材料自动进入后台解析、必要 OCR 和索引任务；评分前即可检索已完成索引的报告。失败任务可从索引任务列表重试。
|
||||
4. 在“评分批次”中选择已发布课程和规则版本，创建并启动批次。每次评分建立独立批次；重试不会覆盖其他批次。
|
||||
5. 在“评分与复核”中查看逐项模型原始分、原文证据、页码、页面图像和异常。教师可逐项填写分数、评语和修改说明；修改历史单独保留。
|
||||
6. 在“导出任务”中按批次导出 Excel，按学生导出 PDF 反馈。缺失或无法评分的项目显示待处理，不自动补零。
|
||||
@@ -105,7 +108,9 @@ uv run uvicorn wisegrade.main:app --reload
|
||||
docker compose --profile test run --build --rm test
|
||||
```
|
||||
|
||||
测试使用独立的 PostgreSQL 16 + pgvector 容器，不连接业务数据库。每个数据库测试创建临时数据库，执行 Alembic 迁移后运行，结束时删除；`test-db` 的数据目录为 tmpfs，不会写入业务数据卷。测试会从 `.env` 读取真实 DeepSeek API Key，并加载 `models/bge-m3` 和 `models/ocr` 中的离线模型；完整流程测试会发起真实模型请求。在宿主机直接运行 `uv run pytest` 时，需先设置指向专用 `wisegrade_tests` 数据库的 `TEST_DATABASE_URL`（使用 `postgresql+psycopg` 驱动，账号需有创建数据库的权限），并提供可用的模型配置。
|
||||
先验证无需真实 API Key 的测试可运行：`docker compose --profile test run --build --rm test pytest -q -m 'not integration'`。宿主机运行同一测试时，须把 `TEST_DATABASE_URL` 指向独立 PostgreSQL 测试库，并将 `EMBEDDING_MODEL_PATH` 指向本机离线模型目录。完整集成测试会访问真实模型，应单独执行和记录。
|
||||
|
||||
测试使用独立的 PostgreSQL 16 + pgvector 容器和 `test-redis`，不连接业务数据库或业务任务队列。每个数据库测试创建临时数据库，执行 Alembic 迁移后运行，结束时删除；`test-db` 的数据目录为 tmpfs，不会写入业务数据卷。测试会从 `.env` 读取真实 DeepSeek API Key，并加载 `models/bge-m3` 和 `models/ocr` 中的离线模型；完整流程测试会发起真实模型请求。在宿主机直接运行 `uv run pytest` 时，需先设置指向专用 `wisegrade_tests` 数据库的 `TEST_DATABASE_URL`（使用 `postgresql+psycopg` 驱动，账号需有创建数据库的权限），并提供可用的模型配置。
|
||||
|
||||
本地开发需提供 PostgreSQL、Redis 和与容器路径一致的挂载目录；可用 Compose 启动 `db` 和 `redis`。Vite 前端：
|
||||
|
||||
@@ -121,5 +126,7 @@ npm run dev
|
||||
|
||||
- `docker compose logs api worker` 查看迁移、解析和任务异常。日志不输出 API Key。
|
||||
- 模型请求失败后按配置有限重试，评分项显示失败原因；可修复配置后重试该批次。
|
||||
- 对话若提示端点或模型不支持 `tool_calls`，在“模型设置”中选择支持工具调用的 OpenAI 兼容端点和模型。探针不发送课程或学生资料；普通模型对话仍有调用次数和超时限制。
|
||||
- 导入后索引任务若显示失败，查看 `/api/index-tasks/{id}` 的错误并修复 Redis、离线 BGE-M3 或 OCR，再重试。批次若已入队或运行，重复点击启动会返回冲突。
|
||||
- 原件哈希变化后必须重新扫描并确认导入，否则解析会报“源文件已变化”。
|
||||
- 源文件和模型目录为只读挂载；解析产物在 `data/processed/`，导出在 `data/exports/`，均被 Git 忽略。
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# WiseGrade（智评）技术方案与开发规格
|
||||
|
||||
> 2026-09-26 增量实现：默认“对话”页面、应用内固定工具 Agent、持久会话、待确认操作、自动索引任务和批次固定项目清单。具体状态机、API 与恢复流程见 [对话页面与业务 Agent](CHAT_AGENT.md)。旧版正文的阶段计划按原始系统设计编写，新增业务边界以该增量文档及当前代码为准。
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
### 1.1 基本信息
|
||||
@@ -927,4 +929,3 @@ docs: add deployment and usage guides
|
||||
- 每个批次都可以导出 Excel 和逐生 PDF
|
||||
- 示例材料可以完成端到端测试
|
||||
- Git 历史包含清晰的阶段提交
|
||||
|
||||
|
||||
Reference in New Issue
Block a user