内容
[](https://pypi.org/project/tg-parser/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/mdemyanov/tg-parser)
[](https://github.com/astral-sh/ruff)
[](https://github.com/microsoft/pyright)
**为LLM处理解析Telegram桌面版JSON导出文件。**
将杂乱的聊天导出文件转化为干净的结构化准备好进行总结、分析和工件提取，适用于ClLLM。
## 功能 已实现 ✅ (v2.0)
- 🗂️ **所有聊天类型**：个人、群组群组、论坛话题、频道
- 🔍 **强大的过滤功能**：9种（日期、发送者、内容、话题、附件、）
- ✂️ **智能分段**：3（固定、话题、适用于LLM上下文限制 🚀 **流**：基于ijson器，适用于大于50MB的文件，自动检测
- **多种格式**：LLM优化）、JSON模板、CSV
- 🔌 **MCP集成**Claude Desktop/Code的6种工具
- 📊 **统计数据**：消息数量、顶级发送者、、提及分析
🎯 **tiktoken集成**：准确的代币带有SimpleTokenCounter- 📄-topics命令**：将论坛聊天按话题分割成单独的文件
**类型安全**：pyright严格模式，413个综合测试
- 🔧 **mcp-config命令**：Claude Desktop/Code MCP集成自动配置
- 🆕 **配置文件支持**：使用`config`命令组的TOML配置文件
## 安装
```bash
# 从PyPI）
pip install tg-parser
# 使用uv
uv tool install tg-parser
# 包含所有额外功能（MCP、tiktoken、流式处理）
pip install "tg-parser[all]"
# 从源码
git clone https://github.com/mdemyanov/tg-parser.git
cd tg-parser
uv sync --all-extras
```
## 快速入门
### 1. 从Telegram桌面版导出
1. 打开Telegram桌面版
2. 进入聊天 → ⋮ 菜单 → 导出聊天记录
3. 选择JSON格式，如果不需要，取消勾选媒体
4. 导出
### 2. 解析导出文件
```bash
# 基本解析
tg-parser parse ./ChatExport/result.json -o ./output/
# 7天-parser parse ./export.json --last-days 7
# 按发送者过滤
tg-parser parse ./export.json --senders "伊万·彼得罗夫,玛丽亚"
# 将论坛按话题分割
tg-parser parse ./forum_export.json --split-topics
# 为LLM上下文限制分段
tg-parser chunk ./export.json -s hybrid --max-tokens 8000
# 分析提及
tg-parser mentions ./export.json --format json
# 大文件流式处理-parser parse ./massive_export.json --stream# 获取统计数据
tg-parser stats ./export.json
```
### 3. 与Claude一起使用
输出针对LLM处理进行了优化：
```markdown
# 聊天：开发团队
**期间：** 2025-01-13 — 2025-01-19
**参与者：** 伊万，亚，阿列克谢
---
## 2025-01-15
### 10:30 — 伊万·彼得罗夫
同事们，我们需要讨论新模块。
### 10:35 — 玛丽亚·西多罗娃
@阿列克谢，请为明天准备好图表。
```
## CLI参考
### `tg-parser parse`
主要解析命令，带有过滤器。
```bash
tg-parser parse <input> [OPTIONS]
# 日期过滤器
--date-from DATE # 开始YYYY-MM--date-to # 结束日期last-days N 最近N天
N N小时
#过滤器
ers TEXT #者（分隔）
--exclude TEXT #发送者
# 器（适用于论坛群组）
--topics TEXT # 包含话题
--exclude-top # 排除# 内容过滤--mentions TEXT # 提及用户的消息
--contains REGEX # 搜索模式
--min-length N # 最小文本长度
# 类型过滤器
--has-attachment # 仅限附件
--has-reactions # 仅限反应
--exclude-forwards # 排除转发
--include-service # 包含服务消息
# 输出
-o, --output PATH # 输出目录
-f, --format FORMAT # markdown|json|csv
--split-topics # 每个话题单独一个文件
```
### `tg-parser chunk`
为LLM上下文限制分割解析输出。
```bash
tg-parser chunk <input> [OPTIONS]
-s, --strategy STRATEGY # fixed|conversation|topic|daily
--max-tokens N # 每个分段的最大代币数（默认：3000）
--time-gap N # 分割的时间间隔（默认：30）
--preserve-threads # 不破坏回复链
```
### `tg-parser stats`
聊天统计概览。
```bash
tg-parser stats <input> [OPTIONS]
--format FORMAT # table|json|markdown
--top-senders N # 显示顶级发送者
--by-topic # 按话题分组
--by-day # 每天的明细
```
## MCP服务器
在Claude Desktop或Claude Code中直接使用tg-parser。
### 设置
```bash
# 自动配置（推荐）
tg-parser mcp-config --apply
# 或手动添加到claude_desktop_config.json：
```
```json
{
"mcpServers": {
"tg-parser": {
"command": "uvx",
"args": ["tg-parser", "mcp"]
}
}
}
```
### `tg-parser mcp-config`
为Claude Desktop/Code生成或应用MCP配置。
```bash
tg-parser mcp-config [OPTIONS]
# 将配置打印到stdout（默认）
tg-parser mcp-config
# 应用到Claude Desktop配置
tg-parser mcp-config --apply
# 模拟运行 - 显示将应用的内容而不实际应用
tg-parser mcp-config --apply --dry-run
# 应用到Claude Code而不是桌面版
tg-parser mcp-config --apply --target code
# 使用'uv run'而不是'uvx'
tg-parser mcp-config --use-uv-run
选项：
--apply 将配置应用于Claude配置文件
--dry-run 显示将写入的内容而不实际写入
--no-backup 跳过在修改前创建备份
--target [desktop|code] 目标应用程序（默认：desktop）
--use-uv-run 在非虚拟环境安装中使用'uv run'而不是'uvx'
-v, --verbose 详细输出
```
### 可用工具
| 工具 | 描述 | 状态 |
|------||
| `parse_telegram_export` | 解析JSON导出文件并过滤 | ✅ |
| `chunk_telegram_export` | 为LLM上下文分割消息 | ✅ |
| `get_chat_statistics` | 获取聊天统计数据（JSON） | ✅ |
| `list_chat_participants` | 列出参与者及其消息数量 | ✅ |
| `list_chat_topics` | 列出论坛话题及其消息数量 | ✅ |
| `list_mentioned_users` | 分析@提及频率 | ✅ |
### 在Claude中的示例用法
```
用户：解析我上周的团队聊天记录并总结关键决策
克劳德：我将解析导出文件并为分析做好准备。
[使用带有date_from过滤器的parse_telegram_export工具]
基于解析的聊天记录，以下是关键决策...
```
## Python API
```python
from tg_parser import parse_chat, ChatFilter
from tg_parser.domain.value_objects import FilterSpecification, DateRange
from datetime import datetime, timedelta
# 简单解析
chat = parse_chat("./export.json")
print(f"加载了 {len(chat.messages)} 条消息")
# 带过滤器
filter_spec = FilterSpecification(
date_range=(
start=datetime.now() - timedelta(days=7 ),
sendersenset(["伊万·彼得罗夫"]),
=True,
)
chat = parse_chat("./export.json", filter_spec=filter_spec)
数据
for topic in chat.topics.values():
msgs = chat.messages_by_topic(topic.id)
print(f"{topic.title}: {len(msgs)} 条消息")
# 分段
from tg_parser.application.services.chunker import ConversationChunker
chunker = ConversationChunker(max_tokens=3000)
chunks = chunker.chunk(chat.messages)
```
## 输出格式
### Markdown（默认）
干净、人类可读的格式，针对LLM理解进行了优化。
### JSON
用于程序化处理的格式化数据：
```json
{
"meta": {
"chat_name": "团队聊天",
"chat_type": "supergroup_forum",
"statistics": {
"total_messages": 127,
"tokens_estimate": 15000
}
},
"messages": [
{
"id": 1234,
"timestamp": "2025-01-15T10:30:00Z",
"author": "伊万·彼得罗夫",
"text": "...",
"topic": "architecture"
}
]
}
```
### CSV
用于电子表格分析的表格格式。
## 分段策略
| 策略 | 描述 | 最适合 |
|----------|-------------|----------|
| `conversation` | 按时间间隔 + 大小分割 | 一般使用（推荐） |
| `fixed` | 固定代币计数 | 简单情况 |
| `topic` | 每个话题一个分段 | 论坛群组 |
| `daily` | 每天一个分段 | 长期时间段 |
## 配置
tg-parser支持TOML配置文件来设置默认选项。
### 配置文件位置（优先级顺序）
1. `--config PATH` CLI标志
2. `TG_PARSER_CONFIG` 环境变量
3. `./tg-parser.toml`（当前目录）
4. `./.tg-parser.toml`（当前目录，隐藏）
5. `~/tg-parser.toml`（主目录）
6. `~/.tg-parser.toml`（主目录，隐藏）
7. `~/.config/tg-parser/config.toml`（XDG标准）
### 管理配置
```bash
# 在当前目录创建示例配置
tg-parser config init
# 在指定位置创建
tg-parser config init -o ~/.tg-parser.toml
# 显示当前有效配置
tg-parser config show -v
# 显示所有搜索位置
tg-parser config path
# 为命令使用自定义配置
tg-parser --config myconfig.toml parse export.json
```
### 配置文件格式
创建 `~/.config/tg-parser/config.toml`:
```toml
[default]
output_format = "markdown" # markdown, kb, json, csv_dir = "~/Documents/tg-exports"
[]
exclude_service =exclude_empty = true
exclude_forwards = false
min_message_length = 0
[chunking]
strategy = "fixed" # fixed, topic, hybrid
max_tokens = 8000
[output.markdown]
include_extraction_guide = false
no_frontmatter = false
[mentions]
min_count = 1
output_format = "table" # table, json
[stats]
top_senders = 10
```
**CLI参数始终覆盖配置文件值。**
## 开发
```bash
# 克隆并设置
git clone https://github.com/example/tg-parser
cd tg-parser
uv sync --all-extras
# 运行测试
uv run pytest
# 类型检查
uv run pyright
# 校验和格式化
uv run ruff check --fix
uv run ruff format
# 在开发模式下运行CLI
uv run tg-parser parse ./test.json
```
## 架构
具有清晰分离的干净架构：
```
presentation/ → application/ → domain/ ← infrastructure/
（CLI，MCP） （用例） （实体） （适配器）
```
## 文档
- **[CLAUDE.md](CLAUDE.md)** — AI助手系统和开发方法论
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 清洁架构层，领域模型，设计决策
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — 开发指南，常见任务，测试指南
- **[docs/TELEGRAM_FORMAT.md](docs/TELEGRAM_FORMAT.md)** — Telegram JSON导出格式规范
- **[PRD.md](PRD.md)** — 产品需求，路线图，实现状态
- **[CHANGELOG.md](CHANGELOG.md)** — 版本历史和发布说明
## 开发状态
**当前版本：** 1.2.0（稳定）
| 组件 | 状态 | 详情 |
|-----------|--------|---------|
| 核心解析 | ✅ 完成 | 所有聊天类型、话题、反应 |
| 过滤 | ✅ 完成 | 9种过滤类型 |
| 分段 | ✅ 完成 | 3种策略（固定、话题、混合） |
| 流式处理 | ✅ 完成 | ijson读取器，自动检测 >50MB |
| CLI | ✅ 完成 | 7个命令：`parse`、`stats`、`chunk`、`mentions`、`split-topics`、`mcp-config`、`config` |
| MCP服务器 | ✅ 完成 | 适用于Claude集成的6种工具 |
| 编写器 | ✅ 完成 | Markdown、JSON、KB模板、CSV |
| 配置 | ✅ 完成 | TOML配置文件、`config`命令组 |
| 测试 | ✅ 完成 | 413个测试，pyright严格 |
| PyPI | ✅ 发布 | v1.2.0可用 |
| CI/CD | ✅ 自动 | GitHub Actions用于测试和发布 |
### 路线图
- **v1.0.0**: ✅ **已发布** - 生产稳定，PyPI发布，CI/CD自动化
- **v1.1.0**: ✅ **已发布** - CSV输出，split-topics命令，tiktoken集成
- **v1.2.0**: ✅ **已发布** - TOML配置文件支持，`config`命令组
参见 [PRD.md](PRD.md) 了解详细路线图。
## 贡献
1. 复刻仓库
2. 创建功能分支（`git checkout -b feature/amazing`）
3. 进行更改并添加测试
4. 确保 `uv run pytest` 和 `uv run pyright` 通过
5. 提交PR
## 许可证
MIT许可证 - 参见 [LICENSE](LICENSE) 了解详情。
## 致谢
- [Telegram Desktop](https://desktop.telegram.org/) 提供了导出功能
- [Typer](https://typer.tiangolo.com/) 提供了CLI框架
- [MCP](https://modelcontextprotocol.io/) 提供了Claude集成
