Tg Parser

tg解析器

](https://pypi.org/project/tg-parser/)     

解析Telegram桌面JSON导出以进行LLM处理。

使用Claude或其他LLM将杂乱的聊天导出转换为干净、结构化的数据，以便进行摘要、分析和工件提取。

特性

实现✅ （v1.2.0）

• 🗂️ 所有聊天类型：个人、团体、超级团体、论坛主题、频道
• 🔍 强大的过滤功能：9种筛选类型（日期、发件人、内容、主题、附件、反应等）
• ✂️ 智能分块：LLM上下文限制的3种策略（固定、主题、混合）
• 🚀 流媒体：基于ijson的阅读器，用于自动检测大于50MB的文件
• 📝 多种格式：Markdown（LLM优化）、JSON、KB模板、CSV
• 🔌 MCP集成：克劳德桌面/代码的6个工具
• 📊 统计：邮件计数、主要发件人、主题细分、提及分析
• 🎯 tiktoken集成：精确的令牌计数（使用SimpleTokenCounter回退）
• 📄 分割主题命令：按主题将论坛聊天拆分为单独的文件
• ✅ 类型安全：版权严格模式，413项综合测试
• 🔧 mcp配置命令：自动配置克劳德桌面/代码MCP集成
• 🆕 配置文件支持：TOML配置 config 命令组

安装

# From PyPI (recommended)
pip install tg-parser

# With uv
uv tool install tg-parser

# With all extras (MCP, tiktoken, streaming)
pip install "tg-parser[all]"

# From source
git clone https://github.com/mdemyanov/tg-parser.git
cd tg-parser
uv sync --all-extras

快速开始

1.从Telegram桌面导出

1. 打开Telegram桌面
2. 去聊天→ ⋮ menu → 导出聊天记录
3. 选择JSON格式，如果不需要，请取消选中媒体
4. 出口

2.解析导出

# Basic parsing
tg-parser parse ./ChatExport/result.json -o ./output/

# Last 7 days only
tg-parser parse ./export.json --last-days 7

# Filter by sender
tg-parser parse ./export.json --senders "Иван Петров,Мария"

# Split forum by topics
tg-parser parse ./forum_export.json --split-topics

# Chunk for LLM context limits
tg-parser chunk ./export.json -s hybrid --max-tokens 8000

# Analyze mentions
tg-parser mentions ./export.json --format json

# Large files with streaming
tg-parser parse ./massive_export.json --streaming

# Get statistics
tg-parser stats ./export.json

3.与Claude一起使用

输出针对LLM处理进行了优化：

# Chat: Команда разработки
**Период:** 2025-01-13 — 2025-01-19  
**Участники:** Иван, Мария, Алексей

---

## 2025-01-15

### 10:30 — Иван Петров
Коллеги, нужно обсудить архитектуру нового модуля.

### 10:35 — Мария Сидорова
@Алексей, подготовь диаграмму к завтра.

CLI 参考

tg-parser parse

带有过滤器的主解析命令。

tg-parser parse  [OPTIONS]

# Date filters
--date-from DATE        # Start date (YYYY-MM-DD)
--date-to DATE          # End date
--last-days N           # Last N days
--last-hours N          # Last N hours

# Sender filters
--senders TEXT          # Include senders (comma-separated)
--exclude-senders TEXT  # Exclude senders

# Topic filters (for forum groups)
--topics TEXT           # Include topics
--exclude-topics TEXT   # Exclude topics

# Content filters
--mentions TEXT         # Messages mentioning users
--contains REGEX        # Search pattern
--min-length N          # Minimum text length

# Type filters
--has-attachment        # Only with attachments
--has-reactions         # Only with reactions
--exclude-forwards      # Exclude forwarded
--include-service       # Include service messages

# Output
-o, --output PATH       # Output directory
-f, --format FORMAT     # markdown|json|csv
--split-topics          # Separate file per topic

tg-parser chunk

拆分LLM上下文限制的解析输出。

tg-parser chunk  [OPTIONS]

-s, --strategy STRATEGY  # fixed|conversation|topic|daily
--max-tokens N           # Max tokens per chunk (default: 3000)
--time-gap N             # Minutes gap to split (default: 30)
--preserve-threads       # Don't break reply chains

tg-parser stats

聊天统计概述。

tg-parser stats  [OPTIONS]

--format FORMAT          # table|json|markdown
--top-senders N          # Show top N senders
--by-topic               # Group by topic
--by-day                 # Daily breakdown

MCP 服务器

直接在Claude Desktop或Claude Code中使用tg解析器。

设置

# Auto-configure (recommended)
tg-parser mcp-config --apply

# Or manually add to claude_desktop_config.json:

{
  "mcpServers": {
    "tg-parser": {
      "command": "uvx",
      "args": ["tg-parser", "mcp"]
    }
  }
}

tg-parser mcp-config

为克劳德桌面/代码生成或应用MCP配置。

tg-parser mcp-config [OPTIONS]

# Print config to stdout (default)
tg-parser mcp-config

# Apply to Claude Desktop config
tg-parser mcp-config --apply

# Dry run - show what would be applied
tg-parser mcp-config --apply --dry-run

# Apply to Claude Code instead
tg-parser mcp-config --apply --target code

# Use 'uv run' instead of 'uvx'
tg-parser mcp-config --use-uv-run

Options:
  --apply               Apply config to Claude config file
  --dry-run             Show what would be written without applying
  --no-backup           Skip creating backup before modifying
  --target [desktop|code]  Target application (default: desktop)
  --use-uv-run          Use 'uv run' instead of 'uvx' for non-venv installs
  -v, --verbose         Verbose output

可用工具

Claude中的示例用法

User: Parse my team chat from last week and summarize key decisions

Claude: I'll parse the export and prepare it for analysis.
[Uses parse_telegram_export tool with date_from filter]

Based on the parsed chat, here are the key decisions...

Python API

from tg_parser import parse_chat, ChatFilter
from tg_parser.domain.value_objects import FilterSpecification, DateRange
from datetime import datetime, timedelta

# Simple parsing
chat = parse_chat("./export.json")
print(f"Loaded {len(chat.messages)} messages")

# With filters
filter_spec = FilterSpecification(
    date_range=DateRange(
        start=datetime.now() - timedelta(days=7)
    ),
    senders=frozenset(["Иван Петров"]),
    exclude_service=True,
)
chat = parse_chat("./export.json", filter_spec=filter_spec)

# Access data
for topic in chat.topics.values():
    msgs = chat.messages_by_topic(topic.id)
    print(f"{topic.title}: {len(msgs)} messages")

# Chunking
from tg_parser.application.services.chunker import ConversationChunker

chunker = ConversationChunker(max_tokens=3000)
chunks = chunker.chunk(chat.messages)

输出格式

Markdown（默认）

为LLM理解而优化的干净、人类可读的格式。

JSON

程序化处理的结构化格式：

{
  "meta": {
    "chat_name": "Team Chat",
    "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文件

电子表格分析的表格格式。

分块策略

配置

tg解析器支持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标准）

管理配置

# Create example config in current directory
tg-parser config init

# Create in specific location
tg-parser config init -o ~/.tg-parser.toml

# Show current effective config
tg-parser config show -v

# Show all search locations
tg-parser config path

# Use custom config for a command
tg-parser --config myconfig.toml parse export.json

配置文件格式

创建 ~/.config/tg-parser/config.toml:

[default]
output_format = "markdown"   # markdown, kb, json, csv
output_dir = "~/Documents/tg-exports"

[filtering]
exclude_service = true
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参数始终覆盖配置文件值。

发展

# Clone and setup
git clone https://github.com/example/tg-parser
cd tg-parser
uv sync --all-extras

# Run tests
uv run pytest

# Type check
uv run pyright

# Lint and format
uv run ruff check --fix
uv run ruff format

# Run CLI in dev mode
uv run tg-parser parse ./test.json

建筑

干净的建筑，清晰的分隔：

presentation/  →  application/  →  domain/  ←  infrastructure/
   (CLI, MCP)     (use cases)    (entities)    (adapters)

文档

• CLAUDE.md --人工智能辅助系统提示与开发方法
• docs/ARCHITECTURE.md --干净的架构层、领域模型、设计决策
• docs/DEVELOPMENT.md --开发指南、常见任务、测试指南
• docs/TELEGRAM_FORMAT.md --电报JSON导出格式规范
• PRD.md --产品要求、路线图、实施状态
• 更改日志.md --版本历史和发行说明

开发状态

当前版本： 1.2.0（稳定）

路线图

• v1.0.0: ✅ 发布 -生产稳定，PyPI发布，CI/CD自动化
• v1.1.0版本: ✅ 发布 -CSV输出、分割主题命令、tiktoken集成
• v1.2.0版本: ✅ 发布 -TOML配置文件支持， config 命令组

看 PRD.md 详细的路线图。

贡献

1. 分叉存储库
2. 创建特征分支(git checkout -b feature/amazing)
3. 通过测试进行更改
4. 确保 uv run pytest 和 uv run pyright 通过
5. 提交PR

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• 电报桌面版 用于导出功能
• 类型 用于CLI框架
• 主控程序 克劳德整合