---
title: "Python-скрипты"
id: "2100"
type: "page"
slug: "scripts"
published_at: "2026-09-30T04:37:41+00:00"
modified_at: "2026-10-15T11:19:29+00:00"
url: "https://pastukhov.com/agents/telegram/docs/scripts"
markdown_url: "https://pastukhov.com/agents/telegram/docs/scripts.md"
excerpt: "Telegram Agent можно расширять своими скриптами на Python. Скрипт — обычный файл рядом с настройками,…"
---

# Python-скрипты

[https://pastukhov.com/agents/telegram/docs/scripts.md](https://pastukhov.com/agents/telegram/docs/scripts.md)

Telegram Agent можно расширять своими скриптами на Python. Скрипт — обычный файл рядом с настройками, который подключается к конвейеру продукта и берёт на себя то, чего не хватает готовым средствам. Достаточно положить файл — пересобирать и перезапускать приложение не нужно. Так подключают сервис, для которого нет готового источника, относят сообщения к категориям и тегам по своим правилам, чистят и дополняют текст перед публикацией или отправляют комментарий своим способом.

Это возможность для тех, кто готов писать код; остальные разделы продукта в скриптах не нуждаются, и часто скрипт — это десяток строк.

## Где лежат скрипты

Все определения живут в папке настроек `/project/apps/telegram/scripts/` — в том же постоянном томе, что остальные настройки. Один скрипт — один файл настроек с числовым именем (например, `1.yml`):

```
id: 1
name: Разбор по ключевым словам
description: Зачем этот скрипт — видно в разделе «Скрипты»
isActive: true
timeoutSec: 30
passEnv: [HTTP_PROXY]
env:
  API_TOKEN: секрет
code: |
  import json, sys
  ctx = json.load(sys.stdin)
  print(json.dumps({"categoryIds": []}))
```

- **название и описание** — чтобы через полгода было понятно, что это и зачем;
- **включение** — выключенный скрипт не обслуживает подключённые к нему места: конвейер ведёт себя так, будто подключения нет, а в журнале остаётся отметка «пропущено»;
- **предельное время** — сколько секунд ждать ответа (по умолчанию 60, потолок — 10 минут); по истечении процесс останавливается;
- **переменные окружения** — постоянные значения для запуска: адреса, ключи доступа. Можно также перечислить, какие переменные окружения сервера передавать скрипту;
- **код** — либо прямо в файле настроек, либо отдельным файлом `.py` рядом с ним: как удобнее. Отдельный файл читается с диска на каждом запуске, поэтому правка в нём видна сразу.

Библиотеки, которые нужны скриптам, перечисляются в одном общем файле `scripts/requirements.txt`. Рабочее окружение Python приложение готовит само при первом запуске — отдельно его настраивать не нужно. Правка файлов применяется на лету, без перезапуска приложения. Удалить скрипт, на который что-то ссылается, продукт не даст: сначала отключите его от места подключения.

## Правила выполнения

Общие правила задаются в отдельном файле `script-runner.yml` рядом с папкой скриптов и применяются на лету. Если файла нет, действуют значения по умолчанию:

- **общий выключатель** — одно переключение запрещает все запуски; каждое подключённое место честно сообщит, что выполнение отключено, а не сделает вид, что всё в порядке;
- **программа Python** — какой именно python запускать (по умолчанию `python3`);
- **предельное время** — 60 секунд на запуск, потолок — 10 минут;
- **одновременные запуски** — по умолчанию не больше двух процессов сразу, чтобы скрипты не перегружали сервер;
- **предел вывода** — 1 МиБ на запуск; данные большего размера остаются в рабочей папке, а скрипт возвращает ссылку на файл.

## Семь точек подключения

Скрипт может быть классификатором, сборщиком или преобразователем текста — всего семь мест в конвейере:

**Классификация** — сообщения сами получают категории и теги:

- **Роутер** — скрипт получает сообщение и список ваших категорий, а возвращает те, что подходят: `{"categoryIds": [...]}`. Это тип роутера «Скрипт» в разделе [Маршрутизация](/agents/telegram/docs/routing) . Идентификаторы, которых больше нет в справочнике, просто отбрасываются;
- **Теггер** — то же самое, но для тегов: скрипт возвращает `{"tagIds": [...]}`.

**Сбор контента** — сообщения приходят из вашего источника:

- **Источник** — скрипт сам забирает сообщения из любого сервиса: получает настройки источника и возвращает найденное списком, не больше 500 записей за один запуск. Позиции чтения скрипт хранит в своей рабочей папке. Подробнее — [Источники](/agents/telegram/docs/sources) .

**Преобразование текста** — текст правится по дороге:

- **Приём сообщения** — скрипт правит текст собранного сообщения до сохранения: убрать лишнее, привести к единому виду;
- **Элемент очереди** — скрипт правит будущую публикацию в момент, когда она попадает в очередь: дополнить текст или сразу перевести её в нужное состояние;
- **Черновик публикации** — скрипт получает готовый текст перед отправкой и заменяет его своим. Так подставляются подпись канала, хэштеги или ссылки. Работает и для предпросмотра, и для самой публикации — текст везде одинаковый;
- **Генерация комментария** — скрипт получает готовый текст комментария перед отправкой и заменяет его своим. Подробнее — [Комментарии с ИИ](/agents/telegram/docs/comments) .

Обращения со скриптами щадящие и строгие. Классификация и правки на приёме и в очереди щадящие: если скрипт сломался, сообщение (или элемент очереди) сохраняется как есть, а сбой остаётся в журнале — один сбой не должен терять контент. Публикация и комментарий строгие: если скрипт сломался или не вернул текст, отправка не происходит, и попытку можно повторить. Так непереработанный текст никогда не уходит в канал. Сбор контента — отдельный случай: если скрипт не смог собрать сообщения, ошибка записывается в источник, а следующая подкачка повторяет попытку — уже собранное не теряется.

## Как проходит запуск

- каждый запуск — отдельный процесс Python: он запускается, отдаёт ответ и завершается;
- на вход приходит один документ JSON: точка подключения, имя скрипта, откуда запуск, данные и аргументы. Читается привычным `json.load(sys.stdin)`;
- ответ — тоже JSON: последний цельный объект, который скрипт напечатал. Сообщения о ходе работы печатать можно, они не мешают;
- у каждого скрипта своя рабочая папка, которая сохраняется между запусками: там удобно держать файлы, позиции чтения и промежуточные результаты;
- размер данных ограничен: если данных много, передавайте не сами данные, а ссылку или файл в рабочей папке;
- процесс не получает секретов приложения: ему доступны только служебные значения и те переменные, которые вы сами перечислили в его настройках.

## Раздел «Скрипты»

В боковой панели есть раздел **«Скрипты»** — страница наблюдения за запусками. Определения здесь читаются, а не правятся: правка файла и есть изменение, а создание и тестовый запуск идут через API.

- состояние среды сверху: есть ли Python, собран ли набор библиотек, сколько запусков и сбоев было за сутки, что случилось в прошлый раз;
- список скриптов: включён или выключен, откуда берётся код, к чему подключён, когда запускался в последний раз;
- история запусков: время, точка подключения, откуда запуск, объект, длительность, код выхода и результат — или понятная причина сбоя. Фильтры — по состоянию и точке подключения;
- сбой назван по-русски и понятен без расшифровки: «Среда недоступна» (нет рабочего Python или не собрались библиотеки), «Таймаут», «Неверный вывод» (скрипт не напечатал цельный JSON), «Вывод слишком велик», «Отменён», «Отключён», «Скрипт не найден»;
- журнал хранится 30 дней и чистится сам.

Сбой скрипта никогда не подменяет данные молчанием: у классификации это просто отсутствие совпадения, у правки текста — запись как есть, у строгих точек — отказ отправки с причиной. Во всех случаях запуск остаётся в журнале с точным временем и ошибкой.

## Внешний API

Тем же набором команд можно управлять извне — через внешний API с ключом из настроек: посмотреть список скриптов и состояние среды, прочитать определение и историю запусков, создать или изменить скрипт, удалить его и выполнить тестовый запуск. Роутеры и теггеры типа «Скрипт» тоже настраиваются через внешний API; источники и преобразования текста задаются в файлах настроек. Подробнее — [Агент](/agents/telegram/docs/agent)
.

## Граница доверия

Скрипты — это ваш собственный код, и запускаются они с правами приложения: отдельной изоляции между скриптом и сервером нет. Поэтому держите их в системе контроля версий вместе с папкой настроек и не запускайте чужие файлы. Если нужна полная изоляция — разворачивайте всё приложение в отдельном контейнере, что и делает стандартная установка. Секретным переменным скрипта стоит уделять то же внимание, что и паролям подключения.

Читайте также: [Маршрутизация](/agents/telegram/docs/routing)
, [Источники](/agents/telegram/docs/sources)
, [Очередь контента](/agents/telegram/docs/queue)
, [Публикации](/agents/telegram/docs/publishing)
, [Комментарии с ИИ](/agents/telegram/docs/comments)
.

[← Оглавление документации](/agents/telegram/docs)