docs: 新增单一正式项目理解文档 project-understanding_wjh.md

[Swan1127]

变更说明（按复审意见整改后）

根据首轮复审意见（PR 描述与实际 diff 不符、diff 误删主干已有的 PROJECT_UNDERSTANDING.md、且新增了两份内容相同的文档），本 PR 已完成整改，现在相对主干仅存在单一正式文档变更：

Files changed（相对主干 XiaoCow666/CodeSense:main @ eba0cbe）

• 新增 project-understanding_wjh.md（+288 行，无删除）—— 唯一新增的项目理解文档。

针对复审意见的整改说明

1. 恢复主干已有内容：PROJECT_UNDERSTANDING.md 已按主干原样恢复（blob 与主干完全一致），本 PR 的 diff 中不再出现对该文件的删除。
2. 移除重复文档：删除了与 project-understanding_wjh.md 逐字重复、且主干中并不存在的 project-understanding.md，最终只保留一份新增文档。
3. PR 描述如实反映 diff：本次实际变更即上表所列的新增一个文件，无其他代码或文档改动。

文档内容概述

• 以个人学习视角整理的 CodeSense 项目理解记录（含架构、数据模型、AI/沙箱机制等结论），其中正文以【源码确认 / 源码推断 / 运行验证】标注结论证据强度（附源码位置与 HEAD SHA），并在附录 B 澄清运行验证范围与未覆盖事项，附录 A 记录个人设想，附录 B 记录本人实际运行与测试的验证过程。
• 纯文档改动，不含业务代码、数据模型或运行逻辑修改。

验证记录

• 文档附录 B 记录了本人在本机实际执行的验证：sandbox 特性测试（3 passed + 5 passed）、真实 g++ 16.1.0 编译运行（3/3 passed）、python run.py 可正常启动。

恳请复审，谢谢。

[XiaoCow666]

复审当前 head dab5f0603813856ce9b619b6777d1deefe3594a7，结论：Request changes。

1. 实际 diff 与 PR 描述不一致：PR 描述写的是“仅新增 project-understanding_wjh.md”，但当前变更实际包含：删除主干已有的 PROJECT_UNDERSTANDING.md，新增 project-understanding.md，再新增 project-understanding_wjh.md。请按实际变更修正 PR 描述，并说明是否确实要删除主干维护文档。

2. 出现两份内容完全相同的文档：project-understanding.md 与 project-understanding_wjh.md 当前内容和 blob 大小一致。请只保留一个正式交付文件，并更新/替换主干已有文档；不要把同一份项目理解文档以多个文件名提交。

3. 请避免删除已有项目接管文档：目标 main 的 PROJECT_UNDERSTANDING.md 是现有维护文档。除非有明确迁移理由、完整保留原有有效内容并在 PR 描述中说明，否则应直接修改该文件，或采用一个不重复且不破坏现有入口的新增路径。

文档中对前轮评审意见的修正和验证范围收窄方向可以保留。完成文件整理、PR 描述修正后，请在同一个主仓库 PR 上重新请求复审。

[XiaoCow666]

仅依据提供的 diff 审查，未执行命令或核验仓库源码。以下为非阻塞文档问题，按优先级排序：

1. [P3] 第四部分「核心子系统」第 3 项：异步行为描述范围过大。「提交后不阻塞请求，任务由线程池执行」与第三部分明确列出的同步 POST /api/submit 路径矛盾。影响：读者可能错误判断 API 的响应时延及超时处理要求。建议限定为「网页表单提交路径异步执行」，并注明 API 提交路径同步返回评测结果。

2. [P3] 附录 B「安装」第 1 项：ast.Str 移除版本有误。 文中称其在 Python 3.12+ 被移除；实际移除版本是 Python 3.14，3.12、3.13 仍保留该兼容类。影响：会把本机的 3.14 兼容性问题错误推广到其他版本，误导环境选择。建议改为「本机 Python 3.14 环境出现该错误，切换 3.11 后恢复」，并仅在有异常堆栈支持时明确归因于 Werkzeug。

[Swan1127]

已按复审意见完成整改：

1. 恢复主干已有内容：PROJECT_UNDERSTANDING.md 已按主干原样恢复（blob 与主干一致），diff 中不再删除该文件。
2. 移除重复文档：删除了与 project-understanding_wjh.md 逐字相同且主干不存在的 project-understanding.md。
3. 修正 PR 描述：标题与正文已更新，如实列出变更。

当前相对主干的实际 diff 仅一项：新增 project-understanding_wjh.md（+288，无删除）。

恳请复审，谢谢。

[Swan1127]

感谢复审，两条 P3 意见均已修正并推送（HEAD 22f93d4）：

1. 异步范围表述：第四部分「核心子系统」第 3 项已限定为网页表单提交路径（POST /submit/<assignment_id> 异步、后台线程池），并注明 POST /api/submit API 路径为同步评测、直接 JSON 返回结果，同时指向第三部分三.2 的 A/B 两条通路，消除歧义。

2. Python 版本表述：附录 B 已改为 ast.Str（及 ast.Num/ast.Bytes/ast.NameConstant/ast.Ellipsis）自 Python 3.8 弃用、到 Python 3.14 才移除，3.12/3.13 仍保留兼容类。Werkzeug 归因已在本机 Python 3.14.3 复现验证（报错堆栈指向 werkzeug/routing/rules.py::_compile_builder），并注明改用 Python 3.11 虚拟环境后恢复。

diff 仍仅为新增 project-understanding_wjh.md 这一份文档的修订，请查收，谢谢。

[XiaoCow666]

提供的 diff 仅新增 project-understanding_wjh.md，未见删除原有文档或新增第二份文件，前轮关于变更范围的问题已解决。

• P3：正文未落实信息可信度标注。 PR 描述称正文区分“已确认 / 推测 / 未知待验证”，但第三节直接断言“实际网络请求统一委托 SharedLLMClient”“绝不写正式库”，未注明确认依据；附录 B 的验证范围也未覆盖这些结论。影响：读者难以区分源码分析结论与实际运行验证，可能高估隔离机制的验证程度。建议为这些结论补充类别、对应源码位置和所依据的提交 SHA；未经验证的部分明确标为待验证。

本次仅审阅所给元数据与 diff，未执行命令或测试，无法独立确认源码行为及附录中的运行结果。

[XiaoCow666]

• P3：源码基线与当前 PR 元数据不一致（project-understanding_wjh.md:3，以及正文、附录 B 中重复的基线说明）。文档把 22f93d4 同时称为“main HEAD”和“PR #14 当前 head”，但提供的 PR 元数据中 head 为 d18243aaaefdd29b22b39919a80d2d459ad49a2a。这会使读者无法准确区分历史核对版本与本次提交，影响“源码确认”结论的追溯。建议将实际核对过的提交明确标为固定的“源码核对基线”，删除“当前 head”等易过期且已不一致的表述，并统一全文引用；不要仅替换 SHA 就声称完成了重新核对。

本次仅依据提供的元数据和 diff 审查；未发现可由这些材料直接确认的阻断性问题。

[Swan1127]

已按 P3 意见补充结论标注并推送（HEAD d18243a）：

1. 文档开头新增“结论标注约定”，统一用**【源码确认 / 源码推断 / 运行验证】**三级标注证据强度，并注明默认源码基线（本仓库 main HEAD SHA 与 PR 对应关系）。
2. 对指出的两处正文断言补充类别/源码位置/SHA/验证状态：
   • “AI 实际网络请求统一委托 SharedLLMClient”→ 标注【源码确认】：依据 utils/llm_evaluator.py::LLMEvaluator（_chat_completions_create 委托 services/llm_client.py::SharedLLMClient；_init_client 仍在旧模块完成初始化与选型），并注明未经真实 AI 请求运行验证。
   • “公开体验绝不写正式库”→ 标注【源码确认】：依据 services/demo_database.py（activate_demo_run / activate_demo_request_database 临时库切换）与 tasks/submission_tasks.py::evaluate_submission_async（docstring：demo_run_id 为空才用正式库、线程内二次校验会话存活），并注明配套 tests/test_demo_* 用例未在附录 B 复跑、运行级验证待补。
3. 附录 B 新增“范围澄清”：明确本附录的运行验证仅覆盖沙箱特性 3 项、沙箱输出限制 5 项、真实 g++ 编译运行 3 例与 python run.py 启动；上述两处结论属源码静态分析，勿视为已实跑确认。
4. PR 描述措辞已同步为【源码确认 / 源码推断 / 运行验证】。

仍为纯文档改动（仅 project-understanding_wjh.md），Files changed 不变，请查收。

[XiaoCow666]

复审当前 head d18243a：文档仍把 22f93d4 写成默认 main HEAD/当前 head，且 PR 描述把基线写成 �ba0cbe；实际 main 当前为 950c233，PR head 为 d18243a。请把源码基线、PR head 和验证提交分开并改为实际 SHA，避免接管者按错误提交复核。修正后再申请复审。其余文档范围问题暂未发现新的阻塞项。

[XiaoCow666]

仅依据所提供的元数据和 diff，未发现需要阻止合并的问题；diff 确实仅新增一份文档，未出现删除主干文档或新增重复文件的变更。未调用工具，也未独立验证源码及运行记录。

• P3｜证据强度标注未完整落实（project-understanding_wjh.md 文首、第三节“失败可见性”、第四节“安全/运维要点”）：文首承诺机制性结论统一标注证据强度，但“AI/沙箱失败在体验中一律置 failed”“后端与日志不再回显完整异常及堆栈”等断言没有对应标注和具体函数位置。影响：读者无法区分已逐行核对的行为与基于调用关系的推断，尤其容易把“一律”等绝对表述当作全面保证。建议：为这些结论补充【源码确认／源码推断】及具体函数位置，并将适用范围限定到实际核对的路径；无需为本次文档变更额外执行测试。

[XiaoCow666]

复审当前 head：变更仅新增单一项目理解文档，无运行时代码、配置、数据、权限或部署改动；前轮关于重复文档、删除主干文件和基线表述的阻塞问题已处理。文首证据标注仍可继续细化，但属于非阻塞文档改进，批准合并。