feat: atxpi — server power & console manager (core, CLI, deploy)

- core/hardware: драйверы real (atxctl/pyserial) + mock, ATXPI_DRIVER - core/power, console, mock: операции питания и RS232-консоли - cli/atxpi: status/on/off/reset/cycle/console (stdlib, без deps) - install.sh: one-shot curl|bash, идемпотентный, хост-агностичный - deploy: systemd-юнит, шаблон env, update.sh - README, AGENTS.md: документация и проектные решения - AGENTS.md и доки очищены от внутренних хостов/адресов (публичный репо)
2026-09-08 21:54:11 +05:00
parent 135b091567
commit 12e6a453de
14 changed files with 657 additions and 0 deletions
@@ -0,0 +1,69 @@
+# AGENTS.md — atxpi (diy/arm)
+
+> Aгент-инструкции для работы с проектом. Загружаются автоматически, когда Hermes работает внутри репозитория.
+
+## Что это
+
+**atxpi** — управляющая плоскость для сервера на базе Raspberry Pi:
+**питание** (ATX) + **RS232-консоль** + статус. По сути компактный «бедняцкий IPMI».
+Репо — на внутреннем git-хостинге (ветка `main`). Адрес/хост в публичном репо не указываем.
+
+## Принятые решения (утверждено)
+
+| # | Решение |
+|---|---|
+| 1 | **Имя пакета/системы — `atxpi`** |
+| 2 | Интерфейсы: **браузерный web-UI** + **CLI-инструменты** + **MCP-сервер для агентов** |
+| 3 | Всё **лёгкое под Raspberry Pi 2B** (armv7, 1 ГБ): без node/сборки, без тяжёлых БД |
+| 4 | Питание — на базе существующего модуля **`atxctl`** (I2C-expander HAT: PWRBTN/RESET/статус) |
+| 5 | Консоль — `ttyUSB0` (PL2303, RS232-TTL), поверх — **браузерный терминал + CLI + MCP** |
+| 6 | **Никаких реальных проверок питания на «живых» серверах** (продакшн). Только стенд/макет. `ATXPI_DRIVER=mock` для разработки |
+| 7 | Доступ: локально через **SSH (key-only)**; удалённо — через VPN/Tailscale. Управляющая плоскость не светится в интернет |
+| 8 | **Временные файлы — только в `atxpi/tmp/`** (НЕ в `/tmp` корня ФС), чтобы агент не запрашивал разрешений на системные пути |
+| 9 | **Распространение: нативно** (система + systemd), **один сервис** `atxpi.service` = FastAPI (REST + WebSocket-консоль + MCP-HTTP + статика). **Без Docker** |
+| 10 | Установка — **one-shot `install.sh`** (`curl \| sudo bash`), идемпотентный; обновление — `deploy/update.sh` |
+| 11 | **MCP для агентов — HTTP-эндпоинт** на самом устройстве (`/mcp`), Hermes подключается по URL+`Bearer` |
+| 12 | Раскладка: `/opt/arm` (чекаут репо), `/opt/arm/atxpi/venv`, `/etc/atxpi/atxpi.env` (0600, генерится, не в git), сервис-юзер `atxpi` |
+
+## Структура репозитория
+
+```
+arm/
+├── AGENTS.md               # этот файл
+├── .gitignore
+├── atxctl/                 # питание: I2C HAT (существующий модуль)
+├── lcd/                    # статусный OLED 52pi (существующий)
+├── ups/                    # защита батареи, INA219 (существующий)
+└── atxpi/                  # НОВЫЙ управляющий слой
+    ├── core/               # hardware.py (абстракция+драйверы), mock.py, power.py, console.py
+    ├── cli/atxpi           # CLI: status/on/off/reset/cycle/console
+    ├── webui/              # (далее) FastAPI: REST + WebSocket-консоль + статика
+    ├── mcp/                # (далее) MCP-сервер (stdio) для агентов
+    ├── deploy/             # (далее) systemd-юниты + setup.sh
+    ├── tmp/                # временные файлы (в gitignore)
+    └── README.md
+```
+
+## Конвенции и инструменты
+
+- **CLI-вызов:** `cd atxpi && ATXPI_DRIVER=mock ./cli/atxpi status`
+- **Драйвер:** `ATXPI_DRIVER=real` (дефолт, железо) | `mock` (разработка). Реальный: питание = `atxctl/main.py`, консоль = `pyserial` на `SERIAL_PORT` (`/dev/ttyUSB0`, 115200).
+- **Mock-состояние питания** хранится в `atxpi/tmp/atxpi_mock_power.json` (не в `/tmp`).
+- **SSH-ключ:** `~/.ssh/id_ed25519` (в Gitea назван `Toros`), пользователь `eka`.
+- **Python:** stdlib для core/CLI; полный набор (`pyserial`, `fastapi`, `uvicorn`, `mcp`) — в `atxpi/requirements.txt`, ставится в venv на устройстве, **не на HP Omen**.
+- **Коммиты:** conventional (`feat:`, `fix:`, `chore:`), по чекпоинтам.
+
+## Важно (безопасность)
+
+- Живой сервер (продакшн) — **только чтение кода**, никаких команд питания.
+- Питание/сброс — деструктивны: логировать действие, требовать аутентификацию.
+- Управляющая плоскость биндится на VPN/loopback, `0.0.0.0` запрещён.
+- Никаких `rm`/записей в `/tmp` корня ФС и вне рабочего каталога.
+
+## Статус
+
+- ✅ Шаг ①: core + CLI + mock (работает на stdlib, проверено на mock)
+- ⬜ Шаг ②: консоль на `pyserial`
+- ⬜ Шаг ③: web-UI (FastAPI + REST + WS-консоль)
+- ⬜ Шаг ④: MCP-сервер для агентов
+- ⬜ Шаг ⑤: systemd + деплой на Pi 2B