内容
# Telegram 聊天记录下载器
一款功能强大的命令行、图形界面和网页界面工具，用于下载和分析 Telegram 聊天记录，支持多种格式。
## 功能特点
- 下载任意 Telegram 聊天记录、群组、超级群组、频道或 Telegram 导出存档
- 下载聊天文件夹
- 从消息线程中提取子对话
- 以 JSON 格式保存消息，包含完整的消息元数据
- 生成人类和 LLM 可读的 TXT 导出文件，显示名称友好
- 下载媒体附件（照片、视频、文档、音频等）
- 通过 `--preset` 使用常见选项集的预设
- 跨平台支持（Windows、macOS、Linux）
- CLI 优先，可选图形用户界面和网页界面
## 过滤功能
- 按日期范围过滤消息
- 按特定用户过滤消息
- 按关键词过滤已保存的消息
- 按消息线程的子对话过滤消息
## 使用方法
首次运行需要登录您的 Telegram 账户。身份验证时会自动打开浏览器窗口。
### 基本命令
```bash
# 按用户名下载聊天记录
telegram-download-chat username
# 按数字 ID 下载聊天记录（群组/频道的 ID 为负数）
telegram-download-chat -123456789
# 按邀请链接下载聊天记录
telegram-download-chat https://t.me/+invite_code
# 按电话号码下载聊天记录（电话号码必须在您的联系人列表中）
telegram-download-chat +1234567890
# 同时下载多个聊天记录
telegram-download-chat chat1,chat2,chat3
```
### 高级用法
```bash
# 下载消息数量有限制的聊天记录
telegram-download-chat username --limit 1000
# 下载聊天文件夹中的所有聊天记录
telegram-download-chat folder:folder_name
# 下载特定日期或之后的聊天记录（YYYY-MM-DD）
telegram-download-chat username --min-date 2025-05-01
# 下载特定日期之前或之后的聊天记录
telegram-download-chat username --max-date 2025-06-05 --last-days 1
# 按特定用户过滤消息
telegram-download-chat group_username --user 123456
# 过滤包含给定关键词的消息（逗号分隔，不区分大小写）
telegram-download-chat username --keywords "hello,bye"
# 下载特定线程/回复链中的消息
telegram-download-chat group_username --subchat 12345
# 指定自定义输出文件
telegram-download-chat username -o custom_output.json
# 启用调试日志
telegram-download-chat username --debug
# 下载媒体附件（照片、视频、文档等）
telegram-download-chat username --media
# 在 TXT 输出中包含媒体类型指示符（例如 [photo]、[file=report.pdf]）
telegram-download-chat username --media-placeholders
# 下载频道的评论
telegram-download-chat channel_username --comments
# 限制每个帖子获取的评论数量
telegram-download-chat channel_username --comments --comments-limit 50
# 仅保留至少有 2 个总反应的评论
telegram-download-chat channel_username --comments --comments-min-reactions 2
# 在 TXT 输出中包含每条消息的反应
telegram-download-chat username --reactions
# 按月或年分割输出文件
telegram-download-chat username --split month
# 将论坛分割成每个主题的子目录
telegram-download-chat group_username --split topics
# 导出 Telegram 风格的 HTML 页面（附带 JSON/TXT）
telegram-download-chat username --html
# 导出 HTML 并显示可点击的媒体文件路径标题
telegram-download-chat username --media --html --html-media-links
# 导出 PDF 文档（附带 JSON/TXT）
telegram-download-chat username --pdf
# 禁用并行多连接媒体下载（使用单流）
telegram-download-chat username --media --no-fast-download
# 显示当前配置
telegram-download-chat --show-config
# 将结果摘要以 JSON 格式输出到 stdout
telegram-download-chat username --results-json
# 使用预定义的预设
telegram-download-chat username --preset short
# 从特定消息 ID 恢复下载
telegram-download-chat username --since-id 5000
```
### 命令行选项
```
usage: telegram-download-chat [-h] [-o OUTPUT] [--limit LIMIT] [--max-date DATE] [--last-days DAYS]
[--min-date DATE] [--subchat SUBCHAT]
[--subchat-name NAME] [--user USER] [--config CONFIG] [--debug]
[--sort {asc,desc}] [--show-config] [-v]
[chat]
将 Telegram 聊天记录下载到 JSON 和 TXT 格式。
positional arguments:
chat 聊天标识（用户名、电话号码、聊天 ID 或 URL）
options:
-h, --help 显示帮助消息并退出
-o, --output OUTPUT 输出文件路径（默认：chat_<chat_id>.json）
-l, --limit LIMIT 要下载的最大消息数量（默认：0 - 无限制）
--since-id SINCE_ID 从此消息 ID 开始下载
--min-date DATE 仅下载此日期或之后的聊天记录（格式：YYYY-MM-DD）
--max-date DATE 仅下载此日期或之前的聊天记录（格式：YYYY-MM-DD）
--last-days DAYS 从 --max-date（或今天）开始下载的聊天记录天数
--subchat SUBCHAT 按线程/回复链过滤消息（消息 ID 或 URL）
--subchat-name NAME 子聊天目录的自定义名称
--user USER 按发送者 ID 过滤消息
-c, --config CONFIG 配置文件路径
--debug 启用调试日志
--sort {asc,desc} 按日期排序消息（默认：asc）
--split {month,year,topics}
分割输出：按月、按年或按论坛主题
--show-config 显示配置文件位置并退出
--results-json 将结果摘要以 JSON 格式输出到 stdout
--keywords KEYWORDS 仅保存包含这些关键词的消息（逗号分隔）
--preset PRESET 使用配置文件中的预设
--media 下载媒体附件到单独的文件夹
--no-fast-download 禁用并行多连接媒体下载（使用单流）
--media-placeholders 在 TXT 输出中插入媒体类型指示符
--reactions 在 TXT 输出中追加每条消息的反应
--html 以 Telegram 风格的 HTML 文件导出聊天记录（附带 JSON/TXT）
--html-media-links 在 HTML 导出中显示可点击的文件路径标题
--pdf 以 PDF 文档导出聊天记录（附带 JSON/TXT）
--comments 从频道的链接讨论组下载帖子评论
--comments-limit N 每个帖子获取的最大评论数量
--comments-min-reactions N 丢弃反应数少于 N 的评论
--overwrite 替换现有输出文件而不是恢复
--proxy-url URL Telegram 连接的代理 URL
-v, --version 显示程序版本号并退出
```
## 安装
### 依赖项
- Python 3.8 或更高版本
- pip（Python 包管理器）
### 从 PyPI 安装（推荐）
```bash
pip install telegram-download-chat
```
### 使用 uv（替代包管理器）
直接运行，无需安装：
```bash
uvx telegram-download-chat username
```
或作为持久工具安装：
```bash
uv tool install telegram-download-chat
```
### 图形界面版本（可选）
对于喜欢图形界面的用户，提供图形界面版本。
Windows 版本可在 [发布页面](https://github.com/popstas/telegram-download-chat/releases/latest) 获取。
1. 安装图形界面依赖：
```bash
pip install "telegram-download-chat[gui]"
```
2. 启动图形界面：
```bash
telegram-download-chat gui
```
### 便携式 Windows 版本（二部分，小更新）
使用 `build_windows_embed.ps1` 生成便携式、无安装程序的 Windows 分发版。它将分发版分为两个部分，以便更新体积小：
```powershell
.\build_windows_embed.ps1
```
输出：
- `dist\telegram-download-chat-base-<version>.zip` — **首次安装**。解压任意位置并运行 `telegram-download-chat.cmd`（CLI）或 `telegram-download-chat-gui.vbs` 快捷方式（图形界面）。无安装程序/注册表更改。
- `runtime\` — **基础**：官方 Windows *可嵌入* CPython 以及所有第三方包（PySide6/Qt、telethon、...）和启动器。安装一次；仅在 Python 或依赖项更新时重新下载。
- `app\` — 我们的源代码包。
- `dist\app-<version>.zip` — **更新**（~150 KB）。每个版本都附带；基础版本是重用的。
**更新：** 在图形界面中，打开 **设置 → 软件更新 → 检查更新**；当有更新可用时，按钮变为 **立即更新**，下载 `app-<version>.zip` 并在原位交换 `app\`，然后提供重启。到命令行更新（原子交换 `app\`）：
```powershell
runtime\python\python.exe -m telegram_download_chat.core.app_updater apply app-<version>.zip <install-dir>
```
由于我们的代码和依赖项生活在单独的部分中，因此正常的版本更新是 ~150 KB 下载，而不是重新运输 ~100 MB 运行时。基础版本仅在 Python 或依赖项更新时更改（然后重新安装基础 zip）。注意嵌入式 Python 次要版本由基础版本锁定，因此任何依赖项的原生 `.pyd` 都是 ABI-locked。
#### 可选 setup.exe（Inno Setup）
要将便携式树包装成经典的 `setup.exe`，并具有开始菜单/桌面快捷方式和卸载程序，请安装 [Inno Setup 6](https://jrsoftware.org/isdl.php) 并运行：
```powershell
.\build_windows_installer.ps1
```
这首先运行 `build_windows_embed.ps1`, 然后将 `installer.iss` 编译成 `dist\telegram-download-chat-v<version>-setup.exe`. 安装程序 **每用户**（安装在 `%LOCALAPPDATA%\Programs` 下，无需管理员权限），因此应用程序内 **更新现在** 可以在不提升权限的情况下交换 `app\`。版本发布此 `telegram-download-chat-v<version>-setup.exe` 以及 `app-<version>.zip`（应用程序内更新资产）。
### 网页界面
使用 Streamlit 构建的轻量级网页界面也可用。
1. 安装网页依赖：
```bash
pip install "telegram-download-chat[web]"
```
2. 启动网页界面：
```bash
telegram-download-chat-web
```
## AI 代理插件（Claude、Cursor、Codex）
CLI 作为 AI 编程代理的可安装技能/插件提供，因此您可以要求您的代理“下载/导出此 Telegram 聊天记录”，它为您驱动 CLI。所有三个版本均从单一真实来源生成 —
`skills/telegram-download-chat/SKILL.md` — 由 `scripts/gen_agent_plugins.py` 生成（如果它们漂移，则测试失败）。编辑技能后，请运行：
```bash
python scripts/gen_agent_plugins.py
```
- **Claude Code** — 将此存储库添加为插件市场，然后安装插件（捆绑技能在 `skills/` 下）：
```
/plugin marketplace add popstas/telegram-download-chat
/plugin install telegram-download-chat
```
清单：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`.
- **Cursor** — `.cursor/rules/telegram-download-chat.mdc` 项目规则在打开此存储库时自动拾取。要在其他项目中使用它，请复制该文件到目标项目的 `.cursor/rules/` 中。
- **Codex** （OpenAI Codex CLI）— 复制 `.codex/prompts/telegram-download-chat.md` 到 `~/.codex/prompts/` 以公开 `/telegram-download-chat` 斜杠命令
（将聊天 ID/用户名/导出路径作为参数传递）。
## 配置
### API 凭证
要使用此工具，您需要从 [my.telegram.org](https://my.telegram.org) 获取 API 凭证：
1. 进入 [API 开发工具](https://my.telegram.org/apps)
2. 使用您的电话号码登录
- **重要提示**：获取 API 凭证时不要使用 VPN
3. 创建新应用程序
4. 将 `api_id` 和 `api_hash` 复制到您的 `config.yml`
### 配置文件
配置文件在首次运行时自动创建在您的应用程序数据目录中：
- **Windows**: `%APPDATA%\telegram-download-chat\config.yml`
- **macOS**: `~/Library/Application Support/telegram-download-chat/config.yml`
- **Linux**: `~/.local/share/telegram-download-chat/config.yml`
#### 示例配置
```yaml
# Telegram API 凭证（必填）
settings:
api_id: your_api_id # 从 https://my.telegram.org 获取
api_hash: your_api_hash # 从 https://my.telegram.org 获取
session_name: session # 可选：自定义会话文件名
request_delay: 1 # API 请求之间的延迟（秒）
max_retries: 5 # 最大重试次数
log_level: INFO # 日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）
log_file: app.log # 日志文件路径（相对于应用程序目录或绝对路径）
# 将用户 ID 映射到显示名称，用于文本导出
# 用户和机器人的名称会自动获取并存储在此，您可以更改它们。
users_map:
123456: "Alice"
789012: "Bob"
# 常用参数集的预设
presets:
- name: short
args:
limit: 100
```
您还可以使用 `--config` 标志指定自定义配置文件位置。
## 高级功能
### 从 Telegram 存档中提取消息
您可以从 Telegram 导出存档（`result.json`)中提取消息，该存档是从 Telegram Desktop 下载的：
```bash
# 从所有聊天记录中提取所有消息
telegram-download-chat "/path/to/Telegram Desktop/DataExport/result.json"
# 仅提取特定用户的消息（按他们的 Telegram ID）
telegram-download-chat "/path/to/Telegram Desktop/DataExport/result.json" --user 123456
# 保存到自定义输出文件
telegram-download-chat "/path/to/Telegram Desktop/DataExport/result.json" -o my_exported_chats.json
```
此功能特别适用于：
- 处理您的完整 Telegram 数据导出
- 从导出中提取特定对话
- 将导出转换为更易读的格式
- 按用户或日期范围过滤消息（使用 `--min-date` 或 `--last-days`）
该工具将处理存档并生成导出的消息的 JSON 和 TXT 文件。
### 恢复中断的下载
如果下载被中断，您可以简单地再次运行相同的命令以恢复中断的位置。
该工具自动将进度保存到临时文件。
您也可以使用 `--since-id` 恢复稍后或让工具从现有的 JSON 文件中读取它。使用 `--overwrite` 替换现有输出文件而不是恢复。
中断的 `--comments` 运行通过简单地再次运行相同的命令来恢复。评论在一个通道的链接讨论组中被获取（没有每个帖子的检查点文件，因此没有每个帖子的进度文件），因此重新运行也将获取该组并合并结果，自动删除重复项。重新运行还将恢复任何在早期导出中保存的评论媒体链接。
### 用户映射
自动收集用户和机器人的显示名称。您可以在 `users_map` 部分覆盖它们：
```yaml
users_map:
123456: "Alice Smith"
789012: "Bob Johnson"
### 聊天映射
自动获取群组和频道聊天的标题。使用 `chats_map` 仅覆盖它们：
```yaml
chats_map:
100123456: "MyGroup"
```
### 关键词过滤
使用 `--keywords` 仅保存包含至少一个给定单词的消息。这减少了输出大小，当您需要有关特定主题的消息时。
- **行为**：下载后（在您的日期/限制内），消息被过滤；仅包含至少一个关键词（不区分大小写）的消息被写入 JSON 和 TXT。
- **格式**：逗号分隔列表，例如 `--keywords "word1,word2,@user"`。
- **结果**：摘要（和 `--results-json`）仍包括 `keywords` 块，每个关键词的计数和样本消息。
```bash
# 仅保存包含" "或"hello"的消息
telegram-download-chat username --min-date 2026-01-01 --keywords " ,hello"
```
### 子聊天提取
从特定线程或回复链中提取对话：
```bash
# 提取特定线程中的消息
telegram-download-chat group_username --subchat 12345 --subchat-name "Important Discussion"
# 或使用直接消息 URL
telegram-download-chat group_username --subchat "https://t.me/c/123456789/12345"
```
## 图形界面（GUI）
对于喜欢视觉界面的用户，应用程序包括一个可选的图形界面，提供了一种直观的方式来下载 Telegram 聊天记录。
### 启动图形界面
```bash
# 启动图形界面应用程序
telegram-download-chat gui
```
### 选择下载内容（聊天标识符）
顶部的大 **聊天** 字段接受与CLI的位置参数 `chat` 相同的标识符（`@username`，链接或 `chat_id`）。根据您要下载的内容，输入以下之一：
| 您要下载的内容 | 在聊天字段中输入的内容 | 备注 |
|---------------------------|--------------------------------|-------|
| 您自己的 **保存的消息** | `me` | `me` 总是解析为您的帐户，因此其消息历史记录是您的保存消息。您也可以使用您自己的 `@username` 或数字用户ID。 |
| 您所属的 **私人小组** | 邀请链接，例如 `https://t.me/+AbCdEf123456`，或群组的数字ID（负数，例如 `-1001234567890`） | 您必须是已经是成员 - 工具通过您的帐户下载，不能代表您加入。私人小组没有公共的 `@username`，因此使用邀请链接或数字ID。 |
| **公共** 聊天、小组或频道 | `@username` 或其 `https://t.me/username` 链接 | 公共实体可以通过其 `@username` 来表示。 |
提示：
- 邀请链接是您用来加入私人小组的相同的 `t.me/+…` 链接； 在 Telegram 中打开小组 → 小组名称 → **邀请链接** 即可复制。
- 要查找数字ID，请使用 `--debug` 运行CLI，或在首次下载后检查写入 `config.yml` 的 `chats_map` / `users_map` 条目。
- **设置** 下的所有其他字段（限制、日期、媒体、HTML/PDF等）适用于您输入的聊天。
- 对于广播频道，**下载频道帖子评论** 复选框（带有 **每帖评论数** 限制下拉菜单：无限制 / 10 / 50 / 100 / 500 / 1000）从频道的链接讨论组中获取评论线程。评论合并到同一个 `messages.json` 中；在HTML导出中，它们在每个帖子的可折叠块中渲染（折叠显示评论数），而在TXT/PDF中，它们嵌套在父帖子下。在 `--media` 下，评论附件下载到聊天的 `attachments/` 文件夹中，并在HTML中像帖子媒体一样内联渲染。
此帮助也显示在应用程序中：点击 **ⓘ 如何填写？** 在字段下以展开完整列表。 **ⓘ** 图标和悬停提示文本在聊天标签旁边可用，但默认情况下关闭。可以通过 `config.yml` 中的 `gui_chat_hint_tooltip` （默认关闭）/ `gui_chat_hint_help` （默认开启）切换。
### 检查更新
**设置** 选项卡有一个 **软件更新** 组，显示当前版本。点击 **检查更新** 以查询 GitHub 的最新版本。如果有新版本，则按钮替换为 **下载**：在Windows上，它直接获取 `telegram-download-chat.exe` 资产，而在其他平台上，它在您的浏览器中打开发布页面。
## 输出格式
该工具为每个聊天生成以下文件：
### JSON 输出（`[chat_name]/messages.json`）
包含完整的消息数据，包括元数据，如：
- 消息ID和时间戳
- 发送者信息
- 来自 `users_map` 的 `user_display_name`
- 消息内容（包括格式）
- 回复信息
- 媒体和文件附件
- 反应和视图
- `attachment_path` - 下载媒体文件时的相对路径（当使用 `--media` 时）
### 文本输出（`[chat_name]/messages.txt`）
聊天的可读版本，包含：
- 格式化的时间戳
- 来自您的 `users_map` 的显示名称，`sender name` -> `recipient name`
- 带有基本格式的消息内容
- 回复指示符
- 可选的媒体类型指示符，带有 `--media-placeholders` （例如 `[photo]`， `[video]`， `[file=report.pdf]`）
- 可选的内联反应，带有 `--reactions` （例如 `Nice post [👍5 ❤️2]`；自定义/高级表情符号显示为 `⭐`）
### 媒体附件（`[chat_name]/attachments/`）
使用 `--media` 标志时，媒体文件与消息文件一起下载，按媒体类型组织：
```
[chat_name]/
├── messages.json
├── messages.txt
└── attachments/
├── images/
│ └── 12345_123456789000.jpg
├── videos/
│ └── 12346_2937458923.mp4
├── documents/
│ └── 12347_report.pdf
├── audio/
├── stickers/
├── archives/
├── contacts/
├── locations/
├── polls/
└── other/
```
文件命名为 `<message_id>_<original_filename>`，并按类别子目录排序。
### HTML / PDF 导出（`[chat_name]/messages.html`， `[chat_name]/messages.pdf`）
在 `--html` / `--pdf` 标志（以及JSON/TXT输出）与 `--media` 结合使用（用于内联图像）时生成。两者都渲染内联的Telegram格式 - **粗体**， *斜体*，下划线，删除线， `code`， 遮蔽，以及链接（仅保留 `http(s)`， `mailto`，和 `tg` 方案；裸域名默认为 `https://`；其他方案，如 `javascript:`，被剥离）。 HTML视图还：
- 将消息分组为由线程头分隔的回复线程。
- 将回复引用转换为可点击的链接，当引用的消息是导出的一部分时，会跳转到被引用的消息。
- 在每个消息下渲染反应药丸（表情符号 + 计数），镜像Telegram客户端；您选择的反应被突出显示，自定义/高级表情符号显示一个带有工具提示中的文档ID的星号占位符。
- 将频道帖子评论渲染为每个帖子的可折叠块（折叠显示“N条评论”）。
- 显示“前N%”评论过滤器栏（当页面有评论时）：按钮用于全部 / 前50% / 20% / 10% / 5%，每个按钮都标有计算出的反应阈值和匹配的评论计数（例如 `前20％：3+（12）`）。点击隐藏低于该反应计数的评论，在浏览器中实时进行；导出内容不会被删除。
当下载的回复引用消息的日期落在请求的 `--min-date` / `--max-date` 窗口（或有限的 `--limit`）之外时，该引用的消息会自动按ID获取，以便在JSON/TXT/HTML中填充引用的引用。
TXT和JSON输出不受这些标志的影响。
支持的媒体类型：
- **照片**：下载为JPG文件
- **视频**：包括视频消息和圆形视频
- **文档**：PDF，存档，办公文件等
- **音频**：音乐文件和音频消息
- **语音消息**：语音录音
- **贴纸**：包括动画贴纸
- **联系人**：保存为VCF文件
- **位置**：地理坐标保存为JSON
- **投票**：投票数据保存为JSON
### 输出结构示例
```
2025-05-25 10:30:15 Alice -> MyGroup:
大家好！
2025-05-25 10:31:22 Bob -> MyGroup （回复Alice）：
嗨，Alice！你怎么样？
2025-05-25 10:32:45 Charlie -> MyGroup：
欢迎加入小组！
```
## 用例
### 学习和研究
- 下载学习小组讨论以供离线审查
- 存档问答环节以供日后参考
- 收集语言或社会研究数据
### 团队协作
- 存档工作相关的小组聊天
- 记录重要决策和讨论
- 从团队对话中创建可搜索的知识库
### 个人使用
- 备份重要的个人对话
- 整理保存的消息和笔记
- 分析自己随时间的沟通模式
### 数据分析
- 导出聊天数据进行情感分析
- 跟踪社区小组中的主题趋势
- 生成消息频率和参与度的统计数据
### 内容创作
- 收集讨论内容以获取创作灵感
- 引用过去的对话以确保准确性
- 存档社区反馈和建议
## 故障排除
### 常见问题
1. **API错误**
- 确保您的API凭证正确
- 如果您遇到连接问题，请尝试禁用VPN
- 检查您的帐户是否未被限制
2. **丢失消息**
- 某些消息可能已被删除或限制
- 检查您在聊天中是否具有必要的权限
- 尝试先使用较小的限制
3. **下载速度慢**
- 工具尊重Telegram的速率限制
- 在配置中增加 `request_delay` 以实现更可靠的下载
- 考虑使用较小的 `limit` 参数
4. **进度条**
- 默认情况下，进度显示1000条消息
- 当当前 > 1000时，最大值为10000，然后为50000，然后为100000等
5. **Windows上的会话文件锁定**
- 有时在注销期间无法删除 `session.session` 文件
### 获取帮助
如果您遇到任何问题，请：
1. 检查 `app.log` 日志（默认情况下在应用程序目录中）
2. 使用 `--debug` 标志运行以获取详细输出
3. 在 [GitHub](https://github.com/popstas/telegram-download-chat/issues) 上打开一个问题
## MCP服务器（用于AI助手）
该软件包包括一个MCP（模型上下文协议）服务器，允许Claude等AI助手从您的Telegram聊天中检索消息。
### 安装
```bash
pip install "telegram-download-chat[mcp]"
```
### 运行服务器
```bash
# 标准输入/输出传输（适用于Claude Desktop）
python -m telegram_download_chat.mcp
# HTTP传输（用于调试/测试）
python -m telegram_download_chat.mcp -t http -p 8000
```
### Claude Desktop 配置
将以下内容添加到您的Claude Desktop配置文件（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"telegram": {
"command": "python",
"args": ["-m", "telegram_download_chat.mcp"]
}
}
}
```
或使用uvx：
```json
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["--from", "telegram-download-chat[mcp]", "telegram-download-chat-mcp"]
}
}
}
```
### 可用工具
| 工具 | 描述 |
|------|-------------|
| `telegram_get_messages` | 从具有datetime筛选器的聊天中获取消息 |
### 先决条件
在使用MCP服务器之前，您必须至少通过CLI或GUI验证一次以创建有效的Telegram会话。
## 测试
运行标准测试套件（快速，无网络）：
```bash
pytest
```
### 运行端到端测试
端到端导出测试（`tests/test_e2e_export.py`，标记为 `@pytest.mark.e2e`）验证HTML/PDF导出针对一个包含所有格式、回复和转发到一个私有Telegram小组的测试组。它们 **默认跳过** 并且不属于CI，因为它们需要：
- 您的 `config.yml` 中的真实API凭证（`api_id` / `api_hash`，而非占位符），以及
- 一个已验证的 `session.session`，用于一个 **成员** 您测试小组的帐户。
使用 `TG_E2E` 显式启用它们，并使用 `e2e` 标记：
```bash
# 只运行针对默认测试组 的端到端导出测试
TG_E2E=1 pytest -m e2e
# 覆盖目标组（必须是您是成员的帐户）
TG_E2E=1 TG_E2E_GROUP="https://t.me/+XXXXXXXX" pytest -m e2e
```
端到端下载使用 `--overwrite` （干净下载），因此导出反映实时组而不是缓存/恢复的部分内容。当 `TG_E2E` 未设置或缺少凭证/会话时，测试跳过并有明确的原因，默认的 `pytest` 运行不受影响。
## 贡献
欢迎贡献！请随时提交拉取请求。
## 许可证
该项目根据MIT许可证授权 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器