maxdshbot

dsh-max-notify

Последний ответ агента — в MAX. Пульт управления, approvals, стоимость и наблюдаемость — оттуда же.
Плагин для DeepSeek Harness · мессенджер MAX · ноль runtime-зависимостей

Быстрый старт · Возможности · Команды · Архитектура · Конфигурация · Roadmap · Changelog

[!NOTE] Плагин ставится в web-профиль DSH через link: и переживает перезагрузки: состояние (маркер polling, outbox, дедуп-ключи, health) лежит вне репозитория, в $DSH_HOME/max-notify/. Доступ — только по allowlist, интерактив fail-closed. Всё, что агент пишет, уходит на серверы MAX — для чувствительных сессий используйте enabled: false или dryRun: true.

Что умеет

Архитектура

flowchart LR
  subgraph DSH["DeepSeek Harness (web profile)"]
    EV["session/event<br/>turn/end · assistant/message"]
    W["approval / user-questions<br/>waterfalls"]
    CM["commands · planMode<br/>workspaceRegistry · sessionController"]
    LEDGER[("cost-meter<br/>ledger.json")]
  end

  subgraph PLUGIN["dsh-max-notify"]
    NOTIFY["notify + format"]
    BOT["bot · commands · cards"]
    INTER["interactions<br/>approve / questions"]
    OUTBOX["outbox · limiter"]
    HEALTH["health · audit · redact"]
    COST["cost adapter"]
  end

  MAX[("MAX Bot API<br/>platform-api2.max.ru")]

  EV --> NOTIFY --> OUTBOX --> MAX
  BOT <-->|long polling / replies| MAX
  W --> INTER --> BOT
  CM --> BOT
  LEDGER --> COST --> BOT
  OUTBOX --> HEALTH
  PLUGIN -->|"0 runtime deps · node builtins"| DSH

Плагин не форкает DSH и не патчит ядро: он использует штатные швы session/event, waterfall-события approvals/questions, sessionController, commands, planMode, workspaceRegistry и read-only ledger dsh-cost-meter.

Быстрый старт

Установка из npm (рекомендуется)

dsh plugin --profile web add dsh-max-notify

Из git-чекаута (для разработки)

git clone https://github.com/enkolesnikov/MaxDSHBot.git
cd MaxDSHBot

cp .env.example .env && chmod 600 .env   # MAX_BOT_TOKEN=..., MAX_CHAT_ID=...
node dsh-max-notify/tools/pair.mjs       # узнать chat_id: нажать Start в диалоге с ботом
node dsh-max-notify/tools/send-test.mjs "проверка"

./dsh-max-notify/install.sh              # профиль web (или: ./install.sh tui)

Оба способа добавляют пакет в dsh.profile.bundles, а его cordis.patch.yml вставляет строку max-notify. Пакет: npmjs.com/package/dsh-max-notify.

- id: max-notify
  config:
    botTokenFile: /path/to/MaxDSHBot/.env
    chatId: 123456789
    allowedUserIds: [987654321]

Команды в MAX

Текст без / уходит агенту как следующее сообщение. Под финальным ответом — кнопки «Продолжить», «Стоп», «Открыть GUI» и настраиваемые пресеты.

Webhook (production-транспорт)

По умолчанию работает long polling. Для production можно включить webhook — MAX будет сам присылать обновления на публичный HTTPS-эндпоинт:

- id: max-notify
  config:
    transport: webhook
    webhookPath: /max/webhook
    webhookPublicUrl: https://example.com/max/webhook
    webhookSecret: ${MAX_NOTIFY_WEBHOOK_SECRET}   # 5–256 символов [A-Za-z0-9_-]
    webhookAutoSubscribe: true

1. webServer.register добавляет точный маршрут в уже работающий DSH HTTP-сервер (nginx с Let's Encrypt терминирует 443 и проксирует на DSH).
2. MAX проверяет TLS-цепочку, домен и secret-заголовок; каждое обновление сначала сохраняется в durable-очередь state.json, потом отвечаем 200.
3. Обработка идемпотентная (общий dedupe с polling), при сбое — 503, MAX повторит; после 8 часов неудач отписка автоматическая.
4. Подписка управляется автоматически (GET/POST /subscriptions), вручную: node tools/webhook.mjs status|subscribe|unsubscribe --env ../.env.

Если webServer/secret/public URL не сконфигурированы, плагин откатывается на long polling и пишет warning в лог. Официальная документация MAX: webhooks.

Брифинг и статус (v1.5)

• /brief — компактный брифинг: что работает, что ждёт решения, деньги, ближайшие расписания. В меню теперь 13 команд.
• /status стал короче: title ≤30 символов, папка basename, деньги с двумя знаками; если сессия дороже «сегодня», пишется «сессия всего».
• Исправлены русские склонения в брифинге/дайджесте.

UX-аудит (v1.4)

• 12 команд в меню вместо 31 (в 1.5 — 13 с /brief); /help ≤450 символов, полный список — /help all.
• Компактный заголовок 🕒 20:03 · Название; старый подробный режим — messageStyle: detailed.
• Тише по умолчанию: subagent/job/goal/TODO-уведомления выключены; остаются финальные ответы, ошибки, approvals/questions и бюджетные алерты.
• Approval-карточка без callId; результат одной строкой; GUI-ответы не создают отдельную карточку; job/subagent/goal — одна строка; digest — «брифинг».
• Продвинутые команды (/diff, /send, /approve, /workspace, /say, …) скрыты из меню, но работают; аудит и причины — в docs/ux.md.

Автономные расписания (v1.3)

• /schedules mode N inherit|read-only|auto — политика для конкретной задачи. read-only разрешает только чтение и отклоняет запись/команды; auto разрешает всё (только после подтверждения), inherit — обычные approvals.
• Решения принимаются автоматически во время запуска по расписанию, без карточки в MAX; пишутся в audit (kind: autonomy).
• auto/read-only переживают reload, отображаются в /schedules; сопоставление — по target/involved session, для new — по заголовку и свежей delivery-записи.

Голос и инструменты (v1.2)

• /say <текст> — озвучить текст; авто-TTS коротких финальных ответов (voiceTts, voiceTtsMode: off|short|always) через OpenAI-совместимый /audio/speech; аудио уходит отдельным сообщением, ошибки TTS не мешают тексту.
• /diff [--staged] [путь] — git diff папки сессии файлом diff.patch.
• /send <путь> — отправить файл из папки сессии; выход за cwd запрещён, лимит 25 МиБ, тип вложения по расширению.
• Настройки применяются без рестарта: mode/дайджест/тихие часы/reply-ветки/ таблицы/TTS/approvals и др. — через GUI; transport/секреты — после перезагрузки.

GUI-настройки, голос, нативные изображения (v1.1)

• Страница настроек в GUI: DSH → Plugins → dsh-max-notify — форма для режима, дайджеста, тихих часов, reply-веток, таблиц, файлов, голоса, таймаутов. Правки сохраняются в $DSH_HOME/max-notify/config.json (0600) и применяются после перезагрузки строки; секреты (токены/ключи) страница не показывает.
• Нативные входящие изображения: картинки из MAX передаются агенту image-партами, с текстовым fallback, если модель/route не принимает images.
• Голосовая расшифровка (STT): опциональный OpenAI-совместимый endpoint; аудио из MAX расшифровывается и уходит агенту текстом.
• TTS, multi-chat и внешний каталог — в 1.2.

Reply-ветки, таблицы, расписания (v1.0)

• Reply-ветки: первый ответ сессии становится якорем, следующие приходят реплаями к нему; ответ пользователя на любой ответ уходит в исходную сессию. Якоря/mid→session переживают reload.
• Таблицы → файлы: markdown-таблицы дополнительно уходят как table-N.csv и table-N.md, текст ответа заменяется плейсхолдером (MAX не рендерит таблицы).
• /schedules: список задач, pause/resume N, cancel N с подтверждением.
• Forwarded-сообщения из MAX разворачиваются и передаются агенту.
• /say, /diff, /send — озвучка, git-diff и отправка файлов.
• /schedules mode N ... — автономный режим задачи (read-only/auto).
• /settings: снимок эффективных настроек (transport, режим, allowlist, таймауты, фичи) без секретов.
• Полный GUI-редактор настроек, голос и нативные входящие изображения — в 1.1.

Надёжность и безопасность

• Durable outbox — финальные ответы и уведомления переживают недоступность MAX и reload; retry с backoff, TTL, приоритеты, дедуп по session:turn:seq.
• At-least-once polling — marker сдвигается после обработки; обработанные update-id сохраняются, повторная доставка не дублирует промпты.
• Лимитер — 2 запроса/с на чат, 30/с суммарно; approvals/ошибки идут critical-каналом.
• Fail-closed — без allowedUserIds/allowedChatIds команды, approvals и polling выключены; уведомления работают. allowUnlistedUsers: true — осознанный escape.
• Approvals — таймаут 120 с, «запомнить» только для явного approvalRememberTools, audit $DSH_HOME/max-notify/audit.jsonl (0600).
• Health/redaction — /health, heartbeat-файл, redaction токенов в логах, rate-limit входящих.

Конфигурация

Структура

Ограничения

Проверка

cd dsh-max-notify && npm test          # 353 unit tests
npm run check                          # синтаксис всех модулей
node tools/smoke.mjs --env ../.env     # read-only: GET /me, state, outbox
node tools/send-test.mjs "проверка"    # реальная отправка

TLS-цепочка проверена openssl verify (leaf → Russian Trusted Sub CA → Root CA); живая отправка — HTTP 200 с mid, markdown-разбор подтверждён GET /messages.

Документация

• ROADMAP.md — план 0.9 → 1.0.
• CHANGELOG.md — история версий.
• SECURITY.md — секреты, allowlist, аудит.
• research/ — устройство DSH-плагинов, MAX Bot API, каталог фич.
• dsh-max-notify/README.md — справка по пакету (EN).

Лицензия

MIT — см. LICENSE.