# Tomato Novel Downloader

> Tomato Novel Downloader

- Skill: `kitemao/tomato-novel-downloader` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kitemao/tomato-novel-downloader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kitemao/tomato-novel-downloader/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kitemao (https://skillmd.com/u/kitemao)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kitemao/tomato-novel-downloader

---

# Tomato Novel Downloader

自动下载番茄小说，输入 URL 即可获取完整 TXT 内容。自动管理下载服务器，无需手动配置。

## 功能

- 自动检测并启动 Tomato-Novel-Downloader 服务器
- 智能复用已完成的下载任务
- EPUB 自动转换为 TXT
- 支持番茄小说 URL 和 book_id
- 零配置使用

## 前提条件

1. **安装 Python 依赖**
   ```bash
   pip install ebooklib beautifulsoup4
   ```

2. **下载 Tomato-Novel-Downloader 服务器**

   从 [zhongbai2333/Tomato-Novel-Downloader](https://github.com/zhongbai2333/Tomato-Novel-Downloader) 下载对应平台的可执行文件：

   macOS ARM64:
   ```bash
   curl -L -o TomatoNovelDownloader-macOS_arm64 \
     https://github.com/zhongbai2333/Tomato-Novel-Downloader/releases/latest/download/TomatoNovelDownloader-macOS_arm64
   chmod +x TomatoNovelDownloader-macOS_arm64
   ```

   或者使用一键安装脚本：
   ```bash
   bash <(curl -sL https://raw.githubusercontent.com/zhongbai2333/Tomato-Novel-Downloader/main/installer.sh)
   ```

## 使用方法

### 方式 1：作为 Cursor/Claude Skill

用户直接说：
```
下载这本小说：https://fanqienovel.com/page/7585469751904717848
```

Agent 会自动：
1. 检测服务器是否在运行
2. 如未运行，自动查找并启动
3. 提取 book_id
4. 检查已有完成的任务
5. 创建新任务并等待完成
6. 转换 EPUB 到 TXT
7. 返回完整内容

### 方式 2：Python API

```python
from tomato_novel_downloader import download_tomato_novel

# 下载小说（默认保存到服务器所在目录的 novels/ 文件夹）
content, file_path = download_tomato_novel("https://fanqienovel.com/page/7585469751904717848")
print(f"文件保存位置: {file_path}")

# 使用 book_id
content, file_path = download_tomato_novel("7585469751904717848")

# 指定输出路径
content, file_path = download_tomato_novel(url, output_path="./novel.txt")
```

### 方式 3：命令行

```bash
python tomato_novel_downloader.py https://fanqienovel.com/page/7585469751904717848
```

## API 文档

### ServerManager

```python
from tomato_novel_downloader import ServerManager

manager = ServerManager()

# 检查服务器是否运行
is_running = manager.is_running()

# 查找二进制文件
binary_path = manager.find_binary()

# 启动服务器
success = manager.start_server(binary_path)

# 一键确保运行
success = manager.ensure_running()
```

### TomatoNovelDownloader

```python
from tomato_novel_downloader import TomatoNovelDownloader

downloader = TomatoNovelDownloader()

# 一键下载（推荐）
content = downloader.download_novel("https://fanqienovel.com/page/7585469751904717848")

# 手动控制流程
downloader.server_manager.ensure_running()
book_id = downloader.extract_book_id(url)
job = downloader.create_job(book_id)
completed = downloader.wait_for_completion(job["id"])
file_path = downloader.find_downloaded_file(completed["title"])
content = downloader.epub_to_txt(file_path)
```

## 注意事项

- 服务器同一时间只允许一个活跃任务
- 首次下载需要获取目录+下载章节，可能较慢
- 已下载过的小说会直接返回，速度极快
- EPUB 文件自动转换为 TXT
- 下载的文件保存在 Tomato-Novel-Downloader 所在目录

## 故障排除

### 找不到服务器

确保 Tomato-Novel-Downloader 二进制文件在以下位置之一：
- 当前工作目录
- `~/tomato-novel-downloader/`
- `~/Downloads/tomato-novel-downloader/`
- PATH 环境变量中

### 依赖错误

```bash
pip install ebooklib beautifulsoup4
```

### 端口占用

默认端口 18423，如果被占用会提示错误。