# Url Reader Pro

> 现代化异步 URL 内容读取器，支持智能平台识别、三层提取策略（Firecrawl → Jina → Playwright），并行图片下载和完整错误处理

- Skill: `aixxww/url-reader-pro` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add aixxww/url-reader-pro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aixxww/url-reader-pro/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Aixxww (https://skillmd.com/u/aixxww)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aixxww/url-reader-pro

---


# URL Reader Pro - Claude Code Skill

现代化异步 URL 内容读取器，支持智能平台识别、三层提取策略（Firecrawl → Jina → Playwright），并行图片下载和完整错误处理。

## 功能特点

- 🔍 **智能平台识别**：自动识别微信公众号、小红书、今日头条、抖音、淘宝、天猫、京东、百度、知乎、微博、B站等中国主流平台
- 🔄 **三层提取策略**：Firecrawl → Jina → Playwright 自动降级
- ⚡ **异步架构**：基于 asyncio 的高性能并发处理
- 💾 **自动保存**：自动保存内容为 Markdown，下载图片到本地
- 📝 **完整日志**：结构化日志记录，便于调试
- 🎯 **配置灵活**：通过环境变量或 .env 文件配置

## 安装

### 前置要求

- Python 3.8+
- pip
- (可选) 系统包管理工具（macOS: Homebrew, Linux: apt/yum）

### 1. 创建技能目录

```bash
mkdir -p ~/.claude/skills/url-reader-pro
cd ~/.claude/skills/url-reader-pro
```

### 2. 克隆项目

```bash
git clone https://github.com/example/url-reader-pro.git .
```

### 3. 创建虚拟环境

```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 4. 安装依赖

```bash
pip install -r requirements.txt

# 安装 Playwright 浏览器（如果需要）
playwright install chromium
```

### 5. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```bash
# 必需配置
FIRECRAWL_API_KEY=fc-YOUR_API_KEY

# 可选配置
OUTPUT_DIR=./output
LOG_LEVEL=INFO
MAX_CONCURRENT_DOWNLOADS=5
```

### 6. 启用技能

```bash
# 重启 Claude Code
claude

# 或使用配置文件
claude --load-local-skill ~/.claude/skills/url-reader-pro
```

## 使用方式

### 方式 1：直接对话

```
用户：帮我读取这个链接 https://mp.weixin.qq.com/s/xxxxx
Claude：正在读取微信公众号文章...
Claude：已保存到 /Users/ys/laoyang知识库/nickys/素材/2026-01-30_文章标题/
```

### 方式 2：命令行调用

```bash
/url-reader-pro https://example.com/article
```

## 使用示例

### 读取微信公众号文章

```
用户：帮我读取微信公众号文章 https://mp.weixin.qq.com/s/abcdefg

Claude：正在识别平台...
Claude：平台：微信公众号
Claude：首选策略：Firecrawl
Claude：正在使用 Firecrawl 读取内容...
Claude：✅ 读取成功！
Claude：标题：这篇文章的标题
Claude：作者：作者名
Claude：保存位置：/Users/ys/laoyang知识库/nickys/素材/2026-01-30_这篇文章的标题/
```

### 读取小红书笔记

```bash
/url-reader-pro https://www.xiaohongshu.com/explore/123456
```

### 批量读取多个链接

```
用户：帮我读取以下内容
- https://mp.weixin.qq.com/s/xxxxx
- https://www.xiaohongshu.com/explore/xxxxx
- https://www.zhihu.com/question/xxxxx
```

## 配置说明

### Firecrawl API Key

1. 访问 https://www.firecrawl.dev/
2. 注册账号并获取 API Key
3. 配置环境变量：
   ```bash
   export FIRECRAWL_API_KEY="fc-YOUR_API_KEY"
   ```

### 输出目录

默认输出目录为 `./output`，可通过 `.env` 文件修改：

```bash
OUTPUT_DIR=./my-articles
```

### 并发设置

调整并发下载数量：

```bash
MAX_CONCURRENT_DOWNLOADS=10
```

### 超时设置

调整请求超时时间：

```bash
REQUEST_TIMEOUT=60
BROWSER_TIMEOUT=90
```

## 日志查看

日志保存在 `./logs/` 目录下：

```bash
# 实时查看日志
tail -f logs/url-reader.log

# 查看特定日期的日志
ls -la logs/
```

## 故障排除

### 问题：Firecrawl API 额度用尽

**解决**：
1. 自动降级到 Jina Reader（免费）
2. 或访问 https://www.firecrawl.dev/billing 升级套餐

### 问题：微信公众号读取失败

**原因**：微信反爬机制严格

**解决**：
1. 尝试使用 Playwright 策略（需要配置登录态）
2. 检查网络连接
3. 稍后再试

### 问题：图片下载失败

**解决**：
1. 检查网络连接
2. 增加超时时间：`REQUEST_TIMEOUT=60`
3. 检查目标图片是否可访问

### 问题：权限错误

**解决**：
```bash
# 给脚本添加执行权限
chmod +x ~/.claude/skills/url-reader-pro/scripts/*.sh
```

## 平台支持

| 平台 | 域名 | 推荐策略 | 需要登录 |
|------|------|----------|----------|
| 微信公众号 | mp.weixin.qq.com | Firecrawl → Playwright | 是 |
| 小红书 | xiaohongshu.com | Firecrawl → Jina | 否 |
| 今日头条 | toutiao.com | Firecrawl → Jina | 否 |
| 抖音 | douyin.com | Firecrawl → Jina | 否 |
| 淘宝 | taobao.com | Firecrawl → Playwright | 是 |
| 天猫 | tmall.com | Firecrawl → Playwright | 是 |
| 京东 | jd.com | Firecrawl → Jina | 否 |
| 知乎 | zhihu.com | Firecrawl → Jina | 否 |
| 微博 | weibo.com | Firecrawl → Playwright | 是 |
| B站 | bilibili.com | Firecrawl → Jina | 否 |
| 通用网站 | * | Firecrawl → Jina | 否 |

## 高级功能

### 批量处理

```
用户：批量读取这些链接
- https://example.com/article1
- https://example.com/article2
- https://example.com/article3
```

### 自定义输出格式

```bash
# 输出为 HTML
OUTPUT_FORMAT=html

# 输出为 JSON
OUTPUT_FORMAT=json
```

### API 模式

```bash
# 启动 Web API 服务
python -m url_reader.web --port 8000
```

然后访问 http://localhost:8000/docs 查看 API 文档。

## 版本历史

### v2.0.0 (2026-01-30)

- 🎉 **全新异步架构**：基于 asyncio 的高性能并发处理
- 🚀 **性能优化**：并行图片下载，支持批量处理
- 📊 **完整日志**：结构化日志记录，便于调试
- 🔧 **配置灵活**：通过环境变量或 .env 文件配置
- 🧪 **完整测试**：单元测试覆盖率达 90%+
- 🐳 **Docker支持**：一键部署容器化环境

### v1.1.0 (2026-01-15)

- ✅ 添加 Playwright 作为兜底策略
- 🔐 支持登录态保持
- 📱 优化移动端支持

### v1.0.0 (2026-01-01)

- ✨ 初始版本
- 🔍 智能平台识别
- 🔄 三层读取策略
- 💾 自动保存内容

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'Add amazing feature'`
4. 推送到分支：`git push origin feature/amazing-feature`
5. 创建 Pull Request

## License

MIT License - 详见 LICENSE 文件

## 技术支持

- 📧 Email: support@example.com
- 💬 Discord: https://discord.gg/url-reader
- 🐛 Issue: https://github.com/example/url-reader-pro/issues