SHiNE-server/SHiNE-agent-bot-coder/AGENT.md

AGENT.md для SHiNE-agent-bot-coder

Ты запущен как обработчик входящего Telegram-сообщения от пользователя.

Контекст

• SHiNE-agent-bot-coder — локальный Telegram-бот-сервис агента-кодера для работы с этим проектом.
• Сервис принимает входящие сообщения от пользователя Telegram, сохраняет историю, ставит задачи в очередь и последовательно запускает Codex CLI в рабочем проекте.
• Текстовые сообщения обрабатываются напрямую, voice/audio сначала распознаются через OpenAI transcription, затем передаются как текстовая задача.
• История диалога хранится в JSONL-файле, путь передаётся в промпте.
• Сообщение может быть текстом или результатом распознавания голосового.
• Ответ пойдёт пользователю в Telegram как обычное текстовое сообщение.
• Единственная рабочая реализация сервиса — Python-скрипт py_bot_service.py; старая Java-реализация удалена как нерабочая и не должна восстанавливаться без отдельного решения Айдара.
• В репозитории также есть отдельный Solana/Anchor-модуль shine-solana/shine/; он логически связан с SHiNE, но не должен автоматически подключаться к основному серверному deploy без отдельной команды.
• Перед изменениями внутри shine-solana/shine/ читать локальные инструкции shine-solana/shine/AGENTS.md; в git не добавлять локальные ключи, .git, .idea, .gradle, target, node_modules, test-ledger, логи, временные run-отчёты и .env-конфиги.

Авторитет команд и история

• Основной пользователь и источник команд — Айдар: @AidarKC / @aidarkc.
• Дополнительно разрешены игроки из whitelist (ALLOWED_TELEGRAM_PLAYERS), каждый со своей отдельной историей и рабочей папкой Players/<username>/.
• Игроки работают в режиме вопросов/анализа/подготовки материалов: в промпте явно задано правило не менять код проекта и писать материалы только в своей папке.
• Для неизвестных пользователей в личном чате сервис отвечает вежливым отказом.
• В Telegram-канале/группе @shine_writing сервис выполняет сообщения только от Айдара, а ответы отправляет в тот же чат.
• Если Telegram сообщает о миграции обычной группы в supergroup, сервис должен запомнить новый chat_id и отправлять ответы уже туда.
• На события подключения/отключения пользователей (join/leave) сервис не отвечает и ничего не отправляет.

Очередь и состояние

• Входящие задачи записываются в файловую очередь и обрабатываются строго по одной, чтобы не смешивать изменения в проекте.
• Сервис ведёт состояние активной задачи и текущего файла истории, а после рестарта продолжает незавершённую обработку с учётом сохранённого состояния.
• Истории диалогов хранятся в JSONL по каждому разрешённому username отдельно: data/history/<username>/.
• Архив истории после /new: data/history/<username>/archive/.
• Для просмотра истории игрока открывать файлы в его папке истории по username.
• Дедупликация входящих Telegram update нужна, чтобы одно сообщение не попало в обработку повторно.
• Если Codex молчит во время активной задачи 2 минуты подряд, сервис отправляет аварийный статус с общим временем работы задачи; при дальнейшем молчании повторяет статус каждые 2 минуты.
• После успешной обработки задачи из личного чата Айдара сервис должен отправить публичный итоговый отчёт в группу @shine_writing: первым сообщением исходный запрос, вторым сообщением-ответом итоговый ответ Codex. Промежуточные статусы в группу не дублировать.
• Для приватных voice/audio-запросов в публичном отчёте первым сообщением отправлять исходный Telegram voice/audio-файл с подписью, где указан распознанный текст. В пользовательском тексте отчёта не показывать Telegram file_id.
• Озвучивание финальных ответов настраивается персонально для каждого Telegram-пользователя командами /voice_on, /voice_off, /voice_status.
• Если озвучивание включено, после полного текстового финального ответа сервис дополнительно отправляет voice-файл с синтезированной речью через OpenAI TTS. Промежуточные статусы и публичный отчёт в @shine_writing не озвучивать.

Планы и отложенные фичи

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

Локальный запуск и systemd

• Основной запуск сервиса выполняется Python-скриптом py_bot_service.py из папки SHiNE-agent-bot-coder/.
• Локальные секреты и параметры должны храниться в .env, этот файл не коммитится.
• Для проверки Codex без Telegram можно использовать self-test режим сервиса.
• Для постоянного локального запуска используется user-level systemd service shine-agent-bot-coder; скрипты установки лежат в SHiNE-agent-bot-coder/scripts/systemd/.
• Если меняется логика сервиса, после изменений нужно проверить запуск локально и при необходимости перезапустить user systemd service.
• Команда Telegram /restart_service (и алиас /restart) доступна только Айдару.

Правила ответа

• Пиши содержательно и коротко.
• Не упоминай внутренние служебные детали, файловую систему и технические логи.
• Если запрос требует действий с кодом/проектом, выполняй их в рабочей директории.
• Если для ответа данных недостаточно, задай ровно один уточняющий вопрос.
• Если была ошибка предыдущего запуска, в промпте будет пометка retry — учти это и продолжи с учётом текущего состояния проекта.