# Lab Report Writer

> |

- **Type:** Skill
- **Install:** `agentstack add skill-endearqb-endearqb-skills-endearqb-lab-report-writer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [endearqb](https://agentstack.voostack.com/s/endearqb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [endearqb](https://github.com/endearqb)
- **Source:** https://github.com/endearqb/endearqb-skills/tree/main/skills/endearqb-lab-report-writer

## Install

```sh
agentstack add skill-endearqb-endearqb-skills-endearqb-lab-report-writer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`。
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 与正文 `` 一致
- [ ] 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（样式/响应式/深色模式/编辑器） | 由 `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拼装脚本 | 阶段二运行 |

---

## Source & license

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

- **Author:** [endearqb](https://github.com/endearqb)
- **Source:** [endearqb/endearqb-skills](https://github.com/endearqb/endearqb-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-endearqb-endearqb-skills-endearqb-lab-report-writer
- Seller: https://agentstack.voostack.com/s/endearqb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.