Telegram-плагин для BB: публикация как отдельная система.

У отправки есть владелец

Идемпотентность начинается до Telegram

CREATE TABLE publications (
  id TEXT PRIMARY KEY,
  channel_id TEXT NOT NULL REFERENCES channels(id),
  idempotency_key TEXT NOT NULL,
  text TEXT NOT NULL,
  text_sha256 TEXT NOT NULL,
  source_json TEXT NOT NULL,
  status TEXT NOT NULL CHECK (status IN (
    'draft', 'publishing', 'published', 'uncertain', 'failed'
  )),
  telegram_message_id TEXT,
  last_error TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE (channel_id, idempotency_key)
);

async function publish(input: PublishInput): Promise<PublicationResult> {
  assertTelegramTextLength(input.text);

  const channel = await channels.findAllowed({
    projectId: input.projectId,
    channelKey: input.channelKey,
  });
  assertCanPublish(channel, input.initiator, input.userExplicitlyAsked);

  const existing = await publications.find(channel.id, input.idempotencyKey);
  if (existing?.status === "published") return toCompactResult(existing);
  if (existing?.status === "uncertain") {
    throw new PublicationUncertain(existing.id);
  }
  if (existing?.status === "publishing") {
    throw new PublicationInProgress(existing.id);
  }

  const publication = await publications.createPublishing({
    channelId: channel.id,
    idempotencyKey: input.idempotencyKey,
    text: input.text,
    source: input.source,
  });

  try {
    const message = await telegram.sendPlainText(channel.chatId, input.text);
    await publications.markPublished(publication.id, message.message_id);
    return { publicationId: publication.id, status: "published" };
  } catch (error) {
    const result = classify(error);
    if (result.kind === "definite_failure") {
      await publications.markFailed(publication.id, result.safeMessage);
    } else {
      await publications.markUncertain(publication.id, result.safeMessage);
    }
    throw error;
  }
}

Права канала и токен живут в разных местах

function assertTelegramTextLength(text: string) {
  const length = Array.from(text).length;
  if (length < 1 || length > 4096) {
    throw new ValidationError("Текст для Telegram должен содержать от 1 до 4096 символов.");
  }
}

CLI остаётся удобным, но не становится обходным путём

bb telegram-publisher channel add \
  --key editorial \
  --name "Редакционный канал" \
  --chat-id @editorial_channel \
  --project /work/newsroom \
  --mode draft

bb telegram-publisher channel check --key editorial

bb telegram-publisher draft create \
  --channel editorial \
  --text-file ./post.txt \
  --idempotency-key article:bb-plugin-telegram-publisher:announce

bb telegram-publisher publish \
  --channel editorial \
  --draft <draft-id> \
  --idempotency-key article:bb-plugin-telegram-publisher:announce

Инструмент агента должен уметь отказаться

Тесты проверяют момент, когда уже поздно исправлять

Источники

• BB: changelog о плагинах, CLI, agent tools и собственном SQLite
• Telegram Bot API: sendMessage, идентификатор чата и лимит текста
• Telegram: базовая настройка бота и отправка сообщений в чаты при нужных правах

Полный текст задания для агента

Создай отдельный BB-плагин `bb-plugin-telegram-publisher`.
Это инфраструктурный плагин для подключения множества Telegram-каналов и
надёжной публикации из BB-тредов и BB-автоматизаций.

Граница ответственности:

- Плагин отвечает за Telegram: боты, каналы, права доступа, черновики,
  отправку сообщений, логи и защиту от дублей.
- Автоматизации и треды не должны обращаться к Telegram Bot API напрямую:
  только через CLI или agent tools этого плагина.

Перед реализацией:

- Прочитай актуальные SDK-типы и нужные инструкции BB plugin authoring.
- Создай плагин через `bb plugin new`; не пиши scaffold вручную.
- Используй текущий SDK как источник истины, не изобретай API.

Настройки плагина:

- `botToken`: обязательная secret-настройка плагина.
- `apiBaseUrl`: обычная настройка с безопасным значением по умолчанию
  `https://api.telegram.org`.
- Никогда не сохраняй токен в SQLite, файлах проекта, выводе CLI, логах,
  сообщениях агента или тестовых фикстурах.
- Если для реальной настройки потребуется токен, попроси его только через
  безопасный механизм BB для секретов, не в чате.

Хранилище:

- Используй исключительно `bb.storage.database()` и миграции
  `bb.storage.migrate()`. Не создавай SQLite-файл вручную в проекте.
- Сделай таблицы:
  - `channels`: ключ канала, название, Telegram `chat_id` или `@username`,
    включённость, режим (`draft` или `auto`), даты создания и изменения.
  - `channel_projects`: связь каналов с разрешёнными BB-проектами.
  - `publications`: канал, idempotency key, текст, хеш, источник, статус,
    Telegram message ID, время публикации, последняя ошибка.
  - при необходимости `publication_attempts` для журнала попыток.
- Уникальность публикации должна быть как минимум
  `(channel_id, idempotency_key)`.

Безопасность публикаций:

- Канал доступен треду или автоматизации только при явном разрешении для
  соответствующего проекта.
- Для каждой публикации обязателен `idempotencyKey`.
- Повторный вызов с уже опубликованным ключом должен вернуть сохранённый
  результат и не создавать новое сообщение.
- Перед отправкой сохраняй состояние `publishing`.
- Если Telegram вернул успешный ответ, запиши `message_id` и статус
  `published`.
- Если сеть оборвалась после потенциальной отправки и исход неизвестен,
  ставь `uncertain` и не повторяй отправку автоматически.
- Не публикуй сообщения при ошибке, капче, отсутствии токена или неясном
  состоянии.
- По умолчанию текст отправляется без Markdown/HTML parse mode. Поддержку
  форматирования можно добавить явно и с валидацией позднее.
- Валидируй лимит Telegram на длину сообщения и возвращай понятную ошибку,
  не обрезай текст молча.

CLI плагина:

Реализуй понятные команды с `defineCli`, полной справкой и JSON-выводом.

Нужны возможности:

- подключить канал: ключ, отображаемое название, `chat_id`, проект,
  режим публикации;
- показать список каналов и их статус;
- включить или отключить канал;
- безопасно проверить токен и доступ бота к каналу без публикации;
- создать черновик;
- показать черновики и публикации;
- опубликовать текст или черновик с каналом и idempotency key.

Для многострочного текста CLI должен принимать файл. Учти multi-machine
правило BB: не читай пользовательский путь через `node:fs` на сервере;
используй SDK-файловую API соответствующего хоста.

Agent tools:

- Добавь read-only tool для списка доступных каналов.
- Добавь tool создания черновика.
- Добавь tool публикации.
- В инструкциях tool явно укажи: агент публикует только когда пользователь
  прямо попросил отправить сообщение либо когда канал имеет режим `auto` и
  вызов пришёл от разрешённой автоматизации.
- В agent tools также обязателен `idempotencyKey`.
- Вывод tools и CLI должен быть компактным и не содержать токенов или полного
  текста больших сообщений.

Документация и проверка:

- Добавь собственный `skills/` каталог с инструкцией по настройке бота,
  подключению канала, режимам `draft` и `auto`, CLI и agent tools.
- Добавь README с архитектурой, ограничениями и примерами команд.
- Добавь тесты миграций, project allow-list, идемпотентности, повторной
  публикации, `uncertain`-состояния, ограничений длины и ошибок Telegram API.
- Не отправляй реальное сообщение при тестировании. Используй mock API или
  тестовый transport.
- Выполни `bb plugin types` и `bb plugin build`.
- После сборки установи плагин локально, проверь `--help` и основные команды
  без токена, затем сообщи, какие действия требуются от пользователя для
  подключения бота и канала.

В финальном отчёте перечисли созданные файлы, результаты тестов, команды
и любые решения, которые потребуют
подтверждения пользователя.