docs: consolidate project guide and organize prompts
This commit is contained in:
@@ -0,0 +1,51 @@
|
||||
# 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 惯例提交可回退的阶段性修改，不提交秘密或运行数据。
|
||||
```
|
||||
@@ -0,0 +1,75 @@
|
||||
# WiseGrade 目录、摘要与正文证据治理：Codex Goal 模式提示词
|
||||
|
||||
将下方提示词完整复制到 Codex Goal 模式，在本仓库执行。本提示词授权新任务修改仓库源码和隔离测试环境；不授权改写当前业务数据库、批次 3 或会话 6。
|
||||
|
||||
~~~text
|
||||
你是 WiseGrade（智评）项目的开发代理。请在 /home/sky/files/Agent/WiseGrade 完整实现“区分报告目录、摘要与正文的证据检索和评分”功能，完成迁移、测试、界面衔接及文档更新。持续推进到下列验收条件全部满足，不要只提交设计方案。
|
||||
|
||||
## 先了解现状
|
||||
|
||||
先检查工作区状态，阅读：
|
||||
- /home/sky/files/Agent/WiseGrade/README.md
|
||||
- /home/sky/files/Agent/WiseGrade/HANDOFF.md
|
||||
- /home/sky/files/Agent/WiseGrade/docs/GUIDE.md
|
||||
|
||||
重点检查 backend/wisegrade 下的 parsing.py、rag.py、models.py、scoring.py、llm.py、indexing.py、services.py、agent_tools.py、chat_api.py、exports.py、actions.py，以及 frontend/src/App.tsx、frontend/src/Chat.tsx、数据库迁移和相关测试。以当前代码为准，保留工作区已有修改。
|
||||
|
||||
当前问题已通过只读检查确认：批次 3 的 77 条评分引文中有 14 条来自目录页，涉及 9 个评分项；会话 6 保存的 20 条引用中有 5 条指向阶段报告 1 的目录页。目录既被当作正文证据，也挤占候选位置，使实际存在的正文难以检索到。上述数字是诊断基线，不是要求修改这些历史记录。
|
||||
|
||||
## 已确定的业务规则
|
||||
|
||||
1. 目录可以证明章节和报告结构，也可以帮助定位正文；不能证明章节的具体内容、完成质量、测试结果或分析。
|
||||
2. 摘要可以用于“摘要称……”这类明确归属的概述，不能单独证明方法已实现、实验已完成或指标已达标。
|
||||
3. 内容性评分必须使用正文中的实质段落、数据、表格或适用的附录。正文页上的单独章节标题也不能充当内容证据。
|
||||
4. 经过针对性正文补检后，若内容性评分目标仍只有目录或摘要命中，该评分项进入“待教师复核”：模型分为 null，总分保持待处理；不得自动给低分或断言“学生未写”。
|
||||
5. 教师已录入的复核分、评语和修改历史必须保留。不要自动改写批次 3 的既有分数或会话 6 的历史消息。
|
||||
|
||||
## 页面标注
|
||||
|
||||
以文档实际页码或 PPT 幻灯片编号为主要标注单位，至少区分 cover、abstract、toc、body、references、unknown。普通知识片段继承所在页面类型。允许 mixed 页面：当目录和正文确实共处一页时，仅对该页按文本块进一步区分，不把整页正文排除。
|
||||
|
||||
识别目录时结合页首标题、章节条目密度、点线与末尾页码，并识别跨页续目录；摘要、参考文献也要识别连续页面。不能只凭“目录”一词或固定页号判定。清理重复页眉页脚，保留判定依据和识别版本。对有疑义的页面标为 unknown，不强行认作正文。
|
||||
|
||||
设计统一的页面级持久化结构，让学生材料和公共课程资料都能查询页面类型；知识片段关联其来源页。另行提取真正的正文章节路径，不要直接把当前“页面第一行”字段当成章节。
|
||||
|
||||
## 证据政策与检索
|
||||
|
||||
把“必备证据的用途”纳入可版本化的评分规则，并随批次保存快照；对既有字符串形式的 required_evidence 做兼容处理。结构目标允许封面、目录或参考文献等对应页面；内容目标只允许正文及有实质内容的附录。不要只在 Prompt 中写规则，也不要仅按评分项 ID 临时硬编码。
|
||||
|
||||
每个必备证据目标分别检索。先限定课程版本、学生项目、材料类别和允许的页面类型，再取候选；页面过滤必须发生在候选数量限制之前。扩大初始候选池，让语义匹配和关键词匹配分别有召回机会，再合并去重。评估现有 PostgreSQL simple 全文检索对中文材料的表现，采用适合当前语料的关键词召回方式。融合排序时避免直接相加未经归一化的语义分与关键词分，可采用基于排名的融合，并用回归样本调整参数。
|
||||
|
||||
第一轮优先分散到不同页面；有可靠章节路径后，再对同一章节设置软上限。名额不足时可回填同页或同节的其他正文片段，但不能放宽证据类型。评分最终给模型的片段数量保持受控，Agent 搜索也保持受控。宽泛的跨报告问题适度覆盖不同文档；明确指定某一报告时不要强制跨文档。
|
||||
|
||||
若某个内容目标未找到正文，利用目录标题匹配实际正文标题，补检该章节及相邻正文页。目录只作导航，最终内容引文必须落在实际正文页。评分发送给模型的页面图像也应优先选择相关的不同正文页，而非目录页。
|
||||
|
||||
## 评分与 Agent 出口
|
||||
|
||||
扩展评分输出及校验，使每条引文关联它要支持的评分目标。除现有原文与页码校验外，还须校验证据来源类型是否获准；内容性判断不能仅由目录、摘要或单独标题支撑。LLM 负责理解证据、判断评分要求和提出补检目标；页面权限及状态转换由代码执行，LLM 不能绕过。
|
||||
|
||||
新增清晰的“待教师复核”评分状态，与材料缺失、解析失败和模型调用失败区分。补检仍不足时记录缺少的正文证据目标和检索范围，模型分保持 null。同步更新批次完成状态、仪表盘待处理数、API 与 Agent 状态筛选、评分详情、导出及教师复核流程。待复核项的教师评分输入框不能预填 0；教师复核后应能正常形成最终分，同时保留原始检索问题记录。
|
||||
|
||||
项目事实抽取也要遵循来源类型，避免从目录标题推断实现结果。
|
||||
|
||||
Agent 的内容搜索和结构／目录查询使用相同的证据政策；可调整现有工具参数或增加清晰区分的只读工具，但保持原有项目范围隔离。工具返回页面类型和稳定的引用标识。最终回答仅附上实际使用、能对应回答判断的引用，而不是汇总所有工具命中。旧批次评分证据若来自目录，展示为“历史评分引用”，不能自动当作报告正文证据。
|
||||
|
||||
## 迁移与历史数据
|
||||
|
||||
增加必要的 Alembic 迁移和索引版本升级。优先利用已保存的学生材料解析页面重新分类和建索引；公共课程资料按现有入库路径处理。旧版索引在完成升级前不得被默默当作已分类正文使用。迁移和重建过程应可重试、可审计，保留原始文件、评分批次、教师复核及会话历史。
|
||||
|
||||
本任务只可在隔离测试数据库和测试材料上执行迁移、重建索引及评分验证。不要对当前业务数据库运行迁移、重建索引、重新评分或修改批次 3／会话 6。提供业务环境应用步骤和批次 3 的复核清单，但不执行这些业务数据操作。
|
||||
|
||||
## 有意义的回归验证
|
||||
|
||||
使用现有报告的已知页面及必要的合成混合页作为回归样本，至少覆盖：
|
||||
|
||||
1. 阶段报告 1 的目录页与第 6–7 页文献调研正文正确区分；stage1.literature 能召回正文分析。
|
||||
2. 阶段报告 3 的目录页与第 11–12 页测试正文正确区分；stage3.data 能召回测试描述。不要把“找到了这些页”直接等同于“应得某个分数”。
|
||||
3. 最终报告的摘要页、跨页目录和正文正确区分；目录仍可支持章节完整性评分。
|
||||
4. 混合页、目录续页、重复页眉和识别不确定页面不会被静默当作普通正文。
|
||||
5. 内容性评分不得引用目录、摘要或单独标题；结构性评分仍能合理使用目录。
|
||||
6. 正文补检仍不足时，模型分为 null、状态为待教师复核、总分待处理；教师能够正常复核，界面不预填 0。
|
||||
7. Agent 最终引用只包含回答实际使用且通过校验的来源；历史评分引文不会被误用作正文证据。
|
||||
8. 学生项目隔离、课程版本隔离、已有评分与导出功能保持可用。
|
||||
|
||||
优先运行针对性后端测试、隔离 PostgreSQL 集成测试、前端类型检查和生产构建。需要真实模型才能验证的部分单独说明，不要把未运行的验证写成通过。更新必要的项目文档，最后报告修改内容、实际测试结果、批次 3 建议复核的项目，以及尚待业务环境执行的步骤。
|
||||
~~~
|
||||
@@ -0,0 +1,190 @@
|
||||
# WiseGrade（智评）Codex Goal 模式开发提示词
|
||||
|
||||
将以下内容复制给 Codex，并使用 goal 模式执行。
|
||||
|
||||
```text
|
||||
你是本项目的主开发代理。请在当前工作目录完成 WiseGrade（智评）整套系统的搭建、开发、测试和部署文档。
|
||||
|
||||
## 最高优先级要求
|
||||
|
||||
1. 先完整阅读 `docs/GUIDE.md`，它是本项目的技术规格和业务约束。
|
||||
2. 当前项目英文名为 WiseGrade，中文名为智评。
|
||||
3. 当前只实现“自动化专业综合实践”，但课程、课程版本、课程目标、毕业要求指标点、评分规则、选题方向和 Prompt 必须可配置、可版本化，未来可以扩展其他课程。
|
||||
4. 系统只供教师使用，采用单机单管理员模式，不实现学生账号。
|
||||
5. 学生材料通过宿主机目录挂载进入容器。不要把原始学生文件设计成浏览器上传流程。前端只选择挂载目录 `/data/inbox` 下的相对目录，后端扫描和读取实际文件。
|
||||
6. 学生目录格式为 `学号_姓名_选题题目`。系统需要自动解析并支持教师在导入确认时修正。
|
||||
7. 支持 PDF、DOCX、PPTX 和 PPT 导出的 PDF。不支持旧版 DOC 输入。
|
||||
8. 评分材料为阶段报告1、阶段报告2、阶段报告3、最终报告、汇报 PPT/PPT PDF。
|
||||
9. 课程成绩结构是：阶段报告1 10% + 阶段报告2 10% + 阶段报告3 10% + 期末成绩 70%。期末成绩包含任务完成度20分、报告规范性20分、汇报答辩40分、结果分析20分；其中本系统只按照 PPT 内容评价“汇报答辩”，不评价现场口头答辩。
|
||||
10. 统一使用一个外部模型 `deepseek-flash`，该模型负责文本理解、图像理解、PPT分析、事实抽取、评分和评语生成。不要设计成文本模型和视觉模型两个必需模型。
|
||||
11. 使用本地嵌入模型，默认 `BAAI/bge-m3`，支持配置轻量替代模型。模型以独立离线模型目录或模型包提供，不能要求系统启动时在线下载。
|
||||
12. 每次评分创建独立评分批次。批次之间不覆盖、不设置唯一正式批次。每个批次都可查看、复核和导出。
|
||||
13. 教师必须可以逐项修改分数和评语。模型原始分数、教师修改结果、证据和修改记录必须同时保留。
|
||||
14. 最终必须支持导出 Excel 成绩表和每个学生一份 PDF 反馈报告。
|
||||
15. 开发和测试过程中必须及时 Git commit。提交信息使用清晰的 Conventional Commits 风格。
|
||||
|
||||
## 推荐技术栈
|
||||
|
||||
- 前端：React + TypeScript + Vite + Ant Design
|
||||
- 后端：FastAPI + SQLAlchemy + Pydantic
|
||||
- 数据库：PostgreSQL + pgvector
|
||||
- 后台任务：Redis + RQ
|
||||
- 解析：PyMuPDF、python-docx、python-pptx、LibreOffice headless
|
||||
- OCR：PaddleOCR 作为扫描 PDF 回退
|
||||
- 嵌入：BAAI/bge-m3
|
||||
- 大模型：OpenAI 兼容方式调用 deepseek-flash
|
||||
- 导出：openpyxl/pandas，HTML/CSS + WeasyPrint 或 Playwright
|
||||
- 部署：Docker Compose，兼容 Linux 和 Windows Docker Desktop
|
||||
|
||||
## 工作方式
|
||||
|
||||
### 第一步：检查和初始化
|
||||
|
||||
- 检查当前目录、现有文件和 `docs/` 资料。
|
||||
- 阅读 `docs/GUIDE.md`。
|
||||
- 如果没有 Git，执行 `git init`。
|
||||
- 创建合理的 `.gitignore`，不得忽略课程资料和源代码，但必须忽略 `.env`、模型目录、运行数据、缓存、构建产物和真实学生材料。
|
||||
- 创建 `README.md`，说明项目名称、启动方式、配置方法和开发状态。
|
||||
- 先提交：`chore: initialize WiseGrade project`。
|
||||
|
||||
### 第二步：设计并实现后端基础
|
||||
|
||||
- 创建 FastAPI 项目结构。
|
||||
- 创建配置模块、日志模块、异常处理、健康检查和数据库连接。
|
||||
- 使用 Alembic 或等价迁移工具。
|
||||
- 创建课程、课程版本、评分规则、指标点、项目、提交材料、评分批次、评分结果、证据、教师复核、导出任务和审计日志模型。
|
||||
- 保证所有评分结果关联课程版本、规则版本、模型配置快照和嵌入模型版本。
|
||||
- 编写单元测试。
|
||||
- 测试通过后提交：`feat: add backend foundation and database models`。
|
||||
|
||||
### 第三步：初始化课程资料和可编辑规则
|
||||
|
||||
- 从 `docs/` 现有材料建立“自动化专业综合实践”的初始课程版本。
|
||||
- 课程目标和毕业要求指标点至少包括 2.3、2.4、4.1、4.2、4.3、4.4、11.1、11.2。
|
||||
- 建立阶段报告1、2、3的初始评分规则，以及期末评分规则。
|
||||
- 评分规则必须有分值、评分等级、证据要求和关联课程目标字段。
|
||||
- 规则应可在 API 和前端中编辑、复制、发布新版本。
|
||||
- 不要把规则写死在 Prompt 或评分代码中。
|
||||
- 测试通过后提交：`feat: add course versioning and editable rubrics`。
|
||||
|
||||
### 第四步：实现挂载目录扫描和导入确认
|
||||
|
||||
- Docker 将宿主机目录挂载为 `/data/inbox:ro`。
|
||||
- 后端只允许访问 `/data/inbox`，必须防止路径越界。
|
||||
- 前端显示后端扫描出的目录树，教师选择某个大文件夹。
|
||||
- 后端扫描其中的学生子文件夹，解析 `学号_姓名_选题题目`。
|
||||
- 识别阶段报告1、2、3、最终报告和汇报PPT/PPT PDF。
|
||||
- 结合文件名、扩展名、首页文本、章节标题进行识别。
|
||||
- 对不确定、缺失、重复、无法解析的材料标记状态，交给教师确认。
|
||||
- 保存相对路径、文件大小、修改时间、SHA-256和解析状态。
|
||||
- 原始材料不复制到浏览器或应用上传临时目录。
|
||||
- 测试通过后提交：`feat: add mounted directory scanning and import confirmation`。
|
||||
|
||||
### 第五步：实现文档解析和页面资产
|
||||
|
||||
- PDF 使用 PyMuPDF 按页解析，保留页码、文本、图片和表格信息。
|
||||
- DOCX 使用 python-docx 解析标题、段落、表格和图片。
|
||||
- PPTX 使用 python-pptx 提取文字、表格和备注，并使用 LibreOffice 渲染幻灯片。
|
||||
- PPT PDF允许作为汇报材料，但需要教师确认材料类型。
|
||||
- 扫描 PDF 使用 OCR 回退。
|
||||
- 生成可追溯的结构化文档对象和页面图像。
|
||||
- 解析失败不得静默忽略，必须进入错误状态并显示原因。
|
||||
- 测试通过后提交：`feat: add document parsing and page rendering`。
|
||||
|
||||
### 第六步：实现知识库和 RAG
|
||||
|
||||
- 建立公共课程知识库：课程导学、课程目标、毕业要求、评分表、阶段模板、选题方向要求和优秀报告。
|
||||
- 为每个学生项目建立独立命名空间，禁止跨学生检索。
|
||||
- 使用结构感知切分，保留文档类型、阶段、页码、章节、课程版本和项目编号元数据。
|
||||
- 使用本地 BGE-M3 生成嵌入，向量保存到 pgvector。
|
||||
- 同时使用 PostgreSQL 全文检索、向量检索和元数据过滤。
|
||||
- 首次启动不得强制在线下载模型；支持挂载 `./models` 或指定本地模型目录。
|
||||
- 测试通过后提交：`feat: add knowledge ingestion and hybrid retrieval`。
|
||||
|
||||
### 第七步：实现 DeepSeek 适配器和评分编排
|
||||
|
||||
- 使用 OpenAI 兼容客户端接入 DeepSeek。
|
||||
- 模型默认名为 `deepseek-flash`，Base URL、API Key、超时、并发数和重试次数可配置。
|
||||
- API Key 后端保存，前端不得直接调用 DeepSeek，日志不得输出密钥。
|
||||
- 通过结构化 JSON Schema/Pydantic 校验模型输出。
|
||||
- 实现项目事实抽取、规则检查、指标级评分、PPT 页面分析和跨文档一致性检查。
|
||||
- 每个评分项输出分数、理由、原文证据、页码或幻灯片编号、缺失证据、建议和置信度。
|
||||
- 每个评分项只发送相关 RAG 证据和必要页面图片，不重复发送完整报告。
|
||||
- 模型不能对没有证据的内容自行假设。
|
||||
- 实现批次级后台任务、进度、失败重试和部分完成状态。
|
||||
- 测试通过后提交：`feat: add deepseek-flash scoring pipeline`。
|
||||
|
||||
### 第八步：实现教师复核和导出
|
||||
|
||||
- 实现学生项目列表、评分批次列表、逐项评分详情和证据查看。
|
||||
- 教师可以修改每个评分项的分数和评语。
|
||||
- 保留模型原始值和教师修改记录。
|
||||
- 缺失材料和无法评分状态必须明显显示。
|
||||
- 导出 Excel：学生信息、各阶段分数、期末分项、期末成绩和总评。
|
||||
- 导出单学生 PDF 反馈：各项分数、证据、页码、缺失内容、建议、教师修改结果、规则版本和模型信息。
|
||||
- 每个评分批次都可以单独导出。
|
||||
- 测试通过后提交：`feat: add teacher review and score exports`。
|
||||
|
||||
### 第九步：完善前端
|
||||
|
||||
实现至少以下页面：
|
||||
|
||||
- 仪表盘
|
||||
- 课程和课程版本
|
||||
- 评分规则编辑
|
||||
- 知识库资料
|
||||
- 挂载目录选择和扫描
|
||||
- 导入确认
|
||||
- 学生项目列表
|
||||
- 评分批次和进度
|
||||
- 学生评分详情
|
||||
- 教师复核
|
||||
- 导出任务
|
||||
- 模型设置
|
||||
|
||||
页面必须适合教师批量操作，重点显示异常、缺失和待复核项目。
|
||||
|
||||
测试通过后提交：`feat: add teacher-facing frontend`。
|
||||
|
||||
### 第十步：测试、部署和文档
|
||||
|
||||
- 使用 `docs/` 当前示例材料完成端到端测试。
|
||||
- 为路径安全、文件哈希、规则权重、材料识别、模型 JSON 输出、评分批次、教师复核和导出补充测试。
|
||||
- 不在测试中提交真实 API Key。
|
||||
- 提供 Linux 启动说明。
|
||||
- 提供 Windows Docker Desktop 启动说明。
|
||||
- 提供离线 BGE-M3 模型包安装说明。
|
||||
- 提供 `.env.example`，说明 DeepSeek 配置、挂载目录、数据库和模型目录。
|
||||
- 完成后提交：`test: add end to end coverage` 和 `docs: add deployment and usage guides`。
|
||||
|
||||
## 重要实现原则
|
||||
|
||||
- 先做可运行的最小闭环，再扩展功能。
|
||||
- 不要为了“微服务化”增加不必要复杂度，第一版采用模块化单体后端。
|
||||
- 不要把评分规则、课程目标或 Prompt 写死在代码中。
|
||||
- 不要把模型权重、API Key、真实学生材料提交到 Git。
|
||||
- 不要静默忽略解析失败、材料缺失或模型失败。
|
||||
- 所有自动评分都必须能回溯到证据。
|
||||
- 所有模型输出都必须经过结构化校验。
|
||||
- 对需要外部网络的模型调用提供清晰错误信息和重试机制。
|
||||
- 每完成一个可验证阶段就运行测试并及时提交 Git。
|
||||
- 除非遇到真正阻塞开发的业务矛盾，否则不要停下来请求用户确认，按规格和合理工程判断继续推进。
|
||||
|
||||
## 最终验收标准
|
||||
|
||||
完成后必须能够：
|
||||
|
||||
1. 在 Linux 上通过 Docker Compose 启动 WiseGrade。
|
||||
2. 在 Windows Docker Desktop 上按文档启动。
|
||||
3. 选择挂载目录下的大文件夹并扫描学生子目录。
|
||||
4. 识别和解析阶段报告、最终报告和 PPT/PPT PDF。
|
||||
5. 编辑课程目标、毕业要求和评分规则并生成新版本。
|
||||
6. 使用本地 BGE-M3 完成混合检索。
|
||||
7. 使用 `deepseek-flash` 完成文本和页面图像评分。
|
||||
8. 为每个评分项显示证据和页码/幻灯片编号。
|
||||
9. 创建多个独立评分批次并分别保存。
|
||||
10. 教师可以修改分数和评语。
|
||||
11. 每个批次分别导出 Excel 和逐生 PDF。
|
||||
12. 使用当前 `docs/` 示例材料完成端到端测试。
|
||||
13. Git 历史包含清晰、及时、可回退的阶段提交。
|
||||
```
|
||||
@@ -0,0 +1,29 @@
|
||||
# WiseGrade“会话”界面更新：Codex Goal 模式提示词
|
||||
|
||||
在本仓库根目录启动 Codex Goal 模式，将下方代码块完整粘贴为目标。本提示词针对已有对话功能做增量更新。
|
||||
|
||||
```text
|
||||
你是 WiseGrade 项目的开发代理。请直接在当前仓库完成“对话”界面的增量更新，包含必要的前后端、数据库迁移、测试和文档修改，直到下面的验收条件全部满足。不要只给出方案或界面样例。
|
||||
|
||||
先检查 git 工作区状态，阅读 README.md、HANDOFF.md、docs/GUIDE.md，并查看 frontend/src/App.tsx、Chat.tsx、style.css、api.ts，backend/wisegrade/chat_api.py、actions.py、models.py，相关 Alembic 迁移及 backend/tests/test_chat_agent.py。保留已有用户修改；沿用当前 React/TypeScript/Ant Design、FastAPI/SQLAlchemy、SSE 和业务 Agent 架构。旧的 docs/prompts/CODEX_CHAT_AGENT_GOAL_PROMPT.md 是上一阶段的实现提示词，本次以当前代码和以下需求为准。
|
||||
|
||||
## 产品行为
|
||||
|
||||
1. 将界面中面向用户的“对话”名称统一改为“会话”，包括左侧导航、页面标题、新建入口、空状态、提示和相关文档；保留现有路由、接口和历史数据的兼容性，不因显示名称变化破坏旧链接。
|
||||
2. 每次打开“会话”界面，默认进入一个新的空白会话草稿，不自动选中上次或列表中的历史会话。草稿只存在前端状态，不能因为进入页面、刷新页面或点击“新建”而写入数据库。历史会话仍在列表中，可点击查看和继续；再次进入界面仍默认展示新的空白草稿。
|
||||
3. 点击“新建”立即切换到一个无课程版本、评分批次、学生项目限定范围的空白草稿，不弹窗，也不发创建接口。输入区和范围选择在空白草稿中直接可用。已有会话若尚无第一条用户消息，其范围也可修改。用户发送第一条非空消息时，才持久化该会话和该消息；确保重复点击、请求失败或并发请求不会留下意外的空会话或创建多个会话。首次提交成功后切换到真实 ID，并继续现有 SSE 回答流程。模型回答失败时，已经成功提交的用户消息和会话仍应可恢复。
|
||||
4. 限定范围在第一条消息提交前可反复修改、清除；第一条消息一旦成功提交就固定，并在界面上明确展示为只读。后端也必须拒绝已开始会话的范围修改，不能仅靠前端禁用。沿用并复核现有课程版本、批次、学生项目之间的一致性校验；选择批次或项目时正确处理其所属课程版本，清除上级范围时避免残留冲突值。历史遗留的空会话也按“未发送第一条消息”处理。
|
||||
5. 会话列表增加删除操作，并有清晰的二次确认。提供后端删除接口，处理该会话的消息、Agent 运行记录、待确认操作等关联数据，防止外键错误和悬空记录；删除会话不能撤销已经确认执行的评分、导入、导出等业务操作，也不能抹掉必要的业务审计。运行中的会话应安全处理并给出明确反馈。删除当前会话后切换到新的空白草稿，列表、详情和本地缓存保持一致；删除其他会话不打断当前编辑。失败时显示错误，不假装删除成功。
|
||||
6. 助手的历史回答和正在生成的回答都渲染 Markdown，至少正确显示标题、段落、列表、链接、引用块、表格和代码块，并有适合聊天框的排版、换行和长内容处理。将模型内容视为不可信输入：禁止原始 HTML 注入，限制危险链接协议，避免 XSS。教师消息仍清楚可辨。
|
||||
7. 整理回答下方的“引用”：按结构化 citation 数据显示紧凑、易读的资料名、页码或幻灯片号、原文摘录和可打开的页面／图像链接；处理缺失字段、重复引用、长摘录与窄屏布局，避免原始对象、重复标题或错乱换行堆叠。引用本身应易于找到，不要被工具调用折叠区遮住。保持既有来源和证据链接的准确性。
|
||||
8. 将一次回答中的工具调用过程做成类似 Codex 的可展开区：默认折叠，仅显示工具名称、执行状态和简短摘要；展开后分别查看调用参数与调用结果／错误。流式执行时可见进行中、成功、失败状态；历史消息刷新后仍可查看对应工具调用与结果。使用稳定的调用标识关联事件，不要把多个同名调用混在一起。后端若需补充 SSE 事件或持久化字段，应做有界、必要的改动，限制结果大小并避免泄露密钥、敏感配置或不必要的学生原文。待确认操作卡片继续独立可见，不能被折叠或绕过确认。
|
||||
9. 一个会话正在生成回答或调用工具时，教师点击切换到其他会话，该会话必须继续在后台运行，切换回去能看到正确的实时进度和最终结果。允许多个不同会话同时运行，互不阻塞、互不串流；每个会话的输入禁用状态、运行标识、工具事件、错误和回答都按会话 ID 独立管理。会话列表显示各自的运行状态。不要让 React 组件卸载、当前选中会话变化或 SSE 客户端断开取消后端运行；刷新后应能恢复正在运行的状态，并通过重连、订阅或轮询继续取得结果。同一会话内重复发送仍按现有并发保护处理。不要把会话切换误认为停止命令。
|
||||
|
||||
## 实现与验证
|
||||
|
||||
优先复用现有接口与组件；为“首次发送才入库”、范围编辑、删除、并行会话运行及工具记录增加必要的 API、事务和 Alembic 迁移。明确失败重试及刷新后的状态：空草稿不出现在会话列表；有用户消息但模型失败的会话应出现并可继续；删除后不能继续访问其详情或确认其旧操作。不要改变 Agent 工具权限、业务写入确认边界、评分计算及检索范围隔离。
|
||||
|
||||
补充有意义的后端测试，覆盖首次发送的持久化时机与幂等／并发、范围修改与锁定、关联数据删除、运行中删除、历史会话兼容、工具记录恢复、切换或断开连接后原会话继续运行，以及不同会话并行且事件不串流。前端至少完成 TypeScript 与生产构建，并实际检查新建无弹窗、范围选择、历史切换、删除确认、Markdown、引用、工具折叠、运行时切换会话、多会话同时运行及移动端布局；若具备浏览器测试工具，执行交互验证。按项目现有方式运行适用测试；环境无法验证的项目说明具体原因，不把未运行的测试写成通过。
|
||||
|
||||
同步更新 README.md、docs/GUIDE.md 和必要的 HANDOFF.md 描述。完成后报告主要改动、实际验证命令及结果、仍有的限制。不要提交 .env、API Key、运行数据或学生原件。除确实无法从代码和本目标推断的业务矛盾外，自主完成实现，不停在普通实现选择上征求确认。
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
# 开发提示词
|
||||
|
||||
本目录集中保存供 Codex 执行的阶段开发任务。请在仓库根目录使用；提示词正文中的文件路径均相对于仓库根目录（明确写出的绝对路径除外）。使用前先阅读 [项目指南](../GUIDE.md) 和 [交接记录](../../HANDOFF.md)，核对当前实现及任务范围。
|
||||
|
||||
| 提示词 | 用途 |
|
||||
|---|---|
|
||||
| [初始系统开发](CODEX_GOAL_PROMPT.md) | 从零搭建系统的历史任务，保留作需求参考。 |
|
||||
| [业务 Agent](CODEX_CHAT_AGENT_GOAL_PROMPT.md) | 会话、业务工具、操作确认与自动索引的阶段任务。 |
|
||||
| [会话界面](CODEX_SESSION_UI_GOAL_PROMPT.md) | 草稿、范围、历史会话、Markdown、工具记录和后台运行的增量任务。 |
|
||||
| [目录、摘要与正文证据治理](CODEX_EVIDENCE_RAG_GOAL_PROMPT.md) | 页面分类、检索与评分证据治理任务，包含业务数据库不可改写的明确边界。 |
|
||||
|
||||
提示词记录任务要求，不代表功能已经完成或通过验证。应用运行时的评分 Prompt 由课程版本管理，不在本目录维护。
|
||||
Reference in New Issue
Block a user