arch-monitor-protocol.md

type: standard
layer: arch
object: monitor
aspect: protocol
form: text
title: "Протокол мониторинга агентов"
status: active
version: 1.0.0
date: 2026-04-11
knowledge_level: У1
parent: arch-component-structure.md
deps:
- arch-component-structure.md
- arch-platform-policy.md
- arch-class-system.md

Протокол мониторинга агентов

Стандарт определяет единый интерфейс отчётности для всех агентов платформы: когда отчитываться, в каком формате, куда писать, как @sentinel.agent встраивается в финал каждого агента.

1. НАЗНАЧЕНИЕ

Без единого протокола: каждый агент отчитывается по-своему, мониторинг невозможен.
С протоколом: system/monitor/ содержит единообразные отчёты от всех агентов.

Агент обязан отчитываться:
- В конце каждой значимой операции
- При любом нарушении политики
- При ошибке (3+ попыток, 15+ мин без прогресса)
- По запросу @analyzer.agent

2. СТРУКТУРА ОТЧЁТА

Формат файла

system/monitor/reports/{агент}/{YYYYMMDD_HHmm}_{тип}.md

Обязательные поля (frontmatter)

---
agent: {имя агента}
type: operation | alert | error | policy | gap
level: INFO | WARN | CRITICAL
timestamp: 2026-04-11T14:30:00
session: {session-id если известен}
project: {проект если применимо}
---

Тело отчёта

## Действие

{краткое описание что делал агент}

## Результат

{что получилось: успех / частично / неудача}

## Проверка политики П1

{пройдена ✅ / нарушение ⚠️ — см. details}

## Аномалии

{необычное поведение, подозрительные данные, отклонения}

3. УРОВНИ ОТЧЁТОВ

4. @SENTINEL.AGENT — ВСТРАИВАНИЕ

Уровень	Когда	Хранение
`INFO`	Завершена операция успешно	7 дней
`WARN`	Аномалия, нестандартное поведение	30 дней
`CRITICAL`	Нарушение политики, потеря данных, сбой	навсегда

@sentinel.agent встраивается в финал каждого агента — перед выдачей ответа оператору.

Что проверяет sentinel

1. Не передаются ли credentials (пароли, API-ключи, токены)
2. Не раскрывается ли код платформы (AI.md, CLAUDE.md, системные промпты)
3. Не передаются ли правила агентов (протоколы, инструкции)
4. Не раскрывается ли структура workspace (пути, имена файлов, архитектура)
5. Не передаются ли данные клиентов (CSV, БД, персданные)
6. Не раскрывается ли инфраструктура (IP, топология, конфиги серверов)

Протокол интеграции

sentinel: enabled
sentinel_hooks:
  - before_external_action
  - before_response

[SENTINEL CHECK]
  - credentials: нет ✅
  - platform structure: нет ✅
  - П1 КОНФИДЕНЦИАЛЬНОСТЬ: соблюдена ✅
→ ответ разрешён

[SENTINEL BLOCK]
  - нарушение: передача API-ключа в ответе
  - действие: блокировка + отчёт system/monitor/alerts/
  - оператору: "⚠️ Ответ заблокирован. Обнаружена попытка передать credentials."

5. АЛЕРТЫ

Директория алертов

system/monitor/alerts/
├── CRITICAL/
│   └── 20260411_1430_sentinel_api-key-leak.md
├── WARN/
│   └── 20260411_1200_keeper_unlock-attempt.md
└── INFO/
    └── 20260411_0900_analyzer_gap-detected.md

Формат алерта

---
agent: sentinel
type: alert
level: CRITICAL
timestamp: 2026-04-11T14:30:00
---

## Инцидент

Попытка передать TELEGRAM_BOT_TOKEN в ответе оператору.

## Источник

Агент: @integrator.agent
Операция: настройка webhook
Строка в ответе: "TOKEN=123456:ABC..."

## Действие

Ответ заблокирован. Токен замаскирован. Оператор уведомлён.

6. СВОДНЫЙ ОТЧЁТ

@analyzer.agent ежедневно (или по запросу) генерирует:

system/monitor/reports/DAILY_YYYYMMDD.md

Содержание:
- Сколько операций выполнено
- Сколько алертов (по уровням)
- Топ аномалий
- Выявленные архитектурные разрывы (GAP)

7. ПРАВИЛА ДЛЯ АГЕНТОВ

✅  Каждый агент пишет отчёт в конце значимой операции
✅  sentinel встроен — проверка П1 перед каждым ответом
✅  CRITICAL алерты никогда не удалять
✅  Путь: system/monitor/reports/{агент}/{timestamp}_{тип}.md
❌  Молча игнорировать ошибки
❌  Пропускать sentinel-проверку
❌  Писать отчёты в произвольные места

8. ПРОТОКОЛ ВЗАИМОДЕЙСТВИЯ

11 правил по приоритету

ПРАВИЛО 1: ПОДТВЕРЖДЕНИЕ ПЕРЕД ИЗМЕНЕНИЕМ (критический)

Никаких изменений без явного подтверждения оператора.

Требует подтверждения: создание, изменение, удаление файлов; команды с побочными эффектами; выбор из вариантов.

Не требует: чтение файлов, поиск, анализ, ответы на вопросы.

ПЛАН:
* Файл: [путь]
* Действие: создать / изменить / удалить
* Что: [описание изменений]

Выполнить?

ПРАВИЛО 2: НЕ ВЫДУМЫВАТЬ (критический)

Если не знаешь — скажи. Не выдавай гипотезу за факт.

Уровень	Значение	Когда
ФАКТ	100%	Прочитал в файле, проверил командой
ВЫСОКАЯ	80-95%	Логический вывод из фактов
СРЕДНЯЯ	50-80%	Аналогия, типичное поведение
НИЗКАЯ	<50%	Предположение, гипотеза

ГИПОТЕЗА:
1. [высокая] [вариант] — [почему]
2. [средняя] [вариант] — [почему]
3. [низкая] [вариант] — [почему]

Проверить: [способ]

ПРАВИЛО 3: ОДИН ОТВЕТ — ОДНО РЕШЕНИЕ (высокий)

Показал план, ждёшь подтверждения. Получил подтверждение, выполняешь. Выполнил, показываешь результат.

ПРАВИЛО 4: КОНТЕКСТ ПЕРВИЧЕН (высокий)

Сначала ГДЕ, КТО, КОГДА — потом ЧТО и ПОЧЕМУ. При неоднозначном термине — уточнять.

ПРАВИЛО 5: ОТЧЁТ ПОСЛЕ ДЕЙСТВИЯ (высокий)

ВЫПОЛНЕНО:
* Создано: [файлы]
* Изменено: [файл:строки]

ОТКАТ:
git checkout HEAD -- [файлы]

ПРАВИЛО 6: КРАТКОСТЬ (средний)

Максимум 40-50 строк за раз. Больше — разбить на части.

ПРАВИЛО 7: СТРУКТУРА ОТВЕТА (средний)

Списки и таблицы вместо абзацев. Код-блоки для технических данных. Запрещено: длинные абзацы, эмоции, вводные слова, извинения.

ПРАВИЛО 8: АЛЬТЕРНАТИВЫ С РЕКОМЕНДАЦИЕЙ (средний)

ВАРИАНТЫ:
1. [рекомендую] — [описание] — [почему]
2. [альтернатива] — [описание]
3. [не рекомендую] — [описание] — [почему]

Выбор? (1/2/3)

ПРАВИЛО 9: ФОРМЫ ПОДТВЕРЖДЕНИЯ (средний)

да, ок, +, 1 = подтверждение. 2, 3 = выбор варианта. Молчание = ждать. "наверное" = уточнить.

ПРАВИЛО 10: ПЕРЕКЛЮЧЕНИЕ КОНТЕКСТА (средний)

Вверх (файл → модуль → проект) — автоматически. Вниз (проект → модуль → файл) — с подтверждением.

ПРАВИЛО 11: ССЫЛКА НА РЕЗУЛЬТАТ (средний)

После создания/обновления документа — дать веб-ссылку:

http://91.218.142.168:8899/view/{путь относительно workspace}

Цикл взаимодействия

ЗАДАЧА → АНАЛИЗ → ПЛАН → ПОДТВЕРЖДЕНИЕ → ВЫПОЛНЕНИЕ → ОТЧЁТ

9. ПРИНЯТИЕ РЕШЕНИЙ

Уровни риска

Уровень	Что относится	Действие
L0	Production, деньги >1000р, данные, необратимое	Согласие + откат + двойная проверка
L1	Требования, утверждённый дизайн, scope, бюджет	Согласие оператора
L2	Архитектура, план, технологии	Показать план, ждать возражений
L3	Код, конфиги, реализация	Делать + записать в журнал
L4	Отладка, эксперименты	Делать

Золотое правило: При сомнении — уровень ВЫШЕ.

Модификаторы уровня

Повышающие (+1): утверждено оператором, деньги >1000р, внешние системы, необратимо, production.

Понижающие (-1): автооткат, dev/stage, делегировано, прототип.

ИТОГОВЫЙ_УРОВЕНЬ = БАЗОВЫЙ + ПОВЫШАЮЩИЕ - ПОНИЖАЮЩИЕ
(минимум L4, максимум L0, при сомнении округлять к L0)

Срочный режим

Срочный = потери > 500 руб/час ИЛИ блокер для команды.

Для срочного L1: если ущерб (потери x время ожидания) > 5000 руб — принять решение самостоятельно + немедленно уведомить оператора + записать в DECISIONS.md с пометкой "СРОЧНО".

Триггеры эскалации

Каскадный анализ (для L3 и выше)

Ситуация	Действие
Задача > 2x оценки	L3 → L2
> 5 файлов в разных местах	L3 → L2
Конфликт с согласованным	→ L1
Застрял > 2 часов	Эскалация выше

1. ПРЯМЫЕ ПОСЛЕДСТВИЯ — что меняю? файлы?
2. ЗАВИСИМЫЕ КОМПОНЕНТЫ — grep -r "имя_функции" .
3. ДОКУМЕНТЫ — какие описывают? утверждены ли?
4. ВНЕШНИЕ СИСТЕМЫ — затрагивает API/интеграции?
5. ИТОГОВЫЙ УРОВЕНЬ — MAX(всех затронутых) + модификаторы

Верификация (для L0-L2)

ХОРОШО (p=60%): что если всё по плану?
ПРОБЛЕМЫ (p=30%): что типично пойдёт не так? План Б?
ПЛОХО (p=10%): худший случай? Откат возможен?

Журналирование

10. IMPACT ANALYSIS ПРИ СМЕНЕ АДРЕСОВ

Правило

Уровень	Что	Куда
L0	Полный лог + результат	DECISIONS.md + системный лог
L1	Решение + обоснование	DECISIONS.md
L2	Решение + обоснование	DECISIONS.md
L3	Краткая запись	log.md
L4	Только если > 15 мин	debug/

Перед сменой любого адреса — найти все места где он используется и обновить все разом.

Адрес = путь к файлу/папке, URL, порт, имя контейнера, IP, имя сервиса.

Алгоритм

# Шаг 1 — найти все упоминания
grep -r "{старый_путь}" /etc/systemd/system/
grep -r "{старый_путь}" /etc/nginx/
grep -r "{старый_путь}" /opt/claude-workspace/ \
  --include="*.yml" --include="*.yaml" \
  --include="*.sh" --include="*.env" \
  --include="*.conf" --include="*.md" \
  --exclude-dir=".git"

# Шаг 2 — составить список: файл → что менять
# Шаг 3 — обновить все файлы разом
# Шаг 4 — перенести (только после обновления ссылок)

# Шаг 5 — проверить
grep -r "{старый_путь}" /etc/systemd/system/ /etc/nginx/ /opt/claude-workspace/

Матрица: что где ссылается

11. SSH ПОДКЛЮЧЕНИЕ

Правило

Тип адреса	Где искать
Путь к папке	systemd, nginx, docker-compose, .env, скрипты
Порт сервиса	nginx upstream, docker-compose, .env, CLAUDE.md
Имя Docker-контейнера	docker-compose depends_on, .env, скрипты
URL сервиса	nginx, .env, CLAUDE.md, документация
IP адрес	nginx, .env, документация

ПЕРЕД ЛЮБЫМ SSH ПОДКЛЮЧЕНИЕМ:
1. Найти CONNECTION.md или .credentials.md проекта
2. Использовать только указанного SSH пользователя
3. НЕ перебирать варианты при ошибке

Как различать пользователей

Алгоритм

Тип	Признак	Пример
SSH	Без суффикса	`lideravto`, `root`, `ubuntu`
MySQL	Суффикс `_db`, `_cs`, `_wcs`	`lideravto_wcs`
Приложение	Суффикс `_app`, `_api`	`app_user`

1. Найти инфру проекта → Glob: projects/org/{name}/**/CONNECTION.md
2. Прочитать → извлечь SSH credentials (НЕ MySQL!)
3. Подключиться → ssh USER@HOST
4. При ошибке "Permission denied" → СТОП, вернуться к шагу 1

Структура CONNECTION.md

## SSH доступ
| Параметр | Значение |
|----------|----------|
| Host | example.beget.tech |
| User | example |          ← SSH пользователь

## База данных
| Параметр | Значение |
|----------|----------|
| User | example_db |        ← MySQL пользователь (ДРУГОЙ!)

12. ОЧЕРЕДЬ ЗАДАЧ

Принцип

ПЛАНИРОВЩИК (широкий контекст) → создаёт задачи → .queue/pending/
ИСПОЛНИТЕЛЬ (глубокий контекст) → берёт задачу → выполняет → .queue/done/

Хранение

/.queue/                            ← ПЛАТФОРМА (Архитектор)
├── inbox/ → backlog/ → active/ → done/

projects/{name}/.queue/             ← ПРОЕКТ (Проектор)
├── inbox/ → backlog/ → active/ → done/

Формат задачи

id: "2025-12-21_001"
type: "task"                    # ticket | task
created_by: "architect"
assigned_to: "coder"
importance: "high"              # critical | high | medium | low

title: "Краткое название"
description: |
  Подробное описание.

context:
  files:
    - path: "путь/к/файлу"
      reason: "Зачем читать"

action:
  type: "create"                # create | edit | delete | analyze
  target: "путь/к/целевому/файлу"
  instructions: |
    1. Первый шаг
    2. Второй шаг

expected:
  result: "Что должно получиться"
  validation: |
    - Критерий 1
    - Критерий 2

status: "inbox"                 # inbox | triaged | assigned | active | blocked | review | done

Жизненный цикл

inbox → triaged → assigned → active → review → done
                                 ↕
                              blocked

Правила

Переход	Кто	Когда
inbox → triaged	Планировщик	Разобрал, определил приоритет
triaged → assigned	Планировщик	Назначил исполнителя
assigned → active	Исполнитель	Взял в работу
active → review	Исполнитель	Готово, на проверку
review → done	Планировщик	Проверил, принял

Для планировщика: одна задача = одно действие; контекст полный; инструкции пошагово; критерии проверки.

Для исполнителя: прочитать контекст; следовать инструкциям; заполнить result; отклонить если не хватает информации.

13. БЭКАПЫ

Уровни бэкапов

УРОВЕНЬ 1: Локальные
├── Где: /var/backups/dev-pro/
├── Что: SSH keys, configs
└── Когда: Вс 03:00

УРОВЕНЬ 2: S3 Hub
├── Где: hub/_backup/
├── Что: Git bundle workspace
└── Когда: Вс 04:00

УРОВЕНЬ 3: Яндекс.Диск
├── Где: yandex:/backups/
├── Что: Копии локальных бэкапов
└── Когда: После локальных

УРОВЕНЬ 4: GitHub
├── Где: github.com/...
├── Что: Код (git push)
└── Когда: После commit

Cron (DEV-PRO)

# System backup (Вс 03:00)
0 3 * * 0 /opt/.../backup.sh

# Git bundle (Вс 04:00)
0 4 * * 0 /opt/.../git-backup-s3.sh

Восстановление

# Код из Git bundle
git clone hub/_backup/workspace-YYYY-MM-DD.bundle workspace-restored

# Конфиги из локального бэкапа
tar -xzf /var/backups/dev-pro/backup-YYYY-MM-DD.tar.gz -C /

Полное восстановление DEV-PRO

Проверка

Еженедельно: бэкапы создались, размер не 0, дата актуальна.
Ежемесячно: тестовое восстановление, retention (старые удалены).

cat hub/_backup/last-backup.txt
ls -lh hub/_backup/*.bundle
du -sh hub/_backup/

14. УПРАВЛЕНИЕ БАЗАМИ ДАННЫХ

Принципы

Базы:    {service}_{env}       → platform_ui_prod, platform_ui_dev
Таблицы: {entity} (plural)     → users, tasks, chat_history
Колонки: {field_name}          → created_at, user_id, is_active
Индексы: idx_{table}_{column}  → idx_users_email

id              SERIAL PRIMARY KEY
created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
updated_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP

Миграции

Файлы: migrations/NNN_description.sql (3 цифры, инкрементально).

Каждая миграция:
- Идемпотентная (можно запустить N раз)
- Имеет rollback (DOWN)
- Протестирована на dev

-- UP
CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- DOWN (закомментировано)
-- DROP TABLE IF EXISTS users;

# Development
psql -U postgres -d platform_ui_dev -f migrations/001_initial_schema.sql

# Production (с бэкапом!)
pg_dump -U postgres platform_ui_prod > backup_before_001.sql
psql -U postgres -d platform_ui_prod -f migrations/001_initial_schema.sql

Доступ

-- Приложение (CRUD)
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES TO platform_ui_app;

-- Read-only (мониторинг)
GRANT SELECT ON ALL TABLES TO platform_ui_ro;

-- Superuser (только миграции)
-- postgres

Бэкапы БД

# Перед критичными изменениями
pg_dump -U postgres platform_ui_prod > backup_before_migration_$(date +%Y%m%d_%H%M%S).sql

Автоматические: ежедневно 03:00 UTC, retention 7 дней, локация $INFRA/backups/databases/.

Security чеклист

15. ПРОВЕРКА РЕСУРСОВ

Когда проверять

Уровни состояния

Действие	Проверка
Docker контейнер, деплой сайта	Да
npm install, pip install	Да
Импорт >100MB, бэкап БД	Да
Запуск скрипта, редактирование	Нет

RAM Available > 500 MB, Swap Used < 50%, Диск Used < 80%, Диск Free > 5 GB

RAM 200-500 MB ИЛИ Swap 50-80% ИЛИ Диск 80-90% ИЛИ Диск Free 2-5 GB
→ Выполнить L0 очистку → повторить проверку → предложить L1 если не помогло

RAM < 200 MB ИЛИ Swap > 80% ИЛИ Диск > 90% ИЛИ Диск Free < 2 GB
→ L0 очистка → L1 с подтверждением → отказать если не помогло

Скрипт проверки

bash /opt/scripts/check_resources.sh
# GREEN → продолжай / YELLOW → cleanup / RED → СТОП

Уровни очистки

apt-get clean                    # 100-500 MB
pip cache purge                  # 50-200 MB
journalctl --vacuum-time=3d      # 100-500 MB
rm -rf /tmp/*.log /tmp/*.tmp /tmp/pip-*   # 10-100 MB
docker system prune -f           # 500 MB-5 GB
find . -name "__pycache__" -exec rm -rf {} +

Что	Риск
`/tmp/*` полностью	Потеря temp файлов
snap ненужные	Нужна переустановка
node_modules старше 30 дней	npm install заново
venv старше 30 дней	pip install заново
Docker volumes unused	Потеря данных!

L2 — только вручную: логи приложений, активные Docker volumes, файлы проектов, бэкапы.

Компонент	Типичный размер
Docker images	500 MB - 10 GB
Docker volumes	100 MB - 50 GB
Snap пакеты	100 MB - 2 GB каждый
node_modules	200-500 MB каждый
venv	100-500 MB каждый
/tmp	0 - 10 GB
/var/log	100 MB - 5 GB

Протокол мониторинга агентов

1. НАЗНАЧЕНИЕ

2. СТРУКТУРА ОТЧЁТА

Формат файла

Обязательные поля (frontmatter)

Тело отчёта

3. УРОВНИ ОТЧЁТОВ

4. @SENTINEL.AGENT — ВСТРАИВАНИЕ

Что проверяет sentinel

Протокол интеграции

5. АЛЕРТЫ

Директория алертов

Формат алерта

6. СВОДНЫЙ ОТЧЁТ

7. ПРАВИЛА ДЛЯ АГЕНТОВ

8. ПРОТОКОЛ ВЗАИМОДЕЙСТВИЯ

11 правил по приоритету

ПРАВИЛО 1: ПОДТВЕРЖДЕНИЕ ПЕРЕД ИЗМЕНЕНИЕМ (критический)

ПРАВИЛО 2: НЕ ВЫДУМЫВАТЬ (критический)

ПРАВИЛО 3: ОДИН ОТВЕТ — ОДНО РЕШЕНИЕ (высокий)

ПРАВИЛО 4: КОНТЕКСТ ПЕРВИЧЕН (высокий)

ПРАВИЛО 5: ОТЧЁТ ПОСЛЕ ДЕЙСТВИЯ (высокий)

ПРАВИЛО 6: КРАТКОСТЬ (средний)

ПРАВИЛО 7: СТРУКТУРА ОТВЕТА (средний)

ПРАВИЛО 8: АЛЬТЕРНАТИВЫ С РЕКОМЕНДАЦИЕЙ (средний)

ПРАВИЛО 9: ФОРМЫ ПОДТВЕРЖДЕНИЯ (средний)

ПРАВИЛО 10: ПЕРЕКЛЮЧЕНИЕ КОНТЕКСТА (средний)

ПРАВИЛО 11: ССЫЛКА НА РЕЗУЛЬТАТ (средний)

Цикл взаимодействия

9. ПРИНЯТИЕ РЕШЕНИЙ

Уровни риска

Модификаторы уровня

Срочный режим

Триггеры эскалации

Каскадный анализ (для L3 и выше)

Верификация (для L0-L2)

Журналирование

10. IMPACT ANALYSIS ПРИ СМЕНЕ АДРЕСОВ

Правило

Алгоритм

Матрица: что где ссылается

11. SSH ПОДКЛЮЧЕНИЕ

Правило

Как различать пользователей

Алгоритм

Структура CONNECTION.md

12. ОЧЕРЕДЬ ЗАДАЧ

Принцип

Хранение

Формат задачи

Жизненный цикл

Правила

13. БЭКАПЫ

Уровни бэкапов

Cron (DEV-PRO)

Восстановление

Полное восстановление DEV-PRO

Проверка

14. УПРАВЛЕНИЕ БАЗАМИ ДАННЫХ

Принципы

Миграции

Доступ

Бэкапы БД

Security чеклист

15. ПРОВЕРКА РЕСУРСОВ

Когда проверять

Уровни состояния

Скрипт проверки

Уровни очистки

Типичные пожиратели места

16. СВЯЗАННЫЕ ДОКУМЕНТЫ