mnemo_cards/ai_docs/AGENT_SYSTEM_SUMMARY.md

AI Agent 24/7 Automation System - Summary

Что создано

Полноценная система автоматизированной разработки с использованием AI агентов для Forgejo.

Архитектура

┌─────────────────────────────────────────┐
│      Forgejo Actions (Workflows)        │
├─────────────────────────────────────────┤
│                                         │
│  Planning Agent → Development Agent     │
│        ↓               ↓                │
│    Task List    →   Code Changes        │
│                        ↓                │
│                  Test & Deploy          │
│                                         │
└─────────────────────────────────────────┘
         ↓
    Cursor CLI (AI Provider)
         ↓
    Claude Sonnet 4.5

Созданные файлы

📁 Workflows (3 файла)

1. .github/workflows/agent-planning.yml

   • Запускается вручную (workflow_dispatch)
   • Анализирует проект
   • Создает task_list.json
   • Создает issue с summary
   • Триггерит development workflow

2. .github/workflows/agent-development.yml

   • Читает задачи из task_list.json
   • Использует Cursor CLI для написания кода
   • Запускает тесты
   • Делает коммиты
   • Цикл до завершения всех задач (макс 10 итераций, 6 часов)

3. .github/workflows/agent-test-deploy.yml

   • Триггерится автоматически после push
   • Определяет измененные компоненты
   • Запускает analyze + tests для каждого
   • Готовит к деплою если тесты прошли
   • Создает issue если тесты не прошли

🐍 Python Scripts (5 файлов)

1. tools/agent/config.py (124 строки)

   • Конфигурация для каждого компонента
   • Пути к файлам состояния
   • Команды для тестов/линтера/сборки

2. tools/agent/task_manager.py (334 строки)

   • Класс Task - представление задачи
   • Класс AgentState - состояние агента
   • Класс TaskManager - работа с задачами и состоянием
   • Класс GlobalLock - глобальная блокировка для shared resources

3. tools/agent/cursor_cli_wrapper.py (300 строк)

   • Wrapper для Cursor CLI
   • Парсинг stream-json output
   • Отслеживание прогресса (tool calls, files modified)
   • Обработка ошибок

4. tools/agent/agent_orchestrator.py (423 строки)

   • Главный оркестратор development цикла
   • Чтение задач
   • Выполнение через Cursor CLI
   • Запуск тестов
   • Создание коммитов
   • Обработка ретраев

5. tools/agent/planning_agent.py (334 строки)

   • Planning агент
   • Анализ текущего состояния проекта
   • Генерация task_list.json через Cursor CLI
   • Валидация JSON
   • Коммит task list

📝 Prompts (2 файла)

1. ai_docs/agent/prompts/development_prompt.md (~400 строк)

   • Инструкции для development агента
   • Code standards (Clean Architecture, yx_state)
   • Примеры кода
   • Testing guidelines
   • DO/DON'T список

2. ai_docs/agent/prompts/planning_prompt.md (~300 строк)

   • Инструкции для planning агента
   • Формат task list
   • Priority guidelines
   • Acceptance criteria examples
   • Task ordering strategy

📊 State Files (7 файлов)

1. ai_docs/agent/web_v2/task_list.json - задачи для web_v2
2. ai_docs/agent/web_v2/agent_state.json - состояние агента web_v2
3. ai_docs/agent/backend/task_list.json - задачи для backend
4. ai_docs/agent/backend/agent_state.json - состояние агента backend
5. ai_docs/agent/common/task_list.json - задачи для common
6. ai_docs/agent/common/agent_state.json - состояние агента common
7. ai_docs/agent/global_lock.json - глобальная блокировка

📚 Documentation (4 файла)

1. ai_docs/agent/README.md (~600 строк)

   • Полная документация системы
   • Архитектура
   • Как работают агенты
   • Multi-agent support
   • Мониторинг и отладка
   • Best practices
   • Примеры использования

2. ai_docs/agent/CONFIGURATION.md (~500 строк)

   • Детальная конфигурация для Forgejo
   • Настройка Forgejo Runner
   • Настройка secrets
   • Cursor CLI setup
   • Troubleshooting
   • Мониторинг
   • Security best practices

3. ai_docs/agent/FORGEJO_SETUP.md (~400 строк)

   • Пошаговая инструкция на 15-30 минут
   • Настройка Forgejo Actions
   • Установка runner
   • Создание secrets
   • Первый запуск
   • Checklist проверки

4. ai_docs/agent/QUICKSTART.md (~200 строк)

   • Быстрый старт за 5 минут
   • Основные команды
   • Структура проекта
   • Troubleshooting
   • Советы

Ключевые особенности

✅ Multi-Agent Support

• Параллельная работа нескольких агентов
• Каждый агент работает над своим компонентом (web_v2, backend, common)
• Per-component locking
• Global lock для shared resources (mnemo_cards_common)

✅ Cursor CLI Integration

• Использует Cursor CLI вместо прямых API вызовов
• Автоматическая оптимизация контекста
• Уважает .cursorrules
• Stream-json для отслеживания прогресса

✅ Forgejo Native

• Полностью адаптировано под Forgejo
• Используется Forgejo API для issues и workflow triggers
• Работает с Forgejo Runner
• Без зависимостей от GitHub

✅ Safety & Limits

• Максимум 10 итераций за запуск
• Timeout 6 часов
• Максимум 3 ретрая для задачи
• Автоматический git pull перед коммитом
• Stale lock detection (2 часа)

✅ Autonomous Operation

• Агенты работают полностью автономно
• Не требуют вмешательства человека
• Автоматический retry при ошибках
• Создание issues при критических ошибках

Workflow процесс

Planning Agent

1. Trigger: Вручную через UI или API
2. Input: tasks.md, workflow_state.md, agent_state.json
3. Process:
   • Cursor CLI анализирует проект
   • Генерирует task_list.json
4. Output:
   • Обновленный task_list.json
   • GitHub issue с summary
   • Триггер development workflow

Development Agent

1. Trigger: Автоматически после planning или вручную
2. Input: task_list.json
3. Process:
   • Цикл по задачам (по приоритету)
   • Для каждой задачи:
     • Cursor CLI пишет код
     • Запускаются тесты
     • При успехе: коммит + next task
     • При ошибке: retry до 3 раз
4. Output:
   • Git commits с изменениями
   • Обновленный agent_state.json
   • Issues для failed tasks

Test & Deploy

1. Trigger: Автоматически после push
2. Input: Git diff
3. Process:
   • Определить измененные компоненты
   • Для каждого: analyze + test
4. Output:
   • Test reports
   • Deployment (если тесты прошли)
   • Issues (если тесты не прошли)

Требования

Обязательные

• Forgejo: 1.20+ с Actions
• Forgejo Runner: установлен и запущен
• Cursor: активная подписка + API key
• Python: 3.8+
• Flutter: 3.24.0+ (для web_v2)
• Dart: 3.0+ (для backend/common)

Secrets

• CURSOR_API_KEY - API ключ от Cursor
• FORGEJO_TOKEN - Personal Access Token для Forgejo

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

1. Установите Runner

wget https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64
sudo mv forgejo-runner-3.3.0-linux-amd64 /usr/local/bin/forgejo-runner
sudo chmod +x /usr/local/bin/forgejo-runner
sudo forgejo-runner register --instance https://your-forgejo.com --token TOKEN
sudo forgejo-runner daemon

2. Добавьте Secrets

Repository -> Settings -> Secrets and Variables -> Actions

• CURSOR_API_KEY
• FORGEJO_TOKEN

3. Запустите Planning

Actions -> AI Agent - Planning -> Run workflow -> web_v2

Готово! Агент начнет работу.

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

• Быстрый старт: QUICKSTART.md
• Полная настройка: FORGEJO_SETUP.md
• Конфигурация: CONFIGURATION.md
• Документация: README.md

Статистика

• Всего файлов: 21
• Python код: ~1500 строк
• Workflows: ~500 строк
• Prompts: ~700 строк
• Documentation: ~1700 строк
• Общий объем: ~4400 строк кода и документации

Возможности расширения

В будущем можно добавить:

• Telegram уведомления о прогрессе
• Dashboard для мониторинга
• Автоматические расписания (cron triggers)
• Metrics и аналитика (сколько задач выполнено, время и т.д.)
• Интеграция с CI/CD для автодеплоя
• A/B тестирование разных AI моделей
• Система приоритетов на основе бизнес-метрик
• Автоматический rollback при критических ошибках

Лицензия

Использует:

• Cursor CLI: Коммерческая лицензия Cursor
• Forgejo: MIT License
• Остальной код: Собственная разработка для проекта mnemo_cards

---

Создано: 2025-11-20
Версия: 1.0
Powered by: Cursor CLI + Claude Sonnet 4.5 + Forgejo Actions