# Resource To Markdown

> 把任意格式资源（PDF/EPUB/视频/音频/HTML/docx/txt）以最佳质量、最快速度转成按章节拆分的 markdown。当用户说"转 markdown"、"把这本书转成 md"、"转录这个视频"、"处理这个 PDF"时触发。带三层 harness 兜底保证成功率。

- **Type:** Skill
- **Install:** `agentstack add skill-q8886b-loom-ai-knowledge-network-resource-to-markdown`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [q8886b](https://agentstack.voostack.com/s/q8886b)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [q8886b](https://github.com/q8886b)
- **Source:** https://github.com/q8886b/loom-ai-knowledge-network/tree/main/skills/resource-to-markdown

## Install

```sh
agentstack add skill-q8886b-loom-ai-knowledge-network-resource-to-markdown
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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](https://github.com/q8886b)
- **Source:** [q8886b/loom-ai-knowledge-network](https://github.com/q8886b/loom-ai-knowledge-network)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-q8886b-loom-ai-knowledge-network-resource-to-markdown
- Seller: https://agentstack.voostack.com/s/q8886b
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.