Resource To Markdown

resource-to-markdown Skill

何时触发

• 用户给一个任意格式文件，要求转成 markdown
• 用户要"消化一本书/PDF/视频"且没有现成 markdown
• Loom 的 DIGEST 流程第 0 步需要前置转换时
• 批量处理 sources// 下的资源

核心承诺

• 任意格式：PDF（文本型 + 扫描型）、EPUB、视频/音频、HTML、docx/pptx、markdown/txt
• 最佳质量：按格式选最佳引擎（pymupdf/docling/rapidocr/pandoc/markitdown/faster-whisper）
• 最快速度：文本型 PDF --out-dir=

指定音视频语言

python3.11 skills/resource-to-markdown/scripts/convert.py video.mp4 --out-dir=out --language=zh

不切章节（只产出 raw.md）

python3.11 skills/resource-to-markdown/scripts/convert.py file.pdf --out-dir=out --no-split

自定义章节大小

python3.11 skills/resource-to-markdown/scripts/convert.py book.epub --out-dir=out --min=1000 --max=30000

## 输出

每个文件产出 3 类输出到 `/`：

.raw.md # 原始转换（完整 markdown） .quality.json # 质量报告（引擎/字数/校验结果/警告） ch01.md, ch02.md, ... # 按章节切分（默认切，--no-split 跳过）

`quality.json` 关键字段：

```json
{
  "status": "ok|ok_with_warnings|quality_failed|convert_failed",
  "convert": {"engine": "...", "chars": ..., "strategy": "..."},
  "raw_summary": {"passed": ..., "failures": [...]},
  "unit_summary": {"passed": ..., "failures": [...]},
  "warnings": [...],
  "duration_sec": ...
}

路由策略（按扩展名 + 内容）

| 格式 | 主引擎 | 兜底 | |---|---|---| | .md/.txt | 直接复制（去 BOM、统一换行） | - | | .pdf（文本型，>50 字/页） | pymupdf sort=True | Docling → MarkItDown | | .pdf（扫描型， 30 字乱码字符占比 max_chars）按 H2 再切，仍超长按句号硬切

• 太短单元（` 时，扫描型 PDF 才可能通过 SSH/SCP 发往该主机；运行时会在 stderr 显示外发提示，并在成功或失败后清理远端临时目录。

与 Loom 集成

本 skill 是 Loom DIGEST 流程的第 0 步前置工具：

用户给资源 → resource-to-markdown → chXX.md → DIGEST-Scout 建主题卡 → DIGEST-Deep 产 L2 卡 → THINK 跨材料

PIPELINE.md（待写）会编排端到端流程。本 skill 单独可用。

文件结构

skills/resource-to-markdown/
├── SKILL.md                       # 本文档
├── scripts/
│   ├── convert.py                 # 主路由
│   ├── harness.py                 # 质量校验
│   ├── split_chapters.py          # 章节切分
│   └── handlers/
│       ├── pdf_handler.py         # PDF（pymupdf/Docling/tesseract/MarkItDown）
│       ├── epub_handler.py        # EPUB（markitdown/pandoc）
│       ├── html_handler.py        # HTML（pandoc/markitdown）
│       ├── office_handler.py      # docx/pptx（markitdown/pandoc）
│       ├── av_handler.py          # 音视频（ffmpeg + faster-whisper/whisper CLI）
│       └── text_handler.py        # md/txt（直接复制）
└── README.md                      # 详细说明

调试与扩展

单独测试某个 handler

python3.11 skills/resource-to-markdown/scripts/handlers/pdf_handler.py input.pdf out.md

添加新格式

1. 在 handlers/ 加 _handler.py，实现 convert(input, out_md) -> dict
2. 在 convert.py 的 EXT_MAP 注册扩展名
3. 在 estimate_min_chars 加字数估算
4. 测试 ≥ 2 个真实样本

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: q8886b
• Source: q8886b/loom-ai-knowledge-network
• License: MIT

Install and usage instructions live in the source repository linked above.