| name | lab-report-writer |
| metadata | {"version":"2.5.2"} |
| description | 撰写期刊风格的实验报告，支持理工科实验课报告、科研论文级实验记录、工程项目技术报告、竞赛展示用报告等全场景。
用户提供实验信息、数据、方法描述后，生成结构完整、排版专业的报告，并附带Python数据验证脚本对所有计算结论进行复核。
触发条件（凡符合以下任一项，均应使用本skill）：
- 用户说"帮我写实验报告"、"写一份实验记录"、"整理实验数据"、"写技术报告"
- 用户提供了实验原始数据并想生成正式报告
- 用户说"我有实验结果，帮我整理成报告"
- 用户想把markdown或word报告转成HTML期刊风格
- 任何涉及"实验"+"报告/记录/总结"的组合请求
- 用户提到要生成包含数据图表、公式推导、误差分析的正式文档
输出格式：优先HTML报告（期刊风格）；也可输出Markdown或Word（.docx）。
如果用户提供了Markdown/Word报告，应提醒其可升级为HTML报告。
|
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。
生成报告前检查：
第四步：报告结构
标准结构（可根据场景裁剪）
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）
- 选图优先级：散点图（关系）> 折线图（趋势）> 柱状图（对比）> 饼图（占比，慎用）
- 去图表垃圾：无网格线（或极淡）、无边框、无多余图例；数据墨水比最大化
- 配色：主色
--accent: #2f4f4f，强调色给最重要系列，其余低饱和灰；严禁彩虹配色
- 描述性图题：用"处理组效率比对照组高23%"，而非"效率对比"；标注优于图例
- 多系列量级差异大 → 优先分面图（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（生成前必读）。
核心三阶段：
- 生成内容文件：正文 HTML 片段（短报告单文件
report-body.html；长报告分段存 body-parts/，骨架见 references/html-template.md）；按需另存 charts-init.js、verify-output.txt、*.svg。
- 拼装：
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。
- 输出：
present_files /mnt/user-data/outputs/report.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" 箭头机制、<text> 禁嵌套规则、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（样式/响应式/深色模式/编辑器） | 由 build_html.py 自动读取，Claude不需读 |
assets/report.js | 所有交互JS（目录/验证面板/内联编辑器） | 由 build_html.py 自动读取，Claude不需读 |
scripts/auto_verify.py | CSV/表格数据自动验证脚本 | 有CSV或粘贴表格数据时 |
scripts/verify_data.py | 手动填写的验证脚本模板 | 有数值+公式但无CSV时 |
scripts/build_html.py | HTML拼装脚本 | 阶段二运行 |
