coderwanfeng 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 内部动作：
- 检查
markitdown是否已装：python3 -c "import markitdown; print('OK')" 2>/dev/null || bash scripts/install.sh - 调
scripts/convert.sh <file>拿 Markdown 全文 - 统计字数和章节数：
- 文件 > 5000 字 → 在对话里分段贴出关键段（避免一次贴爆上下文窗口）
- 文件 < 5000 字 → 全文回灌到对话里
- 给出"已转好"的回执（字数 + 章节数 + 格式类型）
第 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/httpsonly，拒绝file://ftp://等 - 见 reference/safety.md
失败兜底（5 段式）
当
convert.sh抛错、依赖缺失、Python 版本过低时，AI 按 5 段式回应用户：
- 原文：贴出报错最后 1-2 行
- 人话：用 1 句大白话解释"发生了什么"
- 根因：技术层面的真正原因
- 3 步：用户能立刻执行的 3 个具体动作
- 兜底：本 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