[WIP] Improve clarity and structure of experiment quality report

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

实验质量改进报告

1. 文档/指导书问题

高频痛点汇总

• 任务描述不清晰、结构混乱：大量学生反馈文档难以理解，需要反复阅读。任务目标不明确，特别是任务二和任务六。文档更新后有所改善，但初始版本问题严重。
• 关键实现细节缺失：
  • 重定位计算：R_X86_64_64、R_X86_64_PC32等类型的计算公式、addend值的处理、是否需要pushback或直接赋值等细节说明不足。
  • 符号处理：强/弱符号冲突规则、局部符号与全局符号重名处理、未定义符号在符号表中的形态等描述不够。
  • 段合并与对齐：任务二未明确说明合并后需要4KB对齐，导致初期实现错误。段合并的具体规则（按类别合并还是按名称合并）不清晰。
  • 输出文件格式：未明确说明最终可执行文件（program）中必须清空relocs和symbols，导致许多学生被长时间卡住。
• 调试指南不足：虽然提供了readfle等工具，但使用方法、示例、常见错误分析不够详细。学生普遍反映调试困难，不知如何定位问题。
• 任务与框架代码对应性差：文档的理论描述与ld.cpp中的函数、fle.hpp中的数据结构关联性弱，学生不知道代码该写在哪里，如何利用现有结构。
• 示例与案例过少：缺乏从源代码（.cpp）到目标文件（.fle）再到可执行文件（program）的完整示例，特别是重定位计算、符号解析的具体案例。

改进建议

1. 重构文档结构：为每个任务（特别是任务二、六）提供清晰、分点的检查清单，明确列出必须完成的步骤和输出要求。
2. 补充关键细节：在文档中加粗或单独设立“重要提示”框，强调以下内容：
   • 最终program必须清空relocs和symbols。
   • 段合并后必须进行4KB对齐。
   • 重定位信息是覆盖写入而非追加。
   • 注意处理特殊命名的节（如.text.startup, .rodata.str）。
3. 增强调试支持：编写一份独立的、详细的调试手册。包含：
   • readfle、disasm、std::cerr输出日志的详细使用示例。
   • 常见错误信息（如return code ***）的可能原因和排查步骤。
   • 如何利用build/目录下的program文件进行对比调试。
4. 提供完整示例：增加一个从简单C程序到最终链接结果的完整工作流示例，展示每个中间步骤的数据结构变化，特别是符号表和重定位表。
5. 建立文档-代码映射：在ld.cpp的函数注释中，明确引用对应的文档章节和任务编号，增强指导的针对性。

2. 工具/环境问题

高频痛点汇总

• 调试工具信息不足且难用：disasm工具在任务六之前几乎无用。报错信息过于简略（如仅提示return code），难以定位错误。缺乏像断点、单步调试这样的直观手段。
• 测试框架与评测体验问题：
  • 测试点与任务要求不完全匹配（例如，任务二的测试未覆盖Local符号重定位，问题在任务三才暴露）。
  • 测试脚本报错信息不友好，程序崩溃时难以定位。
  • 存在个别测试用例（如11-bss-link）通过率低，且错误信息奇怪（SIGSEGV）。
• 环境配置复杂：部分学生反映Python版本要求（实际需要3.12）与文档说明不符，在WSL或Mac上配置环境困难，依赖安装出现问题。
• 框架代码接口设计小瑕疵：PHF::R | PHF::X的写法在C++枚举类中不合法，需要类型转换。FLESection等结构体成员设计（如缺少name）给使用带来不便。

改进建议

1. 强化调试工具链：
   • 改进disasm工具，使其能解析任务1-5生成的.load段内容。
   • 在评测脚本中增加更详细的错误输出，例如指出哪个测试用例失败、可能的数据结构差异。
   • 官方推荐并演示使用std::cerr输出关键数据结构进行日志调试的方法。
2. 优化测试用例设计：
   • 确保每个任务的测试点能充分覆盖该任务的核心要求，避免bug被隐藏到后续任务。
   • 为每个测试用例提供简单的说明，指出其测试重点。
   • 检查并修复11-bss-link等疑难测试点。
3. 明确环境要求与配置指南：
   • 在README.md开头明确列出所有依赖及准确版本（如Python 3.12+）。
   • 提供针对Windows(WSL2)、macOS、Linux的详细环境配置和问题排查指南。
   • 将rich、tomli等Python依赖写入requirements.txt。
4. 修复框架代码细节：修正PHF枚举类的使用方式，或提供合法的操作示例。考虑完善FLESection等结构体的成员，使其更易用。

3. 难度/设计合理性

高频痛点汇总

• 实验整体难度与工作量严重超出预期：绝大多数学生反馈实际耗时（20-50小时）远超建议时间（7-15小时）。实验被认为“难度偏高”、“工作量巨大”。
• 任务六（节分离）设计存在结构性矛盾：这是最高频、最强烈的痛点。任务1-5将所有段合并到.load段，而任务六要求分离为四个段（.text, .rodata, .data, .bss），导致学生几乎需要完全重写或大幅重构前期代码，造成极大的挫折感和时间浪费。
• 难度曲线不合理：任务二（合并与重定位）作为第一个编码任务，难度陡升，学生同时面临理解框架、设计数据结构、实现复杂逻辑的多重挑战。任务三、四、五相对平缓，而任务六又出现第二个难度高峰。
• “向后兼容”痛苦：完成新任务后，之前通过的测试经常失败，调试过程（“找之前为什么错了”）非常耗时且令人沮丧。
• 对C++/STL不熟悉的学生不友好：实验需要熟练使用C++标准库和面向对象编程，对未修读相关课程或基础薄弱的学生构成很高门槛。

改进建议

1. 重构任务顺序与设计（最关键）：
   • 方案A（推荐）：放弃“先合并到.load，再分离”的设计。从任务二开始，就直接引导学生处理多个段（.text, .rodata, .data, .bss）。任务六可以调整为处理更高级的特性（如静态库、共享库简化版，或更复杂的内存布局）。
   • 方案B：如果保留现有结构，必须将任务六的要求提前至任务一开始明确告知，让学生在设计数据结构和算法时预先考虑多段情况，避免后期重构。
2. 平滑难度曲线：
   • 在任务一和任务二之间，增加一个过渡性任务（如1.5），以“代码填空”形式提供一个极简的链接器伪代码框架，帮助学生建立整体流程概念。
   • 将庞大的任务二、任务六拆解为多个逻辑连续的子任务，并提供每个子任务完成后的中间状态示例。
3. 提供更多脚手架代码：在ld.cpp中为每个任务提供更丰富的函数框架和注释，特别是任务二的入口函数。明确每个步骤需要操作的数据结构。
4. 调整实验布置时间：建议避开期末周，为学生预留更充足的连续时间。

4. 其他建议

汇总

• 提供参考实现或标准答案：许多学生希望获得部分或全部任务完成后生成的正确program文件，用于对比调试。
• 增强框架代码注释：对fle.hpp、fle.cpp中的关键数据结构（FLEObject, Symbol, Relocation）和函数提供更详细的中文注释，解释其字段含义和相互关系。
• 统一命名规范：统一类名前缀（如都使用FLE开头）。
• 增加可视化辅助：在文档中增加链接过程（特别是内存布局、段合并、重定位计算）的流程图或示意图。
• 明确实验与课程理论的衔接：在文档开头简要说明本实验如何对应课程中讲解的链接器知识点，降低脱节感。

改进建议

1. 发布“参考答案”：可以为每个任务提供1-2个简单测试用例对应的正确program文件（JSON格式），放在reference/目录下，供学生调试时参考。
2. 组织框架代码导读：在实验开始前，通过一个简短的视频或图文指南，带领学生快速浏览fle.hpp和fle.cpp，解释核心数据结构的设计意图和关联。
3. 采纳合理建议：逐步统一代码风格，增加必要的图表，并在文档中建立与课程理论的明确链接。

---

报告总结：本次实验的核心问题集中在任务设计的结构性矛盾（尤其是任务六）、关键文档细节的缺失以及调试支持的薄弱。改进应优先解决任务顺序重构、补充明确的关键实现规则、并提供强大的调试指引，以降低不必要的认知负荷和调试成本，使学生能将精力更多集中于理解链接器原理本身。

附录：原始反馈记录

【学生 linklab-2024-ApiecePHweiweixu】:
实验难度偏难，花了readme预计时间还多两天
框架可以给的再全面一点

【学生 linklab-2024-gatzby-git】:
实验文档中关于符号表遍历和链接器实现的描述不够清晰，导致实现时对符号类型判断和段合并的具体规则理解困难。
初始代码将所有段合并到.load段并设置RWX权限，这种简化处理与真实链接器的段分离和权限设置不符，可能导致后续实验理解偏差。
实现符号冲突检测时，对“强符号优先原则”和“跨文件同名符号解析”的具体规则缺乏明确说明，增加了调试难度。
处理64位地址重定位时，实验文档未明确说明R_X86_64_64类型重定位的具体计算方式和可能存在的整数溢出问题。
分离代码和数据段时，实验文档未详细说明如何根据段前缀进行匹配和设置不同权限，导致实现时对齐和权限设置容易出错。

【学生 linklab-2024-greatganyuandsth】:
实验框架代码过少，建议在ld.cpp中为四个步骤都提供框架代码。
部分情况下，最后一个测试用例出现异常，满分仅为3.5分，导致总分只有113.5分。

【学生 linklab-2024-whisperLyx】:
实验文档可以增加更多实际案例，特别是重定位计算的具体示例。
实验文档可以在前面部分描述调试技巧和常见错误处理方法，可能会更清晰易懂。
任务二的文档部分结构不是特别清晰，在实现这部分时遇到了困难，希望能补充完善文档的任务二部分。
框架代码如果再有一个fle.hpp的解释文档可能会更好。

【学生 linklab-2024-TheSkyFuker54188】:
实验初期较难入手，没有明确的思路指引，接口繁杂，单一方向的尝试容易陷入死胡同。
报告的要求不够明确，写作时需要反复推敲才能确定内容是否符合预期。
建议可以提供一些参考实现的框架（可以隐去核心逻辑），帮助学生更快理解要求。

【学生 linklab-2024-sqyhj】:
实验文档在一些细节（例如符号冲突处理的具体实现）上可以进一步补充更多的解释
框架代码在某些部分（如符号表的合并...

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.