AeternaLabsHQ/pullmd

PullMD – 自托管 URL 转 Markdown 服务

是什么

• 一个自托管的 Web 服务，可获取网页（或多种其他媒体类型）并返回干净、高效的 Markdown 文档。
• 专为需要在线内容简洁、结构化表示的人类和 AI 代理设计。

核心功能

功能	详情
网页提取	采用级联流程：Cloudflare 原生 Markdown → Mozilla Readability → Trafilatura → （回退）通过 Playwright 使用无头 Chromium。可完整处理 Reddit 和 Hacker News 线程及评论树。
文档转换（v3）	支持上传或通过 URL 提供 PDF、Word/PowerPoint/Excel、EPUB 等文件。可选 OCR 层（?pdf=ocr）可生成高质量表格。
媒体处理	图像 → 生成字幕；音频 → 转录；YouTube URL → 提取标题、描述和带时间戳的转录文本。所有功能由您配置的任意 OpenAI 兼容视觉/语音识别端点驱动。
输出格式	Markdown 正文仅包含 # 标题 + 内容。所有元数据（源 URL、获取日期、作者、子版块、点赞数、OCR/模型使用情况等）均存储在 YAML 前置元数据块中，可通过 PULLMD_FRONTMATTER_FIELDS 进行裁剪以降低 LLM 流水线的 token 使用量。
可共享 ID	每次转换都会分配一个 8 位十六进制 ID。GET /s/:id 返回缓存的 Markdown，并在超过一小时后自动刷新。
API 表面	• GET /api?url=… – 一次性转换（仅限网页）。 • POST /api/file – 上传文档、图像或音频进行转换。 • POST /mcp – 用于无状态流式传输的 MCP（Claude 兼容）端点。
认证	三种模式：disabled（开放）、single-admin（单管理员）、multi-user（自助注册）。管理员可通过提供的 CLI 管理用户。
安全	内置 SSRF 保护，阻止私有、回环、链路本地和云元数据地址。可通过 PULLMD_ALLOWED_HOSTS 白名单化主机。
可扩展性	可通过 PULLMD_SITE_RECIPES 添加站点特定的“配方”（JSON-LD 转前置元数据、自定义选择器等）。
监控	侧车健康端点（GET /api/status）在渲染器（Playwright、MarkItDown 等）宕机时返回 503。

如何运行

1. Docker Compose（推荐） – 从 Docker Hub 拉取预构建的多架构镜像，通过单条命令启动：

   mkdir pullmd && cd pullmd
   curl -O https://raw.githubusercontent.com/AeternaLabsHQ/pullmd/main/docker-compose.yml
   docker compose up -d   # 服务监听 http://localhost:3000
   

   无需 .env 文件；合理默认值已内嵌。通过在 compose 文件旁创建 .env 文件可覆盖任意设置。
2. 可选侧车 – 该堆栈包含三个辅助容器：
   • pullmd-trafilatura – Trafilatura 提取服务。
   • pullmd-playwright – 用于 JS 富集页面的无头 Chromium/Firefox/WebKit 渲染器（增加约 3.7 GB 镜像缓存）。若仅需静态提取，可省略。
   • pullmd-markitdown – 文档转 Markdown 转换器（PDF/Office/EPUB 必需）。禁用文档转换可省略。
3. 本地开发 – 克隆仓库，运行 npm install，然后 npm start。

配置亮点（在 .env 文件中设置）

• PUBLIC_URL – 帮助页面和可下载的 Claude 技能中使用的公共源地址。
• PULLMD_AUTH_MODE – disabled / single-admin / multi-user。
• PULLMD_ADMIN_EMAIL / PULLMD_ADMIN_PASSWORD – 启动管理员凭据。
• PULLMD_VISION_API_KEY, PULLMD_STT_API_KEY – 通过任意 OpenAI 兼容视觉/语音识别端点启用图像字幕或音频转录。
• PULLMD_PDF_OCR_API_KEY – 启用 PDF 的高级 OCR 层（?pdf=ocr）。
• PULLMD_FRONTMATTER_FIELDS – 白名单化前置元数据字段，以降低 LLM 流水线的 token 使用量。
• DISABLE_PUBLIC_HISTORY – 隐私优先部署中隐藏全局转换历史。
• PULLMD_ALLOWED_HOSTS – 若需绕过默认 SSRF 阻止获取内部主机，可将其加入白名单。

对 AI/LLM 工作流的意义

• Token 效率：通过将所有元数据移至前置元数据块并最小化正文，可将 Markdown 直接输入 LLM，避免重复 URL 或时间戳浪费上下文。
• 代理就绪：MCP 端点允许 Claude 风格代理通过流式兼容 HTTP 调用请求转换。
• 自托管控制：基本网页提取无需第三方 API 密钥，确保数据私密且成本可预测。
• 可扩展媒体处理：图像和音频可实时生成字幕/转录，对多模态代理非常有用。

典型用法

# 单次网页转 Markdown
curl "http://localhost:3000/api?url=https://example.com"

# 上传 PDF 进行转换（需要 markitdown 侧车）
curl -F file=@report.pdf http://localhost:3000/api/file

# 通过 ID 获取可共享 Markdown
curl http://localhost:3000/s/1a2b3c4d

许可证 – AGPL-3.0（参见 LICENSE）。

---

以上所有细节均直接取自仓库的 README；未推断任何额外功能。