# AGENTS.md ## Назначение Слой PosadMesh поверх upstream MeshCore. **По умолчанию:** сохраняем поведение upstream. Изменяем код только для чётко ограниченных возможностей PosadMesh: - `*_repeater_mqtt` - MQTT-аплинк/брокер - веб-панель репитера - документация, релизы, автоматизация ## Принципы - Минимальные точечные изменения - Предпочитаем дополнять, а не менять код upstream - Избегаем посторонних рефакторингов - Сохраняем паритет с поведением upstream ## Ограничения ### Upstream - Не менять постороннюю логику MeshCore - Не менять семантику CLI без явной необходимости - Не вносить ломающие изменения в существующие таргеты ### Документация (обновлять в том же PR, когда это возможно) | Изменение | Файл | | --------------------- | ----------------------------- | | CLI | `posadmesh-docs/custom-cli.md` | | UI/поведение веб-панели | `posadmesh-docs/web-panel.md` | | Релизы | `release-notes.yml` | | Руководство по прошивке | `posadmesh-docs/releases.md` | ### Контроль веб-панели Если правите `examples/simple_repeater/MyMesh.cpp`, обновите также `posadmesh-docs/custom-cli.md`. ## Инструменты - Использовать `uv` + PlatformIO через `uv run` - Не рассчитывать на глобально установленный `pio` ### Политика сборок Сборки дорогие. Избегать без необходимости. НЕ собирать для: - только документация / HTML / CSS Предпочитать: - локальные сборки, запускаемые пользователем - рассуждения вместо выполнения Собирать только если: - изменение высокого риска - нужно проверить поведение прошивки ### Команды ```bash uv sync uv run pio run -e uv run pio device monitor --port --baud 115200 uv run --group docs zensical serve uv run --group docs zensical build ``` Не рассчитывайте, что `pio` установлен глобально. ## Частые команды Показать список таргетов сборки: ```bash bash posadmesh-build.sh list ``` Собрать один таргет: ```bash uv run pio run -e heltec_v4_repeater_mqtt uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt uv run pio run -e heltec_v4_repeater_mqtt_espnow uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt_bridge ``` Сборка с релизными метаданными: ```bash export FIRMWARE_VERSION=v1.15.0 export POSADMESH_VERSION=v2026.5.1 bash posadmesh-build.sh build-firmware heltec_v4_repeater_mqtt bash posadmesh-build.sh build-firmware T_Beam_S3_Supreme_SX1262_repeater_mqtt ``` Прошить таргет: ```bash uv run pio run -e heltec_v4_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX ``` ## Ключевые файлы - `posadmesh-build.sh` — обёртка сборки PosadMesh - `build.sh` — обёртка сборки upstream MeshCore, сохранена ради чистоты слияний - `platformio.ini` - `variants/posadmesh_mqtt/platformio.ini` - `examples/simple_repeater/MyMesh.cpp` - `src/helpers/mqtt/MQTTUplink.cpp` - `posadmesh-docs/*.md` - `RELEASE.md` - `release-notes.yml` ## Принадлежность workflow Репозиторий живёт на . Собственные workflow: - `.gitea/workflows/build-mqtt-firmwares.yml` — ручная сборка MQTT-прошивок на сервере Gitea Actions (`workflow_dispatch`): собирает группу или один таргет, умеет создавать релиз Gitea и загружать в него файлы. Публикация использует секрет репозитория `GITEA_TOKEN`. Кроме workflow прошивки собираются локально через `posadmesh-build.sh`, а теги и релизы создаются в веб-интерфейсе git.meshinfo.ru. Выгрузка собранных файлов в релиз — через `posadmesh-tools/publish-gitea-release.sh`. Workflow upstream MeshCore в `.github/workflows/` остаются под исходными именами файлов ради чистоты слияний. Не адаптируйте их под поведение PosadMesh; держите их близко к upstream. Они не используются для релизов PosadMesh. ## Требования к синхронизации документации Если вы меняете что-либо из перечисленного, обновляйте документацию в том же PR, когда это возможно: - Любые изменения в проекте: - дописать запись о них в раздел «Изменения в проекте» файла `README.md` - Команды веб-панели: - обновить `posadmesh-docs/custom-cli.md` - Пользовательское поведение, разделы, элементы управления или диагностика веб-панели: - обновить `posadmesh-docs/web-panel.md` - Добавления в CLI PosadMesh или изменения семантики: - обновить `posadmesh-docs/custom-cli.md` - Подготовка релиза/тега: - обновить `release-notes.yml` - Руководство по прошивке и файлам релиза: - обновить `posadmesh-docs/releases.md` ## Замечания по MQTT-репитерам Сборки `*_repeater_mqtt` могут включать локальную HTTPS-веб-панель на поддерживаемых таргетах ESP32. Эксплуатационные рекомендации уже отражены в документации: - использовать для первичной настройки и диагностики - после этого предпочитать `set web off` для максимального запаса heap ## Границы продукта Проект собирает и поставляет только MQTT-прошивки (`*_repeater_mqtt`, `*_repeater_mqtt_espnow`, `*_repeater_mqtt_bridge`). Связанные с этим правила: - текущая официальная версия MeshCore — `v1.15.0` - линия companion-прошивок удалена из проекта: окружения `*_companion_radio_*` и код `examples/companion_radio` остаются в upstream-оверлеях, PosadMesh их не собирает и не документирует - не придумывайте отдельные номера версий PosadMesh для треков, которых нет в `release-notes.yml` ## Процесс релиза Текущие форматы тегов: ```bash git tag repeater-bridge-espnow-v1.15.0 git tag repeater-mqtt-espnow-v2026.5.1 git tag repeater-mqtt-bridge-v2026.7.0 git tag repeater-mqtt-v2026.5.1 ``` Правила: - теги `repeater-bridge-espnow` используют версию upstream MeshCore напрямую - теги `repeater-mqtt-espnow` используют версию релиза PosadMesh в теге - теги `repeater-mqtt-bridge` используют версию релиза PosadMesh в теге - теги `repeater-mqtt` используют версию релиза PosadMesh в теге - переменная `FIRMWARE_VERSION` при локальной сборке задаёт базовую версию upstream для релизных сборок треков `repeater-mqtt`, `repeater-mqtt-espnow` и `repeater-mqtt-bridge` - переменная `POSADMESH_VERSION` при локальной сборке задаёт версию релиза PosadMesh - если версия релиза upstream MeshCore изменилась, обновите `FIRMWARE_VERSION` при сборке и в документации Типичный порядок выпуска: 1. Обновить `release-notes.yml` в ветке `develop`. 2. Смерджить релизный PR из `develop` в `main`. 3. Собрать нужные прошивки — локально или ручным workflow в Gitea Actions — с подходящими `FIRMWARE_VERSION` и `POSADMESH_VERSION`. 4. Создать нужный тег или теги релиза на целевом коммите в `main`. 5. Запушить теги в git.meshinfo.ru и создать релиз в его веб-интерфейсе. ## Синхронизация с upstream Когда просят подтянуть изменения из upstream MeshCore: - тянуть из `meshcore-dev/MeshCore:dev` - начинать с локальной ветки `develop` - создать временную интеграционную ветку от `develop` - влить upstream `dev` в эту временную интеграционную ветку - разрешать конфликты так, чтобы сохранить изменения, специфичные для PosadMesh - влить готовую интеграционную ветку обратно в `develop` Не вливайте upstream напрямую в `main`. ## Границы области работ НЕ делать (без явной просьбы): - переименовывать треки - менять форматы тегов - расширять CLI без обновления документации - менять семантику CLI upstream - вводить новые схемы версионирования ## Сообщения коммитов Используйте краткие общепринятые префиксы: - `feat:` новая функциональность - `fix:` исправления ошибок - `docs:` изменения документации - `chore:` обслуживание, инструменты, нефункциональное - `refactor:` изменения кода без изменения поведения Держите сообщения короткими и по делу. ## Правило принятия решений Если изменение не является явно специфичным для PosadMesh, не меняйте код. При сомнениях предпочитайте не менять ничего или запросить уточнение.