SHiNE-server/AGENTS.md

AGENTS

Язык проекта

• По умолчанию использовать русский язык во всех пользовательских текстах и технических пояснениях.
• Пояснения к коммитам, PR и merge-запросам писать на русском языке.
• Комментарии в коде, встроенные справки, документацию и инструкции писать по возможности на русском языке.

Примечание

• Если внешний инструмент/интеграция требует английский формат, допускается английский, но рядом желательно дать краткое пояснение на русском.

Структура проекта (кратко)

• Серверный код SHiNE находится в папке SHiNE-server/.
• Код клиентского UI SHiNE находится в папке shine-UI/.
• Веб-панель администратора сервера (управление Solana PDA сервера) находится в shine-UI/:
• точка входа shine-UI/server-ui.html;
• остальные файлы серверного UI — в shine-UI/server-ui/.
• Локальный Telegram-бот агента-кодера живёт рядом с репозиторием продукта, обычно в ../SHiNE-agent-bot-coder/, и не входит в публичный код основного приложения.
• Solana/Anchor-модуль находится в папке shine-solana/shine/ и ведётся отдельно от основного server/UI деплоя.

Сервис агента-кодера

• Локальный Telegram-бот-сервис агента-кодера находится вне этого git-репозитория, обычно в ../SHiNE-agent-bot-coder/.
• Сервис принимает сообщения из Telegram, ведёт историю диалога, ставит задачи в очередь и вызывает Codex CLI для обработки запросов по проекту.
• Рабочая папка Codex для сервиса должна указывать на этот продуктовый репозиторий: CODEX_WORKDIR=/home/ai/work/SHiNE/SHiNE-server-sha256/SHiNE-product.
• Автоматически читаемые инструкции для Codex внутри сервиса держать в ../SHiNE-agent-bot-coder/AGENTS.md.
• Подробные служебные правила Telegram-обработчика, его очередь, история, systemd-запуск и особенности ответов описывать в ../SHiNE-agent-bot-coder/AGENT.md.
• Если в сообщениях пользователя встречается «агент MD» или похожая формулировка про файл инструкций Codex, считать, что имеется в виду автоматически читаемый AGENTS.md.

ESP32 UI homeserver

• Для UI-скетча устройства ESP32-S3-Touch-AMOLED-2.16 документ-спецификация и Arduino-скетч должны всегда оставаться синхронными.
• Актуальный документ по экранной логике, состояниям, кнопкам, полям, статусам и ограничениям UI считать источником истины для скетча.
• При изменении документа обязательно в том же наборе изменений приводить в соответствие скетч.
• При изменении скетча обязательно в том же наборе изменений обновлять документ, если поменялись экраны, тексты, переходы, статусы, кнопки, поля или поведение.
• Для нового ESP32 UI-прототипа homeserver использовать русский язык как основной и отдельно следить, чтобы текст реально отображался на устройстве, а не только логически присутствовал в коде.

Solana-модуль

• В проекте есть отдельный Solana/Anchor-модуль в папке shine-solana/shine/.
• Модуль логически связан с SHiNE, но не должен автоматически подключаться к сборке или деплою основного сервера без отдельного решения.
• В Solana-модуле действуют локальные инструкции shine-solana/shine/AGENTS.md; при изменениях внутри модуля сначала читать их.
• В git добавлять исходники, lock-файлы, настройки проекта и документацию Solana-модуля, но не добавлять локальные ключи, .git, .idea, .gradle, target, node_modules, test-ledger, логи, временные run-отчёты и .env-конфиги.
• Для Solana deploy/push использовать правила из локального shine-solana/shine/AGENTS.md; не смешивать deploy Solana-модуля со скриптами основного server/UI deploy из deploy/scripts/.
• Для регистрации пользователей в Solana (программа shine_users) единая актуальная инструкция по деплою/инициализации, адресам программ, и куда их прописывать в UI/сервере находится в:
  • docs/Инициализация_Solana_регистрации/README.md
• Этот файл считать основной справкой (single source of truth) по деплою и первичной инициализации Solana-регистрации в текущем проекте.
• Актуальная архитектурная справка по устройству Solana-программ, PDA-счетам, ролям DAO и движению средств находится в:
  • docs/Solana_Architecture/README.md
• Документ формата пользовательской PDA-записи shine_users находится в:
  • shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md
• Актуальная документация по серверному модулю синхронизации Solana users находится в:
  • docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md
• При любом изменении логики серверной синхронизации shine_users, её таблиц PostgreSQL, checkpoint-механизма, startup/lifecycle или deploy-настроек обязательно обновлять:
  • docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md
  • deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md

Документация блокчейна

• Актуальная документация по форматам блокчейна находится в docs/Blockchain/README.md.
• Это точка входа (оглавление), рядом расположены детальные файлы по форматам, типам каналов и командным сообщениям.
• При любом изменении кода, связанного с блокчейном (формат блока, типы каналов, правила чтения/записи, команды), обязательно обновлять соответствующие документы в docs/Blockchain/.
• Дополнительно обязательно вести docs/Blockchain/CHANGELOG.md: дописывать изменения построчно с указанием даты/времени и хэша коммита, после которого внесено изменение.
• Перед любым изменением формата блокчейна обязательно заранее предупреждать пользователя, что формат будет изменён.
• Изменять формат блокчейна можно только после явного подтверждения пользователя (без подтверждения формат не менять).
• Добавление любых данных в блокчейн выполнять только через операцию AddBlock.
• Перед каждым AddBlock обязательно проверять/актуализировать текущее состояние вершины блокчейна (last global number/hash) и использовать его при формировании блока.

Документация личных сообщений (DM)

• Актуальная документация по логике личных сообщений находится в docs/Personal_Messages/Протокол_DM_v1.md.
• Точный байтовый формат DM находится в docs/Personal_Messages/Формат_DM_v1.md.
• При любом изменении кода, связанного с личными сообщениями (формат подписанного DM-блока, типы DM-сообщений, правила доставки/ACK/read-receipt, роутинг по сессиям, UI-логика чатов), обязательно обновлять оба документа:
  • docs/Personal_Messages/Протокол_DM_v1.md
  • docs/Personal_Messages/Формат_DM_v1.md
• Логика личных сообщений в коде должна всегда соответствовать этим документам.
• Документ по личным сообщениям обязан поддерживаться в актуальном состоянии.

Документация API сервера

• Актуальная документация по публичному JSON/WebSocket API сервера находится в docs/API/.
• При любом изменении серверного API/эндпоинтов/операций op обязательно обновлять соответствующие документы в docs/API/.
• Перед изменением самого серверного API обязательно явно предупредить пользователя, какие операции, поля запросов/ответов или коды ошибок будут изменены, и запросить отдельное подтверждение.
• Без явного подтверждения пользователя формат серверного API не менять; допускается только приведение документации в соответствие уже существующему коду.
• Если добавляется новая операция op, нужно обновить общий список операций в docs/API/09_Operations_Index.md или создать его, если файла ещё нет.

Документация Figma

• Актуальная документация по переносу экранов SHiNE в Figma и обратному переносу из Figma в код находится в docs/Figma/.
• Точка входа: docs/Figma/README.md.
• Подробный рабочий регламент: docs/Figma/TRANSFER_UI_SCREENS.md.
• Для экранов регистрации, входа и других чувствительных UI-flow по умолчанию переносить экраны в Figma по одному, а не пачкой, если пользователь отдельно не подтвердил иной способ.

Версионирование

• Все правила по коммитам, merge в main, git push и обновлению VERSION.properties находятся в COMMIT_AND_VERSION_RULES.md.
• Этот файл считать единым источником истины по правилам версионирования и коммитов для данного репозитория.

Deploy

• Все документы, инструкции, backup-правила и скрипты деплоя хранить в папке deploy/.
• Подробные правила для агента по деплою находятся в deploy/AGENTS.md; перед любым deploy читать этот файл.
• Production-серверы SHiNE: shineup.me и server2.shineup.me.
• Тестовые/devnet серверы SHiNE: t1.shineup.me, t2.shineup.me, t3.shineup.me, t4.shineup.me.
• В deploy-документах и скриптах использовать домены, а не IP.
• По возможности все справки, комментарии и примечания в конфигах/документах писать на русском языке.
• Любые изменения и любой деплой на production (shineup.me и server2.shineup.me) выполнять только после отдельного явного подтверждения пользователя.
• Перед production deploy обязательно проверить/обновить бэкап в deploy/backup/archive/.
• Если пользователь пишет просто задеплой без уточнения production/test, уточнить целевой контур; не выбирать production автоматически.
• Deploy выполнять shell-скриптами из deploy/scripts/; Gradle deploy-задачи не использовать.
• Для локального запуска использовать ./gradlew startLocal (или startLocalWithBuild).
• Сначала предлагать локальную проверку, а деплой на сервер выполнять по запросу пользователя.
• Для временной бесплатной загрузки аватаров в Arweave секретный JWK нельзя хранить в git и нельзя прописывать в репозиторный application.properties.
• Для продовой настройки тестового Arweave-кошелька JWK-файл нужно хранить только на сервере, например: /home/player/SHiNE/secrets/test-free-avatar-wallet.json.
• Для этой временной фичи на проде должны быть заданы параметры test.freeAvatar.walletJwkPath и test.freeAvatar.walletAddress через серверный override-конфиг/секреты на хосте.
• После изменения продовых значений test.freeAvatar.* нужно заново выполнить серверный деплой или перезапуск сервера, чтобы настройки были перечитаны приложением.
• При таких изменениях в git допускается коммитить только документацию и код чтения настроек, но не сам JWK, не содержимое секрета и не реальные приватные ключи.

Логи звонков (установка соединения)

• Специальный поток диагностики установки звонков идёт через CallDeliveryReport (клиент → сервер).
• На проде специальный файл для звонков:
• /home/player/SHiNE/shine-server/logs/call-delivery-events.log
• Общий серверный лог (и ротации) на проде:
• /home/player/SHiNE/shine-server/logs/app.log
• /home/player/SHiNE/shine-server/logs/app.YYYY-MM-DD.log
• Для анализа причин недозвона в первую очередь фильтровать записи по ключам:
• CallDeliveryReport
• call_connected
• outgoing_failed
• incoming_failed
• call_busy
• call_declined
• unknown_error
• В этих записях искать поля reason, failureStage, pcConnectionState, pcIceConnectionState, routeLabel, configuredTurnHosts*, reachableTurnHosts*.

Будущие фичи / TODO

• Папка для задач, сознательно отложенных на будущее: TODO/.
• Точка входа по планам: TODO/README.md.
• Внутри планы разделены по горизонтам: near/, medium/, far/ и тематическим подпапкам.
• Если пользователь спрашивает, какие есть планы или что можно продолжить, сначала читать TODO/README.md, затем при необходимости конкретные файлы из подпапок.
• Файлы из этой папки не считать активными задачами и не начинать реализацию без явной просьбы пользователя.
• Старую папку docs/Future_Features/ считать выведенной из использования и больше не использовать для новых записей.
• Если часть кода временно отключена или закомментирована, либо удалена как временная заглушка, в TODO-файле подробно описывать:
  • какие файлы и участки отключены;
  • что осталось в коде как заготовка;
  • какие документы нужно обновить при возврате;
  • с какого сценария продолжать разработку;
  • из какого коммита брать последнюю полную реализацию.

Коммуникация по новым задачам (обязательно)

• При получении нового задания сначала кратко пересказать задачу своими словами.
• До начала реализации задать недостающие уточняющие вопросы (если они есть).
• Если есть уместные идеи/улучшения — кратко предложить их; если полезных идей нет, ничего дополнительно не предлагать.
• Добавлять краткую оценку фичи (насколько это полезно/удачно по мнению исполнителя).
• После этого обязательно запросить подтверждение от пользователя, что задача понята верно, и только после подтверждения переходить к реализации.
• Если вопросов нет, явно написать в формате: «Я всё понял, начинаю делать?» и ждать подтверждения.
• Без подтверждения пользователя реализацию не начинать.