telegram-channel-parser

Парсинг публичных Telegram-каналов через веб-превью (t.me/s/). Без API-ключей, без MTProto, zero config.

Перед запуском

Перед любым запуском скриптов создай рабочую копию скилла в /home/claude/telegram-channel-parser и работай уже из неё:

bash scripts/prepare_runtime.sh
cd /home/claude/telegram-channel-parser

prepare_runtime.sh копирует скилл и, если есть config/.env, нормализует его через sed -i: некавыченные значения с пробелами или кириллицей оборачиваются в кавычки в рабочей копии.

Config

Никаких токенов не требуется. Для дайджестов — скопировать .env.example:

cp config/.env.example config/.env

Без .env: скилл работает, но каналы нужно передавать явно через --channel / --channels.

С .env: дайджест AI-каналов готов из коробки. Пользователь может добавить свои категории.

Структура .env (категории дайджестов):

TG_CATEGORIES=ai,crypto         # реестр доступных категорий
TG_DEFAULT_CATEGORY=ai           # дефолтная при запросе "дайджест"

TG_CHANNELS_AI_LABEL="AI и технологии"
TG_CHANNELS_AI=countwithsasha,evilfreelancer,...

TG_CHANNELS_CRYPTO_LABEL="Криптовалюты"
TG_CHANNELS_CRYPTO=channel1,channel2

Алгоритм агента при запросе дайджеста:

Прочитать config/.env (если есть)
Распарсить TG_CATEGORIES — получить список доступных категорий
Для каждой категории: TG_CHANNELS_<ID> = каналы, TG_CHANNELS_<ID>_LABEL = название
Определить нужную категорию:
- Пользователь назвал тему → сопоставить с _LABEL
- Не уточнил → использовать TG_DEFAULT_CATEGORY
- Несколько категорий подходят → предложить выбор
Передать каналы нужной категории через --channels

Если .env нет → спросить какие каналы парсить, предложить cp config/.env.example config/.env.

Приоритет: --channels явно > категория из .env > агент спрашивает.

Подробности: config/README.md.

Philosophy

Always fresh — данные запрашиваются в реальном времени при каждом вызове. Никогда не пропустишь свежий пост.
Context window hygiene — stdout ограничен 30 строками. Полные данные в TSV/CSV. LLM работает с компактным форматом, а не с сырым HTML.
Rate limit — между запросами к t.me пауза 1.5с. Не жадничаем.
Чистый POSIX sh — никаких зависимостей кроме curl, sed, awk, grep.

В JSON-дайджесте и сравнении каналов последняя страница используется и для постов, и для сведений о канале, без повторной загрузки. При каждом запуске она загружается заново; страницы истории также запрашиваются заново по мере необходимости.

Workflow

Парсинг одного канала

Получи посты:
```
bash scripts/fetch_posts.sh --channel countwithsasha --limit 50
```
Выведет последние 50 постов в TSV (id, date, views, reactions, fwd_from, fwd_link, text, media_url).

Инфо о канале:

bash scripts/channel_info.sh --channel countwithsasha

Поиск по постам:

bash scripts/search_posts.sh --channel countwithsasha --query "скилл"

Топ постов (шер-парад):

bash scripts/top_posts.sh --channel countwithsasha --limit 50 --sort reactions

Расписание публикаций:

bash scripts/posting_schedule.sh --channel countwithsasha --limit 100

Экспорт:

bash scripts/export_csv.sh --channel countwithsasha --limit 100 --csv cache/export.csv

Дайджест по нескольким каналам

# Явный список каналов
bash scripts/digest.sh --channels "countwithsasha,evilfreelancer,aostrikov_ai_agents" --period today

# Дефолтный набор (без --channels)
bash scripts/digest.sh --period today

Периоды: today, yesterday, week, N (последние N дней).

Сравнение каналов

bash scripts/compare_channels.sh --channels "channel1,channel2,channel3" --limit 30

Таблица: подписчики, средние просмотры, частота публикаций, engagement.

React-артифакт для дайджеста

При запросе дайджеста — отображай результаты как React-артифакт (лента карточек).

Алгоритм (4 шага):

Запусти digest_json.sh — он пишет JSON в файл (не stdout!) и возвращает путь:
```
bash scripts/digest_json.sh --period today
# → prints: cache/digest_today.json
```
Прочитай JSON-файл по выведенному пути
Прочитай шаблон assets/digest-feed.tsx
Замени __DIGEST_DATA__ в шаблоне на содержимое JSON, отрендери как React-артифакт

Важно: скрипт пишет в файл, а не в stdout, чтобы обойти лимит буфера sandbox (~200KB). Для 30-дневного дайджеста 15 каналов JSON может быть 500KB+.

Посты автоматически сортируются по дате (новые сверху), перемешаны между каналами. Пользователь фильтрует по периоду и каналу через UI.

Scripts

Общий паттерн вызова:

bash scripts/<script>.sh --channel <username> [--limit N] [--before <post_id>] [--csv path]

Script	Description	Special params
`fetch_posts.sh`	Посты канала → TSV	`--limit`, `--before`, `--after-date YYYY-MM-DD`
`channel_info.sh`	Название, описание, подписчики	—
`search_posts.sh`	Полнотекстовый поиск	`--query "text"`
`top_posts.sh`	Ранжирование постов	`--sort views\|reactions`, `--limit`
`posting_schedule.sh`	Анализ времени публикаций	`--limit`
`export_csv.sh`	Экспорт в CSV	`--csv path`
`digest.sh`	Дайджест нескольких каналов	`--channels "a,b,c"`, `--period today\|yesterday\|week\|N`
`digest_json.sh`	Дайджест → JSON файл (для React-артифакта)	`--channels "a,b,c"`, `--period today\|yesterday\|week\|N`
`compare_channels.sh`	Сравнительная таблица	`--channels "a,b,c"`, `--limit N` (положительное целое)

Общие параметры

Param	Required	Default	Description
`--channel`	да*	—	Username канала (без @)
`--channels`	нет	из .env	Несколько каналов через запятую
`--limit`	нет	20	Сколько постов загрузить
`--before`	нет	—	ID поста для пагинации
`--after-date`	нет	—	Не загружать посты старше даты (YYYY-MM-DD)
`--csv`	нет	—	Путь для экспорта

*--channel для одного канала, --channels для мультиканальных команд.

Ввод канала

Скилл принимает канал в любом формате:

countwithsasha — просто username
@countwithsasha — с собакой
https://t.me/countwithsasha — прямая ссылка
https://t.me/s/countwithsasha — ссылка на веб-превью
t.me/countwithsasha?before=500 — с параметрами

Всё автоматически нормализуется до голого username.

Ограничения

Только публичные каналы (у которых есть t.me/s/ превью)
Некоторые посты Telegram не отдаёт через веб-превью. Если вместо текста приходит предложение открыть Telegram, поле текста в TSV/JSON содержит [Текст недоступен в веб-превью Telegram: https://t.me/<channel>/<id>]. Это пометка скилла, а не текст автора: сообщи о пропуске и дай ссылку, не пересказывай такой пост. Медиа без подписи остаётся с пустым текстом, если Telegram не пометил его как неподдерживаемое.
Счётчик пересылок (shares) недоступен — t.me/s/ его не отдаёт, только MTProto API
Зато парсится откуда переслан пост (fwd_from + ссылка на оригинал)
Реакции парсятся суммарно (общее количество по всем эмодзи)
Пагинация: ~20 постов на страницу, для 100 постов = 5 запросов
Rate limit: 1.5с между запросами к t.me

/telegram-channel-parser

SKILL.md