iia-arg/dsh-plugins--packages-dsh-telegram-multiagent ↗★ 2
dsh-telegram-multiagent
Устойчивый Telegram, файловый A2A и сайт-канал для DSH с квитанциями и изоляцией сессий · Durable Telegram, file A2A and website channel for DSH with receipts and session isolation
安装
npx -p @deepseek-ai/dsh dsh plugin --profile web add 'github:iia-arg/dsh-plugins#464942cd220d62808cfbe27bd41fbc1c8aa538e2&path:packages/dsh-telegram-multiagent'说明文档
阅读完整 README ↗dsh-telegram-multiagent — канал Telegram, файловой почты A2A и чата сайта для агентов DSH с устойчивыми квитанциями
Локальная редакция 3.1.9: строка «опрос жив … ПРОСТОЙ/НЕ БЫЛО» — диагностика для человека, а не автоматический сторож простоя. Автоматического читателя полей ПРОСТОЙ/НЕ БЫЛО нет; dsh-compact-watch ищет только подстроку «опрос жив» и эти поля не разбирает.
Здесь «простой» означает: процесс не завершал никаких ходов 30 минут — A2A, managed, headless или внутренних. Это не означает «владелец не получал ответов». Отметка обновляется на любом turn/end до развилки квитанции и адреса чата. Раз в 20 успешных циклов опроса журнал показывает давность завершения, округлённую до минут; при значении ≥30 — 🔴 ПРОСТОЙ. Следующий завершённый ход обновляет отметку. До первого завершённого хода после старта выводится НЕ БЫЛО: измерения ещё нет. Зависший опрос эта диагностика не обнаруживает, отдельной тревоги не отправляет. Проверка: node test/stend-prostoya.mjs (изолированный обработчик + цикл, девять сценариев).
Назначение
Модуль dsh-telegram-multiagent — плагин платформы DSH (main: src/index.js, inject: ['agents']). Он забирает входящие из Telegram (личные чаты, рабочие группы, гости открытого бота), из файловой почты (/in и ящик почтальона spoolDir) и, если включено, из спула чата сайта; каждое сообщение он записывает в квитанцию SQLite (/.message-receipts/receipts.sqlite), привязывает к поколению сессии агента, ставит в очередь DSH и отправляет ответ туда, откуда пришёл вопрос. Вход сохраняется до продвижения offset Telegram, журнал сессии сбрасывается на диск до побудки. Если исход хода неизвестен, квитанция удерживается для оператора, работа модели вслепую не повторяется.
Кто зовёт: на sadik модуль грузит процесс DSH каждого агента — avrora, iskra, zarya, spartak, marc, petrovich, varvara, anna, alfa, beta, gamma. Каждая служба .service поднимает dsh web, профиль объявляет модуль в своём cordis.patch.yml, а Node находит его по симлинку node_modules/dsh-telegram-multiagent → /opt/agent-plugins/dsh-telegram-multiagent. Код у всех один, агенты различаются только настройками. Отдельно от агентов работает служба mail-stop-arrival.service (root): наблюдатель прихода подписанных стоп-писем.
Кто читает результат: люди в Telegram (ответы, копии владельцу в режиме owner-all, тревоги); курьер машины-координатора (на sadik — sadik-tell-poll с aclaude по ssh: out/ обычной щели — через sudo от root, гостевой щели — sudo -u владельца щели; щель, чей владелец root, не берётся) — забирает /out/*.txt и переносит их в out/polnye; ответы по квитанции receipt-.txt пишутся с правами 0600, прежние записи — по umask; a2a-pochtalon обслуживает ящики /var/spool/a2a, а не out/; обратные квитанции; внешний адаптер сайта — через vyhod/ спула сайта; оператор — через квитанции и src/receipt-admin.mjs; отправитель стопа — через подписанный статус в своём ящике. Модель агента получает от модуля инструменты telegram_send_file, telegram_make_pdf (только при openBot: true) и pismo_rukovoditelyu (только при заданном supervisor), а также команды Telegram — перечень с правами ниже, в «Командах в Telegram».
Подробнее об устройстве — docs/ARCHITECTURE.md; защиты и их читатели — docs/GUARDS.md; стоп и /new почтой — MAIL-STOP.md, MAIL-NEW.md; живой ввод посреди хода — LIVE-INPUT.md; PDF гостям — GUEST-PDF.md.
Команды в Telegram
Команды разбирает модуль, до модели они не доходят. Права проверяются на каждое сообщение.
| Команда | Кто может | Что делает |
|---|---|---|
/start, /help | любой, кого бот пускает (в openBot — и гость) | короткая справка |
/stop | человек из allowedUsers | прерывает текущий ход агента, сохраняя контекст, и ставит разговор на паузу; стоп почтой — MAIL-STOP.md |
/new | человек из allowedUsers; только при newSessionsEnabled: true | начинает разговор заново (новое поколение сессии) |
/goal | goalUsers (в openBot — allowedUsers) | ставит цель агенту; из служебного канала — только подписанным письмом (см. «Ограничения») |
/compact (/ccc), /compact-status (/cs) | человек из allowedUsers | команды платформы: сжатие разговора и его состояние; идут в реестр команд платформы; команды там нет — отказ |
/switch-a, /switch-b | человек из allowedUsers | команда платформы, если реестр её знает; если нет — уходит модели обычным текстом (прежний путь) |
/sss, /sss_on | только владелец (ownerChatId), в личном чате с ботом; при включённом site | закрыть / открыть приём с сайта. /sss записывает выключатель site.stateFile и прерывает разговоры сайта; копии продолжают уходить. Без ownerChatId сайт и /sss выключены |
любая другая / | только владелец (ownerChatId) | команда из реестра платформы; нет такой — отказ «Неизвестная команда», модели не передаётся |
Что ставится и куда
Пакет ставится в бой целым каталогом, по составу публикации (все файлы перечня npm pack --dry-run --ignore-scripts, test/ и docs/ тоже; README.en.md в files не назван, но npm кладёт README* в архив сам). Текущая версия — см. package.json/CHANGELOG.md.
| Файл в пакете | Путь на машине | Режим / владелец | Кто исполняет / читает |
|---|---|---|---|
src/index.js и остальные модули src/*.js, src/*.mjs | /opt/agent-plugins/dsh-telegram-multiagent/src/ | 0644 root:root; src/client.js — 0755 | Node процесса DSH каждого агента (11 служб, см. «Назначение»); вход — main из package.json |
package.json | /opt/agent-plugins/dsh-telegram-multiagent/package.json | 0644 root:root | Node (имя и версия для строки подъёма [dsh-telegram-multiagent · область …] подъём); installed_check реестра |
cordis.patch.yml | /opt/agent-plugins/dsh-telegram-multiagent/cordis.patch.yml | 0755 root:root | Загрузчик DSH (dsh.bundle.patch). Это образец; в бою настройки берутся из профиля агента, собранного по шаблонам /etc/agent-registry/shablony-raskladki/{sdk-claude,codex}/A.tmpl |
systemd/mail-stop-arrival.service | /etc/systemd/system/mail-stop-arrival.service (копия) и …/dsh-telegram-multiagent/systemd/ | 0644 root:root | systemd; юнит enabled, User=root, запускает /usr/local/bin/node /opt/agent-plugins/dsh-telegram-multiagent/src/observe-mail-stop.mjs /etc/dsh-mail-stop/arrival-observer.json (путь к node зашит в ExecStart: где node лежит иначе — править юнит), пишет в /var/lib/dsh-mail-stop-arrivals |
src/observe-mail-stop.mjs, src/mail-stop-arrival.js | в каталоге пакета | 0644 root:root | mail-stop-arrival.service (root) |
src/send-mail-stop.mjs (+ src/publish-mail-stop.py) | в каталоге пакета | 0644 root:root | Отправитель стопа: на sadik — Искра, sudo node /opt/agent-plugins/dsh-telegram-multiagent/src/send-mail-stop.mjs --recipient --mode pause|replace|new [--body-file ]; publish-mail-stop.py вызывается из него через python3 |
src/read-mail-stop-status.mjs | в каталоге пакета | 0644 root:root | Отправитель стопа: сверка подписанного статуса node …/read-mail-stop-status.mjs |
src/sign-coordinator.mjs | в каталоге пакета | 0644 root:root | Подписант координатора: node …/sign-coordinator.mjs REQUEST_JSON |
src/receipt-admin.mjs | в каталоге пакета | 0644 root:root | Оператор: status ROOT, approve-new|discard|release-text|reject-envelope ROOT ID OPERATOR REFERENCE, rollback-v1 ROOT OPERATOR REFERENCE; ROOT — /.message-receipts; status только читает; rollback-v1 отказывает, пока ledger открыт живым процессом; ошибка — код 2 |
src/pdf-calculation.py | в каталоге пакета | 0644 root:root | /usr/bin/python3 -B, запускается из src/pdf-tool.js (инструмент telegram_make_pdf); нужны reportlab, pypdf, шрифт /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf, бланки из pdfTemplatesDir |
courier/iskra-tell, courier/coder-tell | в каталоге пакета | 0755 root:root | На sadik никто не вызывает: это кандидаты курьеров для aclaude (iskra-tell и ссылки petrovich-/marc-/zarya-/avrora-/varvara-/anna-tell, coder-tell) |
Симлинки профилей (ставятся раскладкой профилей, не этим пакетом): /opt/{avrora,iskra,zarya,spartak,marc,varvara,anna}/.dsh/profiles/web/node_modules/dsh-telegram-multiagent, /opt/coders/{alfa,beta,gamma}/.dsh/profiles/web/node_modules/… (относительная ссылка), /opt/petrovich/.dsh/profiles/node_modules/… → /opt/agent-plugins/dsh-telegram-multiagent.
Лежат в каталоге, но в работе не участвуют: test/ (стенды, помощники, фикстуры), docs/, CHANGELOG.md, README.md, README.en.md, GUEST-PDF.md, LIVE-INPUT.md, MAIL-NEW.md, MAIL-STOP.md, NEW-SESSIONS.md, OLD-PATHS.md, OUTGOING-FILES.md, OWNER-COPIES.md, RECEIPTS.md.
Внешние программы, которые пакет не ставит, но зовёт по абсолютному пути:
| Программа | Кто зовёт | Без неё |
|---|---|---|
/usr/local/bin/a2a-send | копии гостей {kind:"a2a"}, свёртки, письмо руководителю (pismo_rukovoditelyu), местные обратные квитанции | отказ «Local courier failed …; delivery not confirmed»: письмо не положено, ошибка остаётся у вызывающего (строка outbox или ответ инструмента) |
/usr/local/bin/tell-komu | обратные квитанции на другую машину (new-return) | строка уходит в HOLD — до решения оператора |
/usr/local/bin/agent-alert | тревога о недоставленных копиях сайта | тревога не уходит, остаётся строка журнала |
$HOME/.local/lib/dsh-coordinator-signer/prepare-coordinator.mjs | курьер courier/iskra-tell при OT=zabava (подпись координатора) | отказ «подпись не получена; ничего не отправлено», код 2 |
/usr/bin/python3 (+ reportlab, pypdf) | telegram_make_pdf | PDF не собирается |
Что модуль создаёт сам во время работы:
| Путь | Что там |
|---|---|
/.message-receipts/receipts.sqlite, released/, return-notices/ | ledger квитанций, архив прочитанного, обратные квитанции |
/attachments/telegram/ (+ index.json) | входящие вложения, приватные каталоги |
/vydacha// | единственная папка, откуда гость получает файлы |
| ` | |
//pauza.json(на sadik/var/lib/dsh-pauza//`) | опубликованный статус паузы; `` = имя каталога spoolDir |
/dsh-voice-// (умолчание /var/tmp) | временные голосовые, 0700 |
/var/lib/dsh-mail-stop-arrivals/*.json | записи наблюдателя прихода стопа (служба root) |
Установка
В npm доступна редакция 3.1.7 (замер 15.10.2026, npm view dsh-telegram-multiagent version). По решению владельца от 14.10.2026 изменения после публикации ведутся локально и в npm не выкладываются. Актуальную локальную редакцию ставят из дерева по воротам; автор в бой не монтирует. Источник — /opt/iskra/workspace/dsh-plugins/packages/dsh-telegram-multiagent.
- Выпуск: номер версии и заголовок в
CHANGELOG.md, воротаvypusk-tegom, коммит и метка в дереве. - Прогон монтажа (ничего не пишет):
sudo smontirovat-vypusk packages/dsh-telegram-multiagent /opt/agent-plugins/dsh-telegram-multiagent --progon - Монтаж по составу публикации со страховкой в
/var/backups/montazh//:sudo smontirovat-vypusk packages/dsh-telegram-multiagent /opt/agent-plugins/dsh-telegram-multiagent --v-boj - Правка записи
telegram-multiagentв/etc/agent-registry/plugins.yaml(version,fingerprint) черезpravka. - Новый код загружается только при подъёме процесса: назначенная рука перезапускает все службы, которые его грузят (
avrora,iskra,zarya,spartak,marc,petrovich,varvara,anna,alfa,beta,gamma.service). Свою службу агент изнутри не перезапускает. - Юнит наблюдателя ставится отдельно, пофайловым монтажом, и только если он изменился:
sudo smontirovat-fajly --punkt --v-boj /packages/dsh-telegram-multiagent/systemd /etc/systemd/system mail-stop-arrival.service, затемsudo systemctl daemon-reload && sudo systemctl enable --now mail-stop-arrival.service. После сменыobserve-mail-stop.mjsилиmail-stop-arrival.js—sudo systemctl restart mail-stop-arrival.service. Нужны root-owned/etc/dsh-mail-stop/arrival-observer.json(поля ровноroot,mailboxes, не больше 32 ящиков) и каталог/var/lib/dsh-mail-stop-arrivals: наблюдатель создаёт его сам (0755), а уже существующий обязан быть каталогом root, не ссылкой и без записи для группы и прочих — иначе отказarrival_root_untrusted.
Проверка вне фермы, в чистом каталоге (без наших ворот и без платформы DSH):
cd /packages/dsh-telegram-multiagent && npm pack --ignore-scripts --pack-destination /tmp/proba
cd /tmp/proba && npm init -y && npm install --ignore-scripts ./dsh-telegram-multiagent-*.tgz @deepseek-ai/cordis@4.0.1
cd node_modules/dsh-telegram-multiagent && npm test
@deepseek-ai/cordis 4.0.1 — devDependency пакета, лежит в открытом реестре npm; без него слепнут стенды, грузящие модуль через cordis. Платформу DSH (@deepseek-ai/dsh-session и др.) так не поставить: стенды, которым она нужна, слепы, пока не задан DSH_TEST_APP — каталог app установленной платформы. Соседние пакеты — GATEWAY_CANDIDATE, ADAPTER_CANDIDATE, BRIDGE_CANDIDATE. Слепота — не отказ пакета: что именно слепнет и почему — docs/GUARDS.md, «Состав test/».
Подключение агенту: блок - insert: - name: dsh-telegram-multiagent в профиле, собранном из шаблона реестра, плюс симлинк в node_modules профиля. Правка профиля руками запрещена — только через реестр (agents.yaml и шаблоны).
Настройка
Настройки приходят из трёх мест: config модуля в профиле, JSON-файл settingsFile и окружение процесса. Пути в бою: токен — /etc/dsh-telegram/.token, JSON — /etc/dsh-telegram/.json.
config в профиле (читается при подъёме):
| Ключ | Умолчание | Смысл |
|---|---|---|
tokenFile | не задан | Файл с токеном бота; читается первым. Пустой или нечитаемый — канал не поднимается |
token | не задан | Токен прямо в конфиге; берётся, только если нет tokenFile |
tokenEnv | DSH_TELEGRAM_BOT_TOKEN | Имя переменной окружения с токеном; последний запасной источник |
settingsFile | tokenFile с заменой .token → .json | JSON с перечитываемыми настройками (таблица ниже) |
appDir | $DSH_APP_DIR | Установка DSH этого агента; от неё разрешаются @deepseek-ai/dsh-*. Не задано или не разрешилось — канал не поднимается |
workspace | process.cwd() | Рабочий каталог: ledger, вложения, vydacha/, cwd сессий |
agentName | telegram в журнале, агент в текстах | Имя агента в журнале и в текстах собеседнику; имя по умолчанию для обращения в группе |
allowedUsers | [] | Числовые ID Telegram с привилегиями. При openBot: false пустой список не пускает никого |
openBot | false | true — говорить можно всем; команды, цели и копии остаются только у allowedUsers; включает telegram_make_pdf и копии гостей |
preset | выбор платформы | Пресет инструментов для обычных разговоров |
guestPreset | site.preset | Пресет для гостевых чатов открытого бота |
provider, model | agentDefaultModel платформы | Запасной выбор модели, если сервис модели по умолчанию не поднялся |
mergeChatIntoA2A | не задан | ID личного чата, сведённого в сессию служебного канала (a2aSession) |
a2aDir | не задан (A2A выключен) | Каталог обмена: in/ (вход), out/ (ответы), polnye/ (зеркало исходящих для копий), tell/ |
a2aSession | a2a | Ключ разговора служебного канала |
spoolDir | не задан (выключен) | Ящик почтальона; имя каталога — ключ агента для паузы, стопа почтой и управления Codex. Без абсолютного пути пауза не |