docs: consolidate project guide and organize prompts

2026-09-30 18:15:48 +08:00
parent 83aa0e84a2
commit 540d0e2918
11 changed files with 1171 additions and 1133 deletions
@@ -1,33 +1,27 @@
 # WiseGrade（智评）

-WiseGrade 是面向《自动化专业综合实践》课程的教师端自动评分系统。
+WiseGrade 是面向《自动化专业综合实践》课程的教师端自动评分系统，采用个人电脑本地部署、单机单管理员模式。

-教师端系统包含持久会话与业务 Agent、课程版本、挂载目录导入、自动文档解析与索引、知识库检索、独立评分批次、教师复核及导出。完整技术规格见：
-
- [技术方案与开发规格](docs/WISEGRADE_TECHNICAL_SPEC.md)
- [会话页面与业务 Agent](docs/CHAT_AGENT.md)
- [Codex Goal 模式开发提示词](docs/CODEX_GOAL_PROMPT.md)
-
-## 当前约束
-
- 仅供教师使用
- 通过宿主机挂载目录读取学生材料
- 支持 PDF、DOCX、PPTX 和 PPT 导出的 PDF
- 使用本地 BGE-M3 嵌入模型
- 使用 `deepseek-flash` 进行文本和图像理解
- 支持课程、评分规则和评分批次版本化
- 支持 Excel 成绩表和逐生 PDF 反馈导出
-
-## 资料
-
-课程原始资料位于 `docs/` 目录。
+系统支持课程与评分规则版本管理、挂载目录导入、文档解析与知识库检索、独立评分批次、教师复核、Excel 成绩表和逐生 PDF 反馈导出。教师也可通过持久会话查询材料、调用业务功能，并在确认卡片中核对和执行写入操作。

 ## 快速启动

-1. 复制 `.env.example` 为 `.env`，设置 `WISEGRADE_DATA_DIR`、`DEEPSEEK_API_KEY` 和 `WISEGRADE_SECRET_KEY`。
-2. 将离线嵌入模型放在 `models/bge-m3/`（或修改 `EMBEDDING_MODEL_PATH`）。
-3. 运行 `docker compose up`，访问 <http://127.0.0.1:18080>。
+1. 复制 `.env.example` 为 `.env`，设置学生材料目录 `WISEGRADE_DATA_DIR`、`DEEPSEEK_API_KEY` 和随机 `WISEGRADE_SECRET_KEY`。
+2. 将离线 BGE-M3 模型放在 `models/bge-m3/`；扫描 PDF 另需离线 OCR 模型。
+3. 在仓库根目录运行 `docker compose up`，访问 <http://127.0.0.1:18080>。

-打开系统默认进入空白“会话”草稿；点击“新建”也只切换草稿，发送第一条消息才保存会话。历史会话可从列表继续或删除；回答上方可逐层展开工具调用，末尾可展开引用原文与页面链接。查询可直接执行，导入、入库、建批、启动、复核和导出先展示确认卡片，由教师点击后执行。学生材料只从只读挂载的 `/data/inbox` 读取。没有本地嵌入模型或 API 密钥时，系统仍可启动和完成导入；索引、会话或评分会显示明确错误。详细部署和使用步骤见 [部署与使用指南](docs/DEPLOYMENT.md)。
+学生材料从只读挂载的 `/data/inbox` 读取，支持 PDF、DOCX、PPTX 和 PPT 导出的 PDF。默认使用本地 BGE-M3 嵌入模型及 `deepseek-flash` 模型配置；模型端点需支持所用功能的文本、图像和工具调用。没有本地嵌入模型或 API 密钥时仍可启动和导入，依赖模型的功能会显示配置错误。

-评分证据与会话检索引用共用文档 ID 和页码。页面文字来自 PostgreSQL 的完整资料页记录，检索片段与向量也在 PostgreSQL；页面 PNG 位于 `data/processed/`，可从引用的“查看图像”打开。数据库直接生成的课程目标和规则没有实体页图像，因此只显示“查看页面文字”。历史引用由迁移 `0005` 一次性规范化。
+## 文档入口
+
+部署、使用和技术说明统一维护在 **[项目指南](docs/GUIDE.md)**：
+
+- [部署与配置](docs/GUIDE.md#deployment)：Linux、Windows Docker Desktop、离线模型和 OCR。
+- [教师使用](docs/GUIDE.md#usage)：导入、评分、复核、导出与会话确认规则。
+- [业务规则与技术设计](docs/GUIDE.md#design)：成绩结构、课程依据、解析、RAG、评分和版本管理。
+- [会话与业务 Agent 实现](docs/GUIDE.md#agent)：任务、数据、工具边界、API 和恢复机制。
+- [开发与测试](docs/GUIDE.md#development) · [故障定位](docs/GUIDE.md#troubleshooting)。
+
+[开发提示词](docs/prompts/README.md) 集中存放阶段任务说明；[交接记录](HANDOFF.md) 保留实现进展、验证记录和接手事项。
+
+课程原始资料及测试示例仍位于 `docs/` 根目录，应用和测试按现有路径读取；学生原件、模型权重和运行产物不纳入项目文档。