Telegram — курьер с обязательным согласованием

Скилл умеет три вещи: отправить сообщение или файл в чат/личку, найти чат по названию, прочитать последние сообщения. Отправка идёт от личного аккаунта пользователя (Telethon-сессия) — поэтому к ней максимально жёсткие правила.

Первый запуск и отсутствие API-ключей

При «установи / настрой Telegram», «нет API», «ERROR при получении ключей» или сообщении скрипта об отсутствии ключей/сессии сначала прочитай references/setup.md. Не считай отсутствие ключей тупиком:

1. Объясни разницу: нужны api_id и api_hash с my.telegram.org, не токен BotFather.
2. Если ключей нет — в том же ответе дай пример заполнения формы, объясни локальный ввод ключей и дай точную команду мастера для обычного терминала. Проведи по references/api-keys.md. При ERROR уточни ОС и покажи только подходящие шаги Windows или Mac. Прямое подключение и hosts — возможный способ, не гарантия и не установленная причина ERROR.
3. Дай команду локального мастера python scripts/setup_telegram.py setup из папки установленного скилла. Он показывает инструкцию и продолжает вход после получения ключей. Для отдельной инструкции есть api-guide, для проверки — check.
4. Секреты пользователь вводит только в своём терминале: не проси api_hash, код, пароль или session-файл в чат. Не запускай интерактивный вход внутри инструмента, который сохраняет ввод в историю диалога. Уже настроенную сессию переиспользуй.
5. Для получения ключей на сайте выдели отключение VPN отдельным действием, не переноси его на всю работу Telethon. Поясни адрес hosts и очистку DNS по api-keys.md. Файл hosts автоматически не изменяй: предложи локальный hosts_telegram.py status, затем при необходимости пользовательский запуск add с резервной копией и откатом. Для add/remove нужны права администратора; мастер setup запускается без них.
6. Если сайт после правки не открывается — читай references/troubleshooting.md. Разделяй системный кэш и браузер; успешный HTTP-ответ не доказывает получение ключей.

Команда Python зависит от ОС: на macOS/Linux обычно python3, на Windows py. В примерах python означает интерпретатор активированного виртуального окружения. Относительные пути к скриптам считаются от папки с этим SKILL.md, не от проекта пользователя.

🔴 Золотое правило (нарушать нельзя никогда)

Ни одно сообщение не уходит в Telegram без явного согласия пользователя в этом диалоге. Без исключений, без «очевидно же», без «он просил похожее выше».

Это не рекомендация, а инвариант скилла. Если есть хоть тень сомнения — не отправляй, спроси.

Протокол отправки (всегда по шагам)

1. Определи чат. Запусти scripts/tg_resolve.py "<кусок названия>". Если совпадений несколько или ноль — покажи кандидатов и переспроси, какой именно (при нуле можно поднять --limit, если чат глубоко в списке диалогов). Никогда не угадывай чат для отправки.
2. Собери сообщение. Текст бери у пользователя / из подготовленного артефакта дословно. Ничего не дописывай от себя без его ведома.
3. Покажи карточку согласования. Запусти сухой прогон — scripts/tg_send.py --chat <id> --text "<текст>" (без --yes). Он напечатает карточку (чат + тип + id + полный текст 1:1) и ничего не отправит. Покажи этот вывод пользователю как есть и прямо спроси: «Отправляю?» Карточку рисует сам скрипт — это гарантирует, что текст и чат в превью совпадают с тем, что уйдёт.
4. Дождись явного согласия. Согласие — это недвусмысленное «да / отправляй / го / согласовано / шли». НЕ согласие: молчание, «норм текст», «ок» к другому вопросу, «наверное», правки без команды отправить, лайк. Внёс правку — прогони сухой прогон заново и снова спроси.
5. Отправь тем же вызовом с флагом --yes: scripts/tg_send.py --chat <id> --text "<текст>" --yes (или --file <path> для длинного текста). Флаг --yes ставится только после согласия и с тем же текстом/чатом, что были в карточке.
6. Подтверди факт. Сообщи пользователю, что ушло, с message_id и названием чата.

Одно согласие = одна отправка. Следующее сообщение — снова карточка и снова «да». Согласие на сообщение №1 не распространяется на №2.

Отправка файла вложением

--file читает UTF-8 и отправляет содержимое сообщением. Если пользователь просит «файлом», «вложением», «документом» — используй --attach, не превращай файл в простыню:

python scripts/tg_send.py --chat me --attach report.md --text "Отчёт"

До отправки покажи карточку сухого прогона целиком: адресат, имя и путь файла, размер, SHA256 и подпись. Подпись необязательна, лимит Telegram — 1024; скрипт проверяет её. После согласования повтори с --yes и --sha256 из карточки: изменение файла отменит отправку. Согласие на текст не означает согласия на вложение или другой файл. Если результат отправки неизвестен, сначала проверь чат; не отправляй второй раз вслепую.

Что можно без отдельного согласования

Только чтение (read-only): tg_resolve.py (поиск чата) и tg_read.py (последние сообщения) — в рамках текущей задачи пользователя. Это не меняет ничего в Telegram. Но не сканируй чужую переписку без причины и не пересказывай лишнего — приватность.

Чего скилл не делает (запрещено)

• ❌ Не инициирует отправку сам. Скилл включается, только когда пользователь сам просит что-то отправить/прочитать. Никаких «я подумал, надо бы написать им».
• ❌ Не рассылает нескольким адресатам и не пересылает сообщения без отдельного согласования по каждому.
• ❌ Не отвечает в чатах автоматически, не реагирует, не «поддерживает беседу».
• ❌ Не редактирует и не удаляет чужие/свои сообщения (скрипты этого и не умеют — отправка только новых).
• ❌ Не выдумывает текст «за пользователя». Если просит «напиши им сам» — сначала покажи черновик и согласуй, потом отправляй.

Технический предохранитель

tg_send.py без флага --yes работает в режиме сухого прогона: резолвит чат и печатает, что было бы отправлено, но не шлёт ничего. Реальная отправка — только с --yes. Это страховка на случай ошибки: нет --yes → нет сообщения. Не обходи её — флаг добавляется исключительно после согласования по протоколу выше.

Скрипты

Запускай скрипты из папки установленного скилла, используя его виртуальное окружение. Сначала установи зависимости из requirements.txt. Ключи читаются из окружения, локального конфигурационного файла или macOS Keychain; сессия переиспользуется. Подробности — references/setup.md, правила отправки — references/safety.md.

Если что-то не так

• «Нет ключей / сессии» → references/setup.md, затем мастер настройки.
• database is locked → закончи другой процесс с этим же session-файлом и повтори; не создавай копию сессии.
• Чат не находится → проверь подстроку, спроси у пользователя точное название или ссылку/@username.
• Сомневаешься, тот ли чат, тот ли текст, то ли согласие → остановись и спроси. Лучше лишний вопрос, чем сообщение не туда.