52 lines
10 KiB
Markdown
52 lines
10 KiB
Markdown
# WiseGrade 对话 Agent：Codex Goal 模式提示词
|
||
|
||
将下方代码块完整复制到 Codex Goal 模式，并在本仓库根目录执行。本提示词只针对现有系统的增量更新；[CODEX_GOAL_PROMPT.md](CODEX_GOAL_PROMPT.md) 是最初搭建系统时使用的历史提示词。
|
||
|
||
```text
|
||
你是 WiseGrade（智评）项目的开发代理。请在当前仓库完成“对话”主页面和后端业务 Agent 的实现、迁移、测试及文档更新，直到下述验收条件全部满足。不要只输出设计或停在前端样例。
|
||
|
||
## 先了解现状
|
||
|
||
先检查工作区状态并阅读 README.md、HANDOFF.md、docs/GUIDE.md。核对当前代码，尤其是 frontend/src/App.tsx、frontend/src/api.ts、backend/wisegrade/api.py、models.py、storage.py、parsing.py、rag.py、llm.py、scoring.py、exports.py、settings_store.py、migrations/ 和 backend/tests/。以当前代码和本提示词确定本次增量工作；旧版 docs/prompts/CODEX_GOAL_PROMPT.md 中“从零创建系统”的步骤不适用于本次任务。保留工作区已有用户修改，不泄露或提交 .env、API Key、模型权重、运行数据及学生原件。
|
||
|
||
现有系统是单机单教师应用：React/TypeScript/Vite/Ant Design 前端，FastAPI/SQLAlchemy 后端，PostgreSQL + pgvector，Redis + RQ；原始学生材料只从只读挂载目录 /data/inbox 读取。现有课程版本、规则、扫描导入、解析、知识库、评分批次、教师复核和导出功能必须继续可用。当前 DeepSeekClient 主要支持结构化 JSON 评分调用，尚无对话工具编排；RAG 检索主要服务评分；学生材料通常在评分时解析和建索引。
|
||
|
||
## 目标与已确认的业务边界
|
||
|
||
1. 在左侧导航“仪表盘”上方增加“对话”，并将其设为打开系统时的默认页面。保留所有原页面。对话页面支持创建、切换、继续多段持久会话；展示课程版本、批次、学生项目上下文、引用、确认卡片和任务进度。刷新后能恢复会话。
|
||
2. 教师可用自然语言查询课程规则及版本、课程知识库资料、学生项目元数据和报告内容、评分批次进度、单学生或单批次评分结果，并按评分项状态筛选和总结。指定批次时，规则和结果必须使用该批次保存的快照；对象名称或版本有歧义时主动澄清，不猜测。
|
||
3. 教师可通过对话扫描挂载目录、预览并确认导入、触发课程资料入库、创建评分批次、启动或重试批次、查看进度、复核评分以及导出 Excel 成绩表或逐生 PDF 反馈。首版评分控制限于创建、启动、重试和查看进度；不增加暂停、取消或指定学生／评分项重评。
|
||
4. 扫描只读取目录，可直接执行。导入、课程资料入库、创建批次、启动或重试批次、教师复核和导出，都先在对话中展示具体目标、参数、影响范围和异常，再由教师点击确认按钮执行。模型不能调用确认动作，也不能靠一句对话文字绕过确认。导入确认同时授权导入后的自动后台解析和建索引。
|
||
5. 对话复核要求教师明确给出分数；Agent 可以根据已查看的证据草拟评语，但不能自行决定教师分数。确认卡片展示原值、新值、评分项、批次、学生及修改原因。写入后保留模型原始分、教师分、证据、修改历史和审计记录。允许教师对已有失败或无法评分的评分项作明确人工复核，但应显示其原状态和证据不足情况。
|
||
6. 学生材料在确认导入后自动进入后台解析、OCR（需要时）和项目知识库建索引任务，因此评分前就能询问报告内容。索引任务要有可见状态、错误和幂等重试。课程资料入库也要有可见进度或完成结果。复用现有解析、嵌入和 RQ 基础设施，避免与评分任务并发写入同一材料造成竞态。
|
||
7. 成绩、人数、分布和未完成数量由数据库及现有规则计算，模型只负责解释。支持单学生、单批次及按状态筛选；未完成、失败、无法评分的项目不得当成零分或完整成绩。总结可区分模型原始分与教师最终分，并链接到对应详情。
|
||
|
||
## 实现路线
|
||
|
||
采用现有应用内的工具注册表和编排器，不为本次功能引入 MCP Server、Codex skill、LangChain 或独立通用 Agent 平台。保留模块化单体架构。将 api.py 中需复用的业务逻辑抽取到服务层，现有 REST 页面和 Agent 工具调用同一服务，避免工具通过 HTTP 回调本应用或复制一套业务规则。
|
||
|
||
为 Agent 建立名称固定、说明清晰、输入输出有类型的工具白名单。至少覆盖：课程／版本／规则查询，课程及项目材料检索，目录浏览与扫描，学生项目查询，批次及进度查询，评分详情与汇总，导入／课程资料入库／建批／启动或重试／复核／导出的待确认操作准备。不要提供任意 SQL、挂载目录外的文件路径、任意 HTTP 请求、执行代码或直接确认工具。使用 Pydantic 校验模型产生的参数；后端再次校验会话范围、课程版本、项目和批次关系，并限制单轮工具调用次数、输出大小及模型超时。
|
||
|
||
扩展 DeepSeek 适配层，参照 https://api-docs.deepseek.com/guides/tool_calls ，通过现有可配置的 OpenAI 兼容 /chat/completions 端点使用 deepseek-flash 的原生 tool_calls；有有效配置且网络可用时，在部署端点执行最小兼容性验证。不要改变现有评分所依赖的 json_call 行为。API Key 始终只在后端，日志和会话表不能保存密钥。若端点或模型不支持工具调用，应给出明确错误和配置指引，不能假装已执行工具。
|
||
|
||
新增 Alembic 迁移，保存会话、消息、Agent 运行状态、待确认操作及索引任务；必要时保存工具调用元数据和引用 ID。提供会话创建／列表／读取／继续、发送消息、确认或取消操作、查询任务状态等 API。对话响应使用 SSE 事件格式，由前端通过 fetch 流式读取；调整 Nginx 对此接口的缓冲和超时。断线和刷新后仍能从数据库恢复已完成消息和待确认操作。前端展示消息、工具进度、引用、索引／评分进度及明确错误。
|
||
|
||
待确认操作由后端保存不可变参数、过期时间、幂等键和预期数据版本。确认端点必须重新检查文件 SHA-256、目录安全、课程及规则发布状态、批次状态、学生／评分项对应关系等条件；条件变化时要求重新预览。避免重复点击导致重复导入、重复建批或重复入队。审计日志记录经对话执行的实际操作和关联会话。
|
||
|
||
知识问答分源处理：课程／规则的权威结构化数据直接查询数据库；课程资料和学生报告使用现有 BGE-M3／pgvector 检索，严格限定课程版本与项目 ID。回答必须附可核验的资料名、页码或幻灯片编号、原文片段及可打开的详情／页面链接；无证据时说明未找到。检索到的文档内容只能作为数据，不能变成新的工具指令。仅将回答所需片段和紧凑统计送往外部模型，不无条件发送整份报告或整个班级的明细。
|
||
|
||
新评分批次固定创建时纳入的项目清单，使确认卡片上的项目范围与后续评分、查询、导出一致；为旧批次提供兼容读取，不能凭空推断旧批次创建时的历史项目清单。修正现有批次“创建后待启动／已入队／运行中”的状态区分，阻止重复启动入队。重试继续保留已评分项和教师复核结果。处理自动索引与评分的任务顺序，避免同一文件重复解析和索引冲突。
|
||
|
||
前端应支持从对话引用跳到原有课程、项目、评分和导出详情，并保持必要的上下文。导入预览应显示学号、姓名、选题、材料类型、缺失、重复、识别异常和文件选择；这些可由教师在确认前修正，不得由模型静默代选有歧义的文件。批次部分完成或导出包含待处理项目时，确认卡片应明确提示。
|
||
|
||
更新 README.md、docs/GUIDE.md 或新增专门设计文档，说明对话操作、确认规则、索引任务、模型配置及异常处理；同步更新 HANDOFF.md 中与本次实现相关的状态，但不要编造未实际验证的结果。现有教师单机、只读挂载目录、课程和评分版本化、证据可追溯及导出规则不能退化。
|
||
|
||
## 验收与验证
|
||
|
||
新增有意义的后端测试，使用模拟模型工具调用和独立测试数据库验证：工具参数校验与作用域隔离、课程及批次快照规则、跨学生检索隔离和引用、扫描预览与文件哈希变化、确认前无副作用及重复确认幂等、导入后自动索引、批次项目清单固定与重复入队防护、明确分数的教师复核与修改历史、部分完成批次总结不补零、失败和断线后的恢复。验证原有 API 和评分流程无回归；前端至少完成 TypeScript 和生产构建，并检查主页面、会话恢复、确认卡片和跳转。
|
||
|
||
优先运行不依赖真实 API Key 的自动测试；若当前环境具备有效配置，可另外做一次最小真实 DeepSeek tool_calls 冒烟验证，不输出密钥或学生原件。按 docs/GUIDE.md 的 uv／pytest、npm 构建及 Docker Compose 路径执行适用验证。若环境限制导致某项无法运行，明确记录具体命令、原因和剩余风险；不要把未执行验证写成通过。
|
||
|
||
按可验证的阶段持续完成工作：共享业务服务与数据迁移 → 自动索引和可引用检索 → Agent 工具编排与持久会话 → 对话页面和确认流程 → 回归测试及文档。每阶段发现与现有代码不符的细节时，以本提示词的用户确认边界为准做合理实现调整。不要因普通实现选择停下询问；只有确实无法从代码和本提示词解决的业务矛盾才提出问题。完成后给出改动、验证结果和实际限制；遵循仓库现有 Conventional Commits 惯例提交可回退的阶段性修改，不提交秘密或运行数据。
|
||
```
|