# AGENTS.md ## Назначение Слой PosadMesh поверх upstream MeshCore. **По умолчанию:** сохраняем поведение upstream. Изменяем код только для чётко ограниченных возможностей PosadMesh: - `*_repeater_observer` - `*_companion_radio_wifi` - 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_observer uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_observer uv run pio run -e heltec_v4_companion_radio_wifi uv run pio run -e T_Beam_S3_Supreme_SX1262_companion_radio_wifi ``` Сборка с релизными метаданными: ```bash export FIRMWARE_VERSION=v1.15.0 export POSADMESH_VERSION=v2026.5.1 bash posadmesh-build.sh build-firmware heltec_v4_repeater_observer bash posadmesh-build.sh build-firmware T_Beam_S3_Supreme_SX1262_repeater_observer ``` Прошить таргет: ```bash uv run pio run -e heltec_v4_repeater_observer -t upload --upload-port /dev/tty.usbmodemXXXX uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_observer -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 GitHub Actions (`posadmesh-*.yml`) удалены при переезде: релизы собираются локально через `posadmesh-build.sh`, теги и релизы создаются вручную в веб-интерфейсе git.meshinfo.ru. Workflow upstream MeshCore остаются под исходными именами файлов ради чистоты слияний. Не адаптируйте их под поведение PosadMesh; держите их близко к upstream. Они не используются для релизов PosadMesh. ## Требования к синхронизации документации Если вы меняете что-либо из перечисленного, обновляйте документацию в том же PR, когда это возможно: - Команды веб-панели: - обновить `posadmesh-docs/custom-cli.md` - Пользовательское поведение, разделы, элементы управления или диагностика веб-панели: - обновить `posadmesh-docs/web-panel.md` - Добавления в CLI PosadMesh или изменения семантики: - обновить `posadmesh-docs/custom-cli.md` - Подготовка релиза/тега: - обновить `release-notes.yml` - Руководство по прошивке и файлам релиза: - обновить `posadmesh-docs/releases.md` ## Замечания по обсерверам Сборки `*_repeater_observer` могут включать локальную HTTPS-веб-панель на поддерживаемых таргетах ESP32. Эксплуатационные рекомендации уже отражены в документации: - использовать для первичной настройки и диагностики - после этого предпочитать `set web off` для максимального запаса heap ## Замечания по companion WiFi Таргеты `*_companion_radio_wifi` поддерживают сохраняемые команды восстановления Wi-Fi через последовательный `CLI Rescue`. Не документируйте команды восстановления companion в документации репитера. Не предполагайте, что поведение веб-панели применимо. Правило версий companion: - теги companion используют только официальную версию релиза upstream MeshCore - текущая официальная версия MeshCore — `v1.15.0` - companion-релизы выпускаются только когда `meshcore-dev/MeshCore` сделал официальный релиз - не придумывайте отдельные номера версий PosadMesh для companion ## Процесс релиза Текущие форматы тегов: ```bash git tag companion-wifi-v1.15.0 git tag repeater-bridge-espnow-v1.15.0 git tag observer-posadmesh-bridge-espnow-v2026.5.1 git tag observer-posadmesh-bridge-mqtt-v2026.7.0 git tag observer-posadmesh-v2026.5.1 ``` Правила: - теги `companion-wifi` используют версию upstream MeshCore напрямую - теги `repeater-bridge-espnow` используют версию upstream MeshCore напрямую - теги `observer-posadmesh-bridge-espnow` используют версию релиза PosadMesh в теге - теги `observer-posadmesh-bridge-mqtt` используют версию релиза PosadMesh в теге - теги `observer-posadmesh` используют версию релиза PosadMesh в теге - переменная `FIRMWARE_VERSION` при локальной сборке задаёт базовую версию upstream для релизных сборок треков `observer-posadmesh`, `observer-posadmesh-bridge-espnow` и `observer-posadmesh-bridge-mqtt` - переменная `POSADMESH_VERSION` при локальной сборке задаёт версию релиза PosadMesh - если версия релиза upstream MeshCore изменилась, обновите `FIRMWARE_VERSION` при сборке и в документации Типичный порядок выпуска: 1. Обновить `release-notes.yml` в ветке `develop`. 2. Смерджить релизный PR из `develop` в `main`. 3. Собрать нужные прошивки локально с подходящими `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, не меняйте код. При сомнениях предпочитайте не менять ничего или запросить уточнение.