# 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` или создать его, если файла ещё нет. ## Документация Figma - Актуальная документация по переносу экранов SHiNE в Figma и обратному переносу из Figma в код находится в `Dev_Docs/Figma/`. - Точка входа: `Dev_Docs/Figma/README.md`. - Подробный рабочий регламент: `Dev_Docs/Figma/TRANSFER_UI_SCREENS.md`. - Для экранов регистрации, входа и других чувствительных UI-flow по умолчанию переносить экраны в Figma по одному, а не пачкой, если пользователь отдельно не подтвердил иной способ. ## Известная проблема (временная пометка) - Мнения по связям пользователя (`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_.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`, затем при необходимости конкретные файлы из горизонтов. - Файлы из этой папки не считать активными задачами и не начинать реализацию без явной просьбы пользователя. - Если часть кода временно отключена или закомментирована, в файле будущей фичи подробно описывать: - какие файлы и участки отключены; - что осталось в коде как заготовка; - какие документы нужно обновить при возврате; - с какого сценария продолжать разработку. ## Коммуникация по новым задачам (обязательно) - При получении нового задания сначала кратко пересказать задачу своими словами. - До начала реализации задать недостающие уточняющие вопросы (если они есть). - Если есть уместные идеи/улучшения — кратко предложить их; если полезных идей нет, ничего дополнительно не предлагать. - Добавлять краткую оценку фичи (насколько это полезно/удачно по мнению исполнителя). - После этого обязательно запросить подтверждение от пользователя, что задача понята верно, и только после подтверждения переходить к реализации. - Если вопросов нет, явно написать в формате: «Я всё понял, начинаю делать?» и ждать подтверждения. - Без подтверждения пользователя реализацию не начинать.