Компонентная разработка vs «Durex-код»

📘 Памятка инженера Metabot

1️⃣ В чём разница подходов

Скриптовый подход Компонентный подход
Код вставляется прямо в сценарий Сценарий использует готовый компонент
Telegram-логика торчит в webhook-скрипте Telegram спрятан внутри плагина
Сценарист не может этим пользоваться Сценарист работает декларативно
Нет чёткого контракта Есть входы, выходы, параметры
Разовое решение Переиспользуемый модуль
Зависит от конкретного проекта Доставляется в любой проект

2️⃣ Что такое «Durex-код»

Durex-код — это:

Это не плохо. Иногда это допустимо.

Но это не архитектурный стиль Metabot.

3️⃣ Что такое компонентный стиль Metabot

Компонент — это:

Пример:

const VoiceInput = require('Common.Voice.VoiceInput')

return VoiceInput.expect({
  code: "orion_profiling_q1_voice",

  lead,

  successScript: "orion_profiling_q2",
  cancelScript: "orion_profiling_cancelled",

  targetAttr: "orion_profiling_q1_text",
  sourceAttr: "orion_profiling_q1_voice_url",

  extraAttrs: {
    active_agent: "orion",
    voice_context: "orion_profiling_q1",
    input_mode: "profiling"
  },

  processorScript: "System_VoiceInput_Processor",

  stt: {
    provider: "openai",
    options: { model: "whisper-1", language: "ru" },
    asyncResponse: true,
    tokenKey: "OPENAI_API_KEY"
  }
})

Сценарист видит:

Он не видит:

Это декларативный стиль.

4️⃣ Что такое декларативный подход

Декларативный подход — это:

Мы описываем ЧТО должно произойти, а не КАК это происходит.

Сценарист пишет:

Ожидай голос.
Перейди в success.
Сохрани результат.

А не:

Проверь payload.message.voice
Достань file_id
Сходи в Telegram API
Отправь в STT
Подожди callback
Распарси JSON

5️⃣ Принципы компонентной разработки Metabot

1. Чёткий контракт

Каждый компонент обязан иметь:

2. Нет неявной передачи данных

❌ Плохо:

memory.foo = 123

Потом в другом месте:

memory.foo

Это разрыв контракта.

✔ Правильно:

3. Одна зона ответственности

Пример:

VoiceInput:

ArtifactResolver:

4. Никаких «всё в один файл»

Если логика растёт — создаём слой.

Пример:

Это инженерный подход.

5. Повторное использование — обязательное требование

Если модуль нельзя переиспользовать — это не компонент.

Компонент должен быть:

6️⃣ Почему это важно

  1. Сценаристам проще
  2. Интеграторам проще
  3. Код чище
  4. Проекты масштабируются
  5. Плагины можно доставлять в разные компании
  6. Мы получаем архитектурную степень свободы

И самое интересное:

⏱ По времени это занимает примерно столько же.

Разница — в мышлении.

6.1 🔓 Декларативный стиль = расширяемая палитра Metabot

Декларативный подход — это не только «красиво».

Это позволяет нам:

Сейчас в Metabot есть ~21 атомарная команда.

Примеры:

Каждый компонент:

Это позволяет:

1️⃣ Легко расширять платформу Добавили новый компонент → он сразу становится частью палитры.

2️⃣ Делать визуальные конструкторы Если у компонента есть вход/выход — можно рисовать схемы.

3️⃣ Строить workflow-системы Компоненты становятся узлами графа.

4️⃣ Делать экспортируемые решения Компонент можно доставить в другой проект.

6.2 🧱 Атомарность = возможность визуализации

Если компонент описан как:

его можно:

Если код:

его нельзя:

7️⃣ Архитектор vs Скриптовик

Скриптовик думает:

Мне нужно сделать, чтобы работало.

Архитектор думает:

Как сделать, чтобы это работало в 10 проектах.

8️⃣ Как использовать это как AI-чеклист

Можно кидать в AI вместе с кодом и спрашивать перед коммитом:

Если на 3+ вопроса ответ «нет» — ты пишешь Durex.

9️⃣ Когда допустим Durex-код

Иногда допустимо:

Но:

1️⃣0️⃣ Когда допустимо писать код в скрипте

Код в скрипте допускается.

Но только если соблюдены условия.

✔ Допустимые случаи

1️⃣ Абсолютно разовая логика

Пример:

if (lead.getAttr("score") > 10) {
  return bot.run({ script_code: "vip_branch" })
}

Это допустимо.

2️⃣ Логика понятна сценаристу

Если сценарист:

— код допустим.

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

Исключение — системные вещи без которых абсолютно нельзя обойтись, например, вызов плагинов.

3️⃣ Логика не нарушает архитектуру

Допустимый код:

❌ Недопустимый Durex-код

Код нельзя писать в сценарии, если:

Такой код должен быть:

1️⃣1️⃣ Финальная мысль

Metabot — это не набор скриптов.

Это:

Если ты пишешь код, который нельзя вынести в палитру — ты... выпускаешь Durex.

Если ты пишешь код, который расширяет палитру — ты работаешь как инженер платформы.

P.S. Почему «Durex»?

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

А разовый скрипт — это расход периода: проект сделали, прибыль получили — но актива не появилось. Работу сделали один раз, в следующем проекте — делаем то же самое заново. Все при деле, задача выполняется, но капитал не создаётся.

Версия #7
Artem Garashko создал 17 February 2026 13:18:28
Artem Garashko обновил 17 February 2026 15:59:00