Aidar/SHiNE-server
SHA256
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ba348dafb3
SHiNE-server/AGENTS.md

20 KiB
Raw Blame History

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-бот-сервис агента-кодера в папке SHiNE-agent-bot-coder/.
  • Сервис принимает сообщения из Telegram, ведёт историю диалога, ставит задачи в очередь и вызывает Codex CLI для обработки запросов по проекту.
  • Автоматически читаемые инструкции для 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-модуля с deployServer/deployUI основного проекта.
  • Для регистрации пользователей в Solana (программа shine_users) единая актуальная инструкция по деплою/инициализации, адресам программ, и куда их прописывать в UI/сервере находится в:
    • Dev_Docs/Инициализация_Solana_регистрации/README.md
  • Этот файл считать основной справкой (single source of truth) по деплою и первичной инициализации Solana-регистрации в текущем проекте.
  • Актуальная архитектурная справка по устройству Solana-программ, PDA-счетам, ролям DAO и движению средств находится в:
    • Dev_Docs/Solana_Architecture/README.md
  • Документ формата пользовательской PDA-записи shine_users находится в:
    • shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md

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

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

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

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

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

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

Известная проблема (временная пометка)

  • Мнения по связям пользователя (known_person, shine_confirmed, shine_seen) в UI могут отображаться нестабильно.
  • Требуется отдельная доработка и финальная проверка end-to-end: запись мнения в блокчейн → обновление connections_state → ответ GetUserConnectionsGraph → отображение в UI.
  • До фикса считать эту часть функционала незавершённой и обязательно перепроверять вручную после каждого деплоя.

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

  • Единый файл версий проекта: VERSION.properties (в корне репозитория).
  • Перед каждым новым коммитом обязательно увеличивать версии в VERSION.properties:
  • client.version — версия клиентского UI.
  • server.version — версия серверной части.
  • Базовое правило инкремента: +1 по последнему числовому сегменту (patch), если не оговорено иное.
  • Обычные коммиты делать стандартным git commit; переменная $GITEA_TOKEN для коммитов не нужна и не используется.

Deploy

  • Все документы и заметки по деплою хранить в папке Dev_Docs/deploy/.
  • Production-хост SHiNE: player@shineup.me (185.229.109.118).
  • Основной test-хост SHiNE: player@193.8.215.70 (test2.shineup.me).
  • Резервный test-хост SHiNE: player@93.170.12.154 (test.shineup.me).
  • Базовый путь на сервере для SHiNE: /home/player (проекты SHiNE размещать в /home/player/SHiNE/...).
  • По возможности все справки, комментарии и примечания в конфигах/документах писать на русском языке.
  • Для операций git push при необходимости использовать токен из переменной окружения $GITEA_TOKEN.
  • Любые изменения и любой деплой на production shineup.me выполнять только после отдельного явного подтверждения пользователя.
  • Если пользователь пишет просто задеплой без уточнения production/test, по умолчанию деплоить на test2.shineup.me.
  • Default server deploy: ./gradlew deployServer или ./gradlew deployServerTest2.
  • Default UI deploy: ./gradlew deployUI или ./gradlew deployUITest2.
  • Production server deploy: ./gradlew deployServerProduction.
  • Production UI deploy: ./gradlew deployUIProduction.
  • Резервный test deploy на test.shineup.me: ./gradlew deployServerTest и ./gradlew deployUITest, но пока их не использовать без отдельной причины.
  • Для локального запуска использовать ./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*.

Недопроверенные фичи (обязательно)

  • Папка для учёта недопроверенных фич: Dev_Docs/Pending_Features/.
  • По каждой новой доработке, которая требует ручной проверки, добавлять отдельный markdown-файл в Dev_Docs/Pending_Features/.
  • Рекомендуемый формат имени файла: YYYY-MM-DD_HHMM_<short-feature-name>.md.
  • Имена новых файлов и краткие описания фич по возможности писать на русском языке.
  • Внутри файла обязательно указывать:
    • краткое описание фичи;
    • что именно проверять;
    • ожидаемый результат;
    • статус (например: pending, in_progress, done).
  • После подтверждения, что фича проверена и работает корректно, соответствующий файл удалять.
  • В Dev_Docs/Pending_Features/README.md вести краткий регламент и поддерживать актуальность.

Будущие фичи

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

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

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