Lab Report Writer

Lab Report Writer — 期刊风格实验报告撰写 Skill

概览

本skill覆盖四类场景：理工科实验课、科研论文级记录、工程技术报告、竞赛展示报告。

核心流程：信息采集 → 文献搜索 → Python自动验证 → 撰写结构化内容 → 生成HTML报告

---

第一步：信息采集与场景识别

识别场景类型

| 场景 | 典型特征 | 报告侧重 | |------|----------|----------| | 实验课报告 | 有实验目的、操作步骤、数据表格 | 规范结构、误差分析、结论 | | 科研记录 | 有假设、方法对比、统计分析 | 方法严谨性、数据可重复性 | | 工程技术报告 | 有设计参数、测试标准、性能指标 | 工程可行性、指标达标情况 | | 竞赛展示 | 有创新点、视觉冲击需求 | 清晰叙事、高质量图表 |

必须从用户处收集的信息

最小信息集（必须有）：

• 实验/项目标题
• 实验目的或研究问题
• 实验方法或操作步骤（文字描述即可）
• 主要结果（数据或文字描述）

增强信息（有则收集）：

• 原始数据表格（CSV、手工记录等）
• 计算公式和推导过程
• 参考文献列表
• 实验装置或流程图描述
• 误差来源分析
• 作者、机构、日期等元数据

信息不完整时的处理策略

• 数据缺失：跳过图表，用文字表述结果，在报告中标注"[图表：数据待补充]"
• 公式缺失：根据领域知识推断，并在报告中说明假设
• 参考文献缺失：生成报告，提醒用户补充
• 元数据缺失：使用占位符（如"[作者姓名]"、"[日期]"）

---

第一步（补）：生成前确认选项

完成信息采集、场景识别后，在开始任何生成之前，必须调用 ask_user_input 工具向用户确认核心选项（用自然语言简短说明后紧接着调用工具，不要纯文字罗列）。该工具单次最多 3 个问题，因此只询问下表 3 个核心问题；其余两项按默认执行，并在调用前一句话告知"默认仅 HTML、不启用内联编辑，如需更改可直接说明"。

| 问题（类型） | 选项 | 默认 | 变量 → 影响 | |---|---|---|---| | 文档模式 (single) | 长文档（分章节，推荐）/ 单文件 | 长文档 | MODE_LONG：false→单文件 report-body.html+--body | | 可视化内容 (multi) | SVG 流程图 / Chart.js 图表 | 全选 | NEED_SVG/NEED_CHART：false→跳过对应文件与占位符 | | 报告色彩主题 (single) | 暖墨纸/午夜藏青/净白简约/橄榄学报/砖红工程/石墨极简 | 暖墨纸 | THEME：非默认→加 --theme |

默认项（不询问，用户主动要求才启用）： 附加输出默认仅 HTML（要 Markdown 草稿 → NEED_MD=true，另出 .md 一同 present_files）；HTML 内联编辑默认关闭（要编辑 → EDITABLE=true，加 --editable）。

> 数据验证跳过（无任何数值）时，build_html.py 另加 --no-verify-panel。

主题映射与注入

主题 CSS 完全由 build_html.py 的 --theme 参数处理，Claude 无需读取或内联任何 CSS。THEME=default 时省略该参数，否则加 --theme 。

| 用户选项 | --theme | | 用户选项 | --theme | |---|---|---|---|---| | 暖墨纸（默认） | 省略 | | 橄榄学报 | olive | | 午夜藏青（深色） | dark | | 砖红工程 | engineering | | 净白简约 | clean | | 石墨极简 | graphite |

> 用户在 ask_user_input 之前已指定主题时，"报告色彩主题"一题的默认高亮改为对应项。完整主题注入说明见 references/html-build-guide.md；仅自定义非预置风格时才读 style-constitution.md。

---

第二步：Python数据自动验证

触发判断

| 情形 | 操作 | |------|------| | 用户上传CSV文件 | 调用 scripts/auto_verify.py 自动解析并验证 | | 用户粘贴表格数据（Markdown表格/空格分隔/逗号分隔） | 写入临时CSV，同上处理 | | 用户提供了具体数值和公式 | 生成专项验证脚本并运行 | | 用户只有文字描述、无任何数值 | 跳过Python验证，在 build_html.py 命令中添加 --no-verify-panel（不渲染验证面板） |

自动验证流程（CSV/表格数据）

运行 scripts/auto_verify.py （可加 --claims "产率=74.35" 对比用户声明值）。脚本依次：读取并检测分隔符 → 统计摘要（均值/标准差/RSD/极值）→ 数据规范自检（小数位/有效数字一致性、样本量、SD vs SEM、疑似异常值>3σ仅标记、百分比合计，⚠/ℹ/✓）→ 关键词匹配已知计算模式并验证 → 偏差核查（标记 >1%）。验证深度随数据量自动调（50 深度含相关性分析）。

脚本自动识别的计算模式（产率、相对误差、欧姆定律、功率、速率等）见 auto_verify.py 的 PATTERNS；无法匹配时仅输出统计摘要，不强行推断。

验证摘要放置规则

• HTML（默认）：脚本输出由 --verify 注入右下角悬浮折叠面板（#verifyPanel），正文不设数据验证章节。三区：① 统计摘要 + 数据规范自检；② 计算验证（公式/计算值/声明值/偏差/✓✗）；③ 偏差汇总（仅有 ✗ 时）。有偏差自动展开并橙色警示，全通过则折叠显示「N/N 通过」，V 键切换。
• Markdown：参考文献后追加 ## 附录：数据验证，原样嵌入脚本纯文本。

---

⚠ 数据冲突处理原则（宪法级规定，不可违反）

当 Python 验证发现用户提供的数值与计算结果存在偏差时：

✅ 正确做法：
   1. 报告正文（Results、Analysis节）始终忠实呈现用户提供的原始数据和结论
   2. 验证面板中如实标注偏差（✗ 项）
   3. 若偏差 > 5%，在「讨论」节自动补充一段措辞，例如：
      「本实验中[指标名]的实测值（X.XX）与理论计算值（Y.YY）存在约Z%的偏差，
       可能来源于[误差分析]，建议实验者核查原始记录。」
   4. 偏差说明措辞用「可能」「建议核查」等不确定语气，不替用户下定论

❌ 禁止做法：
   - 用计算值替换用户提供的数值写入报告正文
   - 在未告知用户的情况下修正任何数据
   - 忽略偏差、不在面板和讨论中体现
   - 因数据存在偏差而拒绝生成报告

偏差严重程度分级：

| 偏差幅度 | 处理方式 | |---------|---------| | 20% | 验证面板标 ✗ 并橙色警示，在正式生成报告前主动告知用户偏差情况，询问是否继续 |

---

第二步（补）：写作逻辑自检（B 类，解读型问题）

auto_verify.py 的「数据规范自检」只覆盖能从数值表客观判定的问题（A 类： 小数位、样本量、SD/SEM、异常值、百分比合计）。另有一类需要正文语境才能判断 的常见错误（B 类），脚本无法自动判定，须由撰写者对照处理。

完整清单见 references/common-pitfalls.md，撰写讨论/结论节前必读。 要点：

• 单位一致且齐全；误差传播到最终结果；摘要/正文/表/图三处数据完全一致
• 相关 ≠ 因果：区分"相关/伴随"与"导致/引起"的措辞
• 不外推：结论不超出数据实际支持的范围；缺对照时不下因果结论
• 不夸大：摘要/结论口径不强于结果章节；不显著差异不谈"趋势"
• 误差分析具体化：指出具体来源与量级方向，不止写"人为误差"
• 统计显著 ≠ 实际意义：p 值之外报告效应量/置信区间

⚠ 处理方式（宪法级：只提示，不改写用户结论）

行文本身保持严谨（区分因果、不外推、不夸大）属于正常写作质量，照常执行。 但当发现用户已声明的结论/数据可能存在 B 类问题时：

✅ 正确做法：
   - 报告正文照常忠实呈现用户的数据与结论
   - 在 present_files 之前，于对话中附一段「📋 写作自检提示」
   - 用「可能/建议/提醒」语气列出疑似问题 + 对应编号（如 B5/B6），供用户自行判断
   - 若无 B 类问题，可不输出此段

❌ 禁止做法：
   - 因为认为用户的结论"逻辑有问题"就擅自改写正文论断
   - 替用户删改数据、下相反结论
   - 把不确定的判断写成肯定的批评

提示段格式示例见 references/common-pitfalls.md 末尾。

---

第三步：文献搜索与引文标注

搜索触发原则

在撰写以下章节时，必须进行网络文献搜索：

• 引言（背景知识、研究现状）
• 实验原理（理论依据、公式来源）
• 讨论（与已有研究对比、机理解释）

搜索策略：

1. 优先搜索数据库/权威来源：
   - 中文：CNKI、万方、维普、国家标准全文库
   - 英文：PubMed、Web of Science、Google Scholar、ACS/RSC/Elsevier期刊
   - 标准文献：GB/T、ISO、ASTM（用 site:std.samr.gov.cn 或 standards.org）
   - 教材/专著：Google Books

2. 搜索关键词构建规则：
   - 中文优先：[实验主题] + [核心概念] + "原理"/"机制"/"方法"
   - 英文补充：[topic] + [concept] + "mechanism" / "review" / "standard method"
   - 针对公式：搜索公式名称（如"Arrhenius equation derivation"）

3. 每个引用点：搜索2-3个候选，选择最权威、最具体的来源
   - 期刊论文 > 教材 > 综述 > 网页
   - 优先选有DOI的来源

4. 无法找到合适文献时：
   - 在正文中不加上标注
   - 不虚构文献信息
   - 可注明"[此处建议查阅相关教材]"

GB/T 7714-2015 引文格式

正文内引用：上标可点击数字，如 [1]（多篇连排）。

参考文献列表：按类型用标识符 [J] 期刊 / [M] 专著 / [S] 标准 / [D] 学位论文 / [EB/OL] 网络，每条以 `` 渲染并附可点击 DOI/URL。

各类型完整格式模板与 HTML 渲染示例见 references/gbt7714-reference-guide.md。

生成报告前检查：

• [ ] 每处引用均能通过URL访问（或有明确DOI）
• [ ] 作者、刊名、年份、卷期页码字段完整
• [ ] 文献类型标识符正确（[J]期刊/[M]专著/[S]标准/[EB/OL]网络）
• [ ] 正文引用编号与参考文献列表编号一一对应
• [ ] 无虚构文献信息

---

第四步：报告结构

标准结构（可根据场景裁剪）

1. 封面区（标题、副标题、作者、机构、日期）
2. Abstract / 摘要（150-300字）
3. 目录（自动生成）
4. 引言 / Introduction
5. 实验原理 / Theory（含公式）
6. 实验装置与方法 / Methods
   - 流程图（SVG，若用户提供了步骤描述）
7. 实验结果 / Results
   - 数据表格
   - 图表（Chart.js，仅当有数据时）
8. 数据处理与分析 / Analysis
   - 计算过程
   - 误差分析
9. 讨论 / Discussion
10. 结论 / Conclusion
11. 参考文献 / References
12. 附录（可选）
    - Markdown 格式：必须追加「附录：数据验证」节（嵌入脚本输出纯文本）
    - HTML 格式：无此附录，数据验证见右下角悬浮面板

场景裁剪原则：

• 实验课报告：保留全部章节，突出误差分析
• 科研记录：在Methods中增加"统计方法"小节
• 工程报告：将"实验原理"改为"设计依据"，增加"指标达标分析"
• 竞赛展示：压缩Methods，突出Results和Discussion，图表优先

---

第五步：可视化规范

数据可视化原则（基于 Storytelling with Data）

1. 选图优先级：散点图（关系）> 折线图（趋势）> 柱状图（对比）> 饼图（占比，慎用）
2. 去图表垃圾：无网格线（或极淡）、无边框、无多余图例；数据墨水比最大化
3. 配色：主色 --accent: #2f4f4f，强调色给最重要系列，其余低饱和灰；严禁彩虹配色
4. 描述性图题：用"处理组效率比对照组高23%"，而非"效率对比"；标注优于图例
5. 多系列量级差异大 → 优先分面图（Facet），避免双 Y 轴；必须用双 Y 轴时左右轴标题用对应系列颜色区分

Chart.js 完整配置模板（折线/柱状/散点/误差棒、颜色规则、figcaption 写法）见 references/swd-chartjs-examples.md。

SVG 流程图规范

• 仅当用户描述了实验步骤/流程时才绘制
• 配色随主题（CSS 变量）、字体 Georgia / Noto Serif SC、步骤框 rx 圆角
• 完整模板、箭头 orient="auto" 机制、` 禁止嵌套 HTML 规则、独立文件 data-svg-src 注入机制，全部见 references/svg-flowchart-template.md`（绘图前必读）。

---

第六步：HTML生成策略

统一走分段生成 → 脚本拼装 → 输出流程。CSS/JS 在 assets/，由 build_html.py 直接读取，不经对话 token。架构、单文件/分段策略、推荐分段方案、四类内容文件规格、主题注入、输出格式，全部见 references/html-build-guide.md（生成前必读）。

核心三阶段：

1. 生成内容文件：正文 HTML 片段（短报告单文件 report-body.html；长报告分段存 body-parts/，骨架见 references/html-template.md）；按需另存 charts-init.js、verify-output.txt、*.svg。
2. 拼装：

``bash # 单文件 python scripts/build_html.py --body report-body.html --output /mnt/user-data/outputs/report.html [--charts charts-init.js] [--verify verify-output.txt] # 分段（长报告推荐） python scripts/build_html.py --body-dir body-parts/ --output /mnt/user-data/outputs/report.html [--charts charts-init.js] [--verify verify-output.txt] ` 按工作变量追加 --theme / --editable / --no-verify-panel`。

1. 输出：present_files /mnt/user-data/outputs/report.html

---

执行检查清单

生成报告前，逐项确认：

阶段零：确认

• [ ] 已调用 ask_user_input 工具展示 3 个核心确认选项（文档模式 / 可视化内容 / 色彩主题）
• [ ] 已在调用前告知默认仅 HTML、不启用内联编辑；仅在用户主动要求时设定 NEED_MD=true / EDITABLE=true
• [ ] 已根据用户回答设定 MODE_LONG / NEED_SVG / NEED_CHART / THEME
• [ ] THEME≠default → build_html.py 命令已加 --theme （无需读取 CSS 文件）
• [ ] EDITABLE=true → build_html.py 命令已加 --editable
• [ ] 数据验证跳过（无任何数值数据）→ build_html.py 命令已加 --no-verify-panel

阶段一：内容生成

• [ ] 场景类型已识别，章节结构已裁剪
• [ ] 必须信息已收集，缺失项已用占位符处理
• [ ] 判断报告长度：≤5章节→单文件 report-body.html；>5章节或内容量大→分段生成至 body-parts/
• [ ] 单文件：report-body.html 含 .report-layout、.page、.float-toc、移动端导航、验证面板骨架
• [ ] 分段：body-01-header.html 含布局开始标签，最后一个片段含闭合标签及全部悬浮元素
• [ ] 所有 section id 与目录 a[href] 一一对应（跨分段也需对应）
• [ ] 有CSV/表格数据 → 已运行 auto_verify.py，输出保存为 verify-output.txt
• [ ] 验证输出已含【数据规范自检】块（小数位/样本量/SD-SEM/异常值/百分比），⚠ 项已随面板如实呈现
• [ ] 已对照 references/common-pitfalls.md 的 B 类逐项自检（单位、误差传播、相关≠因果、不外推、不夸大、误差分析具体化）
• [ ] 发现 B 类疑似问题 → 已在 present_files 前于对话中附「📋 写作自检提示」（仅提示，未改写正文结论）
• [ ] 有数值+公式（无CSV）→ 已生成并运行专项验证脚本，输出同格式保存
• [ ] 正文 Analysis 节无「数据验证」子章节
• [ ] 正文 Results/Analysis 节未出现任何用计算值替换原始数据的情况
• [ ] 有图表 → 已生成 charts-init.js，canvas id 与正文 `` 一致
• [ ] SVG 流程图（若有）已单独保存为 .svg 文件（如 flowchart.svg），与正文片段同目录；对应 ` 使用 data-svg-src` 占位符，不内嵌 SVG 代码
• [ ] 偏差 > 20% → 已在生成报告前告知用户并确认继续
• [ ] 偏差 > 5% → 「讨论」节已补充偏差分析段落
• [ ] 引言、原理、讨论各节已通过 web_search 搜索权威文献
• [ ] 所有引用均有可访问URL或DOI，无虚构文献
• [ ] 参考文献按 GB/T 7714-2015 格式排列，含链接

阶段二：拼装

• [ ] 已运行 build_html.py（单文件用 --body，分段用 --body-dir body-parts/）
• [ ] 脚本输出无 [WARN]（assets/report.css 和 report.js 均已找到）

阶段三：输出

• [ ] 已调用 present_files 向用户提供 HTML 文件下载

---

参考文件索引

| 文件 | 内容 | 何时读取 | |------|------|----------| | references/html-build-guide.md | HTML 构建机制（架构/分段策略/拼装命令/主题注入/输出格式） | 第六步生成 HTML 前必读 | | references/html-template.md | HTML 结构骨架（封面/目录/各 section/验证面板） | 生成正文片段时参照结构 | | references/style-constitution.md | 风格宪法框架 + 6套预置风格 | 用户指定非预置自定义风格时 | | references/svg-flowchart-template.md | SVG流程图模板、orient="auto" 箭头机制、` 禁嵌套规则、data-svg-src 注入机制 | 需要绘制流程图时必读 | | references/swd-chartjs-examples.md | SWD原则Chart.js完整配置模板 | 生成 charts-init.js 时参照 | | references/gbt7714-reference-guide.md | GB/T 7714格式详细规范与示例 | 撰写参考文献节时 | | references/common-pitfalls.md | 常见逻辑与数据错误清单（A类脚本检查项 + B类撰写自检项 + 提示段格式） | 撰写讨论/结论节前必读 | | assets/report.css | 完整CSS（样式/响应式/深色模式/编辑器） | 由 buildhtml.py 自动读取，Claude不需读 | | assets/report.js | 所有交互JS（目录/验证面板/内联编辑器） | 由 buildhtml.py 自动读取，Claude不需读 | | scripts/autoverify.py | CSV/表格数据自动验证脚本 | 有CSV或粘贴表格数据时 | | scripts/verifydata.py | 手动填写的验证脚本模板 | 有数值+公式但无CSV时 | | scripts/build_html.py` | HTML拼装脚本 | 阶段二运行 |

---

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: endearqb
• Source: endearqb/endearqb-skills
• License: MIT

Install and usage instructions live in the source repository linked above.