028、图片与文档处理：图像分析、PDF 章节阅读与 Jupyter Notebook 编辑实战
上周五凌晨两点，我盯着终端里Claude Code吐出的错误日志发呆。一个客户发来的PDF合同，里面嵌着三张扫描件——公章、签名、手写备注。Claude Code读完了文字部分，但图像区域直接跳过了。客户追问：“公章上的编号你们识别了吗？”我翻了下输出，没有。这不是Claude Code的锅，是我没告诉它怎么处理非文本内容。
这个场景在工程化落地中太常见了。很多人把Claude Code当成纯文本工具，遇到图片、PDF、Notebook就抓瞎。今天这篇笔记，我把踩过的坑和摸出来的套路一次性说清楚。
图像分析：别让Claude Code“看”不到图
Claude Code默认不会主动读取图片文件。你扔一个image.png进去，它只会看到文件名。要让模型真正“看见”图片内容，得用--vision模式。
claude--visionanalyze_image.py这里踩过坑：--vision会显著增加token消耗，一张中等分辨率的截图大约吃掉2000-3000 tokens。别在调试阶段每张图都开vision，先确认文本逻辑跑通，最后再开视觉分析。
实战中我常用这个模式做两件事：
1. UI截图对比测试
自动化测试跑完，Claude Code拿到截图后，直接让它描述页面元素位置和颜色变化。比如：
请分析screenshot_after_update.png，告诉我： - 按钮“提交”是否可见 - 错误提示区域是否有红色边框 - 页面加载状态是否消失别这样写：“请分析这张图片”。Claude Code需要明确的任务指令，否则它会给你一段“这是一张包含蓝色按钮和白色背景的图片”这种废话。
2. 手写笔记转结构化数据
客户发来一张手写会议记录的照片。我让Claude Code先做OCR识别，再按Markdown表格整理。关键步骤是分两步走：
第一步，让模型描述图片中的文字内容。第二步，基于描述结果做结构化转换。不要指望一步到位，图片质量差的时候，模型会编造内容。
有个血泪教训：图片分辨率低于300dpi时，识别准确率断崖式下跌。我后来在预处理阶段加了--resize参数，用ImageMagick先放大两倍再喂给Claude Code。
PDF章节阅读：分段投喂的艺术
PDF是Claude Code的天然敌人。不是模型不行，是PDF格式太脏。一个10页的PDF，可能包含5种不同的编码方式、嵌入字体、矢量图、注释层。直接扔进去，Claude Code大概率会吐出乱码或者只读前两页。
我的标准流程是三步：
第一步：PDF转文本
pdftotext-layoutinput.pdf output.txt-layout参数保留原始排版，对多栏文档尤其重要。别用默认参数，否则表格数据会变成一坨。
第二步：按章节切割
写一个简单的Python脚本，根据“第X章”或“Chapter X”做分割。Claude Code对单次输入的长度有限制，超过2万token会开始丢细节。我一般把每个章节控制在5000 token以内。
# 这里踩过坑：直接用split('\n\n')会切碎表格# 改用正则匹配章节标题importre chapters=re.split(r'(?=第[一二三四五六七八九十]+章)',text)第三步：逐章投喂并汇总
每次只给Claude Code一个章节的内容，让它提取关键信息。最后把所有章节的摘要合并，再让模型做一次全局总结。
别这样写：“请阅读整个PDF并总结”。Claude Code会尝试一次性处理，然后告诉你“抱歉，内容过长”。分段投喂虽然慢，但结果可靠。
遇到扫描版PDF怎么办？先转图片，再用vision模式。我写了个自动化脚本：
# 先转图片pdftoppm-png-r300input.pdf output_page# 再逐页分析forfinoutput_page*.png;doclaude--vision"分析$f中的文字内容">>page_content.txtdone这个流程跑一次大概5分钟，但能处理任何格式的PDF，包括那些加密的、带水印的、甚至手写的。
Jupyter Notebook编辑实战：别让Claude Code碰.ipynb
Jupyter Notebook的.ipynb文件本质是JSON。Claude Code能读，但编辑起来极其痛苦。它经常把代码块和Markdown块搞混，或者把输出结果当成代码写进去。
我的解决方案是：永远不要直接编辑.ipynb文件。
工作流：.ipynb → .py → 编辑 → 转回.ipynb
# 提取代码和Markdownjupyter nbconvert--toscript notebook.ipynb# 这会生成notebook.py，包含所有代码和注释然后让Claude Code编辑这个.py文件。它处理纯Python文件得心应手，不会搞混格式。
编辑完成后，再转回Notebook：
# 这里踩过坑：直接转回去会丢失Markdown格式# 改用这个工具jupytext--tonotebook notebook.py-onotebook_updated.ipynbjupytext比nbconvert更智能，能保留Markdown和代码的分隔。我试过用nbconvert转回来，结果所有Markdown都变成了代码注释，气得我重写了一遍。
进阶技巧：让Claude Code生成Notebook
有时候需要从零创建一个Notebook。我让Claude Code先生成一个.py文件，里面用特殊注释标记Markdown和代码块：
# %% [markdown]# # 数据分析报告# 这是标题# %% [code]importpandasaspd df=pd.read_csv('data.csv')然后运行：
jupytext--tonotebook generated.py-oreport.ipynb这个流程比直接让Claude Code写JSON靠谱十倍。它不会把引号搞乱，也不会忘记闭合括号。
实战案例：处理一份混合文档
上周处理了一个真实案例：客户发来一个压缩包，里面包含一个PDF合同、三张盖章照片、一个Jupyter Notebook分析报告。
我的处理流程：
- 解压后，PDF用
pdftotext转文本，照片用--vision逐张分析 - 文本和图片分析结果合并成一个Markdown文件
- 让Claude Code基于合并内容生成合同摘要和风险点
- Notebook用
jupytext转成.py，让Claude Code检查代码逻辑并添加注释 - 最后把修改后的
.py转回.ipynb
整个过程大约20分钟，Claude Code处理了约1.5万token的输入。如果直接扔原始文件，估计要翻车三次。
个人经验性建议
图片预处理比模型能力更重要。分辨率、对比度、去噪，这些做好，Claude Code的视觉能力能提升50%。我写了个预处理脚本，自动做灰度化、对比度增强、锐化，效果立竿见影。
PDF永远不要直接喂。先转文本，再分段。这是铁律。我见过有人直接把100页PDF扔进去，Claude Code卡了15分钟，最后输出“无法处理”。浪费时间。
Notebook编辑用中转格式。
.ipynb是给Jupyter看的，不是给LLM看的。.py才是Claude Code的舒适区。多一步转换，少十次debug。token预算要提前算。一张图片vision模式吃掉2000-3000 tokens，一个PDF章节5000 tokens，一个Notebook可能1万+。我每次开工前先估算总token，超过3万就分两次对话。Claude Code的上下文窗口虽然大，但超过2万后质量明显下降。
保留原始文件。Claude Code编辑完，别急着覆盖原文件。我习惯在文件名加
_claude_edited后缀，对比着看。有一次它把PDF里的表格数据全改成了Markdown格式，数值没变但结构乱了，幸好有原文件对比才发现。
最后说一句：Claude Code处理图片和文档的能力在快速迭代，但工程化的核心不是依赖模型有多强，而是你有多了解它的边界。知道什么时候该用vision，什么时候该用文本，什么时候该手动预处理——这些经验比任何模型更新都值钱。
