lab-report-craft

name

lab-report-craft

description

Universal scientific lab report writing workflow for university physics and engineering experiments. Covers the full pipeline from reading experiment instructions, data review, analysis, visualization, asset collection, LaTeX report writing, to iterative proofreading against the original requirements. Use when the user needs to: (1) Write or improve a physics/engineering lab report in Chinese, (2) Process experimental data and produce publication-quality figures, (3) Fit data to physical models and compare with standard values, (4) Create LaTeX documents with ctexart class including formulas, tables, and figures, (5) Troubleshoot figure layout issues (overlapping legends, parameter boxes, etc.), (6) Ensure the report fully satisfies the experiment instruction requirements.

Lab Report Craft

通用实验报告写作工作流，适用于所有大学物理/工程实验。

核心原则：

1. 讲义驱动——实验讲义的明确要求是最高准则
2. 全局返工——发现问题时回到源头阶段重新执行，不是单步修补
3. 不确定时分级处理——阻塞级不确定必须停下来向用户确认；偏好级不确定可先给推荐默认方案并记录假设
4. 预防胜于检查——写的时候就对，不要指望审校来兜底

---

任务模式

先判断用户请求属于哪种模式，再决定执行范围：

模式	适用场景	必跑门禁
full-report	从讲义和数据生成完整实验报告	阶段0-8全部执行
final-submit	用户要求交付最终 PDF 或提交前检查	compile_report.py、check_numerical_pipeline.py --strict、audit_workflow_evidence.py、validate_report.py 全部通过
repair-only	只修编译错误、图表问题、局部文字或单个脚本	只跑与修改范围直接相关的检查；不强制教师评审
figure-only	只提取、生成或检查图片	转 PNG 后用当前 agent 可用的图像查看工具直接打开验证
audit-only	只做质量检查或提交前审阅	按用户要求选择数值、图像、编译、workflow evidence 检查

若用户没有明确要求最终提交，默认不要强制执行 final-submit 门禁；但必须说明尚未完成最终交付级验证。

---

八阶段工作流

全局返工循环：发现问题 → 回到相关阶段 → 重新流经后续所有阶段
                            ↓
阶段0 环境准备  → 确认 Python/LaTeX/字体，复制模板
阶段1 需求理解  → 读实验讲义，提取《实验要求清单》
                  【不确定时提问：处理方法？仪器型号？讲义歧义？】
阶段2 数据审阅  → 读取数据，检查质量，与讲义要求比对
                  手写数据必须多方独立验证
                  【不确定时提问：数据格式？异常值？手写识别存疑？】
阶段3 数据处理  → 按讲义要求处理；讲义未明确的，自选并记录理由
                  输出数值管线文件（params.tex）供 LaTeX 引用
                  【不确定时提问：拟合模型？误差处理？结果异常？】
阶段4 可视化    → 根据数据特点选择图表类型
                  生成后强制验证：转 PNG 后用可用图像查看工具直接查看
                  【不确定时提问：图表类型？参数框位置？】
阶段5 素材搜集  → 从常用靠谱来源搜集，规范标注版权
                  【不确定时提问：图片来源？标准值来源？】
阶段6 报告撰写  → 基于模板，按讲义要求填充
                  数值管线铁律：所有数值来自脚本输出，禁止手动输入
                  分步写作+即时自检：每段/每图写完后立即检查
                  【不确定时提问：仪器型号？样品参数？步骤细节？】
阶段7 校对迭代  → 七维排查（粗筛）+ 逐页逐图逐句检查（精筛）
                  维护 workflow_evidence.json；所有口头检查必须落到证据文件
                  【不确定时提问：数据不一致？与讲义不符？】
阶段8 最终交付  → validate_report.py + workflow evidence 门禁通过后输出 PDF

---

阶段速览

阶段0：环境准备

检查 Python（numpy, matplotlib, scipy）、LaTeX（xelatex, ctexart）、中文字体。复制 assets/template.tex 到项目目录。

阶段1：需求理解（核心）

在碰任何数据之前，先读实验讲义/指导书，提取全部要求形成《实验要求清单》：

• 实验目的、原理、装置、步骤
• 数据处理要求（讲义明确的方法：分 bin 方式、拟合模型、误差处理等）
• 思考题、报告格式要求
• 区分硬性要求（必须执行）vs 建议性描述（可自选等效方法）
• 讲义未明确时的决策：列出合理方法、分析局限性、选择最适方案、记录理由
• 关于 Origin 等商业软件：若讲义要求用 Origin 作图但环境无法安装，可用 Python matplotlib 等替代，在报告中注明。这是等效替代，不是偷工减料。

【不确定时提问】

• 讲义未明确数据处理方法 → 提供选项让用户选择
• 讲义未明确仪器型号 → 询问用户实际使用的仪器型号
• 讲义文字有歧义 → 提供两种理解让用户确认

阶段2：数据审阅

在《实验要求清单》指导下读取原始数据，检查完整性、异常值、单位一致性，与实验记录核对。

手写数据识别（高风险环节） 若原始数据为手写记录（照片/扫描件），识别后必须执行多方独立验证：

• 至少用两种独立方法（OCR + 人工逐字核对、或不同 OCR 工具交叉验证）确认关键数值
• 对易混淆字符（0↔6、1↔7、3↔8、小数点位置、正负号）重点复核
• 将识别结果与讲义/实验指导书中的预期数量级对比，判断合理性
• 任何不确定的数值必须停止处理，向用户提问确认

【不确定时提问】

• 数据格式无法自动识别 → 询问用户数据格式
• 发现异常值（负值、超量程）→ 询问用户如何处理
• 数据量与讲义描述不符 → 询问用户是否完整
• 手写数据识别存疑（字符模糊、数量级异常）→ 必须向用户展示识别结果并请求确认

阶段3：数据处理

讲义有明确要求的，严格按讲义做；讲义没说的，自行选择最佳方法并记录理由。 执行分析后输出结果文本，确保后续图框/正文/表格三处引用一致。

数值管线初始化：生成 params.tex 等 LaTeX 宏定义文件，供报告自动引用。详见 references/practical-guide.md。

【不确定时提问】

• 拟合模型不确定 → 提供候选模型让用户选择
• 拟合结果异常（负值、发散）→ 询问用户如何处理
• 多种处理方法都合理 → 提供选项让用户选择

阶段4：可视化

不强制任何图表类型。 根据数据特点选择（散点图、直方图、双面板、多子图、柱状图等）。 通用规范：参数框/图例不与数据重叠、数学符号用 LaTeX、优先矢量图（PDF）、位图 300 DPI。

生成后强制验证：将输出的 PDF/PNG 图片转换为可读格式，用当前 agent 可用的图像查看工具直接打开，确认无乱码、无重叠、无截断。不能仅通过 report PDF 的缩略图判断。

可用脚本: scripts/pdf_to_png.py

【不确定时处理】

• 图表类型会影响结论表达 → 提供选项让用户选择
• 仅为展示偏好 → 先选择最清晰方案并记录理由
• 参数框位置可能重叠 → 先自动避障；仍不确定时再提问

阶段5：素材搜集

从常用靠谱来源（权威机构教育页、PDG/CODATA/NIST、学术搜索引擎等）搜集原理图和标准值。 所有外部图片标注来源，标准值给出完整引用。

截图/裁剪硬性规范（严禁违反）：

1. 只裁剪图本身，严禁包含任何正文段落、公式、页眉页脚、页码等无关文字
2. 从 PDF/论文截图时，必须用图像分析方法（连通区域检测、边缘检测等）精确提取 figure 区域
3. 裁剪后必须人工/工具验证：图中是否混入了不属于该图的文字？是否有截断的公式？
4. 如无法获得干净的独立图，宁可不用该图，换来源或向用户说明

可用脚本: scripts/extract_figures_from_pdf.py（提取嵌入图片 + 页面裁剪 + 透明通道处理）

【不确定时提问】

• 原理图来源不确定 → 询问用户是否有指定来源
• 标准值引用来源不确定 → 提供候选来源让用户选择

阶段6：报告撰写

核心原则：写的时候就对，不要指望审校来兜底。

数值管线原则（铁律）

正文中出现的每一个数值，必须来自脚本输出的唯一来源。 通过 \input{results/params.tex} 或 \newcommand 自动填充，严禁手动输入任何数值。

可用脚本: scripts/check_numerical_pipeline.py（扫描手动输入数值，与 params.tex 交叉验证）

分步写作 + 即时自检

不要一次性写完所有内容再检查。每写完一个模块，立即执行自检：

每插入一张图后 → 执行"逐图自检清单"（来源检查 + 渲染检查 + 引用检查）

每写完一个数据段落/表格后 → 执行"数值一致性检查"

每写完一个原理段落/公式后 → 执行"符号一致性检查"

每写完结论后 → 执行"结论自洽性检查"

详见 references/checklist.md 第一节。

【不确定时提问】

• 仪器型号与讲义不一致 → 询问用户以哪个为准
• 样品参数在多个来源不一致 → 询问用户确认
• 实验步骤细节与讲义有出入 → 询问用户以哪个为准

阶段7：校对迭代

七维排查是粗筛，逐页逐图逐句检查是精筛。必须全部执行，不能跳过。

可用脚本: scripts/validate_report.py（一键检查图片存在性 + 数值管线 + 编译测试 + workflow evidence 门禁）

7.0 Workflow evidence 门禁

在阶段7开始前创建 results/workflow_evidence.json：

python3 scripts/audit_workflow_evidence.py --init report.tex

每完成一个阶段，更新 workflow_evidence.json 中对应 stage_evidence，并指向实际证据文件（如 results/requirements_checklist.md、results/data_review.md、reviews/self_review.md、reviews/teacher_review.md）。禁止只写"已检查"而没有文件证据。

阶段8前必须通过：

python3 scripts/audit_workflow_evidence.py report.tex
python3 scripts/validate_report.py report.tex

7.1 七维排查（快速扫描）

数据一致性、讲义符合性、措辞规范、排版质量、图表质量、逐页检查、参考文献。

7.2 逐页检查（对每一页执行）

检查页码连续性、章节编号正确性、内容完整性、排版细节。

7.3 逐图检查（对每一个图执行）

必须直接查看图片文件（PDF 先转 PNG，再用当前 agent 可用的图像查看工具打开），不能仅看 PDF 缩略图。 检查来源合法性、渲染质量（无乱码/重叠/截断）、与正文一致性、物理正确性。

7.4 逐句检查（对关键段落执行）

对摘要、结论、数据处理结果、标准值对比、思考题答案逐句审查：

• 每个数值能否追溯到脚本输出的唯一来源？
• 物理量符号是否与全文一致？
• 物理论断是否有数据支撑？
• 是否存在过度推断？
• 引用是否正确？

特别关注高危表述："这说明...""与理论值一致""误差很小""如图X所示""根据文献[3]"

7.5 数值一致性自动扫描

维护《数值来源表》，逐条核对每个数值在图/正文/表格/结论中是否一致。

详见 references/checklist.md。

阶段7.5：独立教师批改（多轮交叉审核）

必须执行，不可跳过。 由独立的 Agent/子任务扮演"教师"角色进行评审：

• 严格隔离上下文：教师评审时只能看到最终报告、实验讲义要求、数据处理结果，不能看到中间过程或代码细节
• 评审 Agent 必须执行的操作：
  1. 逐页浏览 PDF
  2. 每个图单独查看（逐一检查渲染质量）
  3. 逐句精读摘要和结论
  4. 随机抽查数值，交叉验证一致性
  5. 审查"说明""反映""证明"等强论断是否有数据支撑
• 审核重点：讲义硬性要求是否全部满足、数据计算结果是否自洽、实验结论是否过推断、物理量符号是否混用、图与 caption 是否一致、截图质量、图表渲染质量
• 多轮重复审核：鼓励使用多个独立教师 Agent 交叉审核，每轮发现的问题必须全部修正后再进入下一轮
• Origin 等商业软件：讲义若要求用 Origin 作图，但环境无法安装，可用 matplotlib 等效替代，在报告中明确说明即可。教师审核不应以此扣分

【不确定时提问】

• 发现数据不一致 → 询问用户以哪个为准
• 发现与讲义要求不符 → 询问用户如何修改

阶段8：最终交付

只有在以下检查全部通过后才能输出最终 PDF：

• compile_report.py 编译成功
• check_numerical_pipeline.py 无高风险手动数值
• audit_workflow_evidence.py 通过，确认八阶段证据、逐图直接查看、未解决问题清零、教师评审关闭
• validate_report.py 通过

可用脚本: scripts/compile_report.py（自动多次编译直到交叉引用稳定，格式化错误/警告输出）

---

不确定时提问规则

阻塞级必须提问的场景（严禁自行决定）：

• 仪器型号与讲义不一致
• 讲义未明确数据处理方法
• 数据出现异常值
• 样品参数在多个来源不一致
• 发现数据不一致
• 手写数据识别存疑
• 任何与实验讲义有出入的地方

偏好级可先默认处理的场景：

• 图表类型不确定但讲义无硬性要求：选择最清晰的图表类型，在报告或记录中说明理由
• 参数框/图例位置不确定：先自动避障，若仍可能遮挡再询问
• 参考图片来源有多个可接受候选：优先讲义/课程材料，其次权威机构或教材来源，并记录来源

提问模板要求：

1. 清楚说明为什么需要提问
2. 提供 2-4 个明确选项
3. 给出推荐选项（基于物理合理性）
4. 允许"其他"自定义输入

详见 references/ask-user-guide.md。

---

快速资源索引

文件	内容	何时读取
assets/template.tex	通用 ctexart 实验报告 LaTeX 模板	阶段6
scripts/audit_workflow_evidence.py	八阶段证据门禁，约束 agent 不能跳过逐图/教师评审/用户确认	阶段7/8
references/workflow.md	八阶段工作流详解 + 所有提问触发点模板	全程
references/checklist.md	写作自检 + 七维排查 + 逐页逐图逐句 + 教师评审	阶段6/7
references/practical-guide.md	数据处理 + 可视化 + LaTeX排版 + 素材搜集 + 手写识别	阶段2-6
references/ask-user-guide.md	不确定时提问指南（触发条件+提问模板）	遇到不确定时