6.0 KiB
对话页面与业务 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 原生工具调用文档 发送 tools，在每轮前用不含学生资料的 wisegrade_ping 最小探针验证端点会返回 tool_calls。当前 deepseek-flash 端点支持自动工具选择，但拒绝强制 tool_choice="required"，因此探针采用 auto 并检查返回结构。模型不支持时会显示明确配置错误，不会伪装工具已执行。既有评分 json_call 保持原有 JSON 行为。
工具输入由 Pydantic 校验，后端再校验课程、批次和项目关系。每条教师消息默认最多调用工具 32 次，成功与失败的尝试均计数；模型最多请求 33 轮，以便用完工具次数后还能生成回答。可在 .env 中通过 CHAT_MAX_TOOL_CALLS 调整工具上限（1–64），修改后重新创建 API 容器。工具输出和会话上下文限量。工具没有任意 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 缺失，任务保留具体失败原因；补齐离线模型后重试。若课程资料缺失、原件哈希变化、课程或批次状态变化，应重新预览。