62 lines
9.3 KiB
Markdown
62 lines
9.3 KiB
Markdown
# 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 — учти это и продолжи с учётом текущего состояния проекта.
|