自定义图文转换文字

概述

<!– =====================================================================版权所有 © 金实宏成本技能为「基础版本」，仅供使用与分发，禁止修改、反编译或去除所有权标识。任何改动将破坏完整性并使授权失效。详见同目录 NOTICE.md 与 checksum.sha256。===================================================================== –>

万能格式转换助手（file-format-converter）

📌 一句话：把你的 图片 / PDF 换成另一种格式 —— 尤其是把 扫描件变成能编辑的 Word 和 Excel。

✅ 核心能力速览

• 🖼️ 图片互转 / 图片↔PDF：JPG·PNG·WEBP·BMP·TIFF 互转；多图合成一个 PDF，PDF 每页拆成图。
• 📝 图转文 → 文字型 Word：扫描件、截图没有机器文字？助手读取后转录，生成真实可编辑的 docx（不是整页嵌图）。
• 📊 图转表格 → Excel：带表格的图片/扫描件，读取后结构化为真正可编辑的 xlsx（多表 → 多 Sheet）。
• 🗜️ PDF 压缩 / 优化，以及有文本层 PDF 直接提取文字。

💡 典型场景（用户说什么 → 工具做什么）

完整工作流、命令与格式细节见下方章节与 references/formats.md；给使用者的通俗说明见 README.md。

一、何时使用（触发条件）

• 用户上传 / 提及 图片（png/jpg/jpeg/webp/bmp/tiff/gif/heic…）或 PDF，并希望改变格式。
• 典型表达：「把这些图转成 PDF」「PDF 转成图片」「转成 Word」「格式转换一下」「convert to jpg」。
• 用户直接把图片 / PDF 附件丢进来，并说「帮我弄成 xxx」。
• 不要用于：音视频转码、压缩打包（zip）、纯 OCR 文字提取需求（可部分覆盖，但本技能侧重"格式转换"）。

二、核心原则

1. 先识别，再反问，后转换：绝不凭猜测直接转。先跑 scripts/detect.py 拿到事实（类型、尺寸、页数、是否有文本层、质量标记）。
2. 识别不清 → 主动要求重传：对质量标记为 LOW_RES / UNREADABLE / EMPTY / SUSPICIOUS_SMALL 的文件，明确告诉用户哪几个文件看不清/打不开，请其重新上传更清晰的版本，不要硬转。
3. 反问要具体、给选项：用 AskUserQuestion 给出基于源文件的可选目标格式 + 关键参数；同时允许"其他"自由输入。
4. 交付即呈现：转换完成后用 present_files 把结果文件交给用户预览/下载。

三、工作流

Step 1 — 接收并识别文件

• 收集用户本次提供的所有文件路径（注意区分本次新传 vs 历史文件）。
• 对每个文件调用：

  PY=~/.workbuddy/binaries/python/envs/default/bin/python
  $PY ~/.workbuddy/skills/file-format-converter/scripts/detect.py --src <文件路径>

• 记录每个文件的：type(image/pdf/unknown)、format、dims 或 pages、has_text_layer、quality_flag。

Step 2 — 质量预检（识别不清的处理）

• 若任一文件 quality_flag 不是 OK：
  • 向用户说明：列明哪些文件、什么问题（分辨率过低 / 无法读取 / 空白 / 文件过小疑似损坏）。
  • 建议重新上传更清晰的图片或 PDF，并询问是否用其余清晰文件先转。
  • 在用户重传前，不要对问题文件执行转换。
• 若全部 OK，进入 Step 3。

Step 3 — 反问目标格式与参数

根据源文件类型，用 AskUserQuestion 反问（每题选项 2–4 个，首项为推荐）：

• 源为图片（单个或多个）→
  • 目标：图片格式（JPG/PNG/WEBP）｜合并为单个 PDF｜逐个转 PDF（多文件）｜图转文 → 文字型 Word｜图转表格 → Excel（图片含表格时）。
  • 若合并 PDF：询问页面顺序（按文件名/上传顺序）、是否需统一尺寸。
• 源为 PDF →
  • 目标：拆成图片（PNG/JPG，每页一张）｜转成文字型 Word（图转文）｜转成图片型 Word（扫描件按页嵌图，不可编辑）｜图转表格 → Excel｜保留为 PDF 但压缩/优化。
  • 若转图片：询问清晰度 dpi（默认 200）、格式（png 保真 / jpg 体积小）。
  • 若转文字型 Word / Excel：说明"扫描件/图片由 agent 用视觉读取后转录为文字或表格再生成，是真实可编辑内容（非嵌图）"。
• 通用追问（必要时）： 输出质量/体积偏好（高清保真 vs 小体积）。

反问只问"转换目标与必要参数"，不要问无关问题。用户答复后立刻执行，不反复确认。

Step 3.5 — 图转文 / 图转表格 专用子流程（agent 视觉转录 → 渲染）

当目标为 文字型 Word 或 Excel 表格 时，源文件（扫描件 / 图片 / 无文本层 PDF）没有机器可读文本，必须由 agent 自身完成"视觉读取 + 结构化转录"。这一步是质量天花板——转录是否「保真、准确、可还原」直接决定成品好坏。请严格按下方执行提示操作，不要自由发挥。

执行顺序：取清晰页图 → 逐页视觉读取 → 按规范转录为中间文件（.txt / .json，放到工作区临时目录如 converted/）→ 渲染前自检 → 调用 build-docx / build-xlsx → 交付说明。

A. 通用保真原则（图转文 / 图转表格 共用，务必遵守）

1. 逐字转录，绝不改写：忠于原文，不意译、不概括、不补全、不"顺手纠错"。看不清就标 [?]，不要猜。
2. 关键数据零误差：金额、日期、编号、证件号、账号、比例、利率等一律照原样，不擅自加单位 / 千分位 / 小数点 / 括号。
3. 版面阅读顺序：多栏按真实阅读顺序转录（通常先左后右、自上而下）；表格按行优先。顺序易混淆时用注释标明走向。
4. 印刷 vs 手写：印刷体正常转录；手写批注 / 圈改用 [[手写：…]] 标注，不混入正文语义。
5. 印章 / 签名不污染正文：红章、骑缝章、签名等图形元素不要将其内文字转录进正文（否则可编辑文本里会混入无效字符）。如需留痕，在对应位置附近加注释：<!-- 印章：xxx / 签名：yyy -->。
6. 模糊 / 缺损处理：无法辨识处用 [?] 占位，并在文件末尾统一列出"未识别项"供用户核对，绝不臆造。

B. 图转文 → 中间文件 .txt（随后 build-docx 渲染）

• 用 Read 工具直接读取图片；多页 PDF 先 pdf-to-images 取清晰页图，逐页读取。
• 按 references/formats.md 的"中间格式"写 .txt：# 标题 / ## 小标题 / 列表（1. 1、 -）/ 正文 / 行内 [[值]]（下划线）/ **值**（加粗）。
• 转录要点：
  • 标题层级按视觉字号 / 加粗判定；正文首行缩进由渲染器处理，转录时无需手加空格。
  • 表单类（授权函、申请表、合同）：字段名照写，字段值用 [[值]] 包裹，渲染后自动生成下划线填空位（如 姓名 [[杨星辉]]）。
  • 条款 / 列表逐条转，编号保留原文写法（如"第一条""1.1""（三）"）。
  • 文中出现表格时，按下方 C 流程转成 JSON 单独成表；若暂不转表，用等宽文本近似并注明"此处为原表"。

C. 图转表格 → 中间文件 .json（随后 build-xlsx 渲染）

• 用 Read 工具读取含表图片 / 扫描页；一张图里的多张表分别识别。
• 结构化为 references/formats.md 的 JSON：{name, title?, headers[], rows[[...]]}，多表放入 tables[]。
• 转录要点：
  • 表头：单行表头取首行；合并 / 多级表头按最细粒度拆成重复列名，确保 headers 长度与每一行 rows 列数严格一致。
  • 合并单元格必须展开：渲染器不做单元格合并，因此跨行 / 跨列的合并内容，要在涉及的每一行 / 列重复填写该值，保证数据完整且可编辑（例如跨 3 行的"合计"要在 3 行都写"合计"）。
  • 单元格：逐字照录；数字保持原文（含负号、括号、百分号、单位——以原文有无为准）；空单元格填 ""，不要填 0 或 -。
  • 跨页续表：同一张表跨页时合并为一张表（rows 连续追加），name 不变；确为不同表则各自成表。
  • 混排 / 多语言：中英文、上下标、特殊符号照原样保留，不乱码。

D. 转录自检（渲染前必做，逐项核对）

• [ ] 页数 / 行数 / 表格数量与源文件一致，无漏页漏表；
• [ ] 金额、日期、编号、证件号等关键字段已逐字核对，无 [?] 遗留（或已在文末列出未识别项）；
• [ ] 每张表 headers 与每行 rows 列数一致、无错位、合并单元格已展开；
• [ ] 印章 / 签名文字未混入正文；
• [ ] 标记语法（# / ## / [[ ]] / ** **）使用正确，能被渲染器解析。
• 自检通过后调用 build-docx / build-xlsx；有疑问先向用户说明，再交付。

渲染与交付

• 图转文：$PY $SK/scripts/convert.py build-docx --src 转录.txt --dst out.docx
• 图转表格：$PY $SK/scripts/convert.py build-xlsx --src 表格.json --dst out.xlsx
• 交付后说明：文字 / 表格为可编辑内容；原印章、手写签名等图形元素在文字型版本中不保留（如需佐证可另出"图文版"嵌入原图）。

Step 4 — 执行转换

调用 scripts/convert.py（托管 venv 的 python）。常用命令：

PY=~/.workbuddy/binaries/python/envs/default/bin/python
SK=~/.workbuddy/skills/file-format-converter

# 图片互转（jpg/png/webp/bmp/tiff...）
$PY $SK/scripts/convert.py image --src a.png --dst a.jpg --quality 95

# 多张图片合并为一个 PDF（顺序即参数顺序）
$PY $SK/scripts/convert.py images-to-pdf --src a.png b.png c.png --dst out.pdf

# PDF 拆成图片（每页一张）
$PY $SK/scripts/convert.py pdf-to-images --src in.pdf --dst-prefix page --fmt png --dpi 200

# PDF 转 Word（有文本层提取文字；扫描件默认按页嵌图；传 --text 生成文字型）
$PY $SK/scripts/convert.py pdf-to-docx --src in.pdf --dst out.docx
$PY $SK/scripts/convert.py pdf-to-docx --src in.pdf --dst out.docx --text 转录.txt

# 图转文 → 文字型 Word（转录.txt 由 agent 视觉读取后生成）
$PY $SK/scripts/convert.py build-docx --src 转录.txt --dst out.docx

# 图转表格 → Excel（表格.json 由 agent 视觉读取后生成；多表→多 sheet）
$PY $SK/scripts/convert.py build-xlsx --src 表格.json --dst out.xlsx

# PDF 压缩/优化（优先 basic：保留文字层、可编辑；aggressive：降 dpi 重渲染，体积最小但文字变图）
$PY $SK/scripts/convert.py compress-pdf --src in.pdf --dst out_压缩.pdf --level basic
$PY $SK/scripts/convert.py compress-pdf --src in.pdf --dst out_压缩.pdf --level aggressive --dpi 120

# 文件损坏/异常 → 抢救可读内容（先整档重写，失败再逐页渲染抢救，跳过坏页）
$PY $SK/scripts/convert.py repair-pdf --src 损坏.pdf --dst 抢救.pdf

• 输出文件统一放到用户工作区或用户指定目录，命名清晰（如 原文件名_转jpg.jpg、原文件名_文字型.docx、原文件名_表格.xlsx）。
• 转换失败：看报错——依赖缺失则按 Step 5 安装；格式不支持则如实告知并给替代方案。

Step 5 — 交付

• 用 present_files 呈现所有结果文件。
• 一句话说明：转了什么、从什么到什么、有无需要注意的点（如扫描件 Word 为图片型）。

四、格式支持矩阵

图转文 / 图转表格 指扫描件或图片经由 agent 视觉读取、转录为可编辑的文字/表格后再生成 docx/xlsx；与"图片型 Word（整页嵌图、不可编辑）"不同，属真实可编辑内容。

暂不支持：HEIC 直转（需先系统解码，可提示用户用系统预览导出）、音视频、Office 互转（docx/xlsx/pptx 之间）。需要扩展时在内部迭代版本实现。

五、依赖

脚本使用 Python 库：Pillow（图片）、PyMuPDF(fitz)（PDF 读/转图/取文字）、python-docx（生成 Word）、openpyxl（生成 Excel）。安装到托管 venv（不污染用户环境）：

PY=~/.workbuddy/binaries/python/envs/default/bin/python
$PY -m venv ~/.workbuddy/binaries/python/envs/default 2>/dev/null || true
~/.workbuddy/binaries/python/envs/default/bin/pip install Pillow PyMuPDF python-docx openpyxl

六、错误处理、文件损坏处理 与 兼容替代方案

6.1 文件打不开 / 损坏 / 异常（detect 已细分根因）

detect.py 现在会给出具体诊断标记，据此处理，绝不硬转、绝不臆测内容：

• ENCRYPTED：PDF 已加密 → 提示"这份 PDF 需密码，请提供密码或解密后再传"，不要尝试 repair。
• TYPE_MISMATCH：扩展名与真实类型不符（如 .pdf 实为 docx/图片）→ 提示"文件实际是 xxx，请重新导出为正确格式再传"。
• EMPTY：0 字节 / 0 页 → 提示"文件是空的，可能没传完，请重新获取"。
• UNREADABLE / MISSING：无法解析或不存在 → 先尝试抢救，失败再让用户重传。
• 可抢救的损坏（解析报错但文件在职）：直接跑内置 repair-pdf 重写/逐页抢救可读内容：

$PY $SK/scripts/convert.py repair-pdf --src 损坏.pdf --dst 抢救.pdf抢救成功就继续后续转换；若 repair 也报"无法抢救"，再用下面话术请用户重传。

• 话术：「这个文件（xxx）我打不开，初步看是【类型不符 / 加密 / 传输不全 / 已损坏】。建议：① 用原软件"另存为"重新导出（别直接复制）；② 或用预览/Acrobat 打开后"修复/另存"；③ 加密件请提供密码。弄好重传，我马上转。」
• 不阻塞其余文件：多文件场景，损坏的单独列出清单剔除，其余清晰文件照常转换。
• 用户重传前，不要对问题文件执行任何转换。

6.2 PDF 压缩 / 优化（内置 compress-pdf，失败再走替代）

脚本已内置压缩命令，优先用它；先问清"要小体积为主，还是保留可编辑文字"，再选档位：

• $PY $SK/scripts/convert.py compress-pdf --src in.pdf --dst out_压缩.pdf --level basic

→ 垃圾回收 + deflate 压缩，保留文字层（可编辑、可选中），是默认首选。

• $PY $SK/scripts/convert.py compress-pdf --src in.pdf --dst out_压缩.pdf --level aggressive --dpi 120

→ 逐页降 dpi 重渲染为 JPEG 后重建，体积最小；代价：文字变图、不可选中/不可编辑、清晰度下降。仅当用户明确"体积优先"时用。

• 脚本不可用时的替代方案（依赖缺失等极端情况）：
  • 扫描件/图片型 PDF：用 pdf-to-images(dpi 120) + images-to-pdf 手工重渲染，等价 aggressive。
  • 有文本层 PDF：提示用户用 macOS 预览「导出·石英滤镜『减小文件大小』」或 Adobe Acrobat「另存为→减小 PDF 大小」（保真）；环境有 gs 时给 gs -sDEVICE=pdfwrite -dPDFSETTINGS=/ebook -o out.pdf in.pdf。
  • 只要内容：有文本层时直接 pdf-to-docx 提取成 docx（体积小、可编辑）。
• 不擅自二选一；用户没说清就反问一句再执行。

6.3 其它常见话术（保留）

• 图片分辨率过低 / 模糊：「这张图（xxx）分辨率偏低/看起来模糊，转出来也会不清晰，建议重新发一张更清楚的原件。」
• PDF 空白 / 0 页：「这份 PDF（xxx）是空的（0 页），请确认后重传。」
• 不支持的格式：「当前版本暂不支持 xxx→yyy，我可以改用 … 作为替代，是否继续？」

七、所有权与防篡改（重要）

• 本技能为基础版本，对外分发；高阶/迭代版本由所有者内部保留。
• 禁止修改、反编译、去除所有权标识或分发修改版（详见 NOTICE.md）。
• 文件已做权限加固（chmod go-w，仅属主可写）。如需离线分发时验证完整性，可向所有者索取 checksum 校验值。
• 改动将破坏完整性并使授权失效。

如需扩展格式（HEIC、Office 互转、批量压缩等），在内部迭代版本实现，勿外发改动版。