1# CLAUDE.md — Telegram MCP: знания и правила для LLM
2 
3Этот файл содержит накопленные знания, ошибки и best practices для работы с telegram-mcp.
4Читай его перед любой задачей связанной с Telegram API.
5 
6---
7 
8## Архитектура
9 
10- **Библиотека:** Telethon (MTProto) + FastMCP
11- **Сессия:** `{TELEGRAM_SESSION_NAME}.session` — файл сессии авторизованного аккаунта
12- **MCP-инструменты:** зарегистрированы через `mcporter` как сервер `telegram`
13- **Watcher:** `watcher.py` — systemd-сервис `tg-watcher`, читает все входящие/исходящие
14- **Контекст:** `context/` — jsonl-файлы с сообщениями, профили людей, саммари чатов
15 
16---
17 
18## Критические ошибки (обязательно читать)
19 
20### 1. `<br>` не работает в Telegram HTML
21- ❌ `"текст<br>текст"`
22- ✅ `"текст\nтекст"`
23- Telethon с `parse_mode="html"` игнорирует `<br>`. Только `\n`.
24 
25### 2. `list_messages` / `get_messages` — ограничения
26- Максимум **100 сообщений** за один запрос
27- В **личных чатах** возвращает 0 результатов
28- ✅ Правильно: использовать `iter_all_messages(chat_id, limit, offset_id)`
29 
30### 3. Пагинация через `offset_id`
31- Telethon возвращает сообщения в порядке убывания ID
32- `offset_id = min(msg["id"] for msg in batch)` — для следующей страницы
33- Реализовано в `parse_chat.py`
34 
35### 4. Параллельные вызовы `openclaw agent` → file lock
36- Несколько одновременных вызовов → конфликт lock-файла
37- ✅ Решение: `asyncio.Semaphore(1)` в watcher.py — только один вызов одновременно
38 
39### 5. LLM timeout и overloaded_error
40- `openclaw agent` с timeout=120 падает на больших промптах
41- ✅ Решение: `timeout=300`, `asyncio.sleep(8)` между вызовами в context_builder_llm.py
42 
43### 6. Кеширование `_me`
44- `client.get_me()` — сетевой вызов, не вызывать на каждое сообщение
45- ✅ Инициализировать один раз при старте: `_me = await client.get_me()`
46 
47### 7. Реплаи через mcporter
48- Для ответа на конкретное сообщение: `reply_to_message(chat_id, message_id, text)`
49- ❌ НЕ `send_message` — оно не создаёт тред/цитату
50 
51### 8. ID чатов
52- Группы/супергруппы: отрицательные ID (например `-100123456789`)
53- Личные чаты: user_id собеседника (положительное число)
54- Каналы: тоже отрицательные, но начинаются с `-100`
55 
56---
57 
58## Работа с контекстом (context/)
59 
60### Структура файлов
61```
62context/
63├── messages.jsonl          — live-лог всех сообщений от watcher
64├── raw_{chat_id}.jsonl     — спарсенные сообщения конкретного чата/лички
65├── chats/{id}.md           — саммари чата (статистика + LLM)
66├── people/{id}.md          — профиль человека
67└── summary.md              — общий индекс
68```
69 
70### Парсинг чата
71```bash
72python3 parse_chat.py {chat_id} --limit 5000
73```
74- Сохраняет в `context/raw_{chat_id}.jsonl`
75- Автоматически дописывает новые записи в `messages.jsonl` (с полем `chat_id`)
76- ID для личной переписки = user_id собеседника
77 
78### Формат записи в jsonl
79```json
80{"id": 12345, "sender": "Name", "date": "...", "text": "...", "reply_to": null, "chat_id": -100123456789}
81```
82 
83---
84 
85## Watcher (watcher.py)
86 
87- Запущен как `systemd` сервис: `systemctl status tg-watcher`
88- Триггер "клав" — **only from TELEGRAM_OWNER_ID (set in .env)**
89- Команды других пользователей игнорируются (защита от prompt injection)
90- Семафор: один запрос к `openclaw agent` одновременно
91- Подгружает контекст чата при каждом ответе
92- `_me` кешируется при старте, не вызывается повторно
93 
94---
95 
96## Планируемый рефакторинг
97 
98Текущий стек (Telethon + FastMCP) планируется переписать на **Pyrogram** для ускорения парсинга.
99Текущее время парсинга 5000 сообщений: ~7 минут (медленно из-за пагинации через MCP).
100Цель: < 1 минуты через нативный Pyrogram API.
101 
102При переписывании сохранить:
103- Ту же структуру `context/` файлов
104- Тот же формат jsonl записей
105- `parse_chat.py` интерфейс (аргументы)
106- Автодобавление в `messages.jsonl`
107