┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│  Hermes     │────▶│  md2vk      │────▶│  VK API      │
│  Agent      │     │  :8420      │     │  wall.post   │
│  (skill)    │◀────│  FastAPI    │     │  vk.com      │
└─────────────┘     └─────────────┘     └──────────────┘

Прод: https://md2vk.nixg.ru (basic auth — см. docs/security.md; Swagger /docs).

Документация

Вся документация — в docs/:

docs/index.md — указатель, обзор
docs/access.md — реквизиты и доступы (vps02, Caddy, gitverse, gitea, DNS, VK API)
docs/architecture.md — архитектура, порты, схема
docs/vk-api.md — порядок взаимодействия с VK API (OAuth, wall.post, лонгриды)
docs/security.md — безопасность (basic auth, fail2ban, Fernet, API-ключ)
docs/deploy.md — деплой (docker, Caddy, fail2ban)
docs/status.md — статус/история

Инструкции для агентов (Hermes и др.): AGENTS.md.

Возможности

Публикация Markdown на стене VK с сохранением форматирования
Конвертация Markdown → VK format_data (JSON) без публикации
Управление VK-аккаунтами — несколько страниц через один сервис
Отложенные посты — запись scheduled (планировщик — открытая задача)
Архив публикаций с фильтрацией по статусу
Аудит-лог запросов API (JSONL, ротация по дням)

API

Метод	Путь	Описание
`GET`	`/api/v1/health`	Проверка работоспособности
`GET`	`/api/v1/accounts`	Список VK-аккаунтов
`POST`	`/api/v1/accounts`	Добавить VK-аккаунт
`DELETE`	`/api/v1/accounts/{id}`	Удалить VK-аккаунт
`POST`	`/api/v1/publish`	Опубликовать пост на стене
`POST`	`/api/v1/convert`	Конвертировать Markdown (без публикации)
`POST`	`/api/v1/publications`	Архив публикаций

Swagger UI: http://127.0.0.1:8420/docs (прод — за basic auth).

Быстрый старт

cd /opt/md2vk
make docker-up        # docker compose up -d --build
curl -s http://127.0.0.1:8420/api/v1/health   # {"status":"ok"}

Детали деплоя и проверки — docs/deploy.md.

Технологии

Python 3.12+, FastAPI, SQLAlchemy 2.0 (async), SQLite (aiosqlite), httpx, cryptography (Fernet), Docker, Caddy, fail2ban.