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)