PDF转图片（pdfzhuantu）

将PDF文件转换为PNG图片。基于PyMuPDF（fitz）渲染，保证中文和印刷体清晰度。

快速概览

• 输入：PDF文件（非加密）
• 输出：PNG图片，2x分辨率（~144 DPI），到桌面 PDF转图_时间戳/ 文件夹
• 页数：支持单页/指定页/全部页
• 首次使用：自动检测环境 → 询问确认 → 从清华镜像安装 PyMuPDF==1.27.2.3
• 适用系统：Windows / macOS / Linux
• 不支持：加密PDF、扫描件OCR

文件结构

能力边界

欢迎语

> 已进入PDF转图片模式，首次使用可能会下载匹配的环境依赖，请耐心等待

触发条件

用户提到以下任意一种表述时，立即使用本技能：
- "PDF转图片" / "PDF转图" / "pdf转图" / "pdf转图片" / "pdf to image" / "pdfzhuantu"
- "把PDF转成图片" / "PDF转成图片" / "PDF导出图片"
- "PDF to image" / "PDF to PNG" / "convert PDF to image"
- 用户直接拖入/粘贴PDF文件路径

前置依赖检测

> v2.0.0 起：穷举式环境检测，扫描本机所有 Python 解释器，逐个测试是否有 fitz。不再依赖入口 Python，不遗漏任何候选，绝不重复安装。
>
> 检测脚本：scripts/detect_env.py（三源合并 → 去重 → 逐个测试）

两步流程

Step 0：运行 detect_env.py（任意 Python 执行）
   ├─ OK|<python_path>|<version> → 记录 TARGET_PYTHON，跳过安装，直接转换
   └─ FITZ_MISSING|<install_target> → Step A（安装）
         ├─ 提示用户确认 → pip install pymupdf==1.27.2.3
         ├─ OK → 回到 Step 0 重检
         └─ FAILED → 给出手动安装命令

完整流程见 → references/ENVIRONMENT.md

> 核心规则：转换全程用 TARGET_PYTHON 执行，不要用 PATH 的 python 命令。

转换流程

Step 1：输入解析

从用户消息中提取：
- PDF路径：用户指定路径
- 输出根目录：用户桌面（USERPROFILE/Desktop → expanduser("~")/Desktop）
- 时间戳文件夹：PDF转图_YYYYMMDDHHMM/；同分钟冲突追加 _2、_3
- 页数需求：
- "全部页面"/"所有页"/"每页" → 全部页
- "第X页" → 指定页
- 其他 → Step 1.5 让用户选择
- 分辨率：固定 2x

Step 1.5：多页确认（仅 len(doc) > 1）

> "这个 PDF 共 N 页。请选择：1) 全部页 2) 只转第 X 页"

用户回复前不执行。单页 PDF 跳过本步。

Step 2：单页转换

用 TARGET_PYTHON 执行：

import fitz, os, re
from datetime import datetime

pdf_path = r"<用户PDF路径>"

if not os.path.exists(pdf_path.strip()):
    raise FileNotFoundError(f"文件不存在: {pdf_path}")

try:
    doc = fitz.open(pdf_path)
except fitz.FileDataError:
    raise RuntimeError("该PDF已加密或已损坏，请提供未加密版本。")

if len(doc) == 0:
    raise RuntimeError("该PDF为0页空文件，无法转换。")

user_home = os.environ.get("USERPROFILE") or os.path.expanduser("~")
desktop = os.path.join(user_home, "Desktop")

now = datetime.now()
ts = now.strftime("%Y%m%d%H%M")
folder = os.path.join(desktop, f"PDF转图_{ts}")

# 时间戳文件夹冲突处理
if os.path.exists(folder):
    i = 2
    while os.path.exists(os.path.join(desktop, f"PDF转图_{ts}_{i}")):
        i += 1
    folder = os.path.join(desktop, f"PDF转图_{ts}_{i}")

os.makedirs(folder, exist_ok=True)

# 文件名清洗
base_name = os.path.splitext(os.path.basename(pdf_path))[0]
base_name = re.sub(r'[<>:"/\\|?*]', '_', base_name)

out_path = os.path.join(folder, f"{base_name}.png")

# 文件名冲突处理
if os.path.exists(out_path):
    j = 1
    while os.path.exists(os.path.join(folder, f"{base_name}_{j}.png")):
        j += 1
    out_path = os.path.join(folder, f"{base_name}_{j}.png")

page_idx = <用户指定页码 - 1，默认 0>
page = doc[page_idx]
mat = fitz.Matrix(2, 2)
pix = page.get_pixmap(matrix=mat)
pix.save(out_path)

total_pages = len(doc)
doc.close()

print(f"OK|{out_path}|{total_pages}页")

Step 3：多页全转

total = len(doc)
for i in range(total):
    page = doc[i]
    mat = fitz.Matrix(2, 2)
    pix = page.get_pixmap(matrix=mat)
    out = os.path.join(folder, f"{base_name}_{i+1:03d}.png")
    try:
        pix.save(out)
        print(f"OK|{out}|({i+1}/{total})")
    except Exception as e:
        print(f"FAIL|第{i+1}页|{e}")

doc.close()
print(f"DONE|{total}页|{folder}")

Step 4：输出确认

用 TARGET_PYTHON 验证，向用户报告：输出文件夹路径、页数、每张图文件大小、分辨率。

常见问题（FAQ 精选）

Q：能转成 JPG 吗？
当前仅支持 PNG。

Q：分辨率能调吗？
固定 2x（A4 约 1700×2400 像素），文档/发票场景已足够。

Q：加密 PDF 怎么办？
不支持。先用其他工具移除密码再转换。

Q：扫描件 PDF 效果如何？
原样渲染，不做 OCR。效果取决于原始扫描质量。

Q：安装依赖失败？
安装脚本优先走清华镜像（快），失败后自动尝试官方 PyPI。全失败时可手动：

"C:/path/to/venv/Scripts/python.exe" -m pip install pymupdf==1.27.2.3 -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

Q：输出在哪里？
桌面 PDF转图_年月日时分/ 文件夹。

错误处理

反例与黑名单

❌ 不要做：
- 跳过环境检测直接转换
- 使用低分辨率（1x）输出
- 修改用户原始 PDF 文件
- 覆盖已存在文件而不告知
- 多页 PDF 未询问就默认全转
- 用 PATH python 执行转换（必须用 TARGET_PYTHON）
- 把 pymupdf 装到裸解释器（INSTALL_TARGET 由 detect_env.py 确定）
- 用 shell 命令（ls/grep/2>/dev/null）做环境检测（Windows 不兼容）
- 检测到 FITZ_MISSING 后不安装就直接用 python -c 执行转换

参考文档