MeshCore-Posadmesh/AGENTS.md

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

Предпочитать:

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

Собирать только если:

• изменение высокого риска
• нужно проверить поведение прошивки

Команды

uv sync
uv run pio run -e <env>
uv run pio device monitor --port <port> --baud 115200
uv run --group docs zensical serve
uv run --group docs zensical build

Не рассчитывайте, что pio установлен глобально.

Частые команды

Показать список таргетов сборки:

bash posadmesh-build.sh list

Собрать один таргет:

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

Сборка с релизными метаданными:

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

Прошить таргет:

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

Репозиторий живёт на https://git.meshinfo.ru/shade/MeshCore-Posadmesh.

Собственные 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.18.0 (база PosadMesh после слияния upstream; предыдущая база — v1.17.1)
• линия companion-прошивок удалена из проекта: окружения *_companion_radio_* и код examples/companion_radio остаются в upstream-оверлеях, PosadMesh их не собирает и не документирует
• не придумывайте отдельные номера версий PosadMesh для треков, которых нет в release-notes.yml

Процесс релиза

Текущие форматы тегов:

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 в main.
2. Собрать нужные прошивки — локально или ручным workflow в Gitea Actions — с подходящими FIRMWARE_VERSION и POSADMESH_VERSION.
3. Создать нужный тег или теги релиза на целевом коммите в main.
4. Запушить теги в git.meshinfo.ru и создать релиз в его веб-интерфейсе.

Синхронизация с upstream

Когда просят подтянуть изменения из upstream MeshCore:

• брать релизный тег upstream нужной роли (например repeater-v1.18.0), а не ветку: тег содержит ещё и релизные коммиты, которых в dev нет (на момент 1.18.0 — 7 штук)
• вся работа ведётся в main (ветка develop в этом репозитории — устаревшая, от эпохи EastMesh, ей не пользуемся)
• создать временную интеграционную ветку от main, например integrate/upstream-1.18.0
• поставить страховочный тег pre-<версия> на текущий main и сделать git bundle перед слиянием
• влить тег upstream в интеграционную ветку, разрешать конфликты так, чтобы сохранить изменения, специфичные для PosadMesh
• проверить сборкой несколько ключевых целей, затем влить интеграционную ветку в main

Вливать upstream напрямую в main можно только через интеграционную ветку с проверкой сборкой.

Границы области работ

НЕ делать (без явной просьбы):

• переименовывать треки
• менять форматы тегов
• расширять CLI без обновления документации
• менять семантику CLI upstream
• вводить новые схемы версионирования

Сообщения коммитов

Используйте краткие общепринятые префиксы:

• feat: новая функциональность
• fix: исправления ошибок
• docs: изменения документации
• chore: обслуживание, инструменты, нефункциональное
• refactor: изменения кода без изменения поведения

Держите сообщения короткими и по делу.

Правило принятия решений

Если изменение не является явно специфичным для PosadMesh, не меняйте код. При сомнениях предпочитайте не менять ничего или запросить уточнение.