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_rewrite_on, /voice_rewrite_off. Если она включена, сервис перед TTS вызывает дешёвую текстовую модель OpenAI и делает голосовую версию без длинных хэшей, путей, команд и технического шума, сохраняя смысл и порядок исходного ответа.
• Режим личных ответов настраивается персонально командами /single_message_on, /single_message_off: либо одно редактируемое сообщение по этапам, либо отдельные сообщения как раньше.
• Команда /settings должна сразу показывать текущее состояние всех персональных настроек пользователя и список команд для их изменения.
• Если озвучивание включено, после полного текстового финального ответа сервис дополнительно отправляет voice-файл с синтезированной речью через OpenAI TTS даже для текстовых запросов. Voice отправляется в исходный чат, а также в известный личный чат пользователя и в общий чат @shine_writing, если они отличаются и доступны. Промежуточные статусы не озвучивать.
• Команда /status должна показывать состояние очереди и персональные настройки: voice-ответы, адаптацию текста перед озвучкой и режим одного сообщения в личке.

Правила голосовой версии ответа

• Текстовый финальный ответ должен оставаться полноценным: в нём можно указывать команды, пути, хэши коммитов, номера версий, результаты проверок и другие технические детали.
• Голосовую версию финального ответа нужно делать короче и проще для восприятия на слух. Основной механизм — персонально включаемая адаптация текста через дополнительный OpenAI-вызов перед TTS.
• В голосовой версии не зачитывать длинные хэши коммитов, токены, file_id, длинные команды, полные пути и другие строки, которые человек всё равно не сможет надёжно запомнить на слух.
• Для commit/push в голосовой версии достаточно сказать краткий итог: что коммит сделан, что именно изменено, проверки прошли без ошибок, push выполнен, рабочее дерево чистое.
• Если пользователю нужны точные команды, хэши или подробности, они должны оставаться в текстовом ответе.

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

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

Центр задач и предложений

• Сервис хранит простые задачи и предложения в data/task_center/items.json.
• Айдар может смотреть список через /tasks или естественные фразы вроде «покажи мои задачи», «покажи задачи Миланы».
• Айдар может ставить задачи игрокам фразой вида «поставь задачу Милане: ...».
• Игроки могут отправлять предложения Айдару фразой вида предложение: ..., идея: ... или заявка: ....
• Статусы меняются фразами с ID: одобрить TC-0001, отклонить TC-0001, доработать TC-0001, закрыть TC-0001.
• После финального ответа в личном чате сервис добавляет короткое напоминание, если у пользователя есть активные задачи или предложения.

Локальный запуск и 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 (/restart_service) доступна только Айдару и выполняет отложенный рестарт после текущей задачи, до взятия следующей. Аварийный жёсткий рестарт доступен только Айдару командами /restart_hard, /restart_now, /restart_force.

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

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