11 KiB
11 KiB
WiseGrade（智评）Codex Goal 模式开发提示词
将以下内容复制给 Codex，并使用 goal 模式执行。
你是本项目的主开发代理。请在当前工作目录完成 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 历史包含清晰、及时、可回退的阶段提交。