Документировать API и сервис агента-кодера

SHiNE-agent-bot-coder/README.md

@@ -0,0 +1,44 @@
+# SHiNE-agent-bot-coder
+
+Локальный Telegram-бот-сервис для пользователя `ai`:
+- принимает сообщения от `@AidarKC`;
+- ведёт историю диалога в `JSONL`;
+- ставит задачи в файловую очередь;
+- обрабатывает задачи строго последовательно;
+- поддерживает текстовые и голосовые сообщения (voice/audio через OpenAI transcription);
+- вызывает Codex CLI и отправляет ответ в Telegram;
+- при рестарте восстанавливает незавершённые задачи.
+
+## Структура
+- `.env` — локальные секреты и параметры запуска (не коммитится);
+- `data/queue.jsonl` — очередь задач;
+- `data/state.json` — текущее состояние (active job + текущий history-файл);
+- `data/py_queue.jsonl` — очередь Python-сервиса;
+- `data/py_state.json` — текущее состояние Python-сервиса;
+- `data/py_processed_updates.log` — дедуп входящих update;
+- `data/history/*.jsonl` — активные истории;
+- `data/history/archive/*.jsonl` — архив историй после `/new`.
+
+## Локальный запуск
+1. Скопировать пример:
+   - `cp .env.example .env`
+2. Заполнить секреты в `.env`.
+3. Запуск:
+   - `python3 SHiNE-agent-bot-coder/py_bot_service.py`
+
+## Быстрый self-test Codex (без Telegram)
+```bash
+python3 SHiNE-agent-bot-coder/py_bot_service.py --selftest-codex "Ответь одной строкой: Codex работает"
+```
+
+## Запуск как systemd-сервис
+Файлы для установки:
+- `scripts/systemd/shine-agent-bot-coder.service`
+- `scripts/systemd/install-local-systemd.sh`
+
+Установка:
+- `bash SHiNE-agent-bot-coder/scripts/systemd/install-local-systemd.sh`
+
+Проверка:
+- `systemctl --user status shine-agent-bot-coder --no-pager`
+- `journalctl --user -u shine-agent-bot-coder -f`