exp-report-builder

从实验指导书和报告模板自动生成实验报告。Claude 理解内容、做决策，Python 只做安全的文档读写。

没有固定模板结构、没有固定实验编号、没有固定内容 —— 每次都从头读取两份文档，理解后再填。

核心理念

Claude 是大脑，Python 是手。

固定的模板解析器换一门课就失效。Claude 每次重新读文档、重新理解结构、重新决策填充策略。Python 只提供安全的文档操作原语（读、写、插、删）。

执行流程

① 格式转换 → ② 分析文档 → ③ 确认需求 → ④ 逐实验生成 → ⑤ 导出 PDF

1. 格式兼容：PDF 指导书 → pdfplumber 提取文本/pymupdf 提取图片，.doc 模板 → win32com 转 docx
2. 分析文档：python scripts/docx_utils.py analyze <模板> 打印完整结构（段落/表格/字号）
3. 确认需求：哪些实验？姓名/学号/班级/日期？
4. 逐实验生成：每个实验写 Python 脚本，调用工具函数填充
5. 导出 PDF：win32com → Word 另存为 PDF（格式 100% 一致）

快速开始

分析模板

python scripts/docx_utils.py analyze 模板.docx

输出全文结构（段落索引、字号、粗体），Claude 阅读后决定填充策略。

分析指导书

python scripts/docx_utils.py guide 指导书.docx

提取指导书图片

python scripts/docx_utils.py images 指导书.docx

生成报告（示例脚本）

from scripts.docx_utils import *

doc = Document('模板.docx')

# 1. 封面填充（保留原字号）
fill_cover(doc, {
    'exp_title': '实验一 Servlet技术',
    'student_name': '姓名',
    'teacher_name': '指导教师',
    'class_name': '专业班级',
    'student_id': '学号',
    'date': '2026-06-15',
})

# 2. 填充节内容（段落式模板）
fill_section_content(doc, '实验目的和要求', [
    '1. 掌握HttpServlet的使用。',
    '2. 理解doGet()和doPost()方法的区别。',
])

fill_section_content(doc, '主要实验内容', [
    '一、第一个案例',
    '（1）实验描述',
    '描述内容...',
    '（2）运行结果',
    '结果文字...',
    {'img': 'screenshots/p03_0.png'},  # 嵌入截图
    '（3）实验结果分析',
    '分析内容...',
])

fill_section_content(doc, '心得体会', [
    '1. 实验过程中出现的问题与解决方法',
    '（1）问题：...',
    '2. 通过本次实验掌握的知识内容',
    '（1）...',
])

# 3. 保存
safe_save(doc, '实验一 Servlet技术-班级-姓名-学号.docx')

支持的模板类型

类型	特征	填充方式
段落式	节标题为段落（如"一、实验目的"），无表格	fill_section_content()
表格式	内容在 doc.tables[0] 单元格中	get_template_cells() + add_paragraph_to_cell()

工具函数速查

函数	用途
dump_structure(path)	打印模板全文结构（含字号/粗体）
parse_guide(path)	解析 .docx 指导书为实验-章节-段落
extract_images(path)	从 .docx 中提取图片并显示上下文
fill_cover(doc, info)	填充封面个人信息（自动保留原字号）
fill_para_preserve_font(para, text)	替换段落文本，保留原字号字体
find_label_para(doc, keyword)	按整段文本匹配找段落
fill_section_content(doc, header, content_list)	替换节内容，可混合 str 和 {'img': path}
add_image_after_para(doc, img, last_elem, width)	API 创建图片段落并移到指定位置
get_template_cells(doc)	获取表格式模板的单元格列表
add_paragraph_to_cell(cell, text, bold, size)	向单元格添加新段落
add_image_to_cell(cell, path, width)	向单元格添加居中图片
add_table_to_cell(cell, headers, data)	向单元格添加数据表格
safe_save(doc, path)	安全保存（临时文件 → rename）

关键踩坑经验

1. 封面格式保留：永远不用 clear_para()，用 fill_para_preserve_font() 保留原字号（如 16pt 四号）
2. 标签匹配用整段文本：中文标签常跨多个 run（'实验' + '、实践' + '名称'），匹配 para.text 而非 run.text
3. 段落删除先收集后删除：先 list() 收集引用，再逐个删，避免索引偏移
4. 图片用 API 创建：doc.add_paragraph() → add_picture() 获得正确关系链，直接插入 XML 会报错
5. 导出 PDF 用 Word COM：win32com → SaveAs PDF，唯一可靠的格式保持方案
6. 截图自然融入：不用 【截图：xxx】 占位符，用自然语言描述 + {'img': path} 嵌入

依赖

• Python 3.10+
• python-docx：pip install python-docx
• pdfplumber（PDF 指导书）：pip install pdfplumber
• PyMuPDF（PDF 图片提取）：pip install pymupdf
• pywin32（.doc 转换 + PDF 导出）：pip install pywin32

目录结构

exp-report-builder/
├── skill.md                  # Claude Code skill 定义（执行流程/API速查/规则）
├── README.md                 # 本文件
└── scripts/
    └── docx_utils.py         # 文档操作工具集（结构分析/提取/填充/保存）

License

MIT