当前版本：v2.2.0。
这是 CodeSense Standard Edition 的当前正式版本。发布级变更会记录在 CHANGELOG.md、Git tag 和 GitHub Release 中。
目录
v2.2.0 · 从学习记忆回到原题
学生现在可以从首页、知识路径和作业页查看自己的学习记忆，按作业查找反馈，并返回原提交继续练习。AI 辅导引用个人反馈时也会给出原提交入口。撤回或已更新的反馈不会继续作为旧证据出现；教师仍通过原有作业批注流程回应学生。
产品预览
下面的截图来自当前应用页面。
为什么做这个项目
普通 OJ 很擅长判断程序是否通过测试，但学生看到的通常只有 AC 或 WA。他们不一定知道问题出在算法、实现、边界条件还是调试过程。教师面对大量提交记录，也很难手工归纳每个班级反复出现的问题。
CodeSense 把代码提交、受限执行、AI 辅导、分阶段练习和学情记录放在同一条流程里。学生先写出思路，再逐步构造程序，最后用自己的话解释实现过程。教师可以从作业、班级和学生记录中查看学习进展。
这个项目目前适合高校程序设计课程、编程实训和教学试点，也可以作为研究引导式编程学习流程的工程起点。
适用对象
| 使用者 | 可以完成的事情 |
|---|
| 学生 | 提交 C++ 程序，查看测试结果和反馈，完成思路描述、步骤组装与费曼教学 |
| 教师 | 创建作业，管理班级和花名册，查看提交、完成情况、知识点和能力趋势 |
| 开发者 / 研究者 | 在 Flask、SQLAlchemy 和可替换的 AI 接口上继续扩展评测、教学和数据分析 |
主要功能
代码评测与受限执行
项目内部把这条执行链称为 Causal Sandbox。当前实现主要依靠应用层限制，适合课程内的受控实验，不应当被当作完整的操作系统级安全沙箱。
- 使用 g++ 按 C++17 编译学生代码；
- 编译超时为 15 秒，单个测试用例运行超时为 5 秒；
- 编译和运行子进程的 stdout/stderr 都在运行期间按每路 4096 字节读取；超过上限会及时终止子进程并返回明确的失败结果，不会把截断前缀误判为通过；
- 对正常输出进行换行、行尾空白和末尾空行规范化后比对；
- 使用临时工作目录保存编译产物，执行结束后清理；
- 将编译错误、运行时错误、超时和测试结果交给评测与辅导流程。
如果要面向公网运行，还需要增加容器或虚拟机隔离、低权限账户、网络限制和资源配额。
三阶段引导式学习
一次练习分成三个阶段：
- 思路描述：学生先用自然语言写出算法，系统根据作业要求给出评估和提示。
- 步骤组装：学生填写或选择程序步骤，系统检查顺序并生成代码预览。
- 费曼教学：学生向对话中的 AI 角色解释程序，在追问和修正中检查自己是否理解。
提示词约束和 sanitize_response 过滤器会尽量减少 AI 直接给出完整答案代码的情况，但 AI 仍可能出错。最终结果要以程序评测和教师判断为准。
学习记录与能力画像
系统会记录代码提交、评测结果、提示请求和引导式学习过程，并从算法、代码风格、功能完整性、执行效率和可读性等维度整理能力信息。教师端可以查看知识点得分、个人趋势和班级视图。
作业提交成绩按题目评测计算，能力画像汇总多次学习表现。v2.0.0 起，两者均以 0–100 百分制显示；历史五分制提交依据提交时间兼容读取。
学习记忆与知识路径
v1.8.0 让学生学习记忆在更新失败时继续保留上一版可用记录，并提供有限次重试、过期来源治理和状态提示。学生提交评测后会沿用同一条更新路径，AI 辅导的 JSON/SSE 完成响应会说明来源、索引状态和作用域。
教师首页增加班级学习记录索引汇总，只展示管理班级的人数与状态数量，并连接到已有的班级知识覆盖。学生撤回或过期的来源继续排除查询，教师页面不会展示学生私有来源内容。
v1.9.0 把班级知识覆盖和学习记忆状态连接成教师可执行动作。教师可以直接创建针对性练习，也可以提醒需要更新学习记忆的学生；学生会在行动中心看到提醒，并回到自己的个人学习记忆入口。图谱关系保留作业来源和版本，教师只看管理班级的汇总信息；学生撤回的个人来源不会进入辅导检索。
v2.0.0 把学生知识图谱建议、个人学习记忆状态和教师班级建议接入行动中心。学生可以从图谱建议进入本人可访问的作业，也可以从尚未建立、过期或更新失败的记忆提醒返回首页管理自己的学习来源；教师可以从班级汇总建议进入知识焦点和针对性练习，页面只展示本人管理班级的汇总信息。教师发送的记忆提醒只占一个行动项目，学生完成更新后提醒自动结束。新提交继续采用百分制评分，沙箱结果、AI 反馈以及作业和学生统计采用相同的分值范围；提交详情展示有文字依据的 AI 分项参考，评测等待期间显示当前状态。学生与班级能力图依据带有具体理由的 AI 分项，缺少班级记录时不显示班级曲线。
教师可在班级知识焦点页查看作业知识点标签来自 AI 提取还是教师关联，并直接打开标签编辑页。添加或移除标签后，学生知识路径、教师班级概览、作业辅导证据和该作业范围内的个人学习检索会读取更新后的标签；学生自己的历史掌握记录继续保留。
v1.7.0 把知识图谱和学生学习记忆接入学生辅导与教师干预流程。学生提问和 Code Studio 的完成响应会返回带有作用域、来源引用和来源版本的图谱投影；没有图谱数据时会明确显示无结果状态，个人记录只在当前学生范围内使用。
教师知识点提醒展示班级聚合掌握度、样本数和需要加强的人数，并可直接创建预先关联知识点、预先选择班级的练习作业，创建后进入已有班级布置流程。学生向量检索先在数据库中执行学生与作业范围过滤，再计算相似度；离线评测同时记录召回、作用域过滤和查询延迟指标。
v1.6.0 在学生首页提供来源治理。学生可以查看学习记忆的来源类型、版本和状态，撤回单条来源，并在索引陈旧或重建失败时看到明确的更新入口。索引只读取当前学生的数据，来源内容经过隐私过滤，撤回后不会继续参与检索。
学生在提问或 Code Studio 中请求代码辅导时，AI 会结合当前作业范围内的个人学习记录和作业知识图谱，回答末尾显示来源、作用域和索引版本，帮助学生回看自己的学习过程。学习记忆与图谱用于引导反思和复习，分数仍由评测流程与教师判断决定。
学生首页的知识路径展示作业、知识点和本人掌握度之间的关系；教师首页的知识点提醒可以直接进入针对性练习，AI 教学建议可以查看作业并布置到所属班级。每条图谱关系都带有来源引用和版本指纹，教师视图不会显示单个学生的私有学习来源。
学习会话连续性与状态可视化
CodeSense 会把引导式学习过程投影为可解释的会话状态：学生离开或刷新页面后，可以从“继续学习”入口回到最近会话，并看到当前阶段、下一步动作和可恢复提示；教师可以在授权范围内查看会话概览、阶段进度，并按“进行中、空闲、已完成、已放弃”筛选。状态接口只读已有学习记录，不改写历史数据，也会明确区分服务器观察时间、已存客户端计时和时间戳来源。
作业知识证据工作区
作业详情、提交详情和 Code Studio 会围绕当前作业展示知识焦点与有界证据：学生先看到需要掌握的概念、证据摘要和具体下一步；教师和管理员可以查看知识覆盖与降级状态；AI 代码建议在回答完成时附带可展开的证据收据。检索严格限定在当前作业和当前用户可访问的范围内；没有匹配证据时会明确提示仍可继续提问，知识证据只用于学习参考，不是作业评分依据。
角色化行动中心
v1.2.0 增加统一的行动中心，把学生的继续学习、评测与复核提示，教师的待复核与学情动作，以及管理员的反馈、能力与系统治理入口汇总为角色化队列。页面与只读 API 共用同一份聚合结果，按当前身份隔离数据源、限制条数并标记降级来源；返回内容不包含学生代码正文、姓名或联系方式等敏感字段。入口位于 /action-center，接口位于 /api/action-center。
v2.0.0 让图谱建议成为行动中心里可直接使用的下一步：学生进入符合本人权限的作业，教师进入知识焦点页查看班级练习；个人学习记忆尚未建立、过期或更新失败时，学生能从行动中心返回更新入口。管理员仍只看到反馈、能力分析和系统队列。
教师端
教师可以创建和编辑作业，维护测试用例和提交记录，组织班级与花名册，查看完成情况和知识点趋势。学生、教师和管理员使用不同的角色权限。
编辑器与交互
浏览器内提供代码编辑器，使用 Monaco Editor 的页面会按需加载。引导式学习页面包含步骤选择、代码预览和对话交互，部分流程支持语音转文字与文本优化。
从提交到理解
flowchart LR
A[作业与学习目标] --> B[学生描述思路]
B --> C[步骤组装与代码提交]
C --> D[受限编译与运行]
D --> E[评测结果与运行证据]
E --> F[AI 提示与教师反馈]
F --> G[修正、解释与再提交]
G --> C
E --> H[能力画像与知识点记录]
H --> I[学生私有学习记忆]
I --> J[受限检索与 AI 辅导]
H --> K[教师班级知识覆盖]
在线体验
可以直接打开 在线体验站点，也可以在本地启动服务后访问 /login。登录页提供两个无需注册的体验入口。
- 学生体验进入“演示作业一：循环与斐波那契数列”，可以依次查看思路描述、步骤组装和费曼教学。
- 教师体验进入教师首页，可以查看演示班级、学生状态、作业完成矩阵和 AI 学情建议，再进入班级详情查看记录。
体验数据边界
公开体验会为每次访问创建随机会话和独立的临时 SQLite 数据库。演示用户、班级、作业、提交、引导过程、知识点画像和 AI 分析只写入本次会话，不会创建正式用户，也不会写入正式业务数据库。
退出体验后，临时数据库及旁路文件会清理。浏览器直接关闭时，服务会按空闲超时和最长生命周期清理遗留会话，并在启动时再次检查。下一次进入会重新获得预设状态。
体验中的 AI 分析会调用当前配置的 AI 服务。没有可用密钥、服务调用失败或返回内容异常时，页面会显示失败或重试状态，不会把预设文字当成 AI 结果。
演示环境中的作业提交、知识点画像、五维能力和贝叶斯权重评估均采用 0–100 百分制。
旧的 /sandbox-login/<id> 和 /classes/seed-demo-data 只用于开发和测试，不作为公开入口。
系统结构
flowchart TB
Browser[浏览器]
subgraph Server[Flask 应用]
Routes[Blueprint 路由]
Services[业务服务]
Tasks[后台任务线程]
Routes --> Services
Services --> Tasks
end
DB[(SQL 数据库)]
Sandbox[C++17 评测执行器]
LLM[可选 AI 服务<br/>智谱或 OpenAI]
Session[Redis 或文件会话]
Browser -->|HTTP / SSE| Routes
Services --> DB
Services --> Sandbox
Services -. AI 请求 .-> LLM
Tasks --> DB
Tasks -. 异步 AI 分析 .-> LLM
Routes --> Session
演示数据如何隔离
flowchart LR
Entry[公开体验入口] --> Demo[演示会话]
Demo --> Temp[(临时 SQLite 数据库)]
Demo -. 不写入 .-> Formal[(正式业务数据库)]
Demo --> Exit[退出或超时]
Exit --> Cleanup[清理临时数据]
技术栈
| 层次 | 当前实现 |
|---|
| Web 后端 | Python、Flask 2.2.3、Flask-SQLAlchemy、Flask-Login、Flask-WTF |
| 数据存储 | 开发环境默认 SQLite；生产环境通过 DATABASE_URL 配置数据库，示例使用 MySQL + PyMySQL |
| AI 接口 | 智谱和 OpenAI 的可选接口；未配置密钥时，相关功能不可用 |
| 前端 | Jinja 模板、HTML/CSS/JavaScript、Bootstrap、Monaco Editor、Chart.js |
| 异步处理 | 应用内后台线程和任务队列，用于提交后的处理与能力分析 |
| 代码执行 | g++、C++17、临时工作目录、编译/运行超时和输出长度限制 |
快速开始
环境要求
- Python 3.8–3.14（Flask/Werkzeug/Flask-Session 已升级至 2.3.x/0.8.0 以支持 Python 3.14；Python 3.8–3.13 仅声明支持，未实际验证）
- C++ 评测需要可执行的 g++，并确保它在 PATH 中；
- 开发环境可以使用 SQLite，生产环境需要配置 DATABASE_URL；
- AI 引导、代码建议和部分学情分析需要智谱或 OpenAI API 密钥。
1. 安装依赖
git clone https://github.com/XiaoCow666/CodeSense.git
cd CodeSense
python -m venv .venv
Windows PowerShell：
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item .env.example .env
macOS / Linux：
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
2. 配置环境变量
编辑 .env。只想用 SQLite 开发环境时，删除或注释 DATABASE_URL：
FLASK_CONFIG=development
# SQLite 开发模式
# DATABASE_URL=mysql+pymysql://user:[email protected]:3306/codesense
# 生产环境请替换成随机密钥
SECRET_KEY=replace-with-a-random-secret
# 至少配置一个，AI 功能才会启用
ZHIPU_API_KEY=
OPENAI_API_KEY=
# 密码找回邮件（不配置时，管理员可在用户管理页生成一次性重置链接）
MAIL_SERVER=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_DEFAULT_SENDER=
APP_BASE_URL=https://codesense.example.com
开发和测试配置会在启动时创建数据库表。生产配置要显式设置 DATABASE_URL 和 SECRET_KEY；生产 WSGI 默认跳过启动期建表和迁移，首次部署或数据库结构变化后请执行 python database_maintenance.py。仓库的 update.sh 会在重启应用前自动执行这项维护。不要把 .env、API 密钥或本地数据库文件提交到 Git。
登录页同时提供学生名单注册和邮箱注册。邮箱注册不要求提前导入学生名单，账号创建后必须点击验证邮件中的链接才能登录；验证令牌只保存摘要，过期或重复发送后旧链接会自动失效。AuthIdentity 表为后续接入 Google、微信等社交登录保留统一的身份绑定位置。
3. 安装 C++ 编译器
Windows 请安装 MinGW 或 MSYS2，并把 g++ 加入 PATH。Ubuntu / Debian 可以运行：
sudo apt update
sudo apt install g++
4. 启动开发服务
python run.py
打开 http://127.0.0.1:5000/login。没有 AI 密钥时，登录、基础页面和不依赖 AI 的功能仍可用于本地检查，AI 相关操作会返回不可用或失败状态。
5. 运行测试
如果需要运行仓库测试，请额外安装测试依赖：
python -m pip install -r requirements-test.txt
python -m pytest tests -q
兼容性说明：Flask/Werkzeug 已从 2.2.3 升级至 2.3.x，Flask-Session 从 0.4.0 升级至 0.8.0，以支持 Python 3.14（ast.Str 在 3.12 废弃、Python 3.14 移除；Flask 2.3 移除了 session_cookie_name 应用属性，旧版 Flask-Session 0.4.0 依赖该属性导致初始化失败）。Flask-Session 0.8.0 使用标准的 session modified 检测机制，无需额外钩子。
- 声明支持：Python 3.8–3.14
- 已验证启动：Python 3.14.7（
python run.py 启动成功，/login 返回 200）；Python 3.8–3.13 未实际验证
- 专项回归通过：
tests/test_demo_guided_learning.py 9 个用例、tests/test_compile_error_scoring.py 4 个用例、tests/test_stage3_forum_trace.py 6 个用例；完整测试套件待执行
涉及 C++ 评测的测试需要 g++；涉及真实 AI 服务的测试还需要相应环境变量。
生产部署
生产环境至少要重新检查数据库、密钥、会话、日志、反向代理和代码执行隔离。仓库通过 wsgi:application 暴露 WSGI 对象，可按服务器环境使用 Gunicorn 或其他 WSGI 服务。
# 首次部署或数据库结构变化后执行一次
python database_maintenance.py
# 使用仓库自带配置，默认监听 127.0.0.1:5000
gunicorn -c gunicorn_config.py wsgi:application
完整的 Linux、Gunicorn、Systemd、Nginx、HTTPS、MySQL、Redis 和发布检查步骤见 DEPLOYMENT.md。
配置说明
| 变量 | 用途 |
|---|
| FLASK_CONFIG | development、testing 或 production |
| DATABASE_URL | 生产数据库连接；开发环境也可以用它覆盖 SQLite |
| DEV_DATABASE_URL | 开发环境数据库连接，不设置时使用 SQLite |
| TEST_DATABASE_URL | 测试数据库连接，不设置时使用独立 SQLite |
| SECRET_KEY | Flask 会话和签名密钥；生产环境必须设置随机值 |
| ZHIPU_API_KEY / OPENAI_API_KEY | AI 服务密钥，至少配置一个 |
| MAIL_SERVER / MAIL_PORT / MAIL_USERNAME / MAIL_PASSWORD / MAIL_DEFAULT_SENDER | 忘记密码邮件服务配置；敏感值只放服务器环境变量或受限配置文件 |
| APP_BASE_URL | 邮件和管理员重置链接使用的公开 HTTPS 地址 |
| PASSWORD_RESET_TOKEN_TTL_MINUTES / PASSWORD_RESET_REQUEST_INTERVAL_SECONDS | 重置链接有效期和重复申请冷却时间 |
| AI_PROVIDER_ORDER | 多 provider 的优先顺序，例如 zhipu,openai |
| ZHIPU_MODEL / OPENAI_MODEL | 各 provider 使用的模型 |
| AI_RETRY_ATTEMPTS | 网络错误、限流和 5xx 的最大重试次数 |
| AI_MAX_CONCURRENT_REQUESTS | 单个进程同时处理的 AI 请求上限 |
| AI_CIRCUIT_FAILURE_THRESHOLD / AI_CIRCUIT_COOLDOWN_SECONDS | provider 连续失败后的冷却条件和时长 |
| AI_SINGLEFLIGHT_WAIT_SECONDS | 相同请求合并时等待共享结果的最长时间 |
| REDIS_URL | 可选 Redis 地址，用于会话或缓存相关能力 |
| DB_POOL_SIZE / DB_MAX_OVERFLOW | 每个 Web worker 的连接池基线和溢出上限 |
| DB_POOL_TIMEOUT / DB_POOL_RECYCLE | 获取连接的最长等待时间和连接回收周期 |
| AUTO_INIT_DB / DB_ENSURE_INDEXES | 启动时是否建表和维护索引；生产建议单独执行维护脚本 |
| ASYNC_TASKS_ENABLED / ASYNC_WORKER_COUNT | 进程内任务队列的开关和线程数 |
| PRESET_SCAN_ENABLED / PRESET_SCAN_BATCH_SIZE | 预设补全扫描开关和单次扫描上限 |
| ACCESS_LOG_ENABLED / SLOW_REQUEST_MS | 应用访问日志开关和慢请求阈值 |
| STATIC_CACHE_SECONDS / ENABLE_RESPONSE_COMPRESSION | 静态资源缓存时长和响应压缩开关 |
| SECURE_COOKIES | HTTPS 生产部署应设为 true |
| TRUST_PROXY_HEADERS / PROXY_FIX_HOPS | 反向代理协议头信任开关和代理层数；当前 Nginx → Gunicorn 使用 true / 1 |
API 入口
以下是常用入口，完整路由以 routes/ 中的实现为准：
| 路径 | 方法 | 用途 |
|---|
| /api/submit | POST | 提交代码并开始评测 |
| /api/code_advice | POST | 获取代码建议 |
| /student/rebuild-learning-memory | POST | 更新当前学生的私有学习记忆 |
| /student/learning-memory/revoke | POST | 撤回当前学生的一条学习记忆来源 |
| /teacher/knowledge-focus/<knowledge_point> | GET | 查看教师可管理的针对性练习 |
| /teacher/classes/<class_id>/learning-memory-reminder | POST | 向指定班级中需要更新学习记忆的学生发送站内提醒 |
| /api/get_programming_guidance | POST | 获取编程引导 |
| /api/stream/ability-analysis | GET | 流式获取能力分析 |
| /forgot-password | GET/POST | 申请密码重置链接 |
| /reset-password | GET/POST | 使用一次性链接设置新密码 |
| /users/reset_password/<student_id> | POST | 管理员为账号生成兜底重置链接 |
| /thinking/<assignment_id> | GET | 进入三阶段引导式学习页面 |
| /thinking/api/stage1/submit | POST | 提交阶段一思路 |
| /thinking/api/stage2/verify | POST | 验证阶段二步骤组装 |
| /thinking/api/stage3/chat | POST | 进行阶段三对话 |
阶段一接口的请求示例、本地测试命令和验证边界见 STAGE1_VERIFICATION.md。
安全边界与已知限制
- 学生代码会进入受限编译和运行流程，但当前实现不是完整的恶意代码隔离系统。公网部署必须增加操作系统或容器级隔离。
- 编译器、运行时、AI 服务和数据库都可能不可用。页面应显示失败或重试状态，不能把默认文字当成真实 AI 结果。
- AI 输出可能出错。提示词约束和文本过滤不能替代程序评测、权限控制或教师复核。
- 生产环境要使用随机 SECRET_KEY、受保护的数据库凭据和安全会话配置，并限制日志、上传目录和数据库的访问权限。
- 不要在公开仓库、Issue、日志或截图中提交 API 密钥、用户隐私和生产数据库信息。
发布与版本
CodeSense 使用语义化版本号：
- MAJOR：不兼容的接口或行为变化；
- MINOR：向后兼容的功能增加；
- PATCH：向后兼容的问题修复和小幅调整。
当前正式版本是 v2.1.0。教师可在作业编辑页发布与知识点关联的学习资料，学生从知识路径和作业页阅读，AI 辅导会引用当前版本。教师更新资料会保留修改记录，撤回后学生页面和 AI 引用随即停止显示。学生可以在手机上阅读作业、提交记录与知识画像，从行动中心继续知识点练习或更新个人学习记忆；教师可以查看班级答题明细并整理作业内容；管理员可以查看反馈进度和导入结果。评测等待页会持续检查实际状态，也可以随时返回提交记录。知识记忆与知识证据用于学习参考，分数由评测流程和教师判断决定。
Star History
顶部徽章显示当前 star 数。这里没有嵌入第三方历史图，因为 GitHub 对公开 stargazers 时间线接口的限制会让 Star History 返回错误页面。等仓库自己的趋势数据生成流程准备好后，再把图放回 README。
参与贡献
欢迎通过 Issue 反馈问题或提交 Pull Request。改动请说明原因、验证方式，以及是否影响密钥、数据库或代码执行边界。默认分支的合并由项目维护者审核。
许可证
本项目采用 MIT License。
