Lab Data Workflow

---
name: lab-data-workflow
description: 物理实验数据全流程——手写记录纸照片转录成原始数据 CSV、逐项核对、写处理脚本算结果出图、生成实验报告与 PDF。当用户说"录入实验数据""处理实验数据""写实验报告""实验数据出图/出 PDF""把手写的记下来""数据誊录"时使用。也适用于任何需要把纸质记录变可复现数据文件的场合。
---

# 物理实验数据处理流程

一个实验 = `<unit>` 下的一个子文件夹（如 `1.杨氏模量/`），数据放它的 `实验数据/` 子目录。
本 skill 的脚本在 `.claude/skills/lab-data-workflow/scripts/`，模板在 `templates/`。
**下面所有路径都相对 `<unit>`**（即 `D:\文件\教材\物理实验`）。

## 现在该做哪一步

| 用户说 | 做 |
|---|---|
| 刚放了照片 | §1 转录 |
| "核对一下""看看对不对" | §2 |
| "算一下""处理数据" | §3 |
| "写报告""出 PDF" | §4 |
| "攻击/审阅报告" | §5 |

---

## §1 照片 → 原始数据 CSV

### 1.1 预处理：先看清字，再读

整张手写照片直接读会糊。**必须**先切块，否则一定读错数字。

```bash
# 总览：看版面有哪几张表、有没有转 90 度
python .claude/skills/lab-data-workflow/scripts/prep_photo.py 照片.jpg

# 照片躺倒时转正（--rotate 走的是 PIL 的逆时针角度，im.rotate(90) 就是逆时针 90°）
# 躺倒的照片先试 90，出来还是躺的就试 -90
python .claude/skills/lab-data-workflow/scripts/prep_photo.py 照片.jpg --rotate 90 --split

# 放大某张表：坐标在总览图上量，单位是原图像素
python .claude/skills/lab-data-workflow/scripts/prep_photo.py 照片.jpg --rotate 90 --crop 330,1600,1760,1850 --zoom 1.6

# 字迹淡/照片发灰时加 --region autolevel（去背景+提对比度，效果很明显）
python .claude/skills/lab-data-workflow/scripts/prep_photo.py 照片.jpg --crop 430,1330,2960,1960 --zoom 1.2 --region autolevel
```

产物写到照片同目录的 `_prep/`。**裁切是唯一可靠的办法**——一眼扫过去读宏观表，数字一律靠裁切图逐个确认。

### 1.2 读的纪律

- **认不清就问用户，不要猜。** 手写数字、涂改、单位、批注都问。问的时候把证据一起给（"我读到 X，但 Y 处矛盾"），用户能秒答。
- **涂改以改后为准**，划掉的原值记下来但不用。
- **批注决定单位**。记录纸表头印的单位经常是错的（印 `/mm` 实际写的是 cm），页边批注（"(cm)"、"需乘0.01"、"(+100)"、"千分尺零点 0.011mm 未减"）才是真的。表头印的、表里写的、页边注的三者不一致时，**问**。
- 仪器会转圈。鼓轮读数越过 100 要加回 100，不然会出现负位移。
- 同一个符号在不同实验里含义不同（`d` 既可能是直径也可能是刀口间距），按节读，别跨节套。

### 1.3 写 CSV

```bash
# 检查/转换编码：Excel 中文版另存的是 GBK，其它工具打开乱码
python .claude/skills/lab-data-workflow/scripts/to_utf8.py --check 1.杨氏模量/实验数据/
python .claude/skills/lab-data-workflow/scripts/to_utf8.py 1.杨氏模量/实验数据/   # 就地转 UTF-8 BOM，原文件备份 .gbk.bak
python .claude/skills/lab-data-workflow/scripts/to_utf8.py --clean 1.杨氏模量/实验数据/   # 确认无误后删备份
```

用 `csv_tables.py` 写，它自动加 BOM + CRLF：

```python
import sys; sys.path.insert(0, r'.claude/skills/lab-data-workflow/scripts')
import csv_tables as ct

ct.write('1.杨氏模量/实验数据/2_霍尔法.csv',
  [('横梁的几何尺寸',
    [['测量次数', '1', '2', '3'],
     ['长度d/cm', '23.60', '23.55', '23.57']]),
   ('读数显微镜示数',
    [['序号', '1', '2'],
     ['Zi', '01.9', '16.5']])],
  comments=['霍尔法 原始读数 —— 照抄记录纸, 未换算',
            '长度d 单位 cm; 厚度a 需减千分尺零点 0.011'])
```

```bash
# 检查写完的 CSV 能不能正确解析
python .claude/skills/lab-data-workflow/scripts/csv_tables.py 1.杨氏模量/实验数据/2_霍尔法.csv
```

**CSV 里只存记录纸上的手写原值，不做任何单位换算。** 零点修正、单位换算全部留给 §3 的脚本。
这条是整个流程的核心纪律：一旦在数据文件里预先换算，就会出现"同一个量在两个文件里单位不同"，
而且事后无法从文件本身看出来（实际踩过：宽度 22.16 mm 被写成 0.2216）。

分段标记 `# ---- 名称 ----` 后面第一行是表头，其余是数据行。空格子留空表示记录纸上没有，
读出来是 `None`，不要填 0。

---

## §2 核对：确认前不计算

录完后**先交核对清单，不要直接算**。用户会逐项对，尤其是：

- 每个标了"我把握不足"的值
- 涂改过的格子
- 单位/批注的判断

同时产出一份放大图目录（把 §1.1 的裁切图按表名重命名归档），用户核对时比翻原照片快得多。
确认后把结论写回文档（README 的"修正"一节 + CSV 表头注释），再进 §3。

---

## §3 处理脚本

一个实验一个 `处理.py`，放在 `<unit>/<实验>/实验数据/`。结构固定：

```python
# 1. 顶部「约定」区：所有修正和仪器误差集中在这里，每条注明出处
L_MM = 778.0;  E_RULER = 1.0        # 卷尺分度值 1mm
D_CORR = -0.005                     # 页边批注 "-0.005"
Z_PLUS = 100.0                      # 鼓轮过一圈, 旁注 "(+100)"

# 2. 读 CSV（用 csv_tables），只读原始值
# 3. 修正 + 计算；把每张中间表和每个公式都打印出来
# 4. 出图存 fig1/fig2/fig3*.png
# 5. 报告同时 print 到屏幕 和 写 处理结果.md
```

要点：

- **不确定度把两种取法都打出来**：`u_B = e/√3` 和 `u_B = e`。指导书一般没规定 A/B 类取法，
  做成顶部开关 `DIVISOR_B`，两种结果的最终值都打印，用户按老师要求选。
- **仪器误差要问用户**，指导书经常没写。按行标注"按常用仪器取值，待确认"，别默默假设。
- 逐差法配对时**用实际差值**，不要假设等间隔——实测质量常不是严格等差（如 19.9/40.0/60.5…）。
- 拟合求极值（如外推法的曲线最低点）时，**报告模型间的差异**：二次拟合顶点 vs 两支直线交点
  给出的结果可能差 1 Hz 量级，这比仪器不确定度大得多。
- 跑完把脚本输出连同一句话结论给用户。

---

## §4 报告

### 4.1 文风（用户明确的底线）

- **删掉所有中间代入算式**。"没人要看你列算式算平均值"——`d̄=(0.185+…)/6=0.18517` 这种
  只留结果 `d̄ = 0.18517 mm`。公式就写 `Y = 4MgL/(πd²ΔL) = 2.63×10¹¹`，中间那串数字删掉。
- **不要为了写长而写**。目的写三条就行，别凑第四条套话。
- **括号里不放填充**。"（需要注意的是…）""（顺便一提…）"一律删。
- **和标准值的偏差别当成"待排查问题"**。指导书自己都写了标准值仅供参考。数据质量看
  ① 拟合 R² ② 不同处理方法之间是否自洽（逐差法 vs 作图法差多少），不是看离标准值多近。
- **不复述**：表格里有的数字正文不要再列一遍；同一句物理解释全文只讲一次；
  不要另设"数据质量"章节把前面的数字抄一遍。
- 正文顺序：目的 → 原理 → 仪器 → 数据 → 处理 → 结果。

### 4.2 出 PDF

从模板起步，改内容：

```bash
cp .claude/skills/lab-data-workflow/templates/report.typ 1.杨氏模量/实验数据/实验报告.typ
# 改完之后编译（typst 0.15 已验证；跑一遍即可，交叉引用自动解析）
cd 1.杨氏模量/实验数据 && typst compile 实验报告.typ
```

模板里已经有：三线表 `#bt()`、单位 `#u("mm")`、表格居中、中文字体、公式编号。
图放在报告同目录，用 `#figure(image("fig1.png", width: 55%), caption: [...])`。

排版调不下页数时按这个顺序收：图宽 → `leading` → 页边距 → 结果表加
`#block(breakable: false, ...)` 防止跨页。

---

## §5 对抗式文风审阅

写完报告开一个 subagent 攻它。**prompt 里必须写死范围：只审文风**，并**列明禁止打开的文件**
（数据 CSV、处理脚本、结果文件）。数据正确性已经由 §1–§3 保证过，再让 subagent 重算一遍是
重复劳动，还会掩盖真正要找的文风问题。

攻击清单：复述、过度解释、括号废话、中英夹杂、铺垫过渡话、科研论文式自我批判、
术语符号不统一、孤立数字、表格与正文分工。

攻完逐条改，改完可以再来一轮（第二轮会挑出符号撞车、单位写法不统一这类第一轮漏掉的）。
第二轮后如果只剩零星项，够了。

---

## 踩过的坑

- **`bar(x)` 在 Typst 里是竖线符号**，不是上划线。均值必须写 `overline(x)`，
  否则渲染成 `|x|`。
- **Typst 表格默认齐左**，加 `#show table: it => align(center, it)` 才居中。
- **Typst 表格单元格里写 `"字符串"` 不会当标记解析**，`$公式$` 会原样印出来。
  必须写内容块：`([序号 $i$], [$M\/"g"$])`。
- **Typst 的 `%` 不是注释**（注释是 `//` 和 `/* */`），所以 `6.72%` 可以直接写。
- **PDF 文字提取会打乱分数**：指导书里 `E = d³Mg/(4a³bΔZ)` 的 4 在分母，
  文字提取会把它提到分子位置。**公式一律渲染原页图片核对**，别信提取的文本。
- 长图路径里带中文时，桌面端的文件面板打不开，让用户自己开。
- Python 是 Windows 版，`/tmp/...` 这种路径它不认，脚本里用相对路径或完整 Windows 路径。

## 排查

| 现象 | 原因 / 处理 |
|---|---|
| 中文显示成 `���` | 文件是 GBK。跑 `to_utf8.py` |
| 打开 CSV 第一列多了个 `\ufeff序号` | 读的时候用了 `utf-8` 而不是 `utf-8-sig` |
| 读 CSV 报"有一行不在分段之内" | 缺 `# ---- 名称 ----` 标记 |
| `csv_tables.py` 报"没有 BOM" | 文件被 Excel 另存过了，重跑 `to_utf8.py` |
| Typst 编译报字体缺失 | 改 `.typ` 第 3 行的字体名；`typst fonts` 看有哪些中文字体 |
| 报告页尾大片空白 | 图太大被挤到下一页。缩图宽，或给表格加 `#block(breakable: false)` |