anydoc

Any Doc — 将办公文档转换为 GitHub 风格的 Markdown

anydoc 技能使用固定版本的 Any Doc CLI（@firecrawl/anydoc v0.2.4），将办公文档、电子表格、演示文稿、电子书、CSV 和基于文本的 PDF 转换为 GitHub 风格的 Markdown。所有格式共用一个文档模型和一个 GFM 序列化器，以生成相同的逻辑输出。本地转换无需服务、API 密钥或上传文件；托管 OCR 是单独的显式处理路径。

概述

当任务需要读取 Agent 无法直接读取的文档内容时，请加载此技能：例如，需要总结 Word 报告、将电子表格转换为表格、提取幻灯片内容、分析 CSV，或引用电子书或 PDF。

此技能附带一个小型 Python 辅助工具（scripts/anydoc），它封装了固定版本的 CLI，并增加了输入预验证、易懂的错误提示、批量转换以及 --dry-run/--json 输出。references/workflows.md 中的每个操作示例也都展示了原始 npx 调用，因此无论是否使用辅助工具，此技能都能正常工作。

首次使用决策关口

调用 anydoc 前，请先对请求进行分类：

如果用户需要……	执行此操作
获取现有受支持文档的内容	继续查看命令速查表。
生成、编辑、验证、打包 EPUB、抓取 HTML 或解密密码	停止使用此工具，并改用何时不应使用中列出的处理路径。
判断格式保真度或处理失败	选择命令前，先加载参考路由中对应的条目。
获取转换结果	选择标准输出、-o 或批量模式；运行后再按照验证进行检查。

硬性边界： 本地 anydoc 转换会读取现有的受支持文档并将其转换为 Markdown，不会上传文档。托管 OCR 仅限主动选择：它会将需要 OCR 的整个 PDF 发送到已配置的 Parse 服务。AnyDoc 不会创建、编辑、验证、打包、解密或抓取文档。

何时使用

• 将文档转换为 Markdown — Word、PowerPoint、Excel、OpenDocument、RTF、EPUB、CSV 或基于文本的 PDF。
• 提取结构 — 标题、GFM 表格、幻灯片标题、演讲者备注（作为引用块）和脚注。
• 将文档提供给大模型 — 一次性转换为简洁的 Markdown，用于摘要、信息提取或检索导入。
• 批量处理文件夹 — 转换目录中的多种办公文件，以用于知识库。
• 从标准输入读取文档 — 将字节流传入 anydoc -。

格式覆盖范围（摘要）

anydoc 通过 12 个规范解析器支持 8 类格式 / 21 个扩展名。规范格式为 doc, docx, odt, pdf, ppt, pptx, rtf, epub, xlsx, ods, odp, csv；扩展名别名会映射到这些格式（.docm→docx、.xls→xlsx、.pptm→pptx 等）。

类别	扩展名	预期的 GFM 输出	选择提示
Word	.doc .docx .docm	#–###### 标题、GFM 表格、[^n] 脚注	只需提取内容时使用；需要保留渲染后的版式时使用 documents。
PowerPoint	.ppt .pps .pot .pptx .pptm .ppsx .ppsm	幻灯片标题作为普通段落、项目符号列表、演讲者备注作为 > 引用块、GFM 表格（PPTX/ODP；旧版 .ppt 会将表格展平为文本行）	需要忠实保留表格？优先选择 PPTX 或 ODP；旧版 .ppt 会保留单元格文本，但不会保留表格结构。
Excel	.xls .xlsx .xlsm .xlsb	每个工作表使用 ## <sheet name> 标题和一个 GFM 表格；不保留数字格式（输出原始单元格值）	需要显示百分比、货币或数字格式？优先选择 ODS；XLS/XLSX 输出的是原始值。
OpenDocument	.odt .ods .odp	与 DOCX/PPTX 相同的文档/幻灯片结构；ODS 保留格式化后的显示值	当电子表格的显示格式会影响含义时，优先选择 ODS。
富文本格式	.rtf	与 DOCX/ODT 相同的文档结构	用于提取文本，不用于保留版式。
EPUB	.epub	# 章节标题、GFM 表格、内部锚点链接	用于阅读现有 EPUB；使用 epub 来创作或打包 EPUB。
CSV	.csv	一个 GFM 表格；类似标签的首行会提升为表头；自动检测分隔符；支持带 BOM 的 UTF-16	用于分隔符分隔的表格内容；如果输出有误，请检查分隔符和编码。
PDF	.pdf	标题 + 行内强调，但使用保真度较低的处理流程：表格会展平为文本，脚注和链接会有损。基于文本的 PDF 会在本地处理；扫描版/纯图像 PDF 则需要明确启用托管 OCR 或使用其他 OCR 工具	默认使用本地模式；托管模式会上传整个 PDF，且不能选择页面。

完整的各格式预期输出和保真度注意事项，请参见 references/formats.md；确切的错误消息（包括无 OCR 错误）请参见 references/errors.md。

命令对照表

命令均相对于仓库根目录。<file> 是任意文档路径（例如 anydoc/fixtures/fixture-handmade-outline.docx）；- 表示从标准输入读取文档。

需求	命令	适用场景
将单个文件转换为较小的 Markdown 并输出到标准输出	anydoc/scripts/anydoc convert <file>	调用方需要立即获取内容，且不需要保存生成的文件。
将单个文件转换为 Markdown 文件	anydoc/scripts/anydoc convert <file> -o out.md	输出内容较多、需要稍后审阅，或应作为文件留存。
将多个文件转换到一个目录	anydoc/scripts/anydoc batch <file1> <file2> ... --out-dir out/	请求涉及范围明确的批处理，且需要查看每个文件的输出和状态。
显示工具和固定的 CLI 版本	anydoc/scripts/anydoc info	在排查问题或报告环境问题前，需要确认可执行文件和版本。
原始固定版本 CLI，处理单个文档	npx -y @firecrawl/[email protected] <file> [-o out.md]	包装脚本不可用；保留固定版本的 CLI 及其文档所述语义。
原始固定版本 CLI，从标准输入读取	cat data.csv | npx -y @firecrawl/[email protected] - --format csv	数据已通过标准输入传入，且格式已知；将数据生成管道与转换器分开。

对于需要 OCR 的 PDF，首先使用本地默认方式，以便看到失败情况：

anydoc/scripts/anydoc convert scan.pdf --ocr reject

如果用户明确授权将完整 PDF 发送到 Firecrawl Parse，则在需要时使用包装脚本的确认参数和可信的 FIRECRAWL_API_KEY 环境变量：

anydoc/scripts/anydoc convert scan.pdf --ocr hosted --allow-hosted-upload

包装脚本绝不会将密钥放在命令行上。托管 OCR 不支持选择页面，且托管服务失败并不意味着可以在不告知用户的情况下切换端点。

注意：

• scripts/anydoc 是一个可执行的 Python 3 脚本（shebang #!/usr/bin/env python3）；如果无法使用可执行权限，运行 python3 anydoc/scripts/anydoc ... 效果相同。
• 原始的 npx -y @firecrawl/[email protected] 命令行是转换行为的权威依据；包装脚本会委托给完全相同的命令。
• 为确保转换结果可复现，始终固定使用 @0.2.4。-y 会以非交互方式回答 npx 的“是否继续？”提示；CLI 本身不会显示提示。
• 两种形式遵循相同的约定：每次调用处理一个文档，退出代码为 0 表示成功、1 表示转换或 IO 失败、2 表示用法错误；诊断信息以恰好一行 anydoc: <message> 的形式输出到标准错误，且不会显示提示。

0.2.4 版本的库和 CLI 支持托管 OCR，但包装脚本要求同时指定 --ocr hosted 和 --allow-hosted-upload，以免在未明确选择的情况下上传文件。由于无法选择页面，托管路线会将完整 PDF 发送到 Firecrawl Parse。不要将 API 密钥放在命令行上。

参考路由

只加载能回答当前问题的那一行；命令示例和验证约定保留在此文件中。

当你需要……	加载	其中解答了……
选择格式或预测保真度	references/formats.md	支持的格式系列、输出形态，以及注意事项，例如 XLSX 原始值、ODS 显示值、旧版 .ppt 表格展平和 PDF 降级。
选择标志、stdin 语法、输出行为或版本详情	references/cli-reference.md	原样帮助信息、接受的选项、stdin 规则、stdout/stderr 行为、版本固定和运行时要求。
对故障分类或决定是否重试	references/errors.md	退出代码、准确的错误词汇、无 OCR／加密边界，以及下一步处理方式。
选择单文件、stdin、批处理、vault 或大输出方案	references/workflows.md	端到端方案、安全的输出处理、逐文件故障路由，以及资源限制行为。
验证有文档记录的上游或 fixture 声明	references/sources.md	来源 URL、访问日期、fixture 来源，以及有文档记录的声明所依据的验证信息。
拟定最终证据报告	references/report-examples.md	遵循“验证”后可仿照的完整成功、预期失败和保真度边界报告。

何时不应使用

在使用转换命令前，先查看此路由表：

用户的请求	使用	原因
生成、编辑、检查渲染布局，或验证 PDF/Word/Excel/PowerPoint 工件	documents skill	anydoc 会将现有文档内容提取为 Markdown；它不会创作内容、保留渲染布局或验证工件。
打包或创作 EPUB	epub skill	anydoc 会将现有 EPUB 读取为 Markdown，但不会写入或验证 EPUB 容器。
对扫描版或纯图像 PDF 执行 OCR	本地 OCR 工具，或在明确授权后使用 AnyDoc 托管 OCR	本地模式会报告需要 OCR 的错误，不会上传文件；托管模式会将整个 PDF 发送到 Firecrawl Parse。
抓取 HTML 或其他网页内容	网页抓取 skill	HTML 不是 anydoc 支持的输入。
转录图像、视频或音频等二进制媒体	媒体或转录工具	嵌入图像会变成替代文本；anydoc 无法转录媒体。
保留分页、字体、模板或渲染布局	文档／布局工具	唯一的输出约定是 GitHub 风格 Markdown。
转换受密码保护的文件	由文档所有者提供的未加密副本	anydoc 没有密码或解密选项。

验证

报告证据，而不仅仅是成功。 对每次尝试的转换，都应返回输入、准确的命令或封装器路径、观察到的退出代码、输出目的地（stdout 或文件）、检查过的结构标记，以及任何有文档记录的注意事项或后续处理方式。

精简报告格式：

Input: <path or stdin source>
Command: <exact wrapper or pinned CLI path>
Exit: <observed code>
Output: <stdout or destination file>
Checks: <markers or fidelity facts observed>
Caveat/route: <documented limitation or next action>

常见停止条件

条件	不要	下一步
扫描版或仅含图像的 PDF / 需要 OCR 的错误	原样重试或默认上传	使用本地 OCR，或明确授权并运行 --ocr hosted --allow-hosted-upload；无法选择页面。
加密或受密码保护的文档	猜测密码或原样重试	请求未加密的副本，或由所有者授权后重新导出。
不支持、格式错误或超出资源限制的错误	猜测解析器或声称部分成功	在 references/errors.md 中匹配确切错误，并遵循其中限定的处理路径。
退出码为 0，但缺少预期的结构标记	仅凭退出码报告成功	检查输出结构和源文件保真度，再报告完成。

报告转换完成前，请先确认：

1. 检查退出码。 0 表示 CLI 已生成 Markdown。1 表示无法读取或转换文档——请读取 stderr 中唯一一行 anydoc: <message>，并在 references/errors.md 中匹配。2 表示命令本身存在用法错误（标志错误、缺少输入、--format 无效）。
2. 检查输出结构。 Markdown 必须包含相应格式实际生成的结构标记：
   • Word / ODT / RTF / 基于文本的 PDF：#/## 标题。对于 PDF，不要期待 GFM 表格或 [^1]: 脚注定义——该处理流程会将它们扁平化。
   • 电子表格（xlsx/xls/ods）和 CSV：以 | 分隔的 GFM 表格。xlsx/xls 显示原始单元格值（0.155、1234.5）；ODS 显示格式化后的显示值（15.5%、$1,234.50）。
   • 演示文稿（pptx/odp）：幻灯片标题为普通段落，> 引用块形式的演讲者备注，GFM 表格。旧版 .ppt 会将表格扁平化为纯文本行。
   • EPUB：# 章节标题和内部锚点链接。
3. 将大型输出写入文件，使用 -o。 -o out.md 可保持 stdout 静默，并生成便于审阅的文件，而不是将整个文档流式输出到上下文中。
4. 确认表格是否保留。 如果源文件包含表格，而输出中没有 | 行，请查阅格式注意事项——PDF 和旧版 .ppt 按设计会将表格扁平化，并非错误。

在转换以退出码 0 结束且结构标记与源格式相符时停止。对于有文档说明的失败模式（加密、格式错误、扫描版/仅含图像、不支持），如果不更改输入，不要重新运行或重试；请按 references/errors.md 中的说明报告相应消息和处理路径。