MeshCore-Posadmesh/AGENTS.md

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

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

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

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

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

Команды

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_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

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

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

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

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

Репозиторий живёт на https://git.meshinfo.ru/shade/MeshCore-Posadmesh. Собственные 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

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

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

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, не меняйте код. При сомнениях предпочитайте не менять ничего или запросить уточнение.