015、图片文档处理：图像分析、PDF 阅读与 Notebook 编辑
上周五凌晨两点，我盯着终端里一行报错发呆——Claude Code 在处理一张带表格的 PDF 截图时，把第三列的数据全读成了日期格式。客户那边等着要分析报告，我手头只有一张手机拍的 PDF 照片。那一刻我意识到，图像文档处理不是“能识别文字就行”那么简单，格式理解、上下文关联、甚至文档结构重建，每一步都可能翻车。
图像分析：别让 Claude 只看像素
Claude Code 的图像分析能力基于多模态理解，但很多人把它当 OCR 用，这是第一个坑。直接丢一张截图进去，Claude 会尝试理解图像内容，但如果你不给它“看什么”的提示，它可能把背景里的水印当成正文。
我踩过的真实案例：一张产品说明书照片，背景有公司 logo 的阴影，Claude 把 logo 文字和正文混在一起输出。解决方案是预处理时用 convert 命令（ImageMagick）做背景减除：
# 这里踩过坑：直接传原图会导致背景干扰
# 先做灰度化+对比度增强，让文字更清晰
convert input.jpg -colorspace Gray -contrast-stretch 5%x5% output.jpg
然后传给 Claude 时，在 prompt 里明确指定分析区域：
请分析这张图片中，从左上角(100,50)到右下角(800,600)矩形区域内的文字内容。
忽略所有水印和背景图案，只提取黑色文字部分。
别这样写：“请分析这张图片”——太模糊了，Claude 会猜你要什么，猜错的概率不低。
PDF 阅读：从二进制到结构化数据
PDF 处理是另一个重灾区。Claude Code 原生支持 PDF 输入，但遇到扫描件（图片型 PDF）时，它实际上是在做 OCR，而不是直接读文本。这里有个关键区别：文本型 PDF 可以直接提取内容，扫描型 PDF 需要先转图像再分析。
我常用的工作流是两步走：
# 别这样写：直接让 Claude 读扫描 PDF，速度慢且容易丢行
# 正确做法：先用 PyMuPDF 提取文本，失败再走 OCR
import fitz # PyMuPDF
def extract_pdf_content(pdf_path):
doc = fitz.open(pdf_path)
text_content = []
for page_num, page in enumerate(doc):
# 这里踩过坑：get_text() 对扫描件返回空字符串
text = page.get_text()
if text.strip():
text_content.append(f"— 第{page_num+1}页 —\\n{text}")
else:
# 扫描件，转图片再处理
pix = page.get_pixmap(dpi=300)
pix.save(f"page_{page_num}.png")
text_content.append(f"— 第{page_num+1}页(扫描件) —\\n[需图像分析]")
return "\\n".join(text_content)
对于表格型 PDF，我强烈建议先转成 Markdown 表格再喂给 Claude。直接传 PDF 让 Claude 理解表格结构，它经常把跨页表格的列对齐搞错。用 camelot-py 或 tabula-py 做表格提取：
# 安装时注意：camelot 依赖 ghostscript，别漏了
pip install camelot-py[cv] tabula-py
提取后转成 Markdown，Claude 处理起来准确率能到 95% 以上。
Notebook 编辑：别让代码和输出打架
Jupyter Notebook 的 .ipynb 文件本质是 JSON，但 Claude Code 处理时有个诡异行为——它会把输出单元格的内容当成代码的一部分来理解。如果你传一个带大量报错输出的 notebook，Claude 可能误以为那些报错是你要修复的代码。
我的处理策略是预处理时剥离输出：
import json
def clean_notebook(ipynb_path):
with open(ipynb_path) as f:
nb = json.load(f)
for cell in nb['cells']:
if cell['cell_type'] == 'code':
# 这里踩过坑：不清空 outputs 会导致 Claude 混淆
# 保留 execution_count 但清空输出
cell['outputs'] = []
# 可选：保留最后一个输出作为参考
# cell['outputs'] = [cell['outputs'][-1]] if cell['outputs'] else []
return nb
编辑 notebook 时，我习惯让 Claude 输出 diff 格式的修改建议，而不是直接重写整个文件。这样能避免它不小心改掉你精心调好的参数：
请分析这个 notebook，找出数据清洗部分的 bug。
只输出需要修改的单元格索引和对应的代码 diff，
不要重写整个文件。
实战组合拳：从照片到分析报告
上周那个 PDF 照片的问题，我最终用这套流程解决：
整个过程耗时 15 分钟，比手动录入快了 10 倍。关键点在于每一步都做了“格式转换”，而不是让 Claude 在一个步骤里完成所有事。
个人经验
图像文档处理最容易被忽视的是“格式感知”。Claude 能识别文字，但它不理解“这个表格第三列是金额，应该用数字格式”。所以我的建议是：永远在 prompt 里明确告诉它文档的结构和字段含义，别指望它自己猜出来。
另外，对于超过 10 页的 PDF，分段处理比一次性喂给 Claude 效果好得多。每 3-5 页一组，每组单独分析，最后汇总。这样既避免上下文窗口溢出，也方便定位错误。
最后一条血泪教训：处理完的文档一定要做“回读验证”——让 Claude 根据你提取的数据重新描述文档内容，看它理解得对不对。这一步能发现 80% 的格式理解错误。
