新增 project-understanding.md 文档

[Swan1127]

No description provided.

[XiaoCow666]

谢谢，文档覆盖面很完整，但当前需要修改后再合入：

1. utils/code_evaluator.py 仍通过 utils/llm_evaluator.py 构造评估器；而 utils/llm_evaluator.py 仍保留 provider client 的初始化逻辑。请把 AI 调用链按真实代码写清楚，区分“业务调用最终走 SharedLLMClient”与“旧评估器/客户端初始化仍存在”，不要把架构表述成已经完全收敛。

2. 文档中关于 code_evaluator.py 使用 CodeBERT + TextCNN 的表述与当前仓库不一致。当前标准版 requirements 不依赖 torch/transformers，评分代码是启发式评分 + 可选 LLM 评估。请删除或标注为历史实现，并给出当前代码定位。

3. 请补充可复核证据：关键结论尽量引用当前仓库的相对路径、函数名和提交中的稳定定位；不要使用本机 file:/// 路径。事实、推断、建议继续分开。

4. 这是阶段一文档 PR，请将同一内容以正式 PR 提交到 XiaoCow666/CodeSense 的 main。当前任务记录指向的是 xjx-star/CodeSense#1，它不是主仓库 PR，无法按项目主流程验收。

文档整体方向可以保留；完成以上修改并推送到主仓库 PR 后，我会复审。

[Swan1127]

已按评审意见完成三项修订：

1. 区分 SharedLLMClient 调用链与旧 LLMEvaluator 的 provider 客户端初始化；
2. 删除 CodeBERT + TextCNN 表述，标注为历史实现；
3. 全文改用相对路径 + 函数名引用，去除 file:/// 与本机绝对路径。
   请重新评审，谢谢。

[XiaoCow666]

复审提交 a53d595（PR #7），结论：Request changes。

1. PR description 目前为空，未满足阶段一 PR 的验收门槛。请在 PR body 中明确写出：使用过的 AI 工具、实际阅读范围（仓库相对路径/函数名）、验证命令及结果、未验证事项与风险。文档附录不能替代 PR body。

2. 测试结论需要收窄或补充证据。文档称 python -m pytest tests/test_sandbox_features.py -q 的 3 passed 证明 C++ 编译执行链路可正常使用，但当前 main 的 tests/test_sandbox_features.py 实际断言的是演示数据播种、登录流程和生产环境禁用沙箱，并没有调用 g++ 编译/运行。请改成测试实际证明的结论，或补充真实 C++ 编译/运行命令及输出证据；同时区分 tests/test_sandbox_output_limits.py 的有界进程输出测试与完整 g++ 集成验证。

此前提出的四项已核对：SharedLLMClient 与旧 LLMEvaluator 的边界已说明，CodeBERT/TextCNN 已标为历史实现，引用已改为仓库相对路径，PR 目标也已是 XiaoCow666/CodeSense 的 main。修正以上两点后请再次请求复审。

[XiaoCow666]

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

1. PR description 仍为空（阻塞验收）：阶段一任务要求在 PR body 中写明 AI 工具/模型、实际阅读范围（仓库相对路径与函数名）、验证命令及结果、未验证事项与风险。当前这些内容只写在新增文档的附录中，不能替代 PR body；请补齐后再次请求复审。

2. 新增文件与主干现有文件发生仅大小写冲突（阻塞合入）：目标 main 已存在 PROJECT_UNDERSTANDING.md，本 PR 新增 project-understanding.md，两者只是大小写不同且主题重复。GitHub 的 Linux 文件系统可以同时保存，但 Windows 等大小写不敏感环境会产生 checkout/构建冲突。请改为更新主干现有文件，或改成语义明确且不与现有文件冲突的文件名，并说明是否需要保留两份文档。

3. 附录中的 g++ 结果可以作为本机手工 smoke test，但请明确它不是仓库中的自动化回归测试，也不要把 3/3 表述成完整 Web 提交链路或 CI 通过；最好保留可复现的命令、源码/测试数据范围和环境限制。

文档主体的架构梳理和前两轮意见的修正方向可以保留。完成以上修改后，请在同一个主仓库 PR 上重新请求复审。

[XiaoCow666]

• P3：Python 兼容性说明的版本边界有误（project-understanding.md，附录 B「安装」第 1 项）。文中称 ast.Str 在 Python 3.12+ 被移除；实际是 Python 3.14 移除，3.12 和 3.13 仍保留该兼容类。影响：读者可能据此误判 Python 3.12/3.13 的兼容性并进行不必要的降级。建议改为“本机 Python 3.14 环境因依赖访问已移除的 ast.Str 而启动失败，切换 Python 3.11 后恢复”，并避免推断未验证版本的兼容性。

本次仅审阅所提供的元数据和 diff，未执行任何命令或测试，也未核实文中调用链与仓库实现是否一致。未发现可由该 diff 确认的阻塞问题。

[XiaoCow666]

按“宽进严禁”复审：本 PR 只新增项目理解文档，不修改运行代码、权限、数据、部署或依赖，没有发现恶意或破坏性内容，现有文档内容足以作为阶段性交付，批准合并。

后续建议（不阻塞本次合并）：继续把事实、推断和个人设想分栏维护；涉及旧链路、Python 版本和 AI 调用链时，以当前 main 实际代码为准持续校正。