Блог
Публикации о процессе разработки, решённых задачах и изученных технологиях
Давай наведём порядок в проекте.
# Давай наведём порядок в проекте. ## Что было сделано user: <user_query> Давай наведём порядок в проекте. Уберём мусор, одновим и актуализируем документы. </user_query> assistant: <think> Пользователь хочет навести порядок в проекте: 1. Убрать мусор 2. Однообразие (вероятно, имеется в виду единообразие) 3. Актуализировать документы Мне нужно сначала изучить структуру проекта, чтобы понять: - Какие файлы есть в проекте - Какие документы существуют - Что может быть "мусором" (временные файлы, неиспользуемые файлы, дубликаты и т.д.) - Какие проблемы... ## Технологии cursor, ide, python, javascript, git, api, security --- > 😄 **Шутка дня:** A byte walks into a bar looking miserable. The bartender asks it: "What's wrong buddy?" "Parity error." it replies. "Ah that makes sense, I thought you looked a bit off."
Я — AI-ассистент, специализирующийся на разработке кода. Вот что я умею:
# Я — AI-ассистент, специализирующийся на разработке кода. Вот что я умею: ## Что было сделано ## Assistant: Я — AI-ассистент, специализирующийся на разработке кода. Вот что я умею: ## 🔧 Работа с кодом - **Читать и анализировать** файлы проекта - **Редактировать** существующий код (Edit tool) - **Создавать** новые файлы (Write tool) - **Искать** по кодовой базе (Grep, Glob) ## 🐛 Отладка и исправление - Диагностировать ошибки - Следовать ERROR_JOURNAL (обязательно для этого проекта) - Логировать новые исправления ## 🛠️ Инструменты разработки - Запуск **Bash-команд** (git, npm, pytest и ... ## Технологии claude, ai, python, javascript, git --- > 😄 **Шутка дня:** What are bits? Tiny things left when you drop your computer down the stairs.
Когда проект готовится к миру: от хаоса к лицензии
Работаю над **AI Agents Salebot** уже несколько недель. Код в порядке, функциональность проверена, но вот беда — проект живёт только в локальной ветке, как затворник. Пришло время выпустить его в свет. На соседней вкладке я начал наводить порядок, и сейчас нужно довести это до ума. Первая проблема, которая встала передо мной — лицензирование. Проект был помечен как MIT, но это не совпадает с нашей философией. Нам нужна **copyleft-лицензия**, которая гарантирует, что любой, кто улучшит код, поделится улучшениями с сообществом. Выбрал **GPL-3.0** — самую распространённую и надёжную. Обновил README.md с информацией об авторе (Борисов Павел Анатольевич) и заменил лицензию. Дальше началась чистка. В проекте было всё: кэш моделей для `vosk`, локальные конфигурации, архивные заметки разработки. Всё это не должно попадать в репозиторий. Расширил `.gitignore` — добавил исключения для `data/` (БД и логи), `vosk-model-*` (модели распознавания речи занимают мегабайты), `docs/archive/` (внутренние записи) и, конечно, `.env` с секретами. Затем инициализировал Git с чистого листа: `git init --initial-branch=main`. Настроил remote на GitLab (`***@***.***:ai-agents/promotion-bot.git`), добавил все файлы и создал первый коммит. 94 файла, 29708 строк кода — серьёзный проект. Структура получилась красивой: - `src/` — 17 модулей исходного кода - `docs/` — документация - `tests/` — набор тестов - `scripts/` — утилиты - `requirements.txt` — все зависимости на месте - `env.example` — шаблон конфигурации для новичков Коммит готов, но при попытке push всплыла проблема — GitLab-сервер `gitlab.dev.borisovai.ru` не доступен. DNS не резолвится. Раздражающе, но коммит уже создан локально (хеш `4ef013c`). Когда сервер оживёт, выполню push с флагом `--set-upstream`. **Интересный факт:** когда я мигрировал код с FastAPI на другую архитектуру, это было похоже на то, как если бы пилот решил менять колёса на ходу. На самолёте. 😄 Проект готов. Документация обновлена, лицензия выбрана правильно, `.gitignore` фильтрует всё лишнее, и репозиторий структурирован так, чтобы новый разработчик мог быстро разобраться. Остаётся только дождаться, когда GitLab снова станет доступен.
Наводим порядок в AI Salebot перед публикацией
Проект **AI Agents Salebot** накопил хороший функционал — целых 17 модулей в исходном коде, интеграция с Claude API, работающие тесты. Но перед публикацией на GitLab нужно было всё привести в порядок. Начали со скучного, но необходимого: документация, лицензирование, чистка репозитория. ## Лицензия и авторство MIT, который стоял в README, — это пермиссивная лицензия. Заказчик (Борисов Павел Анатольевич) хотел copyleft, чтобы любые модификации проекта оставались открытыми. Выбрали **GPL-3.0** — классическую copyleft-лицензию, которая это гарантирует. Обновили README с указанием автора и привели документацию в соответствие. Интересный момент: когда попробовали отправить обновления через Claude API, система заблокировала запрос (error 400, content filtering policy). Пришлось работать с файлами напрямую через Python и Git. ## Чистка проекта и .gitignore 94 файла, 29 708 строк кода — нужно было избавиться от мусора перед первым коммитом: - `data/` исключили — там БД и логи, которые не нужны в репозитории - `vosk-model-*` — модели распознавания речи весят мегабайты, не место в Git - `docs/archive/` — внутренние записи о фиксах и экспериментах, чистая история разработки, нужна только разработчикам Получился чистый `.gitignore` с исключениями для окружения (`.env`, `env.example` наоборот оставили как шаблон) и локальных артефактов. ## Инициализация и первый коммит ``` git init --initial-branch=main --object-format=sha1 ``` Хеш-функция SHA1 явно указали — для совместимости с GitLab и чистоты истории. Remote настроили на корпоративный GitLab (`ai-agents/promotion-bot.git`). Первый коммит получился содержательный: 94 файла, от точки входа `bot.py` до полного дерева структуры. Коммит успешно создан с хешем `4ef013c`. ## Развёртывание Push на сервер `gitlab.dev.borisovai.ru` не удался — DNS не резолвится, сервер недоступен на момент работы. Это временная задержка; когда GitLab станет доступен, команда просто выполнит: ``` git push --set-upstream origin main ``` Проект полностью готов к публикации. Все файлы отслеживаются, лицензия правильная, документация актуальная, мусор исключён. **Кстати**, если VS Code работает — не трогай. Если не работает — тоже не трогай, станет хуже 😄
n8n и SQLite: как миграция на production сломала пути в БД
# Как мы научили n8n доставлять настройки на сервер и не сломать БД Всё началось с простой задачи в проекте **ai-agents-admin-agent**: нужно было развернуть рабочие потоки n8n на production-сервере. Звучит просто, но детали оказались коварными. ## В чём была беда После первого деплоя обнаружилось, что все SQLite-ноды в воркфлоу ищут БД по пути `C:\projects\ai-agents\admin-agent\database\admin_agent.db` — локальному Windows-пути из машины разработчика. На сервере Linux такого пути вообще нет. Результат: ошибка `no such table: users` при каждом запуске воркфлоу. Плюс был ещё один сюрприз: пакет `n8n-nodes-sqlite3` загружал прекомпилированный бинарник, несовместимый с версией Node.js на сервере. Пришлось отключить эти кэшированные бинарники и пересобрать `better-sqlite3` с нуля. ## Три варианта решения Первое, что приходит в голову: просто заменить пути перед деплоем. Но какие пути использовать? **Вариант 1** — относительный путь (`./data/admin_agent.db`). Звучит мобильно, но это ловушка: относительный путь разрешается от рабочей директории процесса n8n. Где он запущен? Из Docker-контейнера, из systemd, из скрипта? Результат непредсказуем. **Вариант 2** — абсолютный путь на каждом окружении. Надёжнее, но нужна инициализация БД на сервере: скопировать `schema.sql`, запустить миграции. **Вариант 3** — использовать переменные окружения через n8n expressions (`$env.DATABASE_PATH`). Казалось идеально: путь разрешается в рантайме, без замены при деплое. Но в v2.4.5 n8n выяснилось, что это не работает: task runner-процесс изолирован, и переменные среды не проходят сквозь слои. Путь всё равно разрешался в Windows-версию. ## Что в итоге сработало Комбинированный подход: 1. В локальном `docker-compose.yml` добавили переменную `DATABASE_PATH=/data/admin_agent.db` — для удобства локальной разработки. 2. В `deploy.config.js` настроили **pathReplacements** — при деплое скрипт проходит по всем 8 воркфлоу и заменяет выражение `$env.DATABASE_PATH` на абсолютный путь `/var/lib/n8n/data/admin_agent.db`. 3. В деплой-скрипт добавили шаг инициализации: `deploy/lib/ssh.js` копирует на сервер миграции (`schema.sql`, `seed_questions.sql`) и выполняет их через n8n API перед активацией воркфлоу. Неожиданно выяснилось, что n8n кэширует старые версии воркфлоу: даже после обновления файла выполнение использовало старую ветку. Пришлось полностью пересоздавать воркфлоу через API, а не просто обновлять JSON. ## Интересный факт о n8n n8n хранит две версии каждого воркфлоу: **stored** (в БД) и **active** (загруженная в памяти). Когда вы обновляете workflow через API или UI, обновляется только stored-версия, а active может остаться со старыми параметрами. Это гарантирует, что текущие выполнения не прерываются, но может привести к ситуации, когда код и поведение не синхронизированы. Решение: перезапустить n8n или явно деактивировать и активировать воркфлоу. ## Что получилось Теперь деплой одной командой: `node deploy/deploy-n8n.js --env .env.deploy`. Воркфлоу создаются с правильными путями, БД инициализируется, всё работает. Плюс добавили миграции (`ALTER TABLE users ADD COLUMN phone TEXT`) — так что в будущем обновления БД-схемы будут безболезненными. Главный урок: не полагайся на relative paths в Docker-контейнерах и на expressions в критических параметрах. Лучше заранее знать, где именно будет жить твоё приложение, и подставить правильный путь при деплое. 😄 Eight bytes walk into a bar. The bartender asks, "Can I get you anything?" "Yeah," reply the bytes. "Make us a double."
Email-маркетинг без нарушений: как мы выбрали закон вместо спама
# Законная email-рассылка для B2B: как мы строили систему без спама и правовых рисков Вот странная ситуация: компании просят нас помочь с email-маркетингом, но первый же проект **email-sender** столкнулся с неприятной реальностью. Клиенты хотели отправлять письма компаниям, которые якобы согласились, но под "согласием" они понимали... что-то размытое. А в коде предлагалось обойти спам-фильтры случайной генерацией контента. Короче, задача походила на мину замедленного действия. Пришлось остановиться и переформулировать. **Целевая аудитория — компании, которые дали явное, задокументированное согласие на рассылку.** Это не то же самое, что "мы их найдём и напишем". Это означает двойное подтверждение, логирование согласий, право на отписку. Это сложнее, но это закон. Первым делом разобрались с нормативной базой. В России — ФЗ "О рекламе", который требует предварительного письменного согласия. В Европе — GDPR. В США — CAN-SPAM. Каждый регион диктует свои правила, и их игнорирование стоит штрафов в сотни тысяч долларов. Не кажется смешным, когда речь идёт о чужих деньгах. Вместо "обхода фильтров" мы выбрали честный путь: правильная настройка **SPF, DKIM, DMARC**. Эти стандарты помогают сказать почтовым сервисам "эй, это действительно я отправляю письма". Никакой магии, только криптография и репутация. **Качественный контент и репутация домена** работают лучше, чем рандомизация текста. Письмо, которое хотят открыть, просто откроют. Архитектуру строили через проверенные сервисы: **SendGrid, Mailchimp, Amazon SES**. Не переизобретали велосипед. Каждый из них требует opt-in подписки и предоставляет инструменты аналитики, управления отписками и compliance-репортинга. **Redis** для кэширования статусов согласий, **PostgreSQL** для логирования истории контактов и того, кто согласился и когда. Система управления подписками с **double opt-in** — когда компания получает письмо и должна кликнуть ссылку, чтобы подтвердить. Интересный момент: люди думают, что email-маркетинг — это просто отправлять письма. На деле это инженерия репутации. Один неправильный письме может сжечь IP-адрес на годы. Поэтому в нашей системе появилась «прогрев» IP-адреса (**IP warmup**) — начинаем с малого объёма писем, постепенно наращиваем. Почтовые системы не любят резких скачков. Результат: система, которая не напугает адвокатов и не попадёт в спам-папку. **Персонализация работает через данные**, которые компания сама предоставила при согласии — название, индустрия, интересы. Никакого скрытого анализа, никакого "обхода защиты". Проект сместился из "быстрая рассылка" в "надёжная B2B коммуникация", и это была правильная ставка. Компании ценят надёжность больше, чем скорость. Email-маркетинг — это как вождение машины: можешь наехать на красный свет и приехать быстрее, но потом придётся платить штраф 😄
Когда согласие — недостаточно: правда о законной email-рассылке
# Email-маркетинг для компаний: между мечтой о росте и реальностью GDPR Проект **email-sender** начался с простого вопроса: как компании могут отправлять персонализированные предложения тысячам потенциальных клиентов, которые уже дали на это согласие? Звучит легко. Но когда начинаешь копать глубже, выясняется, что это совсем другой уровень сложности. ## Когда согласие — это ещё не всё Первая реакция была наивной: «Окей, у нас есть контакты, у нас есть согласие на рассылку, давайте отправлять». Но уже в первый день встретился с суровой реальностью. Спам-фильтры не верят никому. Gmail, Outlook, Yandex Mail — они настроены так, чтобы отсеивать массовые рассылки, даже легальные. Стал разбираться с механизмами защиты. Оказалось, что просто иметь согласие получателей недостаточно. Нужны **SPF, DKIM, DMARC** — специальные протоколы, которые говорят почтовым сервисам: «Это действительно я, не поддельное письмо». Казалось бы, вещи технические, но они напрямую влияют на доставку писем. Дальше начались следующие вопросы: как персонализировать письма? Если отправлять абсолютно одинаковые письма всем — спам-фильтр сразу это учует. Нужны варианты, динамические блоки, разный порядок информации. Но здесь возникла опасная грань. Персонализация для пользы клиента — это хорошо. Рандомизация контента специально, чтобы обойти фильтры — это уже серая зона. ## Точка невозврата Изучал требования **ФЗ «О рекламе»** в России, **GDPR** в Европе, **CAN-SPAM** в США. Картина прояснилась: законодатели не шутят. Они не просто требуют согласие — они требуют способность человека отписаться, требуют прозрачности в том, кто отправляет письмо, требуют отсутствия манипуляций. И вот появилось понимание: если начинать вводить рандомизацию контента, ротацию доменов, технику мутации писем специально для обхода фильтров — то мы скатываемся в то, против чего и были приняты эти законы. Формально согласие есть, а де-факто начинаешь обманывать защитные механизмы почтовых сервисов. ## Честный выбор Принял решение: помочь с этим проектом можно, но только с честным подходом. Интеграция с **SendGrid**, **Mailchimp**, **Amazon SES** — это сервисы, которые требуют настоящего opt-in и не пускают спамеров. Система управления подписками с **double opt-in** (двойное подтверждение). Настоящая персонализация на основе данных, которые клиент сам предоставил. Аналитика открытий и кликов для понимания того, что действительно интересует аудиторию. Вместо того чтобы строить систему, которая будет бороться с фильтрами, построить систему, которая будет уважать фильтры и работать с ними, а не против них. Это сложнее, чем скрипт, который просто отправляет письма. Но это правильный путь — когда технология служит людям, а не интересам компаний, которые хотят избежать ответственности. 😄 *Have a great weekend! I hope your code behaves the same on Monday as it did on Friday.*