pdfmd

用途

pdfmd 是一个 PDF 转 Markdown 的转换 Skill（示例），目标是将 PDF 文件转换为结构化的中文 Markdown 文本。它只在用户明确要求“把 PDF 转成 Markdown / MD / 文本 / 文档”时使用。

何时使用：

用户说“把这个 PDF 转成 Markdown / MD / 文本 / 文档”。
用户上传或引用 PDF 文件，并要求“提取里面的正文”“翻译成中文 Markdown”等。

若用户只是一般性阅读或总结 PDF，而不要求导出 Markdown，则可以直接阅读 PDF 文本或使用其他技能，无需启用本技能。

工作目录结构

在当前示例项目中，本 Skill 所在目录如下：

workspace/
  skills/
    pdfmd/
      SKILL.md
      pdf_extract.py

其中 SKILL.md 为本说明文件；pdf_extract.py 是一个 Python 脚本，仅负责从 PDF 中提取纯文本（不调用任何大模型），再由当前 Agent 使用已有的大模型配置完成翻译和 Markdown 转换。

本 Skill 假设执行环境中已安装 Python 以及 pypdf 依赖。

主要能力

从 PDF 中提取纯文本，可选择页码范围。
借助当前 Agent 配置的大模型，将提取出的文本翻译成中文并整理为 Markdown 结构。
在用户明确要求时，将结果写入 Markdown 文件。
支持根据用户需求对 Markdown 结果做二次加工。

使用方式

使用时的操作步骤如下：

确认 PDF 文件路径。若用户提供路径（例如 docs/report.pdf），先确认该路径在当前工作区内；若用户上传了 PDF 文件，将其保存到本地工作目录（如 ./docs/），并记住实际路径。
选择输出路径。若用户希望生成 Markdown 文件，可选定输出路径，例如输入 docs/report.pdf、输出 docs/report.md。
使用 Bash 调用 Python 脚本提取 PDF 文本，示例命令（命令在沙箱工作目录 workspace/ 下执行，因此路径从 skills/ 开始）：

python skills/pdfmd/pdf_extract.py \
  --input "<PDF 文件路径>" \
  --pages "<页码范围，可选，如 1-3,5>"

参数说明：--input 为要读取的 PDF 文件路径（必填）；--pages 为可选页码范围，例如 "1-3,5"。脚本不会调用任何大模型，只会将提取出的纯文本打印到 stdout。Bash 工具返回中，ok 表示命令是否执行成功（exit code 为 0），output 包含脚本的标准输出（即提取出的 PDF 文本）。

在当前对话中使用大模型进行转换。拿到 Bash 输出后，不需要在 Skill 或脚本中直接调用任何外部大模型 API，而是将 output 字段中的内容视为原始 PDF 文本，在当前 Agent 的对话中结合本 Skill 说明向大模型发出请求：翻译成中文、调整为合理的标题段落列表等结构、输出为标准 Markdown 格式。所有大模型调用由 SDK 的 provider/router 统一负责，自动使用当前 Agent 配置好的模型和路由策略，Skill 不负责管理 API Key 或模型选择。
使用 Write 将 Markdown 保存到文件（如用户有此需求），在得到最终 Markdown 文本后调用 Write 工具写入：

{
  "path": "<输出 Markdown 文件路径>",
  "content": "<模型生成的中文 Markdown 文本>"
}

之后可通过正常的文件系统操作（如下载或后续处理）使用该文件。

根据用户需求做二次加工（可选）。若用户还有额外要求（例如“只保留某几章”“简化为摘要”），可在拿到 Markdown 后再用模型进行二次加工；对于特别长的 Markdown，可按章节或段落拆分处理，避免超出上下文限制。

适用场景

用户上传或引用 PDF，并希望导出为中文 Markdown 文档。
需要提取 PDF 正文并翻译整理为结构化 Markdown。
需要在转换后进一步筛选章节或生成摘要。

限制与错误处理

依赖环境：需预先安装 Python 与 pypdf。
若 Python 脚本执行失败（Bash 返回 ok == false 或 exit code 非 0）：检查 PDF 路径是否正确；确认文件存在且为有效 PDF；检查是否已安装 pypdf 依赖。
若生成的 Markdown 明显缺失内容或大量乱码：可向用户说明这是 PDF 原始排版或内嵌字体导致的限制；根据情况建议只转换部分页面，或改用其它方式获取内容。
本 Skill 通过 Python 脚本仅读取 PDF 文本，不执行其中任何代码，但仍建议只对可信来源的 PDF 使用。大模型调用由 SDK 内部统一管理，Skill 不直接处理任何 API Key。
文档中未提供具体收费、价格、平台支持范围与效果保证等信息，暂未提供。