doc-speedreader

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

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 是否已装：

   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 模板填好，直接在对话里输出。

选项 C · 完整 Markdown 副本

AI 写到本地：

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

---

失败兜底（5 段式）

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

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

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

---

核心命令速查

# 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。

---

相关文档（仅本 skill 内部）

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