vesti/AGENT.MD

# AGENT.MD — Правила проекта VESTI

## Правило №1: ВСЕ изменения — через OpenSpec
- **Перед каждым планируемым изменением — обязательно grill-with-docs** (интервью по дизайн-дереву: глоссарий в CONTEXT.md + ADR при необходимости). Только после достижения общего понимания с пользователем — создавать change.
- **Любое изменение проекта (багфикс, фича, рефакторинг, конфиг, деплой, docs) оформляется как отдельный change** в `/opt/vesti/openspec/changes/<change-name>/`.
- **НЕ начинать правки кода/файлов, пока change не создан и не провалидирован (`openspec validate` чисто).** Это обязательное требование (у VESTI нет бэкапа — OpenSpec фиксирует состояние и откат).
- **Сразу после правок — обновить STATUS.md/TODO.md и сделать бэкап** (см. «Бэкап» ниже).
- Формат change (как в образцах `tg-crawler-publisher-prototype`, `publisher-service`):
  - `.openspec.yaml` (schema: spec-driven, created: дата)
  - `proposal.md` — зачем (проблема пользователя)
  - `design.md` — как (дизайн, точные правки)
  - `tasks.md` — чеклист задач; отмечать `[x]` при выполнении
- CLI `openspec change new` НЕ существует → change создаётся вручную (mkdir + файлы по образцу).
- Проверка: `openspec validate <change-name>` — должно быть чисто.
- После подтверждения пользователем change архивируется.
- Не начинать правки кода, пока change не создан и не провалидирован.

## Стек и архитектура
- Новостной агрегатор: TG-краулер → классификатор (Ollama qwen3:8b-nothink) → веб-модерация → публикация в Telegram.
- Веб: :8400 — страницы /candidates (модерация), /crawlers (статус краулеров, запуск воркера), /sources (управление источниками: add/edit/toggle-pause/delete; источник истины — sources.yaml).
- `vesti-web` (FastAPI+Jinja2, :8400, systemd-юнит) --HTTP POST--> `publisher-service` (FastAPI, Docker-контейнер, :8410) --Bot API (SOCKS5 127.0.0.1:1080)--> Telegram @dedinit_vesti.
- БД: SQLite `/opt/vesti/db/vesti.db` — открывать с WAL + busy_timeout (иначе `database is locked` при фоновом классификаторе).
- Фронтенд: **без внешних CDN** (никаких unpkg/jsdelivr). Bootstrap локален: `web/static/bootstrap.min.css`, htmx запрещён. approve/reject — обычные POST-формы.
- Markdown в шаблонах — фильтр `| markdown` (XSS-safe: escape → nl2br → sane_lists). Сырой вывод текста запрещён.
- Даты в UI — фильтр `| dt` → `ЧЧ:ММ ДД.ММ.ГГГГ` (не ISO `[:16]`).
- Пути бандлов: в БД `published.bundle_path` хранится **относительный** путь от `bundles/` (напр. `linux/2026-09/slug.md`), ссылка в UI `/bundle/<rel>`. Абсолютные пути запрещены (баг двойного слэша — исправлен).

## Секреты и .env
- `.env` в корне (chmod 600). Переменные: `ADMIN_USER`, `ADMIN_PASSWORD` (веб-логин), `VESTI_BOT_TOKEN`, `VESTI_BOT_CHANNELS`, `TG_PROXY`, `PUBLISHER_URL`, api_id/api_hash.
- Значения секретов НЕ показывать, НЕ сохранять, НЕ коммитить (пишется только имя переменной).
- `.env.example` — всегда актуализировать при добавлении переменной.

## Правила работы
- **Не удалять пользовательские файлы.** Перезапись/перемещение — только после явного подтверждения пользователя.
- Дедуп постов: sha256(text) + url. Физически ничего не удаляем — только смена `status`.
- Общение с пользователем — на русском, кратко (статусы), без «всё ок».
- Все ресурсы проекта — в `/opt/vesti` (ничего в домашней директории).
- Документация проекта: STATUS.md (живой), PRD.md, TODO.md, WALKTHROUGH.md — поддерживать актуальными; при закрытии сессии обновлять.
- Ссылки и доступы к ресурсам (URL/SSH/пути) фиксировать в файлах проекта.

## Запуск / проверка
```bash
cd /opt/vesti
sudo systemctl restart vesti-web          # веб :8400 (0.0.0.0, uvicorn web.app:app)
docker compose -f services/publisher/docker-compose.yml up -d --build   # publisher :8410
curl -s http://127.0.0.1:8410/healthz     # ok, bot=dedinit_controller_bot, proxy, channels
.venv/bin/python -m crawler.telegram_crawler --all   # краулер (инкрементально)
.venv/bin/python -m crawler.rss_crawler --all         # RSS/Atom-краулер (условные GET, etag/modified; rss_state)
.venv/bin/python -m crawler.rss_crawler --source lwn --dry-run   # сухой прогон без записи в БД
.venv/bin/python -m crawler.crawl_sources --all       # фаза 1: сбор кандидатов в очередь (telegram+rss)
.venv/bin/python -m crawler.worker --workers 8 --limit 200   # фаза 3: параллельная обработка очереди (ThreadPoolExecutor)
MAX_CONCURRENT_LLM=2 .venv/bin/python -m crawler.worker --workers 8   # лимит одновременных LLM-запросов к Ollama
CLASSIFY_TIMEOUT=20 .venv/bin/python -m classifier.classify --db db/vesti.db --limit 200
openspec validate <change-name>           # валидация change
```
- Внешний доступ: https://vesti.nixg.ru (Caddy на VPS02: /opt/caddy/Caddyfile, reverse_proxy 10.8.0.2:8400).

## Направления (directions)
linux, tech, politics, games, electronics, llm. Свой канал @dedinit — источник `own: true`, посты is_own=1, fan-out по направлениям с атрибуцией «Дед в АйТи».

## Бэкап (автоматический, вручную НЕ запускать)
- Скрипт: `/opt/vesti/backup.sh` (по образцу `/opt/icq/backup.sh`): архивирует проект → `/opt/vesti/backups/vesti_<дата>.tar.gz`, копирует на Яндекс.Диск `/mnt/yandex-disk/backup/vesti-backups/`.
- Хранение: локально 7 дней, на ЯД 30 дней (ротация в скрипте).
- Запуск: root cron `45 2 * * *` (как у icq). ЯД монтируется автоматически (fstab davfs + @reboot).
- Бэкапы запускаются автоматически по крону — вручную НЕ запускать.