agentleFS
endearqbendearqb/endearqb-skills/skills/endearqb-lab-report-writer/SKILL.md

lab-report-writer

Skill19 starsChanged 6 months agoMITView on GitHub

撰写期刊风格的实验报告,支持理工科实验课报告、科研论文级实验记录、工程项目技术报告、竞赛展示用报告等全场景。 用户提供实验信息、数据、方法描述后,生成结构完整、排版专业的报告,并附带Python数据验证脚本对所有计算结论进行复核。

The file

Files
SKILL.md

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%)。验证深度随数据量自动调(<10 轻量 / 10–50 中度 / >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. 偏差说明措辞用「可能」「建议核查」等不确定语气,不替用户下定论

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

偏差严重程度分级:

偏差幅度处理方式
< 1%视为数值舍入误差,验证面板标 ✓,正文无需特殊处理
1–5%验证面板标 ✗,讨论节加一句可能原因
5–20%验证面板标 ✗ 并橙色警示,讨论节专门分析,建议核查
> 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 引文格式

正文内引用:上标可点击数字,如 <sup><a href="#ref-1">[1]</a></sup>(多篇连排)。

参考文献列表:按类型用标识符 [J] 期刊 / [M] 专著 / [S] 标准 / [D] 学位论文 / [EB/OL] 网络,每条以 <li id="ref-N"> 渲染并附可点击 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" 机制、<text> 禁止嵌套 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. 拼装:
    # 单文件
    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。
  3. 输出: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 与正文 <canvas id="..."> 一致
  • SVG 流程图(若有)已单独保存为 .svg 文件(如 flowchart.svg),与正文片段同目录;对应 <figure> 使用 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.mdHTML 构建机制(架构/分段策略/拼装命令/主题注入/输出格式)第六步生成 HTML 前必读
references/html-template.mdHTML 结构骨架(封面/目录/各 section/验证面板)生成正文片段时参照结构
references/style-constitution.md风格宪法框架 + 6套预置风格用户指定非预置自定义风格时
references/svg-flowchart-template.mdSVG流程图模板、orient="auto" 箭头机制、<text> 禁嵌套规则、data-svg-src 注入机制需要绘制流程图时必读
references/swd-chartjs-examples.mdSWD原则Chart.js完整配置模板生成 charts-init.js 时参照
references/gbt7714-reference-guide.mdGB/T 7714格式详细规范与示例撰写参考文献节时
references/common-pitfalls.md常见逻辑与数据错误清单(A类脚本检查项 + B类撰写自检项 + 提示段格式)撰写讨论/结论节前必读
assets/report.css完整CSS(样式/响应式/深色模式/编辑器)由 build_html.py 自动读取,Claude不需读
assets/report.js所有交互JS(目录/验证面板/内联编辑器)由 build_html.py 自动读取,Claude不需读
scripts/auto_verify.pyCSV/表格数据自动验证脚本有CSV或粘贴表格数据时
scripts/verify_data.py手动填写的验证脚本模板有数值+公式但无CSV时
scripts/build_html.pyHTML拼装脚本阶段二运行

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.