8.3 KiB
会话页面与业务 Agent
更新日期：2026-09-27。本功能在原单机教师端内实现；原课程、导入、评分、复核和导出页面继续可用。
使用
打开系统默认进入空白“会话”草稿，点击“新建”立即切换到另一空白草稿，不弹窗、不写数据库。可在输入区直接提问，并在首次发送前反复选择或清除课程版本、评分批次和学生项目。发送首条非空消息时，会话和消息在同一事务保存；此后范围固定且在界面显示为只读。旧版留下的空会话仍可编辑范围。选择批次或项目会自动带入所属课程版本，清除课程版本会同时清除下级选择。范围固定后，工具不能读取范围之外的对象。会话列表、消息、引用、待确认操作和运行状态保存在数据库，刷新后可查看历史会话；刷新或再次进入页面仍打开新草稿。
可先问“列出课程版本”“扫描 batch 目录”“查看批次 3 的失败评分项”“查询项目 12 的报告实验数据”。课程目标与规则来自数据库；指定批次时使用批次创建时的快照。课程资料和报告通过 BGE-M3/pgvector 检索，回答附资料名、页码或幻灯片编号、原文片段和可打开的页面链接。没有证据时应明确说明。正式回答上方的“工具调用”先整体折叠，展开后每次调用仍独立折叠，可逐项查看参数和结果；回答末尾的“引用”也默认整体折叠。会话页不显示全局后台进度卡片，正在运行的会话仍在列表中标记。
扫描只读，可直接执行。导入、课程资料入库、创建批次、启动或重试、教师复核、导出和索引重试会生成确认卡片。卡片列出目标、范围、现值、新值及异常；教师点击“确认执行”才写入。模型工具白名单没有确认工具，聊天文字也不能代替按钮。导入候选有重复、识别异常或待确认文件时，卡片禁用确认；教师在卡片中修正身份、类别和文件选择，再“更新预览”。导入确认同时授权后台解析、必要 OCR 和项目索引。
教师复核必须在当前消息明确写出分数，例如“给 8 分”。Agent 可草拟评语，确认卡片展示批次、学生、评分项、模型原分、教师原分、证据、异常、新分和修改原因。失败或无法评分的项也可人工复核；原始模型分、证据和教师修改历史保留。
数据与任务
迁移 0003 添加会话、消息、运行、待确认操作、索引任务和批次固定项目清单；0004 添加首次请求幂等键与有界工具进度记录。新批次在创建时保存项目 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 容器。get_scores 每次最多返回一个项目的六项评分，响应给出 next_criterion_offset 和 next_project_offset 供继续查询；长结果保留结构化评分数据，不再变成无内容的截断提示。检索工具的运行记录保留每次调用找到的有界原文片段；回答引用对各次调用的证据去重后保存，不再只取前 20 条。工具没有任意 SQL、任意文件路径、HTTP 请求、代码执行或确认能力。检索片段只作为数据，不作为工具指令。模型只收到当前问题所需的规则摘要、检索片段或紧凑统计；API Key 不写入日志或会话表。
API 与故障恢复
草稿仅存在于浏览器；POST /api/conversations/first-message 以 UUID 请求键原子创建会话、首条教师消息及运行，重复请求返回同一 ID。POST /api/conversations 保留给旧客户端。GET /api/conversations 返回列表和各会话运行标识；GET /api/conversations/{id} 恢复消息、卡片、工具记录和运行状态；PUT /api/conversations/{id}/scope 仅允许首条教师消息前编辑范围；DELETE /api/conversations/{id} 删除非运行中的会话。删除会话会清理消息、运行与待确认卡片，不回滚已经确认的业务操作，相关业务审计仍保留。POST /api/conversations/{id}/messages/start 在提交消息后启动独立后台运行；GET /api/conversations/{id}/runs/{run_id}/events 可按运行 ID 订阅持久 SSE 事件。旧版 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 秒读取超时。
回答生成由后台线程执行，页面切换或 SSE 断开不会停止运行；前端按运行 ID 订阅 SSE，并轮询列表和当前会话详情恢复进度，可同时运行多个不同会话。同一会话仍拒绝并发发送。刷新后默认打开新草稿，点击历史会话即可查看正在运行的工具状态或最终结果。运行中的会话删除返回冲突，应待完成后重试。服务进程异常留下的 running 记录超过 15 分钟，在读取会话时标为中断。模型失败时，已提交的教师消息仍保留，可在同一会话继续提问。工具参数仅保存必要标识，文本和敏感字段以占位符代替；检索工具记录有界原文片段，评分工具记录有界评分行，其他工具记录结构摘要。回答按安全 Markdown 渲染，HTML 不执行，链接仅允许 HTTP(S)；工具过程在回答上方，引用在回答最后，二者默认折叠。待确认卡片始终独立显示。若嵌入模型或 OCR 缺失，任务保留具体失败原因；补齐离线模型后重试。若课程资料缺失、原件哈希变化、课程或批次状态变化，应重新预览。