# Doc Speedreader

> 把任意文档（PDF/Word/PPT/Excel/图片/音频/HTML/CSV/ZIP/EPUB/YouTube URL 等 15+ 格式）一键转成 Markdown，并按需生成一句话总结 / 结构化摘要 / 完整副本。基于 Microsoft MarkItDown。触发词：「帮我速读这份 PDF」「这个文件讲什么」「转成 Markdown」「给我摘要」「文档转一下」「加快读文档」「读得更快」「读这个文档」「文件里讲了什么」。

- Skill: `coderwanfeng/doc-speedreader` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add coderwanfeng/doc-speedreader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coderwanfeng/doc-speedreader/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: coderwanfeng (https://skillmd.com/u/coderwanfeng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/coderwanfeng/doc-speedreader

---


# doc-speedreader · 速读侠（基于 MarkItDown 的快速读文档 skill）

> **目录名**：`doc-speedreader/`
> **中文名**：速读侠
> **依赖**：Microsoft MarkItDown（`pip install 'markitdown[all]'`）
> **Python**：≥ 3.10

> 把任意文档 → Markdown → 一句话总结 / 结构化摘要 / 完整副本
> **本 skill 完全独立**，不与其他 skill 做任何关联。

---

## 何时使用

✅ **使用本 skill 的场景**：

- 收到一份陌生文件（PDF / Word / PPT / Excel / 图片 / 音频）→ 想知道"这文件讲什么"
- 已经决定要读一个长文档 → 想快速定位"哪几页/哪几章是关键"
- 要把一份文档喂给另一个 LLM / 笔记软件 / RAG → 想拿到干净的 Markdown 副本
- 不想装 Office / Adobe → 想在命令行把 .docx / .pptx / .pdf 一次性转成可读的文本

❌ **不要使用**：

- 用户没说要读文档，只是普通聊天
- 用户明确说"我要细读 / 我要全文"——本 skill 默认只给摘要，给全文是次选
- 用户要 OCR 扫描件 → 本 skill 默认不做 OCR（写进 troubleshooting 引导去装 `markitdown-ocr` 插件）
- 用户要"高保真排版给人看" → 本 skill 输出的是为 LLM 设计的 Markdown，不是给人眼的排版

---

## 交互流程（3 轮强制 + 1 轮可选）

### 第 1 轮 · 开场 + 收集输入

**AI 主动说**：

```
你好，我是「速读侠」。
我能把任意文档（PDF / Word / PPT / Excel / 图片 / 音频 / HTML / CSV / ZIP / EPUB / YouTube 链接 等 15+ 格式）
一键转成 Markdown，然后给你：

A. 一句话总结 + 3 个关键点（10 秒看完）
B. 结构化摘要（30 秒看完）
C. 完整 Markdown 副本（你自己拿走用）

请把文件丢给我（拖入 / 给路径 / 给 URL 都行）。
如果有具体需求一起说（比如"只要 TL;DR"或"摘要第 3 章"）。
```

**用户回答**：拖文件 / 给路径 / 给 URL

**AI 内部动作**：

1. 检查 `markitdown` 是否已装：
   ```bash
   python3 -c "import markitdown; print('OK')" 2>/dev/null || bash scripts/install.sh
   ```
2. 调 `scripts/convert.sh <file>` 拿 Markdown 全文
3. 统计字数和章节数：
   - 文件 > 5000 字 → 在对话里分段贴出关键段（避免一次贴爆上下文窗口）
   - 文件 < 5000 字 → 全文回灌到对话里
4. 给出"已转好"的回执（字数 + 章节数 + 格式类型）

---

### 第 2 轮 · 选产物类型（自动给推荐）

**AI 给出选项**：

```
已转成 Markdown（共 N 字 / M 个章节 / 格式：PDF）。
你接下来想要哪一种？

A. ⭐ TL;DR（一句话总结 + 3 个关键点，10 秒看完）
B. 结构化摘要（标题 + 每章要点 + 数据点 + 行动项，30 秒看完）
C. 完整 Markdown（保存到 skills/doc-speedreader/task/YYYYMMDD-<slug>/<原文件名>.md）
D. 别的（你说，比如"只摘要第 3 章"或"先看第 5-10 页"）

默认走 A——你要 A 吗？
```

**关键决策**：

- 用户说"A" / "默认" / "TL;DR" / 不回答 → 走 A
- 用户说"B" / "结构化" / "摘要详细点" → 走 B
- 用户说"C" / "给我原文" / "完整版" / "Markdown" → 走 C
- 用户说"D" + 自定义 → 按用户要求做

---

### 第 3 轮 · 交付

#### 选项 A · TL;DR

**AI 直接在对话里给**：

```
📌 TL;DR：{一句话总结}

🔑 3 个关键点：
1. {要点 1}
2. {要点 2}
3. {要点 3}
```

**不要**主动推荐其他 skill / 工具。任务到此结束。

#### 选项 B · 结构化摘要

**AI 按 [templates/summary-template.md](templates/summary-template.md) 模板填好**，直接在对话里输出。

#### 选项 C · 完整 Markdown 副本

**AI 写到本地**：

```bash
TASK_DIR="skills/doc-speedreader/task/$(date +%Y%m%d)-<slug>"
mkdir -p "$TASK_DIR"
# 把 Markdown 全文写到 $TASK_DIR/<原文件名>.md
```

**AI 给出路径回执**：

```
✅ 已保存到：skills/doc-speedreader/task/20260716-my-report/report.md
（共 12345 字 / 8 章节）

需要的话你可以直接 cat 这个文件，或者复制到任何你想用的地方。
```

**不要**主动把这份 Markdown 喂给别的 skill / 工具。用户问"接下来呢"时，只回答"任务结束"。

---

### 第 4 轮（可选）· 用户追问

- 用户追问细节（"第 3 章是什么意思" / "X 数据从哪来"）→ 在已转好的 Markdown 上下文里直接回答
- 用户说"够了" / "谢谢" → 收工
- 用户说"再读一份" → 跳回第 1 轮

---

## 边界 & 安全

| 行为 | 是否执行 | 说明 |
|---|---|---|
| 把任意本地文档转 Markdown | ✅ | 核心功能 |
| 把任意 URL 转 Markdown | ✅ | 走 `convert()` 带 10s 超时 |
| 接受 stdin 数据流 | ✅ | 走 `convert_stream()` |
| 接受用户预先 fetch 的 Response | ✅ | 走 `convert_response()` |
| 默认开 LLM 图像描述 | ❌ | 避免要 OpenAI key |
| 默认开 Azure Document Intelligence | ❌ | 99% 用户用不到 |
| 默认开 OCR 插件 | ❌ | 见 troubleshooting 引导 |
| 多文件批量处理 | ❌ | v1 一次一个文件，用户多次调用 |
| 把本 skill 的 Markdown 喂给别的 skill | ❌ | **本 skill 不做下游联动** |
| 推荐其他 skill 给用户 | ❌ | **本 skill 完全独立** |

### 路径安全（convert_local 已自带，但 AI 也应警觉）

- 拒绝 `/etc/` `/var/` `/root/` 等系统目录
- 拒绝 `~/.ssh/` `~/.aws/` 等敏感目录
- URL 限制：`http` / `https` only，拒绝 `file://` `ftp://` 等
- 见 [reference/safety.md](reference/safety.md)

---

## 失败兜底（5 段式）

> 当 `convert.sh` 抛错、依赖缺失、Python 版本过低时，AI 按 5 段式回应用户：

1. **原文**：贴出报错最后 1-2 行
2. **人话**：用 1 句大白话解释"发生了什么"
3. **根因**：技术层面的真正原因
4. **3 步**：用户能立刻执行的 3 个具体动作
5. **兜底**：本 skill 无能为力时的退路（如"换工具"或"再试一次"）

完整 8 个常见报错的 5 段式回答见 [reference/troubleshooting.md](reference/troubleshooting.md)。

---

## 核心命令速查

```bash
# 1. 安装（一次性）
bash scripts/install.sh

# 2. 转本地文件
bash scripts/convert.sh /path/to/file.pdf

# 3. 转 URL
bash scripts/convert.sh https://example.com/doc.docx

# 4. 转 stdin（需要先知道扩展名）
cat file.pdf | bash scripts/convert.sh --stream .pdf

# 5. 走预先 fetch 的 Response
bash scripts/convert.sh --response https://example.com/doc.pdf
```

详细文档见 [reference/quickstart.md](reference/quickstart.md)。

---

## 相关文档（仅本 skill 内部）

- **快速上手**：[reference/quickstart.md](reference/quickstart.md)
- **15+ 格式矩阵**：[reference/formats.md](reference/formats.md)
- **安全约束**：[reference/safety.md](reference/safety.md)
- **失败兜底 8 例**：[reference/troubleshooting.md](reference/troubleshooting.md)
- **摘要模板**：[templates/summary-template.md](templates/summary-template.md)
- **维护说明**：[README.md](README.md)