Skip to main content
Glama
README.md
# tangxin-dl

糖心Vlog 视频搜索与下载工具:**MCP Server + 命令行**。零登录、无广告,一条命令完成
「搜索 → 选中 → 下载 → 命名」。

<p align="left">
  <a href="https://github.com/dagensbox/tangxin-dl/actions/workflows/tests.yml"><img alt="tests" src="https://github.com/dagensbox/tangxin-dl/actions/workflows/tests.yml/badge.svg"></a>
  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-blue">
  <img alt="mcp" src="https://img.shields.io/badge/MCP-streamable--http-6f42c1">
  <a href="https://github.com/dagensbox/tangxin-dl/releases"><img alt="release" src="https://img.shields.io/github/v/release/dagensbox/tangxin-dl?color=brightgreen"></a>
  <img alt="license" src="https://img.shields.io/badge/license-WTFPL-lightgrey">
</p>

> 本项目仅供个人学习与技术研究,涉及成人内容站点,请确保你已成年并遵守所在地法律法规。

## 特性

- **搜索**:按标题 / 作者 / 标签检索,支持多个关键词。
- **下载**:直接拉取 HLS 分片并在本地解密合并,无需登录、无广告。
- **命名**:文件名为 `<视频ID>_<原标题>.mp4`,中文原样保留,便于归档和排序。
- **不重复下载**:同名文件已存在时直接复用,需要重下再显式指定。
- **稳定**:分片并行下载、失败自动补拉、中断后可续传。
- **可集成**:既是命令行工具,也是标准 MCP Server,可被 AI 客户端直接调用。
- **安全**:文件路由做了路径防护,默认只监听本机。

## 安装

```bash
git clone https://github.com/dagensbox/tangxin-dl.git
cd tangxin-dl
pip install -r requirements.txt

# 另需系统工具:
# Windows  scoop install aria2 ffmpeg
# macOS    brew install aria2 ffmpeg
# Linux    sudo apt install aria2 ffmpeg
```

## 使用

### 命令行

```bash
python main.py search 关键词        # 搜索并交互式选择下载
python main.py download <视频ID>    # 按 ID 直接下载
python main.py home                 # 主页推荐
python main.py actor <演员名>       # 某演员的全部作品
python main.py tag <标签>           # 某标签的全部作品
```

视频 ID 可从搜索结果中获得,也见网页地址 `/v/<视频ID>/`。

### MCP Server

```bash
python server.py                    # streamable-http:默认 127.0.0.1:8766,端点 /mcp
python server.py stdio              # stdio:由本地 MCP 客户端直接拉起
```

| 工具 | 说明 |
|------|------|
| `tx_search_posts` | 搜索视频 |
| `tx_get_post_detail` | 视频详情(含播放地址) |
| `tx_download` | 异步下载,返回 `task_id` |
| `tx_check_download` | 查询下载进度与结果 |
| `tx_browse_home` | 主页推荐 |
| `tx_browse_actor` | 演员全部作品 |
| `tx_browse_tag` | 标签全部作品 |

AI 客户端(Claude Desktop / Cursor 等)配置示例:

```json
{
  "mcpServers": {
    "tangxin": {
      "command": "python",
      "args": ["/path/to/tangxin-dl/server.py"]
    }
  }
}
```

## 配置

编辑 `config.json`(未写的项自动使用默认值):

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `download_dir` | 下载目录 | `downloads` |
| `mcp_host` / `mcp_port` | MCP 监听地址与端口 | `127.0.0.1` / `8766` |
| `proxy` | 代理,如 `{"enable": true, "scheme": "http", "host": "127.0.0.1", "port": 7890}` | 读系统代理 |
| `aria2_args` | aria2 额外参数 | `--disable-ipv6 -j8 -x4 -s4` |
| `referer` | CDN 请求头 | 站点首页 |
| `aria2_path` / `ffmpeg_path` | 外部程序完整路径(PATH 找不到时用) | 自动探测 |

本机私有覆盖写在 `config.local.json`(已加入 `.gitignore`,不会被提交),字段同上,
优先级高于 `config.json`;适合放自己的下载目录、代理和 ffmpeg 路径。

## 文件命名

下载结果直接落在 `download_dir` 根目录:

```text
<视频ID>_<原标题>_<作者>.mp4
```

例如 `12345678_示例标题_示例作者.mp4`(此处仅为格式示意)。

- 标题取视频页正文标题,不带站点名、作者等后缀;
- 作者取自详情页 byline,抓不到时省略该段(`12345678_示例标题.mp4`);
- 标题里已经包含作者名时不会重复拼接;
- 中文原样保留,只替换系统不允许的字符;ID、标题、作者三段共享 90 字符预算,过长自动截断;
- 同名文件不覆盖,会追加 ` (2)`、` (3)`;
- 标题缺失时保留 ID 与作者。分隔符由 `engine/download.py` 的 `_ID_SEP` / `_AUTHOR_SEP` 控制。

分片、密钥等中间文件存放在 `download_dir/.tmp/<视频ID>/`,完成后自动清理。

## 测试

```bash
python -m unittest discover -s tests -v
```

全部离线运行,不联网、不下载。

## 免责声明

> ⚠️ 本项目仅供技术研究与学习,不包含、不托管、不分发任何视频内容。
> 所有内容版权归原站点及作者所有。本项目与相关内容站点无任何关联,也未获其授权。
> 使用者应自行遵守所在地法律法规及站点条款,并对自身行为承担全部责任。

## License

[WTFPL](LICENSE)

## 致谢

项目骨架源自 [bomomoQWQ/tangxin-download](https://github.com/bomomoQWQ/tangxin-download)
(WTFPL)。本版本重写了搜索、下载与 MCP 接口,并补充了测试与 CI。