qwen_agent/skills/common/web2md

docai-web2md

独立 Python 工具，用于将网页转换为 Markdown 格式，采用优先级架构。

📖 文档导航

• SKILL.md - Claude Code 使用指南（如何调用此技能）
• README.md - 本文档（工具功能说明和独立使用）
• tools/convert.py - 实际转换代码实现
• 共享参考: web-sources.md - 平台支持矩阵

核心特性

• ✅ Jina Reader API 优先 - 零安装，最快最简单（微信公众号除外）
• ✅ Firecrawl API 支持 - 高级爬虫需求
• ✅ Python 智能回退 - 以上方法失败时自动切换
• ✅ arXiv HTML 优先 - 优先获取 HTML 版，失败时回退 PDF
• ✅ 多平台支持 - 微信公众号（直接 Python）、静态博客、动态页面等

优先级策略

# 转换流程
输入 URL
    ↓
是 arXiv? → 转换为 HTML URL
    ↓
是微信公众号? → 直接 Python 方法 ⭐
    ↓
尝试 Jina Reader API (快速)
    ↓ (失败)
尝试 Firecrawl API (需要密钥)
    ↓ (失败)
Python 方法 (回退)
    ↓
arXiv? → 下载 PDF 提取

微信公众号特殊处理：由于 Jina Reader 对微信公众号支持不佳，直接使用 Python 方法以确保最佳效果。

快速开始

方式 1: 使用 uv（推荐）

# 1. 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 在 docai-skills 目录初始化环境
cd docai-skills
uv sync

# 3. 执行脚本（无需激活环境）
uv run python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering

方式 2: 使用 pip（传统方式）

# 1. 创建虚拟环境（可选但推荐）
python -m venv .venv
source .venv/bin/activate

# 2. 安装依赖
pip install requests beautifulsoup4 markdownify pymupdf

# 3. 执行脚本
python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering

方式 3: Jina Reader API（无需安装）

# 直接使用 API，无需任何依赖
curl https://r.jina.ai/https://www.breezedeus.com/article/ai-agent-context-engineering

⚠️ Claude Code Skill 集成

重要：Claude Code 调用 Skill 时使用系统 Python，需要额外配置：

# 使用 uv 安装到系统（不影响项目虚拟环境）
uv pip install --system requests beautifulsoup4 markdownify pymupdf

# 或使用 pip
pip install requests beautifulsoup4 markdownify pymupdf

详见：UV_ENVIRONMENT.md

命令行使用

# 基本用法（自动优先级）
python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering

# 保存到文件
python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering -o article.md

# 纯文本模式
python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering --pure-text

# 强制使用 Python 方法（跳过 Jina/Firecrawl）
python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering --use-python

优先级架构

输入 URL
    ↓
arXiv? → 转换为 HTML URL
    ↓
Jina Reader API (⭐ 零安装)
    ↓ 失败
Firecrawl API (需密钥)
    ↓ 失败
Python 实现 (全能回退)
    ↓
arXiv? → 下载 PDF 提取
    ↓
普通网页 → HTML 解析

使用示例

# 静态博客（Jina Reader）
python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering

# arXiv 论文（HTML 优先，PDF 回退）
python skills/docai-web2md/tools/convert.py https://arxiv.org/abs/2601.04500v1

# 微信公众号（Jina → Python 回退）
python skills/docai-web2md/tools/convert.py https://mp.weixin.qq.com/s/1LfkYdbzymoWxdvdnKeLnA

# X.com/Twitter（Python 动态渲染）
python skills/docai-web2md/tools/convert.py https://x.com/user/status/123

Python API

from skills.docai_web2md.tools.convert import WebToMarkdown

converter = WebToMarkdown()

# 自动优先级（推荐）
markdown = converter.convert("https://www.breezedeus.com/article/ai-agent-context-engineering")

# arXiv 自动处理（HTML → PDF）
paper = converter.convert("https://arxiv.org/abs/2601.04500v1")

# 强制 Python 方法
markdown = converter.convert("https://www.breezedeus.com/article/ai-agent-context-engineering", use_python=True)

# 纯文本输出
text = converter.convert("https://www.breezedeus.com/article/ai-agent-context-engineering", pure_text=True)

依赖说明

方法	依赖	说明
Jina Reader	无	只需网络连接
Firecrawl	FIRECRAWL_API_KEY	环境变量
Python 回退	requests, beautifulsoup4, markdownify	基础依赖
PDF 支持	pymupdf	arXiv PDF 提取
动态页面	playwright	React/Vue SPA

性能参考

• Jina Reader: ~1-2 秒
• Firecrawl: ~2-5 秒
• Python 静态: ~1-2 秒
• Python 动态: ~5-10 秒
• arXiv PDF: ~2-5 秒

与 Skill 的关系

• SKILL.md: 指导 Claude 如何使用此工具
• tools/convert.py: 实际执行转换的代码
• README.md: 本文档（工具使用说明）

测试

# 测试 breezedeus.com 博客
python skills/docai-web2md/tools/convert.py https://www.breezedeus.com/article/ai-agent-context-engineering

许可证

MIT