Name: doc-to-markdown
Author: daymade/claude-code-skills

1实现原理 · 为什么它能做到

功能由『Pandoc 抽取 + 增值后处理』两层实现：SKILL.md 把架构一句话写死，声称价值在 8 项 DOCX 后处理而非转换本身。

daymade-docs/doc-to-markdown/SKILL.md

**Architecture**: Pandoc (best-in-class extraction) + 8 post-processing fixes (our value-add).

注：convert.py 先按扩展名选工具（DOCX→pandoc、PDF→pymupdf4llm、PPTX/XLSX→markitdown），再对 pandoc/pymupdf4llm 输出做正则级清洗，把引擎私有语法（grid table、{width=...} 属性、media/media/ 路径嵌套等）标准化成通用 markdown。

工具选择被 Quick/Heavy 双模式路由：Quick 单工具快跑，Heavy 多工具并行、逐段（表格/图片/标题/列表/段落）按质量评分择优合并。

daymade-docs/doc-to-markdown/SKILL.md

| PDF | pymupdf4llm | pymupdf4llm + markitdown |

注：同一表格下方 DOCX 行是 pandoc → pandoc+markitdown；Heavy 模式的并行执行与 merge 标准在同文件 'Heavy Mode Workflow' 节（'Parallel Execution: Run all applicable tools simultaneously'）。

DOCX 后处理逐类有测试背书：8 项清洗（grid/simple 表格、图片路径、pandoc 属性、CJK 加粗间距、缩进代码块、转义括号、双括号链接）在 SKILL.md 表格中与 TestPostprocessPipeline / TestCjkBoldSpacing(15 cases) 等测试一一对应。

daymade-docs/doc-to-markdown/SKILL.md

| Grid tables (`+:---+`) | Single-column → blockquote, multi-column → pipe table | `TestPostprocessPipeline` |

注：CJK 加粗间距是 DOCX run 级样式与 markdown 渲染器之间的已知摩擦点，这里用『span 含 CJK 字符即两侧补空格』的启发式规则解决——这是把中文排版知识代码化的典型做法。

PDF 后处理（2026-08-30 起）做三件事：剥 Tesseract OCR 垃圾块、跨页去重复页眉/页脚/水印行（同一条规范化行出现在 ≥60% 页面即判定）、把绝对图片路径改相对。

daymade-docs/doc-to-markdown/SKILL.md

Repeated header/footer/watermark lines (same normalized line on ≥60% of pages, incl. diagonal watermarks) | Detected via pymupdf cross-page scan, removed from markdown; bold-wrapped and merged-with-page-number variants also caught | `TestRepeatingLines`

注：去水印/页眉依赖 pymupdf 跨页统计（_detect_repeating_lines），不是纯文本处理；SKILL.md 同时诚实列出已知局限（重复段落、点线目录被当表格、跨页表格不合并等）。

质量闭环由 validate_output.py 支撑：按文本/表格/图片保留率给出 Pass/Warn/Fail 阈值，并可输出 HTML 报告。

daymade-docs/doc-to-markdown/SKILL.md

| Text Retention | >95% | 85-95% | <85% |

注：该脚本用 pdftotext 抽取 PDF 文本后与输出 markdown 比对（scripts/validate_output.py 内 subprocess.run(['pdftotext','-layout',...])），量化『转换有没有丢东西』。

best-in-class(7.6/10) 声明由仓库内基准文档支撑：对 Docling/MarkItDown/Pandoc/Mammoth 逐维度打分，结论是 pandoc 底座+后处理层。

daymade-docs/doc-to-markdown/references/benchmark-2026-03-22.md

| 维度 | Docling (IBM) | MarkItDown (MS) | Pandoc | Mammoth | **doc-to-markdown（我们）** |

注：SKILL.md description 与 benchmark 文件互相印证；README 对该文档族的定位是『benchmark-first』的开发文化。

2核心能力

01DOCX/PDF/PPTX/XLSX → 高质量 Markdown 单命令转换（Quick 模式默认）

02pandoc 产物 8 项自动清洗（grid/simple 表格、属性噪声、图片路径、CJK 加粗间距、代码块、转义、双括号链接）

03PDF 水印/页眉/页脚/OCR 垃圾自动剥离与图片路径可移植化

04Heavy 模式多工具并行+分segment 质量合并（表格行数/图片 alt/标题层级等准则）

05PDF 图片抽取（带页码/坐标/尺寸元数据与 markdown 引用文件）

06转换质量验证与 HTML 报告（文本/表格/图片保留率三档阈值）

07Windows/WSL 路径换算辅助

3外部依赖

类型	依赖
cli	pandoc
cli	markitdown CLI（markitdown[pdf]）
package	pymupdf4llm / pymupdf（uv --with 拉取）
cli	pdftotext / pdftoppm（poppler，校验脚本用）

4风险提醒风险提醒：蓝色 · 知晓即可

风险提醒：蓝色 · 知晓即可

依赖大量第三方引擎且需各自安装/拉取 — pandoc 系统级安装、pymupdf4llm/markitdown 走 uv 拉取；离线环境 Quick 模式也可能不可用，需先预置。多引擎=多版本行为漂移。
后处理是正则/启发式，边界情况会漏或误改 — SKILL.md 自列局限：重复段落不修、目录页被当表格、跨页表格不合并、水印字 shard 残留——文档转换无完美解，需人工 spot-check。
7.6/10 是内部基准自评 — benchmark 由本仓库作者执行，非独立评测；比较口径（版本/文档集）可能随时间漂移。
文档型输入面 — 解析不可信 docx/pdf/pptx 依赖第三方解析器，宿主应把输入当作不可信文档处理。

风险提醒：蓝色，知晓即可。纯本地转换管线：只调用本地 CLI/Python 库，无运行期网络外发、无凭证读取；对用户文档做读写是功能本质。首次环境预置需联网 PyPI（uv --with），外发对象为官方包源、可预期。

5第二遍独立确认

[ok] 架构=Pandoc+8 后处理 — SKILL.md 原文与 convert.py 的 tool_map/pandoc 调用路径吻合；8 项清洗在 DOCX Post-Processing 表逐行列出。
[ok] CJK 加粗间距规则 — 规则原文（含 CJK 即两侧补空格）在 SKILL.md 'CJK Bold Spacing — why and how' 节，测试类 TestCjkBoldSpacing 存在。
[ok] PDF 水印剥离用 pymupdf 跨页扫描 — SKILL.md 声称 + convert.py _detect_repeating_lines 内 import pymupdf、doc=pymupdf.open(...) 属实。
[ok] Heavy 模式并行多工具 — SKILL.md 'Run all applicable tools simultaneously' + 分 segment 评分合并准则表均在。
[ok] 质量阈值 95/100% 等 — validate_output.py 存在 pdftotext 子进程调用，SKILL 阈值表为文档化契约。
[ok] 7.6/10 best-in-class 声明 — references/benchmark-2026-03-22.md 含 5 工具维度评分表与 '综合最优' 结论；评分口径为内部基准、非独立第三方评测——已注明。
[ok] 无网络外发/无凭证 — convert.py/validate_output.py/merge_outputs.py/extract_pdf_images.py 全量扫描：无 requests/urllib/http 调用点（仅测试 fixture 的 example.com 文本）；无 environ 凭证读取。
[ok] 元数据核对 — GitHub API：MIT、1385 stars、pushed 2026-09-09T12:33:29Z；本地 git HEAD == d5c4678cb5d4 == pin。

6结论

引擎选择有实测基准背书，后处理逐项钉测试，宣称的 8+3 项清洗都可从代码定位。

把中文排版知识（CJK 加粗间距、代码块 CJK）代码化，是同类转换工具少见的本土化增量。

Heavy 模式把『多工具竞争择优』做成可用功能，弥补单引擎短板（表格、图片保留）。

诚实记录已知局限（62 页研报的 5 类不自动修问题），交付期望管理好。

适合：适合需要『文档→可编辑 markdown』且对中文排版/表格/图片保留有要求的场景（研报、合同、书稿、技术文档批量转换）；作者维护积极、含测试，适合接入生产流水线。Heavy 模式留给版式复杂的终稿。

不适合：不适合追求像素级还原的 PDF 版式需求（那是 pdf-to-html/pdf-creator 的方向）；不适合无 uv/无网络的环境（依赖预置成本高）；水印极重的 PDF 与纯扫描件（无文本层）超出能力，需先 OCR。

安装 agent 直装可复制

① 本站镜像更新 2026-09-09

方式 A · 人下载镜像包下载 doc-to-markdown.tar.gz

sha256: 71b6589924471f21…

方式 B · JSON 格式安装指南，复制给 agent

安装指南

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② 上游 GitHub · 原始来源

能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗

本页镜像锁定 commit d5c4678cb5；上游为实时仓库。

来源信息 GitHub 原始

作者 / 仓库daymade / daymade/claude-code-skills

原始 GitHubdaymade/claude-code-skills ↗

Stars1385

最近推送2026-09-09

本 skill commitd5c4678cb5

本站信息

收录日期2026-09-06

分类文档与知识

侦查报告AI 侦查 · 2 遍 · 2026-09-06

本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。

doc-to-markdown

1实现原理 · 为什么它能做到

2核心能力

3外部依赖

4风险提醒 风险提醒：蓝色 · 知晓即可

5第二遍独立确认

6结论

4风险提醒风险提醒：蓝色 · 知晓即可