From 3e6d9914f93323472e3a57e75244181088b68fec Mon Sep 17 00:00:00 2001 From: Blood_hand Date: Fri, 4 Sep 2026 19:19:14 +0800 Subject: [PATCH 1/3] docs: add project understanding --- docs/project-understanding.md | 90 +++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/project-understanding.md diff --git a/docs/project-understanding.md b/docs/project-understanding.md new file mode 100644 index 0000000..f7a0374 --- /dev/null +++ b/docs/project-understanding.md @@ -0,0 +1,90 @@ +# CodeSense（酷森思）项目理解 + +> 阶段一接管记录：本文档基于仓库源码、现有 README、测试命名与本地运行结果整理。它只描述当前实现，不代表对未验证的线上部署行为作保证。 + +## 1. 项目定位 + +CodeSense 是面向高校编程教学的 Flask Web 平台，把 C++ 作业提交、测试执行、AI 辅导、阶段式学习记录和教师侧学情分析放在同一条链路中。学生侧重点是“提交—反馈—修正—解释”，教师侧重点是作业、班级、提交记录和能力趋势管理。 + +项目的核心产品判断是：评测结果不仅用于判定对错，也用于驱动启发式指导和学习画像。AI 是可选服务，代码执行与数据库记录仍是主要业务事实来源。 + +## 2. 主要目录与模块 + +| 路径 | 职责 | 关键入口 | +| --- | --- | --- | +| `app.py` | Flask 应用创建、配置加载、扩展初始化、蓝图注册、日志与任务启动 | `create_app()` | +| `config.py` | development/testing/production 配置；数据库 URI 和密钥来自环境变量 | `config` | +| `models.py` | SQLAlchemy 模型、关系和部分统计/初始化逻辑 | `db`、`init_db()` | +| `routes/` | 页面和 API 蓝图：认证、作业、班级、用户、成绩、思维/阶段流程 | 各文件中的 `Blueprint` | +| `services/` | AI 客户端、演示数据隔离、课程评分、教师分析和 API Key 读取 | `llm_client.py`、`demo_database.py` | +| `utils/` | 代码执行、评测、指导、建议、异步任务、能力评分及 Markdown 处理 | `sandbox_runner.py`、`code_evaluator.py` | +| `tasks/` | 提交后处理和能力分析任务 | `submission_tasks.py` | +| `templates/` | Jinja 页面模板；`static/` 存放 JS、CSS、编辑器与图片 | 页面层 | +| `tests/` | 应用、演示体验、认证、班级/成绩、沙箱和阶段三 Agent 等测试 | pytest 测试文件 | + +应用启动时在 `app.py` 注册 `auth`、`main`、`assignments`、`users`、`api`、`classes`、`thinking`、`grades` 等蓝图。默认开发数据库是项目实例目录下的 SQLite；生产配置要求显式提供 `DATABASE_URL` 和 `SECRET_KEY`。 + +## 3. 核心流程：学生提交 C++ 作业 + +```mermaid +sequenceDiagram + participant B as 浏览器 + participant R as routes/assignments 或 /api + participant D as SQLAlchemy/SQLite 或 MySQL + participant T as tasks/submission_tasks + participant S as utils/sandbox_runner + participant A as AI 服务（可选） + + B->>R: POST 作业提交（源码、作业、测试相关数据） + R->>D: 创建/更新 Submission + R->>T: 调度提交处理或进入评测逻辑 + T->>S: C++17 编译并运行测试用例 + S-->>T: 编译状态、每例输出、错误、耗时 + T->>A: 请求评估/反馈（配置了 Key 时） + A-->>T: 评分、解释或指导文本 + T->>D: 保存结果、反馈、提交计数和能力相关数据 + R-->>B: 页面跳转、结果页或异步状态 +``` + +源码核验点：`routes/assignments.py` 的 `submit_code()` 是页面提交入口，`routes/api.py` 提供 `/api/submit`；`tasks/submission_tasks.py` 调用 `run_test_cases()` 和 `evaluate_cpp_code()`；`utils/sandbox_runner.py` 使用临时目录、`g++ -std=c++17`、编译超时 15 秒和运行超时 5 秒，并标准化输出后比较。 + +控制流不是单一的“请求内同步函数”：项目同时存在路由内评测、后台线程任务和阶段式 `thinking` 流程。因此追踪一次提交时，需要同时看页面路由、任务实现和模型写入，而不能只从模板判断行为。 + +## 4. 本地运行与测试 + +### 运行 + +本机已发现 Conda 环境： + +```powershell +conda activate codesense +cd D:\ProGram\CodeSense +python run.py +``` + +随后访问 `http://127.0.0.1:5000/login`。开发环境可不配置 AI Key；此时 AI 相关能力不可用，但基础页面和不依赖 AI 的功能仍可检查。C++ 评测还要求 `g++` 在 `PATH` 中。 + +### 测试 + +```powershell +conda activate codesense +python -m pytest tests -q +``` + +本次接管核验：`codesense` 环境为 Python 3.10.21；Flask 2.2.5、SQLAlchemy 2.0.51 可导入；`python -m py_compile app.py run.py` 通过；已启动 `python run.py`，访问 `/login` 返回 HTTP 200。尝试按 `requirements.txt` 安装时，PyPI 连接出现 `SSLEOFError`，因此没有把网络安装结果当作验证结论。 + +## 5. 风险与未知项 + +- `sandbox_runner.py` 是应用层 subprocess 隔离，不等同于面向恶意代码的完整容器/虚拟机沙箱；公网部署需要额外的权限、网络和资源隔离。 +- AI 输出依赖外部服务、密钥和提示词约束；超时、异常或不可信输出可能影响反馈质量，不能替代编译测试和教师判断。 +- 路由内同步评测、后台线程和 SSE/状态查询并存，生产部署下的并发、进程模型和任务丢失行为需要进一步压测确认。 +- 数据库默认值、`.env`、会话目录、上传目录和演示临时数据库的生命周期依赖运行环境；多进程部署的共享存储与清理策略尚未完整核验。 +- 仓库存在较多历史兼容逻辑、页面/脚本的多套编辑器实现和阶段三 Agent 代码；模块边界目前是“可运行的演进结构”，不是严格分层架构。 +- 本次只完成源码理解和基础启动核验，未验证真实 MySQL、Redis、AI 账户、生产 Gunicorn 配置或 Windows `g++` 评测链路。 + +## 6. 我的整体理解 + +CodeSense 本质上是一个以提交记录为主线的教学工作台：`Submission` 和评测证据把学生行为沉淀下来，阶段式流程把“写代码”扩展为“描述思路、构造步骤、解释原理”，教师分析再把这些记录聚合成班级和能力视图。Flask 蓝图承担入口编排，SQLAlchemy 模型承担状态持久化，`utils` 和 `services` 承担评测/AI/分析能力。 + +当前最重要的系统边界是三者之间的可信度：代码执行结果是较硬的事实，数据库中的学习记录是业务状态，AI 文本是带不确定性的辅助解释。后续接管应优先围绕这条边界补充运行观测、任务一致性和沙箱隔离验证，而不是先扩大业务功能。 + From cf1ee288b404d0c4c077a79754e64b00ff20d777 Mon Sep 17 00:00:00 2001 From: BloodHand180621 Date: Sat, 5 Sep 2026 21:49:28 +0800 Subject: [PATCH 2/3] Document project architecture and verification boundaries --- docs/project-understanding.md | 84 ++++++++++++++++++++++++++--------- 1 file changed, 62 insertions(+), 22 deletions(-) diff --git a/docs/project-understanding.md b/docs/project-understanding.md index f7a0374..78a8ae5 100644 --- a/docs/project-understanding.md +++ b/docs/project-understanding.md @@ -2,6 +2,20 @@ > 阶段一接管记录：本文档基于仓库源码、现有 README、测试命名与本地运行结果整理。它只描述当前实现，不代表对未验证的线上部署行为作保证。 +## PR 说明与复核范围 + +### 使用的 AI 工具 + +本次接管使用 AI 辅助进行目录检索、源码定位、流程归纳和文档校对；所有关键结论均回到仓库源码和本地命令结果核验。未使用 AI 生成或提交任何 API Key、Token、密码、数据库凭据或内部链接。AI 辅助分析不替代代码执行、测试或人工复核。 + +### 阅读范围 + +重点阅读和交叉核对了：`app.py` 的 `create_app()`、`config.py` 的环境配置、`models.py` 的数据库模型入口、`routes/assignments.py` 的 `submit_code()`、`routes/api.py` 的 `submit_code()`、`tasks/submission_tasks.py` 的 `evaluate_submission_async()`、`utils/code_evaluator.py` 的 `evaluate_cpp_code()`、`utils/sandbox_runner.py` 的 `run_test_cases()`，以及 `services/`、`utils/agents/`、`tasks/`、`templates/`、`static/` 和 `tests/` 的目录结构与相关测试命名。阅读范围以理解主流程和风险边界为目的，并非逐行审计全部文件。 + +### 本 PR 的变更边界 + +本 PR 只新增本项目理解文档和其中的 Mermaid 图示，不新增业务功能、不修改线上配置、不调整依赖，也不包含真实凭据。`docs/` 被仓库忽略规则覆盖，因此提交文档时使用了显式的 `git add -f docs/project-understanding.md`。 + ## 1. 项目定位 CodeSense 是面向高校编程教学的 Flask Web 平台，把 C++ 作业提交、测试执行、AI 辅导、阶段式学习记录和教师侧学情分析放在同一条链路中。学生侧重点是“提交—反馈—修正—解释”，教师侧重点是作业、班级、提交记录和能力趋势管理。 @@ -19,7 +33,9 @@ CodeSense 是面向高校编程教学的 Flask Web 平台，把 C++ 作业提交 | `services/` | AI 客户端、演示数据隔离、课程评分、教师分析和 API Key 读取 | `llm_client.py`、`demo_database.py` | | `utils/` | 代码执行、评测、指导、建议、异步任务、能力评分及 Markdown 处理 | `sandbox_runner.py`、`code_evaluator.py` | | `tasks/` | 提交后处理和能力分析任务 | `submission_tasks.py` | -| `templates/` | Jinja 页面模板；`static/` 存放 JS、CSS、编辑器与图片 | 页面层 | +| `forms.py` | Flask-WTF 表单定义和输入校验 | 登录、作业、提交等表单 | +| `templates/` | Jinja 页面模板；`templates/components/` 提供可复用编辑器组件 | 页面层 | +| `static/` | CSS、图片和前端 JavaScript；`static/js/` 负责编辑器、提交和阶段式学习交互 | 浏览器交互层 | | `tests/` | 应用、演示体验、认证、班级/成绩、沙箱和阶段三 Agent 等测试 | pytest 测试文件 | 应用启动时在 `app.py` 注册 `auth`、`main`、`assignments`、`users`、`api`、`classes`、`thinking`、`grades` 等蓝图。默认开发数据库是项目实例目录下的 SQLite；生产配置要求显式提供 `DATABASE_URL` 和 `SECRET_KEY`。 @@ -27,28 +43,35 @@ CodeSense 是面向高校编程教学的 Flask Web 平台，把 C++ 作业提交 ## 3. 核心流程：学生提交 C++ 作业 ```mermaid -sequenceDiagram - participant B as 浏览器 - participant R as routes/assignments 或 /api - participant D as SQLAlchemy/SQLite 或 MySQL - participant T as tasks/submission_tasks - participant S as utils/sandbox_runner - participant A as AI 服务（可选） - - B->>R: POST 作业提交（源码、作业、测试相关数据） - R->>D: 创建/更新 Submission - R->>T: 调度提交处理或进入评测逻辑 - T->>S: C++17 编译并运行测试用例 - S-->>T: 编译状态、每例输出、错误、耗时 - T->>A: 请求评估/反馈（配置了 Key 时） - A-->>T: 评分、解释或指导文本 - T->>D: 保存结果、反馈、提交计数和能力相关数据 - R-->>B: 页面跳转、结果页或异步状态 +flowchart TB + B[浏览器] + P[页面提交
routes/assignments.py] + API[JSON 提交
routes/api.py /api/submit] + DB[(Submission)] + T[后台评测任务
tasks/submission_tasks.py] + E[直接评估
utils/code_evaluator.py] + S[测试用例沙箱
utils/sandbox_runner.py] + AI[AI 反馈（可选）] + R[保存评测结果与统计] + + B --> P + B --> API + P -->|保存 pending| DB + P -->|异步调度| T + API -->|保存 pending| DB + API -->|请求内直接调用| E + T --> E + T --> S + E -. 配置可用时 .-> AI + E --> R + AI --> R + S --> R + R --> DB ``` -源码核验点：`routes/assignments.py` 的 `submit_code()` 是页面提交入口，`routes/api.py` 提供 `/api/submit`；`tasks/submission_tasks.py` 调用 `run_test_cases()` 和 `evaluate_cpp_code()`；`utils/sandbox_runner.py` 使用临时目录、`g++ -std=c++17`、编译超时 15 秒和运行超时 5 秒，并标准化输出后比较。 +源码核验点：`routes/assignments.py` 的 `submit_code()` 先保存 `pending` 提交，再调用 `evaluate_submission_async()`，由 `tasks/submission_tasks.py` 执行 AI 评估和 `run_test_cases()`；`routes/api.py` 的 `/api/submit` 则在请求内直接调用 `evaluate_cpp_code()`，随后触发能力分析。因此两条提交路径不能简单视为同一条异步链路。`utils/sandbox_runner.py` 使用临时目录、`g++ -std=c++17`、编译超时 15 秒和运行超时 5 秒，并标准化输出后比较。 -控制流不是单一的“请求内同步函数”：项目同时存在路由内评测、后台线程任务和阶段式 `thinking` 流程。因此追踪一次提交时，需要同时看页面路由、任务实现和模型写入，而不能只从模板判断行为。 +AI 服务不是评测事实的唯一来源：`evaluate_cpp_code()` 在 AI 不可用或调用异常时通常会回退到启发式评分或通用反馈；异步任务对公开演示会话捕获到的评测异常则会显式标记失败，避免把任务异常伪装成成功。具体行为取决于调用路径、演示会话标识和当前配置，不能把 AI 返回文本当作程序正确性的证明。 ## 4. 本地运行与测试 @@ -71,7 +94,25 @@ conda activate codesense python -m pytest tests -q ``` -本次接管核验：`codesense` 环境为 Python 3.10.21；Flask 2.2.5、SQLAlchemy 2.0.51 可导入；`python -m py_compile app.py run.py` 通过；已启动 `python run.py`，访问 `/login` 返回 HTTP 200。尝试按 `requirements.txt` 安装时，PyPI 连接出现 `SSLEOFError`，因此没有把网络安装结果当作验证结论。 +本次接管核验分为以下几类： + +- 已执行：`codesense` 环境中的 Python 版本检查，结果为 Python 3.10.21。 +- 已执行：导入 Flask 2.2.5 和 SQLAlchemy 2.0.51。 +- 已执行：`python -m py_compile app.py run.py routes/api.py routes/assignments.py tasks/submission_tasks.py utils/sandbox_runner.py`，通过。 +- 已执行：启动 `python run.py`，访问 `/login`，返回 HTTP 200。 +- 未执行：完整 pytest；当前 Conda 环境没有安装 `pytest`，通过 PyPI 安装时出现 `SSLEOFError`。 +- 未执行：真实 MySQL、Redis、AI 服务和 C++ 编译评测链路；其中 C++ 评测还需要确认 Windows 的 `g++` 配置。 + +### 验证限制记录 + +尝试安装测试依赖的命令为： + +```powershell +conda activate codesense +python -m pip install -r requirements.txt +``` + +该命令因访问 PyPI 时出现 `SSLEOFError` 失败；随后执行 `python -m pytest tests/test_app.py -q`，结果为 `No module named pytest`。因此本 PR 不宣称 pytest 测试通过，只报告已完成的语法检查、依赖导入检查和 `/login` 启动检查。此前尝试通过 GitHub CLI 创建 PR 时还发现本机没有 `gh` 命令；PR #8 的后续推送需由已认证的 Git 客户端完成。 ## 5. 风险与未知项 @@ -87,4 +128,3 @@ python -m pytest tests -q CodeSense 本质上是一个以提交记录为主线的教学工作台：`Submission` 和评测证据把学生行为沉淀下来，阶段式流程把“写代码”扩展为“描述思路、构造步骤、解释原理”，教师分析再把这些记录聚合成班级和能力视图。Flask 蓝图承担入口编排，SQLAlchemy 模型承担状态持久化，`utils` 和 `services` 承担评测/AI/分析能力。 当前最重要的系统边界是三者之间的可信度：代码执行结果是较硬的事实，数据库中的学习记录是业务状态，AI 文本是带不确定性的辅助解释。后续接管应优先围绕这条边界补充运行观测、任务一致性和沙箱隔离验证，而不是先扩大业务功能。 - From cc49e4787869f13462f1257c697053ee979e3292 Mon Sep 17 00:00:00 2001 From: BloodHand180621 Date: Sat, 5 Sep 2026 22:00:49 +0800 Subject: [PATCH 3/3] Add files via upload