190 lines
6.5 KiB
Markdown
190 lines
6.5 KiB
Markdown
---
|
||
name: telegram-collector
|
||
description: Collect, analyze and organize information from Telegram groups and channels. Use to monitor Telegram channels, extract knowledge, build topic databases, and integrate Telegram data into your OpenClaw memory.
|
||
version: 2.0.0
|
||
tags: [telegram, data-collection, knowledge-base, monitoring]
|
||
requirements:
|
||
- python3
|
||
dependencies:
|
||
- telethon>=1.42.0
|
||
- python-dotenv
|
||
allowed-tools: [exec, read, write, edit, cron]
|
||
platforms: [linux]
|
||
---
|
||
|
||
# Telegram Collector
|
||
|
||
> Сбор, хранение и инкрементальное обновление сообщений из Telegram-групп и каналов.
|
||
|
||
## Возможности
|
||
|
||
- ✅ Мониторинг каналов и супергрупп (включая форумные топики)
|
||
- ✅ Первичная загрузка всей истории (пакетами по 10 000, пауза 3 мин)
|
||
- ✅ Инкрементальная загрузка каждые 6 часов (только новые сообщения)
|
||
- ✅ Хранение по структуре: канал → топик → батчи
|
||
- ✅ Загрузка медиафайлов (фото, документы ≤50 МБ)
|
||
- ✅ Метаданные для видео и файлов >50 МБ (для отложенной загрузки)
|
||
- ✅ Восстановление дерева диалогов через reply_to
|
||
|
||
## Структура данных
|
||
|
||
```
|
||
workspace/data/telegram-collector/
|
||
└── raw/
|
||
└── {channel_id}/ ← числовой ID канала/группы
|
||
├── meta.json ← название, username, список топиков
|
||
└── {topic_id}/ ← ID форумного топика (1 = Основная)
|
||
├── state.json ← прогресс загрузки, last_message_id
|
||
├── batch_0001.json
|
||
├── batch_0002.json
|
||
└── media/
|
||
├── {msg_id}_photo.jpg
|
||
├── {msg_id}_document.pdf
|
||
└── ...
|
||
```
|
||
|
||
### meta.json
|
||
```json
|
||
{
|
||
"id": -1001234567890,
|
||
"username": "snowbikerussia",
|
||
"title": "Сноубайк Россия",
|
||
"topics": {
|
||
"1": "Основная",
|
||
"63155": "Барахолка",
|
||
"63467": "Техничка"
|
||
}
|
||
}
|
||
```
|
||
|
||
### state.json (на каждый топик)
|
||
```json
|
||
{
|
||
"topic_id": 63155,
|
||
"topic_title": "Барахолка",
|
||
"first_message_id": 1000,
|
||
"last_message_id": 165197,
|
||
"total_messages": 5432,
|
||
"initial_load_complete": true,
|
||
"last_incremental_at": "2026-03-24T14:00:00Z"
|
||
}
|
||
```
|
||
|
||
### Структура сообщения
|
||
```json
|
||
{
|
||
"id": 165197,
|
||
"date": "2026-03-24T13:08:29Z",
|
||
"text": "Смотрите что купил",
|
||
"from_id": 469188764,
|
||
"reply_to_msg_id": 165180,
|
||
"reply_to_top_id": 63155,
|
||
"quote_text": null,
|
||
"edit_date": null,
|
||
"media": {
|
||
"type": "photo",
|
||
"file_id": "AgACAgI...",
|
||
"size": 245000,
|
||
"mime": "image/jpeg",
|
||
"filename": null,
|
||
"duration": null,
|
||
"width": null,
|
||
"height": null,
|
||
"local_path": "media/165197_photo.jpg",
|
||
"downloaded": true
|
||
}
|
||
}
|
||
```
|
||
|
||
## Логика медиафайлов
|
||
|
||
| Тип | Размер | Действие |
|
||
|-----|--------|----------|
|
||
| Фото | любой | ✅ скачать |
|
||
| Документ / PDF / ZIP / etc | ≤ 50 МБ | ✅ скачать |
|
||
| Видео | любой | ⏭ только метаданные |
|
||
| Любой файл | > 50 МБ | ⏭ только метаданные |
|
||
|
||
`downloaded: false` + `local_path: null` = файл ожидает отложенной загрузки.
|
||
|
||
## Восстановление диалогов
|
||
|
||
- `reply_to_msg_id` = ID сообщения на которое ответили (или ID топика для корневых)
|
||
- `reply_to_top_id` = ID топика (для ответов внутри треда)
|
||
- Дерево диалогов строится по этим полям
|
||
|
||
## Credentials (.env)
|
||
|
||
Хранятся в `~/.openclaw/.env`, никогда в файлах скилла:
|
||
|
||
```bash
|
||
TELEGRAM_COLLECTOR_API_ID=36911437
|
||
TELEGRAM_COLLECTOR_API_HASH=***
|
||
TELEGRAM_COLLECTOR_PHONE=+7XXXXXXXXXX
|
||
TELEGRAM_COLLECTOR_SESSION=telegram_collector
|
||
```
|
||
|
||
Сессия: `skills/telegram-collector/telegram_collector.session`
|
||
|
||
## Конфигурация (config.json)
|
||
|
||
```json
|
||
{
|
||
"data_dir": "/home/node/.openclaw/workspace/data/telegram-collector",
|
||
"incremental_cron": "0 21 * * *",
|
||
"sources": [
|
||
{
|
||
"channel_id": 1242788123,
|
||
"username": "snowbikerussia",
|
||
"title": "Сноубайк Россия",
|
||
"type": "supergroup_forum",
|
||
"enabled": true
|
||
}
|
||
],
|
||
"media": {
|
||
"download_photos": true,
|
||
"download_documents": true,
|
||
"max_file_size_mb": 50,
|
||
"skip_video": true
|
||
}
|
||
}
|
||
```
|
||
|
||
## Скрипты
|
||
|
||
```bash
|
||
# Первичная загрузка всей истории (пакетами по 10 000, пауза 3 мин)
|
||
python3 scripts/initial_load.py
|
||
|
||
# Инкрементальная загрузка (только новые сообщения, отчёт в Telegram)
|
||
python3 scripts/incremental.py
|
||
|
||
# Двухпроходный анализ: GPT-4o mini (пасс 1) + Claude Sonnet (пасс 2)
|
||
# Поддерживает возобновление, считает стоимость, результат → data/{channel}/knowledge_base.md
|
||
python3 scripts/analyzer.py # оба пасса
|
||
python3 scripts/analyzer.py --pass1-only # только извлечение фактов
|
||
python3 scripts/analyzer.py --pass2-only # только синтез из готовых фактов
|
||
python3 scripts/analyzer.py --reset # начать заново
|
||
```
|
||
|
||
## Расписание
|
||
|
||
Настройки расписания (cron expression, job ID) хранятся в `config.json` (поле `incremental_cron`) и в `raw/{channel_id}/meta.json` (поле `cron_job_id`).
|
||
|
||
По завершении инкремента скрипт автоматически отправляет отчёт в Telegram.
|
||
|
||
Логи: `/tmp/incremental.log`
|
||
|
||
## Источники
|
||
|
||
Список источников хранится в `config.json` (поле `sources`).
|
||
Детальная информация по каждому каналу (топики, статус загрузки, статистика) — в `raw/{channel_id}/meta.json`.
|
||
|
||
## Установка зависимостей
|
||
|
||
```bash
|
||
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
|
||
python3 /tmp/get-pip.py --break-system-packages
|
||
~/.local/bin/pip install --break-system-packages telethon python-dotenv
|
||
```
|