163 lines
20 KiB
Markdown
163 lines
20 KiB
Markdown
# 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_<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`, затем при необходимости конкретные файлы из горизонтов.
|
||
- Файлы из этой папки не считать активными задачами и не начинать реализацию без явной просьбы пользователя.
|
||
- Если часть кода временно отключена или закомментирована, в файле будущей фичи подробно описывать:
|
||
- какие файлы и участки отключены;
|
||
- что осталось в коде как заготовка;
|
||
- какие документы нужно обновить при возврате;
|
||
- с какого сценария продолжать разработку.
|
||
|
||
## Коммуникация по новым задачам (обязательно)
|
||
- При получении нового задания сначала кратко пересказать задачу своими словами.
|
||
- До начала реализации задать недостающие уточняющие вопросы (если они есть).
|
||
- Если есть уместные идеи/улучшения — кратко предложить их; если полезных идей нет, ничего дополнительно не предлагать.
|
||
- Добавлять краткую оценку фичи (насколько это полезно/удачно по мнению исполнителя).
|
||
- После этого обязательно запросить подтверждение от пользователя, что задача понята верно, и только после подтверждения переходить к реализации.
|
||
- Если вопросов нет, явно написать в формате: «Я всё понял, начинаю делать?» и ждать подтверждения.
|
||
- Без подтверждения пользователя реализацию не начинать.
|